evennia.commands.default.muxcommand

The command template for the default MUX-style command set. There is also an Account/OOC version that makes sure caller is an Account object.

class evennia.commands.default.muxcommand.MuxCommand(**kwargs)

Bases: Command

This sets up the basis for a MUX command. The idea is that most other Mux-related commands should just inherit from this and don’t have to implement much parsing of their own unless they do something particularly advanced.

Note that the class’s __doc__ string (this text) is used by Evennia to create the automatic help entry for the command, so make sure to document consistently here.

has_perm(srcobj)

This is called by the cmdhandler to determine if srcobj is allowed to execute this command. We just show it here for completeness - we are satisfied using the default check in Command.

at_pre_cmd()

This hook is called before self.parse() on all commands

at_post_cmd()

This hook is called after the command has finished executing (after self.func()).

parse()

This method is called by the cmdhandler once the command name has been identified. It creates a new set of member variables that can be later accessed from self.func() (see below)

The following variables are available for our use when entering this method (from the command definition, and assigned on the fly by the cmdhandler):

self.key - the name of this command (‘look’) self.aliases - the aliases of this cmd (‘l’) self.permissions - permission string for this command self.help_category - overall category of command

self.caller - the object calling this command self.cmdstring - the actual command name used to call this

(this allows you to know which alias was used,

for example)

self.args - the raw input; everything following self.cmdstring. self.cmdset - the cmdset from which this command was picked. Not

often used (useful for commands like ‘help’ or to list all available commands etc)

self.obj - the object on which this command was defined. It is often

the same as self.caller.

A MUX command has the following possible syntax:

name[ with several words][/switch[/switch..]] arg1[,arg2,…] [[=|,] arg[,..]]

The ‘name[ with several words]’ part is already dealt with by the cmdhandler at this point, and stored in self.cmdname (we don’t use it here). The rest of the command is stored in self.args, which can start with the switch indicator /.

Optional variables to aid in parsing, if set:

self.switch_options - (tuple of valid /switches expected by this

command (without the /))

self.rhs_split - Alternate string delimiter or tuple of strings

to separate left/right hand sides. tuple form gives priority split to first string delimiter.

This parser breaks self.args into its constituents and stores them in the following variables:

self.switches = [list of /switches (without the /)] self.raw = This is the raw argument input, including switches self.args = This is re-defined to be everything except the switches self.lhs = Everything to the left of = (lhs:’left-hand side’). If

no = is found, this is identical to self.args.

self.rhs: Everything to the right of = (rhs:’right-hand side’).

If no ‘=’ is found, this is None.

self.lhslist - [self.lhs split into a list by comma] self.rhslist - [list of self.rhs split into a list by comma] self.arglist = [list of space-separated args (stripped, including ‘=’ if it exists)]

All args and list members are stripped of excess whitespace around the strings, but case is preserved.

get_command_info()

Update of parent class’s get_command_info() for MuxCommand.

func()

This is the hook function that actually does all the work. It is called

by the cmdhandler right after self.parser() finishes, and so has access to all the variables defined therein.

aliases = []

help_category = 'general'

key = 'command'

lock_storage = 'cmd:all();'

search_index_entry = {'aliases': '', 'category': 'general', 'key': 'command', 'no_prefix': ' ', 'tags': '', 'text': "\nThis sets up the basis for a MUX command. The idea\nis that most other Mux-related commands should just\ninherit from this and don't have to implement much\nparsing of their own unless they do something particularly\nadvanced.\n\nNote that the class's __doc__ string (this text) is\nused by Evennia to create the automatic help entry for\nthe command, so make sure to document consistently here.\n"}

class evennia.commands.default.muxcommand.MuxAccountCommand(**kwargs)

Bases: MuxCommand

This is an on-Account version of the MuxCommand. Since these commands sit on Accounts rather than on Characters/Objects, we need to check this in the parser.

Account commands are available also when puppeting a Character, it’s just that they are applied with a lower priority and are always available, also when disconnected from a character (i.e. “ooc”).

This class makes sure that caller is always an Account object, while creating a new property “character” that is set only if a character is actually attached to this Account and Session.

account_caller = True

aliases = []

help_category = 'general'

key = 'command'

lock_storage = 'cmd:all();'

search_index_entry = {'aliases': '', 'category': 'general', 'key': 'command', 'no_prefix': ' ', 'tags': '', 'text': '\nThis is an on-Account version of the MuxCommand. Since these commands sit\non Accounts rather than on Characters/Objects, we need to check\nthis in the parser.\n\nAccount commands are available also when puppeting a Character, it\'s\njust that they are applied with a lower priority and are always\navailable, also when disconnected from a character (i.e. "ooc").\n\nThis class makes sure that caller is always an Account object, while\ncreating a new property "character" that is set only if a\ncharacter is actually attached to this Account and Session.\n'}

class evennia.commands.default.muxcommand.Command(**kwargs)

Bases: object

Base command

(you may see this if a child command had no help text defined)

Usage:

command [args]

This is the base command class. Inherit from this to create new commands.

The cmdhandler makes the following variables available to the command methods (so you can always assume them to be there):

self.caller - the game object calling the command self.cmdstring - the command name used to trigger this command (allows

you to know which alias was used, for example)

self.args - everything supplied to the command following the cmdstring

(this is usually what is parsed in self.parse())

self.cmdset - the merged cmdset from which this command was matched (useful only

seldomly, notably for help-type commands, to create dynamic help entries and lists)

self.cmdset_source - the specific cmdset this command was matched from. self.obj - the object on which this command is defined. If a default command,

this is usually the same as caller.

self.raw_string - the full raw string input, including the command name,

any args and no parsing.

The following class properties can/should be defined on your child class:

key - identifier for command (e.g. “look”) aliases - (optional) list of aliases (e.g. [“l”, “loo”]) locks - lock string (default is “cmd:all()”) help_category - how to organize this help entry in help system

(default is “General”)

auto_help - defaults to True. Allows for turning off auto-help generation arg_regex - (optional) raw string regex defining how the argument part of

the command should look in order to match for this command (e.g. must it be a space between cmdname and arg?)

auto_help_display_key - (optional) if given, this replaces the string shown

in the auto-help listing. This is particularly useful for system-commands whose actual key is not really meaningful.

(Note that if auto_help is on, this initial string is also used by the system to create the help entry for the command, so it’s a good idea to format it similar to this one). This behavior can be changed by overriding the method ‘get_help’ of a command: by default, this method returns cmd.__doc__ (that is, this very docstring, or the docstring of your command). You can, however, extend or replace this without disabling auto_help.

__init__(**kwargs)

The lockhandler works the same as for objects. optional kwargs will be set as properties on the Command at runtime, overloading evential same-named class properties.

access(srcobj, access_type='cmd', default=False)

This hook is called by the cmdhandler to determine if srcobj is allowed to execute this command. It should return a boolean value and is not normally something that need to be changed since it’s using the Evennia permission system directly.

Parameters:

• srcobj (Object) – Object trying to gain permission

• access_type (str, optional) – The lock type to check.

• default (bool, optional) – The fallback result if no lock of matching access_type is found on this Command.

aliases = []

arg_regex = re.compile('^[ /]|\\n|$', re.IGNORECASE)

at_post_cmd()

This hook is called after the command has finished executing (after self.func()).

at_pre_cmd()

This hook is called before self.parse() on all commands. If this hook returns anything but False/None, the command sequence is aborted.

auto_help = True

client_width()

Get the client screenwidth for the session using this command.

Returns:

client width (int) – The width (in characters) of the client window.

execute_cmd(raw_string, session=None, obj=None, **kwargs)

A shortcut of execute_cmd on the caller. It appends the session automatically.

Parameters:

• raw_string (str) – Execute this string as a command input.

• session (Session, optional) – If not given, the current command’s Session will be used.

• obj (Object or Account, optional) – Object or Account on which to call the execute_cmd. If not given, self.caller will be used.

Keyword Arguments:

• command (Other keyword arguments will be added to the found)

• is (object instace as variables before it executes. This)

• and (unused by default Evennia but may be used to set flags)

• run-time. (change operating paramaters for commands at)

func()

This is the actual executing part of the command. It is called directly after self.parse(). See the docstring of this module for which object properties are available (beyond those set in self.parse())

get_command_info()

This is the default output of func() if no func() overload is done. Provided here as a separate method so that it can be called for debugging purposes when making commands.

get_extra_info(caller, **kwargs)

Display some extra information that may help distinguish this command from others, for instance, in a disambiguity prompt.

If this command is a potential match in an ambiguous situation, one distinguishing feature may be its attachment to a nearby object, so we include this if available.

Parameters:

• caller (TypedObject) – The caller who typed an ambiguous

• function. (term handed to the search)

Returns:

A string with identifying information to disambiguate the object, conventionally with a preceding space.

get_help(caller, cmdset)

Return the help message for this command and this caller.

By default, return self.__doc__ (the docstring just under the class definition). You can override this behavior, though, and even customize it depending on the caller, or other commands the caller can use.

Parameters:

• caller (Object or Account) – the caller asking for help on the command.

• cmdset (CmdSet) – the command set (if you need additional commands).

Returns:

docstring (str) – the help text to provide the caller for this command.

help_category = 'general'

is_exit = False

key = 'command'

lock_storage = 'cmd:all();'

lockhandler

locks = 'cmd:all();'

match(cmdname, include_prefixes=True)

This is called by the system when searching the available commands, in order to determine if this is the one we wanted. cmdname was previously extracted from the raw string by the system.

Parameters:

cmdname (str) – Always lowercase when reaching this point.

Kwargs:

include_prefixes (bool): If false, will compare against the _noprefix

variants of commandnames.

Returns:

result (bool) – Match result.

msg(text=None, to_obj=None, from_obj=None, session=None, **kwargs)

This is a shortcut instead of calling msg() directly on an object - it will detect if caller is an Object or an Account and also appends self.session automatically if self.msg_all_sessions is False.

Parameters:

• text (str, optional) – Text string of message to send.

• to_obj (Object, optional) – Target object of message. Defaults to self.caller.

• from_obj (Object, optional) – Source of message. Defaults to to_obj.

• session (Session, optional) – Supply data only to a unique session (ignores the value of self.msg_all_sessions).

Keyword Arguments:

• options (dict) – Options to the protocol.

• any (any) – All other keywords are interpreted as th name of send-instructions.

msg_all_sessions = False

parse()

Once the cmdhandler has identified this as the command we want, this function is run. If many of your commands have a similar syntax (for example ‘cmd arg1 = arg2’) you should simply define this once and just let other commands of the same form inherit from this. See the docstring of this module for which object properties are available to use (notably self.args).

retain_instance = False

save_for_next = False

search_index_entry = {'aliases': '', 'category': 'general', 'key': 'command', 'no_prefix': ' ', 'tags': '', 'text': '\n## Base command\n\n(you may see this if a child command had no help text defined)\n\nUsage:\n  command [args]\n\nThis is the base command class. Inherit from this\nto create new commands.\n\nThe cmdhandler makes the following variables available to the\ncommand methods (so you can always assume them to be there):\n\nself.caller - the game object calling the command\nself.cmdstring - the command name used to trigger this command (allows\n                 you to know which alias was used, for example)\nself.args - everything supplied to the command following the cmdstring\n           (this is usually what is parsed in self.parse())\nself.cmdset - the merged cmdset from which this command was matched (useful only\n              seldomly, notably for help-type commands, to create dynamic\n              help entries and lists)\nself.cmdset_source - the specific cmdset this command was matched from.\nself.obj - the object on which this command is defined. If a default command,\n           this is usually the same as caller.\nself.raw_string - the full raw string input, including the command name,\n                  any args and no parsing.\n\nThe following class properties can/should be defined on your child class:\n\nkey - identifier for command (e.g. "look")\naliases - (optional) list of aliases (e.g. ["l", "loo"])\nlocks - lock string (default is "cmd:all()")\nhelp_category - how to organize this help entry in help system\n                (default is "General")\nauto_help - defaults to True. Allows for turning off auto-help generation\narg_regex - (optional) raw string regex defining how the argument part of\n            the command should look in order to match for this command\n            (e.g. must it be a space between cmdname and arg?)\nauto_help_display_key - (optional) if given, this replaces the string shown\n    in the auto-help listing. This is particularly useful for system-commands\n    whose actual key is not really meaningful.\n\n(Note that if auto_help is on, this initial string is also used by the\nsystem to create the help entry for the command, so it\'s a good idea to\nformat it similar to this one).  This behavior can be changed by\noverriding the method \'get_help\' of a command: by default, this\nmethod returns cmd.__doc__ (that is, this very docstring, or\nthe docstring of your command).  You can, however, extend or\nreplace this without disabling auto_help.\n'}

set_aliases(new_aliases)

Replace aliases with new ones.

Parameters:

new_aliases (str or list) – Either a ;-separated string or a list of aliases. These aliases will replace the existing ones, if any.

Notes

This is necessary to use to make sure the optimization caches are properly updated as well.

set_key(new_key)

Update key.

Parameters:

new_key (str) – The new key.

Notes

This is necessary to use to make sure the optimization caches are properly updated as well.

styled_footer(*args, **kwargs)

Create a pretty footer.

styled_header(*args, **kwargs)

Create a pretty header.

styled_separator(*args, **kwargs)

Create a separator.

styled_table(*args, **kwargs)

Create an EvTable styled by on user preferences.

Parameters:

*args (str) – Column headers. If not colored explicitly, these will get colors from user options.

Keyword Arguments:

any (str, int or dict) – EvTable options, including, optionally a table dict detailing the contents of the table.

Returns:

table (EvTable) –

An initialized evtable entity, either complete (if using table kwarg)

or incomplete and ready for use with .add_row or .add_collumn.

web_get_admin_url()

Returns the URI path for the Django Admin page for this object.

ex. Account#1 = ‘/admin/accounts/accountdb/1/change/’

Returns:

path (str) – URI path to Django Admin page for object.

web_get_detail_url()

Returns the URI path for a View that allows users to view details for this object.

ex. Oscar (Character) = ‘/characters/oscar/1/’

For this to work, the developer must have defined a named view somewhere in urls.py that follows the format ‘modelname-action’, so in this case a named view of ‘character-detail’ would be referenced by this method.

ex.

url(r'characters/(?P<slug>[\w\d\-]+)/(?P<pk>[0-9]+)/$',
    CharDetailView.as_view(), name='character-detail')

If no View has been created and defined in urls.py, returns an HTML anchor.

This method is naive and simply returns a path. Securing access to the actual view and limiting who can view this object is the developer’s responsibility.

Returns:

path (str) – URI path to object detail page, if defined.