# evennia.commands.cmdparser

The default command parser. Use your own by assigning settings.COMMAND_PARSER to a Python path to a module containing the replacing cmdparser function. The replacement parser must accept the same inputs as the default one.

`evennia.commands.cmdparser.``create_match`(cmdname, string, cmdobj, raw_cmdname)

  Builds a command match by splitting the incoming string and evaluating the quality of the match.

  Parameters

    - cmdname (str) – Name of command to check for.

    - string (str) – The string to match against.

    - cmdobj (str) – The full Command instance.

    - raw_cmdname (str, optional) – If CMD_IGNORE_PREFIX is set and the cmdname starts with one of the prefixes to ignore, this contains the raw, unstripped cmdname, otherwise it is None.

  Returns

    match (tuple) –

    This is on the form (cmdname, args, cmdobj, cmdlen, mratio, raw_cmdname),

      where cmdname is the command’s name and args is the rest of the incoming string, without said command name. cmdobj is the Command instance, the cmdlen is the same as len(cmdname) and mratio is a measure of how big a part of the full input string the cmdname takes up - an exact match would be 1.0. Finally, the raw_cmdname is the cmdname unmodified by eventual prefix-stripping.

`evennia.commands.cmdparser.``build_matches`(raw_string, cmdset, include_prefixes=False)

  Build match tuples by matching raw_string against available commands.

  Parameters

    - raw_string (str) – Input string that can look in any way; the only assumption is that the sought command’s name/alias must be first in the string.

    - cmdset (CmdSet) – The current cmdset to pick Commands from.

    - include_prefixes (bool) – If set, include prefixes like @, ! etc (specified in settings) in the match, otherwise strip them before matching.

  Returns

    matches (list) A list of match tuples created by cmdparser.create_match.

`evennia.commands.cmdparser.``try_num_differentiators`(raw_string)

  Test if user tried to separate multi-matches with a number separator (default 1-name, 2-name etc). This is usually called last, if no other match was found.

  Parameters

    raw_string (str) – The user input to parse.

  Returns

    mindex, new_raw_string (tuple) –

    If a multimatch-separator was detected,

      this is stripped out as an integer to separate between the matches. The new_raw_string is the result of stripping out that identifier. If no such form was found, returns (None, None).

  Example

  In the default configuration, entering 2-ball (e.g. in a room will more than one ‘ball’ object), will lead to a multimatch and this function will parse “2-ball” and return (2, “ball”).

`evennia.commands.cmdparser.``cmdparser`(raw_string, cmdset, caller, match_index=None)

  This function is called by the cmdhandler once it has gathered and merged all valid cmdsets valid for this particular parsing.

  Parameters

    - raw_string (str) – The unparsed text entered by the caller.

    - cmdset (CmdSet) – The merged, currently valid cmdset

    - caller (Session, Account or Object) – The caller triggering this parsing.

    - match_index (int, optional) – Index to pick a given match in a list of same-named command matches. If this is given, it suggests this is not the first time this function was called: normally the first run resulted in a multimatch, and the index is given to select between the results for the second run.

  Returns

    matches (list) –

    This is a list of match-tuples as returned by create_match.

      If no matches were found, this is an empty list.

  Notes

  The cmdparser understand the following command combinations (where [] marks optional parts.

  [cmdname[ cmdname2 cmdname3 …] [the rest]

  A command may consist of any number of space-separated words of any length, and contain any character. It may also be empty.

  The parser makes use of the cmdset to find command candidates. The parser return a list of matches. Each match is a tuple with its first three elements being the parsed cmdname (lower case), the remaining arguments, and the matched cmdobject from the cmdset.