doc/efun/add_action

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)