Vidi fonton por Vikipedio:Lua/Moduloj/URLutil/de

{{LuaModuleDoc}}
<onlyinclude>'''<code>URLutil</code>''' – Modul mit Funktionen für Zeichenketten im Zusammenhang mit Internet-Adressen ([[Uniform Resource Locator|URL]]; IP-Adressen –&nbsp;auch [[IPv4]] und [[IPv6]]&nbsp;– sowie E-Mail). Auch internationalisierte Adressen ([[Internationalized Resource Identifier|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''
<noinclude>__TOC__</noinclude>
== {{Ankro3|Vorlage}} 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.

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.
; getURIScheme   {{Ankro3|getURIScheme}}
: Extrahiere das [[Uniform Resource Identifier|URI]]-Schema aus einer beliebigen URL, z.B. einem <code>mailto:</code> Link)  (Ergebnis kleingeschrieben; ohne Doppelpunkt und Schrägstriche). ''Für Ressourcen-URLs siehe auch das spezialisierte [[#getScheme|getScheme]].''
:* <code>mailto</code> – URI-Schema
:* <code>//</code> – Spezialfall: schemarelative URL (z.B. <code>//de.wikipedia.org</code>)
:* ''nichts'' – wenn Beginn der URL unzulässig
; getAuthority   {{Ankro3|getAuthority}}
: Extrahiere aus einer Ressourcen-URL die Server-Ansteuerung (Ergebnis kleingeschrieben)
:* ''nichts'' – wenn unzulässig
; getFragment   {{Ankro3|getFragment}}
: Extrahiere aus einer Ressourcen-URL den [[Fragmentbezeichner]]
: Parameter '''2''' – (optional) Dekodierung
:* <code>2=%</code> – URL ist Prozent-kodiert
:* <code>2=WIKI</code> – URL ist Wiki-kodiert mit Punkten und Unterstreichungsstrich
: Ergebnis:
:* ''nichts'' – wenn nicht angegeben
:* beginnend mit <code>#</code> – wenn vorhanden
; getHost   {{Ankro3|getHost}}
: Extrahiere aus einer Ressourcen-URL die Domain oder IP-Adresse (Ergebnis kleingeschrieben)
:* ''nichts'' – wenn unzulässig
; getLocation   {{Ankro3|getLocation}}
: Extrahiere die URL ohne möglichen [[Fragmentbezeichner]]
; getPath   {{Ankro3|getPath}}
: Extrahiere aus einer Ressourcen-URL den Pfad ohne mögliche Query und ohne möglichen [[Fragmentbezeichner]].
: Das Ergebnis beginnt mit <code>/</code> als Basis-Ressource.
; getPort   {{Ankro3|getPort}}
: Extrahiere aus einer Ressourcen-URL die Port-Angabe (Ergebnis Zahl)
:* ''nichts'' – wenn nicht vorhanden
; getQuery   {{Ankro3|getQuery}}
: Extrahiere aus einer Ressourcen-URL den Query-Anteil
: Parameter '''2''' – (optional) Einzelner Parametername
: Parameter '''3''' – Alternativer Separator wie <code>;</code> – Vorgabe: <code>&</code>
: Ergebnis:
:* ''nichts'' – wenn nicht angegeben<includeonly>
:* beginnend mit <code>?</code> – wenn vorhanden</includeonly>
:* Einzelwert, wenn einzelner Parameter abgefragt
; getRelativePath   {{Ankro3|getRelativePath}}
: Extrahiere aus einer Ressourcen-URL den Pfad samt Query und möglichem [[Fragmentbezeichner]], jedoch relativ zum Host.
; getScheme   {{Ankro3|getScheme}}
: Extrahiere aus einer Ressourcen-URL das Schema (Ergebnis kleingeschrieben; einschließlich doppelter Schrägstriche)
:* <code>//</code> – relatives Protokoll
:* <code>https://</code> – Protokoll
:* ''nichts'' – wenn Beginn der URL unzulässig
; getTLD   {{Ankro3|getTLD}}
: Extrahiere aus einer Ressourcen-URL die ''[[Top-Level-Domain]]'' (Ergebnis kleingeschrieben)
:* ''nichts'' – wenn unzulässig oder IP
; getTop2domain   {{Ankro3|getTop2domain}}
: Extrahiere aus einer Ressourcen-URL die obersten beiden Level der Domain (Ergebnis kleingeschrieben)
:* ''nichts'' – wenn unzulässig oder IP
; getTop3domain   {{Ankro3|getTop3domain}}
: Extrahiere aus einer Ressourcen-URL die obersten drei Level der Domain (Ergebnis kleingeschrieben)
:* ''nichts'' – wenn unzulässig oder IP
; isAuthority   {{Ankro3|isAuthority}}
: Ist es die Server-Adresse (auch IP) einer Ressource, einschließlich Port?
:* <code>1</code> – ''ja''
; isDomain   {{Ankro3|isDomain}}
: Ist es eine benannte Domain, einschließlich Sub-Domains?
:* <code>1</code> – ''ja''
; isDomainExample   {{Ankro3|isDomainExample}}
: Ist es eine Beispiel-Domain nach RFC 2606 (example.com example.edu example.net example.org)?
:* <code>1</code> – ''ja''
; isDomainInt   {{Ankro3|isDomainInt}}
: Ist es eine [[Internationalized Domain Name|internationalisierte Domain]] (nicht ASCII oder [[Punycode]])?
:* <code>1</code> – ''ja''
; isHost   {{Ankro3|isHost}}
: Ist es eine Server-Adresse ohne Port (auch IP)?
:* <code>1</code> – ''ja''
; isIP   {{Ankro3|isIP}}
: Ist es eine IP-Adresse?
:* <code>4</code> ''wenn [[IPv4]]'' (in Standard-Notation)
:* <code>6</code> ''wenn [[IPv6]]''
:* ''nichts'' – ansonsten
; isIPlocal   {{Ankro3|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)
:* <code>1</code> – ''ja''
; isIPv4   {{Ankro3|isIPv4}}
: Ist es eine [[IPv4]]-Adresse in Standard-Notation (durch Punkte gegliedert, dezimal)?
:* <code>1</code> – ''ja''
; isIPv6   {{Ankro3|isIPv6}}
: Ist es eine [[IPv6]]-Adresse?
:* <code>1</code> – ''ja''
; isMailAddress   {{Ankro3|isMailAddress}}
: Ist es eine E-Mail-Adresse?
:* <code>1</code> – ''ja''
; isMailLink   {{Ankro3|isMailLink}}
: Ist es ein E-Mail-Link (<nowiki>mailto:</nowiki>)?
:* <code>1</code> – ''ja''
; isProtocolMW   {{Ankro3|isProtocolMW}}
: Ist es eine URL / Schema-Bezeichner, das vom Wiki allgemein erkannt wird?
: Aktuelle Liste siehe [https://doc.wikimedia.org/mediawiki-core/master/php/html/DefaultSettings_8php_source.html#l03387]
:* <code>1</code> – ''ja''
; isProtocolDialog   {{Ankro3|isProtocolDialog}}
: Ist es eine URL / Schema-Bezeichner, das im Wiki einen Dialog einleiten kann?
: <code>mailto, irc, ircs, ssh, telnet</code>
:* <code>1</code> – ''ja''
; isProtocolWiki   {{Ankro3|isProtocolWiki}}
: Ist es eine URL / Schema-Bezeichner, womit im Wiki auf eine Ressource verwiesen werden kann?
: Relatives Protokoll sowie <code>ftp ftps git http https mms nntp sftp svn worldwind</code>
: Unerwünscht sind hier: gopher, wais sowie mailto, irc, ircs, ssh, telnet.
:* <code>1</code> – ''ja''
; isResourceURL   {{Ankro3|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.
:* <code>1</code> – ''ja''
; isSuspiciousURL   {{Ankro3|isSuspiciousURL}}
: Ist es eine syntaktisch „verdächtige“ URL, vor der gewarnt werden sollte?
:* <code>1</code> – ''ja''
; isUnescapedURL   {{Ankro3|isUnescapedURL}}
: Ist es eine URL, bei der noch Wikisyntax <code>[ | ]</code> abgefangen werden muss?
:* <code>1</code> – ''ja''
; isWebURL   {{Ankro3|isWebURL}}
: Ist es eine gültige Adresse für eine Ressource (Protokoll beliebig)?
:* <code>1</code> – ''ja''
; wikiEscapeURL   {{Ankro3|wikiEscapeURL}}
: Wikisyntax-sicher <code>[ | ]</code> escapen.
:* Identisch mit dem Parameter, wenn keine problematischen Zeichen vorkommen.
:* Ersatz von <code>[ | ]</code> durch Webserver-sichere HTML-Entities, falls vorhanden. Eine Pipe ist in der Vorlagensyntax nicht ohne Weiteres möglich.

===  Beispiele (Testseite) ===
Eine [[:de:Wikipedia:Lua/Modul/URLutil/test|Testseite]] illustriert praktische Beispiele.</onlyinclude>

== {{Ankro3|Lua}} Funktionen für Lua-Module ==

Alle oben dokumentierten Funktionen können auch über <code>require()</code> in andere Module eingebunden werden:
<syntaxhighlight lang="lua">
local lucky, URLutil = pcall( require, "Modulo:URLutil" )
if type( URLutil ) == "table" then
    URLutil = URLutil.URLutil()
else
    -- Fehlerfall; URLutil enthält Fehlermeldung
    return "<span class='error'>" .. URLutil .. "</span>"
end
</syntaxhighlight>
Danach stehen folgende Funktionen zur Verfügung:
* URLutil.getURIScheme()
* URLutil.getAuthority()
* URLutil.getFragment()<br />Zeichenkette nach <code>#</code>
* URLutil.getHost()
* URLutil.getLocation()
* URLutil.getPath()
* URLutil.getPort()<br />numerischer Wert, oder <code>false</code>
* URLutil.getQuery(url, key, separator)<br />Zeichenkette nach <code>?</code>
* URLutil.getQueryTable(url, separator)<br />''table'' mit allen Zuweisungen ''key=value''
* URLutil.getRelativePath()
* URLutil.getScheme()
* URLutil.getTLD()
* URLutil.getTop2domain()
* URLutil.getTop3domain()
* URLutil.isAuthority()
* URLutil.isDomain()
* URLutil.isDomainExample()
* URLutil.isDomainInt()
* URLutil.isHost()
* URLutil.isIP()<br />numerisch 4, 6, oder <code>false</code>
* URLutil.isIPlocal()
* URLutil.isIPv4()
* URLutil.isIPv6()
* URLutil.isMailAddress()
* URLutil.isMailLink()
* URLutil.isProtocolMW()
* URLutil.isProtocolDialog()
* URLutil.isProtocolWiki()
* URLutil.isResourceURL()
* URLutil.isSuspiciousURL()
* URLutil.isUnescapedURL()
* URLutil.isWebURL()
* URLutil.wikiEscapeURL()
Im Erfolgsfall geben die ''URLutil.get*()'' eine Zeichenkette zurück, die ''URLutil.is*()'' den Wert <code>true</code> (sofern nicht anders angegeben); bei Misserfolg jeweils <code>false</code>.

Zusätzlich gibt es zwei Konstanten:
* URLutil.serial – ''string'', aktuelle Versionsnummer (Datum)
* URLutil.suite – <code>"URLutil"</code>

== Verwendung ==
Allgemeine Bibliothek; nicht eingegrenzt.

== Abhängigkeiten ==
Keine.

== Siehe auch ==
* [[:de:Hilfe:Lua/Links#mw.uri|mw: '''Uri library''']] – andere Funktionalitäten auf allgemeiner URI; aber speziell für Wiki-URL hilfreich.

<!-- == Interne Funktionen == -->
== Vorbild ==
* [[:de:Vorlage:URLutil]] - vom 15. Juni 2013, die ihrerseite teilweise aus [[:en:Special:Permalink/542839577?title=Module:IPAddress|en:Module:IPAddress]] – 1. März 2013  entstand
* Unit tests: [[:en:Module:IPAddress/tests]]

[[Kategorio:Vikipedio:Lua/Moduloj/dokumentado|URLutil/de]]