mirrors/argparse
1
0
Fork 0
mirror of https://github.com/TangentFoxy/argparse.git synced 2025-07-28 02:52:20 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
f9fd78a5f09d6a4182cd443033970c1f69aa73fc
argparse/doc/index.html
mpeterv f9fd78a5f0 Minor doc fix [ci skip]
2014-03-09 15:21:42 +04:00

873 lines
39 KiB
HTML
Raw Blame History

<!DOCTYPE html>
<html>
<head>
<meta charset='utf-8' />
<meta http-equiv="X-UA-Compatible" content="chrome=1" />
<meta name="description" content="Argparse tutorial : " />
<link rel="stylesheet" type="text/css" media="screen" href="stylesheets/stylesheet.css">
<title>Argparse tutorial</title>
</head>
<body>
<!-- HEADER -->
<div id="header_wrap" class="outer">
<header class="inner">
<a id="forkme_banner" href="https://github.com/mpeterv/argparse">View on GitHub</a>
<h1 id="project_title">Argparse tutorial</h1>
<h2 id="project_tagline"></h2>
</header>
</div>
<!-- MAIN CONTENT -->
<div id="main_content_wrap" class="outer">
<section id="main_content" class="inner">
<ul>
<li><a href="#creating-a-parser">Creating a parser</a></li>
<li>
<a href="#parsing-command-line-arguments">Parsing command line arguments</a>
<ul>
<li><a href="#error-handling">Error handling</a></li>
<li><a href="#help-option">Help option</a></li>
<li><a href="#typo-autocorrection">Typo autocorrection</a></li>
</ul>
</li>
<li><a href="#configuring-parser">Configuring parser</a></li>
<li>
<a href="#adding-arguments">Adding arguments</a>
<ul>
<li><a href="#setting-number-of-arguments">Setting number of arguments</a></li>
</ul>
</li>
<li>
<a href="#adding-options">Adding options</a>
<ul>
<li><a href="#flags">Flags</a></li>
<li><a href="#control-characters">Control characters</a></li>
<li><a href="#setting-number-of-arguments-1">Setting number of arguments</a></li>
<li><a href="#setting-number-of-invocations">Setting number of invocations</a></li>
</ul>
</li>
<li><a href="#mutually-exclusive-groups">Mutually exclusive groups</a></li>
<li>
<a href="#commands">Commands</a>
<ul>
<li><a href="#adding-elements-to-commands">Adding elements to commands</a></li>
<li><a href="#making-a-command-optional">Making a command optional</a></li>
</ul>
</li>
<li>
<a href="#default-values">Default values</a>
<ul>
<li><a href="#default-mode">Default mode</a></li>
</ul>
</li>
<li>
<a href="#converters">Converters</a>
<ul>
<li><a href="#table-converters">Table converters</a></li>
</ul>
</li>
<li><a href="#actions">Actions</a></li>
<li>
<a href="#miscellaneous">Miscellaneous</a>
<ul>
<li><a href="#overwriting-default-help-option">Overwriting default help option</a></li>
<li>
<a href="#configuring-usage-and-help-messages">Configuring usage and help messages</a>
<ul>
<li><a href="#description-and-epilog">Description and epilog</a></li>
<li><a href="#argument-placeholder">Argument placeholder</a></li>
</ul>
</li>
<li><a href="#prohibiting-overuse-of-options">Prohibiting overuse of options</a></li>
<li><a href="#generating-usage-and-help-messages">Generating usage and help messages</a></li>
<li><a href="#parsing-algorithm">Parsing algorithm</a></li>
</ul>
</li>
</ul><h2>
<a name="creating-a-parser" class="anchor" href="#creating-a-parser"><span class="octicon octicon-link"></span></a>Creating a parser</h2>
<p>The module is a function which, when called, creates an instance of the Parser class. </p>
<div class="highlight highlight-lua"><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>
<p><code>parser</code> is now an empty parser which does not recognize any command line arguments or options. </p>
<h2>
<a name="parsing-command-line-arguments" class="anchor" href="#parsing-command-line-arguments"><span class="octicon octicon-link"></span></a>Parsing command line arguments</h2>
<p><code>:parse([cmdline])</code> method of the Parser class returns a table with processed data from the command line or <code>cmdline</code> array. </p>
<div class="highlight highlight-lua"><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="k">for</span> <span class="n">k</span><span class="p">,</span> <span class="n">v</span> <span class="k">in</span> <span class="nb">pairs</span><span class="p">(</span><span class="n">args</span><span class="p">)</span> <span class="k">do</span> <span class="nb">print</span><span class="p">(</span><span class="n">k</span><span class="p">,</span> <span class="n">v</span><span class="p">)</span> <span class="k">end</span>
</pre></div>
<p>When executed, this script prints nothing because the parser is empty and no command line arguments were supplied. </p>
<div class="highlight highlight-bash"><pre><span class="nv">$ </span>lua script.lua
</pre></div>
<h3>
<a name="error-handling" class="anchor" href="#error-handling"><span class="octicon octicon-link"></span></a>Error handling</h3>
<p>If the provided command line arguments are not recognized by the parser, it will print an error message and call <code>os.exit(1)</code>. </p>
<div class="highlight highlight-bash"><pre><span class="nv">$ </span>lua script.lua foo
</pre></div>
<pre><code>Usage: script.lua [-h]
Error: too many arguments
</code></pre>
<p>If halting the program is undesirable, <code>:pparse([cmdline])</code> 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 <code>:error()</code> method. </p>
<div class="highlight highlight-lua"><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>
<pre><code>Usage: script.lua [-h]
Error: manual argument validation failed
</code></pre>
<h3>
<a name="help-option" class="anchor" href="#help-option"><span class="octicon octicon-link"></span></a>Help option</h3>
<p>As the automatically generated usage message states, there is a help option <code>-h</code> added to any parser by default. </p>
<p>When a help option is used, parser will print a help message and call <code>os.exit(0)</code>. </p>
<div class="highlight highlight-bash"><pre><span class="nv">$ </span>lua script.lua -h
</pre></div>
<pre><code>Usage: script.lua [-h]
Options:
-h, --help Show this help message and exit.
</code></pre>
<h3>
<a name="typo-autocorrection" class="anchor" href="#typo-autocorrection"><span class="octicon octicon-link"></span></a>Typo autocorrection</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 highlight-bash"><pre><span class="nv">$ </span>lua script.lua --hepl
</pre></div>
<pre><code>Usage: script.lua [-h]
Error: unknown option '--hepl'
Did you mean '--help'?
</code></pre>
<h2>
<a name="configuring-parser" class="anchor" href="#configuring-parser"><span class="octicon octicon-link"></span></a>Configuring parser</h2>
<p>Parsers have several fields affecting their behavior. For example, <code>description</code> field sets the text to be displayed in the help message between the usage message and the listings of options and arguments. Another is <code>name</code>, 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 fields. The first is to call a parser with a table containing some fields. </p>
<div class="highlight highlight-lua"><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>
</pre></div>
<p>The second is to chain setter methods of Parser object. </p>
<div class="highlight highlight-lua"><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>
</pre></div>
<p>As a special case, <code>name</code> field can be set by calling a parser with a string. </p>
<div class="highlight highlight-lua"><pre><span class="kd">local</span> <span class="n">parser</span> <span class="o">=</span> <span class="n">argparse</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>
</pre></div>
<h2>
<a name="adding-arguments" class="anchor" href="#adding-arguments"><span class="octicon octicon-link"></span></a>Adding arguments</h2>
<p>Positional arguments can be added using <code>:argument()</code> method. It returns an Argument instance, which can be configured in the same way as Parsers. The <code>name</code> field is required. </p>
<div class="highlight highlight-lua"><pre><span class="n">parser</span><span class="p">:</span><span class="n">argument</span> <span class="s2">"</span><span class="s">input"</span> <span class="c1">-- sugar for :argument():name "input"</span>
</pre></div>
<div class="highlight highlight-bash"><pre><span class="nv">$ </span>lua script.lua foo
</pre></div>
<pre><code>input foo
</code></pre>
<p>The data passed to the argument is stored in the result table at index <code>input</code> because it is the argument's name. The index can be changed using <code>target</code> field. </p>
<h3>
<a name="setting-number-of-arguments" class="anchor" href="#setting-number-of-arguments"><span class="octicon octicon-link"></span></a>Setting number of arguments</h3>
<p><code>args</code> field sets how many command line arguments the argument consumes. Its value is interpreted as follows: </p>
<table>
<thead><tr>
<th>Value</th>
<th>Interpretation</th>
</tr></thead>
<tbody>
<tr>
<td>Number <code>N</code>
</td>
<td>Exactly <code>N</code> arguments</td>
</tr>
<tr>
<td>String <code>"A-B"</code>, where <code>A</code> and <code>B</code> are numbers</td>
<td>From <code>A</code> to <code>B</code> arguments</td>
</tr>
<tr>
<td>String <code>"N+"</code>, where <code>N</code> is a number</td>
<td>
<code>N</code> or more arguments</td>
</tr>
<tr>
<td>String <code>"?"</code>
</td>
<td>An optional argument</td>
</tr>
<tr>
<td>String <code>"*"</code>
</td>
<td>Any number of arguments</td>
</tr>
<tr>
<td>String <code>"+"</code>
</td>
<td>At least one argument</td>
</tr>
</tbody>
</table><p>If more than one argument can be passed, a table is used to store the data. </p>
<div class="highlight highlight-lua"><pre><span class="n">parser</span><span class="p">:</span><span class="n">argument</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="p">:</span><span class="n">description</span> <span class="s2">"</span><span class="s">A pair of arguments. "</span>
<span class="n">parser</span><span class="p">:</span><span class="n">argument</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>
<span class="p">:</span><span class="n">description</span> <span class="s2">"</span><span class="s">An optional argument. "</span>
</pre></div>
<div class="highlight highlight-bash"><pre><span class="nv">$ </span>lua script.lua foo bar
</pre></div>
<pre><code>pair {foo, bar}
</code></pre>
<div class="highlight highlight-bash"><pre><span class="nv">$ </span>lua script.lua foo bar baz
</pre></div>
<pre><code>pair {foo, bar}
optional baz
</code></pre>
<h2>
<a name="adding-options" class="anchor" href="#adding-options"><span class="octicon octicon-link"></span></a>Adding options</h2>
<p>Options can be added using <code>:option()</code> method. It returns an Option instance, which can be configured in the same way as Parsers. The <code>name</code> field is required. An option can have several aliases, which can be set using <code>aliases</code> field or by continuously calling the Option instance. </p>
<div class="highlight highlight-lua"><pre><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>
</pre></div>
<div class="highlight highlight-bash"><pre><span class="nv">$ </span>lua script.lua --from there
<span class="nv">$ </span>lua script.lua --from<span class="o">=</span>there
<span class="nv">$ </span>lua script.lua -f there
<span class="nv">$ </span>lua script.lua -fthere
</pre></div>
<pre><code>from there
</code></pre>
<p>For an option, default index used to store data is the first 'long' alias (an alias starting with two control characters) or just the first alias, without control characters. </p>
<p>Sometimes it is useful to explicitly set the index using <code>target</code> field to improve readability of help messages. </p>
<div class="highlight highlight-lua"><pre><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="p">:</span><span class="n">target</span> <span class="s2">"</span><span class="s">server"</span>
</pre></div>
<div class="highlight highlight-bash"><pre><span class="nv">$ </span>lua script.lua --help
</pre></div>
<pre><code>Usage: script.lua [-f &lt;server&gt;] [-h]
Options:
-f &lt;server&gt;, --from &lt;server&gt;
-h, --help Show this help message and exit.
</code></pre>
<div class="highlight highlight-bash"><pre><span class="nv">$ </span>lua script.lua --from there
</pre></div>
<pre><code>server there
</code></pre>
<h3>
<a name="flags" class="anchor" href="#flags"><span class="octicon octicon-link"></span></a>Flags</h3>
<p>Flags are almost identical to options, except that they don't take an argument by default. </p>
<div class="highlight highlight-lua"><pre><span class="n">parser</span><span class="p">:</span><span class="n">flag</span> <span class="s2">"</span><span class="s">-q"</span> <span class="s2">"</span><span class="s">--quiet"</span>
</pre></div>
<div class="highlight highlight-bash"><pre><span class="nv">$ </span>lua script.lua -q
</pre></div>
<pre><code>quiet true
</code></pre>
<h3>
<a name="control-characters" class="anchor" href="#control-characters"><span class="octicon octicon-link"></span></a>Control characters</h3>
<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>
<h3>
<a name="setting-number-of-arguments-1" class="anchor" href="#setting-number-of-arguments-1"><span class="octicon octicon-link"></span></a>Setting number of arguments</h3>
<p>Just as arguments, options can be configured to take several command line arguments. </p>
<div class="highlight highlight-lua"><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>
<div class="highlight highlight-bash"><pre><span class="nv">$ </span>lua script.lua --pair foo bar
</pre></div>
<pre><code>pair {foo, bar}
</code></pre>
<div class="highlight highlight-bash"><pre><span class="nv">$ </span>lua script.lua --pair foo bar --optional
</pre></div>
<pre><code>pair {foo, bar}
optional {}
</code></pre>
<div class="highlight highlight-bash"><pre><span class="nv">$ </span>lua script.lua --optional<span class="o">=</span>baz
</pre></div>
<pre><code>optional {baz}
</code></pre>
<p>Note that the data passed to <code>optional</code> 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>
<h3>
<a name="setting-number-of-invocations" class="anchor" href="#setting-number-of-invocations"><span class="octicon octicon-link"></span></a>Setting number of invocations</h3>
<p>For options, it is possible to control how many times they can be used. argparse uses <code>count</code> field to set how many times an option can be invoked. The value of the field is interpreted in the same way <code>args</code> is. </p>
<div class="highlight highlight-lua"><pre><span class="n">parser</span><span class="p">:</span><span class="n">option</span> <span class="s2">"</span><span class="s">-e"</span> <span class="s2">"</span><span class="s">--exclude"</span>
<span class="p">:</span><span class="n">count</span> <span class="s2">"</span><span class="s">*"</span>
</pre></div>
<div class="highlight highlight-bash"><pre><span class="nv">$ </span>lua script.lua -eFOO -eBAR
</pre></div>
<pre><code>exclude {FOO, BAR}
</code></pre>
<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 associated field of the result table. </p>
<div class="highlight highlight-lua"><pre><span class="n">parser</span><span class="p">:</span><span class="n">flag</span> <span class="s2">"</span><span class="s">-v"</span> <span class="s2">"</span><span class="s">--verbose"</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>
<span class="p">:</span><span class="n">description</span> <span class="s">[[Sets verbosity level. </span>
<span class="s">-v: Report all warning. </span>
<span class="s">-vv: Report all debugging information. ]]</span>
</pre></div>
<div class="highlight highlight-bash"><pre><span class="nv">$ </span>lua script.lua -vv
</pre></div>
<pre><code>verbosity 2
</code></pre>
<h2>
<a name="mutually-exclusive-groups" class="anchor" href="#mutually-exclusive-groups"><span class="octicon octicon-link"></span></a>Mutually exclusive groups</h2>
<p>A group of options can be marked as mutually exclusive using <code>:mutex()</code> method of the Parser class. </p>
<div class="highlight highlight-lua"><pre><span class="n">parser</span><span class="p">:</span><span class="n">mutex</span><span class="p">(</span>
<span class="n">parser</span><span class="p">:</span><span class="n">flag</span> <span class="s2">"</span><span class="s">-q"</span> <span class="s2">"</span><span class="s">--quiet"</span><span class="p">,</span>
<span class="n">parser</span><span class="p">:</span><span class="n">flag</span> <span class="s2">"</span><span class="s">-v"</span> <span class="s2">"</span><span class="s">--verbose"</span>
<span class="p">)</span>
</pre></div>
<p>If more than one element of a mutually exclusive group is used, an error is raised. </p>
<div class="highlight highlight-bash"><pre><span class="nv">$ </span>lua script.lua -qv
</pre></div>
<pre><code>Usage: script.lua ([-q] | [-v]) [-h]
Error: option '-v' can not be used together with option '-q'
</code></pre>
<h2>
<a name="commands" class="anchor" href="#commands"><span class="octicon octicon-link"></span></a>Commands</h2>
<p>A command is a subparser invoked when its name is passed as an argument. For example, in luarocks CLI <code>install</code>, <code>make</code>, <code>build</code>, etc. are commands. Each command has its own set of arguments and options. </p>
<p>Commands can be added using <code>:command()</code> method. Just as options, commands can have several aliases. </p>
<div class="highlight highlight-lua"><pre><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="s2">"</span><span class="s">i"</span>
</pre></div>
<p>If a command it used, <code>true</code> is stored in the corresponding field of the result table. </p>
<div class="highlight highlight-bash"><pre><span class="nv">$ </span>lua script.lua install
</pre></div>
<pre><code>install true
</code></pre>
<p>A typo will result in an appropriate error message: </p>
<div class="highlight highlight-bash"><pre><span class="nv">$ </span>lua script.lua instal
</pre></div>
<pre><code>Usage: script.lua [-h] &lt;command&gt; ...
Error: unknown command 'instal'
Did you mean 'install'?
</code></pre>
<h3>
<a name="adding-elements-to-commands" class="anchor" href="#adding-elements-to-commands"><span class="octicon octicon-link"></span></a>Adding elements to commands</h3>
<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 highlight-lua"><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"</span> <span class="s2">"</span><span class="s">--from"</span>
</pre></div>
<div class="highlight highlight-bash"><pre><span class="nv">$ </span>lua script.lua install foo --from<span class="o">=</span>bar
</pre></div>
<pre><code>install true
rock foo
from bar
</code></pre>
<p>Commands have their own usage and help messages. </p>
<div class="highlight highlight-bash"><pre><span class="nv">$ </span>lua script.lua install
</pre></div>
<pre><code>Usage: script.lua install [-f &lt;from&gt;] [-h] &lt;rock&gt;
Error: too few arguments
</code></pre>
<div class="highlight highlight-bash"><pre><span class="nv">$ </span>lua script.lua install --help
</pre></div>
<pre><code>Usage: script.lua install [-f &lt;from&gt;] [-h] &lt;rock&gt;
Arguments:
rock
Options:
-f &lt;from&gt;, --from &lt;from&gt;
-h, --help Show this help message and exit.
</code></pre>
<h3>
<a name="making-a-command-optional" class="anchor" href="#making-a-command-optional"><span class="octicon octicon-link"></span></a>Making a command optional</h3>
<p>By default, if a parser has commands, using one of them is obligatory. </p>
<div class="highlight highlight-lua"><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>
<div class="highlight highlight-bash"><pre><span class="nv">$ </span>lua script.lua
</pre></div>
<pre><code>Usage: script.lua [-h] &lt;command&gt; ...
Error: a command is required
</code></pre>
<p>This can be changed using the <code>require_command</code> field. </p>
<div class="highlight highlight-lua"><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>
<p>Now not using a command is not an error:</p>
<div class="highlight highlight-bash"><pre><span class="nv">$ </span>lua script.lua
</pre></div>
<p>produces nothing. </p>
<h2>
<a name="default-values" class="anchor" href="#default-values"><span class="octicon octicon-link"></span></a>Default values</h2>
<p>For elements such as arguments and options, if <code>default</code> field is set, its value is stored in case the element was not used. </p>
<div class="highlight highlight-lua"><pre><span class="n">parser</span><span class="p">:</span><span class="n">option</span> <span class="s2">"</span><span class="s">-o"</span> <span class="s2">"</span><span class="s">--output"</span>
<span class="p">:</span><span class="n">default</span> <span class="s2">"</span><span class="s">a.out"</span>
</pre></div>
<div class="highlight highlight-bash"><pre><span class="nv">$ </span>lua script.lua
</pre></div>
<pre><code>output a.out
</code></pre>
<p>The existence of a default value is reflected in help message. </p>
<div class="highlight highlight-bash"><pre><span class="nv">$ </span>lua script.lua --help
</pre></div>
<pre><code>Usage: script [-o &lt;output&gt;] [-h]
Options:
-o &lt;output&gt;, --output &lt;output&gt;
default: a.out
-h, --help Show this help message and exit.
</code></pre>
<p>Note that invocation without required arguments is still an error. </p>
<div class="highlight highlight-bash"><pre><span class="nv">$ </span>lua script.lua -o
</pre></div>
<pre><code>Usage: script [-o &lt;output&gt;] [-h]
Error: too few arguments
</code></pre>
<h3>
<a name="default-mode" class="anchor" href="#default-mode"><span class="octicon octicon-link"></span></a>Default mode</h3>
<p>The <code>defmode</code> field regulates how argparse should use the default value of an element. </p>
<p>If <code>defmode</code> contains <code>"u"</code>(for <code>unused</code>), the default value will be automatically passed to the element if it was not invoked at all. This is the default behavior. </p>
<p>If <code>defmode</code> contains <code>"a"</code>(for <code>argument</code>), the default value will be automatically passed to the element if not enough arguments were passed, or not enough invocations were made. </p>
<p>Consider the difference: </p>
<div class="highlight highlight-lua"><pre><span class="n">parser</span><span class="p">:</span><span class="n">option</span> <span class="s2">"</span><span class="s">-o"</span>
<span class="p">:</span><span class="n">default</span> <span class="s2">"</span><span class="s">a.out"</span>
<span class="n">parser</span><span class="p">:</span><span class="n">option</span> <span class="s2">"</span><span class="s">-p"</span>
<span class="p">:</span><span class="n">default</span> <span class="s2">"</span><span class="s">password"</span>
<span class="p">:</span><span class="n">defmode</span> <span class="s2">"</span><span class="s">arg"</span>
</pre></div>
<div class="highlight highlight-bash"><pre><span class="nv">$ </span>lua script.lua -h
</pre></div>
<pre><code>Usage: script [-o &lt;o&gt;] [-p [&lt;p&gt;]] [-h]
Options:
-o &lt;o&gt; default: a.out
-p [&lt;p&gt;] default: password
-h, --help Show this help message and exit.
</code></pre>
<div class="highlight highlight-bash"><pre><span class="nv">$ </span>lua script.lua
</pre></div>
<pre><code>o a.out
</code></pre>
<div class="highlight highlight-bash"><pre><span class="nv">$ </span>lua script.lua -p
</pre></div>
<pre><code>o a.out
p password
</code></pre>
<div class="highlight highlight-bash"><pre><span class="nv">$ </span>lua script.lua -o
</pre></div>
<pre><code>Usage: script [-o &lt;o&gt;] [-p [&lt;p&gt;]] [-h]
Error: too few arguments
</code></pre>
<h2>
<a name="converters" class="anchor" href="#converters"><span class="octicon octicon-link"></span></a>Converters</h2>
<p>argparse can perform automatic validation and conversion on arguments. If <code>convert</code> field of an element is a function, it will be applied to all the arguments passed to it. The function should return <code>nil</code> and, optionally, an error message if conversion failed. Standard <code>tonumber</code> and <code>io.open</code> functions work exactly like that. </p>
<div class="highlight highlight-lua"><pre><span class="n">parser</span><span class="p">:</span><span class="n">argument</span> <span class="s2">"</span><span class="s">input"</span>
<span class="p">:</span><span class="n">convert</span><span class="p">(</span><span class="nb">io.open</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">-t"</span> <span class="s2">"</span><span class="s">--times"</span>
<span class="p">:</span><span class="n">convert</span><span class="p">(</span><span class="nb">tonumber</span><span class="p">)</span>
</pre></div>
<div class="highlight highlight-bash"><pre><span class="nv">$ </span>lua script.lua foo.txt -t5
</pre></div>
<pre><code>input file (0xaddress)
times 5 (number)
</code></pre>
<div class="highlight highlight-bash"><pre><span class="nv">$ </span>lua script.lua nonexistent.txt
</pre></div>
<pre><code>Usage: script.lua [-t &lt;times&gt;] [-h] &lt;input&gt;
Error: nonexistent.txt: No such file or directory
</code></pre>
<div class="highlight highlight-bash"><pre><span class="nv">$ </span>lua script.lua foo.txt --times<span class="o">=</span>many
</pre></div>
<pre><code>Usage: script.lua [-t &lt;times&gt;] [-h] &lt;input&gt;
Error: malformed argument 'many'
</code></pre>
<h3>
<a name="table-converters" class="anchor" href="#table-converters"><span class="octicon octicon-link"></span></a>Table converters</h3>
<p>If <code>convert</code> field of an element contains a table, arguments passed to it will be used as keys. If a key is missing, an error is raised. </p>
<div class="highlight highlight-lua"><pre><span class="n">parser</span><span class="p">:</span><span class="n">argument</span> <span class="s2">"</span><span class="s">choice"</span>
<span class="p">:</span><span class="n">convert</span> <span class="p">{</span>
<span class="n">foo</span> <span class="o">=</span> <span class="s2">"</span><span class="s">Something foo-related"</span><span class="p">,</span>
<span class="n">bar</span> <span class="o">=</span> <span class="s2">"</span><span class="s">Something bar-related"</span>
<span class="p">}</span>
</pre></div>
<div class="highlight highlight-bash"><pre><span class="nv">$ </span>lua script.lua bar
</pre></div>
<pre><code>choice Something bar-related
</code></pre>
<div class="highlight highlight-bash"><pre><span class="nv">$ </span>lua script.lua baz
</pre></div>
<pre><code>Usage: script.lua [-h] &lt;choice&gt;
Error: malformed argument 'baz'
</code></pre>
<h2>
<a name="actions" class="anchor" href="#actions"><span class="octicon octicon-link"></span></a>Actions</h2>
<p>argparse can trigger a callback when an option or a command is encountered. The callback can be set using <code>action</code> field. Actions are called regardless of whether the rest of command line arguments are correct. </p>
<div class="highlight highlight-lua"><pre><span class="n">parser</span><span class="p">:</span><span class="n">flag</span> <span class="s2">"</span><span class="s">-v"</span> <span class="s2">"</span><span class="s">--version"</span>
<span class="p">:</span><span class="n">description</span> <span class="s2">"</span><span class="s">Show version info and exit. "</span>
<span class="p">:</span><span class="n">action</span><span class="p">(</span><span class="k">function</span><span class="p">()</span>
<span class="nb">print</span><span class="p">(</span><span class="s2">"</span><span class="s">script.lua v1.0.0"</span><span class="p">)</span>
<span class="nb">os.exit</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span>
<span class="k">end</span><span class="p">)</span>
</pre></div>
<div class="highlight highlight-bash"><pre><span class="nv">$ </span>lua script.lua -v
</pre></div>
<pre><code>script.lua v1.0.0
</code></pre>
<p>This example would work even if the script had mandatory arguments. </p>
<h2>
<a name="miscellaneous" class="anchor" href="#miscellaneous"><span class="octicon octicon-link"></span></a>Miscellaneous</h2>
<h3>
<a name="overwriting-default-help-option" class="anchor" href="#overwriting-default-help-option"><span class="octicon octicon-link"></span></a>Overwriting default help option</h3>
<p>If the field <code>add_help</code> of a parser is set to false, no help option will be added to it. Otherwise, the value of the field will be used to configure it. </p>
<div class="highlight highlight-lua"><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">add_help</span> <span class="s2">"</span><span class="s">/?"</span>
</pre></div>
<div class="highlight highlight-bash"><pre><span class="nv">$ </span>lua script.lua /?
</pre></div>
<pre><code>Usage: script.lua [/?]
Options:
/? Show this help message and exit.
</code></pre>
<h3>
<a name="configuring-usage-and-help-messages" class="anchor" href="#configuring-usage-and-help-messages"><span class="octicon octicon-link"></span></a>Configuring usage and help messages</h3>
<h4>
<a name="description-and-epilog" class="anchor" href="#description-and-epilog"><span class="octicon octicon-link"></span></a>Description and epilog</h4>
<p>The value of <code>description</code> field of a parser is placed between the usage message and the argument list in the help message. </p>
<p>The value of <code>epilog</code> field is appended to the help message. </p>
<div class="highlight highlight-lua"><pre><span class="kd">local</span> <span class="n">parser</span> <span class="o">=</span> <span class="n">argparse</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 description. "</span>
<span class="p">:</span><span class="n">epilog</span> <span class="s2">"</span><span class="s">An epilog. "</span>
</pre></div>
<div class="highlight highlight-bash"><pre><span class="nv">$ </span>lua script.lua --help
</pre></div>
<pre><code>Usage: script [-h]
A description.
Options:
-h, --help Show this help message and exit.
An epilog.
</code></pre>
<h4>
<a name="argument-placeholder" class="anchor" href="#argument-placeholder"><span class="octicon octicon-link"></span></a>Argument placeholder</h4>
<p>For options and arguments, <code>argname</code> field controls the placeholder for the argument in the usage message. </p>
<div class="highlight highlight-lua"><pre><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="p">:</span><span class="n">argname</span> <span class="s2">"</span><span class="s">&lt;server&gt;"</span>
</pre></div>
<div class="highlight highlight-bash"><pre><span class="nv">$ </span>lua script.lua --help
</pre></div>
<pre><code>Usage: script.lua [-f &lt;server&gt;] [-h]
Options:
-f &lt;server&gt;, --from &lt;server&gt;
-h, --help Show this help message and exit.
</code></pre>
<p><code>argname</code> can be an array of placeholders. </p>
<div class="highlight highlight-lua"><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="p">:</span><span class="n">argname</span><span class="p">{</span><span class="s2">"</span><span class="s">&lt;key&gt;"</span><span class="p">,</span> <span class="s2">"</span><span class="s">&lt;value&gt;"</span><span class="p">}</span>
</pre></div>
<div class="highlight highlight-bash"><pre><span class="nv">$ </span>lua script.lua --help
</pre></div>
<pre><code>Usage: script.lua [--pair &lt;key&gt; &lt;value&gt;] [-h]
Options:
--pair &lt;key&gt; &lt;value&gt;
-h, --help Show this help message and exit.
</code></pre>
<h3>
<a name="prohibiting-overuse-of-options" class="anchor" href="#prohibiting-overuse-of-options"><span class="octicon octicon-link"></span></a>Prohibiting overuse of options</h3>
<p>By default, if an option is invoked too many times, latest invocations overwrite the data passed earlier. </p>
<div class="highlight highlight-lua"><pre><span class="n">parser</span><span class="p">:</span><span class="n">option</span> <span class="s2">"</span><span class="s">-o"</span> <span class="s2">"</span><span class="s">--output"</span>
</pre></div>
<div class="highlight highlight-bash"><pre><span class="nv">$ </span>lua script.lua -oFOO -oBAR
</pre></div>
<pre><code>output BAR
</code></pre>
<p>Set the <code>overwrite</code> field to false to prohibit this behavior. </p>
<div class="highlight highlight-lua"><pre><span class="n">parser</span><span class="p">:</span><span class="n">option</span> <span class="s2">"</span><span class="s">-o"</span> <span class="s2">"</span><span class="s">--output"</span>
<span class="p">:</span><span class="n">overwrite</span><span class="p">(</span><span class="kc">false</span><span class="p">)</span>
</pre></div>
<div class="highlight highlight-bash"><pre><span class="nv">$ </span>lua script.lua -oFOO -oBAR
</pre></div>
<pre><code>Usage: script.lua [-o &lt;output&gt;] [-h]
Error: option '-o' must be used at most 1 time
</code></pre>
<h3>
<a name="generating-usage-and-help-messages" class="anchor" href="#generating-usage-and-help-messages"><span class="octicon octicon-link"></span></a>Generating usage and help messages</h3>
<p><code>:get_help()</code> and <code>:get_usage()</code> methods of Parser and Command classes can be used to generate their help and usage messages. </p>
<h3>
<a name="parsing-algorithm" class="anchor" href="#parsing-algorithm"><span class="octicon octicon-link"></span></a>Parsing algorithm</h3>
<p>argparse interprets command line arguments in the following way: </p>
<table>
<thead><tr>
<th>Argument</th>
<th>Interpretation</th>
</tr></thead>
<tbody>
<tr>
<td><code>foo</code></td>
<td>An argument of an option or a positional argument.</td>
</tr>
<tr>
<td><code>--foo</code></td>
<td>An option.</td>
</tr>
<tr>
<td><code>--foo=bar</code></td>
<td>An option and its argument. The option must be able to take arguments.</td>
</tr>
<tr>
<td><code>-f</code></td>
<td>An option.</td>
</tr>
<tr>
<td><code>-abcdef</code></td>
<td>Letters are interpreted as options. If one of them can take an argument, the rest of the string is passed to it.</td>
</tr>
<tr>
<td><code>--</code></td>
<td>The rest of the command line arguments will be interpreted as positional arguments.</td>
</tr>
</tbody>
</table>
</section>
</div>
<!-- FOOTER -->
<div id="footer_wrap" class="outer">
<footer class="inner">
<p class="copyright">Argparse is maintained by <a href="https://github.com/mpeterv">mpeterv</a></p>
</footer>
</div>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink