<spanid="evennia-contrib-base-systems-unixcommand-unixcommand"></span><h1>evennia.contrib.base_systems.unixcommand.unixcommand<aclass="headerlink"href="#module-evennia.contrib.base_systems.unixcommand.unixcommand"title="Permalink to this headline">¶</a></h1>
<p>Unix-like Command style parent</p>
<p>Evennia contribution, Vincent Le Geoff 2017</p>
<p>This module contains a command class that allows for unix-style command syntax in-game, using
–options, positional arguments and stuff like -n 10 etc similarly to a unix command. It might not
the best syntax for the average player but can be really useful for builders when they need to have
a single command do many things with many options. It uses the ArgumentParser from Python’s standard
library under the hood.</p>
<p>To use, inherit <strong>UnixCommand</strong> from this module from your own commands. You need
to override two methods:</p>
<ulclass="simple">
<li><dlclass="simple">
<dt>The <strong>init_parser</strong> method, which adds options to the parser. Note that you should normally</dt><dd><p><em>not</em> override the normal <strong>parse</strong> method when inheriting from <strong>UnixCommand</strong>.</p>
</dd>
</dl>
</li>
<li><p>The <strong>func</strong> method, called to execute the command once parsed (like any Command).</p></li>
<spanclass="n">default</span><spanclass="o">=</span><spanclass="mi">1</span><spanclass="p">,</span><spanclass="n">help</span><spanclass="o">=</span><spanclass="s2">"the age of the plant to be planted"</span><spanclass="p">)</span>
<spanclass="n">help</span><spanclass="o">=</span><spanclass="s2">"should the newly-planted plant be hidden to players?"</span><spanclass="p">)</span>
<p>To see the full power of argparse and the types of supported options, visit
[the documentation of argparse](<aclass="reference external"href="https://docs.python.org/2/library/argparse.html">https://docs.python.org/2/library/argparse.html</a>).</p>
<emclass="property">exception </em><codeclass="sig-prename descclassname">evennia.contrib.base_systems.unixcommand.unixcommand.</code><codeclass="sig-name descname">ParseError</code><aclass="reference internal"href="../_modules/evennia/contrib/base_systems/unixcommand/unixcommand.html#ParseError"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.contrib.base_systems.unixcommand.unixcommand.ParseError"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">__init__</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">prog</span></em>, <emclass="sig-param"><spanclass="n">description</span><spanclass="o">=</span><spanclass="default_value">''</span></em>, <emclass="sig-param"><spanclass="n">epilog</span><spanclass="o">=</span><spanclass="default_value">''</span></em>, <emclass="sig-param"><spanclass="n">command</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <emclass="sig-param"><spanclass="o">**</span><spanclass="n">kwargs</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/contrib/base_systems/unixcommand/unixcommand.html#UnixCommandParser.__init__"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.contrib.base_systems.unixcommand.unixcommand.UnixCommandParser.__init__"title="Permalink to this definition">¶</a></dt>
<dd><p>Build a UnixCommandParser with a link to the command using it.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><ulclass="simple">
<li><p><strong>prog</strong> (<em>str</em>) – the program name (usually the command key).</p></li>
<li><p><strong>description</strong> (<em>str</em>) – a very brief line to show in the usage text.</p></li>
<li><p><strong>epilog</strong> (<em>str</em>) – the epilog to show below options.</p></li>
<li><p><strong>command</strong> (<aclass="reference internal"href="evennia.commands.command.html#evennia.commands.command.Command"title="evennia.commands.command.Command"><em>Command</em></a>) – the command calling the parser.</p></li>
</ul>
</dd>
<dtclass="field-even">Keyword Arguments</dt>
<ddclass="field-even"><ulclass="simple">
<li><p><strong>keyword arguments are directly sent to</strong> (<em>Additional</em>) –</p></li>
<li><p><strong>You will find them on the</strong> (<em>argparse.ArgumentParser.</em>) –</p></li>
<codeclass="sig-name descname">format_usage</code><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/contrib/base_systems/unixcommand/unixcommand.html#UnixCommandParser.format_usage"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.contrib.base_systems.unixcommand.unixcommand.UnixCommandParser.format_usage"title="Permalink to this definition">¶</a></dt>
<dd><p>Return the usage line.</p>
<divclass="admonition note">
<pclass="admonition-title">Note</p>
<p>This method is present to return the raw-escaped usage line,
<codeclass="sig-name descname">format_help</code><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/contrib/base_systems/unixcommand/unixcommand.html#UnixCommandParser.format_help"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.contrib.base_systems.unixcommand.unixcommand.UnixCommandParser.format_help"title="Permalink to this definition">¶</a></dt>
<dd><p>Return the parser help, including its epilog.</p>
<divclass="admonition note">
<pclass="admonition-title">Note</p>
<p>This method is present to return the raw-escaped help,
in order to avoid unintentional color codes. Color codes
in the epilog (the command docstring) are supported.</p>
<codeclass="sig-name descname">print_usage</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">file</span><spanclass="o">=</span><spanclass="default_value">None</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/contrib/base_systems/unixcommand/unixcommand.html#UnixCommandParser.print_usage"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.contrib.base_systems.unixcommand.unixcommand.UnixCommandParser.print_usage"title="Permalink to this definition">¶</a></dt>
<dd><p>Print the usage to the caller.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><p><strong>file</strong> (<em>file-object</em>) – not used here, the caller is used.</p>
</dd>
</dl>
<divclass="admonition note">
<pclass="admonition-title">Note</p>
<p>This method will override <strong>argparse.ArgumentParser</strong>’s in order
to not display the help on stdout or stderr, but to the
<codeclass="sig-name descname">print_help</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">file</span><spanclass="o">=</span><spanclass="default_value">None</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/contrib/base_systems/unixcommand/unixcommand.html#UnixCommandParser.print_help"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.contrib.base_systems.unixcommand.unixcommand.UnixCommandParser.print_help"title="Permalink to this definition">¶</a></dt>
<dd><p>Print the help to the caller.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><p><strong>file</strong> (<em>file-object</em>) – not used here, the caller is used.</p>
</dd>
</dl>
<divclass="admonition note">
<pclass="admonition-title">Note</p>
<p>This method will override <strong>argparse.ArgumentParser</strong>’s in order
to not display the help on stdout or stderr, but to the
<emclass="property">class </em><codeclass="sig-prename descclassname">evennia.contrib.base_systems.unixcommand.unixcommand.</code><codeclass="sig-name descname">UnixCommand</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="o">**</span><spanclass="n">kwargs</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/contrib/base_systems/unixcommand/unixcommand.html#UnixCommand"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.contrib.base_systems.unixcommand.unixcommand.UnixCommand"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">__init__</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="o">**</span><spanclass="n">kwargs</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/contrib/base_systems/unixcommand/unixcommand.html#UnixCommand.__init__"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.contrib.base_systems.unixcommand.unixcommand.UnixCommand.__init__"title="Permalink to this definition">¶</a></dt>
<dd><p>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.</p>
<codeclass="sig-name descname">init_parser</code><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/contrib/base_systems/unixcommand/unixcommand.html#UnixCommand.init_parser"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.contrib.base_systems.unixcommand.unixcommand.UnixCommand.init_parser"title="Permalink to this definition">¶</a></dt>
<dd><p>Configure the argument parser, adding in options.</p>
<divclass="admonition note">
<pclass="admonition-title">Note</p>
<p>This method is to be overridden in order to add options
to the argument parser. Use <strong>self.parser</strong>, which contains
the <strong>argparse.ArgumentParser</strong>. You can, for instance,
<codeclass="sig-name descname">func</code><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/contrib/base_systems/unixcommand/unixcommand.html#UnixCommand.func"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.contrib.base_systems.unixcommand.unixcommand.UnixCommand.func"title="Permalink to this definition">¶</a></dt>
<dd><p>Override to handle the command execution.</p>
<codeclass="sig-name descname">get_help</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">caller</span></em>, <emclass="sig-param"><spanclass="n">cmdset</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/contrib/base_systems/unixcommand/unixcommand.html#UnixCommand.get_help"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.contrib.base_systems.unixcommand.unixcommand.UnixCommand.get_help"title="Permalink to this definition">¶</a></dt>
<dd><p>Return the help message for this command and this caller.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><ulclass="simple">
<li><p><strong>caller</strong> (<em>Object</em><em> or </em><em>Player</em>) – the caller asking for help on the command.</p></li>
<li><p><strong>cmdset</strong> (<aclass="reference internal"href="evennia.commands.cmdset.html#evennia.commands.cmdset.CmdSet"title="evennia.commands.cmdset.CmdSet"><em>CmdSet</em></a>) – the command set (if you need additional commands).</p></li>
</ul>
</dd>
<dtclass="field-even">Returns</dt>
<ddclass="field-even"><p><em>docstring (str)</em>– the help text to provide the caller for this command.</p>
<codeclass="sig-name descname">parse</code><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/contrib/base_systems/unixcommand/unixcommand.html#UnixCommand.parse"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.contrib.base_systems.unixcommand.unixcommand.UnixCommand.parse"title="Permalink to this definition">¶</a></dt>
<dd><p>Process arguments provided in <strong>self.args</strong>.</p>
<divclass="admonition note">
<pclass="admonition-title">Note</p>
<p>You should not override this method. Consider overriding
<codeclass="sig-name descname">aliases</code><emclass="property"> = []</em><aclass="headerlink"href="#evennia.contrib.base_systems.unixcommand.unixcommand.UnixCommand.aliases"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">help_category</code><emclass="property"> = 'general'</em><aclass="headerlink"href="#evennia.contrib.base_systems.unixcommand.unixcommand.UnixCommand.help_category"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">key</code><emclass="property"> = 'command'</em><aclass="headerlink"href="#evennia.contrib.base_systems.unixcommand.unixcommand.UnixCommand.key"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">lock_storage</code><emclass="property"> = 'cmd:all();'</em><aclass="headerlink"href="#evennia.contrib.base_systems.unixcommand.unixcommand.UnixCommand.lock_storage"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">search_index_entry</code><emclass="property"> = {'aliases': '', 'category': 'general', 'key': 'command', 'no_prefix': ' ', 'tags': '', 'text': '\n Unix-type commands, supporting short and long options.\n\n This command syntax uses the Unix-style commands with short options\n (-X) and long options (--something). The `argparse` module is\n used to parse the command.\n\n In order to use it, you should override two methods:\n - `init_parser`: this method is called when the command is created.\n It can be used to set options in the parser. `self.parser`\n contains the `argparse.ArgumentParser`, so you can add arguments\n here.\n - `func`: this method is called to execute the command, but after\n the parser has checked the arguments given to it are valid.\n You can access the namespace of valid arguments in `self.opts`\n at this point.\n\n The help of UnixCommands is derived from the docstring, in a\n slightly different way than usual: the first line of the docstring\n is used to represent the program description (the very short\n line at the top of the help message). The other lines below are\n used as the program\'s "epilog", displayed below the options. It\n means in your docstring, you don\'t have to write the options.\n They will be automatically provided by the parser and displayed\n accordingly. The `argparse` module provides a default \'-h\' or\n \'--help\' option on the command. Typing |whelp commandname|n will\n display the same as |wcommandname -h|n, though this behavior can\n be changed.\n\n '}</em><aclass="headerlink"href="#evennia.contrib.base_systems.unixcommand.unixcommand.UnixCommand.search_index_entry"title="Permalink to this definition">¶</a></dt>
