mirror of
https://github.com/TangentFoxy/argparse.git
synced 2025-07-28 11:02:20 +00:00
af793c49f3
It is better to have docs built in the repo so that building scm version doesn't fail with 'missing doc directory' error.
297 lines
13 KiB
HTML
297 lines
13 KiB
HTML
|
|
|
|
<!DOCTYPE html>
|
|
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
|
|
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
|
|
<head>
|
|
<meta charset="utf-8">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
|
|
<title>Adding and configuring commands — argparse 0.4.0 tutorial</title>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<link href='https://fonts.googleapis.com/css?family=Lato:400,700|Roboto+Slab:400,700|Inconsolata:400,700' rel='stylesheet' type='text/css'>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
|
|
|
|
|
|
|
|
<link rel="top" title="argparse 0.4.0 tutorial" href="index.html"/>
|
|
<link rel="next" title="Default values" href="defaults.html"/>
|
|
<link rel="prev" title="Mutually exclusive groups" href="mutexes.html"/>
|
|
|
|
|
|
<script src="https://cdnjs.cloudflare.com/ajax/libs/modernizr/2.6.2/modernizr.min.js"></script>
|
|
|
|
</head>
|
|
|
|
<body class="wy-body-for-nav" role="document">
|
|
|
|
<div class="wy-grid-for-nav">
|
|
|
|
|
|
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
|
|
<div class="wy-side-nav-search">
|
|
<a href="index.html" class="fa fa-home"> argparse</a>
|
|
<div role="search">
|
|
<form id ="rtd-search-form" class="wy-form" action="search.html" method="get">
|
|
<input type="text" name="q" placeholder="Search docs" />
|
|
<input type="hidden" name="check_keywords" value="yes" />
|
|
<input type="hidden" name="area" value="default" />
|
|
</form>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
|
|
|
|
|
|
<ul class="current">
|
|
<li class="toctree-l1"><a class="reference internal" href="parsers.html">Creating and using parsers</a><ul>
|
|
<li class="toctree-l2"><a class="reference internal" href="parsers.html#parsing-command-line-arguments">Parsing command line arguments</a></li>
|
|
<li class="toctree-l2"><a class="reference internal" href="parsers.html#configuring-parsers">Configuring parsers</a></li>
|
|
</ul>
|
|
</li>
|
|
<li class="toctree-l1"><a class="reference internal" href="arguments.html">Adding and configuring arguments</a><ul>
|
|
<li class="toctree-l2"><a class="reference internal" href="arguments.html#setting-number-of-consumed-arguments">Setting number of consumed arguments</a></li>
|
|
</ul>
|
|
</li>
|
|
<li class="toctree-l1"><a class="reference internal" href="options.html">Adding and configuring options</a><ul>
|
|
<li class="toctree-l2"><a class="reference internal" href="options.html#flags">Flags</a></li>
|
|
<li class="toctree-l2"><a class="reference internal" href="options.html#control-characters">Control characters</a></li>
|
|
<li class="toctree-l2"><a class="reference internal" href="options.html#setting-number-of-consumed-arguments">Setting number of consumed arguments</a></li>
|
|
<li class="toctree-l2"><a class="reference internal" href="options.html#setting-number-of-invocations">Setting number of invocations</a></li>
|
|
</ul>
|
|
</li>
|
|
<li class="toctree-l1"><a class="reference internal" href="mutexes.html">Mutually exclusive groups</a></li>
|
|
<li class="toctree-l1 current"><a class="current reference internal" href="">Adding and configuring commands</a><ul>
|
|
<li class="toctree-l2"><a class="reference internal" href="#adding-elements-to-commands">Adding elements to commands</a></li>
|
|
<li class="toctree-l2"><a class="reference internal" href="#making-a-command-optional">Making a command optional</a></li>
|
|
</ul>
|
|
</li>
|
|
<li class="toctree-l1"><a class="reference internal" href="defaults.html">Default values</a><ul>
|
|
<li class="toctree-l2"><a class="reference internal" href="defaults.html#default-mode">Default mode</a></li>
|
|
</ul>
|
|
</li>
|
|
<li class="toctree-l1"><a class="reference internal" href="callbacks.html">Callbacks</a><ul>
|
|
<li class="toctree-l2"><a class="reference internal" href="callbacks.html#converters">Converters</a></li>
|
|
<li class="toctree-l2"><a class="reference internal" href="callbacks.html#actions">Actions</a></li>
|
|
</ul>
|
|
</li>
|
|
<li class="toctree-l1"><a class="reference internal" href="misc.html">Miscellaneous</a><ul>
|
|
<li class="toctree-l2"><a class="reference internal" href="misc.html#generating-and-overwriting-help-and-usage-messages">Generating and overwriting help and usage messages</a></li>
|
|
<li class="toctree-l2"><a class="reference internal" href="misc.html#overwriting-default-help-option">Overwriting default help option</a></li>
|
|
<li class="toctree-l2"><a class="reference internal" href="misc.html#setting-argument-placeholder">Setting argument placeholder</a></li>
|
|
<li class="toctree-l2"><a class="reference internal" href="misc.html#disabling-option-handling">Disabling option handling</a></li>
|
|
<li class="toctree-l2"><a class="reference internal" href="misc.html#prohibiting-overuse-of-options">Prohibiting overuse of options</a></li>
|
|
<li class="toctree-l2"><a class="reference internal" href="misc.html#parsing-algorithm">Parsing algorithm</a></li>
|
|
<li class="toctree-l2"><a class="reference internal" href="misc.html#property-lists">Property lists</a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
|
|
</div>
|
|
|
|
</nav>
|
|
|
|
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
|
|
|
|
|
|
<nav class="wy-nav-top" role="navigation" aria-label="top navigation">
|
|
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
|
|
<a href="index.html">argparse</a>
|
|
</nav>
|
|
|
|
|
|
|
|
<div class="wy-nav-content">
|
|
<div class="rst-content">
|
|
<div role="navigation" aria-label="breadcrumbs navigation">
|
|
<ul class="wy-breadcrumbs">
|
|
<li><a href="index.html">Docs</a> »</li>
|
|
|
|
<li>Adding and configuring commands</li>
|
|
<li class="wy-breadcrumbs-aside">
|
|
|
|
<a href="_sources/commands.txt" rel="nofollow"> View page source</a>
|
|
|
|
</li>
|
|
</ul>
|
|
<hr/>
|
|
</div>
|
|
<div role="main">
|
|
|
|
<div class="section" id="adding-and-configuring-commands">
|
|
<h1>Adding and configuring commands<a class="headerlink" href="#adding-and-configuring-commands" title="Permalink to this headline">¶</a></h1>
|
|
<p>A command is a subparser invoked when its name is passed as an argument. For example, in <a class="reference external" href="http://git-scm.com">git</a> CLI <tt class="docutils literal"><span class="pre">add</span></tt>, <tt class="docutils literal"><span class="pre">commit</span></tt>, <tt class="docutils literal"><span class="pre">push</span></tt>, etc. are commands. Each command has its own set of arguments and options, but inherits options of its parent.</p>
|
|
<p>Commands can be added using <tt class="docutils literal"><span class="pre">:command(name,</span> <span class="pre">description,</span> <span class="pre">epilog)</span></tt> method. Just as options, commands can have several aliases.</p>
|
|
<div class="highlight-lua"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1</pre></div></td><td class="code"><div class="highlight"><pre><span class="n">parser</span><span class="p">:</span><span class="n">command</span> <span class="s2">"</span><span class="s">install i"</span>
|
|
</pre></div>
|
|
</td></tr></table></div>
|
|
<p>If a command it used, <tt class="docutils literal"><span class="pre">true</span></tt> is stored in the corresponding field of the result table.</p>
|
|
<div class="highlight-python"><div class="highlight"><pre>$ lua script.lua install
|
|
</pre></div>
|
|
</div>
|
|
<div class="highlight-lua"><div class="highlight"><pre><span class="p">{</span>
|
|
<span class="n">install</span> <span class="o">=</span> <span class="kc">true</span>
|
|
<span class="p">}</span>
|
|
</pre></div>
|
|
</div>
|
|
<p>A typo will result in an appropriate error message.</p>
|
|
<div class="highlight-python"><div class="highlight"><pre>$ lua script.lua instal
|
|
</pre></div>
|
|
</div>
|
|
<div class="highlight-python"><div class="highlight"><pre>Usage: script.lua [-h] <command> ...
|
|
|
|
Error: unknown command 'instal'
|
|
Did you mean 'install'?
|
|
</pre></div>
|
|
</div>
|
|
<div class="section" id="adding-elements-to-commands">
|
|
<h2>Adding elements to commands<a class="headerlink" href="#adding-elements-to-commands" title="Permalink to this headline">¶</a></h2>
|
|
<p>The Command class is a subclass of the Parser class, so all the Parser’s methods for adding elements work on commands, too.</p>
|
|
<div class="highlight-lua"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1
|
|
2
|
|
3</pre></div></td><td class="code"><div class="highlight"><pre><span class="kd">local</span> <span class="n">install</span> <span class="o">=</span> <span class="n">parser</span><span class="p">:</span><span class="n">command</span> <span class="s2">"</span><span class="s">install"</span>
|
|
<span class="n">install</span><span class="p">:</span><span class="n">argument</span> <span class="s2">"</span><span class="s">rock"</span>
|
|
<span class="n">install</span><span class="p">:</span><span class="n">option</span> <span class="s2">"</span><span class="s">-f --from"</span>
|
|
</pre></div>
|
|
</td></tr></table></div>
|
|
<div class="highlight-python"><div class="highlight"><pre>$ lua script.lua install foo --from=bar
|
|
</pre></div>
|
|
</div>
|
|
<div class="highlight-lua"><div class="highlight"><pre><span class="p">{</span>
|
|
<span class="n">install</span> <span class="o">=</span> <span class="kc">true</span><span class="p">,</span>
|
|
<span class="n">rock</span> <span class="o">=</span> <span class="s2">"</span><span class="s">foo"</span><span class="p">,</span>
|
|
<span class="n">from</span> <span class="o">=</span> <span class="s2">"</span><span class="s">bar"</span>
|
|
<span class="p">}</span>
|
|
</pre></div>
|
|
</div>
|
|
<p>Commands have their own usage and help messages.</p>
|
|
<div class="highlight-python"><div class="highlight"><pre>$ lua script.lua install
|
|
</pre></div>
|
|
</div>
|
|
<div class="highlight-python"><div class="highlight"><pre>Usage: script.lua install [-f <from>] [-h] <rock>
|
|
|
|
Error: too few arguments
|
|
</pre></div>
|
|
</div>
|
|
<div class="highlight-python"><div class="highlight"><pre>$ lua script.lua install --help
|
|
</pre></div>
|
|
</div>
|
|
<div class="highlight-python"><div class="highlight"><pre>Usage: script.lua install [-f <from>] [-h] <rock>
|
|
|
|
Arguments:
|
|
rock
|
|
|
|
Options:
|
|
-f <from>, --from <from>
|
|
-h, --help Show this help message and exit.
|
|
</pre></div>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="making-a-command-optional">
|
|
<h2>Making a command optional<a class="headerlink" href="#making-a-command-optional" title="Permalink to this headline">¶</a></h2>
|
|
<p>By default, if a parser has commands, using one of them is obligatory.</p>
|
|
<div class="highlight-lua"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1
|
|
2</pre></div></td><td class="code"><div class="highlight"><pre><span class="kd">local</span> <span class="n">parser</span> <span class="o">=</span> <span class="n">argparse</span><span class="p">()</span>
|
|
<span class="n">parser</span><span class="p">:</span><span class="n">command</span> <span class="s2">"</span><span class="s">install"</span>
|
|
</pre></div>
|
|
</td></tr></table></div>
|
|
<div class="highlight-python"><div class="highlight"><pre>$ lua script.lua
|
|
</pre></div>
|
|
</div>
|
|
<div class="highlight-python"><div class="highlight"><pre>Usage: script.lua [-h] <command> ...
|
|
|
|
Error: a command is required
|
|
</pre></div>
|
|
</div>
|
|
<p>This can be changed using <tt class="docutils literal"><span class="pre">require_command</span></tt> property.</p>
|
|
<div class="highlight-lua"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1
|
|
2
|
|
3</pre></div></td><td class="code"><div class="highlight"><pre><span class="kd">local</span> <span class="n">parser</span> <span class="o">=</span> <span class="n">argparse</span><span class="p">()</span>
|
|
<span class="p">:</span><span class="n">require_command</span><span class="p">(</span><span class="kc">false</span><span class="p">)</span>
|
|
<span class="n">parser</span><span class="p">:</span><span class="n">command</span> <span class="s2">"</span><span class="s">install"</span>
|
|
</pre></div>
|
|
</td></tr></table></div>
|
|
</div>
|
|
</div>
|
|
|
|
|
|
</div>
|
|
<footer>
|
|
|
|
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
|
|
|
|
<a href="defaults.html" class="btn btn-neutral float-right" title="Default values"/>Next <span class="fa fa-arrow-circle-right"></span></a>
|
|
|
|
|
|
<a href="mutexes.html" class="btn btn-neutral" title="Mutually exclusive groups"><span class="fa fa-arrow-circle-left"></span> Previous</a>
|
|
|
|
</div>
|
|
|
|
|
|
<hr/>
|
|
|
|
<div role="contentinfo">
|
|
<p>
|
|
© Copyright 2013 - 2015, Peter Melnichenko.
|
|
</p>
|
|
</div>
|
|
|
|
<a href="https://github.com/snide/sphinx_rtd_theme">Sphinx theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>
|
|
</footer>
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
|
|
<script type="text/javascript">
|
|
var DOCUMENTATION_OPTIONS = {
|
|
URL_ROOT:'./',
|
|
VERSION:'0.4.0',
|
|
COLLAPSE_INDEX:false,
|
|
FILE_SUFFIX:'.html',
|
|
HAS_SOURCE: true
|
|
};
|
|
</script>
|
|
<script type="text/javascript" src="_static/jquery.js"></script>
|
|
<script type="text/javascript" src="_static/underscore.js"></script>
|
|
<script type="text/javascript" src="_static/doctools.js"></script>
|
|
|
|
|
|
|
|
|
|
|
|
<script type="text/javascript" src="_static/js/theme.js"></script>
|
|
|
|
|
|
|
|
|
|
<script type="text/javascript">
|
|
jQuery(function () {
|
|
SphinxRtdTheme.StickyNav.enable();
|
|
});
|
|
</script>
|
|
|
|
|
|
</body>
|
|
</html> |