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.