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.
303 lines
16 KiB
HTML
303 lines
16 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>Creating and using parsers — 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="Adding and configuring arguments" href="arguments.html"/>
|
|
<link rel="prev" title="Argparse tutorial" href="index.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 current"><a class="current reference internal" href="">Creating and using parsers</a><ul>
|
|
<li class="toctree-l2"><a class="reference internal" href="#parsing-command-line-arguments">Parsing command line arguments</a></li>
|
|
<li class="toctree-l2"><a class="reference internal" href="#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"><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>Creating and using parsers</li>
|
|
<li class="wy-breadcrumbs-aside">
|
|
|
|
<a href="_sources/parsers.txt" rel="nofollow"> View page source</a>
|
|
|
|
</li>
|
|
</ul>
|
|
<hr/>
|
|
</div>
|
|
<div role="main">
|
|
|
|
<div class="section" id="creating-and-using-parsers">
|
|
<h1>Creating and using parsers<a class="headerlink" href="#creating-and-using-parsers" title="Permalink to this headline">¶</a></h1>
|
|
<p>The <tt class="docutils literal"><span class="pre">argparse</span></tt> module is a function which, when called, creates an instance of the Parser class.</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">-- script.lua</span>
|
|
<span class="kd">local</span> <span class="n">argparse</span> <span class="o">=</span> <span class="nb">require</span> <span class="s2">"</span><span class="s">argparse"</span>
|
|
<span class="kd">local</span> <span class="n">parser</span> <span class="o">=</span> <span class="n">argparse</span><span class="p">()</span>
|
|
</pre></div>
|
|
</td></tr></table></div>
|
|
<p><tt class="docutils literal"><span class="pre">parser</span></tt> is now an empty parser which does not recognize any command line arguments or options.</p>
|
|
<div class="section" id="parsing-command-line-arguments">
|
|
<h2>Parsing command line arguments<a class="headerlink" href="#parsing-command-line-arguments" title="Permalink to this headline">¶</a></h2>
|
|
<p><tt class="docutils literal"><span class="pre">:parse([args])</span></tt> method of the Parser class returns a table with processed data from the command line or <tt class="docutils literal"><span class="pre">args</span></tt> array.</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">args</span> <span class="o">=</span> <span class="n">parser</span><span class="p">:</span><span class="n">parse</span><span class="p">()</span>
|
|
<span class="nb">print</span><span class="p">(</span><span class="n">args</span><span class="p">)</span> <span class="c1">-- Assuming print is patched to handle tables nicely.</span>
|
|
</pre></div>
|
|
</td></tr></table></div>
|
|
<p>When executed, this script prints <tt class="docutils literal"><span class="pre">{}</span></tt> because the parser is empty and no command line arguments were supplied.</p>
|
|
<div class="section" id="error-handling">
|
|
<h3>Error handling<a class="headerlink" href="#error-handling" title="Permalink to this headline">¶</a></h3>
|
|
<p>If the provided command line arguments are not recognized by the parser, it will print an error message and call <tt class="docutils literal"><span class="pre">os.exit(1)</span></tt>.</p>
|
|
<div class="highlight-python"><div class="highlight"><pre>$ lua script.lua foo
|
|
</pre></div>
|
|
</div>
|
|
<div class="highlight-python"><div class="highlight"><pre>Usage: script.lua [-h]
|
|
|
|
Error: too many arguments
|
|
</pre></div>
|
|
</div>
|
|
<p>If halting the program is undesirable, <tt class="docutils literal"><span class="pre">:pparse([args])</span></tt> method should be used. It returns boolean flag indicating success of parsing and result or error message.</p>
|
|
<p>An error can raised manually using <tt class="docutils literal"><span class="pre">:error()</span></tt> method.</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="nb">error</span><span class="p">(</span><span class="s2">"</span><span class="s">manual argument validation failed"</span><span class="p">)</span>
|
|
</pre></div>
|
|
</td></tr></table></div>
|
|
<div class="highlight-python"><div class="highlight"><pre>Usage: script.lua [-h]
|
|
|
|
Error: manual argument validation failed
|
|
</pre></div>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="help-option">
|
|
<h3>Help option<a class="headerlink" href="#help-option" title="Permalink to this headline">¶</a></h3>
|
|
<p>As the automatically generated usage message states, there is a help option <tt class="docutils literal"><span class="pre">-h</span></tt> added to any parser by default.</p>
|
|
<p>When a help option is used, parser will print a help message and call <tt class="docutils literal"><span class="pre">os.exit(0)</span></tt>.</p>
|
|
<div class="highlight-python"><div class="highlight"><pre>$ lua script.lua -h
|
|
</pre></div>
|
|
</div>
|
|
<div class="highlight-python"><div class="highlight"><pre>Usage: script.lua [-h]
|
|
|
|
Options:
|
|
-h, --help Show this help message and exit.
|
|
</pre></div>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="typo-autocorrection">
|
|
<h3>Typo autocorrection<a class="headerlink" href="#typo-autocorrection" title="Permalink to this headline">¶</a></h3>
|
|
<p>When an option is not recognized by the parser, but there is an option with a similar name, a suggestion is automatically added to the error message.</p>
|
|
<div class="highlight-python"><div class="highlight"><pre>$ lua script.lua --hepl
|
|
</pre></div>
|
|
</div>
|
|
<div class="highlight-python"><div class="highlight"><pre>Usage: script.lua [-h]
|
|
|
|
Error: unknown option '--hepl'
|
|
Did you mean '--help'?
|
|
</pre></div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="configuring-parsers">
|
|
<h2>Configuring parsers<a class="headerlink" href="#configuring-parsers" title="Permalink to this headline">¶</a></h2>
|
|
<p>Parsers have several properties affecting their behavior. For example, <tt class="docutils literal"><span class="pre">description</span></tt> and <tt class="docutils literal"><span class="pre">epilog</span></tt> properties set the text to be displayed in the help message after the usage message and after the listings of options and arguments, respectively. Another is <tt class="docutils literal"><span class="pre">name</span></tt>, which overwrites the name of the program which is used in the usage message (default value is inferred from command line arguments).</p>
|
|
<p>There are several ways to set properties. The first is to chain setter methods of Parser object.</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="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">name</span> <span class="s2">"</span><span class="s">script"</span>
|
|
<span class="p">:</span><span class="n">description</span> <span class="s2">"</span><span class="s">A testing script."</span>
|
|
<span class="p">:</span><span class="n">epilog</span> <span class="s2">"</span><span class="s">For more info, see http://example.com"</span>
|
|
</pre></div>
|
|
</td></tr></table></div>
|
|
<p>The second is to call a parser with a table containing some properties.</p>
|
|
<div class="highlight-lua"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1
|
|
2
|
|
3
|
|
4
|
|
5</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">name</span> <span class="o">=</span> <span class="s2">"</span><span class="s">script"</span><span class="p">,</span>
|
|
<span class="n">description</span> <span class="o">=</span> <span class="s2">"</span><span class="s">A testing script."</span><span class="p">,</span>
|
|
<span class="n">epilog</span> <span class="s2">"</span><span class="s">For more info, see http://example.com."</span>
|
|
<span class="p">}</span>
|
|
</pre></div>
|
|
</td></tr></table></div>
|
|
<p>Finally, <tt class="docutils literal"><span class="pre">name</span></tt>. <tt class="docutils literal"><span class="pre">description</span></tt> and <tt class="docutils literal"><span class="pre">epilog</span></tt> properties can be passed as arguments when calling a parser.</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="kd">local</span> <span class="n">parser</span> <span class="o">=</span> <span class="n">argparse</span><span class="p">(</span><span class="s2">"</span><span class="s">script"</span><span class="p">,</span> <span class="s2">"</span><span class="s">A testing script."</span><span class="p">,</span> <span class="s2">"</span><span class="s">For more info, see http://example.com."</span><span class="p">)</span>
|
|
</pre></div>
|
|
</td></tr></table></div>
|
|
</div>
|
|
</div>
|
|
|
|
|
|
</div>
|
|
<footer>
|
|
|
|
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
|
|
|
|
<a href="arguments.html" class="btn btn-neutral float-right" title="Adding and configuring arguments"/>Next <span class="fa fa-arrow-circle-right"></span></a>
|
|
|
|
|
|
<a href="index.html" class="btn btn-neutral" title="Argparse tutorial"><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> |