Hilfe:Lua/Zeichenketten

Diese Hilfeseite gibt für Lua-Programmierer eine Kurzreferenz zum Umgang mit Zeichenketten in der Lua-Programmierung.

ASCII und Unicode

Die Wiki-Projekte sind in vollem Unicode geschrieben, Lua arbeitet jedoch nur mit 8-bit-Code (ISO 8859-1).

• Wenn das Suchmuster sich auf ASCII beschränkt, kann etwas effizienter mit den ASCII-Funktionen und entsprechenden Pattern gearbeitet werden, weil die Umwandlung von UTF-8 entfällt. Der 8-bit-Anteil jenseits von ASCII ist nicht sinnvoll nutzbar, weil hier die UTF-8-Kodierungen liegen.
• Allgemeine, beliebige Zeichenketten des Wikitextes müssen mit den ustring-Funktionen für Unicode verarbeitet werden.

String-Funktionen (Kurzreferenz)

siehe Scribunto (englisch):

• ASCII string
• mw.ustring

Angegeben sind jeweils die Funktionen für ASCII und Unicode; letztere mit mw.ustring.*().

Parameter

Die Parameter bedeuten:

• s – Ausgangs-Zeichenkette
  • !!! Datentyp string sicherstellen !!!
• pattern – Suchmuster
  • Kann Klammer-Paare (captures) enthalten, die den Ergebnisvariablen zugeordnet werden.
• c – Zeichen-Code (ASCII oder codepoint)
• i – Start-Index; -1: letztes Zeichen.
  • Beginnend mit 1.
  • Negativ: vom Ende zählen.
• j – End-Index.
  • Position des letzten Zeichens; ab 1 gezählt, einschließlich.
  • Negativ: vom Ende zählen; -1: bis zum Schluss
• n – Anzahl (optional)
• init – Start-Index (optional); kann negativ sein und zählt dann vom Ende
• plain – pattern nicht als pattern-Syntax, sondern buchstäblich (optional)

Die Index-Zahlen gelten immer in Zeichen; das sind bei der ASCII-Version Bytes.

• Wenn ein Unicode-String nicht ordnungsgemäß nach UTF-8 kodiert ist, wird nil von den mw.ustring.* zurückgegeben. Das ist beim Wikitext nicht zu erwarten, wenn man ihn nicht vorher selbst ruiniert hatte.
• Ansonsten ist der Rückgabewert die neue Zeichenkette bzw. die erfragte Anzahl in Byte bzw. Unicode-Zeichen.

Kurzreferenz

string.byte( s, i, j )

s:byte( i, j )

mw.ustring.byte( s, i, j )

mw.ustring.codepoint( s, i, j )

Jedes Byte/Zeichen in einzelne Variable

r1, r2, r3, r4 = s:byte( i, j )

mw.ustring.byteoffset( s, l, i )

Byte-Position eines Unicode-Zeichens

string.char( c1, c2, c3, … )

mw.ustring.char( c1, c2, c3, … )

Zeichenkette aus den angegebenen Codes bilden

string.find( s, pattern, init, plain )

s:find( pattern, init, plain )

mw.ustring.find( s, pattern, init, plain )

Beginn und optional Ende des gesamten pattern in s; optional ab Position init gesucht.

j, k = s:find( pattern )

Wird pattern nicht gefunden, sind beide Zahlen nil.

Optionales plain bewirkt die buchstäbliche Suche nach pattern, nicht über die besondere Syntax.

Siehe auch match()

Besonderheit: Ein leeres Klammernpaar in pattern ist möglich; liefert die Position dieses Treffers. Klammern (captures) haben ansonsten keine Wirkung.

string.format( format, p1, p2, … )

mw.ustring.format( format, p1, p2, … )

Formatiere Argumente in begrenztem C-Stil (printf)

Siehe unten

mw.ustring.gcodepoint( s, i, j )

Iterator für eine for-Schleife über jedes Zeichen

string.gmatch( s, pattern )

s:gmatch( pattern )

mw.ustring.gmatch( s, pattern )

Iterator für eine for-Schleife

string.gsub( s, pattern, replace, n )

s:gsub( pattern, replace, n )

mw.ustring.gsub( s, pattern, replace, n )

Ersetze (substituiere) pattern durch replace.

n optional; Vorgabe: alle

r, k = s:gsub( pattern, replace )

Der zweite Rückgabewert ist die Anzahl der vorgenommenen Ersetzungen.

Vorsicht: return s:gsub( "X", "U" ) hängt unvermutet eine Zahl an die Zeichenkette des Rückgabewerts an.

• Wenn replace eine Zeichenkette ist, wird sie für die Ersetzung benutzt.
• Dabei können Klammerausdrücke durch %1 bis %9 eingefügt werden. %0 steht für die gesamte Fundstelle.
• Wenn replace eine Tabelle ist, wird über den ersten Klammerausdruck auf ein geeignetes Element zugegriffen; ansonsten über den gesamten Treffer.
• Wenn replace eine Funktion ist, wird diese Funktion bei jedem Treffer aufgerufen, und alle Klammerausdrücke als Parameter übergeben; ansonsten der gesamte Treffer.
• Wenn das Ergebnis von Tabellenabfrage oder Funktionsaufruf eine Zeichenkette oder Zahl ist, wird mit diesem Wert ersetzt. Ist es nil oder false, dann wird nichts verändert.

mw.ustring.isutf8( s )

true wenn die UTF-8-Kodierung gültig ist.

string.len( s )

s:len()

mw.ustring.len( s )

Länge der Zeichenkette

s:len() ist das Gleiche wie #s

string.lower( s )

s:lower()

mw.ustring.lower( s )

Kleinbuchstaben

string.match( s, pattern, init )

s:match( pattern, init )

mw.ustring.match( s, pattern, init )

r1, r2, r3 = s:match( pattern )

Inhalte der Klammern des pattern in s; ohne Klammern r1=s

Optional ab Position init

Siehe auch find()

string.rep( s, n )

s:rep( n )

mw.ustring.rep( s, n )

(Repeat) n Wiederholungen von s

Bei der Wiederholung einer ganzen gültigen Zeichenkette spielt die Kodierung keine Rolle; aber der Symmetrie und Vollständigkeit halber auch mw.ustring.rep().

„repeat“ ist ein reserviertes Schlüsselwort, das nicht als Name für eine Funktion verwendet werden kann.

string.reverse( s )

s:reverse()

Zeichenkette rückwärts

string.sub( s, i, j )

s:sub( i, j )

mw.ustring.sub( s, i, j )

Substring: Teilzeichenkette von i bis j.

Sowohl i als auch j können negativ sein und zählen dann vom Ende.

j ist optional und hat -1 als Vorgabe.

mw.ustring.toNFC( s )

Unicode-Normalisierung der kanonischen Komposition

mw.ustring.toNFD( s )

Unicode-Normalisierung der kanonischen Dekomposition

string.upper( s )

s:upper()

mw.ustring.upper( s )

Großbuchstaben

mw.ustring.maxPatternLength

10000 (Mai 2013)

mw.ustring.maxStringLength

2048000 (Mai 2013) und damit für alle darstellbaren Wiki-Quelltexte gerade hinreichend

.format()

siehe Scribunto (englisch)

Die beiden Funktionen

• string.format( spec, p1, p2, … )
• mw.ustring.format( spec, p1, p2, … )

formatieren ihre Argumente p1, p2 usw.

Dabei ist

• spec eine Zeichenkette aus den nachstehenden Spezifikatoren.
  • Neben den Spezifikatoren kann beliebiger Text eingestreut werden, sofern er keine Prozentzeichen enthält.
• Jeder Spezifikation muss ein Wert p_i aus der Parameterliste gegenüberstehen.

Die Formatierungs-Spezifizierung spec für die einzelnen Werte entspricht einer Teilmenge der Programmiersprache C (printf).

Die prinzipielle Struktur der Spezifikation für einen einzelnen Wert ist

% f w .p s c

mit den optionalen Angaben

• f – flags
• w – width (Feldweite)
• p – precision
• s – size
• c – conversion (Kennbuchstabe, Pflicht) für den Datentyp; oder %% zur Darstellung eines einzelnen Prozentzeichens.

Die Spezifikation beginnt also mit dem Prozentzeichen und endet mit dem Kennbuchstaben; die näheren Angaben dazwischen sind frei.

• Als flags sind vorhanden: '-', '+', ' ', '#', '0'.
• Für ganze Zahlen werden Feldweiten bis 99 unterstützt. '*' ist nicht verfügbar.
• Für ganze Zahlen werden precisions bis 99 unterstützt. '*' ist nicht verfügbar.
• Length modifiers werden nicht unterstützt.
• Kennbuchstaben für conversion siehe unten.
• Positional specifiers (wie "%2$s") werden nicht unterstützt.

conversion

c	Kodierung als einzelnes Zeichen
d	Dezimalzahl
i	Dezimalzahl mit Vorzeichen; in Lua wie d
u	Vorzeichenlose Dezimalzahl; in Lua wie d
o	Oktalzahl
x	Hexadezimalzahl; kleine Buchstaben
X	Hexadezimalzahl; große Buchstaben
e	Exponentialnotation; kleines e
E	Exponentialnotation; großes E
f	Gleitkommazahl
g	Gleitkommazahl oder e nach Genauigkeit
G	Gleitkommazahl oder E nach Genauigkeit
s	Formatierung als Zeichenkette bestimmter Länge
%	Prozentzeichen
q	Lua-interne Repräsentation; wiedereinlesbar kodiert

Der Kennbuchstabe ‘q’ entspricht ‘s’, formatiert jedoch die Zeichenkette auf eine Weise, die später vom Lua-Interpreter zurückgelesen werden kann: Eingeschlossen in " und im Inneren geeignet escaped.

Pattern

Die Pattern entsprechen im Prinzip den verbreiteten regulären Ausdrücken mit einigen Besonderheiten:

• Escape über % und so ebenfalls die Kennzeichnung der Spezifikatoren.
• Innerhalb der eckigen Klammern für Zeichenbereiche sind auch Spezifikatoren möglich.
• Es können nur einzelne Zeichen, Spezifikatoren oder in eckige Klammern gesetzte Zeichendefinitionen mit einer Wiederholungsangabe * ? + - versehen werden. Bei in runde Klammern gesetzten Ausdrücken (captures) ist das nicht möglich.
• Es gibt keine Disjunktion | (Pipe).
• Der Punkt . schließt Zeilenumbrüche mit ein (!).
• Für Anfang und Ende stehen ^ und $ – im Inneren jedoch als ganz normale Zeichen. Andere Begrenzer wie \b gibt es nicht.
• Es gibt eine non-greedy Wiederholungsangabe - (Bindestrich-Minus), die versucht, so wenig wie möglich Zeichen zu liefern.
  • In "ababab" liefert "a.-b" nur "ab", während "a.*b" die ganze "ababab" ergeben würde.
• Es gibt keine {n,m} für die Anzahl der Zeichen.
• Es gibt keine globale Kennzeichnung für ignorierte Groß- und Kleinschreibung.
• Ein „balancierter Ausdruck“ kann mit %bxy gefunden werden, wobei x und y Zeichen sind. %b() greift beispielsweise, wenn die runden Klammern paarweise auftreten.
• %f[Liste] setzt die Position an jene Grenzstelle, deren vorangehendes Zeichen nicht der Liste entspricht und folgendes Zeichen der Liste entspricht. Dieses Pattern matcht keine Zeichen an sich, sondern die imaginäre leere Zeichenkette zwischen zwei Zeichen.
  • In "DIES (IST) eiN BEIspiel-TEXT." liefert "%f[%a]%u+%f[%A]" alle großgeschriebenen Wörter "DIES", "IST" und "TEXT", während das Muster "%u+" auch "N" und "BEI" zurückgeben würde. Der Grund ist, dass "%f[%a]" den Übergang zwischen Nichtbuchstaben und Buchstaben matcht, d. h. Wortanfänge, "%f[%A]" Übergänge zwischen Buchstaben und Nichtbuchstaben, d. h. Wortenden, und "%u+" verlangt, dass alle diese Buchstaben zwischen Wortanfang bis Wortende Großbuchstaben sind.
• %1 bis %9 muss gleich dem entsprechend nummerierten vorangegangenen Ausdruck in runden Klammern sein.

Gleich ist der Zeichenbereich in eckigen Klammern [Liste] und dessen Negation [^Liste] sowie die Notation A-Z usw. für einen Bereich zwischen zwei Zeichencodes.

Pattern für ASCII

siehe Scribunto (englisch)

Die Zeichen sind in Klassen eingeteilt; jede hat einen Spezifikator. Damit wird jeweils ein ganzer Bereich beschrieben.

Klasse	Bedeutung
x	ist das Zeichen selbst, wenn es nicht eines der Zeichen mit Sonderbedeutung ist: ^$()%.[]*+-?
.	(Punkt) alle Zeichen, einschließlich Zeilenumbruch (!)
%a	alle ASCII-Buchstaben
%c	alle ASCII-Steuerzeichen (nur Tab und Zeilenumbruch im Wikitext)
%d	alle Ziffern
%l	alle ASCII-Kleinbuchstaben
%p	alle Sonderzeichen der Interpunktion
%s	aller ASCII-Whitespace
%u	alle ASCII-Großbuchstaben
%w	alle ASCII-alphanumerischen Zeichen
%x	alle Hexadezimalziffern
%z	ASCII NUL (zero byte) nicht im Wikitext
%A	alle Zeichen nicht in %a
%C	alle Zeichen nicht in %c
%D	alle Zeichen nicht in %d
%L	alle Zeichen nicht in %l
%P	alle Zeichen nicht in %p
%S	alle Zeichen nicht in %s
%U	alle Zeichen nicht in %u
%W	alle Zeichen nicht in %w
%X	alle Zeichen nicht in %x
%Z	alle Zeichen nicht in %z
%x	Wenn x kein alphanumerisches Zeichen ist, ist es das Zeichen x selbst. Somit ist dies der normale Weg, um die Zeichen mit Sonderbedeutung darzustellen. Eine Anwendung auf ein sonstiges Sonderzeichen ist unschädlich.

Pattern für Unicode

siehe Scribunto (englisch)

Der wesentliche Unterschied zu einem ASCII-Pattern ist, dass die Zeichenklassen die Unicode-Eigenschaften wiedergeben.

Klasse	General Category
%a	Letter
%c	Control
%d	Decimal Number
%l	Lowercase Letter
%p	Punctuation
%s	Separator	zuzüglich \t, \n, \r, \v, \f
%u	Uppercase Letter
%w	Letter Decimal Number
%x		zuzüglich vollbreiter Versionen der Hex.

Die Zeichen werden grundsätzlich als Unicode-Zeichen und nicht als Bytes interpretiert. Damit sind Bereiche wie [０-９] oder ein Pattern wie %b«» möglich, und Wiederholungszeichen arbeiten korrekt.

mw.text

siehe Scribunto (englisch)

Eine weitere Hilfsbibliothek durch Scribunto, um kleine Manipulationen an Zeichenketten vornehmen zu können.

Unter „Zeichen“ wird hier Unicode verstanden.

mw.text.decode( s, decodeNamedEntities )

HTML-Entites durch Zeichencodes ersetzen

• Standard: Nur lt, gt, amp, quot, nbsp sowie alle numerischen.
• Optionales decodeNamedEntities bedeutet: Definition gemäß HTML5 verwenden. Über die in HTML4/XHTML hinaus bekannten sind das etliche mehr.

mw.text.encode( s, charset )

Escape für HTML: Zeichencodes durch HTML-Entites ersetzen.

• Standard: '<', '>', '&', '"' und das geschützte Leerzeichen werden ersetzt durch die benannten lt, gt, amp, quot, nbsp. Mögliche weitere Entities sind numerisch.
• Optionales charset ist ein Satz, der geeignet wäre, bei einem pattern in eckigen Klammern zu stehen.
  Vorgabe ist "<>&\"' " mit geschütztem Leerzeichen am Ende.

Siehe auch mw.text.nowiki()

mw.text.jsonDecode( s, flags )

Aus einer Zeichenkette gemäß JSON eine table oder sonstigen Wert generieren.

s ist die Zeichenkette.

flags ist eine optionale number; wenn ungleich 0, dann durch Addition von Konstanten kombiniert:

• mw.text.JSON_PRESERVE_KEYS – Vermeiden, dass die zero-based Arrays in JSON auf Lua sequence tables abgebildet werden: Indizes beibehalten, Zählung bei 0 statt Lua-üblich 1 beginnen.
• mw.text.JSON_TRY_FIXING – Nicht empfohlen: Syntaxbeschränkungen ignorieren; etwa redundantes schließendes Komma in Array oder object.

Beschränkungen durch Lua-Sprachkonzept:

• Wenn ein JSON Array einen Wert null enthält, kann es in Lua keine sequence table werden.
• Werte null in einem JSON object erscheinen nicht.
• Es ist nicht möglich, aus Lua zu entscheiden, ob in JSON ein Array oder object vorgelegen hatte, falls die Elemente durchgängig mit Integer-Schlüsseln bezeichnet wurden.

mw.text.jsonEncode( value, flags )

Zeichenkette gemäß JSON generieren.

value ist ein Wert beliebigen Typs.

flags ist eine optionale number; wenn ungleich 0, dann durch Addition von Konstanten kombiniert:

• mw.text.JSON_PRESERVE_KEYS – Vermeiden, dass die sequence tables in Lua auf zero-based Arrays in JSON abgebildet werden: Indizes beibehalten, Zählung bei 1 statt JS-üblich 0 beginnen.
• mw.text.JSON_PRETTY – pretty printing (formatierte mehrzeilige Darstellung statt kompakter Abfolge).

Beschränkungen durch Lua-Sprachkonzept:

• Eine leere table wird als leeres Array [] und nicht als leeres object {} generiert.
• Um eine sequence table als JSON object abzubilden, muss ein Dummy-Element hinzugefügt werden.
• Eine sequence table mit Schlüsseln ab 0 wird genauso wie eine ab 1 als JSON Array generiert; es sei denn, dass mw.text.JSON_PRESERVE_KEYS angegeben wurde.
• Wenn sowohl numerische Indizes wie auch gleiche Werte als string-Darstellung auftreten, ist das Verhalten nicht vorhersagbar.
• Um ein Array oder object mit einem Wert von nil zu erreichen, ist die metamethod __pairs erforderlich.

mw.text.listToText( list, separator, conjunction )

Alle Elemente einer table aneinanderfügen, ähnlich table.concat().

list ist eine table.

Vorgaben für die optonalen weiteren Parameter sind:

• separator über MediaWiki:comma-separator als Komma und Leerzeichen: »⧼MediaWiki:comma-separator⧽«
• conjuction über MediaWiki:and verbunden mit MediaWiki:word-separator als: »⧼MediaWiki:comma-separator⧽⧼MediaWiki:word-separator⧽«

mw.text.nowiki( s )

Escape für Wikitext: Zeichencodes durch HTML-Entites ersetzen.

• Alle Vorkommen: '"', '&', "'", '<', '=', '>', '[', ']', '{', '|', '}'
• Beginn von s oder unmittelbar nach einem Zeilenumbruch: '#', '*', ':', ';'
• Die „Magischen Wörter“ "//:", "ISBN ", "RFC "

Siehe auch mw.text.encode()

mw.text.split( s, pattern, plain )

Generiere Tabelle (sequence) aus Zeichenkette s durch Segmentierung (Tokenizer).

pattern ist der Ausdruck, der die Elemente voneinander trennt.

• Bei leerer Zeichenkette für pattern wird jedes Zeichen einzeln in die Tabelle geschrieben.

Optionales plain bewirkt die buchstäbliche Suche nach pattern, nicht über die besondere Syntax.

mw.text.gsplit( s, pattern, plain )

Iterator-Funktion für for analog zu mw.text.split()

mw.text.tag( name, attrs, content )

Generiere ein HTML-Tag mit dem Bezeichner name.

• Das optionale, aber oft sinnvolle attrs ist eine table mit den Zuweisungen k=v.
• Wenn das optionale content als Zeichenkette (oder number) angegeben wird, wird das Element auch mit einem end-tag nach content versehen; sonst ist es nur ein start-tag.
• Encoding erfolgt nicht automatisch; sofern wünschenswert und erforderlich, muss es mittels mw.text.encode() geeignet veranlasst werden.
• Bei content =false wird ein unary tag generiert.

Diese Funktion gilt nur für HTML-Tags als bloße Zeichenketten. Ein Tag einer Wiki-Erweiterung wie <ref> muss mit frame:extensionTag() generiert werden; andernfalls würde es nicht wirksam.

Zu einer später entstandenen, umfassenderen Funktionalität siehe mw.html – diese Bibliothek ist im Zweifelsfall votzuziehen und einheitlich darauf umzustellen.

mw.text.trim( s, charset )

Leerzeichen und Zeilenumbruch an Beginn und Ende von s entfernen.

Das optionale charset ist eine Zeichenkette, die zwischen den eckigen Klammern eines pattern als [set] stehen kann.

• Die Vorgabe ist: "\t\r\n\f "

mw.text.truncate( text, length, ellipsis, adjustLength )

Abschneiden der Zeichenkette s auf die Länge length.

Dabei wird an eine abgeschnittene Zeichenkette die Auslassungsmarkierung ellipsis angehängt.

• Wenn length negativ ist, wird der Betrag genommen und der Beginn von s abgeschnitten; sonst das Ende.
• Wenn die optionale ellipsis nicht angegeben ist, wird MediaWiki:ellipsis (also »…«) benutzt. Um nichts anzuhängen, muss explizit eine leere Zeichenkette angegeben werden.

Wenn das optionale adjustLength mit true verwendet wird, ist der Betrag von length die Gesamtlänge einschließlich ellipsis.

mw.text.unstrip( s )

Entfernt die MediaWiki-internen strip markers.

Diese Funktion sollte in der normalen Lua-Programmierung nicht benutzt werden, da mit Bruch zu rechnen ist.

mw.text.unstripNoWiki( s )

mw.text.killMarkers( s )

mw.dumpObject()

mw.dumpObject( table )

Das Objekt table wird in einer menschenfreundlichen Form in eine mehrzeilige Zeichenkette überführt und diese zurückgegeben.

mw.logObject() verwendet dieses Format.