From the NannyMUD documentation

LAST CHANGE

2002-07-03

NAME

        msg - Object for generating messages to a specified audience from one string.

LOCATION

        /std/msg.c

FUNCTIONS

OTHER FUNCTIONS

        msg - generates and displays appropriate messages for each 
              specified audience

        fix_msg - generates a message for a specific person.

DESCRIPTION

        Normally you would use the function msg() to display messages. If
        you need the message string to be returned rather than displayed, 
        use fix_msg() instead. Inheritance should only be used when the
        inheriting objects will use msg() or fix_msg() profusely.

FUNCTION

NAME
        msg - Generates and displays messages to a specified audience.


LOCATION
        /std/msg.c

SYNTAX
        varargs void msg(string message,
                         mixed first, mixed second, mixed third,
                         int echo);

DESCRIPTION
        This is a function that generates and displays messages to players.
        The messages will be automatically line-broken if there are no
        trailing '\n'. The message string is modified to grammatically fit 
        each person; this is done through tags. The tags will be replaced 
        with the appropriate parts of speech and then displayed to the player.

        The tags have the following format:

           \b

         specifies which person - 1 for first person, 2 for second
        person and 3 for third person. This corresponds to the function 
        arguments first, second and third. If  isn't specified, it 
        defaults to 1.

        The identifiers are as follows:

        OBJ     Adds the approppriate proper noun or reflexive pronoun of 
                the object.
                i.e. Mami, yourself, himself, herself, itself, yourselves
                     or themselves.

        obj     Adds the appropriate object pronoun or reflexive pronoun.
                i.e. you, him, her, it, them, yourself, himself, herself,
                     itself, yourselves or themselves.

        POSS    Possession. Adds the appropriate genitive.
                i.e. Banshee's, Mats', etc.

        poss    Adds the appropriate possessive adjective.
                i.e. your, his, her, its or their.

        PRON    Adds the appropriate proper noun(s).
                i.e. Mami, Gabe, Brom, etc.

        pron    Adds the appropriate subject pronoun.
                i.e. you, he, she, it or they.

        is      Adds 'is' for third person singular.
                Adds 'are' for others.

        $$      Adds an 'es' to verbs for third person singular.

        $       Adds an 's' to verbs for third person singular.

        {a|b}   'a' will be displayed to the specified person and 
                'b' for all others

        Modifiers are as follows:

        cap     The result of the tag will be capitalized.
                Note:  Names are automatically capitalized, so the 'cap'
                       modifier should only be used at the beginning of 
                       a sentence.
                
        fix     The result of the tag will be the same regardless of who
                the audience is.
                i.e. "\bfixOBJ" will give the name of the first person to all
                     persons involved, including the first person who would
                     have seen 'you' otherwise.

        new     This notifies msg that the subject of the clause has changed
                - it is no longer the subject assigned by 'PRON' or 'pron'. 
                The result of the tag, when used with the identifier 'obj', 
                will always return the objective pronoun rather than the 
                reflexive.
                i.e. "\bnewobj" will always return you, him, her, it or them.
                Note:  If you find yourself using this modifier profusely,
                       maybe you are using 'obj' and 'pron' in the wrong way.

        Different messages can also be displayed to the first, second and 
        third persons by using one or two \b| separators. If only one \b|
        separator is used, the second string is displayed to both second and
        third persons. It should be written in the following format:

           "1st person msg\b|2nd person msg\b|3rd person msg"

        The arguments 'first', 'second' and 'third' are used to specify who is
        in each person. They can be an object, an array of objects or 0.  

        The argument 'first' defaults to this_player() if it is not specified.

        The argument 'second' defaults to ({}) if it is not specified.

        The argument 'third' defaults to everyone and everything else in 
        the room.

        The argument 'echo', if set, will display the message to all persons
        if the message does not contain any tags. Otherwise, it is only 
        displayed to the first person.


NOTE
        Third person tags should generally not be used, unless you know what
        you are doing.


EXAMPLE
        "/std/msg" -> msg("\bPRON \bis smiling happily.");


EXAMPLE
        "/std/msg" -> msg("\bPRON kiss\b$$ \b2OBJ.", 0, target);


EXAMPLE
        "/std/msg" -> msg("\bPRON chant\b$ \b{the holy|a strange} prayer.");


EXAMPLE
        "/std/msg" -> msg("\bPRON slap\b$ \b2POSS hand.", 0, target);


EXAMPLE
        "/std/msg" -> msg("\bPRON smile and think evil thoughts." +
                          "\b|\bPRON smiles.");


SEE ALSO
        msg.examples in std/text/msg.examples




FUNCTION

NAME
        fix_msg - Generates a message for a specific person.


LOCATION
        /std/msg.c

SYNTAX
        string fix_msg(string message, mixed *persons, object active);

DESCRIPTION
        This is a function used by msg(). The 'message' argument uses the same
        tags as the 'message' argument for msg() except for the \b| separators.
        
        The second argument 'persons' is an array of arrays of objects, with 
        persons[0] containing the first person(s), persons[1] containing the
        second person(s) and person[2] containing the third person(s). 
        
        The third argument active is the person for which the message should 
        be generated.
        
        The generated message will be returned.
EXAMPLE
        An example of the usage of fix_msg() can be found in the function 
        extra_look in /std/basic_thing.c:

        string extra_look() {
          string s;
          if(stringp(s = query_property("__extra_look")) && 
             sscanf(s, "%*s\b")) {
            return "/std/msg" -> fix_msg(s, ({ ({ environment() }) - ({ 0 }),
                                               ({ this_player() }) - ({ 0 }),
                                               ({}) }), this_player());
          }
          return s;
        }