add_command |
Discworld creator help |
add_command |
Syntax
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)
Note
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'.
Description
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.
Patterns
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.
| {in|on} | required words | |
| [in|on] | optional words | |
| <indirect:object> | special word list |
The special word list sequences have a few options. Options are separated from the main identifier by a ':'.
| 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'. |
Several of these specifiers have options as follows:
direct, indirect:
| 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. |
string (default is short):
| short | A short string, this means it will make the shortest possible string based on the rest of the matching. eg: <string:short> at <string>, would matching in the following 'frog at bing at bing' it would get 'frog' | |
| long | A long string, this means it will make the longest possible string based on the rest of the matching. eg: <string:long> at <string>, would matching in the following 'frog at bing at bing' it would get 'frog at bing' | |
| quoted | Uses quotes to match. So it looks for string surrounded with " ' or `. |
number:
| positive | Only matching positive numbers, theses are numbers > 0. | |
| negative | Only matching negative numbers, these are numbers < 0. |
The second option is where to look for the objects, this only applies to direct and indirect matching arguments.
| 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. |
Standard Arguments
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:
int func(object *indirect_obs, string *dir_match, string indir_match,
mixed *args, string pattern);
Note: When called from within an add_item the verb is passed as the first arg and then the args as described above.
int func(string verb, object *indirect_obs, string *dir_match, string indir_match, mixed *args, string pattern);
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:
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);
Return value
Returning 1 from func will signal that the command succeeded, returning 0 that the command failed.
