
parse_command(3)      LPC Library Functions      parse_command(3)

NAME
       parse_command()  - try to match a string with a given pat-
       tern

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 ref-
       erence  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                       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  identi-
       cal  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
              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 visible
                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

MudOS                       5 Sep 1994                          2

parse_command(3)      LPC Library Functions      parse_command(3)

       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  pat-
       tern 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();

       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

MudOS                       5 Sep 1994                          3

parse_command(3)      LPC Library Functions      parse_command(3)

       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                       5 Sep 1994                          4

