<spanid="evennia-commands-cmdset"></span><h1>evennia.commands.cmdset<aclass="headerlink"href="#module-evennia.commands.cmdset"title="Permalink to this headline">¶</a></h1>
<p>A Command Set (CmdSet) holds a set of commands. The Cmdsets can be
merged and combined to create new sets of commands in a
non-destructive way. This makes them very powerful for implementing
custom game states where different commands (or different variations
of commands) are available to the accounts depending on circumstance.</p>
<p>The available merge operations are partly borrowed from mathematical
Set theory.</p>
<ulclass="simple">
<li><dlclass="simple">
<dt>Union The two command sets are merged so that as many commands as</dt><dd><p>possible of each cmdset ends up in the merged cmdset. Same-name
commands are merged by priority. This is the most common default.
Ex: A1,A3 + B1,B2,B4,B5 = A1,B2,A3,B4,B5</p>
</dd>
</dl>
</li>
<li><dlclass="simple">
<dt>Intersect - Only commands found in <em>both</em> cmdsets (i.e. which have</dt><dd><p>same names) end up in the merged cmdset, with the higher-priority
<dt>Replace - The commands of this cmdset completely replaces the</dt><dd><p>lower-priority cmdset’s commands, regardless of if same-name commands
exist. Ex: A1,A3 + B1,B2,B4,B5 = A1,A3</p>
</dd>
</dl>
</li>
<li><dlclass="simple">
<dt>Remove - This removes the relevant commands from the</dt><dd><p>lower-priority cmdset completely. They are not replaced with
anything, so this in effects uses the high-priority cmdset as a filter
to affect the low-priority cmdset. Ex: A1,A3 + B1,B2,B4,B5 = B2,B4,B5</p>
</dd>
</dl>
</li>
</ul>
<dlclass="py class">
<dtid="evennia.commands.cmdset.CmdSet">
<emclass="property">class </em><codeclass="sig-prename descclassname">evennia.commands.cmdset.</code><codeclass="sig-name descname">CmdSet</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">cmdsetobj</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <emclass="sig-param"><spanclass="n">key</span><spanclass="o">=</span><spanclass="default_value">None</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/commands/cmdset.html#CmdSet"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.commands.cmdset.CmdSet"title="Permalink to this definition">¶</a></dt>
<p>This class describes a unique cmdset that understands priorities.
CmdSets can be merged and made to perform various set operations
on each other. CmdSets have priorities that affect which of their
ingoing commands gets used.</p>
<p>In the examples, cmdset A always have higher priority than cmdset B.</p>
<p>key - the name of the cmdset. This can be used on its own for game
operations</p>
<p>mergetype (partly from Set theory):</p>
<blockquote>
<div><dl>
<dt>Union - The two command sets are merged so that as many</dt><dd><p>commands as possible of each cmdset ends up in the
merged cmdset. Same-name commands are merged by
priority. This is the most common default.
Ex: A1,A3 + B1,B2,B4,B5 = A1,B2,A3,B4,B5</p>
</dd>
<dt>Intersect - Only commands found in <em>both</em> cmdsets</dt><dd><p>(i.e. which have same names) end up in the merged
cmdset, with the higher-priority cmdset replacing the
lower one. Ex: A1,A3 + B1,B2,B4,B5 = A1</p>
</dd>
<dt>Replace - The commands of this cmdset completely replaces</dt><dd><p>the lower-priority cmdset’s commands, regardless
of if same-name commands exist.
Ex: A1,A3 + B1,B2,B4,B5 = A1,A3</p>
</dd>
<dt>Remove - This removes the relevant commands from the</dt><dd><blockquote>
<div><p>lower-priority cmdset completely. They are not
replaced with anything, so this in effects uses the
high-priority cmdset as a filter to affect the
low-priority cmdset.
Ex: A1,A3 + B1,B2,B4,B5 = B2,B4,B5</p>
</div></blockquote>
<dlclass="simple">
<dt>Note: Commands longer than 2 characters and starting</dt><dd><p>with double underscrores, like ‘__noinput_command’
are considered ‘system commands’ and are
excempt from all merge operations - they are
ALWAYS included across mergers and only affected
if same-named system commands replace them.</p>
</dd>
</dl>
</dd>
</dl>
</div></blockquote>
<dl>
<dt>priority- All cmdsets are always merged in pairs of two so that</dt><dd><p>the higher set’s mergetype is applied to the
lower-priority cmdset. Default commands have priority 0,
high-priority ones like Exits and Channels have 10 and 9.
Priorities can be negative as well to give default
commands preference.</p>
</dd>
<dt>duplicates - determines what happens when two sets of equal</dt><dd><blockquote>
<div><p>priority merge (only). Defaults to None and has the first of them in the
merger (i.e. A above) automatically taking
precedence. But if <strong>duplicates</strong> is true, the
result will be a merger with more than one of each
name match. This will usually lead to the account
receiving a multiple-match error higher up the road,
but can be good for things like cmdsets on non-account
objects in a room, to allow the system to warn that
more than one ‘ball’ in the room has the same ‘kick’
command defined on it, so it may offer a chance to
select which ball to kick … Allowing duplicates
only makes sense for Union and Intersect, the setting
is ignored for the other mergetypes.
Note that the <strong>duplicates</strong> flag is <em>not</em> propagated in
a cmdset merger. So <strong>A + B = C</strong> will result in
a cmdset with duplicate commands, but C.duplicates will
be <strong>None</strong>. For duplication to apply to a whole cmdset
stack merge, _all_ cmdsets in the stack must have
<strong>.duplicates=True</strong> set.</p>
</div></blockquote>
<p>Finally, if a final cmdset has <strong>.duplicates=None</strong> (the normal
unless created alone with another value), the cmdhandler
will assume True for object-based cmdsets and False for
all other. This is usually the most intuitive outcome.</p>
</dd>
<dt>key_mergetype (dict) - allows the cmdset to define a unique</dt><dd><p>mergetype for particular cmdsets. Format is
{CmdSetkeystring:mergetype}. Priorities still apply.
Example: {‘Myevilcmdset’,’Replace’} which would make
sure for this set to always use ‘Replace’ on
Myevilcmdset no matter what overall mergetype this set
has.</p>
</dd>
<dt>no_objs - don’t include any commands from nearby objects</dt><dd><p>when searching for suitable commands</p>
</dd>
<dt>no_exits - ignore the names of exits when matching against</dt><dd><p>commands</p>
</dd>
<dt>no_channels - ignore the name of channels when matching against</dt><dd><p>commands (WARNING- this is dangerous since the
account can then not even ask staff for help if
something goes wrong)</p>
</dd>
</dl>
<dlclass="py attribute">
<dtid="evennia.commands.cmdset.CmdSet.mergetype">
<codeclass="sig-name descname">mergetype</code><emclass="property"> = 'Union'</em><aclass="headerlink"href="#evennia.commands.cmdset.CmdSet.mergetype"title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dlclass="py attribute">
<dtid="evennia.commands.cmdset.CmdSet.priority">
<codeclass="sig-name descname">priority</code><emclass="property"> = 0</em><aclass="headerlink"href="#evennia.commands.cmdset.CmdSet.priority"title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dlclass="py attribute">
<dtid="evennia.commands.cmdset.CmdSet.no_exits">
<codeclass="sig-name descname">no_exits</code><emclass="property"> = None</em><aclass="headerlink"href="#evennia.commands.cmdset.CmdSet.no_exits"title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dlclass="py attribute">
<dtid="evennia.commands.cmdset.CmdSet.no_objs">
<codeclass="sig-name descname">no_objs</code><emclass="property"> = None</em><aclass="headerlink"href="#evennia.commands.cmdset.CmdSet.no_objs"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">no_channels</code><emclass="property"> = None</em><aclass="headerlink"href="#evennia.commands.cmdset.CmdSet.no_channels"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">duplicates</code><emclass="property"> = None</em><aclass="headerlink"href="#evennia.commands.cmdset.CmdSet.duplicates"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">persistent</code><emclass="property"> = False</em><aclass="headerlink"href="#evennia.commands.cmdset.CmdSet.persistent"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">key_mergetypes</code><emclass="property"> = {}</em><aclass="headerlink"href="#evennia.commands.cmdset.CmdSet.key_mergetypes"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">errmessage</code><emclass="property"> = ''</em><aclass="headerlink"href="#evennia.commands.cmdset.CmdSet.errmessage"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">to_duplicate</code><emclass="property"> = ('key', 'cmdsetobj', 'no_exits', 'no_objs', 'no_channels', 'persistent', 'mergetype', 'priority', 'duplicates', 'errmessage')</em><aclass="headerlink"href="#evennia.commands.cmdset.CmdSet.to_duplicate"title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dlclass="py method">
<dtid="evennia.commands.cmdset.CmdSet.__init__">
<codeclass="sig-name descname">__init__</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">cmdsetobj</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <emclass="sig-param"><spanclass="n">key</span><spanclass="o">=</span><spanclass="default_value">None</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/commands/cmdset.html#CmdSet.__init__"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.commands.cmdset.CmdSet.__init__"title="Permalink to this definition">¶</a></dt>
<dd><p>Creates a new CmdSet instance.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><ulclass="simple">
<li><p><strong>cmdsetobj</strong> (<aclass="reference internal"href="evennia.server.session.html#evennia.server.session.Session"title="evennia.server.session.Session"><em>Session</em></a><em>, </em><em>Account</em><em>, </em><em>Object</em><em>, </em><em>optional</em>) – This is the database object
to which this particular instance of cmdset is related. It
is often a character but may also be a regular object, Account
or Session.</p></li>
<li><p><strong>key</strong> (<em>str</em><em>, </em><em>optional</em>) – The idenfier for this cmdset. This
helps if wanting to selectively remov cmdsets.</p></li>
</ul>
</dd>
</dl>
</dd></dl>
<dlclass="py attribute">
<dtid="evennia.commands.cmdset.CmdSet.key">
<codeclass="sig-name descname">key</code><emclass="property"> = 'Unnamed CmdSet'</em><aclass="headerlink"href="#evennia.commands.cmdset.CmdSet.key"title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dlclass="py method">
<dtid="evennia.commands.cmdset.CmdSet.add">
<codeclass="sig-name descname">add</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">cmd</span></em>, <emclass="sig-param"><spanclass="n">allow_duplicates</span><spanclass="o">=</span><spanclass="default_value">False</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/commands/cmdset.html#CmdSet.add"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.commands.cmdset.CmdSet.add"title="Permalink to this definition">¶</a></dt>
<dd><p>Add a new command or commands to this CmdSet, a list of
commands or a cmdset to this cmdset. Note that this is <em>not</em>
a merge operation (that is handled by the + operator).</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><ulclass="simple">
<li><p><strong>cmd</strong> (<aclass="reference internal"href="evennia.commands.command.html#evennia.commands.command.Command"title="evennia.commands.command.Command"><em>Command</em></a><em>, </em><em>list</em><em>, </em><em>Cmdset</em>) – This allows for adding one or
more commands to this Cmdset in one go. If another Cmdset
is given, all its commands will be added.</p></li>
<li><p><strong>allow_duplicates</strong> (<em>bool</em><em>, </em><em>optional</em>) – If set, will not try to remove
duplicate cmds in the set. This is needed during the merge process
to avoid wiping commands coming from cmdsets with duplicate=True.</p></li>
</ul>
</dd>
</dl>
<pclass="rubric">Notes</p>
<p>If cmd already exists in set, it will replace the old one
(no priority checking etc happens here). This is very useful
when overloading default commands).</p>
<p>If cmd is another cmdset class or -instance, the commands of
that command set is added to this one, as if they were part of
the original cmdset definition. No merging or priority checks
are made, rather later added commands will simply replace
existing ones to make a unique set.</p>
</dd></dl>
<dlclass="py method">
<dtid="evennia.commands.cmdset.CmdSet.remove">
<codeclass="sig-name descname">remove</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">cmd</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/commands/cmdset.html#CmdSet.remove"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.commands.cmdset.CmdSet.remove"title="Permalink to this definition">¶</a></dt>
<dd><p>Remove a command instance from the cmdset.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><p><strong>cmd</strong> (<aclass="reference internal"href="evennia.commands.command.html#evennia.commands.command.Command"title="evennia.commands.command.Command"><em>Command</em></a><em> or </em><em>str</em>) – Either the Command object to remove
or the key of such a command.</p>
</dd>
</dl>
</dd></dl>
<dlclass="py method">
<dtid="evennia.commands.cmdset.CmdSet.get">
<codeclass="sig-name descname">get</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">cmd</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/commands/cmdset.html#CmdSet.get"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.commands.cmdset.CmdSet.get"title="Permalink to this definition">¶</a></dt>
<dd><p>Get a command from the cmdset. This is mostly useful to
check if the command is part of this cmdset or not.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><p><strong>cmd</strong> (<aclass="reference internal"href="evennia.commands.command.html#evennia.commands.command.Command"title="evennia.commands.command.Command"><em>Command</em></a><em> or </em><em>str</em>) – Either the Command object or its key.</p>
</dd>
<dtclass="field-even">Returns</dt>
<ddclass="field-even"><p><em>cmd (Command)</em>– The first matching Command in the set.</p>
</dd>
</dl>
</dd></dl>
<dlclass="py method">
<dtid="evennia.commands.cmdset.CmdSet.count">
<codeclass="sig-name descname">count</code><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/commands/cmdset.html#CmdSet.count"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.commands.cmdset.CmdSet.count"title="Permalink to this definition">¶</a></dt>
<dd><p>Number of commands in set.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Returns</dt>
<ddclass="field-odd"><p><em>N (int)</em>– Number of commands in this Cmdset.</p>
<codeclass="sig-name descname">get_system_cmds</code><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/commands/cmdset.html#CmdSet.get_system_cmds"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.commands.cmdset.CmdSet.get_system_cmds"title="Permalink to this definition">¶</a></dt>
<dd><p>Get system commands in cmdset</p>
<dlclass="field-list simple">
<dtclass="field-odd">Returns</dt>
<ddclass="field-odd"><p><em>sys_cmds (list)</em>– The system commands in the set.</p>
</dd>
</dl>
<pclass="rubric">Notes</p>
<p>As far as the Cmdset is concerned, system commands are any
commands with a key starting with double underscore __.
<codeclass="sig-name descname">make_unique</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">caller</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/commands/cmdset.html#CmdSet.make_unique"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.commands.cmdset.CmdSet.make_unique"title="Permalink to this definition">¶</a></dt>
<dd><p>Remove duplicate command-keys (unsafe)</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><p><strong>caller</strong> (<em>object</em>) – Commands on this object will
get preference in the duplicate removal.</p>
</dd>
</dl>
<pclass="rubric">Notes</p>
<p>This is an unsafe command meant to clean out a cmdset of
doublet commands after it has been created. It is useful
for commands inheriting cmdsets from the cmdhandler where
obj-based cmdsets always are added double. Doublets will
be weeded out with preference to commands defined on
caller, otherwise just by first-come-first-served.</p>
<codeclass="sig-name descname">get_all_cmd_keys_and_aliases</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">caller</span><spanclass="o">=</span><spanclass="default_value">None</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/commands/cmdset.html#CmdSet.get_all_cmd_keys_and_aliases"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.commands.cmdset.CmdSet.get_all_cmd_keys_and_aliases"title="Permalink to this definition">¶</a></dt>
<dd><p>Collects keys/aliases from commands</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><p><strong>caller</strong> (<em>Object</em><em>, </em><em>optional</em>) – If set, this is used to check access permissions
on each command. Only commands that pass are returned.</p>
<dt>A list of all command keys and aliases in this cmdset. If <strong>caller</strong></dt><dd><p>was given, this list will only contain commands to which <strong>caller</strong> passed
<codeclass="sig-name descname">at_cmdset_creation</code><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/commands/cmdset.html#CmdSet.at_cmdset_creation"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.commands.cmdset.CmdSet.at_cmdset_creation"title="Permalink to this definition">¶</a></dt>
<dd><p>Hook method - this should be overloaded in the inheriting
class, and should take care of populating the cmdset by use of
self.add().</p>
</dd></dl>
<dlclass="py attribute">
<dtid="evennia.commands.cmdset.CmdSet.path">
<codeclass="sig-name descname">path</code><emclass="property"> = 'evennia.commands.cmdset.CmdSet'</em><aclass="headerlink"href="#evennia.commands.cmdset.CmdSet.path"title="Permalink to this definition">¶</a></dt>
