Update doc/efun/ aus Driversourcen.
Manpages der efuns aktualisiert, neue Manpages hinzugefuegt.
Change-Id: I7cc91684269ff56d1aef47d5c5e7c87f7fd531dc
diff --git a/doc/efun/terminal_colour b/doc/efun/terminal_colour
index 4d51a33..13976a2 100644
--- a/doc/efun/terminal_colour
+++ b/doc/efun/terminal_colour
@@ -1,67 +1,64 @@
SYNOPSIS
- varargs string terminal_colour(string str,
- null | mapping | closure map,
+ varargs string terminal_colour(string str, null|mapping|closure map,
int wrap, int indent)
-BESCHREIBUNG
- Ist <map> ein Wert ungleich 0, ersetzt diese Efun alle Farb-
- Definitionen der Form "%^KEY%^" (siehe unten fuer Details) im
- String <str> und ersetzt sie durch die entsprechenden Werte aus dem
- unter <map> angegebenen Farbschluessel.
- Ist <map> ein Mapping, muessen die Eintraege das Format
- "KEY" : "wert" haben; Eintraege, die keine Strings enthalten,
- werden ignoriert. Einzige Ausnahme dazu: enthaelt <map> einen
- Eintrag der Form 0:wert, wird dieser fuer alle Farbdefinitionen
- verwendet, die keinem anderen Schluessel zugeordnet werden koennen.
- <wert> kann in diesem Fall ein String oder eine Closure sein. Handelt
- es sich um eine Closure, erhaelt diese den <KEY> als Argument und
- muss einen String zurueck liefern, der <KEY> ersetzt.
+DESCRIPTION
+ If <map> is given as a non-0 value, this efun expands all
+ colour-defines of the form "%^KEY%^" (see below for details) from the
+ input-string and replaces them by the apropriate values found
+ for the color-key specified by <map>.
- Ist <map> eine Closure, wird diese mit den Farbdefinitionen <KEY>
- als Argument aufgerufen und muss einen String zurueck liefern, der
- die <KEY>s ersetzt.
+ If <map> is a mapping, the entries queries have the
+ format "KEY" : "value", non-string contents are ignored with one
+ exception: if the mapping contains an entry 0:value, it is used
+ for all otherwise unrecognized keys. The value in this case can be
+ a string, or a closure. If it is a closure, it takes the key as
+ argument and has to return the replacement string.
- Die speziellen Schluessel "%^%^" und "%%^^" werden immer durch das
- Literal "%^" ersetzt.
+ If <map> is given as a closure, it is called with the KEYs to
+ replace, and has to return the replacement string.
- Die Parameter <wrap> und <indent> sind optional. Ist nur <wrap>
- angegeben, wird <str> in der Spalte <wrap> umgebrochen. Ist
- zusaetzlich <indent> angegeben, werden alle umgebrochenen Zeilen
- um <indent> Spalten eingerueckt.
+ The special keys "%^%^" and "%%^^" are always replaced with the
+ literal "%^".
- Der Zeilenumbruch ignoriert die Laenge der Farbmakros und ihrer
- Inhalte. Er bricht <str> anhand der Laenge der uebrigen Zeichen
- um, ist also farb-neutral.
+ The parameters wrap and indent are both optional, if only wrap is
+ given then the str will be linewrapped at the column given with
+ wrap. If indent is given too, then all wrapped lines will be
+ indented with the number of blanks specified with indent.
- Ist <map> als 0 angegeben, fuehrt die Efun kein Suchen und Ersetzen
- von Farbdefinitionen durch. Die Funktionalitaet von Zeilenumbruch
- und Einrueckung bleiben erhalten, wenn gewuenscht. Auf diese Weise
- dupliziert terminal_colour() die Funktion von sprintf("%-=s") und
- wirkt als einfache Zeilenumbruch Funktion.
+ The wrapper itself ignores the length of the color macros and that
+ what they contain, it wraps the string based on the length of the
+ other chars inside. Therefore it is color-aware.
+
+ If <map> is given as 0, the efun does no colour-define detection
+ and replacement at all, but still does linewrapping and indentation
+ if requested. This way terminal_colour() doubles as a simple
+ line wrapping function, duplicating the functionality also
+ provided by sprintf("%-=s").
- ERKENNEN VON FARBDEFINITIONEN
+ KEY RECOGNITION STRATEGY
- Wie bereits erwaehnt, werden die speziellen Schluessel "%^%^" und
- "%%^^" durch das Literal "%^" ersetzt und spielen im Weiteren
- keine Rolle.
+ As mentioned above, the special keys "%^%^" and "%%^^" are always
+ replaced with the literal "%^" and play no role in the following
+ considerations.
- Fuer den Eingabestring wird das folgende Format vorausgesetzt:
+ The input string is supposed to follow this syntax:
- text { '%^' colorkey '%^' text } [ '%^' colorkey ]
+ text { '%^' colorkey '%^' text } [ '%^' colorkey ]
- Oder in Worten: die Efun trennt den String bei jedem '%^', das
- sie antrifft und behandelt anschliessend jeden zweiten Teilstring
- als Farbschluessel.
+ or in words: the efun splits up the string at every '%^' it finds
+ and then treats every second substring as color key.
- Merke: dieses Verhalten unterscheidet sich von der Behandlung des
- Eingabestrings unter MudOS. Dort lautet die Syntax:
- key_oder_text { '%^' key_oder_text }
+ Note that this is different from the way MudOS treats the
+ input string. MudOS uses this syntax:
- Oder in Worten: die MudOS Efun trennt den String bei jedem '%^'
- und versucht dann jeden Teilstring als Farbschluessel zu behandeln.
- Dieses Verhalten laesst sich auch unter LPC erreichen:
+ key_or_text { '%^' key_or_text }
+
+ or in words: the MudOS efun splits the string at every '%^' and
+ then tries to treat every substring as color key. One can achieve
+ the MudOS behaviour with this LPC function:
string mudos_terminal_colour(string str, mapping ext, int w, int i) {
return terminal_colour("%^"+implode(explode(str, "%^")-({""})
@@ -69,8 +66,7 @@
, ext, w, i);
}
-
-BEISPIELE
+EXAMPLES
mapping trans;
string str;
@@ -78,49 +74,43 @@
str = terminal_colour( "%^GREEN%^ and %^RED%^ and %^BLUE%^", trans );
- Dies fuehrt zu str == "ansi-green and and BLUE".
+ This will result in str == "ansi-green and and BLUE"
- "%^GREEN^%" wird ersetzt durch "ansi-green", weil <trans> das so
- definiert,
- "%^RED%^" wird aus <str> entfernt, weil es mit "" ersetzt wird, und
- "%^BLUE%^" wird um die "%^" verkuert, weil der Eintrag zu BLUE in
- <trans> keinen gueltigen Wert enthaelt (d.h. kein String ist). Das
- selbe wuerde passieren, wenn <str> "%^DEFINE%^" enthalten wuerde,
- zu dem es keinen Eintrag in <trans> gibt.
+ %^GREEN%^ is expanded to ansi-green because trans defines that,
+ %^RED%^ is stripped because trans defines that as "" and
+ %^BLUE%^ gets the %^'s removed because the contents of trans are
+ not valid (i.e. no string). The same would happen to %^DEFINES%^
+ where the key is not found inside the trans mapping.
- Merke: um direkt benachbarte Schluessel zu ersetzen, soll die
- Efun wie folgt verwendet werden:
+ Caveat: to replace adjacent keys, use the efun like this:
str = terminal_colour( "%^GREEN%^%^RED%^", trans );
- Eine Eingabe der Form
+ A command like
str = terminal_colour( "%^GREEN%^RED%^", trans );
- fuehrt zum logischen, aber vielleicht unerwarteten Ergebnis
- "ansi-greenRED".
+ will return the logical but sometimes unexpected "ansi-greenRED".
- Einige Worte zum Zeilenumbruch:
+ Some words about wrapping:
- Ein String, der ohne Einrueckung umgebrochen wird (<indent> ist 0),
- sieht so aus:
+ a string wrapped without indent would look like this:
- "dies ist die erste Zeile\nund dies ist die zweite Zeile"
+ "this is the first line\nand this is the second line"
- Ein String, der mit <indent> 3 umgebrochen wird, sieht so aus:
+ a string wrapped with indent 3 would look like:
- "dies ist die erste Zeile\n und dies ist die zweite Zeile"
+ "this is the first line\n and this is the indented second one"
-GESCHICHTE
- Die Idee fuer diese Efun und die erste Implementierung stammen
- aus MudOS; die Strategie fuer das Erkennen von Schluesseln
- (eingeschlossen die pure Zeilenumbruch Funktion) wurde in
- LDMud 3.2.8 geglaettet.
- LDMud 3.2.9 fuegte die Verwendung von Closures zur Definition
- von Farbschluesseln hinzu. Es erklaerte zudem offiziell das
- Verhalten betreffen "%%^^" aus Gruenden besserer Kompatibilitaet
- mit MudOS.
+HISTORY
+ Efun idea and initial implementation taken from MudOS; the key
+ recognition strategy (including pure wrapping mode) was straightened
+ out in LDMud 3.2.8.
+ LDMud 3.2.9/3.3.58 added the use of closures to specify the colour
+ mappings.
+ LDMud 3.2.9/3.3.102 officialized the "%%^^" replacement pattern for
+ better MudOS compatibility.
-SIEHE AUCH
+SEE ALSO
sprintf(E)