SYNOPSIS
        varargs string terminal_colour(string str, null|mapping|closure map,
                                       int wrap, int indent)

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>.

        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.

        If <map> 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 <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").


        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)