parse_command(3) LPC Library Functions parse_command(3)
NAME
parse_command() - try to match a string with a given pattern
SYNOPSIS
int parse_command( string command, object env|object *oblist,
string pattern, mixed arg, ... );
DESCRIPTION
parse_command() is a piffed up sscanf(3) operating on word
basis. It works similar to sscanf(3) in that it takes a pat-
tern and a variable set of destination arguments. It is
together with sscanf(3) the only efun to use pass by refer-
ence for other variables than arrays. That is,
parse_command() returns values in its arguments.
parse_command() returns 1 if 'command' is considered to have
matched
The 'env' or 'oblist' parameter either holds an object or a
list of objects. If it holds a single object than a list of
objects are automatically created by adding the
deep_inventory of the object, ie this is identical:
parse_command(cmd, environment(), pattern, arg)
and
parse_command( cmd, ({ environment() }) +
deep_inventory(environment()), pattern, arg)
Example string = " 'get' / 'take' %i "
Syntax:
'word' obligatory text
[word] optional text
/ Alternative marker
%o Single item, object
%l Living objects
%s Any text
%w Any word
%p One of a list (prepositions)
%i Any items
%d Number 0- or tx(0-99)
The 'arg' list is zero or more arguments. These are the
result variables as in sscanf. Note that one variable is
needed for each %_
The return types of different %_ is:
%o Returns an object
%s Returns a string of words
MudOS Last change: 5 Sep 1994 1
parse_command(3) LPC Library Functions parse_command(3)
%w Returns a string of one word
%p Can on entry hold a list of word in array
or an empty variable
Returns:
if empty variable: a string
if array: array[0] = matched word
%i Returns a special array on the form:
[0] = (int) +(wanted) -(order) 0(all)
[1..n] (object) Objectpointers
%l Returns a special array on the form:
[0] = (int) +(wanted) -(order) 0(all)
[1..n] (object) Objectpointers
These are only living objects.
%d Returns a number
The only types of % that uses all the loaded information
from the objects are %i and %l. These are in fact identical
except that %l filters out all nonliving objects from the
list of objects before trying to parse.
The return values of %i and %l is also the most complex.
They return an array consisting of first a number and then
all possible objects matching. As the typical string
matched by %i/%l looks like: 'three red roses', of these
numerical constructs was matched:
if numeral >0 then three, four, five etc were matched
if numeral <0 then second, twentyfirst etc were matched
if numeral==0 then 'all' or a generic plural form such as
'apples' were matched.
NOTE!
The efun makes no semantic implication on the given
numeral. It does
not matter if 'all apples' or 'second apple' is
given. A %i will
return ALL possible objects matching in the array. It
is up to the
caller to decide what 'second' means in a given con-
text.
Also when given an object and not an explicit array
of objects the
entire recursive inventory of the given object is
searched. It is up
to the caller to decide which of the objects are
actually visible
meaning that 'second' might not at all mean the
second object in
the returned array of objects.
MudOS Last change: 5 Sep 1994 2
parse_command(3) LPC Library Functions parse_command(3)
CAVEAT
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.
BUGS
Patterns of the type: 'word' and [word] The 'word' can not
contain spaces. It must be a single word. This is so
because the pattern is exploded on " " (space) and a pattern
element can therefore not contain spaces.
As another effect of the exploding on space, separate pieces
of a pattern MUST be separated with space, ie not "
'word'/%i " but " 'word' / %i"
EXAMPLE:
if (parse_command("spray car",environment(this_player()),
" 'spray' / 'paint' [paint] %i ",items))
{
/*
If the pattern matched then items holds a return array as
described under 'destargs' %i above.
*/
}
MUDLIB SUPPORT
To make the efun useful it must have a certain support from
the mudlib, there is a set of functions that it needs to
call to get relevant information before it can parse in a
sensible manner.
In earlier versions it used the normal id() lfun in the LPC
objects to find out if a given object was identified by a
certain string. This was highly inefficient as it could
result in hundreds or maybe thousands of calls when very
long commands were parsed.
The new version relies on the LPC objects to give it three
lists of 'names'.
1 - The normal singular names.
2 - The plural forms of the names.
3 - The acknowledged adjectives of the object.
These are fetched by calls to the functions:
1 - string *parse_command_id_list();
2 - string *parse_command_plural_id_list();
3 - string *parse_command_adjectiv_id_list();
MudOS Last change: 5 Sep 1994 3
parse_command(3) LPC Library Functions parse_command(3)
The only really needed list is the first. If the second does
not exist than the efun will try to create one from the
singluar list. For grammatical reasons it does not always
succeed in a perfect way. This is especially true when the
'names' are not single words but phrases.
The third is very nice to have because it makes constructs
like
Apart from these functions that should exist in all objects,
and which are therefore best put in the base mudlib object
there is also a set of functions needed in the master
object. These are not absolutely necessary but they give
extra power to the efun.
Basically these master object lfuns are there to give
default values for the lists of names fetched from each
object.
The names in these lists are applicable to any and all
objects, the first three are identical to the lfuns in the
objects:
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" })
The last two are the default list of the prepositions and a
single so called
string *parse_command_prepos_list()
- Would normally return: ({ "in", "on", "under" })
string parse_command_all_word()
- Would normally return: "all"
MudOS Last change: 5 Sep 1994 4