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
[Quelltext bearbeiten]format
[Quelltext bearbeiten]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
- wie für
- 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.
- Mögliche Werte:
- shift
- Verschiebung
- wie für
#time
(2. Parameter)- Mögliche Werte:
1 day
oder2 years ago
sowie-5 months
usw. - Die Angaben
tomorrow
oderyesterday
wie auchnext Friday
sind nur möglich, wenn sich 1 aufnow
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.
- Mögliche Werte:
- 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.
- Mögliche Werte: nichts oder
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
[Quelltext bearbeiten]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-08-03 19:12:04+02:00
| |||
ISO-T
|
2024-08-03T19:12:04+02:00
| |||
timestamp
|
20240803071204
| |||
T._Monat JJJJ hh:mm:ss Zone
|
3. August 2024 19:12:04 (MESZ)
|
× | ||
dewiki
|
19:12, 3. Aug. 2024
| |||
T._Monat JJJJ
|
3. August 2024
| |||
T._Mon JJJJ
|
3. Aug. 2024
| |||
T._Mon_JJJJ
|
3. Aug. 2024
|
× | ||
T._Mon4 JJJJ
|
3. Aug. 2024
|
× | ||
T._Mon4_JJJJ
|
3. Aug. 2024
|
× | ||
T._Mon4 JJJJ hh:mm:ss
|
3. Aug. 2024 19:12:04
|
|||
T._Mon4 JJJJ hh:mm:ss Zone
|
3. Aug. 2024 19:12:04 (MESZ)
| |||
T. Mon JJJJ
|
3. Aug. 2024
| |||
TT.MM.JJJJ
|
03.08.2024
| |||
T.M.JJJJ
|
3.8.2024
| |||
$JulianDate$
|
2460526.3001389
| |||
$JulianDate,$
|
2.460.526,3001389
| |||
$"$ Text
|
Text
|
Mehrere Darstellungsformate
[Quelltext bearbeiten]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
[Quelltext bearbeiten]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
– kleinerle
– kleiner oder gleicheq
– gleichne
– ungleichge
– größer oder gleichgt
– größer
failsafe
[Quelltext bearbeiten]Diese Funktion gibt die Versionsbezeichnung des Moduls aus.
{{#invoke:DateTime|failsafe}}
ergibt2023-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)
[Quelltext bearbeiten]Testseiten illustrieren praktische Beispiele.
Funktionen für Lua-Module
[Quelltext bearbeiten]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
[Quelltext bearbeiten]Dieses Objekt sollte immer DateTime
genannt werden. Es steht nicht für eine konkrete Zeitangabe.
Felder
[Quelltext bearbeiten]- .serial
- Versionsdatum der Implementierung; zurzeit:
"2023-10-03"
- .suite
- Typ des Objekts; immer:
"{DateTime}"
Konstruktorfunktion
[Quelltext bearbeiten]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
– jetztfalse
– 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
[Quelltext bearbeiten]- 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
[Quelltext bearbeiten]- .serial
- Versionsdatum der Implementierung; zurzeit:
"2023-10-03"
- .suite
- Typ des Objekts; immer:
"DateTime"
Komponenten des Zeitpunkts
[Quelltext bearbeiten]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
[Quelltext bearbeiten]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.
- Beispiel: Einem Tag im Februar kann nur der Wert
- 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
[Quelltext bearbeiten]Jedes Zeitpunktobjekt kann genauso wie ein Bibliotheksobjekt als Konstruktorfunktion aufgerufen werden (mit gleichen Parametern); deren Ergebnis ist ein neues Zeitpunktobjekt.
Methoden
[Quelltext bearbeiten]Sofern die Aufrufe auch wieder ein Zeitpunktobjekt ergeben, können sie natürlich verkettet werden.
:clone()
[Quelltext bearbeiten]Generiere einen Klon dieses Zeitpunktobjekts.
:fair( access, assign )
[Quelltext bearbeiten]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 )
[Quelltext bearbeiten]Monat über Monatsnamen zuweisen.
- assign
- string – Monatsname
Ergebnis: Zeitpunktobjekt
:first()
[Quelltext bearbeiten]Abgekürzten Monatsnamen in der Objektsprache abfragen.
- Der Zeitpunkt muss einen Monat definiert haben.
Ergebnis: string oder nil
:flow( another, assert )
[Quelltext bearbeiten]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
oderfalse
:format( ask, adapt )
[Quelltext bearbeiten]Zeitpunktobjekt darstellen.
- ask
- Formatspezifikation
- wie für
#time
- gemäß besonderer Vereinbarung
- Vorgabe:
"c"
→ ISO-T
- wie für
- 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 20220426073401
, falls das die Angaben im Objekt waren, das zweite: 19:12, 3. Aug. 2024 (MESZ)
.
:full()
[Quelltext bearbeiten]Monatsname in der Objektsprache abfragen.
- Der Zeitpunkt muss einen Monat definiert haben.
Ergebnis: string oder nil
:future( add )
[Quelltext bearbeiten]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()
[Quelltext bearbeiten]Zeitpunktobjekt als Zeichenkette darstellen; an ISO angenähert und meist wieder einlesbar.
:valueOf()
[Quelltext bearbeiten]Zeitpunktobjekt auf reine table der Komponenten reduzieren.
:failsafe( atleast )
[Quelltext bearbeiten]- atleast
- optionale Zeichenkette, wie dort
Vergleichsausdrücke
[Quelltext bearbeiten]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
oderfalse
.
Beispiele:
local heute = DateTime()
local stop = "2021-12-21"
local termin = DateTime( stop )
if termin > heute then
if heute <= stop then
Verschiebung
[Quelltext bearbeiten]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
[Quelltext bearbeiten]Allgemeine Bibliothek; nicht eingegrenzt.
- Modul:Sort/cellDate – Anwendung für Sortierschlüssel
Abhängigkeiten
[Quelltext bearbeiten]- Modul:DateTime/local – sprach/projektspezifische Anpassungen