mirror of
https://github.com/TangentFoxy/argparse.git
synced 2025-07-28 02:52:20 +00:00
340 lines
18 KiB
HTML
340 lines
18 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 options — argparse 0.4.1 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.1 tutorial" href="index.html"/>
|
|
<link rel="next" title="Mutually exclusive groups" href="mutexes.html"/>
|
|
<link rel="prev" title="Adding and configuring arguments" href="arguments.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 current"><a class="current reference internal" href="">Adding and configuring options</a><ul>
|
|
<li class="toctree-l2"><a class="reference internal" href="#flags">Flags</a></li>
|
|
<li class="toctree-l2"><a class="reference internal" href="#control-characters">Control characters</a></li>
|
|
<li class="toctree-l2"><a class="reference internal" href="#setting-number-of-consumed-arguments">Setting number of consumed arguments</a></li>
|
|
<li class="toctree-l2"><a class="reference internal" href="#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"><a class="reference internal" href="commands.html">Adding and configuring commands</a><ul>
|
|
<li class="toctree-l2"><a class="reference internal" href="commands.html#adding-elements-to-commands">Adding elements to commands</a></li>
|
|
<li class="toctree-l2"><a class="reference internal" href="commands.html#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 options</li>
|
|
<li class="wy-breadcrumbs-aside">
|
|
|
|
<a href="_sources/options.txt" rel="nofollow"> View page source</a>
|
|
|
|
</li>
|
|
</ul>
|
|
<hr/>
|
|
</div>
|
|
<div role="main">
|
|
|
|
<div class="section" id="adding-and-configuring-options">
|
|
<h1>Adding and configuring options<a class="headerlink" href="#adding-and-configuring-options" title="Permalink to this headline">¶</a></h1>
|
|
<p>Options can be added using <tt class="docutils literal"><span class="pre">:option(name,</span> <span class="pre">description,</span> <span class="pre">default,</span> <span class="pre">convert,</span> <span class="pre">args,</span> <span class="pre">count)</span></tt> method. It returns an Option instance, which can be configured in the same way as Parsers. The <tt class="docutils literal"><span class="pre">name</span></tt> property is required. An option can have several aliases, which can be set as space separated substrings in its name or by continuously setting <tt class="docutils literal"><span class="pre">name</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="c1">-- These lines are equivalent:</span>
|
|
<span class="n">parser</span><span class="p">:</span><span class="n">option</span> <span class="s2">"</span><span class="s">-f"</span> <span class="s2">"</span><span class="s">--from"</span>
|
|
<span class="n">parser</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 --from there
|
|
$ lua script.lua --from=there
|
|
$ lua script.lua -f there
|
|
$ lua script.lua -fthere
|
|
</pre></div>
|
|
</div>
|
|
<div class="highlight-lua"><div class="highlight"><pre><span class="p">{</span>
|
|
<span class="n">from</span> <span class="o">=</span> <span class="s2">"</span><span class="s">there"</span>
|
|
<span class="p">}</span>
|
|
</pre></div>
|
|
</div>
|
|
<p>For an option, default index used to store arguments passed to it is the first “long” alias (an alias starting with two control characters, typically hyphens) or just the first alias, without control characters. Hyphens in the default index are replaced with underscores. In the following table it is assumed that <tt class="docutils literal"><span class="pre">local</span> <span class="pre">args</span> <span class="pre">=</span> <span class="pre">parser:parse()</span></tt> has been executed.</p>
|
|
<table border="1" class="docutils">
|
|
<colgroup>
|
|
<col width="44%" />
|
|
<col width="56%" />
|
|
</colgroup>
|
|
<thead valign="bottom">
|
|
<tr class="row-odd"><th class="head">Option’s aliases</th>
|
|
<th class="head">Location of option’s arguments</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody valign="top">
|
|
<tr class="row-even"><td><tt class="docutils literal"><span class="pre">-o</span></tt></td>
|
|
<td><tt class="docutils literal"><span class="pre">args.o</span></tt></td>
|
|
</tr>
|
|
<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">-o</span></tt> <tt class="docutils literal"><span class="pre">--output</span></tt></td>
|
|
<td><tt class="docutils literal"><span class="pre">args.output</span></tt></td>
|
|
</tr>
|
|
<tr class="row-even"><td><tt class="docutils literal"><span class="pre">-s</span></tt> <tt class="docutils literal"><span class="pre">--from-server</span></tt></td>
|
|
<td><tt class="docutils literal"><span class="pre">args.from_server</span></tt></td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p>As with arguments, the index can be explicitly set using <tt class="docutils literal"><span class="pre">target</span></tt> property.</p>
|
|
<div class="section" id="flags">
|
|
<h2>Flags<a class="headerlink" href="#flags" title="Permalink to this headline">¶</a></h2>
|
|
<p>Flags are almost identical to options, except that they don’t take an argument by default.</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">flag</span><span class="p">(</span><span class="s2">"</span><span class="s">-q --quiet"</span><span class="p">)</span>
|
|
</pre></div>
|
|
</td></tr></table></div>
|
|
<div class="highlight-python"><div class="highlight"><pre>$ lua script.lua -q
|
|
</pre></div>
|
|
</div>
|
|
<div class="highlight-lua"><div class="highlight"><pre><span class="p">{</span>
|
|
<span class="n">quiet</span> <span class="o">=</span> <span class="kc">true</span>
|
|
<span class="p">}</span>
|
|
</pre></div>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="control-characters">
|
|
<h2>Control characters<a class="headerlink" href="#control-characters" title="Permalink to this headline">¶</a></h2>
|
|
<p>The first characters of all aliases of all options of a parser form the set of control characters, used to distinguish options from arguments. Typically the set only consists of a hyphen.</p>
|
|
</div>
|
|
<div class="section" id="setting-number-of-consumed-arguments">
|
|
<h2>Setting number of consumed arguments<a class="headerlink" href="#setting-number-of-consumed-arguments" title="Permalink to this headline">¶</a></h2>
|
|
<p>Just as arguments, options can be configured to take several command line arguments.</p>
|
|
<div class="highlight-lua"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1
|
|
2
|
|
3
|
|
4</pre></div></td><td class="code"><div class="highlight"><pre><span class="n">parser</span><span class="p">:</span><span class="n">option</span> <span class="s2">"</span><span class="s">--pair"</span>
|
|
<span class="p">:</span><span class="n">args</span><span class="p">(</span><span class="mi">2</span><span class="p">)</span>
|
|
<span class="n">parser</span><span class="p">:</span><span class="n">option</span> <span class="s2">"</span><span class="s">--optional"</span>
|
|
<span class="p">:</span><span class="n">args</span> <span class="s2">"</span><span class="s">?"</span>
|
|
</pre></div>
|
|
</td></tr></table></div>
|
|
<div class="highlight-python"><div class="highlight"><pre>$ lua script.lua --pair foo bar
|
|
</pre></div>
|
|
</div>
|
|
<div class="highlight-lua"><div class="highlight"><pre><span class="p">{</span>
|
|
<span class="n">pair</span> <span class="o">=</span> <span class="p">{</span><span class="s2">"</span><span class="s">foo"</span><span class="p">,</span> <span class="s2">"</span><span class="s">bar"</span><span class="p">}</span>
|
|
<span class="p">}</span>
|
|
</pre></div>
|
|
</div>
|
|
<div class="highlight-python"><div class="highlight"><pre>$ lua script.lua --pair foo bar --optional
|
|
</pre></div>
|
|
</div>
|
|
<div class="highlight-lua"><div class="highlight"><pre><span class="p">{</span>
|
|
<span class="n">pair</span> <span class="o">=</span> <span class="p">{</span><span class="s2">"</span><span class="s">foo"</span><span class="p">,</span> <span class="s2">"</span><span class="s">bar"</span><span class="p">},</span>
|
|
<span class="n">optional</span> <span class="o">=</span> <span class="p">{}</span>
|
|
<span class="p">}</span>
|
|
</pre></div>
|
|
</div>
|
|
<div class="highlight-python"><div class="highlight"><pre>$ lua script.lua --optional=baz
|
|
</pre></div>
|
|
</div>
|
|
<div class="highlight-lua"><div class="highlight"><pre><span class="p">{</span>
|
|
<span class="n">optional</span> <span class="o">=</span> <span class="p">{</span><span class="s2">"</span><span class="s">baz"</span><span class="p">}</span>
|
|
<span class="p">}</span>
|
|
</pre></div>
|
|
</div>
|
|
<p>Note that the data passed to <tt class="docutils literal"><span class="pre">optional</span></tt> option is stored in an array. That is necessary to distinguish whether the option was invoked without an argument or it was not invoked at all.</p>
|
|
</div>
|
|
<div class="section" id="setting-number-of-invocations">
|
|
<h2>Setting number of invocations<a class="headerlink" href="#setting-number-of-invocations" title="Permalink to this headline">¶</a></h2>
|
|
<p>For options, it is possible to control how many times they can be used. argparse uses <tt class="docutils literal"><span class="pre">count</span></tt> property to set how many times an option can be invoked. The value of the property is interpreted in the same way <tt class="docutils literal"><span class="pre">args</span></tt> is.</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="n">parser</span><span class="p">:</span><span class="n">option</span><span class="p">(</span><span class="s2">"</span><span class="s">-e --exclude"</span><span class="p">)</span>
|
|
<span class="p">:</span><span class="n">count</span> <span class="s2">"</span><span class="s">*"</span>
|
|
</pre></div>
|
|
</td></tr></table></div>
|
|
<div class="highlight-python"><div class="highlight"><pre>$ lua script.lua -eFOO -eBAR
|
|
</pre></div>
|
|
</div>
|
|
<div class="highlight-lua"><div class="highlight"><pre><span class="p">{</span>
|
|
<span class="n">exclude</span> <span class="o">=</span> <span class="p">{</span><span class="s2">"</span><span class="s">FOO"</span><span class="p">,</span> <span class="s2">"</span><span class="s">BAR"</span><span class="p">}</span>
|
|
<span class="p">}</span>
|
|
</pre></div>
|
|
</div>
|
|
<p>If an option can be used more than once and it can consume more than one argument, the data is stored as an array of invocations, each being an array of arguments.</p>
|
|
<p>As a special case, if an option can be used more than once and it consumes no arguments (e.g. it’s a flag), than the number of invocations is stored in the associated field of the result table.</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="n">parser</span><span class="p">:</span><span class="n">flag</span><span class="p">(</span><span class="s2">"</span><span class="s">-v --verbose"</span><span class="p">,</span> <span class="s2">"</span><span class="s">Sets verbosity level."</span><span class="p">)</span>
|
|
<span class="p">:</span><span class="n">count</span> <span class="s2">"</span><span class="s">0-2"</span>
|
|
<span class="p">:</span><span class="n">target</span> <span class="s2">"</span><span class="s">verbosity"</span>
|
|
</pre></div>
|
|
</td></tr></table></div>
|
|
<div class="highlight-python"><div class="highlight"><pre>$ lua script.lua -vv
|
|
</pre></div>
|
|
</div>
|
|
<div class="highlight-lua"><div class="highlight"><pre><span class="p">{</span>
|
|
<span class="n">verbosity</span> <span class="o">=</span> <span class="mi">2</span>
|
|
<span class="p">}</span>
|
|
</pre></div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
|
|
</div>
|
|
<footer>
|
|
|
|
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
|
|
|
|
<a href="mutexes.html" class="btn btn-neutral float-right" title="Mutually exclusive groups"/>Next <span class="fa fa-arrow-circle-right"></span></a>
|
|
|
|
|
|
<a href="arguments.html" class="btn btn-neutral" title="Adding and configuring arguments"><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.1',
|
|
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> |