| SYNOPSIS |
| #include <commands.h> |
| |
| void add_action(string|closure fun, string cmd) |
| void add_action(string|closure fun, string cmd, int flag) |
| |
| DESCRIPTION |
| Set up a local function fun to be called when user input |
| matches the command cmd. Functions called by a user command |
| will get the arguments as a string. It must then return 0 if |
| it was the wrong command, otherwise 1. |
| |
| If it was the wrong command, the parser will continue |
| searching for another command, until one returns 1 or give an |
| error message to the user. |
| |
| For example, there can be a wand and a rod. Both of these |
| objects define as command "wave". One of them will be randomly |
| called first, and it must look at the argument, and match |
| against "wand" or "rod" respectively. |
| |
| The function associated to a command will be called with a |
| string as argument which stands for the given words behind the |
| typed command. The verb entered can be retrieved using the |
| query_verb() efun and is always the first word in the input |
| line up to the first space. |
| |
| Always have add_action() called only from an init() routine. |
| The object defining these commands must be present to the |
| user, either being the user, being carried by the user, |
| being the room around the user, or being an object in the |
| same room as the user. If the player leaves this vicinity of the |
| object, the actions are automatically removed. |
| |
| Actions can also be removed on demand with the remove_actions() efun. |
| |
| If argument <flag> is AA_SHORT (1), then the arguments may |
| follow the verb without separating space. Any arguments after |
| the first space are passed as argument string. |
| |
| If argument <flag> is AA_NOSPACE (2), then again the arguments |
| may follow the verb without separating space. In contrast to |
| AA_SHORT, all characters following the verb are passed as |
| the argument string. However, note that the characters immediately |
| following the given verb are passed as argument AND as result |
| of query_verb(). |
| |
| If argument <flag> is AA_IMM_ARGS (3), then again the arguments |
| may follow the verb without separating space. All characters following |
| the given verb are passed as argument, and only as argument. |
| |
| If argument <flag> is negative, the verb given by the player |
| has to match only the leading -<flag> characters of the verb <cmd>. |
| |
| Never use one of the functions 'create' 'reset' 'init' 'exit' |
| 'heart_beat' etc as the first argument to add_action(). In |
| general, a function with a name defined in /doc/applied should |
| have the behaviour defined there. |
| |
| |
| EXAMPLES |
| add_action("GoInside", "enter"); |
| |
| When typing "enter" the function GoInside() will be invoked. |
| |
| add_action("DisFunc", "dis", AA_SHORT); |
| |
| Whenever you type in a command which starts with "dis" the |
| function DisFunc() will be called. To get the real word which |
| was typed in (because until now you only know that it was a |
| command beginning with "dis") you have to call the efun |
| query_verb(). |
| |
| add_action("DisFunc", "disconnect", AA_NOSPACE); |
| |
| The function DisFunc() will be called for all commands which |
| use "disconnect" or a shortened form like "di", "dis" or |
| "discon" as verb. The command 'disconnecting' will _not_ |
| be recognized. To get the real word which was typed in |
| you have to call the efun query_verb(). |
| |
| |
| add_action("...", "cmd"); |
| add_action("...", "xcmd", AA_SHORT); |
| add_action("...", "scmd", AA_NOSPACE); |
| add_action("...", "icmd", AA_IMM_ARGS); |
| |
| When given the following commands, the driver will parse it |
| as described below. 'verb' is what query_verb() would return, |
| 'arg' is what would be passed to the command function. |
| |
| "cmd" -> verb "cmd", arg 0 |
| "cmd foo bar" -> verb "cmd", arg "foo bar" |
| |
| "xcmd" -> verb "xcmd", arg 0 |
| "xcmd foo" -> verb "xcmd", arg "foo" |
| "xcmdfoo" -> verb "xcmdfoo", arg 0 |
| "xcmd foo bar" -> verb "xcmd", arg "foo bar" |
| "xcmdfoo bar" -> verb "xcmdfoo", arg "bar" |
| |
| "scmd" -> verb "scmd", arg 0 |
| "scmd foo" -> verb "scmd", arg " foo" |
| "scmdfoo" -> verb "scmdfoo", arg "foo" |
| "scmd foo bar" -> verb "scmd", arg " foo bar" |
| "scmdfoo bar" -> verb "scmdfoo", arg "foo bar" |
| |
| "icmd" -> verb "icmd", arg 0 |
| "icmd foo" -> verb "icmd", arg " foo" |
| "icmdfoo" -> verb "icmd", arg "foo" |
| "icmd foo bar" -> verb "icmd", arg " foo bar" |
| "icmdfoo bar" -> verb "icmd", arg "foo bar" |
| |
| |
| HISTORY |
| The flag < 0 argument was supported since 3.2@127, but not |
| really implemented before LDMud 3.2.8. |
| LDMud 3.2.9 introduced the AA_IMM_ARGS flag. |
| LDMud 3.3 removed the historical add_action(fun) notation. |
| Since LDMud 3.5 the function can be given as a closure. |
| |
| SEE ALSO |
| query_verb(E), query_command(E), remove_action(E), init(A) |