| OPTIONAL |
| SYNOPSIS |
| int parse_command (string cmd, object env, string fmt, mixed &var, ...) |
| int parse_command (string cmd, object* arr, string fmt, mixed &var, ...) |
| |
| DESCRIPTION |
| parse_command() is basically a spiffed up sscanf operating |
| on word basis and targeted at recognizing object descriptions from |
| command strings. |
| |
| The efun takes the command string <cmd> and the object(s) <env>/<arr> |
| and tries to match it against the format string <fmt>. Successfully |
| matched elements are assigned to the variables <var>.... The result |
| from the efun is 1 if the command could be fully matched, and 0 |
| otherwise. |
| |
| If the objects are given as a single object <env>, the efun matches |
| against the given object and all objects contained therein. Otherwise, |
| if the objects are given as an array <arr> of objects, the efun |
| matches only against the given objects. |
| |
| The format string <fmt> consists of words, syntactic markers, and |
| %-directives for the values to parse and return in the variables. |
| A typical example is " 'get' / 'take' %i " or |
| " 'spray' / 'paint' [paint] %i ". The elements in detail are: |
| |
| 'word': obligatory text |
| [word]: optional text |
| / : Alternative marker |
| %o : Single item, object |
| %s : Any text |
| %w : Any word |
| %p : One of a list of prepositions. |
| If the variable associated with %p is used to pass |
| a list of words to the efun, the matching will take |
| only against this list. |
| %l : non-compat: Living objects |
| compat: a single living object |
| %i : Any objects |
| %d : Number >= 0, or when given textual: 0-99. |
| |
| A <word> in this context is any sequence of characters not containing |
| a space. 'living objects' are searched by calls to the (simul)efuns |
| find_player() and find_living(): both functions have to accept a name |
| as argument and return the object for this name, or 0 if there |
| is none. |
| |
| The results assigned to the variables by the %-directives are: |
| |
| %o : returns an object |
| %s : returns a string of words |
| %w : returns a string of one word |
| %p : if passed empty: a string |
| if passed as array of words: var[0] is the matched word |
| %i : returns an array with the following content: |
| [0]: int: the count/number recognized in the object spec |
| > 0: a count (e.g. 'three', '4') |
| < 0: an ordinal (e.g. 'second', 'third') |
| = 0: 'all' or a generic plural such as 'apples' |
| [1..]: object: all(!) objects matching the item description. |
| In the <env> form this may be the whole |
| recursive inventory of the <env> object. |
| It is up to the caller to interpret the recognized numeral |
| and to apply it on the list of matched objects. |
| %l : non-compat: as %i, except that only living objects are |
| returned. |
| compat: as %o, except that only a living object is returned. |
| |
| %i (and non-compat-%l) match descriptions like 'three red roses', |
| 'all nasty bugs' or 'second blue sword'. |
| |
| Note: Patterns of type: "%s %w %i" might not work as one would expect. |
| %w will always succeed so the arg corresponding to %s will always be |
| empty. |
| |
| To make the efun useful it must have a certain support from the |
| mudlib: it calls a set of functions in objects to get the |
| information it needs to parse a string. |
| |
| 1. string *parse_command_id_list() |
| Normal singular names of the object. |
| |
| 2. string *parse_command_plural_id_list() - optional |
| Plural forms of the names returned by 1. |
| If this function doesn't exist, the parser tries to pluralize |
| the names returned by 1. |
| |
| 3. string *parse_command_adjectiv_id_list() - optional |
| All adjectives associated with this object. |
| |
| All names and adjectives may consist of several words separated |
| by spaces. |
| |
| These functions should exist in all objects and are therefore best |
| put into a mandatory inherit file (e.g. /std/object.c). |
| |
| In addition the master object may offer the same functions to provide |
| reasonable defaults (like 'thing' as generic singular name): |
| |
| string *parse_command_id_list() |
| - Would normally return: ({ "one", "thing" }) |
| |
| string *parse_command_plural_id_list() |
| - Would normally return: ({ "ones", "things", "them" }) |
| |
| string *parse_command_adjectiv_id_list() |
| - Would normally return ({ "iffish" }) |
| |
| Two additional functions in the master object provide the default |
| list of prepositions (needed for %p) and the single 'all' word: |
| |
| string *parse_command_prepos_list() |
| - Would normally return: ({ "in", "on", "under", "behind", |
| "beside" }) |
| |
| string parse_command_all_word() |
| - Would normally return: "all" |
| |
| |
| int parse_command(string, object|object*, string, destargs...) |
| |
| |
| EXAMPLE |
| object *items; |
| parse_command( "take apple",environment(this_player()) |
| , " 'get' / 'take' %i ",items); |
| |
| HISTORY |
| LDMud 3.3.258 removed the compat-mode parse_command(). |
| |
| SEE ALSO |
| sscanf(E) |