parsing / parse_command

Edit on Github

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 pattern  and  a  variable
set  of  destination  arguments. It is together with sscanf(3) the only
efun to use pass by reference 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  auto‐
matically  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  vari‐
ables 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
%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  fil‐
ters  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 match‐
ing.  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 context.
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 vis‐
ible
meaning  that 'second' might not at all mean the second object
in
the returned array of objects.

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 spa‐
ces.   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 pat‐
tern 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();

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 gram‐
matical  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 neces‐
sary 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"