Wikipedia:Lua/Modul/DateTime/de

Vorlagenprogrammierung	Diskussionen	Lua			Test	Unterseiten
		Modul	Deutsch	English		Modul:	Dokumentation

DateTime – Modul mit Funktionen für die Interpretation von Datums- und Zeitangaben, sowie ihre Berechnung und Vergleich, schließlich die Darstellung.

Das Modul ist für solche Aufgaben vorgesehen, die die Leistungsfähigkeit der Parserfunktionen #time und #timel übersteigen.

Alle zweifelsfreien Datumsformate für den deutsch- und englischsprachigen Raum werden bei der Eingabe unterstützt.

Funktionen für Vorlagen

format

Formatiere eine Datums-/Zeitangabe.

Parameter (alle optional; umgebender Whitespace wird ignoriert):

1

Angabe von Datum oder Uhrzeit

now – jetzt (Vorgabe)

Interpretierbares Format; Beispiele siehe Testseite.

Führendes # gibt die Anzahl der Sekunden seit 1. Januar 1970 (UTC) an (Unix-Zeit).

  usw. werden als Leerzeichen behandelt.

2

Formatspezifikation

• wie für #time
• gemäß besonderer Vereinbarung

lang

Besondere Sprachbezeichnung (Kürzel gemäß ISO 639)

• Mögliche Werte: de (Vorgabe); de-AT sowie wohl alle Sprachen, in denen eine Wikipedia existiert. Bei unbekannter Sprachvariante wird auf die Basissprache zurückgefallen. Groß- und Kleinschreibung wird ignoriert.

shift

Verschiebung

wie für #time (2. Parameter)

• Mögliche Werte: 1 day oder 2 years ago sowie -5 months usw.
• Die Angaben tomorrow oder yesterday wie auch next Friday sind nur möglich, wenn sich 1 auf now bezieht.
• Anders als bei #time ist ansonsten auch die Angabe eines Basiszeitpunkts möglich.
• Eine einzelne Zahl ohne Maßeinheit wird als Anzahl von Sekunden interpretiert, positiv/negativ, muss nicht ganzzahlig sein (Dezimalpunkt).
• Wie bei #time kann es bei Überschreitung von Monats- oder Jahresgrenzen durch andere als glatte Intervalle zu unvorhergesehenen Ergebnissen kommen; was der 31. Mai plus 1 Monat sein soll, bleibt ohnehin unklar.

noerror

Fehlermeldung unterdrücken

• Mögliche Werte: nichts oder 0 (Vorgabe); 1 sonst
• Standardmäßig wird eine mit class="error" markierte Meldung gezeigt.
• Wenn sich bei noerror=1 ein leerer Wert ergibt, war der Eingabewert ungültig.

Ergebnis: Formatierte Angabe.

• Anders als bei der Parserfunktion führen fehlende Angaben in der Eingabe jedoch nicht dazu, dass es zu Fehlern oder unerwünschten Ergänzungen kommt; sondern der Ausgabewert wird möglichst auf die Elemente beschränkt, die auch angegeben wurden.

errCat

Ein oder mehrere Titel von Wartungskategorien.

Die Titel sind durch Pipe-Symbol (per {{!}}) zu trennen.

Beispiel: errCat=Wikipedia:Vorlagenfehler/Parameter:Datum

Standardformate

Zusätzliche Formatspezifikationen über #time hinaus (nur deutschsprachig)

Bezeichner	Beispielausgabe	geschütztes Leerzeichen zwischen		Monatsname bis 4 Buchstaben nicht abkürzen
		Punkt und Monatsname	Monatsname und Jahreszahl
keine Angabe	→ISO-T
ISO	2024-11-27 15:33:10+01:00
ISO-T	2024-11-27T15:33:10+01:00
timestamp	20241127033310
T._Monat JJJJ hh:mm:ss Zone	27. November 2024 15:33:10 (MEZ)	×
dewiki	15:33, 27. Nov. 2024
T._Monat JJJJ	27. November 2024
T._Mon JJJJ	27. Nov. 2024
T._Mon_JJJJ	27. Nov. 2024		×
T._Mon4 JJJJ	27. Nov. 2024			×
T._Mon4_JJJJ	27. Nov. 2024		×
T._Mon4 JJJJ hh:mm:ss	27. Nov. 2024 15:33:10
T._Mon4 JJJJ hh:mm:ss Zone	27. Nov. 2024 15:33:10 (MEZ)
T. Mon JJJJ	27. Nov. 2024
TT.MM.JJJJ	27.11.2024
T.M.JJJJ	27.11.2024
$JulianDate$	2460642.1482986
$JulianDate,$	2.460.642,1482986
$"$Text	Text

Mehrere Darstellungsformate

Es ist möglich, denselben Zeitpunkt mehrfach in unterschiedlichen Formaten und somit ggf. anderen Zeitrechnungen, Kalendern, Zeitzonen darzustellen.

• Dazu müssen die Formatangaben durch ||| voneinander getrennt werden.
• In der Vorlagenprogrammierung wird das durch {{!}}{{!}}{{!}} erreicht.
• Die Komponenten werden nahtlos aneinandergefügt.
• Mit dem Sonderformat $"$ können Textblöcke eingestreut werden, damit Schlüsselwörter als Formate nutzbar sind. Gleichzeitig lässt sich die Darstellung entsprechend gliedern und beschriften.
• Die Verwendung ist etwas komplizierter und zielt auf entsprechende Vorlagenprogrammierungen ab.

lt le eq ne ge gt

Diese Funktionen vergleichen den ersten und zweiten Parameter miteinander; als Datum/Zeit in beliebigem Format (oder „jetzt“ wenn nicht angegeben).

• Funktionswert ist 1, wenn die Bedingung erfüllt ist, sonst „nichts“.

Die Funktionen sind im Einzelnen:

• lt – kleiner
• le – kleiner oder gleich
• eq – gleich
• ne – ungleich
• ge – größer oder gleich
• gt – größer

failsafe

Diese Funktion gibt die Versionsbezeichnung des Moduls aus.

• {{#invoke:DateTime|failsafe}} ergibt 2023-10-03

Mit Angabe eines Parameters als Datum im ISO-Format wird verglichen, ob das aktuelle Modul diese Version oder später erfüllt.

• {{#invoke:DateTime|failsafe|2001-01-01}} ergibt: »2023-10-03«
• {{#invoke:DateTime|failsafe|2099-01-01}} ergibt: »« – leer, falls Mindestversionsbezeichnung nicht erfüllt

Ist dieser Zusatzparameter das Schlüsselwort wikidata, so ist der Wert die auf Wikidata registrierte Versionsbezeichnung (2023-10-03) oder lokal, falls dort keine gefunden.

• Ist der Zusatzparameter das Zeichen ~, so ist das Ergebnis leer, falls Übereinstimmung der lokalen mit der auf Wikidata registrierten Versionsbezeichnung besteht (2023-10-03).

Beispiele (Testseiten)

Testseiten illustrieren praktische Beispiele.

Funktionen für Lua-Module

Die Bibliothek kann auch über require() in andere Module eingebunden werden:

local lucky, DateTime = pcall( require, "Modul:DateTime" )
if type( DateTime ) == "table" then
    DateTime = DateTime.DateTime()
else
    -- Fehlerfall; DateTime enthält Fehlermeldung
    return "<span class=\"error\">" .. DateTime .. "</span>"
end

Danach steht das Bibliotheksobjekt DateTime zur Verfügung.

Bibliotheksobjekt

Dieses Objekt sollte immer DateTime genannt werden. Es steht nicht für eine konkrete Zeitangabe.

Felder

.serial

Versionsdatum der Implementierung; zurzeit: "2023-10-03"

.suite

Typ des Objekts; immer: "{DateTime}"

Konstruktorfunktion

Das Bibliotheksobjekt kann als Konstruktorfunktion DateTime() aufgerufen werden; deren Ergebnis ist ein Zeitpunktobjekt. Bei ungültiger Anforderung wird false zurückgegeben; möglicherweise auch ein string mit einer feststellbaren Fehlermeldung.

Die Konstruktorfunktion hat drei optionale Parameter:

assign

Angabe von Datum oder Uhrzeit

• nil – jetzt
• false – leeres Objekt
• "now" – jetzt
• string – Interpretierbares Format; Beispiele siehe Testseite.
• Zeitpunktobjekt
• table – Komponenten

alien

Besondere Sprachbezeichnung (Kürzel gemäß ISO 639) analog zum Vorlagenparameter lang.

nil – de

add

Verschiebungsintervall

nil – keine Verschiebung

string – analog zum Vorlagenparameter shift

number – Anzahl von Sekunden, positiv/negativ, muss nicht ganzzahlig sein

Beispiel:

local o = DateTime( "2013-12" )

Es wird ein Zeitpunktobjekt o generiert mit den Komponenten year=2013 und month=12; sowie in unserem Kontext lang=de.

Zeitpunktobjekt

• Jedes Zeitpunktobjekt repräsentiert einen konkreten Zeitpunkt, der allerdings auch leer sein könnte.
• Jedes Zeitpunktobjekt enthält dieselben Felder und Methoden wie das Bibliotheksobjekt und könnte an dessen Stelle verwendet werden.

Felder

.serial

Versionsdatum der Implementierung; zurzeit: "2023-10-03"

.suite

Typ des Objekts; immer: "DateTime"

Komponenten des Zeitpunkts

Alle Zahlen sind ganzzahlig, wodurch sich Genauigkeiten und erforderliche Ausgabefomate schnell und sicher bestimmen lassen.

Komponente	Typ	Bemerkung
lang	string	Code der Standardsprache nach ISO 639 (de)
bc	boolean	false, nil: n. Chr.
year	number	>0 (=0??)
month	number	1–12; auch ohne year
dom	number
week	number	Nach ISO berechnet
hour	number
min	number
sec	number
msec	number	0–999; volle Millisekunden
mysec	number	0–999; ohne volle Millisekunden
dom2	boolean	Einstellige Zahlen wurden zweistellig angegeben, obwohl das Eingabeformat dies nicht erzwungen hatte.
month2
hour2
zone	string, number, boolean	Code (CET,CEST,MEZ) oder Anzahl der Minuten false, nil: Lokal, einschließlich Sommerzeit
leap	boolean	false, nil: sec<60 (Schaltsekunde unzulässig)
jul	boolean	false, nil: Gregorianischer Kalender

Wertzuweisung

Existiert ein Objekt, dann können auch einzelnen Komponenten Werte zugewiesen werden:

o.dom = 31

Die Zuweisung wird nur ausgeführt, wenn sie gültig ist. Das bedeutet:

• Zahlenwerte usw. müssen im Kontext aller anderen Komponenten gültig sein.
  • Beispiel: Einem Tag im Februar kann nur der Wert 29 zugewiesen werden, wenn ein angegebenes Jahr auch ein Schaltjahr ist.
• Die Abfolge der Komponenten darf nicht unterbrochen sein; das heißt, es darf kein Lücke entstehen zwischen der ersten und letzten definierten Komponente (etwa Jahr, Monat, Tag, Stunde, Minute, Sekunde).

An dieser Stelle ist keine Fehlermeldung möglich. Ob eine Zuweisung erfolgreich vorgenommen wurde, wäre in Zweifelsfällen anschließend zu überprüfen; im obigen Beispiel:

if o.dom ~= 31 then

Konstruktorfunktion

Jedes Zeitpunktobjekt kann genauso wie ein Bibliotheksobjekt als Konstruktorfunktion aufgerufen werden (mit gleichen Parametern); deren Ergebnis ist ein neues Zeitpunktobjekt.

Methoden

Sofern die Aufrufe auch wieder ein Zeitpunktobjekt ergeben, können sie natürlich verkettet werden.

:clone()

Generiere einen Klon dieses Zeitpunktobjekts.

:fair( access, assign )

Formale Gültigkeit eines Zeitpunktobjekts prüfen.

access

Einzelnes Datenelement, das geprüft werden soll

string oder nil

nil – ganzes Objekt (Vorgabe)

access

Einzelner Wert für access, der geprüft werden soll

string oder nil

Nur sinnvoll, wenn access angegeben

Ergebnis: boolean

:figure( assign )

Monat über Monatsnamen zuweisen.

assign

string – Monatsname

Ergebnis: Zeitpunktobjekt

:first()

Abgekürzten Monatsnamen in der Objektsprache abfragen.

• Der Zeitpunkt muss einen Monat definiert haben.

Ergebnis: string oder nil

:flow( another, assert )

Vergleiche das Zeitpunktobjekt mit einem anderen Zeitpunkt.

another

anderer Zeitpunkt; table als Objekt oder geeignete Zeichenkette

assert

Optionaler Vergleichsoperator als Bedingung

Einer von: "lt", "le", "eq", "ne", "ge", "gt", "<", "<=", "==", "~=", "<>", ">=", "=>", ">"

Ergebnis:

• ohne (gültiges) assert: -1, 0, 1 für kleiner, gleich, größer
• mit assert: true oder false

:format( ask, adapt )

Zeitpunktobjekt darstellen.

ask

Formatspezifikation

• wie für #time
• gemäß besonderer Vereinbarung
• Vorgabe: "c" → ISO-T

adapt

Optionen; table oder nil

• .lang – Besondere Sprachbezeichnung (Kürzel gemäß ISO 639)
• .london – Ausgabe in UTC; Standard ist lokal
• .lonely – Stunde ohne Minute

Ergebnis: Zeichenkette mit der formatierten Angabe; siehe format für Vorlagen.

Beispiele:

o:format( "timestamp" )
DateTime():format( "dewiki" )

Das erste Beispiel ergibt 20220426063401, falls das die Angaben im Objekt waren, das zweite: 15:33, 27. Nov. 2024 (MEZ).

:full()

Monatsname in der Objektsprache abfragen.

• Der Zeitpunkt muss einen Monat definiert haben.

Ergebnis: string oder nil

:future( add )

Verschiebung um Zeitspanne.

add

Zeitspanne

analog zum Vorlagenparameter shift

Syntax wie beim zweiten Parameter von #time, ausgenommen: Next Thursday

Ergebnis: Zeitpunktobjekt

Beispiele:

o:future( "tomorrow" )
o:future( "1 week 3 days" )
o:future( "1 year ago" )
o:future( "-3 years 1 day" )

:tostring()

Zeitpunktobjekt als Zeichenkette darstellen; an ISO angenähert und meist wieder einlesbar.

:valueOf()

Zeitpunktobjekt auf reine table der Komponenten reduzieren.

:failsafe( atleast )

Siehe oben.

atleast

optionale Zeichenkette, wie dort

Vergleichsausdrücke

Ein Zeitpunktobjekt kann mit einem darauf folgenden anderen oder einer geeigneten Zeichenkette verglichen werden, indem einer der gängigen Lua-Vergleichsoperatoren dazwischengesetzt wird:

• < <= == ~= >= >
• Der Wert des Ausdrucks ist true oder false.

Beispiele:

local heute  = DateTime()
local stop   = "2021-12-21"
local termin = DateTime( stop )
if termin > heute then
if heute <= stop then

Verschiebung

Der Wert eines Objekts kann geändert werden, indem eine unter :future() angegebene Zeitspanne mittels + „addiert“ wird.

Beispiel:

local fristablauf = o + "1 year 2 days -1 hour"

Ergebnis: Zeitpunktobjekt

Verwendung

Allgemeine Bibliothek; nicht eingegrenzt.

• Modul:Sort/cellDate – Anwendung für Sortierschlüssel

Abhängigkeiten

• Modul:DateTime/local – sprach/projektspezifische Anpassungen