SYNOPSIS varargs string terminal_colour( string str , null|mapping|closure map , int wrap, int indent ) DESCRIPTION If 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 . If 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. If is given as a closure, it is called with the KEYs to replace, and has to return the replacement string. The special keys "%^%^" and "%%^^" are always replaced with the literal "%^". 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. 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 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"). KEY RECOGNITION STRATEGY As mentioned above, the special keys "%^%^" and "%%^^" are always replaced with the literal "%^" and play no role in the following considerations. The input string is supposed to follow this syntax: text { '%^' colorkey '%^' text } [ '%^' colorkey ] or in words: the efun splits up the string at every '%^' it finds and then treats every second substring as color key. Note that this is different from the way MudOS treats the input string. MudOS uses this syntax: 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, "%^")-({""}) ,"%^%^") , ext, w, i); } EXAMPLES mapping trans; string str; trans = ([ "GREEN" : "ansi-green", "RED" : "", "BLUE" : 1 ]); str = terminal_colour( "%^GREEN%^ and %^RED%^ and %^BLUE%^", trans ); This will result in str == "ansi-green and and BLUE" %^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. Caveat: to replace adjacent keys, use the efun like this: str = terminal_colour( "%^GREEN%^%^RED%^", trans ); A command like str = terminal_colour( "%^GREEN%^RED%^", trans ); will return the logical but sometimes unexpected "ansi-greenRED". Some words about wrapping: a string wrapped without indent would look like this: "this is the first line\nand this is the second line" a string wrapped with indent 3 would look like: "this is the first line\n and this is the indented second one" 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. SEE ALSO sprintf(E)