blob: 6cd1bce8bb8b069237e361c164abbc75223df5c9 [file] [log] [blame]
MG Mud User88f12472016-06-24 23:31:02 +02001SYNOPSIS
2 varargs string terminal_colour(string str,
3 null | mapping | closure map,
4 int wrap, int indent);
5BESCHREIBUNG
6 Ist <map> ein Wert ungleich 0, ersetzt diese Efun alle Farb-
7 Definitionen der Form "%^KEY%^" (siehe unten fuer Details) im
8 String <str> und ersetzt sie durch die entsprechenden Werte aus dem
9 unter <map> angegebenen Farbschluessel.
10
11 Ist <map> ein Mapping, muessen die Eintraege das Format
12 "KEY" : "wert" haben; Eintraege, die keine Strings enthalten,
13 werden ignoriert. Einzige Ausnahme dazu: enthaelt <map> einen
14 Eintrag der Form 0:wert, wird dieser fuer alle Farbdefinitionen
15 verwendet, die keinem anderen Schluessel zugeordnet werden koennen.
16 <wert> kann in diesem Fall ein String oder eine Closure sein. Handelt
17 es sich um eine Closure, erhaelt diese den <KEY> als Argument und
18 muss einen String zurueck liefern, der <KEY> ersetzt.
19
20 Ist <map> eine Closure, wird diese mit den Farbdefinitionen <KEY>
21 als Argument aufgerufen und muss einen String zurueck liefern, der
22 die <KEY>s ersetzt.
23
24 Die speziellen Schluessel "%^%^" und "%%^^" werden immer durch das
25 Literal "%^" ersetzt.
26
27 Die Parameter <wrap> und <indent> sind optional. Ist nur <wrap>
28 angegeben, wird <str> in der Spalte <wrap> umgebrochen. Ist
29 zusaetzlich <indent> angegeben, werden alle umgebrochenen Zeilen
30 um <indent> Spalten eingerueckt.
31
32 Der Zeilenumbruch ignoriert die Laenge der Farbmakros und ihrer
33 Inhalte. Er bricht <str> anhand der Laenge der uebrigen Zeichen
34 um, ist also farb-neutral.
35
36 Ist <map> als 0 angegeben, fuehrt die Efun kein Suchen und Ersetzen
37 von Farbdefinitionen durch. Die Funktionalitaet von Zeilenumbruch
38 und Einrueckung bleiben erhalten, wenn gewuenscht. Auf diese Weise
39 dupliziert terminal_colour() die Funktion von sprintf("%-=s") und
40 wirkt als einfache Zeilenumbruch Funktion.
41
42
43 ERKENNEN VON FARBDEFINITIONEN
44
45 Wie bereits erwaehnt, werden die speziellen Schluessel "%^%^" und
46 "%%^^" durch das Literal "%^" ersetzt und spielen im Weiteren
47 keine Rolle.
48
49 Fuer den Eingabestring wird das folgende Format vorausgesetzt:
50
51 text { '%^' colorkey '%^' text } [ '%^' colorkey ]
52
53 Oder in Worten: die Efun trennt den String bei jedem '%^', das
54 sie antrifft und behandelt anschliessend jeden zweiten Teilstring
55 als Farbschluessel.
56
57 Merke: dieses Verhalten unterscheidet sich von der Behandlung des
58 Eingabestrings unter MudOS. Dort lautet die Syntax:
59
60 key_oder_text { '%^' key_oder_text }
61
62 Oder in Worten: die MudOS Efun trennt den String bei jedem '%^'
63 und versucht dann jeden Teilstring als Farbschluessel zu behandeln.
64 Dieses Verhalten laesst sich auch unter LPC erreichen:
65
66 string mudos_terminal_colour(string str, mapping ext, int w, int i)
67 {
68 return terminal_colour("%^"+implode(explode(str, "%^")-({""})
69 ,"%^%^")
70 , ext, w, i);
71 }
72
73
74BEISPIELE
75 mapping trans;
76 string str;
77
78 trans = ([ "GREEN" : "ansi-green", "RED" : "", "BLUE" : 1 ]);
79
80 str = terminal_colour( "%^GREEN%^ and %^RED%^ and %^BLUE%^", trans );
81
82 Dies fuehrt zu str == "ansi-green and and BLUE".
83
84 "%^GREEN^%" wird ersetzt durch "ansi-green", weil <trans> das so
85 definiert,
86 "%^RED%^" wird aus <str> entfernt, weil es mit "" ersetzt wird, und
87 "%^BLUE%^" wird um die "%^" verkuert, weil der Eintrag zu BLUE in
88 <trans> keinen gueltigen Wert enthaelt (d.h. kein String ist). Das
89 selbe wuerde passieren, wenn <str> "%^DEFINE%^" enthalten wuerde,
90 zu dem es keinen Eintrag in <trans> gibt.
91
92 Merke: um direkt benachbarte Schluessel zu ersetzen, soll die
93 Efun wie folgt verwendet werden:
94
95 str = terminal_colour( "%^GREEN%^%^RED%^", trans );
96
97 Eine Eingabe der Form
98
99 str = terminal_colour( "%^GREEN%^RED%^", trans );
100
101 fuehrt zum logischen, aber vielleicht unerwarteten Ergebnis
102 "ansi-greenRED".
103
104
105 Einige Worte zum Zeilenumbruch:
106
107 Ein String, der ohne Einrueckung umgebrochen wird (<indent> ist 0),
108 sieht so aus:
109
110 "dies ist die erste Zeile\nund dies ist die zweite Zeile"
111
112 Ein String, der mit <indent> 3 umgebrochen wird, sieht so aus:
113
114 "dies ist die erste Zeile\n und dies ist die zweite Zeile"
115
116AENDERUNGEN
117 Die Idee fuer diese Efun und die erste Implementierung stammen
118 aus MudOS; die Strategie fuer das Erkennen von Schluesseln
119 (eingeschlossen die pure Zeilenumbruch Funktion) wurde in
120 LDMud 3.2.8 geglaettet.
121 LDMud 3.2.9 fuegte die Verwendung von Closures zur Definition
122 von Farbschluesseln hinzu. Es erklaerte zudem offiziell das
123 Verhalten betreffen "%%^^" aus Gruenden besserer Kompatibilitaet
124 mit MudOS.
125
126SIEHE AUCH
127 sprintf(E)