blob: 83b77317210b60ac5c576cd2cdde0c494982006d [file] [log] [blame]
MG Mud User88f12472016-06-24 23:31:02 +02001OPTIONAL
2SYNOPSIS
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
6DESCRIPTION
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
123EXAMPLE
124 object *items;
125 parse_command( "take apple",environment(this_player())
126 , " 'get' / 'take' %i ",items);
127
128HISTORY
129 LDMud 3.3.258 removed the compat-mode parse_command().
130
131SEE ALSO
132 sscanf(E)