MG Mud User | 88f1247 | 2016-06-24 23:31:02 +0200 | [diff] [blame^] | 1 | OPTIONAL |
| 2 | SYNOPSIS |
| 3 | int parse_command (string cmd, object env, string fmt, mixed &var, ...) |
| 4 | int parse_command (string cmd, object* arr, string fmt, mixed &var, ...) |
| 5 | |
| 6 | DESCRIPTION |
| 7 | parse_command() is basically a spiffed up sscanf operating |
| 8 | on word basis and targeted at recognizing object descriptions from |
| 9 | command strings. |
| 10 | |
| 11 | The efun takes the command string <cmd> and the object(s) <env>/<arr> |
| 12 | and tries to match it against the format string <fmt>. Successfully |
| 13 | matched elements are assigned to the variables <var>.... The result |
| 14 | from the efun is 1 if the command could be fully matched, and 0 |
| 15 | otherwise. |
| 16 | |
| 17 | If the objects are given as a single object <env>, the efun matches |
| 18 | against the given object and all objects contained therein. Otherwise, |
| 19 | if the objects are given as an array <arr> of objects, the efun |
| 20 | matches only against the given objects. |
| 21 | |
| 22 | The format string <fmt> consists of words, syntactic markers, and |
| 23 | %-directives for the values to parse and return in the variables. |
| 24 | A typical example is " 'get' / 'take' %i " or |
| 25 | " 'spray' / 'paint' [paint] %i ". The elements in detail are: |
| 26 | |
| 27 | 'word': obligatory text |
| 28 | [word]: optional text |
| 29 | / : Alternative marker |
| 30 | %o : Single item, object |
| 31 | %s : Any text |
| 32 | %w : Any word |
| 33 | %p : One of a list of prepositions. |
| 34 | If the variable associated with %p is used to pass |
| 35 | a list of words to the efun, the matching will take |
| 36 | only against this list. |
| 37 | %l : non-compat: Living objects |
| 38 | compat: a single living object |
| 39 | %i : Any objects |
| 40 | %d : Number >= 0, or when given textual: 0-99. |
| 41 | |
| 42 | A <word> in this context is any sequence of characters not containing |
| 43 | a space. 'living objects' are searched by calls to the (simul)efuns |
| 44 | find_player() and find_living(): both functions have to accept a name |
| 45 | as argument and return the object for this name, or 0 if there |
| 46 | is none. |
| 47 | |
| 48 | The results assigned to the variables by the %-directives are: |
| 49 | |
| 50 | %o : returns an object |
| 51 | %s : returns a string of words |
| 52 | %w : returns a string of one word |
| 53 | %p : if passed empty: a string |
| 54 | if passed as array of words: var[0] is the matched word |
| 55 | %i : returns an array with the following content: |
| 56 | [0]: int: the count/number recognized in the object spec |
| 57 | > 0: a count (e.g. 'three', '4') |
| 58 | < 0: an ordinal (e.g. 'second', 'third') |
| 59 | = 0: 'all' or a generic plural such as 'apples' |
| 60 | [1..]: object: all(!) objects matching the item description. |
| 61 | In the <env> form this may be the whole |
| 62 | recursive inventory of the <env> object. |
| 63 | It is up to the caller to interpret the recognized numeral |
| 64 | and to apply it on the list of matched objects. |
| 65 | %l : non-compat: as %i, except that only living objects are |
| 66 | returned. |
| 67 | compat: as %o, except that only a living object is returned. |
| 68 | |
| 69 | %i (and non-compat-%l) match descriptions like 'three red roses', |
| 70 | 'all nasty bugs' or 'second blue sword'. |
| 71 | |
| 72 | Note: Patterns of type: "%s %w %i" might not work as one would expect. |
| 73 | %w will always succeed so the arg corresponding to %s will always be |
| 74 | empty. |
| 75 | |
| 76 | To make the efun useful it must have a certain support from the |
| 77 | mudlib: it calls a set of functions in objects to get the |
| 78 | information it needs to parse a string. |
| 79 | |
| 80 | 1. string *parse_command_id_list() |
| 81 | Normal singular names of the object. |
| 82 | |
| 83 | 2. string *parse_command_plural_id_list() - optional |
| 84 | Plural forms of the names returned by 1. |
| 85 | If this function doesn't exist, the parser tries to pluralize |
| 86 | the names returned by 1. |
| 87 | |
| 88 | 3. string *parse_command_adjectiv_id_list() - optional |
| 89 | All adjectives associated with this object. |
| 90 | |
| 91 | All names and adjectives may consist of several words separated |
| 92 | by spaces. |
| 93 | |
| 94 | These functions should exist in all objects and are therefore best |
| 95 | put into a mandatory inherit file (e.g. /std/object.c). |
| 96 | |
| 97 | In addition the master object may offer the same functions to provide |
| 98 | reasonable defaults (like 'thing' as generic singular name): |
| 99 | |
| 100 | string *parse_command_id_list() |
| 101 | - Would normally return: ({ "one", "thing" }) |
| 102 | |
| 103 | string *parse_command_plural_id_list() |
| 104 | - Would normally return: ({ "ones", "things", "them" }) |
| 105 | |
| 106 | string *parse_command_adjectiv_id_list() |
| 107 | - Would normally return ({ "iffish" }) |
| 108 | |
| 109 | Two additional functions in the master object provide the default |
| 110 | list of prepositions (needed for %p) and the single 'all' word: |
| 111 | |
| 112 | string *parse_command_prepos_list() |
| 113 | - Would normally return: ({ "in", "on", "under", "behind", |
| 114 | "beside" }) |
| 115 | |
| 116 | string parse_command_all_word() |
| 117 | - Would normally return: "all" |
| 118 | |
| 119 | |
| 120 | int parse_command(string, object|object*, string, destargs...) |
| 121 | |
| 122 | |
| 123 | EXAMPLE |
| 124 | object *items; |
| 125 | parse_command( "take apple",environment(this_player()) |
| 126 | , " 'get' / 'take' %i ",items); |
| 127 | |
| 128 | HISTORY |
| 129 | LDMud 3.3.258 removed the compat-mode parse_command(). |
| 130 | |
| 131 | SEE ALSO |
| 132 | sscanf(E) |