*** /dev/null Wed Apr 17 00:22:10 2024
--- - Wed Apr 17 00:22:37 2024
***************
*** 0 ****
--- 1,175 ----
+ libvar.a
+
+ - Prefix ist "var_", beziehungsweise "VAR_".
+
+ - Eine Variable kann im Text in der Form $name oder ${name} angegeben
+ werden, wobei die Wahl der Klammern '{' '}' und des '$'
+ parametriesiert werden können.
+
+ - Gültige Zeichen für einen Variablennamen sind konfigurierbar.
+ Garbage in -- garbage out.
+
+ - Ein echtes '$'-Zeichen im Text kann durch Voranstellung eines
+ wählbaren Escapezeichen dargestellt werden. Default ist der
+ Backslash ('\').
+
+ - Der Aufrufer der Funktion soll steuern können, wie sich die Library
+ verhält, wenn eine Variable nicht existiert. Denkbar sind:
+
+ - Abbruch mit Fehler,
+ - die Variable wird zu "", oder
+ - der Ausdruck wird unverändert in den Ausgabetext übernommen,
+ sodaß eventuell ein zweiter Pass gemacht werden kann.
+
+ - ${parameter:-word} wird normal expandiert. Wenn "parameter" leer
+ ist, wird stattdessen "word" eingesetzt.
+
+ - ${parameter:+word} substituiert "word" wenn "parameter" nicht leer
+ ist, sonst wird "" substituiert.
+
+ - ${parameter:o<start>-}, ${parameter:o<start>-<end>}
+
+ - ${parameter:o<start>,}, ${parameter:o<start>,<length>}
+
+ - ${parameter:#} expandiert zur Länge des Inhaltes von "parameter".
+
+ - ${parameter:s/pattern/string/[gti]} expandiert "parameter" und
+ führt dann eine Ersetzung mittels des regulären Ausdrucks "pattern"
+ durch. Wird das 'g'-Flag angegeben, wird nicht nur eine Instanz von
+ "pattern" durch "string" ersetzt, sondern alle. Das 't'-Flag
+ signalisiert, daß eine reine Text-Ersetzung ohne Unterstützung von
+ regulären Ausdrücken gewünscht ist. Das 'i'-Flag besagt, daß die
+ Suche nach "pattern" case-insensitiv durchgeführt wird.
+
+ - ${parameter:y/ochars/nchars/} expandiert den Inhalt von "parameter"
+ und transformiert dabei nach dem Prinzip von tr(1) die "ochars" im
+ Text zu "nchars".
+
+ - ${parameter:l} wandelt den Inhalt von "parameter" in
+ Kleinbuchstaben, bevor es die Variable expandiert. Dies geschieht
+ über toupper(3).
+
+ - ${parameter:u} wandelt den Inhalt von "parameter" in
+ Großbuchstaben, bevor es die Variable expandiert. Dies geschieht
+ über tolower(3).
+
+ - ${parameter:*word} expandiert zum leeren Wort, wenn "parameter"
+ nicht leer ist, sonst zu "word".
+
+ - Padding: ${parameter:p/<width>/<string>/<align>} expandiert
+ "parameter" in einen String der Mindestbreite <width>, wobei abhaengig
+ von <align> ("r" = right, "l" = left, "c" = center) noch fehlende
+ Zeichen mit <string> aufgefuellt werden. Diest ist gedacht, um in
+ Templates saubere Tabellen erzeugen zu koennen.
+ Beispiele (foo="bar"):
+ "${foo:p/6/./r}" -> "bar..."
+ "${foo:p/6/./l}" -> "...bar"
+ "${foo:p/6/./c}" -> ".bar.." (oder "..bar.", egal)
+ "${foo:p/20/-=/c}" -> "-=-=-=-=-bar-=-=-=-="
+
+ - Jedes Vorkommen eines der folgenden Konstrukte im Text wird durch
+ das zugehörige Sonderzeichen ersetzt.
+
+ \t tab
+ \n newline
+ \r return
+ \033 octal char
+ \x1B hex char
+ \x{263a} wide hex char
+
+ - Syntax:
+
+ input : ( TEXT | variable )*
+
+ variable : '$' ( name | expression )
+
+ expression : START-DELIM ( name | variable )+ ( ':' command )* END-DELIM
+
+ name : ( VARNAME | SPECIAL1 | SPECIAL2 )+
+
+ command : '-' ( EXPTEXT | variable )+
+ | '+' ( EXPTEXT | variable )+
+ | 'o' ( NUMBER ('-' | ',') ( NUMBER )? )
+ | '#'
+ | '*' ( EXPTEXT | variable )+
+ | 's' '/' ( variable | SUBSTTEXT )+ '/' ( variable | SUBSTTEXT )* '/' ( 'g' | 'i' | 't' )*
+ | 'y' '/' ( variable | SUBSTTEXT )+ '/' ( variable | SUBSTTEXT )* '/'
+ | 'p' '/' NUMBER '/' ( variable | SUBSTTEXT )* '/' ( 'r' | 'l' | 'c' )
+ | 'l'
+ | 'u'
+
+ START-DELIM : '{'
+
+ END-DELIM : '}'
+
+ VARNAME : '[a-zA-Z0-9_]+'
+
+ SPECIAL1 : '['
+
+ SPECIAL2 : ']'
+
+ NUMBER : '[0-9]+'
+
+ SUBSTTEXT : '[^$/]'
+
+ EXPTEXT : '[^$}:]+'
+
+ TEXT : '[^$]+'
+
+ - Doku sollte ein Beispiel für Quoting von Shell- und
+ Regexp-Ausdrücken enthalten.
+
+ - Wir unterstützen PCRE-, POSIX-Regex- oder keine regulären
+ Ausdrücke. Dies kann über autoconf zur Compilezeit angegeben
+ werden.
+
+ - Das Escaping-Problem:
+
+ Unsere Library macht zwei Dinge:
+
+ (1) Sie expandiert Variablen-Ausdrücke mit Unterstützung von
+ Operationen wie Suchen/Ersetzen, und
+
+ (2) sie expandiert sogenannte "quoted pairs", wie zum Beispiel \n.
+
+ Das Problem ist nun, daß sie dies in zwei Pässen tun will -- und muß.
+ Die Frage ist jedoch, in welcher Reihenfolge tut sie es und welche
+ Ergebnisse werden in den Ausgabetext ausgegeben? Betrachtet man
+ folgendes Beispiel, wird das Problem klarer:
+
+ Variablen: TEST = foo
+ Eingabe..: Der Betrag auf Konto $TEST ist \$50.
+
+ Soll die korrekte Ausgabe an dieser Stelle nun
+
+ Der Betrag auf Konto foo ist \$50.
+
+ oder
+
+ Der Betrag auf Konto foo ist $50.
+
+ sein? Die erste Form ist die, die man intuitiv erwartet, die zweite
+ Form ist jedoch die, die man braucht, wenn man den Text durch mehrere
+ Pässe jagen will -- was wir ausdrücklich vorgesehen haben.
+
+ Schlimmer noch: Wie soll die Library die Eingabe
+
+ Der Betrag auf Konto ${TEST:s/(.*)/\1bar/} ist \$50.
+
+ interpretieren? Würde unser Parser das Token "\1" interpretieren,
+ würde nur eine "1" zurückbleiben, der Benutzer müßte also "\\1"
+ schreiben, um das Ergebnis zu erhalten, was er erwartet.
+ Interpretierte unser Parser die "quoted pairs" nicht, könnte man den
+ Ausdruck
+
+ ${TEST:s/\n/ /g}
+
+ nicht verwenden, weil die Regular-Expression-Funktionen ein '\n' nicht
+ kennen.
+
+ Nehmen wir also an, wir interpretieren "quoted pairs" und leben damit,
+ daß der Benutzer dann doppelt escapen muß ... Wie verhält sich das
+ dann mit mehreren Pässen? Läuft die Library zweimal über die Eingabe,
+ bräuchte man bereits
+
+ Der Betrag auf Konto ${TEST:s/(.*)/\\1bar/} ist \$50.
|
