
parse_command(3)       C 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

Sun Release 4.1           Last change:                          1

parse_command(3)       C LIBRARY FUNCTIONS       parse_command(3)

                     %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  liv-
     ing 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 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

Sun Release 4.1           Last change:                          2

parse_command(3)       C LIBRARY FUNCTIONS       parse_command(3)

     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  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.

Sun Release 4.1           Last change:                          3

parse_command(3)       C LIBRARY FUNCTIONS       parse_command(3)

        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 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"

Sun Release 4.1           Last change:                          4

