.DT
add_command
$MUDNAME$ creator help
add_command
.SH Syntax
.SI 5
int add_command(string verb, object ob)
int add_command(string verb, object ob, string pattern)
int add_command(string verb, object ob, string *pattern)
int add_command(string verb, object ob, string pattern, function f)
int add_command(string verb, object ob, string *pattern, function f)
.EI
.SH Note
.SI 5
For information on converting from add_action() to add_command() please
see 'help add_command_conversion'. For full details of using add_command see 'help add_command_details'.
.EI
.SH Description
.SP 5 5
This function is a pattern matching input parser. It is designed to
make input parsing from the user a lot easier.
The first parameter passed to the add_command function is the verb. The
verb is the same as the verb specified in the add_action command. The verb
does not handle '*' completion stuff and it does not handle short verbs.
The second parameter is the object. This is the object that is defining the
verb and it is the object upon which the function is called if it is matched.
This will be defined in more detail later on.
The third parameter is the pattern. The pattern is the main part of the
processing. If the pattern is not defined a pattern of "<direct:object>" is
assumed. The format of the pattern will be defined in the Section on
patterns.
The fourth parameter is a function pointer. If no pointer is given a
function do_<command> will be called. eg. if the command is 'read'
do_read() will be called.
.EP
.SH Patterns
.SP 5 5
The patterns are defined by using a series of key characters and a
normal text string. Anything which is not enclosed in wrapping
brackets is a required word.
.SO 5 20 -30
{in|on} required words
[in|on] optional words
<indirect:object> special word list
.EO
.SP 5 5
The special word list sequences have a few options. Options are
separated from the main identifier by a ':'.
.EP
.SO 5 20 -30
direct The direct object reference.
indirect The indirect object reference.
string One or more words comprise a string.
word A single word.
number A number (only matching numerics)
fraction A composite number.
preposition A preposition, a word like 'from', 'in', 'under'.
.EO
.SP 5 5
Several of these specifiers have options as follows.
.EP
.SO 5 20 -30
object Any object, uses find_match directly.
living Any living object.
distant-living Uses find_living.
any-living A combination of living and distant-living.
player Will only match a player.
wiz-present Uses wiz_present to do a match.
.EO
.SP 5 5
The second option is where to look for the objects.
.EP
.SO 5 20 -30
me The players inventory.
here The inventory of the room.
here-me The inventory of the room, then the inventory of the player.
me-here The inventory of the player and then the inventory of the room.
direct-obs The inventory of the direct object.
.EO
.SP 5 5
Strings also have parameter, they can be short, long or quoted. Strings
default to being short strings.
.EP
.SH Standard Arguments
.SP 5 5
These are the arguments which are passed into the function calls by
default. The reason these all seem a little weird is those wonderful
words, 'backwards compatibility'. These are always the same:
.EP
.SI 10
int func(object *indirect_obs, string dir_match, string indir_match,
mixed *args, string pattern);
int func(object **indirect_obs, string *dir_match, string indir_match,
mixed *args, string pattern);
.EI
.SP 5 5
When using a function pointer to call your function the params above are
numbered 1 to 5. Thus if you just want to know the first indirect
object and the second argument string you would use:
.EP
.SI 10
add_command("bing", this_object(), "<indirect:player> sideways",
(: my_fun($1[0], $4[1]) :);
and declare your function as:
int my_fun(object ob, string param);
.EI
.SH Return value
.SP 5 5
Returning 1 from func will signal that the command succeded,
returning 0 that the command failed.
.EP
.SH See also
.SI 5
add_command_details, add_succeeded, add_succeeded_mess,
add_failed_mess, command_control and help syntax, help
add_command_conversion
.EI
