# evennia.commands.cmdhandler

Command handler

This module contains the infrastructure for accepting commands on the command line. The processing of a command works as follows:

1. The calling object (caller) is analyzed based on its callertype.

2. Cmdsets are gathered from different sources: - object cmdsets: all objects at caller’s location are scanned for non-empty

   > cmdsets. This includes cmdsets on exits.

   - caller: the caller is searched for its own currently active cmdset.

   - account: lastly the cmdsets defined on caller.account are added.

3. The collected cmdsets are merged together to a combined, current cmdset.

4. If the input string is empty -> check for CMD_NOINPUT command in current cmdset or fallback to error message. Exit.

5. The Command Parser is triggered, using the current cmdset to analyze the input string for possible command matches.

6. If multiple matches are found -> check for CMD_MULTIMATCH in current cmdset, or fallback to error message. Exit.

7. If no match was found -> check for CMD_NOMATCH in current cmdset or fallback to error message. Exit.

8. At this point we have found a normal command. We assign useful variables to it that will be available to the command coder at run-time.

9. We have a unique cmdobject, primed for use. Call all hooks: at_pre_cmd(), cmdobj.parse(), cmdobj.func() and finally at_post_cmd().

10. Return deferred that will fire with the return from cmdobj.func() (unused by default).

`evennia.commands.cmdhandler.``cmdhandler`(called_by, raw_string, _testing=False, callertype='session', session=None, cmdobj=None, cmdobj_key=None, **kwargs)

  This is the main mechanism that handles any string sent to the engine.

  Parameters

    - called_by (Session, Account or Object) – Object from which this command was called. which this was called from. What this is depends on the game state.

    - raw_string (str) – The command string as given on the command line.

    - _testing (bool, optional) – Used for debug purposes and decides if we should actually execute the command or not. If True, the command instance will be returned.

    - callertype (str, optional) – One of “session”, “account” or “object”. These are treated in decending order, so when the Session is the caller, it will merge its own cmdset into cmdsets from both Account and eventual puppeted Object (and cmdsets in its room etc). An Account will only include its own cmdset and the Objects and so on. Merge order is the same order, so that Object cmdsets are merged in last, giving them precendence for same-name and same-prio commands.

    - session (Session, optional) – Relevant if callertype is “account” - the session will help retrieve the correct cmdsets from puppeted objects.

    - cmdobj (Command, optional) – If given a command instance, this will be executed using called_by as the caller, raw_string representing its arguments and (optionally) cmdobj_key as its input command name. No cmdset lookup will be performed but all other options apply as normal. This allows for running a specific Command within the command system mechanism.

    - cmdobj_key (string, optional) – Used together with cmdobj keyword to specify which cmdname should be assigned when calling the specified Command instance. This is made available as self.cmdstring when the Command runs. If not given, the command will be assumed to be called as cmdobj.key.

  Keyword Arguments

    kwargs (any) – other keyword arguments will be assigned as named variables on the retrieved command object before it is executed. This is unused in default Evennia but may be used by code to set custom flags or special operating conditions for a command as it executes.

  Returns

    deferred (Deferred) – This deferred is fired with the return value of the command’s func method. This is not used in default Evennia.

exception `evennia.commands.cmdhandler.``InterruptCommand`

  Bases: `Exception`

  Cleanly interrupt a command.