Andreas/evennia
1
0
Fork 0
mirror of https://github.com/evennia/evennia.git synced 2026-03-27 02:06:32 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions
evennia/docs/latest/api/evennia.contrib.base_systems.unixcommand.unixcommand.html
Evennia docbuilder action 243d596662 Updated HTML docs.
2025-08-15 18:14:21 +00:00

491 lines
No EOL
49 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html>
<html lang="en" data-content_root="../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>evennia.contrib.base_systems.unixcommand.unixcommand &#8212; Evennia latest documentation</title>
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=d75fae25" />
<link rel="stylesheet" type="text/css" href="../_static/nature.css?v=279e0f84" />
<link rel="stylesheet" type="text/css" href="../_static/custom.css?v=e4a91a55" />
<script src="../_static/documentation_options.js?v=c6e86fd7"></script>
<script src="../_static/doctools.js?v=9bcbadda"></script>
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
<link rel="icon" href="../_static/favicon.ico"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="evennia.contrib.full_systems" href="evennia.contrib.full_systems.html" />
<link rel="prev" title="evennia.contrib.base_systems.unixcommand.tests" href="evennia.contrib.base_systems.unixcommand.tests.html" />
</head><body>
<div class="related" role="navigation" aria-label="Related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="evennia.contrib.full_systems.html" title="evennia.contrib.full_systems"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="evennia.contrib.base_systems.unixcommand.tests.html" title="evennia.contrib.base_systems.unixcommand.tests"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia</a> &#187;</li>
<li class="nav-item nav-item-1"><a href="../Evennia-API.html" >API Summary</a> &#187;</li>
<li class="nav-item nav-item-2"><a href="evennia-api.html" >evennia</a> &#187;</li>
<li class="nav-item nav-item-3"><a href="evennia.html" >evennia</a> &#187;</li>
<li class="nav-item nav-item-4"><a href="evennia.contrib.html" >evennia.contrib</a> &#187;</li>
<li class="nav-item nav-item-5"><a href="evennia.contrib.base_systems.html" >evennia.contrib.base_systems</a> &#187;</li>
<li class="nav-item nav-item-6"><a href="evennia.contrib.base_systems.unixcommand.html" accesskey="U">evennia.contrib.base_systems.unixcommand</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">evennia.contrib.base_systems.unixcommand.unixcommand</a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="module-evennia.contrib.base_systems.unixcommand.unixcommand">
<span id="evennia-contrib-base-systems-unixcommand-unixcommand"></span><h1>evennia.contrib.base_systems.unixcommand.unixcommand<a class="headerlink" href="#module-evennia.contrib.base_systems.unixcommand.unixcommand" title="Link to this heading"></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>
<ul class="simple">
<li><dl class="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>
</ul>
<p>Here’s a short example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">evennia.contrib.base_systems.unixcommand</span><span class="w"> </span><span class="kn">import</span> <span class="n">UnixCommand</span>
<span class="k">class</span><span class="w"> </span><span class="nc">CmdPlant</span><span class="p">(</span><span class="n">UnixCommand</span><span class="p">):</span>
<span class="w"> </span><span class="sd">&#39;&#39;&#39;</span>
<span class="sd"> Plant a tree or plant.</span>
<span class="sd"> This command is used to plant something in the room you are in.</span>
<span class="sd"> Examples:</span>
<span class="sd"> plant orange -a 8</span>
<span class="sd"> plant strawberry --hidden</span>
<span class="sd"> plant potato --hidden --age 5</span>
<span class="sd"> &#39;&#39;&#39;</span>
<span class="n">key</span> <span class="o">=</span> <span class="s2">&quot;plant&quot;</span>
<span class="k">def</span><span class="w"> </span><span class="nf">init_parser</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="s2">&quot;Add the arguments to the parser.&quot;</span>
<span class="c1"># &#39;self.parser&#39; inherits **argparse.ArgumentParser**</span>
<span class="bp">self</span><span class="o">.</span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s2">&quot;key&quot;</span><span class="p">,</span>
<span class="n">help</span><span class="o">=</span><span class="s2">&quot;the key of the plant to be planted here&quot;</span><span class="p">)</span>
<span class="bp">self</span><span class="o">.</span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s2">&quot;-a&quot;</span><span class="p">,</span> <span class="s2">&quot;--age&quot;</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="nb">int</span><span class="p">,</span>
<span class="n">default</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s2">&quot;the age of the plant to be planted&quot;</span><span class="p">)</span>
<span class="bp">self</span><span class="o">.</span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s2">&quot;--hidden&quot;</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">&quot;store_true&quot;</span><span class="p">,</span>
<span class="n">help</span><span class="o">=</span><span class="s2">&quot;should the newly-planted plant be hidden to players?&quot;</span><span class="p">)</span>
<span class="k">def</span><span class="w"> </span><span class="nf">func</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="s2">&quot;func is called only if the parser succeeded.&quot;</span>
<span class="c1"># &#39;self.opts&#39; contains the parsed options</span>
<span class="n">key</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">opts</span><span class="o">.</span><span class="n">key</span>
<span class="n">age</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">opts</span><span class="o">.</span><span class="n">age</span>
<span class="n">hidden</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">opts</span><span class="o">.</span><span class="n">hidden</span>
<span class="bp">self</span><span class="o">.</span><span class="n">msg</span><span class="p">(</span><span class="s2">&quot;Going to plant &#39;</span><span class="si">{}</span><span class="s2">&#39;, age=</span><span class="si">{}</span><span class="s2">, hidden=</span><span class="si">{}</span><span class="s2">.&quot;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span>
<span class="n">key</span><span class="p">,</span> <span class="n">age</span><span class="p">,</span> <span class="n">hidden</span><span class="p">))</span>
</pre></div>
</div>
<p>To see the full power of argparse and the types of supported options, visit
[the documentation of argparse](<a class="reference external" href="https://docs.python.org/2/library/argparse.html">https://docs.python.org/2/library/argparse.html</a>).</p>
<dl class="py exception">
<dt class="sig sig-object py" id="evennia.contrib.base_systems.unixcommand.unixcommand.ParseError">
<em class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">evennia.contrib.base_systems.unixcommand.unixcommand.</span></span><span class="sig-name descname"><span class="pre">ParseError</span></span><a class="reference internal" href="../_modules/evennia/contrib/base_systems/unixcommand/unixcommand.html#ParseError"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.contrib.base_systems.unixcommand.unixcommand.ParseError" title="Link to this definition"></a></dt>
<dd><p>Bases: <code class="xref py py-class docutils literal notranslate"><span class="pre">Exception</span></code></p>
<p>An error occurred during parsing.</p>
</dd></dl>
<dl class="py class">
<dt class="sig sig-object py" id="evennia.contrib.base_systems.unixcommand.unixcommand.UnixCommandParser">
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">evennia.contrib.base_systems.unixcommand.unixcommand.</span></span><span class="sig-name descname"><span class="pre">UnixCommandParser</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">prog</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">description</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">''</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">epilog</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">''</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">command</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/contrib/base_systems/unixcommand/unixcommand.html#UnixCommandParser"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.contrib.base_systems.unixcommand.unixcommand.UnixCommandParser" title="Link to this definition"></a></dt>
<dd><p>Bases: <code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></p>
<p>A modifier command parser for unix commands.</p>
<p>This parser is used to replace <strong>argparse.ArgumentParser</strong>. It
is aware of the command calling it, and can more easily report to
the caller. Some features (like the “brutal exit” of the original
parser) are disabled or replaced. This parser is used by UnixCommand
and creating one directly isn’t recommended nor necessary. Even
adding a sub-command will use this replaced parser automatically.</p>
<dl class="py method">
<dt class="sig sig-object py" id="evennia.contrib.base_systems.unixcommand.unixcommand.UnixCommandParser.__init__">
<span class="sig-name descname"><span class="pre">__init__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">prog</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">description</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">''</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">epilog</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">''</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">command</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/contrib/base_systems/unixcommand/unixcommand.html#UnixCommandParser.__init__"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.contrib.base_systems.unixcommand.unixcommand.UnixCommandParser.__init__" title="Link to this definition"></a></dt>
<dd><p>Build a UnixCommandParser with a link to the command using it.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="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> (<a class="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>
<dt class="field-even">Keyword Arguments<span class="colon">:</span></dt>
<dd class="field-even"><ul class="simple">
<li><p><strong>to</strong> (<em>Additional keyword arguments are directly sent</em>)</p></li>
<li><p><strong>the</strong> (<em>argparse.ArgumentParser. You will find them on</em>)</p></li>
<li><p><strong>documentation</strong><strong>]</strong><strong>(</strong><strong>https</strong> (<em>[</em><em>parser's</em>) – //docs.python.org/2/library/argparse.html).</p></li>
</ul>
</dd>
</dl>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>It’s doubtful you would need to create this parser manually.
The <strong>UnixCommand</strong> does that automatically. If you create
sub-commands, this class will be used.</p>
</div>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="evennia.contrib.base_systems.unixcommand.unixcommand.UnixCommandParser.format_usage">
<span class="sig-name descname"><span class="pre">format_usage</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/contrib/base_systems/unixcommand/unixcommand.html#UnixCommandParser.format_usage"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.contrib.base_systems.unixcommand.unixcommand.UnixCommandParser.format_usage" title="Link to this definition"></a></dt>
<dd><p>Return the usage line.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>This method is present to return the raw-escaped usage line,
in order to avoid unintentional color codes.</p>
</div>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="evennia.contrib.base_systems.unixcommand.unixcommand.UnixCommandParser.format_help">
<span class="sig-name descname"><span class="pre">format_help</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/contrib/base_systems/unixcommand/unixcommand.html#UnixCommandParser.format_help"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.contrib.base_systems.unixcommand.unixcommand.UnixCommandParser.format_help" title="Link to this definition"></a></dt>
<dd><p>Return the parser help, including its epilog.</p>
<div class="admonition note">
<p class="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>
</div>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="evennia.contrib.base_systems.unixcommand.unixcommand.UnixCommandParser.print_usage">
<span class="sig-name descname"><span class="pre">print_usage</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">file</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/contrib/base_systems/unixcommand/unixcommand.html#UnixCommandParser.print_usage"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.contrib.base_systems.unixcommand.unixcommand.UnixCommandParser.print_usage" title="Link to this definition"></a></dt>
<dd><p>Print the usage to the caller.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>file</strong> (<em>file-object</em>) – not used here, the caller is used.</p>
</dd>
</dl>
<div class="admonition note">
<p class="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
command’s caller.</p>
</div>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="evennia.contrib.base_systems.unixcommand.unixcommand.UnixCommandParser.print_help">
<span class="sig-name descname"><span class="pre">print_help</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">file</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/contrib/base_systems/unixcommand/unixcommand.html#UnixCommandParser.print_help"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.contrib.base_systems.unixcommand.unixcommand.UnixCommandParser.print_help" title="Link to this definition"></a></dt>
<dd><p>Print the help to the caller.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>file</strong> (<em>file-object</em>) – not used here, the caller is used.</p>
</dd>
</dl>
<div class="admonition note">
<p class="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
command’s caller.</p>
</div>
</dd></dl>
</dd></dl>
<dl class="py class">
<dt class="sig sig-object py" id="evennia.contrib.base_systems.unixcommand.unixcommand.HelpAction">
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">evennia.contrib.base_systems.unixcommand.unixcommand.</span></span><span class="sig-name descname"><span class="pre">HelpAction</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">option_strings</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">dest</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">nargs</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">const</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">default</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">type</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">choices</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">required</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">help</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">metavar</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">deprecated</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/contrib/base_systems/unixcommand/unixcommand.html#HelpAction"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.contrib.base_systems.unixcommand.unixcommand.HelpAction" title="Link to this definition"></a></dt>
<dd><p>Bases: <code class="xref py py-class docutils literal notranslate"><span class="pre">Action</span></code></p>
<p>Override the -h/–help action in the default parser.</p>
<p>Using the default -h/–help will call the exit function in different
ways, preventing the entire help message to be provided. Hence
this override.</p>
</dd></dl>
<dl class="py class">
<dt class="sig sig-object py" id="evennia.contrib.base_systems.unixcommand.unixcommand.UnixCommand">
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">evennia.contrib.base_systems.unixcommand.unixcommand.</span></span><span class="sig-name descname"><span class="pre">UnixCommand</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/contrib/base_systems/unixcommand/unixcommand.html#UnixCommand"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.contrib.base_systems.unixcommand.unixcommand.UnixCommand" title="Link to this definition"></a></dt>
<dd><p>Bases: <a class="reference internal" href="evennia.commands.command.html#evennia.commands.command.Command" title="evennia.commands.command.Command"><code class="xref py py-class docutils literal notranslate"><span class="pre">Command</span></code></a></p>
<p>Unix-type commands, supporting short and long options.</p>
<p>This command syntax uses the Unix-style commands with short options
(-X) and long options (–something). The <strong>argparse</strong> module is
used to parse the command.</p>
<p>In order to use it, you should override two methods:
- <strong>init_parser</strong>: this method is called when the command is created.</p>
<blockquote>
<div><p>It can be used to set options in the parser. <strong>self.parser</strong>
contains the <strong>argparse.ArgumentParser</strong>, so you can add arguments
here.</p>
</div></blockquote>
<ul class="simple">
<li><p><strong>func</strong>: this method is called to execute the command, but after
the parser has checked the arguments given to it are valid.
You can access the namespace of valid arguments in <strong>self.opts</strong>
at this point.</p></li>
</ul>
<p>The help of UnixCommands is derived from the docstring, in a
slightly different way than usual: the first line of the docstring
is used to represent the program description (the very short
line at the top of the help message). The other lines below are
used as the program’s “epilog”, displayed below the options. It
means in your docstring, you don’t have to write the options.
They will be automatically provided by the parser and displayed
accordingly. The <strong>argparse</strong> module provides a default ‘-h’ or
‘–help’ option on the command. Typing <a href="#id1"><span class="problematic" id="id2">|</span></a>whelp commandname|n will
display the same as <a href="#id3"><span class="problematic" id="id4">|</span></a>wcommandname -h|n, though this behavior can
be changed.</p>
<dl class="py method">
<dt class="sig sig-object py" id="evennia.contrib.base_systems.unixcommand.unixcommand.UnixCommand.__init__">
<span class="sig-name descname"><span class="pre">__init__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/contrib/base_systems/unixcommand/unixcommand.html#UnixCommand.__init__"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.contrib.base_systems.unixcommand.unixcommand.UnixCommand.__init__" title="Link 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>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="evennia.contrib.base_systems.unixcommand.unixcommand.UnixCommand.init_parser">
<span class="sig-name descname"><span class="pre">init_parser</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/contrib/base_systems/unixcommand/unixcommand.html#UnixCommand.init_parser"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.contrib.base_systems.unixcommand.unixcommand.UnixCommand.init_parser" title="Link to this definition"></a></dt>
<dd><p>Configure the argument parser, adding in options.</p>
<div class="admonition note">
<p class="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,
use its <strong>add_argument</strong> method.</p>
</div>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="evennia.contrib.base_systems.unixcommand.unixcommand.UnixCommand.func">
<span class="sig-name descname"><span class="pre">func</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/contrib/base_systems/unixcommand/unixcommand.html#UnixCommand.func"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.contrib.base_systems.unixcommand.unixcommand.UnixCommand.func" title="Link to this definition"></a></dt>
<dd><p>Override to handle the command execution.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="evennia.contrib.base_systems.unixcommand.unixcommand.UnixCommand.get_help">
<span class="sig-name descname"><span class="pre">get_help</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">caller</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">cmdset</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/contrib/base_systems/unixcommand/unixcommand.html#UnixCommand.get_help"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.contrib.base_systems.unixcommand.unixcommand.UnixCommand.get_help" title="Link to this definition"></a></dt>
<dd><p>Return the help message for this command and this caller.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="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> (<a class="reference internal" href="evennia.commands.cmdhandler.html#evennia.commands.cmdhandler.CmdSet" title="evennia.commands.cmdhandler.CmdSet"><em>CmdSet</em></a>) – the command set (if you need additional commands).</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p><em>docstring (str)</em> – the help text to provide the caller for this command.</p>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="evennia.contrib.base_systems.unixcommand.unixcommand.UnixCommand.parse">
<span class="sig-name descname"><span class="pre">parse</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/contrib/base_systems/unixcommand/unixcommand.html#UnixCommand.parse"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.contrib.base_systems.unixcommand.unixcommand.UnixCommand.parse" title="Link to this definition"></a></dt>
<dd><p>Process arguments provided in <strong>self.args</strong>.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>You should not override this method. Consider overriding
<strong>init_parser</strong> instead.</p>
</div>
</dd></dl>
<dl class="py attribute">
<dt class="sig sig-object py" id="evennia.contrib.base_systems.unixcommand.unixcommand.UnixCommand.aliases">
<span class="sig-name descname"><span class="pre">aliases</span></span><em class="property"><span class="w"> </span><span class="p"><span class="pre">=</span></span><span class="w"> </span><span class="pre">[]</span></em><a class="headerlink" href="#evennia.contrib.base_systems.unixcommand.unixcommand.UnixCommand.aliases" title="Link to this definition"></a></dt>
<dd></dd></dl>
<dl class="py attribute">
<dt class="sig sig-object py" id="evennia.contrib.base_systems.unixcommand.unixcommand.UnixCommand.help_category">
<span class="sig-name descname"><span class="pre">help_category</span></span><em class="property"><span class="w"> </span><span class="p"><span class="pre">=</span></span><span class="w"> </span><span class="pre">'general'</span></em><a class="headerlink" href="#evennia.contrib.base_systems.unixcommand.unixcommand.UnixCommand.help_category" title="Link to this definition"></a></dt>
<dd></dd></dl>
<dl class="py attribute">
<dt class="sig sig-object py" id="evennia.contrib.base_systems.unixcommand.unixcommand.UnixCommand.key">
<span class="sig-name descname"><span class="pre">key</span></span><em class="property"><span class="w"> </span><span class="p"><span class="pre">=</span></span><span class="w"> </span><span class="pre">'command'</span></em><a class="headerlink" href="#evennia.contrib.base_systems.unixcommand.unixcommand.UnixCommand.key" title="Link to this definition"></a></dt>
<dd></dd></dl>
<dl class="py attribute">
<dt class="sig sig-object py" id="evennia.contrib.base_systems.unixcommand.unixcommand.UnixCommand.lock_storage">
<span class="sig-name descname"><span class="pre">lock_storage</span></span><em class="property"><span class="w"> </span><span class="p"><span class="pre">=</span></span><span class="w"> </span><span class="pre">'cmd:all();'</span></em><a class="headerlink" href="#evennia.contrib.base_systems.unixcommand.unixcommand.UnixCommand.lock_storage" title="Link to this definition"></a></dt>
<dd></dd></dl>
<dl class="py attribute">
<dt class="sig sig-object py" id="evennia.contrib.base_systems.unixcommand.unixcommand.UnixCommand.search_index_entry">
<span class="sig-name descname"><span class="pre">search_index_entry</span></span><em class="property"><span class="w"> </span><span class="p"><span class="pre">=</span></span><span class="w"> </span><span class="pre">{'aliases':</span> <span class="pre">'',</span> <span class="pre">'category':</span> <span class="pre">'general',</span> <span class="pre">'key':</span> <span class="pre">'command',</span> <span class="pre">'no_prefix':</span> <span class="pre">'</span> <span class="pre">',</span> <span class="pre">'tags':</span> <span class="pre">'',</span> <span class="pre">'text':</span> <span class="pre">'\nUnix-type</span> <span class="pre">commands,</span> <span class="pre">supporting</span> <span class="pre">short</span> <span class="pre">and</span> <span class="pre">long</span> <span class="pre">options.\n\nThis</span> <span class="pre">command</span> <span class="pre">syntax</span> <span class="pre">uses</span> <span class="pre">the</span> <span class="pre">Unix-style</span> <span class="pre">commands</span> <span class="pre">with</span> <span class="pre">short</span> <span class="pre">options\n(-X)</span> <span class="pre">and</span> <span class="pre">long</span> <span class="pre">options</span> <span class="pre">(--something).</span>&#160; <span class="pre">The</span> <span class="pre">`argparse`</span> <span class="pre">module</span> <span class="pre">is\nused</span> <span class="pre">to</span> <span class="pre">parse</span> <span class="pre">the</span> <span class="pre">command.\n\nIn</span> <span class="pre">order</span> <span class="pre">to</span> <span class="pre">use</span> <span class="pre">it,</span> <span class="pre">you</span> <span class="pre">should</span> <span class="pre">override</span> <span class="pre">two</span> <span class="pre">methods:\n-</span> <span class="pre">`init_parser`:</span> <span class="pre">this</span> <span class="pre">method</span> <span class="pre">is</span> <span class="pre">called</span> <span class="pre">when</span> <span class="pre">the</span> <span class="pre">command</span> <span class="pre">is</span> <span class="pre">created.\n</span>&#160; <span class="pre">It</span> <span class="pre">can</span> <span class="pre">be</span> <span class="pre">used</span> <span class="pre">to</span> <span class="pre">set</span> <span class="pre">options</span> <span class="pre">in</span> <span class="pre">the</span> <span class="pre">parser.</span>&#160; <span class="pre">`self.parser`\n</span>&#160; <span class="pre">contains</span> <span class="pre">the</span> <span class="pre">`argparse.ArgumentParser`,</span> <span class="pre">so</span> <span class="pre">you</span> <span class="pre">can</span> <span class="pre">add</span> <span class="pre">arguments\n</span>&#160; <span class="pre">here.\n-</span> <span class="pre">`func`:</span> <span class="pre">this</span> <span class="pre">method</span> <span class="pre">is</span> <span class="pre">called</span> <span class="pre">to</span> <span class="pre">execute</span> <span class="pre">the</span> <span class="pre">command,</span> <span class="pre">but</span> <span class="pre">after\n</span>&#160; <span class="pre">the</span> <span class="pre">parser</span> <span class="pre">has</span> <span class="pre">checked</span> <span class="pre">the</span> <span class="pre">arguments</span> <span class="pre">given</span> <span class="pre">to</span> <span class="pre">it</span> <span class="pre">are</span> <span class="pre">valid.\n</span>&#160; <span class="pre">You</span> <span class="pre">can</span> <span class="pre">access</span> <span class="pre">the</span> <span class="pre">namespace</span> <span class="pre">of</span> <span class="pre">valid</span> <span class="pre">arguments</span> <span class="pre">in</span> <span class="pre">`self.opts`\n</span>&#160; <span class="pre">at</span> <span class="pre">this</span> <span class="pre">point.\n\nThe</span> <span class="pre">help</span> <span class="pre">of</span> <span class="pre">UnixCommands</span> <span class="pre">is</span> <span class="pre">derived</span> <span class="pre">from</span> <span class="pre">the</span> <span class="pre">docstring,</span> <span class="pre">in</span> <span class="pre">a\nslightly</span> <span class="pre">different</span> <span class="pre">way</span> <span class="pre">than</span> <span class="pre">usual:</span> <span class="pre">the</span> <span class="pre">first</span> <span class="pre">line</span> <span class="pre">of</span> <span class="pre">the</span> <span class="pre">docstring\nis</span> <span class="pre">used</span> <span class="pre">to</span> <span class="pre">represent</span> <span class="pre">the</span> <span class="pre">program</span> <span class="pre">description</span> <span class="pre">(the</span> <span class="pre">very</span> <span class="pre">short\nline</span> <span class="pre">at</span> <span class="pre">the</span> <span class="pre">top</span> <span class="pre">of</span> <span class="pre">the</span> <span class="pre">help</span> <span class="pre">message).</span>&#160; <span class="pre">The</span> <span class="pre">other</span> <span class="pre">lines</span> <span class="pre">below</span> <span class="pre">are\nused</span> <span class="pre">as</span> <span class="pre">the</span> <span class="pre">program\'s</span> <span class="pre">&quot;epilog&quot;,</span> <span class="pre">displayed</span> <span class="pre">below</span> <span class="pre">the</span> <span class="pre">options.</span>&#160; <span class="pre">It\nmeans</span> <span class="pre">in</span> <span class="pre">your</span> <span class="pre">docstring,</span> <span class="pre">you</span> <span class="pre">don\'t</span> <span class="pre">have</span> <span class="pre">to</span> <span class="pre">write</span> <span class="pre">the</span> <span class="pre">options.\nThey</span> <span class="pre">will</span> <span class="pre">be</span> <span class="pre">automatically</span> <span class="pre">provided</span> <span class="pre">by</span> <span class="pre">the</span> <span class="pre">parser</span> <span class="pre">and</span> <span class="pre">displayed\naccordingly.</span>&#160; <span class="pre">The</span> <span class="pre">`argparse`</span> <span class="pre">module</span> <span class="pre">provides</span> <span class="pre">a</span> <span class="pre">default</span> <span class="pre">\'-h\'</span> <span class="pre">or\n\'--help\'</span> <span class="pre">option</span> <span class="pre">on</span> <span class="pre">the</span> <span class="pre">command.</span>&#160; <span class="pre">Typing</span> <span class="pre">|whelp</span> <span class="pre">commandname|n</span> <span class="pre">will\ndisplay</span> <span class="pre">the</span> <span class="pre">same</span> <span class="pre">as</span> <span class="pre">|wcommandname</span> <span class="pre">-h|n,</span> <span class="pre">though</span> <span class="pre">this</span> <span class="pre">behavior</span> <span class="pre">can\nbe</span> <span class="pre">changed.\n\n'}</span></em><a class="headerlink" href="#evennia.contrib.base_systems.unixcommand.unixcommand.UnixCommand.search_index_entry" title="Link to this definition"></a></dt>
<dd></dd></dl>
</dd></dl>
</section>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="Main">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="../index.html">
<img class="logo" src="../_static/evennia_logo.png" alt="Logo of Evennia"/>
</a></p>
<search id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</search>
<script>document.getElementById('searchbox').style.display = "block"</script>
<h3><a href="../index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">evennia.contrib.base_systems.unixcommand.unixcommand</a><ul>
<li><a class="reference internal" href="#evennia.contrib.base_systems.unixcommand.unixcommand.ParseError"><code class="docutils literal notranslate"><span class="pre">ParseError</span></code></a></li>
<li><a class="reference internal" href="#evennia.contrib.base_systems.unixcommand.unixcommand.UnixCommandParser"><code class="docutils literal notranslate"><span class="pre">UnixCommandParser</span></code></a><ul>
<li><a class="reference internal" href="#evennia.contrib.base_systems.unixcommand.unixcommand.UnixCommandParser.__init__"><code class="docutils literal notranslate"><span class="pre">UnixCommandParser.__init__()</span></code></a></li>
<li><a class="reference internal" href="#evennia.contrib.base_systems.unixcommand.unixcommand.UnixCommandParser.format_usage"><code class="docutils literal notranslate"><span class="pre">UnixCommandParser.format_usage()</span></code></a></li>
<li><a class="reference internal" href="#evennia.contrib.base_systems.unixcommand.unixcommand.UnixCommandParser.format_help"><code class="docutils literal notranslate"><span class="pre">UnixCommandParser.format_help()</span></code></a></li>
<li><a class="reference internal" href="#evennia.contrib.base_systems.unixcommand.unixcommand.UnixCommandParser.print_usage"><code class="docutils literal notranslate"><span class="pre">UnixCommandParser.print_usage()</span></code></a></li>
<li><a class="reference internal" href="#evennia.contrib.base_systems.unixcommand.unixcommand.UnixCommandParser.print_help"><code class="docutils literal notranslate"><span class="pre">UnixCommandParser.print_help()</span></code></a></li>
</ul>
</li>
<li><a class="reference internal" href="#evennia.contrib.base_systems.unixcommand.unixcommand.HelpAction"><code class="docutils literal notranslate"><span class="pre">HelpAction</span></code></a></li>
<li><a class="reference internal" href="#evennia.contrib.base_systems.unixcommand.unixcommand.UnixCommand"><code class="docutils literal notranslate"><span class="pre">UnixCommand</span></code></a><ul>
<li><a class="reference internal" href="#evennia.contrib.base_systems.unixcommand.unixcommand.UnixCommand.__init__"><code class="docutils literal notranslate"><span class="pre">UnixCommand.__init__()</span></code></a></li>
<li><a class="reference internal" href="#evennia.contrib.base_systems.unixcommand.unixcommand.UnixCommand.init_parser"><code class="docutils literal notranslate"><span class="pre">UnixCommand.init_parser()</span></code></a></li>
<li><a class="reference internal" href="#evennia.contrib.base_systems.unixcommand.unixcommand.UnixCommand.func"><code class="docutils literal notranslate"><span class="pre">UnixCommand.func()</span></code></a></li>
<li><a class="reference internal" href="#evennia.contrib.base_systems.unixcommand.unixcommand.UnixCommand.get_help"><code class="docutils literal notranslate"><span class="pre">UnixCommand.get_help()</span></code></a></li>
<li><a class="reference internal" href="#evennia.contrib.base_systems.unixcommand.unixcommand.UnixCommand.parse"><code class="docutils literal notranslate"><span class="pre">UnixCommand.parse()</span></code></a></li>
<li><a class="reference internal" href="#evennia.contrib.base_systems.unixcommand.unixcommand.UnixCommand.aliases"><code class="docutils literal notranslate"><span class="pre">UnixCommand.aliases</span></code></a></li>
<li><a class="reference internal" href="#evennia.contrib.base_systems.unixcommand.unixcommand.UnixCommand.help_category"><code class="docutils literal notranslate"><span class="pre">UnixCommand.help_category</span></code></a></li>
<li><a class="reference internal" href="#evennia.contrib.base_systems.unixcommand.unixcommand.UnixCommand.key"><code class="docutils literal notranslate"><span class="pre">UnixCommand.key</span></code></a></li>
<li><a class="reference internal" href="#evennia.contrib.base_systems.unixcommand.unixcommand.UnixCommand.lock_storage"><code class="docutils literal notranslate"><span class="pre">UnixCommand.lock_storage</span></code></a></li>
<li><a class="reference internal" href="#evennia.contrib.base_systems.unixcommand.unixcommand.UnixCommand.search_index_entry"><code class="docutils literal notranslate"><span class="pre">UnixCommand.search_index_entry</span></code></a></li>
</ul>
</li>
</ul>
</li>
</ul>
<div>
<h4>Previous topic</h4>
<p class="topless"><a href="evennia.contrib.base_systems.unixcommand.tests.html"
title="previous chapter">evennia.contrib.base_systems.unixcommand.tests</a></p>
</div>
<div>
<h4>Next topic</h4>
<p class="topless"><a href="evennia.contrib.full_systems.html"
title="next chapter">evennia.contrib.full_systems</a></p>
</div>
<div role="note" aria-label="source link">
<!--h3>This Page</h3-->
<ul class="this-page-menu">
<li><a href="../_sources/api/evennia.contrib.base_systems.unixcommand.unixcommand.md.txt"
rel="nofollow">Show Page Source</a></li>
</ul>
</div><h3>Links</h3>
<ul>
<li><a href="https://www.evennia.com/docs/latest/index.html">Documentation Top</a> </li>
<li><a href="https://www.evennia.com">Evennia Home</a> </li>
<li><a href="https://github.com/evennia/evennia">Github</a> </li>
<li><a href="http://games.evennia.com">Game Index</a> </li>
<li>
<a href="https://discord.gg/AJJpcRUhtF">Discord</a> -
<a href="https://github.com/evennia/evennia/discussions">Discussions</a> -
<a href="https://evennia.blogspot.com/">Blog</a>
</li>
</ul>
<h3>Doc Versions</h3>
<ul>
<li>
<a href="https://www.evennia.com/docs/latest/index.html">latest (main branch)</a>
</li>
<li>
<a href="https://www.evennia.com/docs/5.x/index.html">v5.0.0 branch (outdated)</a>
</li>
<li>
<a href="https://www.evennia.com/docs/4.x/index.html">v4.0.0 branch (outdated)</a>
</li>
<li>
<a href="https://www.evennia.com/docs/3.x/index.html">v3.0.0 branch (outdated)</a>
</li>
<li>
<a href="https://www.evennia.com/docs/2.x/index.html">v2.0.0 branch (outdated)</a>
</li>
<li>
<a href="https://www.evennia.com/docs/1.x/index.html">v1.0.0 branch (outdated)</a>
</li>
<li>
<a href="https://www.evennia.com/docs/0.x/index.html">v0.9.5 branch (outdated)</a>
</li>
</ul>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="Related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="evennia.contrib.full_systems.html" title="evennia.contrib.full_systems"
>next</a> |</li>
<li class="right" >
<a href="evennia.contrib.base_systems.unixcommand.tests.html" title="evennia.contrib.base_systems.unixcommand.tests"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia</a> &#187;</li>
<li class="nav-item nav-item-1"><a href="../Evennia-API.html" >API Summary</a> &#187;</li>
<li class="nav-item nav-item-2"><a href="evennia-api.html" >evennia</a> &#187;</li>
<li class="nav-item nav-item-3"><a href="evennia.html" >evennia</a> &#187;</li>
<li class="nav-item nav-item-4"><a href="evennia.contrib.html" >evennia.contrib</a> &#187;</li>
<li class="nav-item nav-item-5"><a href="evennia.contrib.base_systems.html" >evennia.contrib.base_systems</a> &#187;</li>
<li class="nav-item nav-item-6"><a href="evennia.contrib.base_systems.unixcommand.html" >evennia.contrib.base_systems.unixcommand</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">evennia.contrib.base_systems.unixcommand.unixcommand</a></li>
</ul>
</div>
<div class="footer" role="contentinfo">
&#169; Copyright 2024, The Evennia developer community.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.2.3.
</div>
</body>
</html>
Reference in a new issue View git blame Copy permalink