Wikipedia:Lua/Modul/URLutil

Vorlagen- programmierung	Diskussionen	Lua						Test	Unterseiten
		Modul	Deutsch	English	Esperanto	Dolnoserbski	Hornjoserbsce		Modul:	WP:Lua

URLutil – Modul mit Funktionen für Zeichenketten im Zusammenhang mit Internet-Adressen (URL; IP-Adressen – auch IPv4 und IPv6 – sowie E-Mail). Auch internationalisierte Adressen (IRI) sind möglich.

Unterstellt wird ein Nutzen für ein Wiki-Projekt; also sinnvolle Adressen im offenen Internet. Folgende Sonderfälle sind nicht programmiert, aber auch kaum relevant:

IPv4-Adresse nicht in Standard-Notation (durch Punkte gegliedert, dezimal)
URL mit IPv6-Host (geklammert; beißt sich etwas mit der Wikisyntax)
Authority mit username

Funktionen für Vorlagen

Alle Funktionen haben genau einen unbenannten Pfichtparameter (sinnvollerweise anzugeben). Dieser ist tolerant gegenüber Leerzeichen vor oder nach dem Inhalt. In der Regel handelt es sich dabei um eine URL; ggf. sind auch nur Teile davon möglich. In einigen Fällen gibt es einen optionalen Zusatzparameter.

Der Rückgabewert ist eine leere Zeichenkette („nichts“), wenn der Parameterwert die Erwartung nicht erfüllt. Wenn ein Ergebnis vorhanden oder die Abfragebedingung wahr ist, resultiert mindestens ein Zeichen. Das Ergebnis beginnt oder endet nicht mit Leerzeichen. HTML-Entities sind in der Eingabe möglich und werden im Resultat aufgelöst.

anchorencode

Prozent-Encoding geeignet für id="" HTML-Attribute

Parameter 2 – (optional) erlaubt führende Ziffer

decode

Decoding analog zur Parserfunktion {{urlencode:}}

Kritische Zeichen werden HTML-kodiert; darunter eckige Klammern und Pipe.

Parameter 2 – (optional) Kodierung

2=QUERY – Leerzeichen als Pluszeichen
2=WIKI – sparsame Kodierung, Leerzeichen als Unterstreichungsstrich
2=PATH – Leerzeichen Prozent-kodiert

encode

Encoding analog zur Parserfunktion {{urlencode:}}

Kritische Zeichen zu Beginn werden jedoch kodiert; außerdem eckige Klammern und Pipe.

Parameter 2 – (optional) Kodierung

2=% – QUERY, Leerzeichen als Pluszeichen
2=WIKI – sparsame Kodierung, Leerzeichen als Unterstreichungsstrich
2=PATH – Leerzeichen Prozent-kodiert

getAuthority

Extrahiere aus einer Ressourcen-URL die Server-Ansteuerung (Ergebnis kleingeschrieben)

nichts – wenn unzulässig

getFragment

Extrahiere aus einer Ressourcen-URL den Fragmentbezeichner

Parameter 2 – (optional) Dekodierung

2=% – URL ist Prozent-kodiert
2=WIKI – URL ist Wiki-kodiert mit Punkten und Unterstreichungsstrich

Ergebnis:

nichts – wenn nicht angegeben
beginnend mit # – wenn vorhanden

getHost

Extrahiere aus einer Ressourcen-URL die Domain oder IP-Adresse (Ergebnis kleingeschrieben)

nichts – wenn unzulässig

getLocation

Extrahiere die URL ohne möglichen Fragmentbezeichner

getNormalized

Standardisiere in der URL überflüssiges Encoding und escape [|]<> sowie Leerzeichen

getPath

Extrahiere aus einer Ressourcen-URL den Pfad ohne mögliche Query und ohne möglichen Fragmentbezeichner.

Das Ergebnis beginnt mit / als Basis-Ressource.

nichts – wenn keine Ressourcen-URL

getPort

Extrahiere aus einer Ressourcen-URL die Port-Angabe (Ergebnis Zahl)

nichts – wenn nicht vorhanden

getQuery

Extrahiere aus einer Ressourcen-URL den Query-Anteil

Parameter 2 – (optional) Einzelner Parametername

Parameter 3 – Alternativer Separator wie ; – Vorgabe: &

Ergebnis:

nichts – wenn nicht angegeben
beginnend mit ? – wenn vorhanden
Einzelwert, wenn einzelner Parameter abgefragt

getRelativePath

Extrahiere aus einer Ressourcen-URL den Pfad samt Query und möglichem Fragmentbezeichner, jedoch relativ zum Host; sonst analog getPath.

getScheme

Extrahiere aus einer Ressourcen-URL das Schema (Ergebnis kleingeschrieben; einschließlich doppelter Schrägstriche)

// – relatives Protokoll
https:// – Protokoll
nichts – wenn Beginn der URL unzulässig

getSortkey

Bilde einen Sortierschlüssel aus der URL im www.

Dabei wird nach TLD, Subdomain, Subsubdomain usw., anschließend nach Port und Protokoll und schließlich nach dem Pfad sortiert.

nichts – wenn Beginn der URL unzulässig

getTLD

Extrahiere aus einer Ressourcen-URL die Top-Level-Domain (Ergebnis kleingeschrieben)

nichts – wenn unzulässig oder IP

getTop2domain

Extrahiere aus einer Ressourcen-URL die obersten beiden Level der Domain (Ergebnis kleingeschrieben)

nichts – wenn unzulässig oder IP

getTop3domain

Extrahiere aus einer Ressourcen-URL die obersten drei Level der Domain (Ergebnis kleingeschrieben)

nichts – wenn unzulässig oder IP

isAuthority

Ist es die Server-Adresse (auch IP) einer Ressource, einschließlich Port?

1 – ja

isDomain

Ist es eine benannte Domain, einschließlich Sub-Domains?

1 – ja

isDomainExample

Ist es eine Beispiel-Domain nach RFC 2606 (example.com example.edu example.net example.org)?

1 – ja

isDomainInt

Ist es eine internationalisierte Domain (nicht ASCII oder Punycode)?

1 – ja

isHost

Ist es eine Server-Adresse ohne Port (auch IP)?

1 – ja

isHostPathResource

Ist es eine vollständige Ressourcen-URL oder eine solche ohne Protokoll (beginnend mit Host)?

1 – ja

isIP

Ist es eine IP-Adresse?

4 wenn IPv4 (in Standard-Notation)
6 wenn IPv6
nichts – ansonsten

isIPlocal

Ist es eine IPv4-Adresse, die mutmaßlich nicht zum Internet gehört? RFC 1918, RFC 1122; auch alles wie 0.0.0.0 (RFC 5735)

1 – ja

isIPv4

Ist es eine IPv4-Adresse in Standard-Notation (durch Punkte gegliedert, dezimal)?

1 – ja

isIPv6

Ist es eine IPv6-Adresse?

1 – ja

isMailAddress

Ist es eine E-Mail-Adresse?

1 – ja

isMailLink

Ist es ein E-Mail-Link (mailto:)?

1 – ja

isProtocolDialog

Ist es eine URL / Schema-Bezeichner, das im Wiki einen Dialog einleiten kann?

mailto, irc, ircs, ssh, telnet

1 – ja

isProtocolWiki

Ist es eine URL / Schema-Bezeichner, womit im Wiki auf eine Ressource verwiesen werden kann?

Relatives Protokoll sowie ftp ftps git http https mms nntp sftp svn worldwind

Unerwünscht sind hier: gopher, wais sowie mailto, irc, ircs, ssh, telnet.

1 – ja

isResourceURL

Ist es eine URL, bei der allgemein auf eine Ressource zugegriffen werden kann? Das wären: relatives Protokoll, http, https, ftp und außerdem ein gültiger Host. Andere URL wären auf Projekt- und Funktionsseiten vorstellbar, nicht aber im enzyklopädischen Bereich.

1 – ja

isSuspiciousURL

Ist es eine syntaktisch „verdächtige“ URL, vor der gewarnt werden sollte?

1 – ja

isUnescapedURL

Ist es eine URL, bei der noch Wikisyntax [ | ] abgefangen werden muss?

1 – ja

isWebURL

Ist es eine gültige Adresse für eine Ressource (Protokoll beliebig)?

1 – ja

wikiEscapeURL

Wikisyntax-sicher [ | ] escapen.

Identisch mit dem Parameter, wenn keine problematischen Zeichen vorkommen.
Ersatz von [ | ] durch Webserver-sichere HTML-Entities, falls vorhanden. Eine Pipe ist in der Vorlagensyntax nicht ohne Weiteres möglich.

failsafe: Versionsverwaltung

Die Failsafe-Schnittstelle erlaubt den damit ausgerüsteten Modulen in globaler Verteilung

sicherzustellen, dass eine von einer Vorlage oder einem Modul benötigte Funktion in der lokalen Kopie eines Bibliotheksmoduls vorhanden ist, und ggf. auch in einer erforderlichen Mindestversion;
die globale Aktualisierung und Verknüpfung von Modulen über Wikidata zu verwalten.

Die Failsafe-Schnittstelle liegt sowohl auf Ebene der Vorlagen wie auch in direktem Lua-Zugriff vor.

Die Funktionen sind im Einzelnen (nicht alle werden bereits überall in vollem Umfang unterstützt):

Parameter
Wert	Ergebnis	aktuell
nichts `false`	lokale Version	»2024-11-21«
Mindestversion	Mindestversionsbezeichnung Datum im ISO-Format Es wird verglichen, ob das aktuelle Modul diese Version oder später erfüllt. leer, falls Mindestversion nicht erfüllt	2001-01-01 → »2024-11-21« 2099-01-01 → »«
`wikidata`	Versionsbezeichnung der globalen Mutter (d:Q10859193) Versionsbezeichnung auf Wikidata lokal, falls dort keine gefunden	»2024-10-29«
`item`	ID des Wikidata-Items leer, falls nicht definiert	»Q10859193«
`~`	Übereinstimmung der lokalen mit der auf Wikidata registrierten Versionsbezeichnung leer, falls aktuell Versionsbezeichnung auf Wikidata, falls ungleich	»2024-10-29«
`@`	Ist die aktuelle (Modul-)Seite richtig mit Wikidata verknüpft? leer, falls mit dem richtigen Item verknüpft Item-ID, falls nicht
Der Rückgabewert ist in der Vorlagenprogrammierung leer und per Lua `false`; andernfalls die angegebene Zeichenkette.

Beispiele (Testseite)

Eine Testseite illustriert praktische Beispiele.

Allgemeine Hinweise zur Einbindung von Modulen

Eine Einbindung erfolgt jeweils im Format

{{#invoke: URLutil | Funktionsname | Wert1 | Wert2 | NameX=Wert … }}

Die Parameter können wie bei Vorlagen benannt oder unbenannt sein; deren Regeln gelten analog.

Wenn unbekannte Zeichenketten von außen kommen (als Vorlagenparameter), sollte immer mit der Form 1=Wert gearbeitet werden.

Zu allgemeinen Problemen beachte die Abhilfen wie bei Vorlagen.

Wenn in einer Vorlage ein Modul verwendet wird, sollte auch immer die Vorlage:Dokumentation/Lua in der Dokumentationsseite eingebunden werden.

Das gibt einem Programmierer Aufschluss, dass ein Lua-Modul benutzt wird, welche/s und ggf. welche Einzelfunktion daraus, und verlinkt auf die Dokumentation.
Die Modul-Dokumentationen bekommen ein Link, in welchen Vorlagen sie eingesetzt werden, und wo bei eventuellen Funktionsänderungen Anpassungen erforderlich werden.
Die Vorlage wird zur Übersicht kategorisiert in Kategorie:Vorlage:mit Lua-Programmierung.

Zu weiteren Informationen siehe Hilfe:Lua.

Bei Problemen wende dich bitte an die Vorlagen-Werkstatt, in schweren Fällen hilft auch die Lua-Werkstatt.