1564 lines
No EOL
140 KiB
HTML
1564 lines
No EOL
140 KiB
HTML
<!DOCTYPE html>
|
||
<html lang="en">
|
||
<head>
|
||
<meta charset="utf-8">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
<meta name="generator" content="rustdoc">
|
||
<meta name="description" content="API documentation for the Rust `Arg` struct in crate `clap`.">
|
||
<meta name="keywords" content="rust, rustlang, rust-lang, Arg">
|
||
|
||
<title>clap::Arg - Rust</title>
|
||
|
||
<link rel="stylesheet" type="text/css" href="../rustdoc.css">
|
||
<link rel="stylesheet" type="text/css" href="../main.css">
|
||
|
||
|
||
|
||
|
||
</head>
|
||
<body class="rustdoc">
|
||
<!--[if lte IE 8]>
|
||
<div class="warning">
|
||
This old browser is unsupported and will most likely display funky
|
||
things.
|
||
</div>
|
||
<![endif]-->
|
||
|
||
|
||
|
||
<nav class="sidebar">
|
||
|
||
<p class='location'><a href='index.html'>clap</a></p><script>window.sidebarCurrent = {name: 'Arg', ty: 'struct', relpath: ''};</script><script defer src="sidebar-items.js"></script>
|
||
</nav>
|
||
|
||
<nav class="sub">
|
||
<form class="search-form js-only">
|
||
<div class="search-container">
|
||
<input class="search-input" name="search"
|
||
autocomplete="off"
|
||
placeholder="Click or press ‘S’ to search, ‘?’ for more options…"
|
||
type="search">
|
||
</div>
|
||
</form>
|
||
</nav>
|
||
|
||
<section id='main' class="content struct">
|
||
<h1 class='fqn'><span class='in-band'>Struct <a href='index.html'>clap</a>::<wbr><a class='struct' href=''>Arg</a></span><span class='out-of-band'><span id='render-detail'>
|
||
<a id="toggle-all-docs" href="javascript:void(0)" title="collapse all docs">
|
||
[<span class='inner'>−</span>]
|
||
</a>
|
||
</span><a id='src-2735' class='srclink' href='../src/clap/args/arg.rs.html#34-75' title='goto source code'>[src]</a></span></h1>
|
||
<pre class='rust struct'>pub struct Arg<'a, 'b> <span class='where'>where 'a: 'b</span> {
|
||
// some fields omitted
|
||
}</pre><div class='docblock'><p>The abstract representation of a command line argument. Used to set all the options and
|
||
relationships that define a valid argument for the program.</p>
|
||
|
||
<p>There are two methods for constructing <code>Arg</code>s, using the builder pattern and setting options
|
||
manually, or using a usage string which is far less verbose but has fewer options. You can also
|
||
use a combination of the two methods to achieve the best of both worlds.</p>
|
||
|
||
<h1 id='examples' class='section-header'><a href='#examples'>Examples</a></h1>
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='comment'>// Using the traditional builder pattern and setting each option manually</span>
|
||
<span class='kw'>let</span> <span class='ident'>cfg</span> <span class='op'>=</span> <span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"config"</span>)
|
||
.<span class='ident'>short</span>(<span class='string'>"c"</span>)
|
||
.<span class='ident'>long</span>(<span class='string'>"config"</span>)
|
||
.<span class='ident'>takes_value</span>(<span class='boolval'>true</span>)
|
||
.<span class='ident'>value_name</span>(<span class='string'>"FILE"</span>)
|
||
.<span class='ident'>help</span>(<span class='string'>"Provides a config file to myprog"</span>);
|
||
<span class='comment'>// Using a usage string (setting a similar argument to the one above)</span>
|
||
<span class='kw'>let</span> <span class='ident'>input</span> <span class='op'>=</span> <span class='ident'>Arg</span>::<span class='ident'>from_usage</span>(<span class='string'>"-i, --input=[FILE] 'Provides an input file to the program'"</span>);</pre>
|
||
</div><h2 id='methods'>Methods</h2><h3 class='impl'><code>impl<'a, 'b> <a class='struct' href='../clap/struct.Arg.html' title='clap::Arg'>Arg</a><'a, 'b></code></h3><div class='impl-items'><h4 id='method.with_name' class='method'><code>fn <a href='#method.with_name' class='fnname'>with_name</a>(n: &'a <a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.str.html'>str</a>) -> Self</code></h4>
|
||
<div class='docblock'><p>Creates a new instance of <code>Arg</code> using a unique string name. The name will be used to get
|
||
information about whether or not the argument was used at runtime, get values, set
|
||
relationships with other args, etc..</p>
|
||
|
||
<p><strong>NOTE:</strong> In the case of arguments that take values (i.e. <code>takes_value(true)</code>)
|
||
and positional arguments (i.e. those without a preceding <code>-</code> or <code>--</code>) the name will also
|
||
be displayed when the user prints the usage/help information of the program.</p>
|
||
|
||
<h1 id='examples-1' class='section-header'><a href='#examples-1'>Examples</a></h1>
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"config"</span>)</pre>
|
||
</div><h4 id='method.from_usage' class='method'><code>fn <a href='#method.from_usage' class='fnname'>from_usage</a>(u: &'a <a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.str.html'>str</a>) -> Self</code></h4>
|
||
<div class='docblock'><p>Creates a new instance of <code>Arg</code> from a usage string. Allows creation of basic settings for
|
||
the <code>Arg</code>. The syntax is flexible, but there are some rules to follow.</p>
|
||
|
||
<p><strong>NOTE</strong>: Not all settings may be set using the usage string method. Some properties are
|
||
only available via the builder pattern.</p>
|
||
|
||
<p><strong>NOTE</strong>: Only ASCII values in <code>from_usage</code> strings are officially supported. Some UTF-8
|
||
codepoints may work just fine, but this is not guaranteed.</p>
|
||
|
||
<h1 id='syntax' class='section-header'><a href='#syntax'>Syntax</a></h1>
|
||
<p>Usage strings typically following the form:</p>
|
||
|
||
<pre><code class="language-notrust">[explicit name] [short] [long] [value names] [help string]
|
||
</code></pre>
|
||
|
||
<p>This is not a hard rule as the attributes can appear in other orders. There are also
|
||
several additional sigils which denote additional settings. Below are the details of each
|
||
portion of the string.</p>
|
||
|
||
<h3 id='explicit-name' class='section-header'><a href='#explicit-name'>Explicit Name</a></h3>
|
||
<p>This is an optional field, if it's omitted the argumenet will use one of the additioinal
|
||
fields as the name using the following priority order:</p>
|
||
|
||
<ul>
|
||
<li>Explicit Name (This always takes precedence when present)</li>
|
||
<li>Long</li>
|
||
<li>Short</li>
|
||
<li>Value Name</li>
|
||
</ul>
|
||
|
||
<p><code>clap</code> determines explicit names as the first string of characters between either <code>[]</code> or
|
||
<code><></code> where <code>[]</code> has the dual notation of meaning the argument is optional, and <code><></code> meaning
|
||
the argument is required.</p>
|
||
|
||
<p>Explicit names may be followed by:
|
||
* The multiple denotation <code>...</code></p>
|
||
|
||
<p>Example explicit names as follows (<code>ename</code> for an optional argument, and <code>rname</code> for a
|
||
required argument):</p>
|
||
|
||
<pre><code class="language-notrust">[ename] -s, --long 'some flag'
|
||
<rname> -r, --longer 'some other flag'
|
||
</code></pre>
|
||
|
||
<h3 id='short' class='section-header'><a href='#short'>Short</a></h3>
|
||
<p>This is set by placing a single character after a leading <code>-</code>.</p>
|
||
|
||
<p>Shorts may be followed by
|
||
* The multiple denotation <code>...</code>
|
||
* An optional comma <code>,</code> which is cosmetic only
|
||
* Value notation</p>
|
||
|
||
<p>Example shorts are as follows (<code>-s</code>, and <code>-r</code>):</p>
|
||
|
||
<pre><code class="language-notrust">-s, --long 'some flag'
|
||
<rname> -r [val], --longer 'some option'
|
||
</code></pre>
|
||
|
||
<h3 id='long' class='section-header'><a href='#long'>Long</a></h3>
|
||
<p>This is set by placing a word (no spaces) after a leading <code>--</code>.</p>
|
||
|
||
<p>Shorts may be followed by
|
||
* The multiple denotation <code>...</code>
|
||
* Value notation</p>
|
||
|
||
<p>Example longs are as follows (<code>--some</code>, and <code>--rapid</code>):</p>
|
||
|
||
<pre><code class="language-notrust">-s, --some 'some flag'
|
||
--rapid=[FILE] 'some option'
|
||
</code></pre>
|
||
|
||
<h3 id='values-value-notation' class='section-header'><a href='#values-value-notation'>Values (Value Notation)</a></h3>
|
||
<p>This is set by placing a word(s) between <code>[]</code> or <code><></code> optionally after <code>=</code> (although this
|
||
is cosmetic only and does not affect functionality). If an explicit name has <strong>not</strong> been
|
||
set, using <code><></code> will denote a required argument, and <code>[]</code> will denote an optional argument</p>
|
||
|
||
<p>Values may be followed by
|
||
* The multiple denotation <code>...</code>
|
||
* More Value notation</p>
|
||
|
||
<p>More than one value will also implicitly set the arguments number of values, i.e. having
|
||
two values, <code>--option [val1] [val2]</code> specifies that in order for option to be satisified it
|
||
must receive exactly two values</p>
|
||
|
||
<p>Example values are as follows (<code>FILE</code>, and <code>SPEED</code>):</p>
|
||
|
||
<pre><code class="language-notrust">-s, --some [FILE] 'some option'
|
||
--rapid=<SPEED>... 'some required multiple option'
|
||
</code></pre>
|
||
|
||
<h3 id='help-string' class='section-header'><a href='#help-string'>Help String</a></h3>
|
||
<p>The help string is denoted between a pair of single quotes <code>''</code> and may contain any characters.</p>
|
||
|
||
<p>Example help strings are as follows:</p>
|
||
|
||
<pre><code class="language-notrust">-s, --some [FILE] 'some option'
|
||
--rapid=<SPEED>... 'some required multiple option'
|
||
</code></pre>
|
||
|
||
<h3 id='additional-sigils' class='section-header'><a href='#additional-sigils'>Additional Sigils</a></h3>
|
||
<p>Multiple notation <code>...</code> (three consecutive dots/periods) specifies that this argument may
|
||
be used multiple times. Do not confuse multiple occurrences (<code>...</code>) with multiple values.
|
||
<code>--option val1 val2</code> is a single occurrence with multiple values. <code>--flag --flag</code> is
|
||
multiple occurrences (and then you can obviously have instances of both as well)</p>
|
||
|
||
<h1 id='examples-2' class='section-header'><a href='#examples-2'>Examples</a></h1>
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"myprog"</span>)
|
||
.<span class='ident'>args</span>(<span class='kw-2'>&</span>[
|
||
<span class='ident'>Arg</span>::<span class='ident'>from_usage</span>(<span class='string'>"--config <FILE> 'a required file for the configuration and no short'"</span>),
|
||
<span class='ident'>Arg</span>::<span class='ident'>from_usage</span>(<span class='string'>"-d, --debug... 'turns on debugging information and allows multiples'"</span>),
|
||
<span class='ident'>Arg</span>::<span class='ident'>from_usage</span>(<span class='string'>"[input] 'an optional input file to use'"</span>)
|
||
])</pre>
|
||
</div><h4 id='method.short' class='method'><code>fn <a href='#method.short' class='fnname'>short</a><S: <a class='trait' href='https://doc.rust-lang.org/nightly/core/convert/trait.AsRef.html' title='core::convert::AsRef'>AsRef</a><<a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.str.html'>str</a>>>(self, s: S) -> Self</code></h4>
|
||
<div class='docblock'><p>Sets the short version of the argument without the preceding <code>-</code>.</p>
|
||
|
||
<p>By default <code>clap</code> automatically assigns <code>V</code> and <code>h</code> to display version and help information
|
||
respectively. You may use <code>V</code> or <code>h</code> for your own purposes, in which case <code>clap</code> simply
|
||
will not assign those to the displaying of version or help.</p>
|
||
|
||
<p><strong>NOTE:</strong> Any leading <code>-</code> characters will be stripped, and only the first
|
||
non <code>-</code> character will be used as the <code>short</code> version</p>
|
||
|
||
<h1 id='examples-3' class='section-header'><a href='#examples-3'>Examples</a></h1>
|
||
<p>To set <code>short</code> use a single valid UTF-8 codepoint. If you supply a leading <code>-</code> such as <code>-c</code>
|
||
it will be stripped.</p>
|
||
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"config"</span>)
|
||
.<span class='ident'>short</span>(<span class='string'>"c"</span>)</pre>
|
||
|
||
<p>Setting <code>short</code> allows using the argument via a single hyphen (<code>-</code>) such as <code>-c</code></p>
|
||
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>let</span> <span class='ident'>m</span> <span class='op'>=</span> <span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"shorttest"</span>)
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"config"</span>)
|
||
.<span class='ident'>short</span>(<span class='string'>"c"</span>))
|
||
.<span class='ident'>get_matches_from</span>(<span class='macro'>vec</span><span class='macro'>!</span>[
|
||
<span class='string'>"shorttest"</span>, <span class='string'>"-c"</span>
|
||
]);
|
||
|
||
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>m</span>.<span class='ident'>is_present</span>(<span class='string'>"config"</span>));</pre>
|
||
</div><h4 id='method.long' class='method'><code>fn <a href='#method.long' class='fnname'>long</a>(self, l: &'b <a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.str.html'>str</a>) -> Self</code></h4>
|
||
<div class='docblock'><p>Sets the long version of the argument without the preceding <code>--</code>.</p>
|
||
|
||
<p>By default <code>clap</code> automatically assigns <code>version</code> and <code>help</code> to display version and help
|
||
information respectively. You may use <code>version</code> or <code>help</code> for your own purposes, in which
|
||
case <code>clap</code> simply will not assign those to the displaying of version or help automatically,
|
||
and you will have to do so manually.</p>
|
||
|
||
<p><strong>NOTE:</strong> Any leading <code>-</code> characters will be stripped</p>
|
||
|
||
<h1 id='examples-4' class='section-header'><a href='#examples-4'>Examples</a></h1>
|
||
<p>To set <code>long</code> use a word containing valid UTF-8 codepoints. If you supply a dobule leading
|
||
<code>--</code> such as <code>--config</code> they will be stripped. Hyphens in the middle of the word, however,
|
||
will <em>not</em> be stripped (i.e. <code>config-file</code> is allowed)</p>
|
||
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"cfg"</span>)
|
||
.<span class='ident'>long</span>(<span class='string'>"config"</span>)</pre>
|
||
|
||
<p>Setting <code>long</code> allows using the argument via a double hyphen (<code>--</code>) such as <code>--config</code></p>
|
||
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>let</span> <span class='ident'>m</span> <span class='op'>=</span> <span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"longtest"</span>)
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"cfg"</span>)
|
||
.<span class='ident'>long</span>(<span class='string'>"config"</span>))
|
||
.<span class='ident'>get_matches_from</span>(<span class='macro'>vec</span><span class='macro'>!</span>[
|
||
<span class='string'>"shorttest"</span>, <span class='string'>"--config"</span>
|
||
]);
|
||
|
||
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>m</span>.<span class='ident'>is_present</span>(<span class='string'>"cfg"</span>));</pre>
|
||
</div><h4 id='method.help' class='method'><code>fn <a href='#method.help' class='fnname'>help</a>(self, h: &'b <a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.str.html'>str</a>) -> Self</code></h4>
|
||
<div class='docblock'><p>Sets the help text of the argument that will be displayed to the user when they print the
|
||
usage/help information.</p>
|
||
|
||
<h1 id='examples-5' class='section-header'><a href='#examples-5'>Examples</a></h1>
|
||
<p>Any valid <code>String</code> slice is allowed as help (i.e. only valid UTF-8). The one exception is
|
||
one wishes to include a newline in the help text. To include a newline <strong>and</strong> be properly
|
||
aligned with all other arguments help text, it must be specified via <code>{n}</code> instead of <code>\n</code>.</p>
|
||
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"config"</span>)
|
||
.<span class='ident'>help</span>(<span class='string'>"The config file used by the myprog"</span>)</pre>
|
||
|
||
<p>Setting <code>help</code> displays a short message to the side of the argument when the user passes
|
||
<code>-h</code> or <code>--help</code> (by default).</p>
|
||
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>let</span> <span class='ident'>m</span> <span class='op'>=</span> <span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"helptest"</span>)
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"cfg"</span>)
|
||
.<span class='ident'>long</span>(<span class='string'>"config"</span>)
|
||
.<span class='ident'>help</span>(<span class='string'>"Some help text describing the --config arg"</span>))
|
||
.<span class='ident'>get_matches_from</span>(<span class='macro'>vec</span><span class='macro'>!</span>[
|
||
<span class='string'>"shorttest"</span>, <span class='string'>"--help"</span>
|
||
]);
|
||
|
||
<span class='comment'>// ...</span></pre>
|
||
|
||
<p>The above example displays</p>
|
||
|
||
<pre><code class="language-notrust">helptest
|
||
|
||
USAGE:
|
||
helptest [FLAGS]
|
||
|
||
FLAGS:
|
||
--config Some help text describing the --config arg
|
||
-h, --help Prints help information
|
||
-V, --version Prints version information
|
||
</code></pre>
|
||
</div><h4 id='method.required' class='method'><code>fn <a href='#method.required' class='fnname'>required</a>(self, r: <a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.bool.html'>bool</a>) -> Self</code></h4>
|
||
<div class='docblock'><p>Sets whether or not the argument is required by default. Required by default means it is
|
||
required, when no other conflicting rules have been evaluated. Conflicting rules take
|
||
precedence over being required. <strong>Default:</strong> <code>false</code></p>
|
||
|
||
<p><strong>NOTE:</strong> Flags (i.e. not positional, or arguments that take values) cannot be required.</p>
|
||
|
||
<h1 id='examples-6' class='section-header'><a href='#examples-6'>Examples</a></h1>
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"config"</span>)
|
||
.<span class='ident'>required</span>(<span class='boolval'>true</span>)</pre>
|
||
|
||
<p>Setting <code>required(true)</code> requires that the argument be used at runtime.</p>
|
||
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>let</span> <span class='ident'>res</span> <span class='op'>=</span> <span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"longtest"</span>)
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"cfg"</span>)
|
||
.<span class='ident'>required</span>(<span class='boolval'>true</span>)
|
||
.<span class='ident'>takes_value</span>(<span class='boolval'>true</span>)
|
||
.<span class='ident'>long</span>(<span class='string'>"config"</span>))
|
||
.<span class='ident'>get_matches_from_safe</span>(<span class='macro'>vec</span><span class='macro'>!</span>[
|
||
<span class='string'>"shorttest"</span>, <span class='string'>"--config"</span>, <span class='string'>"file.conf"</span>
|
||
]);
|
||
|
||
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>res</span>.<span class='ident'>is_ok</span>());</pre>
|
||
|
||
<p>Setting <code>required(true)</code> and <em>not</em> supplying that argument is an error.</p>
|
||
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>let</span> <span class='ident'>res</span> <span class='op'>=</span> <span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"longtest"</span>)
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"cfg"</span>)
|
||
.<span class='ident'>required</span>(<span class='boolval'>true</span>)
|
||
.<span class='ident'>takes_value</span>(<span class='boolval'>true</span>)
|
||
.<span class='ident'>long</span>(<span class='string'>"config"</span>))
|
||
.<span class='ident'>get_matches_from_safe</span>(<span class='macro'>vec</span><span class='macro'>!</span>[
|
||
<span class='string'>"shorttest"</span>
|
||
]);
|
||
|
||
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>res</span>.<span class='ident'>is_err</span>());
|
||
<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>res</span>.<span class='ident'>unwrap_err</span>().<span class='ident'>kind</span>, <span class='ident'>ErrorKind</span>::<span class='ident'>MissingRequiredArgument</span>);</pre>
|
||
</div><h4 id='method.required_unless' class='method'><code>fn <a href='#method.required_unless' class='fnname'>required_unless</a>(self, name: &'a <a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.str.html'>str</a>) -> Self</code></h4>
|
||
<div class='docblock'><p>Sets an arg that override this arg's required setting. (i.e. this arg will be required
|
||
unless this other argument is present).</p>
|
||
|
||
<p><strong>Pro Tip:</strong> Using <code>Arg::required_unless</code> implies <code>Arg::required</code> and is therefore not
|
||
mandatory to also set.</p>
|
||
|
||
<h1 id='examples-7' class='section-header'><a href='#examples-7'>Examples</a></h1>
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"config"</span>)
|
||
.<span class='ident'>required_unless</span>(<span class='string'>"debug"</span>)</pre>
|
||
|
||
<p>Setting <code>required_unless(name)</code> requires that the argument be used at runtime <em>unless</em>
|
||
<code>name</code> is present. In the following example, the required argument is <em>not</em> provided, but
|
||
it's not an error because the <code>unless</code> arg has been supplied.</p>
|
||
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>let</span> <span class='ident'>res</span> <span class='op'>=</span> <span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"unlesstest"</span>)
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"cfg"</span>)
|
||
.<span class='ident'>required_unless</span>(<span class='string'>"dbg"</span>)
|
||
.<span class='ident'>takes_value</span>(<span class='boolval'>true</span>)
|
||
.<span class='ident'>long</span>(<span class='string'>"config"</span>))
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"dbg"</span>)
|
||
.<span class='ident'>long</span>(<span class='string'>"debug"</span>))
|
||
.<span class='ident'>get_matches_from_safe</span>(<span class='macro'>vec</span><span class='macro'>!</span>[
|
||
<span class='string'>"unlesstest"</span>, <span class='string'>"--debug"</span>
|
||
]);
|
||
|
||
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>res</span>.<span class='ident'>is_ok</span>());</pre>
|
||
|
||
<p>Setting <code>required_unless(name)</code> and <em>not</em> supplying <code>name</code> or this arg is an error.</p>
|
||
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>let</span> <span class='ident'>res</span> <span class='op'>=</span> <span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"unlesstest"</span>)
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"cfg"</span>)
|
||
.<span class='ident'>required_unless</span>(<span class='string'>"dbg"</span>)
|
||
.<span class='ident'>takes_value</span>(<span class='boolval'>true</span>)
|
||
.<span class='ident'>long</span>(<span class='string'>"config"</span>))
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"dbg"</span>)
|
||
.<span class='ident'>long</span>(<span class='string'>"debug"</span>))
|
||
.<span class='ident'>get_matches_from_safe</span>(<span class='macro'>vec</span><span class='macro'>!</span>[
|
||
<span class='string'>"unlesstest"</span>
|
||
]);
|
||
|
||
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>res</span>.<span class='ident'>is_err</span>());
|
||
<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>res</span>.<span class='ident'>unwrap_err</span>().<span class='ident'>kind</span>, <span class='ident'>ErrorKind</span>::<span class='ident'>MissingRequiredArgument</span>);</pre>
|
||
</div><h4 id='method.required_unless_all' class='method'><code>fn <a href='#method.required_unless_all' class='fnname'>required_unless_all</a>(self, names: <a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.slice.html'>&[</a>&'a <a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.str.html'>str</a><a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.slice.html'>]</a>) -> Self</code></h4>
|
||
<div class='docblock'><p>Sets args that override this arg's required setting. (i.e. this arg will be required unless
|
||
all these other argument are present).</p>
|
||
|
||
<p><strong>NOTE:</strong> If you wish for the this argument to only be required if <em>one of</em> these args are
|
||
present see <code>Arg::required_unless_one</code></p>
|
||
|
||
<h1 id='examples-8' class='section-header'><a href='#examples-8'>Examples</a></h1>
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"config"</span>)
|
||
.<span class='ident'>required_unless_all</span>(<span class='kw-2'>&</span>[<span class='string'>"cfg"</span>, <span class='string'>"dbg"</span>])</pre>
|
||
|
||
<p>Setting <code>required_unless_all(names)</code> requires that the argument be used at runtime <em>unless</em>
|
||
<em>all</em> the args in <code>names</code> are present. In the following example, the required argument is
|
||
<em>not</em> provided, but it's not an error because all the <code>unless</code> args have been supplied.</p>
|
||
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>let</span> <span class='ident'>res</span> <span class='op'>=</span> <span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"unlessall"</span>)
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"cfg"</span>)
|
||
.<span class='ident'>required_unless_all</span>(<span class='kw-2'>&</span>[<span class='string'>"dbg"</span>, <span class='string'>"infile"</span>])
|
||
.<span class='ident'>takes_value</span>(<span class='boolval'>true</span>)
|
||
.<span class='ident'>long</span>(<span class='string'>"config"</span>))
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"dbg"</span>)
|
||
.<span class='ident'>long</span>(<span class='string'>"debug"</span>))
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"infile"</span>)
|
||
.<span class='ident'>short</span>(<span class='string'>"i"</span>)
|
||
.<span class='ident'>takes_value</span>(<span class='boolval'>true</span>))
|
||
.<span class='ident'>get_matches_from_safe</span>(<span class='macro'>vec</span><span class='macro'>!</span>[
|
||
<span class='string'>"unlessall"</span>, <span class='string'>"--debug"</span>, <span class='string'>"-i"</span>, <span class='string'>"file"</span>
|
||
]);
|
||
|
||
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>res</span>.<span class='ident'>is_ok</span>());</pre>
|
||
|
||
<p>Setting <code>required_unless_all(names)</code> and <em>not</em> supplying <em>all</em> of <code>names</code> or this arg is an
|
||
error.</p>
|
||
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>let</span> <span class='ident'>res</span> <span class='op'>=</span> <span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"unlessall"</span>)
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"cfg"</span>)
|
||
.<span class='ident'>required_unless_all</span>(<span class='kw-2'>&</span>[<span class='string'>"dbg"</span>, <span class='string'>"infile"</span>])
|
||
.<span class='ident'>takes_value</span>(<span class='boolval'>true</span>)
|
||
.<span class='ident'>long</span>(<span class='string'>"config"</span>))
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"dbg"</span>)
|
||
.<span class='ident'>long</span>(<span class='string'>"debug"</span>))
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"infile"</span>)
|
||
.<span class='ident'>short</span>(<span class='string'>"i"</span>)
|
||
.<span class='ident'>takes_value</span>(<span class='boolval'>true</span>))
|
||
.<span class='ident'>get_matches_from_safe</span>(<span class='macro'>vec</span><span class='macro'>!</span>[
|
||
<span class='string'>"unlessall"</span>
|
||
]);
|
||
|
||
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>res</span>.<span class='ident'>is_err</span>());
|
||
<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>res</span>.<span class='ident'>unwrap_err</span>().<span class='ident'>kind</span>, <span class='ident'>ErrorKind</span>::<span class='ident'>MissingRequiredArgument</span>);</pre>
|
||
</div><h4 id='method.required_unless_one' class='method'><code>fn <a href='#method.required_unless_one' class='fnname'>required_unless_one</a>(self, names: <a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.slice.html'>&[</a>&'a <a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.str.html'>str</a><a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.slice.html'>]</a>) -> Self</code></h4>
|
||
<div class='docblock'><p>Sets args that override this arg's required setting. (i.e. this arg will be required unless
|
||
<em>at least one of</em> these other argument are present).</p>
|
||
|
||
<p><strong>NOTE:</strong> If you wish for the this argument to only be required if <em>all of</em> these args are
|
||
present see <code>Arg::required_unless_all</code></p>
|
||
|
||
<h1 id='examples-9' class='section-header'><a href='#examples-9'>Examples</a></h1>
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"config"</span>)
|
||
.<span class='ident'>required_unless_all</span>(<span class='kw-2'>&</span>[<span class='string'>"cfg"</span>, <span class='string'>"dbg"</span>])</pre>
|
||
|
||
<p>Setting <code>required_unless_one(names)</code> requires that the argument be used at runtime <em>unless</em>
|
||
<em>at least one of</em> the args in <code>names</code> are present. In the following example, the required
|
||
argument is <em>not</em> provided, but it's not an error because one the <code>unless</code> args have been
|
||
supplied.</p>
|
||
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>let</span> <span class='ident'>res</span> <span class='op'>=</span> <span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"unlessone"</span>)
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"cfg"</span>)
|
||
.<span class='ident'>required_unless_one</span>(<span class='kw-2'>&</span>[<span class='string'>"dbg"</span>, <span class='string'>"infile"</span>])
|
||
.<span class='ident'>takes_value</span>(<span class='boolval'>true</span>)
|
||
.<span class='ident'>long</span>(<span class='string'>"config"</span>))
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"dbg"</span>)
|
||
.<span class='ident'>long</span>(<span class='string'>"debug"</span>))
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"infile"</span>)
|
||
.<span class='ident'>short</span>(<span class='string'>"i"</span>)
|
||
.<span class='ident'>takes_value</span>(<span class='boolval'>true</span>))
|
||
.<span class='ident'>get_matches_from_safe</span>(<span class='macro'>vec</span><span class='macro'>!</span>[
|
||
<span class='string'>"unlessone"</span>, <span class='string'>"--debug"</span>
|
||
]);
|
||
|
||
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>res</span>.<span class='ident'>is_ok</span>());</pre>
|
||
|
||
<p>Setting <code>required_unless_one(names)</code> and <em>not</em> supplying <em>at least one of</em> <code>names</code> or this
|
||
arg is an error.</p>
|
||
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>let</span> <span class='ident'>res</span> <span class='op'>=</span> <span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"unlessone"</span>)
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"cfg"</span>)
|
||
.<span class='ident'>required_unless_one</span>(<span class='kw-2'>&</span>[<span class='string'>"dbg"</span>, <span class='string'>"infile"</span>])
|
||
.<span class='ident'>takes_value</span>(<span class='boolval'>true</span>)
|
||
.<span class='ident'>long</span>(<span class='string'>"config"</span>))
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"dbg"</span>)
|
||
.<span class='ident'>long</span>(<span class='string'>"debug"</span>))
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"infile"</span>)
|
||
.<span class='ident'>short</span>(<span class='string'>"i"</span>)
|
||
.<span class='ident'>takes_value</span>(<span class='boolval'>true</span>))
|
||
.<span class='ident'>get_matches_from_safe</span>(<span class='macro'>vec</span><span class='macro'>!</span>[
|
||
<span class='string'>"unlessone"</span>
|
||
]);
|
||
|
||
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>res</span>.<span class='ident'>is_err</span>());
|
||
<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>res</span>.<span class='ident'>unwrap_err</span>().<span class='ident'>kind</span>, <span class='ident'>ErrorKind</span>::<span class='ident'>MissingRequiredArgument</span>);</pre>
|
||
</div><h4 id='method.conflicts_with' class='method'><code>fn <a href='#method.conflicts_with' class='fnname'>conflicts_with</a>(self, name: &'a <a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.str.html'>str</a>) -> Self</code></h4>
|
||
<div class='docblock'><p>Sets a conflicting argument by name. I.e. when using this argument,
|
||
the following argument can't be present and vice versa.</p>
|
||
|
||
<p><strong>NOTE:</strong> Conflicting rules take precedence over being required by default. Conflict rules
|
||
only need to be set for one of the two arguments, they do not need to be set for each.</p>
|
||
|
||
<p><strong>NOTE:</strong> Defining a conflict is two-way, but does <em>not</em> need to defined for both arguments
|
||
(i.e. if A conflicts with B, defining A.conflicts_with(B) is sufficient. You do not need
|
||
need to also do B.conflicts_with(A))</p>
|
||
|
||
<h1 id='examples-10' class='section-header'><a href='#examples-10'>Examples</a></h1>
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"config"</span>)
|
||
.<span class='ident'>conflicts_with</span>(<span class='string'>"debug"</span>)</pre>
|
||
|
||
<p>Setting conflicting argument, and having both arguments present at runtime is an error.</p>
|
||
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>let</span> <span class='ident'>res</span> <span class='op'>=</span> <span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"conflictions"</span>)
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"cfg"</span>)
|
||
.<span class='ident'>takes_value</span>(<span class='boolval'>true</span>)
|
||
.<span class='ident'>conflicts_with</span>(<span class='string'>"debug"</span>)
|
||
.<span class='ident'>long</span>(<span class='string'>"config"</span>))
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"debug"</span>)
|
||
.<span class='ident'>long</span>(<span class='string'>"debug"</span>))
|
||
.<span class='ident'>get_matches_from_safe</span>(<span class='macro'>vec</span><span class='macro'>!</span>[
|
||
<span class='string'>"conflictions"</span>, <span class='string'>"--debug"</span>, <span class='string'>"--config"</span>, <span class='string'>"file.conf"</span>
|
||
]);
|
||
|
||
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>res</span>.<span class='ident'>is_err</span>());
|
||
<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>res</span>.<span class='ident'>unwrap_err</span>().<span class='ident'>kind</span>, <span class='ident'>ErrorKind</span>::<span class='ident'>ArgumentConflict</span>);</pre>
|
||
</div><h4 id='method.conflicts_with_all' class='method'><code>fn <a href='#method.conflicts_with_all' class='fnname'>conflicts_with_all</a>(self, names: <a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.slice.html'>&[</a>&'a <a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.str.html'>str</a><a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.slice.html'>]</a>) -> Self</code></h4>
|
||
<div class='docblock'><p>The same as <code>Arg::conflicts_with</code> but allows specifying multiple two-way conlicts per
|
||
argument.</p>
|
||
|
||
<p><strong>NOTE:</strong> Conflicting rules take precedence over being required by default. Conflict rules
|
||
only need to be set for one of the two arguments, they do not need to be set for each.</p>
|
||
|
||
<p><strong>NOTE:</strong> Defining a conflict is two-way, but does <em>not</em> need to defined for both arguments
|
||
(i.e. if A conflicts with B, defining A.conflicts_with(B) is sufficient. You do not need
|
||
need to also do B.conflicts_with(A))</p>
|
||
|
||
<h1 id='examples-11' class='section-header'><a href='#examples-11'>Examples</a></h1>
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"config"</span>)
|
||
.<span class='ident'>conflicts_with_all</span>(<span class='kw-2'>&</span>[<span class='string'>"debug"</span>, <span class='string'>"input"</span>])</pre>
|
||
|
||
<p>Setting conflicting argument, and having any of the arguments present at runtime with a
|
||
conflicting argument is an error.</p>
|
||
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>let</span> <span class='ident'>res</span> <span class='op'>=</span> <span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"conflictions"</span>)
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"cfg"</span>)
|
||
.<span class='ident'>takes_value</span>(<span class='boolval'>true</span>)
|
||
.<span class='ident'>conflicts_with_all</span>(<span class='kw-2'>&</span>[<span class='string'>"debug"</span>, <span class='string'>"input"</span>])
|
||
.<span class='ident'>long</span>(<span class='string'>"config"</span>))
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"debug"</span>)
|
||
.<span class='ident'>long</span>(<span class='string'>"debug"</span>))
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"input"</span>)
|
||
.<span class='ident'>index</span>(<span class='number'>1</span>))
|
||
.<span class='ident'>get_matches_from_safe</span>(<span class='macro'>vec</span><span class='macro'>!</span>[
|
||
<span class='string'>"conflictions"</span>, <span class='string'>"--config"</span>, <span class='string'>"file.conf"</span>, <span class='string'>"file.txt"</span>
|
||
]);
|
||
|
||
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>res</span>.<span class='ident'>is_err</span>());
|
||
<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>res</span>.<span class='ident'>unwrap_err</span>().<span class='ident'>kind</span>, <span class='ident'>ErrorKind</span>::<span class='ident'>ArgumentConflict</span>);</pre>
|
||
</div><h4 id='method.overrides_with' class='method'><code>fn <a href='#method.overrides_with' class='fnname'>overrides_with</a>(self, name: &'a <a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.str.html'>str</a>) -> Self</code></h4>
|
||
<div class='docblock'><p>Sets a overridable argument by name. I.e. this argument and the following argument
|
||
will override each other in POSIX style (whichever argument was specified at runtime
|
||
<strong>last</strong> "wins")</p>
|
||
|
||
<p><strong>NOTE:</strong> When an argument is overriden it is essentially as if it never was used, any
|
||
conflicts, requirements, etc. are evaluated <strong>after</strong> all "overrides" have been removed</p>
|
||
|
||
<h1 id='examples-12' class='section-header'><a href='#examples-12'>Examples</a></h1>
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>let</span> <span class='ident'>m</span> <span class='op'>=</span> <span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"posix"</span>)
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>from_usage</span>(<span class='string'>"-f, --flag 'some flag'"</span>)
|
||
.<span class='ident'>conflicts_with</span>(<span class='string'>"debug"</span>))
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>from_usage</span>(<span class='string'>"-d, --debug 'other flag'"</span>))
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>from_usage</span>(<span class='string'>"-c, --color 'third flag'"</span>)
|
||
.<span class='ident'>overrides_with</span>(<span class='string'>"flag"</span>))
|
||
.<span class='ident'>get_matches_from</span>(<span class='macro'>vec</span><span class='macro'>!</span>[<span class='string'>"posix"</span>, <span class='string'>"-f"</span>, <span class='string'>"-d"</span>, <span class='string'>"-c"</span>]);
|
||
<span class='comment'>// ^~~~~~~~~~~~^~~~~ flag is overriden by color</span>
|
||
|
||
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>m</span>.<span class='ident'>is_present</span>(<span class='string'>"color"</span>));
|
||
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>m</span>.<span class='ident'>is_present</span>(<span class='string'>"debug"</span>)); <span class='comment'>// even though flag conflicts with debug, it's as if flag</span>
|
||
<span class='comment'>// was never used because it was overriden with color</span>
|
||
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='op'>!</span><span class='ident'>m</span>.<span class='ident'>is_present</span>(<span class='string'>"flag"</span>));</pre>
|
||
</div><h4 id='method.overrides_with_all' class='method'><code>fn <a href='#method.overrides_with_all' class='fnname'>overrides_with_all</a>(self, names: <a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.slice.html'>&[</a>&'a <a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.str.html'>str</a><a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.slice.html'>]</a>) -> Self</code></h4>
|
||
<div class='docblock'><p>Sets multiple mutually overridable arguments by name. I.e. this argument and the following
|
||
argument will override each other in POSIX style (whichever argument was specified at
|
||
runtime <strong>last</strong> "wins")</p>
|
||
|
||
<p><strong>NOTE:</strong> When an argument is overriden it is essentially as if it never was used, any
|
||
conflicts, requirements, etc. are evaluated <strong>after</strong> all "overrides" have been removed</p>
|
||
|
||
<h1 id='examples-13' class='section-header'><a href='#examples-13'>Examples</a></h1>
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>let</span> <span class='ident'>m</span> <span class='op'>=</span> <span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"posix"</span>)
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>from_usage</span>(<span class='string'>"-f, --flag 'some flag'"</span>)
|
||
.<span class='ident'>conflicts_with</span>(<span class='string'>"color"</span>))
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>from_usage</span>(<span class='string'>"-d, --debug 'other flag'"</span>))
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>from_usage</span>(<span class='string'>"-c, --color 'third flag'"</span>)
|
||
.<span class='ident'>overrides_with_all</span>(<span class='kw-2'>&</span>[<span class='string'>"flag"</span>, <span class='string'>"debug"</span>]))
|
||
.<span class='ident'>get_matches_from</span>(<span class='macro'>vec</span><span class='macro'>!</span>[<span class='string'>"posix"</span>, <span class='string'>"-f"</span>, <span class='string'>"-d"</span>, <span class='string'>"-c"</span>]);
|
||
<span class='comment'>// ^~~~~~^~~~~~~~~ flag and debug are overriden by color</span>
|
||
|
||
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>m</span>.<span class='ident'>is_present</span>(<span class='string'>"color"</span>)); <span class='comment'>// even though flag conflicts with color, it's as if flag</span>
|
||
<span class='comment'>// and debug were never used because they were overriden</span>
|
||
<span class='comment'>// with color</span>
|
||
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='op'>!</span><span class='ident'>m</span>.<span class='ident'>is_present</span>(<span class='string'>"debug"</span>));
|
||
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='op'>!</span><span class='ident'>m</span>.<span class='ident'>is_present</span>(<span class='string'>"flag"</span>));</pre>
|
||
</div><h4 id='method.requires' class='method'><code>fn <a href='#method.requires' class='fnname'>requires</a>(self, name: &'a <a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.str.html'>str</a>) -> Self</code></h4>
|
||
<div class='docblock'><p>Sets an argument by name that is required when this one is present I.e. when
|
||
using this argument, the following argument <em>must</em> be present.</p>
|
||
|
||
<p><strong>NOTE:</strong> Conflicting rules and override rules take precedence over being required</p>
|
||
|
||
<h1 id='examples-14' class='section-header'><a href='#examples-14'>Examples</a></h1>
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"config"</span>)
|
||
.<span class='ident'>requires</span>(<span class='string'>"input"</span>)</pre>
|
||
|
||
<p>Setting <code>requires("arg")</code> requires that the argument be used at runtime if the defining
|
||
argument is used. If the defining argument isn't used, the other arguemnt isn't required</p>
|
||
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>let</span> <span class='ident'>res</span> <span class='op'>=</span> <span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"reqtest"</span>)
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"cfg"</span>)
|
||
.<span class='ident'>takes_value</span>(<span class='boolval'>true</span>)
|
||
.<span class='ident'>requires</span>(<span class='string'>"input"</span>)
|
||
.<span class='ident'>long</span>(<span class='string'>"config"</span>))
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"input"</span>)
|
||
.<span class='ident'>index</span>(<span class='number'>1</span>))
|
||
.<span class='ident'>get_matches_from_safe</span>(<span class='macro'>vec</span><span class='macro'>!</span>[
|
||
<span class='string'>"reqtest"</span>
|
||
]);
|
||
|
||
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>res</span>.<span class='ident'>is_ok</span>()); <span class='comment'>// We didn't use cfg, so input wasn't required</span></pre>
|
||
|
||
<p>Setting <code>requires("arg")</code> and <em>not</em> supplying that argument is an error.</p>
|
||
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>let</span> <span class='ident'>res</span> <span class='op'>=</span> <span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"reqtest"</span>)
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"cfg"</span>)
|
||
.<span class='ident'>takes_value</span>(<span class='boolval'>true</span>)
|
||
.<span class='ident'>requires</span>(<span class='string'>"input"</span>)
|
||
.<span class='ident'>long</span>(<span class='string'>"config"</span>))
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"input"</span>)
|
||
.<span class='ident'>index</span>(<span class='number'>1</span>))
|
||
.<span class='ident'>get_matches_from_safe</span>(<span class='macro'>vec</span><span class='macro'>!</span>[
|
||
<span class='string'>"reqtest"</span>, <span class='string'>"--config"</span>, <span class='string'>"file.conf"</span>
|
||
]);
|
||
|
||
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>res</span>.<span class='ident'>is_err</span>());
|
||
<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>res</span>.<span class='ident'>unwrap_err</span>().<span class='ident'>kind</span>, <span class='ident'>ErrorKind</span>::<span class='ident'>MissingRequiredArgument</span>);</pre>
|
||
</div><h4 id='method.requires_all' class='method'><code>fn <a href='#method.requires_all' class='fnname'>requires_all</a>(self, names: <a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.slice.html'>&[</a>&'a <a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.str.html'>str</a><a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.slice.html'>]</a>) -> Self</code></h4>
|
||
<div class='docblock'><p>Sets multiple arguments by names that are required when this one is present I.e. when
|
||
using this argument, the following arguments <em>must</em> be present.</p>
|
||
|
||
<p><strong>NOTE:</strong> Mutually exclusive and override rules take precedence over being required
|
||
by default.</p>
|
||
|
||
<h1 id='examples-15' class='section-header'><a href='#examples-15'>Examples</a></h1>
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"config"</span>)
|
||
.<span class='ident'>requires_all</span>(<span class='kw-2'>&</span>[<span class='string'>"input"</span>, <span class='string'>"output"</span>])</pre>
|
||
|
||
<p>Setting <code>requires_all(&["arg", "arg2"])</code> requires that all the arguments be used at runtime
|
||
if the defining argument is used. If the defining argument isn't used, the other arguemnt
|
||
isn't required</p>
|
||
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>let</span> <span class='ident'>res</span> <span class='op'>=</span> <span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"reqtest"</span>)
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"cfg"</span>)
|
||
.<span class='ident'>takes_value</span>(<span class='boolval'>true</span>)
|
||
.<span class='ident'>requires</span>(<span class='string'>"input"</span>)
|
||
.<span class='ident'>long</span>(<span class='string'>"config"</span>))
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"input"</span>)
|
||
.<span class='ident'>index</span>(<span class='number'>1</span>))
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"output"</span>)
|
||
.<span class='ident'>index</span>(<span class='number'>2</span>))
|
||
.<span class='ident'>get_matches_from_safe</span>(<span class='macro'>vec</span><span class='macro'>!</span>[
|
||
<span class='string'>"reqtest"</span>
|
||
]);
|
||
|
||
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>res</span>.<span class='ident'>is_ok</span>()); <span class='comment'>// We didn't use cfg, so input and output weren't required</span></pre>
|
||
|
||
<p>Setting <code>requires_all(&["arg", "arg2"])</code> and <em>not</em> supplying all the arguments is an error.</p>
|
||
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>let</span> <span class='ident'>res</span> <span class='op'>=</span> <span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"reqtest"</span>)
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"cfg"</span>)
|
||
.<span class='ident'>takes_value</span>(<span class='boolval'>true</span>)
|
||
.<span class='ident'>requires_all</span>(<span class='kw-2'>&</span>[<span class='string'>"input"</span>, <span class='string'>"output"</span>])
|
||
.<span class='ident'>long</span>(<span class='string'>"config"</span>))
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"input"</span>)
|
||
.<span class='ident'>index</span>(<span class='number'>1</span>))
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"output"</span>)
|
||
.<span class='ident'>index</span>(<span class='number'>2</span>))
|
||
.<span class='ident'>get_matches_from_safe</span>(<span class='macro'>vec</span><span class='macro'>!</span>[
|
||
<span class='string'>"reqtest"</span>, <span class='string'>"--config"</span>, <span class='string'>"file.conf"</span>, <span class='string'>"in.txt"</span>
|
||
]);
|
||
|
||
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>res</span>.<span class='ident'>is_err</span>());
|
||
<span class='comment'>// We didn't use output</span>
|
||
<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>res</span>.<span class='ident'>unwrap_err</span>().<span class='ident'>kind</span>, <span class='ident'>ErrorKind</span>::<span class='ident'>MissingRequiredArgument</span>);</pre>
|
||
</div><h4 id='method.takes_value' class='method'><code>fn <a href='#method.takes_value' class='fnname'>takes_value</a>(self, tv: <a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.bool.html'>bool</a>) -> Self</code></h4>
|
||
<div class='docblock'><p>Specifies that the argument takes a value at run time.</p>
|
||
|
||
<p><strong>NOTE:</strong> values for arguments may be specified in any of the following methods</p>
|
||
|
||
<ul>
|
||
<li>Using a space such as <code>-o value</code> or <code>--option value</code></li>
|
||
<li>Using an equals and no space such as <code>-o=value</code> or <code>--option=value</code></li>
|
||
<li>Use a short and no space such as <code>-ovalue</code></li>
|
||
</ul>
|
||
|
||
<p><strong>NOTE:</strong> By default, values are delimted by commas, meaning <code>--option=val1,val2,val3</code> is
|
||
is three values for the <code>--option</code> argument. If you wish to change the delimiter to another
|
||
character you can use <code>Arg::value_delimiter(char)</code>, alternatively you can delimiting values
|
||
<strong>OFF</strong> by using <code>Arg::use_delimiter(false)</code></p>
|
||
|
||
<h1 id='examples-16' class='section-header'><a href='#examples-16'>Examples</a></h1>
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"config"</span>)
|
||
.<span class='ident'>takes_value</span>(<span class='boolval'>true</span>)</pre>
|
||
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>let</span> <span class='ident'>m</span> <span class='op'>=</span> <span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"posvals"</span>)
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"mode"</span>)
|
||
.<span class='ident'>long</span>(<span class='string'>"mode"</span>)
|
||
.<span class='ident'>takes_value</span>(<span class='boolval'>true</span>))
|
||
.<span class='ident'>get_matches_from</span>(<span class='macro'>vec</span><span class='macro'>!</span>[<span class='string'>"posvals"</span>, <span class='string'>"--mode"</span>, <span class='string'>"fast"</span>]);
|
||
|
||
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>m</span>.<span class='ident'>is_present</span>(<span class='string'>"mode"</span>));
|
||
<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>m</span>.<span class='ident'>value_of</span>(<span class='string'>"mode"</span>), <span class='prelude-val'>Some</span>(<span class='string'>"fast"</span>));</pre>
|
||
</div><h4 id='method.index' class='method'><code>fn <a href='#method.index' class='fnname'>index</a>(self, idx: <a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.u64.html'>u64</a>) -> Self</code></h4>
|
||
<div class='docblock'><p>Specifies the index of a positional argument <strong>starting at</strong> 1.</p>
|
||
|
||
<p><strong>NOTE:</strong> The index refers to position according to <strong>other positional argument</strong>. It does
|
||
not define position in the argument list as a whole.</p>
|
||
|
||
<p><strong>NOTE:</strong> If no <code>short</code>, or <code>long</code> have been defined, you can optionally leave off the
|
||
<code>index</code> method, and the index will be assigned in order of evaluation. Utilizing the
|
||
<code>index</code> method allows for setting indexes out of order</p>
|
||
|
||
<p><strong>NOTE:</strong> When utilized with <code>multiple(true)</code>, only the <strong>last</strong> psoitional argument may
|
||
be defined as multiple (i.e. with the highest index)</p>
|
||
|
||
<h1 id='panics' class='section-header'><a href='#panics'>Panics</a></h1>
|
||
<p>Although not in this method directly, <code>App</code> will <code>panic!</code> if indexes are skipped (such as
|
||
defining <code>index(1)</code> and <code>index(3)</code> but not <code>index(2)</code>, or a positional argument is defined
|
||
as multiple and is not the highest index</p>
|
||
|
||
<h1 id='examples-17' class='section-header'><a href='#examples-17'>Examples</a></h1>
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"config"</span>)
|
||
.<span class='ident'>index</span>(<span class='number'>1</span>)</pre>
|
||
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>let</span> <span class='ident'>m</span> <span class='op'>=</span> <span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"posvals"</span>)
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"mode"</span>)
|
||
.<span class='ident'>index</span>(<span class='number'>1</span>))
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"debug"</span>)
|
||
.<span class='ident'>long</span>(<span class='string'>"debug"</span>))
|
||
.<span class='ident'>get_matches_from</span>(<span class='macro'>vec</span><span class='macro'>!</span>[<span class='string'>"posvals"</span>, <span class='string'>"--debug"</span>, <span class='string'>"fast"</span>]);
|
||
|
||
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>m</span>.<span class='ident'>is_present</span>(<span class='string'>"mode"</span>));
|
||
<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>m</span>.<span class='ident'>value_of</span>(<span class='string'>"mode"</span>), <span class='prelude-val'>Some</span>(<span class='string'>"fast"</span>)); <span class='comment'>// notice index(1) means "first positional"</span>
|
||
<span class='comment'>// *not* first argument</span></pre>
|
||
</div><h4 id='method.multiple' class='method'><code>fn <a href='#method.multiple' class='fnname'>multiple</a>(self, multi: <a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.bool.html'>bool</a>) -> Self</code></h4>
|
||
<div class='docblock'><p>Specifies that the argument may appear more than once. For flags, this results
|
||
in the number of occurrences of the flag being recorded. For example <code>-ddd</code> or <code>-d -d -d</code>
|
||
would count as three occurrences. For options there is a distinct difference in multiple
|
||
occurrences vs multiple values.</p>
|
||
|
||
<p>For example, <code>--opt val1 val2</code> is one occurrence, but two values. Whereas
|
||
<code>--opt val1 --opt val2</code> is two occurrences.</p>
|
||
|
||
<p><strong>WARNING:</strong></p>
|
||
|
||
<p>Setting <code>multipe(true)</code> for an option allows multiple values <strong>and</strong> multiple occurrences
|
||
because it isn't possible to more occurrences than values for options. Because multiple
|
||
values are allowed, <code>--option val1 val2 val3</code> is perfectly valid, be careful when designing
|
||
a CLI where positional arguments are expectd after a option which accepts multiple values,
|
||
as <code>clap</code> will continue parsing <em>values</em> until it reaches the max or specific number of values defined, or another flag
|
||
or option.</p>
|
||
|
||
<p><strong>Pro Tip</strong>:</p>
|
||
|
||
<p>It's possible to define an option which allows multiple occurrences, but only one value per
|
||
occurrence. To do this use <code>Arg::number_of_values(1)</code> in coordination with
|
||
<code>Arg::multiple(true)</code>.</p>
|
||
|
||
<h1 id='examples-18' class='section-header'><a href='#examples-18'>Examples</a></h1>
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"debug"</span>)
|
||
.<span class='ident'>short</span>(<span class='string'>"d"</span>)
|
||
.<span class='ident'>multiple</span>(<span class='boolval'>true</span>)</pre>
|
||
|
||
<p>An example with flags</p>
|
||
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>let</span> <span class='ident'>m</span> <span class='op'>=</span> <span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"mults"</span>)
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"verbose"</span>)
|
||
.<span class='ident'>multiple</span>(<span class='boolval'>true</span>)
|
||
.<span class='ident'>short</span>(<span class='string'>"v"</span>))
|
||
.<span class='ident'>get_matches_from</span>(<span class='macro'>vec</span><span class='macro'>!</span>[<span class='string'>"mults"</span>, <span class='string'>"-v"</span>, <span class='string'>"-v"</span>, <span class='string'>"-v"</span>]); <span class='comment'>// note, -vvv would have same result</span>
|
||
|
||
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>m</span>.<span class='ident'>is_present</span>(<span class='string'>"verbose"</span>));
|
||
<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>m</span>.<span class='ident'>occurrences_of</span>(<span class='string'>"verbose"</span>), <span class='number'>3</span>);</pre>
|
||
|
||
<p>An example with options</p>
|
||
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>let</span> <span class='ident'>m</span> <span class='op'>=</span> <span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"mults"</span>)
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"file"</span>)
|
||
.<span class='ident'>multiple</span>(<span class='boolval'>true</span>)
|
||
.<span class='ident'>takes_value</span>(<span class='boolval'>true</span>)
|
||
.<span class='ident'>short</span>(<span class='string'>"F"</span>))
|
||
.<span class='ident'>get_matches_from</span>(<span class='macro'>vec</span><span class='macro'>!</span>[<span class='string'>"mults"</span>, <span class='string'>"-F"</span>, <span class='string'>"file1"</span>, <span class='string'>"file2"</span>, <span class='string'>"file3"</span>]);
|
||
|
||
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>m</span>.<span class='ident'>is_present</span>(<span class='string'>"file"</span>));
|
||
<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>m</span>.<span class='ident'>occurrences_of</span>(<span class='string'>"file"</span>), <span class='number'>1</span>); <span class='comment'>// notice only one occurrence</span>
|
||
<span class='kw'>let</span> <span class='ident'>files</span>: <span class='ident'>Vec</span><span class='op'><</span>_<span class='op'>></span> <span class='op'>=</span> <span class='ident'>m</span>.<span class='ident'>values_of</span>(<span class='string'>"file"</span>).<span class='ident'>unwrap</span>().<span class='ident'>collect</span>();
|
||
<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>files</span>, [<span class='string'>"file1"</span>, <span class='string'>"file2"</span>, <span class='string'>"file3"</span>]);</pre>
|
||
|
||
<p>This is functionally equivilant to the example above</p>
|
||
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>let</span> <span class='ident'>m</span> <span class='op'>=</span> <span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"mults"</span>)
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"file"</span>)
|
||
.<span class='ident'>multiple</span>(<span class='boolval'>true</span>)
|
||
.<span class='ident'>takes_value</span>(<span class='boolval'>true</span>)
|
||
.<span class='ident'>short</span>(<span class='string'>"F"</span>))
|
||
.<span class='ident'>get_matches_from</span>(<span class='macro'>vec</span><span class='macro'>!</span>[<span class='string'>"mults"</span>, <span class='string'>"-F"</span>, <span class='string'>"file1"</span>, <span class='string'>"-F"</span>, <span class='string'>"file2"</span>, <span class='string'>"-F"</span>, <span class='string'>"file3"</span>]);
|
||
<span class='kw'>let</span> <span class='ident'>files</span>: <span class='ident'>Vec</span><span class='op'><</span>_<span class='op'>></span> <span class='op'>=</span> <span class='ident'>m</span>.<span class='ident'>values_of</span>(<span class='string'>"file"</span>).<span class='ident'>unwrap</span>().<span class='ident'>collect</span>();
|
||
<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>files</span>, [<span class='string'>"file1"</span>, <span class='string'>"file2"</span>, <span class='string'>"file3"</span>]);
|
||
|
||
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>m</span>.<span class='ident'>is_present</span>(<span class='string'>"file"</span>));
|
||
<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>m</span>.<span class='ident'>occurrences_of</span>(<span class='string'>"file"</span>), <span class='number'>3</span>); <span class='comment'>// Notice 3 occurrences</span>
|
||
<span class='kw'>let</span> <span class='ident'>files</span>: <span class='ident'>Vec</span><span class='op'><</span>_<span class='op'>></span> <span class='op'>=</span> <span class='ident'>m</span>.<span class='ident'>values_of</span>(<span class='string'>"file"</span>).<span class='ident'>unwrap</span>().<span class='ident'>collect</span>();
|
||
<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>files</span>, [<span class='string'>"file1"</span>, <span class='string'>"file2"</span>, <span class='string'>"file3"</span>]);</pre>
|
||
|
||
<p>A common mistake is to define an option which allows multiples, and a positional argument</p>
|
||
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>let</span> <span class='ident'>m</span> <span class='op'>=</span> <span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"mults"</span>)
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"file"</span>)
|
||
.<span class='ident'>multiple</span>(<span class='boolval'>true</span>)
|
||
.<span class='ident'>takes_value</span>(<span class='boolval'>true</span>)
|
||
.<span class='ident'>short</span>(<span class='string'>"F"</span>))
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"word"</span>)
|
||
.<span class='ident'>index</span>(<span class='number'>1</span>))
|
||
.<span class='ident'>get_matches_from</span>(<span class='macro'>vec</span><span class='macro'>!</span>[<span class='string'>"mults"</span>, <span class='string'>"-F"</span>, <span class='string'>"file1"</span>, <span class='string'>"file2"</span>, <span class='string'>"file3"</span>, <span class='string'>"word"</span>]);
|
||
|
||
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>m</span>.<span class='ident'>is_present</span>(<span class='string'>"file"</span>));
|
||
<span class='kw'>let</span> <span class='ident'>files</span>: <span class='ident'>Vec</span><span class='op'><</span>_<span class='op'>></span> <span class='op'>=</span> <span class='ident'>m</span>.<span class='ident'>values_of</span>(<span class='string'>"file"</span>).<span class='ident'>unwrap</span>().<span class='ident'>collect</span>();
|
||
<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>files</span>, [<span class='string'>"file1"</span>, <span class='string'>"file2"</span>, <span class='string'>"file3"</span>, <span class='string'>"word"</span>]); <span class='comment'>// wait...what?!</span>
|
||
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='op'>!</span><span class='ident'>m</span>.<span class='ident'>is_present</span>(<span class='string'>"word"</span>)); <span class='comment'>// but we clearly used word!</span></pre>
|
||
|
||
<p>The problem is clap doesn't know when to stop parsing values for "files". This is further
|
||
compounded by if we'd said <code>word -F file1 file2</code> it would have worked fine, so it would
|
||
appear to only fail sometimes...not good!</p>
|
||
|
||
<p>A solution for the example above is to specify that <code>-F</code> only accepts one value, but is
|
||
allowed to appear multiple times</p>
|
||
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>let</span> <span class='ident'>m</span> <span class='op'>=</span> <span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"mults"</span>)
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"file"</span>)
|
||
.<span class='ident'>multiple</span>(<span class='boolval'>true</span>)
|
||
.<span class='ident'>takes_value</span>(<span class='boolval'>true</span>)
|
||
.<span class='ident'>number_of_values</span>(<span class='number'>1</span>)
|
||
.<span class='ident'>short</span>(<span class='string'>"F"</span>))
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"word"</span>)
|
||
.<span class='ident'>index</span>(<span class='number'>1</span>))
|
||
.<span class='ident'>get_matches_from</span>(<span class='macro'>vec</span><span class='macro'>!</span>[<span class='string'>"mults"</span>, <span class='string'>"-F"</span>, <span class='string'>"file1"</span>, <span class='string'>"-F"</span>, <span class='string'>"file2"</span>, <span class='string'>"-F"</span>, <span class='string'>"file3"</span>, <span class='string'>"word"</span>]);
|
||
|
||
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>m</span>.<span class='ident'>is_present</span>(<span class='string'>"file"</span>));
|
||
<span class='kw'>let</span> <span class='ident'>files</span>: <span class='ident'>Vec</span><span class='op'><</span>_<span class='op'>></span> <span class='op'>=</span> <span class='ident'>m</span>.<span class='ident'>values_of</span>(<span class='string'>"file"</span>).<span class='ident'>unwrap</span>().<span class='ident'>collect</span>();
|
||
<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>files</span>, [<span class='string'>"file1"</span>, <span class='string'>"file2"</span>, <span class='string'>"file3"</span>]);
|
||
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>m</span>.<span class='ident'>is_present</span>(<span class='string'>"word"</span>));
|
||
<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>m</span>.<span class='ident'>value_of</span>(<span class='string'>"word"</span>), <span class='prelude-val'>Some</span>(<span class='string'>"word"</span>));</pre>
|
||
|
||
<p>As a final example, notice if we define <code>number_of_values(1)</code> and try to run the problem
|
||
example above, it would have been a runtime error with a pretty message to the user :)</p>
|
||
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>let</span> <span class='ident'>res</span> <span class='op'>=</span> <span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"mults"</span>)
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"file"</span>)
|
||
.<span class='ident'>multiple</span>(<span class='boolval'>true</span>)
|
||
.<span class='ident'>takes_value</span>(<span class='boolval'>true</span>)
|
||
.<span class='ident'>number_of_values</span>(<span class='number'>1</span>)
|
||
.<span class='ident'>short</span>(<span class='string'>"F"</span>))
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"word"</span>)
|
||
.<span class='ident'>index</span>(<span class='number'>1</span>))
|
||
.<span class='ident'>get_matches_from_safe</span>(<span class='macro'>vec</span><span class='macro'>!</span>[<span class='string'>"mults"</span>, <span class='string'>"-F"</span>, <span class='string'>"file1"</span>, <span class='string'>"file2"</span>, <span class='string'>"file3"</span>, <span class='string'>"word"</span>]);
|
||
|
||
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>res</span>.<span class='ident'>is_err</span>());
|
||
<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>res</span>.<span class='ident'>unwrap_err</span>().<span class='ident'>kind</span>, <span class='ident'>ErrorKind</span>::<span class='ident'>UnknownArgument</span>);</pre>
|
||
</div><h4 id='method.global' class='method'><code>fn <a href='#method.global' class='fnname'>global</a>(self, g: <a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.bool.html'>bool</a>) -> Self</code></h4>
|
||
<div class='docblock'><p>Specifies that an argument can be matched to all child subcommands.</p>
|
||
|
||
<p><strong>NOTE:</strong> Global arguments <em>only</em> propagate down, <strong>not</strong> up (to parent commands)</p>
|
||
|
||
<p><strong>NOTE:</strong> Global arguments <em>cannot</em> be required.</p>
|
||
|
||
<p><strong>NOTE:</strong> Global arguments, when matched, <em>only</em> exist in the command's matches that they
|
||
were matched to. For example, if you defined a <code>--flag</code> global argument in the top most
|
||
parent command, but the user supplied the arguments <code>top cmd1 cmd2 --flag</code> <em>only</em> <code>cmd2</code>'s
|
||
<code>ArgMatches</code> would return <code>true</code> if tested for <code>.is_present("flag")</code>.</p>
|
||
|
||
<h1 id='examples-19' class='section-header'><a href='#examples-19'>Examples</a></h1>
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"debug"</span>)
|
||
.<span class='ident'>short</span>(<span class='string'>"d"</span>)
|
||
.<span class='ident'>global</span>(<span class='boolval'>true</span>)</pre>
|
||
|
||
<p>For example, assume an appliction with two subcommands, and you'd like to define a
|
||
<code>--verbose</code> flag that can be called on any of the subcommands and parent, but you don't
|
||
want to clutter the source with three duplicate <code>Arg</code> definitions.</p>
|
||
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>let</span> <span class='ident'>m</span> <span class='op'>=</span> <span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"mults"</span>)
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"verb"</span>)
|
||
.<span class='ident'>long</span>(<span class='string'>"verbose"</span>)
|
||
.<span class='ident'>short</span>(<span class='string'>"v"</span>)
|
||
.<span class='ident'>global</span>(<span class='boolval'>true</span>))
|
||
.<span class='ident'>subcommand</span>(<span class='ident'>SubCommand</span>::<span class='ident'>with_name</span>(<span class='string'>"test"</span>))
|
||
.<span class='ident'>subcommand</span>(<span class='ident'>SubCommand</span>::<span class='ident'>with_name</span>(<span class='string'>"do-stuff"</span>))
|
||
.<span class='ident'>get_matches_from</span>(<span class='macro'>vec</span><span class='macro'>!</span>[<span class='string'>"mults"</span>, <span class='string'>"do-stuff"</span>, <span class='string'>"--verbose"</span>]);
|
||
|
||
<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>m</span>.<span class='ident'>subcommand_name</span>(), <span class='prelude-val'>Some</span>(<span class='string'>"do-stuff"</span>));
|
||
<span class='kw'>let</span> <span class='ident'>sub_m</span> <span class='op'>=</span> <span class='ident'>m</span>.<span class='ident'>subcommand_matches</span>(<span class='string'>"do-stuff"</span>).<span class='ident'>unwrap</span>();
|
||
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>sub_m</span>.<span class='ident'>is_present</span>(<span class='string'>"verb"</span>));</pre>
|
||
</div><h4 id='method.empty_values' class='method'><code>fn <a href='#method.empty_values' class='fnname'>empty_values</a>(self, ev: <a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.bool.html'>bool</a>) -> Self</code></h4>
|
||
<div class='docblock'><p>Allows an argument to accept explicitly empty values. An empty value must be specified at
|
||
the command line with an explicit <code>""</code>, or <code>''</code></p>
|
||
|
||
<p><strong>NOTE:</strong> Defaults to <code>true</code> (Explicitly empty values are allowed)</p>
|
||
|
||
<p><strong>NOTE:</strong> Implicitly sets <code>takes_value(true)</code> when set to <code>false</code></p>
|
||
|
||
<h1 id='examples-20' class='section-header'><a href='#examples-20'>Examples</a></h1>
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"file"</span>)
|
||
.<span class='ident'>long</span>(<span class='string'>"file"</span>)
|
||
.<span class='ident'>empty_values</span>(<span class='boolval'>false</span>)</pre>
|
||
|
||
<p>The default is to allow empty values, such as <code>--option ""</code> would be an empty value. But
|
||
we can change to make empty values become an error.</p>
|
||
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>let</span> <span class='ident'>res</span> <span class='op'>=</span> <span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"evals"</span>)
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"cfg"</span>)
|
||
.<span class='ident'>long</span>(<span class='string'>"config"</span>)
|
||
.<span class='ident'>short</span>(<span class='string'>"v"</span>)
|
||
.<span class='ident'>empty_values</span>(<span class='boolval'>false</span>))
|
||
.<span class='ident'>get_matches_from_safe</span>(<span class='macro'>vec</span><span class='macro'>!</span>[<span class='string'>"evals"</span>, <span class='string'>"--config="</span>]);
|
||
|
||
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>res</span>.<span class='ident'>is_err</span>());
|
||
<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>res</span>.<span class='ident'>unwrap_err</span>().<span class='ident'>kind</span>, <span class='ident'>ErrorKind</span>::<span class='ident'>EmptyValue</span>);</pre>
|
||
</div><h4 id='method.hidden' class='method'><code>fn <a href='#method.hidden' class='fnname'>hidden</a>(self, h: <a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.bool.html'>bool</a>) -> Self</code></h4>
|
||
<div class='docblock'><p>Hides an argument from help message output.</p>
|
||
|
||
<p><strong>NOTE:</strong> This does <strong>not</strong> hide the argument from usage strings on error</p>
|
||
|
||
<h1 id='examples-21' class='section-header'><a href='#examples-21'>Examples</a></h1>
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"debug"</span>)
|
||
.<span class='ident'>hidden</span>(<span class='boolval'>true</span>)</pre>
|
||
|
||
<p>Setting <code>hidden(true)</code> will hide the argument when displaying help text</p>
|
||
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>let</span> <span class='ident'>m</span> <span class='op'>=</span> <span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"helptest"</span>)
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"cfg"</span>)
|
||
.<span class='ident'>long</span>(<span class='string'>"config"</span>)
|
||
.<span class='ident'>hidden</span>(<span class='boolval'>true</span>)
|
||
.<span class='ident'>help</span>(<span class='string'>"Some help text describing the --config arg"</span>))
|
||
.<span class='ident'>get_matches_from</span>(<span class='macro'>vec</span><span class='macro'>!</span>[
|
||
<span class='string'>"shorttest"</span>, <span class='string'>"--help"</span>
|
||
]);
|
||
|
||
<span class='comment'>// ...</span></pre>
|
||
|
||
<p>The above example displays</p>
|
||
|
||
<pre><code class="language-notrust">helptest
|
||
|
||
USAGE:
|
||
helptest [FLAGS]
|
||
|
||
FLAGS:
|
||
-h, --help Prints help information
|
||
-V, --version Prints version information
|
||
</code></pre>
|
||
</div><h4 id='method.possible_values' class='method'><code>fn <a href='#method.possible_values' class='fnname'>possible_values</a>(self, names: <a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.slice.html'>&[</a>&'b <a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.str.html'>str</a><a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.slice.html'>]</a>) -> Self</code></h4>
|
||
<div class='docblock'><p>Specifies a list of possible values for this argument. At runtime, <code>clap</code> verifies that only
|
||
one of the specified values was used, or fails with an error message.</p>
|
||
|
||
<p><strong>NOTE:</strong> This setting only applies to options and positional arguments</p>
|
||
|
||
<h1 id='examples-22' class='section-header'><a href='#examples-22'>Examples</a></h1>
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"mode"</span>)
|
||
.<span class='ident'>takes_value</span>(<span class='boolval'>true</span>)
|
||
.<span class='ident'>possible_values</span>(<span class='kw-2'>&</span>[<span class='string'>"fast"</span>, <span class='string'>"slow"</span>, <span class='string'>"medium"</span>])</pre>
|
||
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>let</span> <span class='ident'>m</span> <span class='op'>=</span> <span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"posvals"</span>)
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"mode"</span>)
|
||
.<span class='ident'>long</span>(<span class='string'>"mode"</span>)
|
||
.<span class='ident'>takes_value</span>(<span class='boolval'>true</span>)
|
||
.<span class='ident'>possible_values</span>(<span class='kw-2'>&</span>[<span class='string'>"fast"</span>, <span class='string'>"slow"</span>, <span class='string'>"medium"</span>]))
|
||
.<span class='ident'>get_matches_from</span>(<span class='macro'>vec</span><span class='macro'>!</span>[<span class='string'>"posvals"</span>, <span class='string'>"--mode"</span>, <span class='string'>"fast"</span>]);
|
||
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>m</span>.<span class='ident'>is_present</span>(<span class='string'>"mode"</span>));
|
||
<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>m</span>.<span class='ident'>value_of</span>(<span class='string'>"mode"</span>), <span class='prelude-val'>Some</span>(<span class='string'>"fast"</span>));</pre>
|
||
|
||
<p>The next example shows a failed parse from using a value which wasn't defined as one of the
|
||
possible values.</p>
|
||
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>let</span> <span class='ident'>res</span> <span class='op'>=</span> <span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"posvals"</span>)
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"mode"</span>)
|
||
.<span class='ident'>long</span>(<span class='string'>"mode"</span>)
|
||
.<span class='ident'>takes_value</span>(<span class='boolval'>true</span>)
|
||
.<span class='ident'>possible_values</span>(<span class='kw-2'>&</span>[<span class='string'>"fast"</span>, <span class='string'>"slow"</span>, <span class='string'>"medium"</span>]))
|
||
.<span class='ident'>get_matches_from_safe</span>(<span class='macro'>vec</span><span class='macro'>!</span>[<span class='string'>"myprog"</span>, <span class='string'>"--mode"</span>, <span class='string'>"wrong"</span>]);
|
||
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>res</span>.<span class='ident'>is_err</span>());
|
||
<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>res</span>.<span class='ident'>unwrap_err</span>().<span class='ident'>kind</span>, <span class='ident'>ErrorKind</span>::<span class='ident'>InvalidValue</span>);</pre>
|
||
</div><h4 id='method.possible_value' class='method'><code>fn <a href='#method.possible_value' class='fnname'>possible_value</a>(self, name: &'b <a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.str.html'>str</a>) -> Self</code></h4>
|
||
<div class='docblock'><p>Specifies a possible value for this argument, one at a time. At runtime, <code>clap</code> verifies
|
||
that only one of the specified values was used, or fails with error message.</p>
|
||
|
||
<h1 id='examples-23' class='section-header'><a href='#examples-23'>Examples</a></h1>
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"mode"</span>)
|
||
.<span class='ident'>takes_value</span>(<span class='boolval'>true</span>)
|
||
.<span class='ident'>possible_value</span>(<span class='string'>"fast"</span>)
|
||
.<span class='ident'>possible_value</span>(<span class='string'>"slow"</span>)
|
||
.<span class='ident'>possible_value</span>(<span class='string'>"medium"</span>)</pre>
|
||
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>let</span> <span class='ident'>m</span> <span class='op'>=</span> <span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"posvals"</span>)
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"mode"</span>)
|
||
.<span class='ident'>long</span>(<span class='string'>"mode"</span>)
|
||
.<span class='ident'>takes_value</span>(<span class='boolval'>true</span>)
|
||
.<span class='ident'>possible_value</span>(<span class='string'>"fast"</span>)
|
||
.<span class='ident'>possible_value</span>(<span class='string'>"slow"</span>)
|
||
.<span class='ident'>possible_value</span>(<span class='string'>"medium"</span>))
|
||
.<span class='ident'>get_matches_from</span>(<span class='macro'>vec</span><span class='macro'>!</span>[<span class='string'>"posvals"</span>, <span class='string'>"--mode"</span>, <span class='string'>"fast"</span>]);
|
||
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>m</span>.<span class='ident'>is_present</span>(<span class='string'>"mode"</span>));
|
||
<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>m</span>.<span class='ident'>value_of</span>(<span class='string'>"mode"</span>), <span class='prelude-val'>Some</span>(<span class='string'>"fast"</span>));</pre>
|
||
|
||
<p>The next example shows a failed parse from using a value which wasn't defined as one of the
|
||
possible values.</p>
|
||
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>let</span> <span class='ident'>res</span> <span class='op'>=</span> <span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"posvals"</span>)
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"mode"</span>)
|
||
.<span class='ident'>long</span>(<span class='string'>"mode"</span>)
|
||
.<span class='ident'>takes_value</span>(<span class='boolval'>true</span>)
|
||
.<span class='ident'>possible_value</span>(<span class='string'>"fast"</span>)
|
||
.<span class='ident'>possible_value</span>(<span class='string'>"slow"</span>)
|
||
.<span class='ident'>possible_value</span>(<span class='string'>"medium"</span>))
|
||
.<span class='ident'>get_matches_from_safe</span>(<span class='macro'>vec</span><span class='macro'>!</span>[<span class='string'>"myprog"</span>, <span class='string'>"--mode"</span>, <span class='string'>"wrong"</span>]);
|
||
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>res</span>.<span class='ident'>is_err</span>());
|
||
<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>res</span>.<span class='ident'>unwrap_err</span>().<span class='ident'>kind</span>, <span class='ident'>ErrorKind</span>::<span class='ident'>InvalidValue</span>);</pre>
|
||
</div><h4 id='method.group' class='method'><code>fn <a href='#method.group' class='fnname'>group</a>(self, name: &'a <a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.str.html'>str</a>) -> Self</code></h4>
|
||
<div class='docblock'><p>Specifies the name of the group the argument belongs to.</p>
|
||
|
||
<h1 id='examples-24' class='section-header'><a href='#examples-24'>Examples</a></h1>
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"debug"</span>)
|
||
.<span class='ident'>long</span>(<span class='string'>"debug"</span>)
|
||
.<span class='ident'>group</span>(<span class='string'>"mode"</span>)</pre>
|
||
|
||
<p>Multiple arguments can be a member of a single group and then the group checked as if it
|
||
was one of said arguments.</p>
|
||
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>let</span> <span class='ident'>m</span> <span class='op'>=</span> <span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"groups"</span>)
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"debug"</span>)
|
||
.<span class='ident'>long</span>(<span class='string'>"debug"</span>)
|
||
.<span class='ident'>group</span>(<span class='string'>"mode"</span>))
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"verbose"</span>)
|
||
.<span class='ident'>long</span>(<span class='string'>"verbose"</span>)
|
||
.<span class='ident'>group</span>(<span class='string'>"mode"</span>))
|
||
.<span class='ident'>get_matches_from</span>(<span class='macro'>vec</span><span class='macro'>!</span>[<span class='string'>"posvals"</span>, <span class='string'>"--debug"</span>]);
|
||
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>m</span>.<span class='ident'>is_present</span>(<span class='string'>"mode"</span>));</pre>
|
||
</div><h4 id='method.number_of_values' class='method'><code>fn <a href='#method.number_of_values' class='fnname'>number_of_values</a>(self, qty: <a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.u64.html'>u64</a>) -> Self</code></h4>
|
||
<div class='docblock'><p>Specifies how many values are required to satisfy this argument. For example, if you had a
|
||
<code>-f <file></code> argument where you wanted exactly 3 'files' you would set
|
||
<code>.number_of_values(3)</code>, and this argument wouldn't be satisfied unless the user provided
|
||
3 and only 3 values.</p>
|
||
|
||
<p><strong>NOTE:</strong> Does <em>not</em> require <code>.multiple(true)</code> to be set. Setting <code>.multiple(true)</code> would
|
||
allow <code>-f <file> <file> <file> -f <file> <file> <file></code> where as <em>not</em> setting
|
||
<code>.multiple(true)</code> would only allow one occurrence of this argument.</p>
|
||
|
||
<h1 id='examples-25' class='section-header'><a href='#examples-25'>Examples</a></h1>
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"file"</span>)
|
||
.<span class='ident'>short</span>(<span class='string'>"f"</span>)
|
||
.<span class='ident'>number_of_values</span>(<span class='number'>3</span>)</pre>
|
||
|
||
<p>Not supplying the correct number of values is an error</p>
|
||
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>let</span> <span class='ident'>res</span> <span class='op'>=</span> <span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"numvals"</span>)
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"file"</span>)
|
||
.<span class='ident'>takes_value</span>(<span class='boolval'>true</span>)
|
||
.<span class='ident'>number_of_values</span>(<span class='number'>2</span>)
|
||
.<span class='ident'>short</span>(<span class='string'>"F"</span>))
|
||
.<span class='ident'>get_matches_from_safe</span>(<span class='macro'>vec</span><span class='macro'>!</span>[<span class='string'>"mults"</span>, <span class='string'>"-F"</span>, <span class='string'>"file1"</span>]);
|
||
|
||
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>res</span>.<span class='ident'>is_err</span>());
|
||
<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>res</span>.<span class='ident'>unwrap_err</span>().<span class='ident'>kind</span>, <span class='ident'>ErrorKind</span>::<span class='ident'>WrongNumberOfValues</span>);</pre>
|
||
</div><h4 id='method.validator' class='method'><code>fn <a href='#method.validator' class='fnname'>validator</a><F>(self, f: F) -> Self <span class='where'>where F: <a class='trait' href='https://doc.rust-lang.org/nightly/core/ops/trait.Fn.html' title='core::ops::Fn'>Fn</a>(<a class='struct' href='https://doc.rust-lang.org/nightly/collections/string/struct.String.html' title='collections::string::String'>String</a>) -> <a class='enum' href='https://doc.rust-lang.org/nightly/core/result/enum.Result.html' title='core::result::Result'>Result</a><<a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.tuple.html'>()</a>, <a class='struct' href='https://doc.rust-lang.org/nightly/collections/string/struct.String.html' title='collections::string::String'>String</a>> + 'static</span></code></h4>
|
||
<div class='docblock'><p>Allows one to perform a custom validation on the argument value. You provide a closure which
|
||
accepts a <code>String</code> value, a <code>Result</code> where the <code>Err(String)</code> is a message displayed to the
|
||
user.</p>
|
||
|
||
<p><strong>NOTE:</strong> The error message does <em>not</em> need to contain the <code>error:</code> portion, only the
|
||
message.</p>
|
||
|
||
<p><strong>NOTE:</strong> There is a small performance hit for using validators, as they are implemented
|
||
with <code>Rc</code> pointers. And the value to be checked will be allocated an extra time in order to
|
||
to be passed to the closure. This performance hit is extremely minimal in the grand scheme
|
||
of things.</p>
|
||
|
||
<h1 id='examples-26' class='section-header'><a href='#examples-26'>Examples</a></h1>
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>fn</span> <span class='ident'>has_at</span>(<span class='ident'>v</span>: <span class='ident'>String</span>) <span class='op'>-></span> <span class='prelude-ty'>Result</span><span class='op'><</span>(), <span class='ident'>String</span><span class='op'>></span> {
|
||
<span class='kw'>if</span> <span class='ident'>v</span>.<span class='ident'>contains</span>(<span class='string'>"@"</span>) { <span class='kw'>return</span> <span class='prelude-val'>Ok</span>(()); }
|
||
<span class='prelude-val'>Err</span>(<span class='ident'>String</span>::<span class='ident'>from</span>(<span class='string'>"The value did not contain the required @ sigil"</span>))
|
||
}
|
||
<span class='kw'>let</span> <span class='ident'>res</span> <span class='op'>=</span> <span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"validators"</span>)
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"file"</span>)
|
||
.<span class='ident'>index</span>(<span class='number'>1</span>)
|
||
.<span class='ident'>validator</span>(<span class='ident'>has_at</span>))
|
||
.<span class='ident'>get_matches_from_safe</span>(<span class='macro'>vec</span><span class='macro'>!</span>[
|
||
<span class='string'>"validators"</span>, <span class='string'>"some@file"</span>
|
||
]);
|
||
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>res</span>.<span class='ident'>is_ok</span>());
|
||
<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>res</span>.<span class='ident'>unwrap</span>().<span class='ident'>value_of</span>(<span class='string'>"file"</span>), <span class='prelude-val'>Some</span>(<span class='string'>"some@file"</span>));</pre>
|
||
</div><h4 id='method.max_values' class='method'><code>fn <a href='#method.max_values' class='fnname'>max_values</a>(self, qty: <a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.u64.html'>u64</a>) -> Self</code></h4>
|
||
<div class='docblock'><p>Specifies the <em>maximum</em> number of values are for this argument. For example, if you had a
|
||
<code>-f <file></code> argument where you wanted up to 3 'files' you would set
|
||
<code>.max_values(3)</code>, and this argument would be satisfied if the user provided, 1, 2, or 3
|
||
values.</p>
|
||
|
||
<p><strong>NOTE:</strong> This does not implicitly set <code>mulitple(true)</code>. This is because <code>-o val -o val</code> is
|
||
multiples occurrences but a single value and <code>-o val1 val2</code> is a single occurence with
|
||
multple values. For positional arguments this <strong>does</strong> set <code>multiple(true)</code> because there
|
||
is no way to determine the diffrence between multiple occureces and multiple values.</p>
|
||
|
||
<h1 id='examples-27' class='section-header'><a href='#examples-27'>Examples</a></h1>
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"file"</span>)
|
||
.<span class='ident'>short</span>(<span class='string'>"f"</span>)
|
||
.<span class='ident'>max_values</span>(<span class='number'>3</span>)</pre>
|
||
|
||
<p>Supplying less than the maximum number of values is allowed</p>
|
||
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>let</span> <span class='ident'>res</span> <span class='op'>=</span> <span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"numvals"</span>)
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"file"</span>)
|
||
.<span class='ident'>takes_value</span>(<span class='boolval'>true</span>)
|
||
.<span class='ident'>max_values</span>(<span class='number'>3</span>)
|
||
.<span class='ident'>short</span>(<span class='string'>"F"</span>))
|
||
.<span class='ident'>get_matches_from_safe</span>(<span class='macro'>vec</span><span class='macro'>!</span>[<span class='string'>"mults"</span>, <span class='string'>"-F"</span>, <span class='string'>"file1"</span>, <span class='string'>"file2"</span>]);
|
||
|
||
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>res</span>.<span class='ident'>is_ok</span>());
|
||
<span class='kw'>let</span> <span class='ident'>m</span> <span class='op'>=</span> <span class='ident'>res</span>.<span class='ident'>unwrap</span>();
|
||
<span class='kw'>let</span> <span class='ident'>files</span>: <span class='ident'>Vec</span><span class='op'><</span>_<span class='op'>></span> <span class='op'>=</span> <span class='ident'>m</span>.<span class='ident'>values_of</span>(<span class='string'>"file"</span>).<span class='ident'>unwrap</span>().<span class='ident'>collect</span>();
|
||
<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>files</span>, [<span class='string'>"file1"</span>, <span class='string'>"file2"</span>]);</pre>
|
||
|
||
<p>Supplying more than the maximum number of values is an error</p>
|
||
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>let</span> <span class='ident'>res</span> <span class='op'>=</span> <span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"numvals"</span>)
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"file"</span>)
|
||
.<span class='ident'>takes_value</span>(<span class='boolval'>true</span>)
|
||
.<span class='ident'>max_values</span>(<span class='number'>2</span>)
|
||
.<span class='ident'>short</span>(<span class='string'>"F"</span>))
|
||
.<span class='ident'>get_matches_from_safe</span>(<span class='macro'>vec</span><span class='macro'>!</span>[<span class='string'>"mults"</span>, <span class='string'>"-F"</span>, <span class='string'>"file1"</span>, <span class='string'>"file2"</span>, <span class='string'>"file3"</span>]);
|
||
|
||
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>res</span>.<span class='ident'>is_err</span>());
|
||
<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>res</span>.<span class='ident'>unwrap_err</span>().<span class='ident'>kind</span>, <span class='ident'>ErrorKind</span>::<span class='ident'>TooManyValues</span>);</pre>
|
||
</div><h4 id='method.min_values' class='method'><code>fn <a href='#method.min_values' class='fnname'>min_values</a>(self, qty: <a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.u64.html'>u64</a>) -> Self</code></h4>
|
||
<div class='docblock'><p>Specifies the <em>minimum</em> number of values are for this argument. For example, if you had a
|
||
<code>-f <file></code> argument where you wanted at least 2 'files' you would set
|
||
<code>.min_values(2)</code>, and this argument would be satisfied if the user provided, 2 or more
|
||
values.</p>
|
||
|
||
<p><strong>NOTE:</strong> This does not implicitly set <code>mulitple(true)</code>. This is because <code>-o val -o val</code> is
|
||
multiples occurrences but a single value and <code>-o val1 val2</code> is a single occurence with
|
||
multple values. For positional arguments this <strong>does</strong> set <code>multiple(true)</code> because there
|
||
is no way to determine the diffrence between multiple occureces and multiple values.</p>
|
||
|
||
<h1 id='examples-28' class='section-header'><a href='#examples-28'>Examples</a></h1>
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"file"</span>)
|
||
.<span class='ident'>short</span>(<span class='string'>"f"</span>)
|
||
.<span class='ident'>min_values</span>(<span class='number'>3</span>)</pre>
|
||
|
||
<p>Supplying more than the minimum number of values is allowed</p>
|
||
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>let</span> <span class='ident'>res</span> <span class='op'>=</span> <span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"numvals"</span>)
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"file"</span>)
|
||
.<span class='ident'>takes_value</span>(<span class='boolval'>true</span>)
|
||
.<span class='ident'>min_values</span>(<span class='number'>2</span>)
|
||
.<span class='ident'>short</span>(<span class='string'>"F"</span>))
|
||
.<span class='ident'>get_matches_from_safe</span>(<span class='macro'>vec</span><span class='macro'>!</span>[<span class='string'>"mults"</span>, <span class='string'>"-F"</span>, <span class='string'>"file1"</span>, <span class='string'>"file2"</span>, <span class='string'>"file3"</span>]);
|
||
|
||
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>res</span>.<span class='ident'>is_ok</span>());
|
||
<span class='kw'>let</span> <span class='ident'>m</span> <span class='op'>=</span> <span class='ident'>res</span>.<span class='ident'>unwrap</span>();
|
||
<span class='kw'>let</span> <span class='ident'>files</span>: <span class='ident'>Vec</span><span class='op'><</span>_<span class='op'>></span> <span class='op'>=</span> <span class='ident'>m</span>.<span class='ident'>values_of</span>(<span class='string'>"file"</span>).<span class='ident'>unwrap</span>().<span class='ident'>collect</span>();
|
||
<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>files</span>, [<span class='string'>"file1"</span>, <span class='string'>"file2"</span>, <span class='string'>"file3"</span>]);</pre>
|
||
|
||
<p>Supplying less than the mainimum number of values is an error</p>
|
||
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>let</span> <span class='ident'>res</span> <span class='op'>=</span> <span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"numvals"</span>)
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"file"</span>)
|
||
.<span class='ident'>takes_value</span>(<span class='boolval'>true</span>)
|
||
.<span class='ident'>min_values</span>(<span class='number'>2</span>)
|
||
.<span class='ident'>short</span>(<span class='string'>"F"</span>))
|
||
.<span class='ident'>get_matches_from_safe</span>(<span class='macro'>vec</span><span class='macro'>!</span>[<span class='string'>"mults"</span>, <span class='string'>"-F"</span>, <span class='string'>"file1"</span>]);
|
||
|
||
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>res</span>.<span class='ident'>is_err</span>());
|
||
<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>res</span>.<span class='ident'>unwrap_err</span>().<span class='ident'>kind</span>, <span class='ident'>ErrorKind</span>::<span class='ident'>TooFewValues</span>);</pre>
|
||
</div><h4 id='method.use_delimiter' class='method'><code>fn <a href='#method.use_delimiter' class='fnname'>use_delimiter</a>(self, d: <a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.bool.html'>bool</a>) -> Self</code></h4>
|
||
<div class='docblock'><p>Specifies whether or not an arugment should allow grouping of multiple values via a
|
||
delimter. I.e. shoulde <code>--option=val1,val2,val3</code> be parsed as three values (<code>val1</code>, <code>val2</code>,
|
||
and <code>val3</code>) or as a single value (<code>val1,val2,val3</code>). Defaults to using <code>,</code> (comma) as the
|
||
value delimiter for all arguments that accept values (options and positional arguments)</p>
|
||
|
||
<p><strong>NOTE:</strong> The defalt is <code>true</code>. Setting the value to <code>true</code> will reset any previous use of
|
||
<code>Arg::value_delimiter</code> back to the default of <code>,</code> (comma).</p>
|
||
|
||
<h1 id='examples-29' class='section-header'><a href='#examples-29'>Examples</a></h1>
|
||
<p>The following example shows the default behavior.</p>
|
||
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>let</span> <span class='ident'>delims</span> <span class='op'>=</span> <span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"delims"</span>)
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"option"</span>)
|
||
.<span class='ident'>long</span>(<span class='string'>"option"</span>)
|
||
.<span class='ident'>takes_value</span>(<span class='boolval'>true</span>))
|
||
.<span class='ident'>get_matches_from</span>(<span class='macro'>vec</span><span class='macro'>!</span>[
|
||
<span class='string'>"delims"</span>,
|
||
<span class='string'>"--option=val1,val2,val3"</span>,
|
||
]);
|
||
|
||
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>delims</span>.<span class='ident'>is_present</span>(<span class='string'>"option"</span>));
|
||
<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>delims</span>.<span class='ident'>occurrences_of</span>(<span class='string'>"option"</span>), <span class='number'>1</span>);
|
||
<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>delims</span>.<span class='ident'>values_of</span>(<span class='string'>"option"</span>).<span class='ident'>unwrap</span>().<span class='ident'>collect</span>::<span class='op'><</span><span class='ident'>Vec</span><span class='op'><</span>_<span class='op'>>></span>(), [<span class='string'>"val1"</span>, <span class='string'>"val2"</span>, <span class='string'>"val3"</span>]);</pre>
|
||
|
||
<p>The next example shows the difference when turning delimiters off.</p>
|
||
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>let</span> <span class='ident'>nodelims</span> <span class='op'>=</span> <span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"nodelims"</span>)
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"option"</span>)
|
||
.<span class='ident'>long</span>(<span class='string'>"option"</span>)
|
||
.<span class='ident'>use_delimiter</span>(<span class='boolval'>false</span>)
|
||
.<span class='ident'>takes_value</span>(<span class='boolval'>true</span>))
|
||
.<span class='ident'>get_matches_from</span>(<span class='macro'>vec</span><span class='macro'>!</span>[
|
||
<span class='string'>"nodelims"</span>,
|
||
<span class='string'>"--option=val1,val2,val3"</span>,
|
||
]);
|
||
|
||
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>nodelims</span>.<span class='ident'>is_present</span>(<span class='string'>"option"</span>));
|
||
<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>nodelims</span>.<span class='ident'>occurrences_of</span>(<span class='string'>"option"</span>), <span class='number'>1</span>);
|
||
<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>nodelims</span>.<span class='ident'>value_of</span>(<span class='string'>"option"</span>).<span class='ident'>unwrap</span>(), <span class='string'>"val1,val2,val3"</span>);</pre>
|
||
</div><h4 id='method.value_delimiter' class='method'><code>fn <a href='#method.value_delimiter' class='fnname'>value_delimiter</a>(self, d: &<a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.str.html'>str</a>) -> Self</code></h4>
|
||
<div class='docblock'><p>Specifies the separator to use when values are clumped together, defaults to <code>,</code> (comma).</p>
|
||
|
||
<p><strong>NOTE:</strong> implicitly sets <code>Arg::use_delimiter(true)</code></p>
|
||
|
||
<p><strong>NOTE:</strong> implicitly sets <code>Arg::takes_value(true)</code></p>
|
||
|
||
<h1 id='examples-30' class='section-header'><a href='#examples-30'>Examples</a></h1>
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>let</span> <span class='ident'>app</span> <span class='op'>=</span> <span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"fake"</span>)
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"config"</span>)
|
||
.<span class='ident'>short</span>(<span class='string'>"c"</span>)
|
||
.<span class='ident'>long</span>(<span class='string'>"config"</span>)
|
||
.<span class='ident'>value_delimiter</span>(<span class='string'>";"</span>));
|
||
|
||
<span class='kw'>let</span> <span class='ident'>m</span> <span class='op'>=</span> <span class='ident'>app</span>.<span class='ident'>get_matches_from</span>(<span class='macro'>vec</span><span class='macro'>!</span>[
|
||
<span class='string'>"fake"</span>, <span class='string'>"--config=val1;val2;val3"</span>
|
||
]);
|
||
|
||
<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>m</span>.<span class='ident'>values_of</span>(<span class='string'>"config"</span>).<span class='ident'>unwrap</span>().<span class='ident'>collect</span>::<span class='op'><</span><span class='ident'>Vec</span><span class='op'><</span>_<span class='op'>>></span>(), [<span class='string'>"val1"</span>, <span class='string'>"val2"</span>, <span class='string'>"val3"</span>])</pre>
|
||
</div><h4 id='method.value_names' class='method'><code>fn <a href='#method.value_names' class='fnname'>value_names</a>(self, names: <a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.slice.html'>&[</a>&'b <a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.str.html'>str</a><a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.slice.html'>]</a>) -> Self</code></h4>
|
||
<div class='docblock'><p>Specify multiple names for values of option arguments. These names are cosmetic only, used
|
||
for help and usage strings only. The names are <strong>not</strong> used to access arguments. The values
|
||
of the arguments are accessed in numeric order (i.e. if you specify two names <code>one</code> and
|
||
<code>two</code> <code>one</code> will be the first matched value, <code>two</code> will be the second).</p>
|
||
|
||
<p>This setting can be very helpful when describing the type of input the user should be
|
||
using, such as <code>FILE</code>, <code>INTERFACE</code>, etc. Although not required, it's somewhat convention to
|
||
use all capital letters for the value name.</p>
|
||
|
||
<p><strong>Pro Tip:</strong> It may help to use <code>Arg::next_line_help(true)</code> if there are long, or multiple
|
||
value names in order to not throw off the help text alignment of all options.</p>
|
||
|
||
<p><strong>NOTE:</strong> This implicitly sets <code>.number_of_values()</code> if the number of value names is
|
||
greater than one. I.e. be aware that the number of "names" you set for the values, will be
|
||
the <em>exact</em> number of values required to satisfy this argument</p>
|
||
|
||
<p><strong>NOTE:</strong> implicitly sets <code>Arg::takes_value(true)</code></p>
|
||
|
||
<p><strong>NOTE:</strong> Does <em>not</em> require or imply <code>.multiple(true)</code>.</p>
|
||
|
||
<h1 id='examples-31' class='section-header'><a href='#examples-31'>Examples</a></h1>
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"speed"</span>)
|
||
.<span class='ident'>short</span>(<span class='string'>"s"</span>)
|
||
.<span class='ident'>value_names</span>(<span class='kw-2'>&</span>[<span class='string'>"fast"</span>, <span class='string'>"slow"</span>])</pre>
|
||
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>let</span> <span class='ident'>app</span> <span class='op'>=</span> <span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"valnames"</span>)
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"io"</span>)
|
||
.<span class='ident'>long</span>(<span class='string'>"io-files"</span>)
|
||
.<span class='ident'>value_names</span>(<span class='kw-2'>&</span>[<span class='string'>"INFILE"</span>, <span class='string'>"OUTFILE"</span>]))
|
||
.<span class='ident'>get_matches_from</span>(<span class='macro'>vec</span><span class='macro'>!</span>[
|
||
<span class='string'>"valnames"</span>, <span class='string'>"--help"</span>
|
||
]);</pre>
|
||
|
||
<p>Running the above program produces the following output</p>
|
||
|
||
<pre><code class="language-notrust">valnames
|
||
|
||
USAGE:
|
||
valnames [FLAGS] [OPTIONS]
|
||
|
||
FLAGS:
|
||
-h, --help Prints help information
|
||
-V, --version Prints version information
|
||
|
||
OPTIONS:
|
||
--io-files <INFILE> <OUTFILE> Some help text
|
||
</code></pre>
|
||
</div><h4 id='method.value_name' class='method'><code>fn <a href='#method.value_name' class='fnname'>value_name</a>(self, name: &'b <a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.str.html'>str</a>) -> Self</code></h4>
|
||
<div class='docblock'><p>Specifies the name for value of option or positional arguments inside of help documenation.
|
||
This name is cosmetic only, the name is <strong>not</strong> used to access arguments. This setting can
|
||
be very helpful when describing the type of input the user should be using, such as <code>FILE</code>,
|
||
<code>INTERFACE</code>, etc. Although not required, it's somewhat convention to use all capital
|
||
letters for the value name.</p>
|
||
|
||
<p><strong>NOTE:</strong> implicitly sets <code>Arg::takes_value(true)</code></p>
|
||
|
||
<h1 id='examples-32' class='section-header'><a href='#examples-32'>Examples</a></h1>
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"cfg"</span>)
|
||
.<span class='ident'>long</span>(<span class='string'>"config"</span>)
|
||
.<span class='ident'>value_name</span>(<span class='string'>"FILE"</span>)</pre>
|
||
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>let</span> <span class='ident'>app</span> <span class='op'>=</span> <span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"valnames"</span>)
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"config"</span>)
|
||
.<span class='ident'>long</span>(<span class='string'>"config"</span>)
|
||
.<span class='ident'>value_name</span>(<span class='string'>"FILE"</span>))
|
||
.<span class='ident'>get_matches_from</span>(<span class='macro'>vec</span><span class='macro'>!</span>[
|
||
<span class='string'>"valnames"</span>, <span class='string'>"--help"</span>
|
||
]);</pre>
|
||
|
||
<p>Running the above program produces the following output</p>
|
||
|
||
<pre><code class="language-notrust">valnames
|
||
|
||
USAGE:
|
||
valnames [FLAGS] [OPTIONS]
|
||
|
||
FLAGS:
|
||
-h, --help Prints help information
|
||
-V, --version Prints version information
|
||
|
||
OPTIONS:
|
||
--config <FILE> Some help text
|
||
</code></pre>
|
||
</div><h4 id='method.default_value' class='method'><code>fn <a href='#method.default_value' class='fnname'>default_value</a>(self, val: &'a <a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.str.html'>str</a>) -> Self</code></h4>
|
||
<div class='docblock'><p>Specifies the value of the argument when <em>not</em> specified at runtime.</p>
|
||
|
||
<p><strong>NOTE:</strong> If the user <em>does not</em> use this argument at runtime, <code>ArgMatches::occurrences_of</code>
|
||
will return <code>0</code> even though the <code>value_of</code> will return the default specified.</p>
|
||
|
||
<p><strong>NOTE:</strong> If the user <em>does not</em> use this argument at runtime <code>ArgMatches::is_present</code> will
|
||
still return <code>true</code>. If you wish to determine whether the argument was used at runtime or
|
||
not, consider <code>ArgMatches::occurrences_of</code> which will return <code>0</code> if the argument was <em>not</em>
|
||
used at runtmie.</p>
|
||
|
||
<p><strong>NOTE:</strong> This implicitly sets <code>Arg::takes_value(true)</code>.</p>
|
||
|
||
<h1 id='examples-33' class='section-header'><a href='#examples-33'>Examples</a></h1>
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>let</span> <span class='ident'>m</span> <span class='op'>=</span> <span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"defvals"</span>)
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"opt"</span>)
|
||
.<span class='ident'>long</span>(<span class='string'>"myopt"</span>)
|
||
.<span class='ident'>default_value</span>(<span class='string'>"myval"</span>))
|
||
.<span class='ident'>get_matches_from</span>(<span class='macro'>vec</span><span class='macro'>!</span>[
|
||
<span class='string'>"defvals"</span>
|
||
]);
|
||
|
||
<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>m</span>.<span class='ident'>value_of</span>(<span class='string'>"opt"</span>), <span class='prelude-val'>Some</span>(<span class='string'>"myval"</span>));
|
||
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>m</span>.<span class='ident'>is_present</span>(<span class='string'>"opt"</span>));
|
||
<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>m</span>.<span class='ident'>occurrences_of</span>(<span class='string'>"opt"</span>), <span class='number'>0</span>);</pre>
|
||
</div><h4 id='method.next_line_help' class='method'><code>fn <a href='#method.next_line_help' class='fnname'>next_line_help</a>(self, nlh: <a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.bool.html'>bool</a>) -> Self</code></h4>
|
||
<div class='docblock'><p>When set to <code>true</code> the help string will be displayed on the line after the argument and
|
||
indented once. This can be helpful for arguments with very long or complex help messages.
|
||
This can also be helpful for arguments with very long flag names, or many/long value names.</p>
|
||
|
||
<p><strong>NOTE:</strong> To apply this setting to all arguments consider using <code>AppSettings::NextLineHelp</code></p>
|
||
|
||
<h1 id='examples-34' class='section-header'><a href='#examples-34'>Examples</a></h1>
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>let</span> <span class='ident'>m</span> <span class='op'>=</span> <span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"nlh"</span>)
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"opt"</span>)
|
||
.<span class='ident'>long</span>(<span class='string'>"long-option-flag"</span>)
|
||
.<span class='ident'>short</span>(<span class='string'>"o"</span>)
|
||
.<span class='ident'>takes_value</span>(<span class='boolval'>true</span>)
|
||
.<span class='ident'>value_names</span>(<span class='kw-2'>&</span>[<span class='string'>"value1"</span>, <span class='string'>"value2"</span>])
|
||
.<span class='ident'>help</span>(<span class='string'>"Some really long help and complex{n}\
|
||
help that makes more sense to be{n}\
|
||
on a line after the option"</span>)
|
||
.<span class='ident'>next_line_help</span>(<span class='boolval'>true</span>))
|
||
.<span class='ident'>get_matches_from</span>(<span class='macro'>vec</span><span class='macro'>!</span>[
|
||
<span class='string'>"nlh"</span>, <span class='string'>"--help"</span>
|
||
]);</pre>
|
||
|
||
<p>The above example displays the following help message</p>
|
||
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='ident'>nlh</span>
|
||
|
||
<span class='ident'>USAGE</span>:
|
||
<span class='ident'>nlh</span> [<span class='ident'>FLAGS</span>] [<span class='ident'>OPTIONS</span>]
|
||
|
||
<span class='ident'>FLAGS</span>:
|
||
<span class='op'>-</span><span class='ident'>h</span>, <span class='op'>-</span><span class='op'>-</span><span class='ident'>help</span> <span class='ident'>Prints</span> <span class='ident'>help</span> <span class='ident'>information</span>
|
||
<span class='op'>-</span><span class='ident'>V</span>, <span class='op'>-</span><span class='op'>-</span><span class='ident'>version</span> <span class='ident'>Prints</span> <span class='ident'>version</span> <span class='ident'>information</span>
|
||
|
||
<span class='ident'>OPTIONS</span>:
|
||
<span class='op'>-</span><span class='ident'>o</span>, <span class='op'>-</span><span class='op'>-</span><span class='ident'>long</span><span class='op'>-</span><span class='ident'>option</span><span class='op'>-</span><span class='ident'>flag</span> <span class='op'><</span><span class='ident'>value1</span><span class='op'>></span> <span class='op'><</span><span class='ident'>value2</span><span class='op'>></span>
|
||
<span class='prelude-val'>Some</span> <span class='ident'>really</span> <span class='ident'>long</span> <span class='ident'>help</span> <span class='ident'>and</span> <span class='ident'>complex</span>
|
||
<span class='ident'>help</span> <span class='ident'>that</span> <span class='ident'>makes</span> <span class='ident'>more</span> <span class='ident'>sense</span> <span class='ident'>to</span> <span class='ident'>be</span>
|
||
<span class='ident'>on</span> <span class='ident'>a</span> <span class='ident'>line</span> <span class='ident'>after</span> <span class='ident'>the</span> <span class='ident'>option</span></pre>
|
||
</div><h4 id='method.display_order' class='method'><code>fn <a href='#method.display_order' class='fnname'>display_order</a>(self, ord: <a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.usize.html'>usize</a>) -> Self</code></h4>
|
||
<div class='docblock'><p>Allows custom ordering of args within the help message. Args with a lower value will be
|
||
displayed first in the help message. This is helpful when one would like to emphasise
|
||
frequently used args, or prioritize those towards the top of the list. Duplicate values
|
||
<strong>are</strong> allowed. Args with duplicate display orders will be displayed in alphabetical
|
||
order.</p>
|
||
|
||
<p><strong>NOTE:</strong> The default is 999 for all arguments.</p>
|
||
|
||
<p><strong>NOTE:</strong> This setting is ignored for positional arguments which are always displayed in
|
||
index order.</p>
|
||
|
||
<h1 id='examples-35' class='section-header'><a href='#examples-35'>Examples</a></h1>
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>let</span> <span class='ident'>m</span> <span class='op'>=</span> <span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"cust-ord"</span>)
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"a"</span>) <span class='comment'>// Typically args are grouped alphabetically by name.</span>
|
||
<span class='comment'>// Args without a display_order have a value of 999 and are</span>
|
||
<span class='comment'>// displayed alphabetically with all other 999 valued args.</span>
|
||
.<span class='ident'>long</span>(<span class='string'>"long-option"</span>)
|
||
.<span class='ident'>short</span>(<span class='string'>"o"</span>)
|
||
.<span class='ident'>takes_value</span>(<span class='boolval'>true</span>)
|
||
.<span class='ident'>help</span>(<span class='string'>"Some help and text"</span>))
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"b"</span>)
|
||
.<span class='ident'>long</span>(<span class='string'>"other-option"</span>)
|
||
.<span class='ident'>short</span>(<span class='string'>"O"</span>)
|
||
.<span class='ident'>takes_value</span>(<span class='boolval'>true</span>)
|
||
.<span class='ident'>display_order</span>(<span class='number'>1</span>) <span class='comment'>// In order to force this arg to appear *first*</span>
|
||
<span class='comment'>// all we have to do is give it a value lower than 999.</span>
|
||
<span class='comment'>// Any other args with a value of 1 will be displayed</span>
|
||
<span class='comment'>// alphabetically with this one...then 2 values, then 3, etc.</span>
|
||
.<span class='ident'>help</span>(<span class='string'>"I should be first!"</span>))
|
||
.<span class='ident'>get_matches_from</span>(<span class='macro'>vec</span><span class='macro'>!</span>[
|
||
<span class='string'>"cust-ord"</span>, <span class='string'>"--help"</span>
|
||
]);</pre>
|
||
|
||
<p>The above example displays the following help message</p>
|
||
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='ident'>cust</span><span class='op'>-</span><span class='ident'>ord</span>
|
||
|
||
<span class='ident'>USAGE</span>:
|
||
<span class='ident'>cust</span><span class='op'>-</span><span class='ident'>ord</span> [<span class='ident'>FLAGS</span>] [<span class='ident'>OPTIONS</span>]
|
||
|
||
<span class='ident'>FLAGS</span>:
|
||
<span class='op'>-</span><span class='ident'>h</span>, <span class='op'>-</span><span class='op'>-</span><span class='ident'>help</span> <span class='ident'>Prints</span> <span class='ident'>help</span> <span class='ident'>information</span>
|
||
<span class='op'>-</span><span class='ident'>V</span>, <span class='op'>-</span><span class='op'>-</span><span class='ident'>version</span> <span class='ident'>Prints</span> <span class='ident'>version</span> <span class='ident'>information</span>
|
||
|
||
<span class='ident'>OPTIONS</span>:
|
||
<span class='op'>-</span><span class='ident'>O</span>, <span class='op'>-</span><span class='op'>-</span><span class='ident'>other</span><span class='op'>-</span><span class='ident'>option</span> <span class='op'><</span><span class='ident'>b</span><span class='op'>></span> <span class='ident'>I</span> <span class='ident'>should</span> <span class='ident'>be</span> <span class='macro'>first</span><span class='macro'>!</span>
|
||
<span class='op'>-</span><span class='ident'>o</span>, <span class='op'>-</span><span class='op'>-</span><span class='ident'>long</span><span class='op'>-</span><span class='ident'>option</span> <span class='op'><</span><span class='ident'>a</span><span class='op'>></span> <span class='prelude-val'>Some</span> <span class='ident'>help</span> <span class='ident'>and</span> <span class='ident'>text</span></pre>
|
||
</div><h4 id='method.is_set' class='method'><code>fn <a href='#method.is_set' class='fnname'>is_set</a>(&self, s: ArgSettings) -> <a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.bool.html'>bool</a></code></h4>
|
||
<div class='docblock'><p>Checks if one of the <code>ArgSettings</code> settings is set for the argument</p>
|
||
</div><h4 id='method.set' class='method'><code>fn <a href='#method.set' class='fnname'>set</a>(self, s: ArgSettings) -> Self</code></h4>
|
||
<div class='docblock'><p>Sets one of the <code>ArgSettings</code> settings for the argument</p>
|
||
</div><h4 id='method.unset' class='method'><code>fn <a href='#method.unset' class='fnname'>unset</a>(self, s: ArgSettings) -> Self</code></h4>
|
||
<div class='docblock'><p>Unsets one of the <code>ArgSettings</code> settings for the argument</p>
|
||
</div></div><h2 id='implementations'>Trait Implementations</h2><h3 class='impl'><code>impl<'a, 'b> <a class='trait' href='https://doc.rust-lang.org/nightly/core/default/trait.Default.html' title='core::default::Default'>Default</a> for <a class='struct' href='../clap/struct.Arg.html' title='clap::Arg'>Arg</a><'a, 'b></code></h3><div class='impl-items'><h4 id='method.default' class='method'><code>fn <a href='https://doc.rust-lang.org/nightly/core/default/trait.Default.html#tymethod.default' class='fnname'>default</a>() -> Self</code></h4>
|
||
</div><h3 class='impl'><code>impl<'a, 'b, 'z> <a class='trait' href='https://doc.rust-lang.org/nightly/core/convert/trait.From.html' title='core::convert::From'>From</a><&'z <a class='struct' href='../clap/struct.Arg.html' title='clap::Arg'>Arg</a><'a, 'b>> for <a class='struct' href='../clap/struct.Arg.html' title='clap::Arg'>Arg</a><'a, 'b></code></h3><div class='impl-items'><h4 id='method.from' class='method'><code>fn <a href='https://doc.rust-lang.org/nightly/core/convert/trait.From.html#tymethod.from' class='fnname'>from</a>(a: &'z <a class='struct' href='../clap/struct.Arg.html' title='clap::Arg'>Arg</a><'a, 'b>) -> Self</code></h4>
|
||
</div><h3 class='impl'><code>impl<'a, 'b> <a class='trait' href='https://doc.rust-lang.org/nightly/core/clone/trait.Clone.html' title='core::clone::Clone'>Clone</a> for <a class='struct' href='../clap/struct.Arg.html' title='clap::Arg'>Arg</a><'a, 'b></code></h3><div class='impl-items'><h4 id='method.clone' class='method'><code>fn <a href='https://doc.rust-lang.org/nightly/core/clone/trait.Clone.html#tymethod.clone' class='fnname'>clone</a>(&self) -> Self</code></h4>
|
||
<h4 id='method.clone_from' class='method'><code>fn <a href='https://doc.rust-lang.org/nightly/core/clone/trait.Clone.html#method.clone_from' class='fnname'>clone_from</a>(&mut self, source: &Self)</code><span class="since">1.0.0</span></h4>
|
||
</div></section>
|
||
<section id='search' class="content hidden"></section>
|
||
|
||
<section class="footer"></section>
|
||
|
||
<aside id="help" class="hidden">
|
||
<div>
|
||
<h1 class="hidden">Help</h1>
|
||
|
||
<div class="shortcuts">
|
||
<h2>Keyboard Shortcuts</h2>
|
||
|
||
<dl>
|
||
<dt>?</dt>
|
||
<dd>Show this help dialog</dd>
|
||
<dt>S</dt>
|
||
<dd>Focus the search field</dd>
|
||
<dt>⇤</dt>
|
||
<dd>Move up in search results</dd>
|
||
<dt>⇥</dt>
|
||
<dd>Move down in search results</dd>
|
||
<dt>⏎</dt>
|
||
<dd>Go to active search result</dd>
|
||
</dl>
|
||
</div>
|
||
|
||
<div class="infos">
|
||
<h2>Search Tricks</h2>
|
||
|
||
<p>
|
||
Prefix searches with a type followed by a colon (e.g.
|
||
<code>fn:</code>) to restrict the search to a given type.
|
||
</p>
|
||
|
||
<p>
|
||
Accepted types are: <code>fn</code>, <code>mod</code>,
|
||
<code>struct</code>, <code>enum</code>,
|
||
<code>trait</code>, <code>type</code>, <code>macro</code>,
|
||
and <code>const</code>.
|
||
</p>
|
||
|
||
<p>
|
||
Search functions by type signature (e.g.
|
||
<code>vec -> usize</code> or <code>* -> vec</code>)
|
||
</p>
|
||
</div>
|
||
</div>
|
||
</aside>
|
||
|
||
|
||
|
||
<script>
|
||
window.rootPath = "../";
|
||
window.currentCrate = "clap";
|
||
window.playgroundUrl = "";
|
||
</script>
|
||
<script src="../jquery.js"></script>
|
||
<script src="../main.js"></script>
|
||
|
||
<script defer src="../search-index.js"></script>
|
||
</body>
|
||
</html> |