Man message

From LSWiki

(Difference between revisions)

Revision as of 00:45, 3 November 2011

message - advanced multipurpose messaging protocol

1 SYNOPSIS
2 FILES
3 DESCRIPTION
4 EXAMPLES
5 HISTORICAL
6 SEE ALSO

SYNOPSIS

void message(mixed spec);
varargs void message(mixed array msg, object array exclude,
    object array targets, closure filter);

FILES

/mod/basic/messaging.c
/def/descriptor/message.c
/lib/descriptors/message.h
/lib/msg.h

DESCRIPTION

The function message() provides a multipurpose, flexible, expandable protocol for delivery of a point-of-view oriented event message to a selection of targets. It should be called in the object which the message should "originate" from; this is somewhat arbitrary, but allows certain convenient shorthand notations to be used. This object will henceforth be referred to as the originator.

Descriptor

In its basic form, the first argument to message() is a message descriptor specification, as defined by /def/descriptor/message.c.

Message_Content

The core of the message, an array of various values that define the message to be delivered. This is the only field that is required; all others are optional. If an array is sent as the message specification, it will be interpreted as a Message_Content field (rather than each element of the array being interpreted as a different descriptor field).

Message_Exclude

May be used to specify exclusion of objects from receiving the message. This can be a closure (which will be called with the object in question as argument), an object (that specific object should be excluded), an array (objects in the array should be excluded), or a mapping (objects that exist as keys in the array should be excluded). Flags like Message_Flag_Exclude_Source should be preferred to this option, if they are applicable to your situation.

Message_Targets

May be used to specify explicitly what objects should receive the message, rather than relying on the default behavior (see below). This can be an object (meaning only that object should receive the message; normally there are better ways of doing this, such as passing the message to display() in that object) or an array of objects (specifying the objects to send to).

The default set of objects to receive a message is the contents of the originator's environment, plus the environment itself, unless the originator has the invisibility flag Invis_Actions, in which case the default is all object variables present at any level in Message_Content.

Message_Filter

May be used to define a filter that can determine whether a given object should receive the message. This can be a closure call descriptor or condition descriptor (which will be called with the object in question as argument), an object (meaning only that object should receive the message; normally there are better ways of doing this), an array (only objects in the array should receive the message), or a mapping (only objects that exist as keys in the mapping should receive the message).

Message_Flags

May be used to specify flags that affect the message system's behavior for this message. The list is beyond this document's scope at present.

Message_Senses

May be used to specify sensory flags that constitute the senses that must be operational in order to perceive the message, such as Message_Sense_Visual.

Message_Alternate

May be used to specify an alternate message that may be delivered if the main message cannot be delivered due to Message_Senses. This is a complete message descriptor in itself.

Backwards Compatibility

Alternately, the backward-compatibility four-argument form may be used. In this case, the first argument specifies Message_Content, the second specifies Message_Exclude, the third Message_Targets, and the fourth Message_Filter.

Message Interpretation

message() operates by broadcasting the message descriptor to all its targets through the function receive_message(). In each individual target, the various elements of the message are converted to the appropriate representational string and joined together; i.e. an object configured as a ring might be converted to "brass ring" or "ring of warmth" according to how the target recognizes it.

An element of a list may be:

Zero

This will be replaced with the originator and evaluated as per an object.

A string

The string will be used as-is in the final message.

An object

The object will be converted to a string identifier based on the

object's query_name(); an article (a, an, or the) or possessive (your)

will be applied if appropriate.

A closure

The closure will be evaluated with no arguments passed. It is

expected to return a string or zero (zero will be interpreted

as a no-op); failure to do so will cause errors.

A nonzero integer
- The integer will be interpreted as a special code, usually a control code that affects subsequent list elements. Valid codes are as follows. The raw form is to the left, readability macro from msg.h to the right.

'a' Msg_Ctl_A_Next
Apply a() to the following element.
'b' Msg_Ctl_Sentence_Break
Interpret a sentence break at the current position, including applying terminal punctuation to the preceding word (if there is any and Message_Flag_Suppress_Punctuation is not on), Capitalizing the following word (unless Messsage_Flag_Suppress_Capitalization is on), and causing there to be two spaces between the sentences. This is not needed at the end of the message; it's for when you need to have a sentence break inside the message. (Please also consider issuing two separate messages instead of doing this.)
'c' Msg_Ctl_Capitalize_Next
Apply capitalize() to the following element.
'i' Msg_Ctl_Interpolate_Next
If the following element is an array, and is not a call, description, message, abstract item, identity, or manipulator descriptor, interpolate it into the message as if it had been added to the message array rather than embedded in it. 'i' will also work if the following element is a closure or call descriptor that returns an array. (Array contents of description descriptors are always interpolated.)
'j' Msg_Ctl_Join_Next
Join together the following two elements without inserting a space between them.
'n' Msg_Ctl_No_Op
Ignore this element, as if it were not present; useful in conditional construction of messages. Embedding an empty string achieves the same effect.
'p' Msg_Ctl_Pluralize_Next
Apply pluralize() to the following element.
's' Msg_Ctl_Singularize_Next
Apply singularize() to the following element.
'v' Msg_Viewer
Indicates the viewer. In basic message construction, this would be the same as using 0. Some contexts of message use, such as descriptions, process zeroes into references to the object described, however. Using 'v' allows messages defined in these contexts to refer to the eventual viewer.
'w' Msg_Ctl_Capitalize_Words_Next
Apply capitalize_words() to the following element.

An array

The array must contain either two or three elements, the first of which must be a string or an integer. The second and third elements may be an object, a string, an array, or 0; 0 will be converted to the originator.

If the first element is a string, it will be treated as a verb being performed by the second element, which should be an object or an array of objects. So ({ "beep", 0 }) specifies that the message originator is "beeping"; the originator will see "beep", others will see "beeps". If you are using msg.h readability macros, you can write this as Msg_Verb("beep", 0).

As a special case related to the 'v' / Msg_Viewer code above, if any array element after the first is 'v', it will be converted to the viewer. This serves the same purpose as the 'v' code outside of arrays.

If the first element is an integer, it will be interpreted as a special command code based on its character value, according to the following table. For each entry, its readability macro form from msg.h is listed on the line following the "raw" form.

 ({ 'a', obj })                                                 "an orc"
 Msg_A(obj)
 
     The second element will be affected as by the function a();
     i.e. ({ 'a', autonomon }) will be converted into a string
     along the lines of "an orc", "a troll", or "Bob"

 ({ 'b', obj, limbs })                        "head, left arm and hands"
 Msg_Limbs(obj)
 
     A description of one or more limbs, indicated by array of indices,
     of the second element, as they appear to the viewer.  This
     description is obtained from query_limbs_description().  If a
     fourth element is supplied, it will be used as message listing
     flags, the only one of which is relevant to the context is
     Message_Listing_Flag_Combat_Limb_Name.  Note: this is provided
     strictly for the case where you need to describe a set of limbs
     without a proximate indication of who they belong to.  If something
     like "his head" or "Bob's head" is what you're looking for, use
     'r' or 's', below.

 ({ 'c', obj })                                                    "orc"
 Msg_Race(obj)

     The race of the second element, which must be an object, as
     apparent to the viewer.  If the second element has no race,
     "object" will be produced.

 ({ 'd', room, Direction_North })             "north" / "from the south"
 Msg_Direction(room, Direction_North)

     Third element expressed as a direction originating within
     the second element; i.e. ({ 'd', room, "north" }) will
     produce "north" for those in 'room' and "from the south"
     for those elsewhere.

 ({ 'e', obj })                   "a sword" / "the sword" / "your sword"
 Msg_Article_Pron(obj)

     Second element affected as by one(), unless it is not near the
     viewer, in which case it is affected as by a(), or it is in the
     viewer's inventory, in which case it is affected as by article()
     with a second argument of "your"

 ({ 'f', obj })                                  "a sword" / "the sword"
 Msg_Article(obj)

     Second element affected as by one(), unless it is not near the
     viewer, in which case it is affected as by a()

 ({ 'h', list })                           "a sword, an axe and a shield"
 ({ 'h', list, "or" })                     "a sword, an axe or a shield"
 Msg_Unique_List(list)

     Unique array-listing form of the second element, which must be an
     array.  Any objects will be converted to strings, duplicates will
     be eliminated, and list_array() will be applied to the result.  If
     a third element is supplied, this will become the conjunction used
     by list_array().  If a fourth element is supplied, it will be used
     as identity query flags for resolving the names of the list
     elements.

 ({ 'i', list })                  "a sword, a sword, an axe and a shield"
 ({ 'i', list, "or" })            "a sword, a sword, an axe or a shield"
 Msg_Indiv_List(list)
 Msg_Indiv_List(list, "or")

     Array-listing form of the second element, which must be an
     array.  Any objects will be converted to strings and list_array()
     will be applied to the result.  If a third element is supplied,
     this will become the conjunction used by list_array().  If a fourth
     element is supplied, it will be used as identity query flags for
     resolving the names of the list elements.  If a fifth element is
     supplied, it will be interpreted as message listing flags.

 ({ 'j', list })               "a couple of swords, an axe and a shield"
 Msg_Group_List(list)

     Item-listing form of the second element, which must be an
     array.  /daemon/item_listing's functionality will be will be
     applied to the list.  If a third element is supplied, it will be
     used as identity query flags for resolving the names of the list
     elements.  If a fourth element is supplied, it will be used as
     listing flags; Listing_Flag_Include_Viewer is always turned on.

 ({ 'l', obj })                       "himself" / "herself" / "yourself"
 Msg_Refl_Pron(obj)

     Reflexive pronoun of the second element (himself, herself,
     yourself, etc)

 ({ 'm', obj })                                 "his" / "hers" / "yours"
 Msg_Poss_Adj_Pron(obj)

     Possessive-adjective pronoun of the second element (his, hers,
     yours, etc)

 ({ 'n', obj })                                                    "orc"
 Msg_Name(obj)

     The literal name of the second element, i.e. "orc", "troll", "Bob"

 ({ 'N', obj })                                                    "orc"
 Msg_Conv_Name(obj)

     The conversational name of the second element, i.e. "anthrope",
     "human", "Bob"

 ({ 'o', obj })                    "him" / "her" / "it" / "them" / "you"
 ({ 'o', obj, Identity_Query_Flag_Indicative_Case })
                                   "him" / "her" / "that" / "those" / "you"
 Msg_Obj_Pron(obj)
 Msg_Obj_Pron(obj, Identity_Query_Flag_Indicative_Case)

     Objective pronoun of the second element (him, her, etc).  The
     third element may contain identity query flags; if they include
     Identity_Query_Flag_Indicative_Case, the objective indicative
     pronoun ('that' rather than 'it', 'those' rather than 'them') is
     used.

 ({ 'p', obj })                     "he" / "she" / "it" / "they" / "you"
 ({ 'p', obj, Identity_Query_Flag_Indicative_Case })
                                    "he" / "she" / "that" / "those" / "you"
 Msg_Subj_Pron(obj)
 Msg_Subj_Pron(obj, Identity_Query_Flag_Indicative_Case)

     Subjective pronoun of the second element (he, she, etc).  The
     third element may contain identity query flags; if they include
     Identity_Query_Flag_Indicative_Case, the subjective indicative
     pronoun ('that' rather than 'it', 'those' rather than 'they')
     is used.

 ({ 'q', obj })                                   "his" / "her" / "your"
 Msg_Poss_Pron(obj)

     Possessive pronoun of the second element (his, her, etc).  This
     is ALMOST NEVER appropriate to use; use 'r' instead whenever
     possible.

 ({ 'r', who, obj })                          "his sword" / "your knife"
 ({ 'r', who, list })                              "his sword and knife"
 Msg_Pron_Has(who, obj)
 Msg_Pron_Has(who, list)

     Indefinite possessive form of the third element with respect
     to the second element; i.e. ({ 'r', 0, weapon }) will produce
     "his sword", "her knife", "Heavensfire", etc.  The third element
     may be a string, an object, or an array of strings and/or objects
     and/or limb indices of 'who' (limb indices will be converted to a
     summary list of the appropriate limb names using the function
     query_limbs_description()).  A fourth element, if supplied, will be
     used as message listing flags (cf. /def/descriptor/message.c).
     If a fifth element is supplied, it will be used as identity query
     flags (cf.  /def/descriptor/identity.c).

 ({ 's', who, obj })                    "the orc's sword" / "your knife"
 ({ 's', who, list })                        "the orc's sword and knife"
 Msg_Name_Has(who, obj)
 Msg_Name_Has(who, list)

     Definite possessive form of the third element with respect to
     the second element; i.e. ({ 's', 0, weapon }) will produce "the
     troll's sword", "Bob's knife", "Stormbringer", etc.  The third
     element may be a string, an object, or an array of strings and/or
     objects and/or limb indices (as with 'r' above).  If a fourth element
     is supplied, it will be used as message listing flags
     (cf. /def/descriptor/message.c).  A fifth element, if supplied, will
     be used as identity query flags (cf. /def/descriptor/identity.c).

     In a very special-case behavior, if 's' is used and the third
     element is entirely proper-named so that the second element's name
     does not appear, this causes the next non-reflexive pronoun in the
     message that refers to the second element to display a name; this
     means that a 'm' or 'q' will be treated as a 'u', an 'o' or 'p'
     will be treated as a 'e', and a 'r' will be treated as a 's'.

 ({ 't', obj })                                                "the orc"
 Msg_The(obj)

     Second element affected as if by the()

 ({ 'u', obj })                                     "the orc's" / "your"
 Msg_Defn_Poss(obj)

     Definite possessive form of the second element, i.e.  ({ 'u', 0 })
     will produce "your" or "Bob's" or "the orc's".  If a third element
     is provided, it will be used as identity query flags.  This is
     ALMOST NEVER appropriate to use; use 's' instead of 'u' whenever
     possible.

 ({ 'v', obj })                                         "this" / "these"
 Msg_Indic_Pron(obj)

     Indicative pronoun of the second element (this, these).

 ({ 'w', obj })                                          "orc" / "orc 2"
 Msg_Which(obj)

     Second element affected as if by which(), with the message's
     observer used as which()'s observer argument.  If a third element
     is supplied, it is used as the 'name' argument to which().  If
     a fourth element is supplied, it is used as the 'flags' argument
     to which().  If a fifth element is supplied, it is used as the
     'context' argument to which().

 ({ 'x', obj })                                        "male" / "female"
 Msg_Sex(obj)

     The sex of the second element as apparent to the viewer, i.e.
     ({ 'x', person }) will produce "male", "female", "neuter", etc.
     If the second element's sex is indeterminate to the viewer,
     nothing will be produced.  If a third element is provided, it
     is expected to be a string and will be appended (with a space
     in between) to the sex name if and only if one is displayed.
     Most often, the results desired with this are better obtained
     using 'c' with the 'include sex' flag enabled.

 ({ 'z', obj, "forme", "foryou" })                    "forme" / "foryou"
 Msg_Self_Other(obj, "forme", "foryou")

     Uses the third or fourth element depending on the viewer, i.e.
     ({ 'z', 0, "you", "this" }) will produce "you" if the viewer
     matches the originator of the message, otherwise "this".

 ({ 'X', ({ ... })})
 Msg_Expand(({ ... }))

     Expands the array specified into the outer message.  So
     ({ ({ 'X', ({ "foo" }) has the same effect as ({ "foo" }).
    If this doesn't make any sense to you, it probably doesn't
     need to; it exists to support some difficult cases that lib
     developers run into.

Once converted to strings locally, the elements of the list are normally concatenated with a single space inserted between each pair. The space will not be inserted, however, before any list element which begins with one of the characters ,;:.!? for purposes of consistency.

It is expected that support for language interpretation and other functions will be added into the messaging code.

EXAMPLES

To send a message of an orc bowing to an ogre (represented by the object variables 'orc' and 'ogre' respectively):

 orc->message(([
     Message_Content : ({
         0, ({ "bow", 0 }), "to", ogre,
     }),
     Message_Senses  : Message_Sense_Visual | Message_Sense_Kinesthetic_For_Source,
 ]));

 // msg.h version
 orc->message(([
     Message_Content : ({
         0, Msg_Verb("bow")  "to", ogre,
     }),
     Message_Senses  : Message_Sense_Visual | Message_Sense_Kinesthetic_For_Source,
 ]));

The orc will see "You bow to the ogre.\n", the ogre will see "The orc bows to you.\n", and others present will see "The orc bbows to the ogre.\n".

For a sword to send a message that it leaps toward its target:

 wielder->message(([
     Message_Content : ({
         ({ 's', 0, this_object() }), ({ "leap", this_object() }),
         "toward", target,
     }),
     Message_Senses  : Message_Sense_Visual | Message_Sense_Kinesthetic_For_Source | Message_Sense_Tactile_For_Participants,
 ]));

 // msg.h version
 wielder->message(([
     Message_Content : ({
         Msg_Name_Has(0, this_object()), Msg_Verb("leap", this_object()),
         "toward", target,
     }),
     Message_Senses  : Message_Sense_Visual | Message_Sense_Kinesthetic_For_Source | Message_Sense_Tactile_For_Participants,
 ]));

For 'bob' to wiggle his ears:

 bob->message(([
     Message_Content : ({
         0, ({ "wiggle", 0 }), ({ 'r', 0, "ears" }),
     }),
     Message_Senses  : Message_Sense_Visual | Message_Sense_Kinesthetic_For_Source,
 ]));

 // msg.h version
 bob->message(([
     Message_Content : ({
         0, Msg_Verb("wiggle", 0), Msg_Pron_Has(0, "ears"),
     }),
     Message_Senses  : Message_Sense_Visual | Message_Sense_Kinesthetic_For_Source,
 ]));

For 'larry' to run into 'moe', shoving him into 'curly':

 larry->message(([
     Message_Content : ({
         0, ({ "run", 0 }), "into", moe, ", shoving",
         ({ 'o', moe }), "into", curly,
     }),
     Message_Senses  : Message_Sense_Visual | Message_Sense_Kinesthetic_For_Source | Message_Sense_Tactile_For_Participants,
 ]));

 // msg.h version
 larry->message(([
     Message_Content : ({
         0, Msg_Verb("run", 0), "into", moe, ", shoving",
         Msg_Obj_Pron(moe), "into", curly,
     }),
     Message_Senses  : Message_Sense_Visual | Message_Sense_Kinesthetic_For_Source | Message_Sense_Tactile_For_Participants,
 ]));

HISTORICAL

The original message() function had a four-argument form which could only handle different messages for one target and which had no facility for subjective recognition of objects. Its functionality was once supported for backward compatibility, but this is no longer the case.