mirror of
https://github.com/fluencelabs/wasmer
synced 2025-04-25 18:32:15 +00:00
2403 lines
306 KiB
HTML
2403 lines
306 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 `structopt`."><meta name="keywords" content="rust, rustlang, rust-lang, Arg"><title>structopt::clap::Arg - Rust</title><link rel="stylesheet" type="text/css" href="../../normalize.css"><link rel="stylesheet" type="text/css" href="../../rustdoc.css" id="mainThemeStyle"><link rel="stylesheet" type="text/css" href="../../dark.css"><link rel="stylesheet" type="text/css" href="../../light.css" id="themeStyle"><script src="../../storage.js"></script><noscript><link rel="stylesheet" href="../../noscript.css"></noscript><link rel="shortcut icon" href="../../favicon.ico"><style type="text/css">#crate-search{background-image:url("../../down-arrow.svg");}</style></head><body class="rustdoc struct"><!--[if lte IE 8]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><nav class="sidebar"><div class="sidebar-menu">☰</div><a href='../../structopt/index.html'><div class='logo-container'><img src='../../rust-logo.png' alt='logo'></div></a><p class='location'>Struct Arg</p><div class="sidebar-elems"><div class="block items"><a class="sidebar-title" href="#methods">Methods</a><div class="sidebar-links"><a href="#method.alias">alias</a><a href="#method.aliases">aliases</a><a href="#method.allow_hyphen_values">allow_hyphen_values</a><a href="#method.case_insensitive">case_insensitive</a><a href="#method.conflicts_with">conflicts_with</a><a href="#method.conflicts_with_all">conflicts_with_all</a><a href="#method.default_value">default_value</a><a href="#method.default_value_if">default_value_if</a><a href="#method.default_value_if_os">default_value_if_os</a><a href="#method.default_value_ifs">default_value_ifs</a><a href="#method.default_value_ifs_os">default_value_ifs_os</a><a href="#method.default_value_os">default_value_os</a><a href="#method.display_order">display_order</a><a href="#method.empty_values">empty_values</a><a href="#method.env">env</a><a href="#method.env_os">env_os</a><a href="#method.from_usage">from_usage</a><a href="#method.global">global</a><a href="#method.group">group</a><a href="#method.groups">groups</a><a href="#method.help">help</a><a href="#method.hidden">hidden</a><a href="#method.hidden_long_help">hidden_long_help</a><a href="#method.hidden_short_help">hidden_short_help</a><a href="#method.hide_default_value">hide_default_value</a><a href="#method.hide_env_values">hide_env_values</a><a href="#method.hide_possible_values">hide_possible_values</a><a href="#method.index">index</a><a href="#method.is_set">is_set</a><a href="#method.last">last</a><a href="#method.long">long</a><a href="#method.long_help">long_help</a><a href="#method.max_values">max_values</a><a href="#method.min_values">min_values</a><a href="#method.multiple">multiple</a><a href="#method.next_line_help">next_line_help</a><a href="#method.number_of_values">number_of_values</a><a href="#method.overrides_with">overrides_with</a><a href="#method.overrides_with_all">overrides_with_all</a><a href="#method.possible_value">possible_value</a><a href="#method.possible_values">possible_values</a><a href="#method.raw">raw</a><a href="#method.require_delimiter">require_delimiter</a><a href="#method.require_equals">require_equals</a><a href="#method.required">required</a><a href="#method.required_if">required_if</a><a href="#method.required_ifs">required_ifs</a><a href="#method.required_unless">required_unless</a><a href="#method.required_unless_all">required_unless_all</a><a href="#method.required_unless_one">required_unless_one</a><a href="#method.requires">requires</a><a href="#method.requires_all">requires_all</a><a href="#method.requires_if">requires_if</a><a href="#method.requires_ifs">requires_ifs</a><a href="#method.set">set</a><a href="#method.short">short</a><a href="#method.takes_value">takes_value</a><a href="#method.unset">unset</a><a href="#method.use_delimiter">use_delimiter</a><a href="#method.validator">validator</a><a href="#method.validator_os">validator_os</a><a href="#method.value_delimiter">value_delimiter</a><a href="#method.value_name">value_name</a><a href="#method.value_names">value_names</a><a href="#method.value_terminator">value_terminator</a><a href="#method.visible_alias">visible_alias</a><a href="#method.visible_aliases">visible_aliases</a><a href="#method.with_name">with_name</a></div><a class="sidebar-title" href="#implementations">Trait Implementations</a><div class="sidebar-links"><a href="#impl-Clone">Clone</a><a href="#impl-Default">Default</a><a href="#impl-From%3C%26%27z%20Arg%3C%27a%2C%20%27b%3E%3E">From<&'z Arg<'a, 'b>></a><a href="#impl-PartialEq%3CArg%3C%27n%2C%20%27e%3E%3E">PartialEq<Arg<'n, 'e>></a></div><a class="sidebar-title" href="#synthetic-implementations">Auto Trait Implementations</a><div class="sidebar-links"><a href="#impl-RefUnwindSafe">!RefUnwindSafe</a><a href="#impl-Send">!Send</a><a href="#impl-Sync">!Sync</a><a href="#impl-Unpin">Unpin</a><a href="#impl-UnwindSafe">!UnwindSafe</a></div><a class="sidebar-title" href="#blanket-implementations">Blanket Implementations</a><div class="sidebar-links"><a href="#impl-Any">Any</a><a href="#impl-Borrow%3CT%3E">Borrow<T></a><a href="#impl-BorrowMut%3CT%3E">BorrowMut<T></a><a href="#impl-From%3CT%3E">From<T></a><a href="#impl-Into%3CU%3E">Into<U></a><a href="#impl-ToOwned">ToOwned</a><a href="#impl-TryFrom%3CU%3E">TryFrom<U></a><a href="#impl-TryInto%3CU%3E">TryInto<U></a></div></div><p class='location'><a href='../index.html'>structopt</a>::<wbr><a href='index.html'>clap</a></p><script>window.sidebarCurrent = {name: 'Arg', ty: 'struct', relpath: ''};</script><script defer src="sidebar-items.js"></script></div></nav><div class="theme-picker"><button id="theme-picker" aria-label="Pick another theme!"><img src="../../brush.svg" width="18" alt="Pick another theme!"></button><div id="theme-choices"></div></div><script src="../../theme.js"></script><nav class="sub"><form class="search-form js-only"><div class="search-container"><div><select id="crate-search"><option value="All crates">All crates</option></select><input class="search-input" name="search" autocomplete="off" spellcheck="false" placeholder="Click or press ‘S’ to search, ‘?’ for more options…" type="search"></div><a id="settings-menu" href="../../settings.html"><img src="../../wheel.svg" width="18" alt="Change settings"></a></div></form></nav><section id="main" class="content"><h1 class='fqn'><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 class='srclink' href='../../src/clap/args/arg.rs.html#43-52' title='goto source code'>[src]</a></span><span class='in-band'>Struct <a href='../index.html'>structopt</a>::<wbr><a href='index.html'>clap</a>::<wbr><a class="struct" href=''>Arg</a></span></h1><div class="docblock type-decl hidden-by-usual-hider"><pre class='rust struct'>pub struct Arg<'a, 'b> <span class="where fmt-newline">where<br> 'a: 'b,<br> 'a: 'b, </span> { /* fields omitted */ }</pre></div><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 <a href="./struct.Arg.html"><code>Arg</code></a>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>
|
||
<div class="example-wrap"><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="bool-val">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>
|
||
</div><h2 id='methods' class='small-section-header'>Methods<a href='#methods' class='anchor'></a></h2><h3 id='impl' class='impl'><code class='in-band'>impl<'a, 'b> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a href='#impl' class='anchor'></a><a class='srclink' href='../../src/clap/args/arg.rs.html#54-3936' title='goto source code'>[src]</a></h3><div class='impl-items'><h4 id='method.with_name' class="method"><code id='with_name.v'>pub 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>) -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a class='srclink' href='../../src/clap/args/arg.rs.html#72-77' title='goto source code'>[src]</a></h4><div class='docblock'><p>Creates a new instance of <a href="./struct.Arg.html"><code>Arg</code></a> 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. <a href="./struct.Arg.html#method.takes_value"><code>Arg::takes_value(true)</code></a>)
|
||
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>
|
||
<div class="example-wrap"><pre class="rust rust-example-rendered">
|
||
<span class="ident">Arg</span>::<span class="ident">with_name</span>(<span class="string">"config"</span>)</pre></div>
|
||
</div><h4 id='method.from_usage' class="method"><code id='from_usage.v'>pub 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>) -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a class='srclink' href='../../src/clap/args/arg.rs.html#290-293' title='goto source code'>[src]</a></h4><div class='docblock'><p>Creates a new instance of <a href="./struct.Arg.html"><code>Arg</code></a> from a usage string. Allows creation of basic settings
|
||
for the <a href="./struct.Arg.html"><code>Arg</code></a>. 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 are officially supported in <a href="./struct.Arg.html#method.from_usage"><code>Arg::from_usage</code></a> strings. 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 argument will use one of the additional
|
||
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:</p>
|
||
<ul>
|
||
<li>The multiple denotation <code>...</code></li>
|
||
</ul>
|
||
<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</p>
|
||
<ul>
|
||
<li>The multiple denotation <code>...</code></li>
|
||
<li>An optional comma <code>,</code> which is cosmetic only</li>
|
||
<li>Value notation</li>
|
||
</ul>
|
||
<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</p>
|
||
<ul>
|
||
<li>The multiple denotation <code>...</code></li>
|
||
<li>Value notation</li>
|
||
</ul>
|
||
<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</p>
|
||
<ul>
|
||
<li>The multiple denotation <code>...</code></li>
|
||
<li>More Value notation</li>
|
||
</ul>
|
||
<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>
|
||
<div class="example-wrap"><pre class="rust rust-example-rendered">
|
||
<span class="ident">App</span>::<span class="ident">new</span>(<span class="string">"prog"</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>
|
||
</div><h4 id='method.short' class="method"><code id='short.v'>pub fn <a href='#method.short' class='fnname'>short</a><S>(self, s: S) -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b> <span class="where fmt-newline">where<br> S: <a class="trait" href="https://doc.rust-lang.org/nightly/core/convert/trait.AsRef.html" title="trait core::convert::AsRef">AsRef</a><<a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.str.html">str</a>>, </span></code><a class='srclink' href='../../src/clap/args/arg.rs.html#331-334' title='goto source code'>[src]</a></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 the auto-generated <code>version</code> and
|
||
<code>help</code> arguments respectively. You may use the uppercase <code>V</code> or lowercase <code>h</code> for your own
|
||
arguments, in which case <code>clap</code> simply will not assign those to the auto-generated
|
||
<code>version</code> or <code>help</code> arguments.</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 <a href="./struct.Arg.html#method.short"><code>short</code></a> version</p>
|
||
<h1 id="examples-3" class="section-header"><a href="#examples-3">Examples</a></h1>
|
||
<p>To set <a href="./struct.Arg.html#method.short"><code>short</code></a> use a single valid UTF-8 code point. If you supply a leading <code>-</code> such as
|
||
<code>-c</code>, the <code>-</code> will be stripped.</p>
|
||
|
||
<div class="example-wrap"><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></div>
|
||
<p>Setting <a href="./struct.Arg.html#method.short"><code>short</code></a> allows using the argument via a single hyphen (<code>-</code>) such as <code>-c</code></p>
|
||
|
||
<div class="example-wrap"><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">"prog"</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">"prog"</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>
|
||
</div><h4 id='method.long' class="method"><code id='long.v'>pub 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>) -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a class='srclink' href='../../src/clap/args/arg.rs.html#371-374' title='goto source code'>[src]</a></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 the auto-generated
|
||
<code>version</code> and <code>help</code> arguments respectively. You may use the word <code>version</code> or <code>help</code> for
|
||
the long form of your own arguments, in which case <code>clap</code> simply will not assign those to
|
||
the auto-generated <code>version</code> or <code>help</code> arguments.</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 double 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>
|
||
|
||
<div class="example-wrap"><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></div>
|
||
<p>Setting <code>long</code> allows using the argument via a double hyphen (<code>--</code>) such as <code>--config</code></p>
|
||
|
||
<div class="example-wrap"><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">"prog"</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">"prog"</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>
|
||
</div><h4 id='method.alias' class="method"><code id='alias.v'>pub fn <a href='#method.alias' class='fnname'>alias</a><S>(self, name: S) -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b> <span class="where fmt-newline">where<br> S: <a class="trait" href="https://doc.rust-lang.org/nightly/core/convert/trait.Into.html" title="trait core::convert::Into">Into</a><&'b <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.str.html">str</a>>, </span></code><a class='srclink' href='../../src/clap/args/arg.rs.html#397-404' title='goto source code'>[src]</a></h4><div class='docblock'><p>Allows adding a <a href="./struct.Arg.html"><code>Arg</code></a> alias, which function as "hidden" arguments that
|
||
automatically dispatch as if this argument was used. This is more efficient, and easier
|
||
than creating multiple hidden arguments as one only needs to check for the existence of
|
||
this command, and not all variants.</p>
|
||
<h1 id="examples-5" class="section-header"><a href="#examples-5">Examples</a></h1>
|
||
<div class="example-wrap"><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">"prog"</span>)
|
||
.<span class="ident">arg</span>(<span class="ident">Arg</span>::<span class="ident">with_name</span>(<span class="string">"test"</span>)
|
||
.<span class="ident">long</span>(<span class="string">"test"</span>)
|
||
.<span class="ident">alias</span>(<span class="string">"alias"</span>)
|
||
.<span class="ident">takes_value</span>(<span class="bool-val">true</span>))
|
||
.<span class="ident">get_matches_from</span>(<span class="macro">vec</span><span class="macro">!</span>[
|
||
<span class="string">"prog"</span>, <span class="string">"--alias"</span>, <span class="string">"cool"</span>
|
||
]);
|
||
<span class="macro">assert</span><span class="macro">!</span>(<span class="ident">m</span>.<span class="ident">is_present</span>(<span class="string">"test"</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">"test"</span>), <span class="prelude-val">Some</span>(<span class="string">"cool"</span>));</pre></div>
|
||
</div><h4 id='method.aliases' class="method"><code id='aliases.v'>pub fn <a href='#method.aliases' class='fnname'>aliases</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>) -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a class='srclink' href='../../src/clap/args/arg.rs.html#427-436' title='goto source code'>[src]</a></h4><div class='docblock'><p>Allows adding <a href="./struct.Arg.html"><code>Arg</code></a> aliases, which function as "hidden" arguments that
|
||
automatically dispatch as if this argument was used. This is more efficient, and easier
|
||
than creating multiple hidden subcommands as one only needs to check for the existence of
|
||
this command, and not all variants.</p>
|
||
<h1 id="examples-6" class="section-header"><a href="#examples-6">Examples</a></h1>
|
||
<div class="example-wrap"><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">"prog"</span>)
|
||
.<span class="ident">arg</span>(<span class="ident">Arg</span>::<span class="ident">with_name</span>(<span class="string">"test"</span>)
|
||
.<span class="ident">long</span>(<span class="string">"test"</span>)
|
||
.<span class="ident">aliases</span>(<span class="kw-2">&</span>[<span class="string">"do-stuff"</span>, <span class="string">"do-tests"</span>, <span class="string">"tests"</span>])
|
||
.<span class="ident">help</span>(<span class="string">"the file to add"</span>)
|
||
.<span class="ident">required</span>(<span class="bool-val">false</span>))
|
||
.<span class="ident">get_matches_from</span>(<span class="macro">vec</span><span class="macro">!</span>[
|
||
<span class="string">"prog"</span>, <span class="string">"--do-tests"</span>
|
||
]);
|
||
<span class="macro">assert</span><span class="macro">!</span>(<span class="ident">m</span>.<span class="ident">is_present</span>(<span class="string">"test"</span>));</pre></div>
|
||
</div><h4 id='method.visible_alias' class="method"><code id='visible_alias.v'>pub fn <a href='#method.visible_alias' class='fnname'>visible_alias</a><S>(self, name: S) -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b> <span class="where fmt-newline">where<br> S: <a class="trait" href="https://doc.rust-lang.org/nightly/core/convert/trait.Into.html" title="trait core::convert::Into">Into</a><&'b <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.str.html">str</a>>, </span></code><a class='srclink' href='../../src/clap/args/arg.rs.html#458-465' title='goto source code'>[src]</a></h4><div class='docblock'><p>Allows adding a <a href="./struct.Arg.html"><code>Arg</code></a> alias that functions exactly like those defined with
|
||
<a href="../../structopt/clap/struct.Arg.html#method.alias" title="`Arg::alias`"><code>Arg::alias</code></a>, except that they are visible inside the help message.</p>
|
||
<h1 id="examples-7" class="section-header"><a href="#examples-7">Examples</a></h1>
|
||
<div class="example-wrap"><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">"prog"</span>)
|
||
.<span class="ident">arg</span>(<span class="ident">Arg</span>::<span class="ident">with_name</span>(<span class="string">"test"</span>)
|
||
.<span class="ident">visible_alias</span>(<span class="string">"something-awesome"</span>)
|
||
.<span class="ident">long</span>(<span class="string">"test"</span>)
|
||
.<span class="ident">takes_value</span>(<span class="bool-val">true</span>))
|
||
.<span class="ident">get_matches_from</span>(<span class="macro">vec</span><span class="macro">!</span>[
|
||
<span class="string">"prog"</span>, <span class="string">"--something-awesome"</span>, <span class="string">"coffee"</span>
|
||
]);
|
||
<span class="macro">assert</span><span class="macro">!</span>(<span class="ident">m</span>.<span class="ident">is_present</span>(<span class="string">"test"</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">"test"</span>), <span class="prelude-val">Some</span>(<span class="string">"coffee"</span>));</pre></div>
|
||
</div><h4 id='method.visible_aliases' class="method"><code id='visible_aliases.v'>pub fn <a href='#method.visible_aliases' class='fnname'>visible_aliases</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>) -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a class='srclink' href='../../src/clap/args/arg.rs.html#485-494' title='goto source code'>[src]</a></h4><div class='docblock'><p>Allows adding multiple <a href="./struct.Arg.html"><code>Arg</code></a> aliases that functions exactly like those defined
|
||
with <a href="../../structopt/clap/struct.Arg.html#method.aliases" title="`Arg::aliases`"><code>Arg::aliases</code></a>, except that they are visible inside the help message.</p>
|
||
<h1 id="examples-8" class="section-header"><a href="#examples-8">Examples</a></h1>
|
||
<div class="example-wrap"><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">"prog"</span>)
|
||
.<span class="ident">arg</span>(<span class="ident">Arg</span>::<span class="ident">with_name</span>(<span class="string">"test"</span>)
|
||
.<span class="ident">long</span>(<span class="string">"test"</span>)
|
||
.<span class="ident">visible_aliases</span>(<span class="kw-2">&</span>[<span class="string">"something"</span>, <span class="string">"awesome"</span>, <span class="string">"cool"</span>]))
|
||
.<span class="ident">get_matches_from</span>(<span class="macro">vec</span><span class="macro">!</span>[
|
||
<span class="string">"prog"</span>, <span class="string">"--awesome"</span>
|
||
]);
|
||
<span class="macro">assert</span><span class="macro">!</span>(<span class="ident">m</span>.<span class="ident">is_present</span>(<span class="string">"test"</span>));</pre></div>
|
||
</div><h4 id='method.help' class="method"><code id='help.v'>pub 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>) -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a class='srclink' href='../../src/clap/args/arg.rs.html#546-549' title='goto source code'>[src]</a></h4><div class='docblock'><p>Sets the short help text of the argument that will be displayed to the user when they print
|
||
the help information with <code>-h</code>. Typically, this is a short (one line) description of the
|
||
arg.</p>
|
||
<p><strong>NOTE:</strong> If only <code>Arg::help</code> is provided, and not <a href="./struct.Arg.html#method.long_help"><code>Arg::long_help</code></a> but the user requests
|
||
<code>--help</code> clap will still display the contents of <code>help</code> appropriately</p>
|
||
<p><strong>NOTE:</strong> Only <code>Arg::help</code> is used in completion script generation in order to be concise</p>
|
||
<h1 id="examples-9" class="section-header"><a href="#examples-9">Examples</a></h1>
|
||
<p>Any valid UTF-8 is allowed in the help text. The one exception is when one wishes to
|
||
include a newline in the help text and have the following text be properly aligned with all
|
||
the other help text.</p>
|
||
|
||
<div class="example-wrap"><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></div>
|
||
<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>
|
||
|
||
<div class="example-wrap"><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">"prog"</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">"prog"</span>, <span class="string">"--help"</span>
|
||
]);</pre></div>
|
||
<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.long_help' class="method"><code id='long_help.v'>pub fn <a href='#method.long_help' class='fnname'>long_help</a>(self, h: &'b <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.str.html">str</a>) -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a class='srclink' href='../../src/clap/args/arg.rs.html#617-620' title='goto source code'>[src]</a></h4><div class='docblock'><p>Sets the long help text of the argument that will be displayed to the user when they print
|
||
the help information with <code>--help</code>. Typically this a more detailed (multi-line) message
|
||
that describes the arg.</p>
|
||
<p><strong>NOTE:</strong> If only <code>long_help</code> is provided, and not <a href="./struct.Arg.html#method.help"><code>Arg::help</code></a> but the user requests <code>-h</code>
|
||
clap will still display the contents of <code>long_help</code> appropriately</p>
|
||
<p><strong>NOTE:</strong> Only <a href="./struct.Arg.html#method.help"><code>Arg::help</code></a> is used in completion script generation in order to be concise</p>
|
||
<h1 id="examples-10" class="section-header"><a href="#examples-10">Examples</a></h1>
|
||
<p>Any valid UTF-8 is allowed in the help text. The one exception is when one wishes to
|
||
include a newline in the help text and have the following text be properly aligned with all
|
||
the other help text.</p>
|
||
|
||
<div class="example-wrap"><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">long_help</span>(
|
||
<span class="string">"The config file used by the myprog must be in JSON format
|
||
with only valid keys and may not contain other nonsense
|
||
that cannot be read by this program. Obviously I'm going on
|
||
and on, so I'll stop now."</span>)</pre></div>
|
||
<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>
|
||
|
||
<div class="example-wrap"><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">"prog"</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">long_help</span>(
|
||
<span class="string">"The config file used by the myprog must be in JSON format
|
||
with only valid keys and may not contain other nonsense
|
||
that cannot be read by this program. Obviously I'm going on
|
||
and on, so I'll stop now."</span>))
|
||
.<span class="ident">get_matches_from</span>(<span class="macro">vec</span><span class="macro">!</span>[
|
||
<span class="string">"prog"</span>, <span class="string">"--help"</span>
|
||
]);</pre></div>
|
||
<p>The above example displays</p>
|
||
<pre><code class="language-notrust">helptest
|
||
|
||
USAGE:
|
||
helptest [FLAGS]
|
||
|
||
FLAGS:
|
||
--config
|
||
The config file used by the myprog must be in JSON format
|
||
with only valid keys and may not contain other nonsense
|
||
that cannot be read by this program. Obviously I'm going on
|
||
and on, so I'll stop now.
|
||
|
||
-h, --help
|
||
Prints help information
|
||
|
||
-V, --version
|
||
Prints version information
|
||
</code></pre>
|
||
</div><h4 id='method.last' class="method"><code id='last.v'>pub fn <a href='#method.last' class='fnname'>last</a>(self, l: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.bool.html">bool</a>) -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a class='srclink' href='../../src/clap/args/arg.rs.html#694-700' title='goto source code'>[src]</a></h4><div class='docblock'><p>Specifies that this arg is the last, or final, positional argument (i.e. has the highest
|
||
index) and is <em>only</em> able to be accessed via the <code>--</code> syntax (i.e. <code>$ prog args -- last_arg</code>). Even, if no other arguments are left to parse, if the user omits the <code>--</code> syntax
|
||
they will receive an <a href="./enum.ErrorKind.html#variant.UnknownArgument"><code>UnknownArgument</code></a> error. Setting an argument to <code>.last(true)</code> also
|
||
allows one to access this arg early using the <code>--</code> syntax. Accessing an arg early, even with
|
||
the <code>--</code> syntax is otherwise not possible.</p>
|
||
<p><strong>NOTE:</strong> This will change the usage string to look like <code>$ prog [FLAGS] [-- <ARG>]</code> if
|
||
<code>ARG</code> is marked as <code>.last(true)</code>.</p>
|
||
<p><strong>NOTE:</strong> This setting will imply <a href="./enum.AppSettings.html#variant.DontCollapseArgsInUsage"><code>AppSettings::DontCollapseArgsInUsage</code></a> because failing
|
||
to set this can make the usage string very confusing.</p>
|
||
<p><strong>NOTE</strong>: This setting only applies to positional arguments, and has no affect on FLAGS /
|
||
OPTIONS</p>
|
||
<p><strong>CAUTION:</strong> Setting an argument to <code>.last(true)</code> <em>and</em> having child subcommands is not
|
||
recommended with the exception of <em>also</em> using <a href="./enum.AppSettings.html#variant.ArgsNegateSubcommands"><code>AppSettings::ArgsNegateSubcommands</code></a>
|
||
(or <a href="./enum.AppSettings.html#variant.SubcommandsNegateReqs"><code>AppSettings::SubcommandsNegateReqs</code></a> if the argument marked <code>.last(true)</code> is also
|
||
marked <a href="./struct.Arg.html#method.required"><code>.required(true)</code></a>)</p>
|
||
<h1 id="examples-11" class="section-header"><a href="#examples-11">Examples</a></h1>
|
||
<div class="example-wrap"><pre class="rust rust-example-rendered">
|
||
<span class="ident">Arg</span>::<span class="ident">with_name</span>(<span class="string">"args"</span>)
|
||
.<span class="ident">last</span>(<span class="bool-val">true</span>)</pre></div>
|
||
<p>Setting <a href="./struct.Arg.html#method.last"><code>Arg::last(true)</code></a> ensures the arg has the highest <a href="./struct.Arg.html#method.index">index</a> of all positional args
|
||
and requires that the <code>--</code> syntax be used to access it early.</p>
|
||
|
||
<div class="example-wrap"><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">"prog"</span>)
|
||
.<span class="ident">arg</span>(<span class="ident">Arg</span>::<span class="ident">with_name</span>(<span class="string">"first"</span>))
|
||
.<span class="ident">arg</span>(<span class="ident">Arg</span>::<span class="ident">with_name</span>(<span class="string">"second"</span>))
|
||
.<span class="ident">arg</span>(<span class="ident">Arg</span>::<span class="ident">with_name</span>(<span class="string">"third"</span>).<span class="ident">last</span>(<span class="bool-val">true</span>))
|
||
.<span class="ident">get_matches_from_safe</span>(<span class="macro">vec</span><span class="macro">!</span>[
|
||
<span class="string">"prog"</span>, <span class="string">"one"</span>, <span class="string">"--"</span>, <span class="string">"three"</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="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">m</span>.<span class="ident">value_of</span>(<span class="string">"third"</span>), <span class="prelude-val">Some</span>(<span class="string">"three"</span>));
|
||
<span class="macro">assert</span><span class="macro">!</span>(<span class="ident">m</span>.<span class="ident">value_of</span>(<span class="string">"second"</span>).<span class="ident">is_none</span>());</pre></div>
|
||
<p>Even if the positional argument marked <code>.last(true)</code> is the only argument left to parse,
|
||
failing to use the <code>--</code> syntax results in an error.</p>
|
||
|
||
<div class="example-wrap"><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">"prog"</span>)
|
||
.<span class="ident">arg</span>(<span class="ident">Arg</span>::<span class="ident">with_name</span>(<span class="string">"first"</span>))
|
||
.<span class="ident">arg</span>(<span class="ident">Arg</span>::<span class="ident">with_name</span>(<span class="string">"second"</span>))
|
||
.<span class="ident">arg</span>(<span class="ident">Arg</span>::<span class="ident">with_name</span>(<span class="string">"third"</span>).<span class="ident">last</span>(<span class="bool-val">true</span>))
|
||
.<span class="ident">get_matches_from_safe</span>(<span class="macro">vec</span><span class="macro">!</span>[
|
||
<span class="string">"prog"</span>, <span class="string">"one"</span>, <span class="string">"two"</span>, <span class="string">"three"</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>
|
||
</div><h4 id='method.required' class="method"><code id='required.v'>pub 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>) -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a class='srclink' href='../../src/clap/args/arg.rs.html#753-759' title='goto source code'>[src]</a></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 by
|
||
default. This is simply because if a flag should be required, it should simply be implied
|
||
as no additional information is required from user. Flags by their very nature are simply
|
||
yes/no, or true/false.</p>
|
||
<h1 id="examples-12" class="section-header"><a href="#examples-12">Examples</a></h1>
|
||
<div class="example-wrap"><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="bool-val">true</span>)</pre></div>
|
||
<p>Setting <a href="./struct.Arg.html#method.required"><code>Arg::required(true)</code></a> requires that the argument be used at runtime.</p>
|
||
|
||
<div class="example-wrap"><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">"prog"</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="bool-val">true</span>)
|
||
.<span class="ident">takes_value</span>(<span class="bool-val">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">"prog"</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></div>
|
||
<p>Setting <a href="./struct.Arg.html#method.required"><code>Arg::required(true)</code></a> and <em>not</em> supplying that argument is an error.</p>
|
||
|
||
<div class="example-wrap"><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">"prog"</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="bool-val">true</span>)
|
||
.<span class="ident">takes_value</span>(<span class="bool-val">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">"prog"</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>
|
||
</div><h4 id='method.require_equals' class="method"><code id='require_equals.v'>pub fn <a href='#method.require_equals' class='fnname'>require_equals</a>(self, r: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.bool.html">bool</a>) -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a class='srclink' href='../../src/clap/args/arg.rs.html#815-822' title='goto source code'>[src]</a></h4><div class='docblock'><p>Requires that options use the <code>--option=val</code> syntax (i.e. an equals between the option and
|
||
associated value) <strong>Default:</strong> <code>false</code></p>
|
||
<p><strong>NOTE:</strong> This setting also removes the default of allowing empty values and implies
|
||
<a href="./struct.Arg.html#method.empty_values"><code>Arg::empty_values(false)</code></a>.</p>
|
||
<h1 id="examples-13" class="section-header"><a href="#examples-13">Examples</a></h1>
|
||
<div class="example-wrap"><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">long</span>(<span class="string">"config"</span>)
|
||
.<span class="ident">takes_value</span>(<span class="bool-val">true</span>)
|
||
.<span class="ident">require_equals</span>(<span class="bool-val">true</span>)</pre></div>
|
||
<p>Setting <a href="./struct.Arg.html#method.require_equals"><code>Arg::require_equals(true)</code></a> requires that the option have an equals sign between
|
||
it and the associated value.</p>
|
||
|
||
<div class="example-wrap"><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">"prog"</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">require_equals</span>(<span class="bool-val">true</span>)
|
||
.<span class="ident">takes_value</span>(<span class="bool-val">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">"prog"</span>, <span class="string">"--config=file.conf"</span>
|
||
]);
|
||
|
||
<span class="macro">assert</span><span class="macro">!</span>(<span class="ident">res</span>.<span class="ident">is_ok</span>());</pre></div>
|
||
<p>Setting <a href="./struct.Arg.html#method.require_equals"><code>Arg::require_equals(true)</code></a> and <em>not</em> supplying the equals will cause an error
|
||
unless <a href="./struct.Arg.html#method.empty_values"><code>Arg::empty_values(true)</code></a> is set.</p>
|
||
|
||
<div class="example-wrap"><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">"prog"</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">require_equals</span>(<span class="bool-val">true</span>)
|
||
.<span class="ident">takes_value</span>(<span class="bool-val">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">"prog"</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">EmptyValue</span>);</pre></div>
|
||
</div><h4 id='method.allow_hyphen_values' class="method"><code id='allow_hyphen_values.v'>pub fn <a href='#method.allow_hyphen_values' class='fnname'>allow_hyphen_values</a>(self, a: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.bool.html">bool</a>) -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a class='srclink' href='../../src/clap/args/arg.rs.html#880-886' title='goto source code'>[src]</a></h4><div class='docblock'><p>Allows values which start with a leading hyphen (<code>-</code>)</p>
|
||
<p><strong>WARNING</strong>: Take caution when using this setting combined with <a href="./struct.Arg.html#method.multiple"><code>Arg::multiple(true)</code></a>, as
|
||
this becomes ambiguous <code>$ prog --arg -- -- val</code>. All three <code>--, --, val</code> will be values
|
||
when the user may have thought the second <code>--</code> would constitute the normal, "Only
|
||
positional args follow" idiom. To fix this, consider using <a href="./struct.Arg.html#method.number_of_values"><code>Arg::number_of_values(1)</code></a></p>
|
||
<p><strong>WARNING</strong>: When building your CLIs, consider the effects of allowing leading hyphens and
|
||
the user passing in a value that matches a valid short. For example <code>prog -opt -F</code> where
|
||
<code>-F</code> is supposed to be a value, yet <code>-F</code> is <em>also</em> a valid short for another arg. Care should
|
||
should be taken when designing these args. This is compounded by the ability to "stack"
|
||
short args. I.e. if <code>-val</code> is supposed to be a value, but <code>-v</code>, <code>-a</code>, and <code>-l</code> are all valid
|
||
shorts.</p>
|
||
<h1 id="examples-14" class="section-header"><a href="#examples-14">Examples</a></h1>
|
||
<div class="example-wrap"><pre class="rust rust-example-rendered">
|
||
<span class="ident">Arg</span>::<span class="ident">with_name</span>(<span class="string">"pattern"</span>)
|
||
.<span class="ident">allow_hyphen_values</span>(<span class="bool-val">true</span>)</pre></div>
|
||
|
||
<div class="example-wrap"><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">"prog"</span>)
|
||
.<span class="ident">arg</span>(<span class="ident">Arg</span>::<span class="ident">with_name</span>(<span class="string">"pat"</span>)
|
||
.<span class="ident">allow_hyphen_values</span>(<span class="bool-val">true</span>)
|
||
.<span class="ident">takes_value</span>(<span class="bool-val">true</span>)
|
||
.<span class="ident">long</span>(<span class="string">"pattern"</span>))
|
||
.<span class="ident">get_matches_from</span>(<span class="macro">vec</span><span class="macro">!</span>[
|
||
<span class="string">"prog"</span>, <span class="string">"--pattern"</span>, <span class="string">"-file"</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">"pat"</span>), <span class="prelude-val">Some</span>(<span class="string">"-file"</span>));</pre></div>
|
||
<p>Not setting <a href="./struct.Arg.html#method.allow_hyphen_values"><code>Arg::allow_hyphen_values(true)</code></a> and supplying a value which starts with a
|
||
hyphen is an error.</p>
|
||
|
||
<div class="example-wrap"><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">"prog"</span>)
|
||
.<span class="ident">arg</span>(<span class="ident">Arg</span>::<span class="ident">with_name</span>(<span class="string">"pat"</span>)
|
||
.<span class="ident">takes_value</span>(<span class="bool-val">true</span>)
|
||
.<span class="ident">long</span>(<span class="string">"pattern"</span>))
|
||
.<span class="ident">get_matches_from_safe</span>(<span class="macro">vec</span><span class="macro">!</span>[
|
||
<span class="string">"prog"</span>, <span class="string">"--pattern"</span>, <span class="string">"-file"</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>
|
||
</div><h4 id='method.required_unless' class="method"><code id='required_unless.v'>pub 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>) -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a class='srclink' href='../../src/clap/args/arg.rs.html#943-950' title='goto source code'>[src]</a></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 <a href="./struct.Arg.html#method.required_unless"><code>Arg::required_unless</code></a> implies <a href="./struct.Arg.html#method.required"><code>Arg::required</code></a> and is therefore not
|
||
mandatory to also set.</p>
|
||
<h1 id="examples-15" class="section-header"><a href="#examples-15">Examples</a></h1>
|
||
<div class="example-wrap"><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></div>
|
||
<p>Setting <a href="./struct.Arg.html#method.required_unless"><code>Arg::required_unless(name)</code></a> 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>
|
||
|
||
<div class="example-wrap"><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">"prog"</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="bool-val">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">"prog"</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></div>
|
||
<p>Setting <a href="./struct.Arg.html#method.required_unless"><code>Arg::required_unless(name)</code></a> and <em>not</em> supplying <code>name</code> or this arg is an error.</p>
|
||
|
||
<div class="example-wrap"><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">"prog"</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="bool-val">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">"prog"</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>
|
||
</div><h4 id='method.required_unless_all' class="method"><code id='required_unless_all.v'>pub 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>) -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a class='srclink' href='../../src/clap/args/arg.rs.html#1015-1025' title='goto source code'>[src]</a></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 arguments are present).</p>
|
||
<p><strong>NOTE:</strong> If you wish for this argument to only be required if <em>one of</em> these args are
|
||
present see <a href="./struct.Arg.html#method.required_unless_one"><code>Arg::required_unless_one</code></a></p>
|
||
<h1 id="examples-16" class="section-header"><a href="#examples-16">Examples</a></h1>
|
||
<div class="example-wrap"><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></div>
|
||
<p>Setting <a href="./struct.Arg.html#method.required_unless_all"><code>Arg::required_unless_all(names)</code></a> 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>
|
||
|
||
<div class="example-wrap"><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">"prog"</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="bool-val">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="bool-val">true</span>))
|
||
.<span class="ident">get_matches_from_safe</span>(<span class="macro">vec</span><span class="macro">!</span>[
|
||
<span class="string">"prog"</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></div>
|
||
<p>Setting <a href="./struct.Arg.html#method.required_unless_all"><code>Arg::required_unless_all(names)</code></a> and <em>not</em> supplying <em>all</em> of <code>names</code> or this
|
||
arg is an error.</p>
|
||
|
||
<div class="example-wrap"><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">"prog"</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="bool-val">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="bool-val">true</span>))
|
||
.<span class="ident">get_matches_from_safe</span>(<span class="macro">vec</span><span class="macro">!</span>[
|
||
<span class="string">"prog"</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>
|
||
</div><h4 id='method.required_unless_one' class="method"><code id='required_unless_one.v'>pub 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>) -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a class='srclink' href='../../src/clap/args/arg.rs.html#1091-1100' title='goto source code'>[src]</a></h4><div class='docblock'><p>Sets args that override this arg's <a href="./struct.Arg.html#method.required">required</a> setting. (i.e. this arg will be required
|
||
unless <em>at least one of</em> these other arguments are present).</p>
|
||
<p><strong>NOTE:</strong> If you wish for this argument to only be required if <em>all of</em> these args are
|
||
present see <a href="./struct.Arg.html#method.required_unless_all"><code>Arg::required_unless_all</code></a></p>
|
||
<h1 id="examples-17" class="section-header"><a href="#examples-17">Examples</a></h1>
|
||
<div class="example-wrap"><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></div>
|
||
<p>Setting <a href="./struct.Arg.html#method.required_unless_one"><code>Arg::required_unless_one(names)</code></a> 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>
|
||
|
||
<div class="example-wrap"><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">"prog"</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="bool-val">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="bool-val">true</span>))
|
||
.<span class="ident">get_matches_from_safe</span>(<span class="macro">vec</span><span class="macro">!</span>[
|
||
<span class="string">"prog"</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></div>
|
||
<p>Setting <a href="./struct.Arg.html#method.required_unless_one"><code>Arg::required_unless_one(names)</code></a> and <em>not</em> supplying <em>at least one of</em> <code>names</code>
|
||
or this arg is an error.</p>
|
||
|
||
<div class="example-wrap"><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">"prog"</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="bool-val">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="bool-val">true</span>))
|
||
.<span class="ident">get_matches_from_safe</span>(<span class="macro">vec</span><span class="macro">!</span>[
|
||
<span class="string">"prog"</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>
|
||
</div><h4 id='method.conflicts_with' class="method"><code id='conflicts_with.v'>pub 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>) -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a class='srclink' href='../../src/clap/args/arg.rs.html#1139-1146' title='goto source code'>[src]</a></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-18" class="section-header"><a href="#examples-18">Examples</a></h1>
|
||
<div class="example-wrap"><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></div>
|
||
<p>Setting conflicting argument, and having both arguments present at runtime is an error.</p>
|
||
|
||
<div class="example-wrap"><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">"prog"</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="bool-val">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">"prog"</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>
|
||
</div><h4 id='method.conflicts_with_all' class="method"><code id='conflicts_with_all.v'>pub 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>) -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a class='srclink' href='../../src/clap/args/arg.rs.html#1189-1198' title='goto source code'>[src]</a></h4><div class='docblock'><p>The same as <a href="./struct.Arg.html#method.conflicts_with"><code>Arg::conflicts_with</code></a> 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-19" class="section-header"><a href="#examples-19">Examples</a></h1>
|
||
<div class="example-wrap"><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></div>
|
||
<p>Setting conflicting argument, and having any of the arguments present at runtime with a
|
||
conflicting argument is an error.</p>
|
||
|
||
<div class="example-wrap"><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">"prog"</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="bool-val">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">"prog"</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>
|
||
</div><h4 id='method.overrides_with' class="method"><code id='overrides_with.v'>pub 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>) -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a class='srclink' href='../../src/clap/args/arg.rs.html#1298-1305' title='goto source code'>[src]</a></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 overridden it is essentially as if it never was used, any
|
||
conflicts, requirements, etc. are evaluated <strong>after</strong> all "overrides" have been removed</p>
|
||
<p><strong>WARNING:</strong> Positional arguments cannot override themselves (or we would never be able
|
||
to advance to the next positional). If a positional agument lists itself as an override,
|
||
it is simply ignored.</p>
|
||
<h1 id="examples-20" class="section-header"><a href="#examples-20">Examples</a></h1>
|
||
<div class="example-wrap"><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">"prog"</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">"prog"</span>, <span class="string">"-f"</span>, <span class="string">"-d"</span>, <span class="string">"-c"</span>]);
|
||
<span class="comment">// ^~~~~~~~~~~~^~~~~ flag is overridden 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 overridden 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>
|
||
<p>Care must be taken when using this setting, and having an arg override with itself. This
|
||
is common practice when supporting things like shell aliases, config files, etc.
|
||
However, when combined with multiple values, it can get dicy.
|
||
Here is how clap handles such situations:</p>
|
||
<p>When a flag overrides itself, it's as if the flag was only ever used once (essentially
|
||
preventing a "Unexpected multiple usage" error):</p>
|
||
|
||
<div class="example-wrap"><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">"--flag 'some 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">"--flag"</span>, <span class="string">"--flag"</span>]);
|
||
<span class="macro">assert</span><span class="macro">!</span>(<span class="ident">m</span>.<span class="ident">is_present</span>(<span class="string">"flag"</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">"flag"</span>), <span class="number">1</span>);</pre></div>
|
||
<p>Making a arg <code>multiple(true)</code> and override itself is essentially meaningless. Therefore
|
||
clap ignores an override of self if it's a flag and it already accepts multiple occurrences.</p>
|
||
|
||
<div class="example-wrap"><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">"--flag... 'some 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">""</span>, <span class="string">"--flag"</span>, <span class="string">"--flag"</span>, <span class="string">"--flag"</span>, <span class="string">"--flag"</span>]);
|
||
<span class="macro">assert</span><span class="macro">!</span>(<span class="ident">m</span>.<span class="ident">is_present</span>(<span class="string">"flag"</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">"flag"</span>), <span class="number">4</span>);</pre></div>
|
||
<p>Now notice with options (which <em>do not</em> set <code>multiple(true)</code>), it's as if only the last
|
||
occurrence happened.</p>
|
||
|
||
<div class="example-wrap"><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">"--opt [val] 'some option'"</span>).<span class="ident">overrides_with</span>(<span class="string">"opt"</span>))
|
||
.<span class="ident">get_matches_from</span>(<span class="macro">vec</span><span class="macro">!</span>[<span class="string">""</span>, <span class="string">"--opt=some"</span>, <span class="string">"--opt=other"</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">1</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">"other"</span>));</pre></div>
|
||
<p>Just like flags, options with <code>multiple(true)</code> set, will ignore the "override self" setting.</p>
|
||
|
||
<div class="example-wrap"><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">"--opt [val]... 'some option'"</span>)
|
||
.<span class="ident">overrides_with</span>(<span class="string">"opt"</span>))
|
||
.<span class="ident">get_matches_from</span>(<span class="macro">vec</span><span class="macro">!</span>[<span class="string">""</span>, <span class="string">"--opt"</span>, <span class="string">"first"</span>, <span class="string">"over"</span>, <span class="string">"--opt"</span>, <span class="string">"other"</span>, <span class="string">"val"</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">2</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">"opt"</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="kw">_</span><span class="op">></span><span class="op">></span>(), <span class="kw-2">&</span>[<span class="string">"first"</span>, <span class="string">"over"</span>, <span class="string">"other"</span>, <span class="string">"val"</span>]);</pre></div>
|
||
<p>A safe thing to do if you'd like to support an option which supports multiple values, but
|
||
also is "overridable" by itself, is to use <code>use_delimiter(false)</code> and <em>not</em> use
|
||
<code>multiple(true)</code> while telling users to seperate values with a comma (i.e. <code>val1,val2</code>)</p>
|
||
|
||
<div class="example-wrap"><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">"--opt [val] 'some option'"</span>)
|
||
.<span class="ident">overrides_with</span>(<span class="string">"opt"</span>)
|
||
.<span class="ident">use_delimiter</span>(<span class="bool-val">false</span>))
|
||
.<span class="ident">get_matches_from</span>(<span class="macro">vec</span><span class="macro">!</span>[<span class="string">""</span>, <span class="string">"--opt=some,other"</span>, <span class="string">"--opt=one,two"</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">1</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">"opt"</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="kw">_</span><span class="op">></span><span class="op">></span>(), <span class="kw-2">&</span>[<span class="string">"one,two"</span>]);</pre></div>
|
||
</div><h4 id='method.overrides_with_all' class="method"><code id='overrides_with_all.v'>pub 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>) -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a class='srclink' href='../../src/clap/args/arg.rs.html#1334-1343' title='goto source code'>[src]</a></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 overridden 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-21" class="section-header"><a href="#examples-21">Examples</a></h1>
|
||
<div class="example-wrap"><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">"prog"</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">"prog"</span>, <span class="string">"-f"</span>, <span class="string">"-d"</span>, <span class="string">"-c"</span>]);
|
||
<span class="comment">// ^~~~~~^~~~~~~~~ flag and debug are overridden 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 overridden</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>
|
||
</div><h4 id='method.requires' class="method"><code id='requires.v'>pub 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>) -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a class='srclink' href='../../src/clap/args/arg.rs.html#1400-1409' title='goto source code'>[src]</a></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> <a href="./struct.Arg.html#method.conflicts_with">Conflicting</a> rules and <a href="./struct.Arg.html#method.overrides_with">override</a> rules take precedence over being required</p>
|
||
<h1 id="examples-22" class="section-header"><a href="#examples-22">Examples</a></h1>
|
||
<div class="example-wrap"><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></div>
|
||
<p>Setting <a href="./struct.Arg.html#method.requires"><code>Arg::requires(name)</code></a> requires that the argument be used at runtime if the
|
||
defining argument is used. If the defining argument isn't used, the other argument isn't
|
||
required</p>
|
||
|
||
<div class="example-wrap"><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">"prog"</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="bool-val">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">"prog"</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></div>
|
||
<p>Setting <a href="./struct.Arg.html#method.requires"><code>Arg::requires(name)</code></a> and <em>not</em> supplying that argument is an error.</p>
|
||
|
||
<div class="example-wrap"><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">"prog"</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="bool-val">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">"prog"</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>
|
||
</div><h4 id='method.requires_if' class="method"><code id='requires_if.v'>pub fn <a href='#method.requires_if' class='fnname'>requires_if</a>(self, val: &'b <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.str.html">str</a>, arg: &'a <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.str.html">str</a>) -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a class='srclink' href='../../src/clap/args/arg.rs.html#1470-1477' title='goto source code'>[src]</a></h4><div class='docblock'><p>Allows a conditional requirement. The requirement will only become valid if this arg's value
|
||
equals <code>val</code>.</p>
|
||
<p><strong>NOTE:</strong> If using YAML the values should be laid out as follows</p>
|
||
<pre><code class="language-yaml">requires_if:
|
||
- [val, arg]
|
||
</code></pre>
|
||
<h1 id="examples-23" class="section-header"><a href="#examples-23">Examples</a></h1>
|
||
<div class="example-wrap"><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_if</span>(<span class="string">"val"</span>, <span class="string">"arg"</span>)</pre></div>
|
||
<p>Setting [<code>Arg::requires_if(val, arg)</code>] requires that the <code>arg</code> be used at runtime if the
|
||
defining argument's value is equal to <code>val</code>. If the defining argument is anything other than
|
||
<code>val</code>, the other argument isn't required.</p>
|
||
|
||
<div class="example-wrap"><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">"prog"</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="bool-val">true</span>)
|
||
.<span class="ident">requires_if</span>(<span class="string">"my.cfg"</span>, <span class="string">"other"</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">"other"</span>))
|
||
.<span class="ident">get_matches_from_safe</span>(<span class="macro">vec</span><span class="macro">!</span>[
|
||
<span class="string">"prog"</span>, <span class="string">"--config"</span>, <span class="string">"some.cfg"</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 --config=my.cfg, so other wasn't required</span></pre></div>
|
||
<p>Setting [<code>Arg::requires_if(val, arg)</code>] and setting the value to <code>val</code> but <em>not</em> supplying
|
||
<code>arg</code> is an error.</p>
|
||
|
||
<div class="example-wrap"><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">"prog"</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="bool-val">true</span>)
|
||
.<span class="ident">requires_if</span>(<span class="string">"my.cfg"</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">get_matches_from_safe</span>(<span class="macro">vec</span><span class="macro">!</span>[
|
||
<span class="string">"prog"</span>, <span class="string">"--config"</span>, <span class="string">"my.cfg"</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>
|
||
</div><h4 id='method.requires_ifs' class="method"><code id='requires_ifs.v'>pub fn <a href='#method.requires_ifs' class='fnname'>requires_ifs</a>(self, ifs: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.slice.html">&[</a><a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.tuple.html">(</a>&'b <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.str.html">str</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.tuple.html">)</a><a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.slice.html">]</a>) -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a class='srclink' href='../../src/clap/args/arg.rs.html#1530-1543' title='goto source code'>[src]</a></h4><div class='docblock'><p>Allows multiple conditional requirements. The requirement will only become valid if this arg's value
|
||
equals <code>val</code>.</p>
|
||
<p><strong>NOTE:</strong> If using YAML the values should be laid out as follows</p>
|
||
<pre><code class="language-yaml">requires_if:
|
||
- [val, arg]
|
||
- [val2, arg2]
|
||
</code></pre>
|
||
<h1 id="examples-24" class="section-header"><a href="#examples-24">Examples</a></h1>
|
||
<div class="example-wrap"><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_ifs</span>(<span class="kw-2">&</span>[
|
||
(<span class="string">"val"</span>, <span class="string">"arg"</span>),
|
||
(<span class="string">"other_val"</span>, <span class="string">"arg2"</span>),
|
||
])</pre></div>
|
||
<p>Setting [<code>Arg::requires_ifs(&["val", "arg"])</code>] requires that the <code>arg</code> be used at runtime if the
|
||
defining argument's value is equal to <code>val</code>. If the defining argument's value is anything other
|
||
than <code>val</code>, <code>arg</code> isn't required.</p>
|
||
|
||
<div class="example-wrap"><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">"prog"</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="bool-val">true</span>)
|
||
.<span class="ident">requires_ifs</span>(<span class="kw-2">&</span>[
|
||
(<span class="string">"special.conf"</span>, <span class="string">"opt"</span>),
|
||
(<span class="string">"other.conf"</span>, <span class="string">"other"</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">"opt"</span>)
|
||
.<span class="ident">long</span>(<span class="string">"option"</span>)
|
||
.<span class="ident">takes_value</span>(<span class="bool-val">true</span>))
|
||
.<span class="ident">arg</span>(<span class="ident">Arg</span>::<span class="ident">with_name</span>(<span class="string">"other"</span>))
|
||
.<span class="ident">get_matches_from_safe</span>(<span class="macro">vec</span><span class="macro">!</span>[
|
||
<span class="string">"prog"</span>, <span class="string">"--config"</span>, <span class="string">"special.conf"</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 used --config=special.conf so --option <val> is required</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>
|
||
</div><h4 id='method.required_if' class="method"><code id='required_if.v'>pub fn <a href='#method.required_if' class='fnname'>required_if</a>(self, arg: &'a <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.str.html">str</a>, val: &'b <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.str.html">str</a>) -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a class='srclink' href='../../src/clap/args/arg.rs.html#1608-1615' title='goto source code'>[src]</a></h4><div class='docblock'><p>Allows specifying that an argument is <a href="./struct.Arg.html#method.required">required</a> conditionally. The requirement will only
|
||
become valid if the specified <code>arg</code>'s value equals <code>val</code>.</p>
|
||
<p><strong>NOTE:</strong> If using YAML the values should be laid out as follows</p>
|
||
<pre><code class="language-yaml">required_if:
|
||
- [arg, val]
|
||
</code></pre>
|
||
<h1 id="examples-25" class="section-header"><a href="#examples-25">Examples</a></h1>
|
||
<div class="example-wrap"><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_if</span>(<span class="string">"other_arg"</span>, <span class="string">"value"</span>)</pre></div>
|
||
<p>Setting [<code>Arg::required_if(arg, val)</code>] makes this arg required if the <code>arg</code> is used at
|
||
runtime and it's value is equal to <code>val</code>. If the <code>arg</code>'s value is anything other than <code>val</code>,
|
||
this argument isn't required.</p>
|
||
|
||
<div class="example-wrap"><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">"prog"</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="bool-val">true</span>)
|
||
.<span class="ident">required_if</span>(<span class="string">"other"</span>, <span class="string">"special"</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">"other"</span>)
|
||
.<span class="ident">long</span>(<span class="string">"other"</span>)
|
||
.<span class="ident">takes_value</span>(<span class="bool-val">true</span>))
|
||
.<span class="ident">get_matches_from_safe</span>(<span class="macro">vec</span><span class="macro">!</span>[
|
||
<span class="string">"prog"</span>, <span class="string">"--other"</span>, <span class="string">"not-special"</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 --other=special, so "cfg" wasn't required</span></pre></div>
|
||
<p>Setting [<code>Arg::required_if(arg, val)</code>] and having <code>arg</code> used with a value of <code>val</code> but <em>not</em>
|
||
using this arg is an error.</p>
|
||
|
||
<div class="example-wrap"><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">"prog"</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="bool-val">true</span>)
|
||
.<span class="ident">required_if</span>(<span class="string">"other"</span>, <span class="string">"special"</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">"other"</span>)
|
||
.<span class="ident">long</span>(<span class="string">"other"</span>)
|
||
.<span class="ident">takes_value</span>(<span class="bool-val">true</span>))
|
||
.<span class="ident">get_matches_from_safe</span>(<span class="macro">vec</span><span class="macro">!</span>[
|
||
<span class="string">"prog"</span>, <span class="string">"--other"</span>, <span class="string">"special"</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>
|
||
</div><h4 id='method.required_ifs' class="method"><code id='required_ifs.v'>pub fn <a href='#method.required_ifs' class='fnname'>required_ifs</a>(self, ifs: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.slice.html">&[</a><a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.tuple.html">(</a>&'a <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.str.html">str</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.tuple.html">)</a><a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.slice.html">]</a>) -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a class='srclink' href='../../src/clap/args/arg.rs.html#1697-1710' title='goto source code'>[src]</a></h4><div class='docblock'><p>Allows specifying that an argument is <a href="./struct.Arg.html#method.required">required</a> based on multiple conditions. The
|
||
conditions are set up in a <code>(arg, val)</code> style tuple. The requirement will only become valid
|
||
if one of the specified <code>arg</code>'s value equals it's corresponding <code>val</code>.</p>
|
||
<p><strong>NOTE:</strong> If using YAML the values should be laid out as follows</p>
|
||
<pre><code class="language-yaml">required_if:
|
||
- [arg, val]
|
||
- [arg2, val2]
|
||
</code></pre>
|
||
<h1 id="examples-26" class="section-header"><a href="#examples-26">Examples</a></h1>
|
||
<div class="example-wrap"><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_ifs</span>(<span class="kw-2">&</span>[
|
||
(<span class="string">"extra"</span>, <span class="string">"val"</span>),
|
||
(<span class="string">"option"</span>, <span class="string">"spec"</span>)
|
||
])</pre></div>
|
||
<p>Setting [<code>Arg::required_ifs(&[(arg, val)])</code>] makes this arg required if any of the <code>arg</code>s
|
||
are used at runtime and it's corresponding value is equal to <code>val</code>. If the <code>arg</code>'s value is
|
||
anything other than <code>val</code>, this argument isn't required.</p>
|
||
|
||
<div class="example-wrap"><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">"prog"</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_ifs</span>(<span class="kw-2">&</span>[
|
||
(<span class="string">"extra"</span>, <span class="string">"val"</span>),
|
||
(<span class="string">"option"</span>, <span class="string">"spec"</span>)
|
||
])
|
||
.<span class="ident">takes_value</span>(<span class="bool-val">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">"extra"</span>)
|
||
.<span class="ident">takes_value</span>(<span class="bool-val">true</span>)
|
||
.<span class="ident">long</span>(<span class="string">"extra"</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">takes_value</span>(<span class="bool-val">true</span>)
|
||
.<span class="ident">long</span>(<span class="string">"option"</span>))
|
||
.<span class="ident">get_matches_from_safe</span>(<span class="macro">vec</span><span class="macro">!</span>[
|
||
<span class="string">"prog"</span>, <span class="string">"--option"</span>, <span class="string">"other"</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 --option=spec, or --extra=val so "cfg" isn't required</span></pre></div>
|
||
<p>Setting [<code>Arg::required_ifs(&[(arg, val)])</code>] and having any of the <code>arg</code>s used with it's
|
||
value of <code>val</code> but <em>not</em> using this arg is an error.</p>
|
||
|
||
<div class="example-wrap"><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">"prog"</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_ifs</span>(<span class="kw-2">&</span>[
|
||
(<span class="string">"extra"</span>, <span class="string">"val"</span>),
|
||
(<span class="string">"option"</span>, <span class="string">"spec"</span>)
|
||
])
|
||
.<span class="ident">takes_value</span>(<span class="bool-val">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">"extra"</span>)
|
||
.<span class="ident">takes_value</span>(<span class="bool-val">true</span>)
|
||
.<span class="ident">long</span>(<span class="string">"extra"</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">takes_value</span>(<span class="bool-val">true</span>)
|
||
.<span class="ident">long</span>(<span class="string">"option"</span>))
|
||
.<span class="ident">get_matches_from_safe</span>(<span class="macro">vec</span><span class="macro">!</span>[
|
||
<span class="string">"prog"</span>, <span class="string">"--option"</span>, <span class="string">"spec"</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>
|
||
</div><h4 id='method.requires_all' class="method"><code id='requires_all.v'>pub 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>) -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a class='srclink' href='../../src/clap/args/arg.rs.html#1774-1787' title='goto source code'>[src]</a></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> <a href="./struct.Arg.html#method.conflicts_with">Conflicting</a> rules and <a href="./struct.Arg.html#method.overrides_with">override</a> rules take precedence over being required
|
||
by default.</p>
|
||
<h1 id="examples-27" class="section-header"><a href="#examples-27">Examples</a></h1>
|
||
<div class="example-wrap"><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></div>
|
||
<p>Setting [<code>Arg::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
|
||
argument isn't required</p>
|
||
|
||
<div class="example-wrap"><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">"prog"</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="bool-val">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">"prog"</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></div>
|
||
<p>Setting [<code>Arg::requires_all(&[arg, arg2])</code>] and <em>not</em> supplying all the arguments is an
|
||
error.</p>
|
||
|
||
<div class="example-wrap"><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">"prog"</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="bool-val">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">"prog"</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>
|
||
<p>[<code>Arg::requires_all(&[arg, arg2])</code>]: ./struct.Arg.html#method.requires_all</p>
|
||
</div><h4 id='method.takes_value' class="method"><code id='takes_value.v'>pub 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>) -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a class='srclink' href='../../src/clap/args/arg.rs.html#1827-1833' title='goto source code'>[src]</a></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, args which allow <a href="./struct.Arg.html#method.multiple">multiple values</a> are delimited by commas, meaning
|
||
<code>--option=val1,val2,val3</code> is three values for the <code>--option</code> argument. If you wish to
|
||
change the delimiter to another character you can use <a href="./struct.Arg.html#method.value_delimiter"><code>Arg::value_delimiter(char)</code></a>,
|
||
alternatively you can turn delimiting values <strong>OFF</strong> by using <a href="./struct.Arg.html#method.use_delimiter"><code>Arg::use_delimiter(false)</code></a></p>
|
||
<h1 id="examples-28" class="section-header"><a href="#examples-28">Examples</a></h1>
|
||
<div class="example-wrap"><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="bool-val">true</span>)</pre></div>
|
||
|
||
<div class="example-wrap"><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">"prog"</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="bool-val">true</span>))
|
||
.<span class="ident">get_matches_from</span>(<span class="macro">vec</span><span class="macro">!</span>[
|
||
<span class="string">"prog"</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>
|
||
</div><h4 id='method.hide_possible_values' class="method"><code id='hide_possible_values.v'>pub fn <a href='#method.hide_possible_values' class='fnname'>hide_possible_values</a>(self, hide: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.bool.html">bool</a>) -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a class='srclink' href='../../src/clap/args/arg.rs.html#1863-1869' title='goto source code'>[src]</a></h4><div class='docblock'><p>Specifies if the possible values of an argument should be displayed in the help text or
|
||
not. Defaults to <code>false</code> (i.e. show possible values)</p>
|
||
<p>This is useful for args with many values, or ones which are explained elsewhere in the
|
||
help text.</p>
|
||
<h1 id="examples-29" class="section-header"><a href="#examples-29">Examples</a></h1>
|
||
<div class="example-wrap"><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">hide_possible_values</span>(<span class="bool-val">true</span>)</pre></div>
|
||
|
||
<div class="example-wrap"><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">"prog"</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">possible_values</span>(<span class="kw-2">&</span>[<span class="string">"fast"</span>, <span class="string">"slow"</span>])
|
||
.<span class="ident">takes_value</span>(<span class="bool-val">true</span>)
|
||
.<span class="ident">hide_possible_values</span>(<span class="bool-val">true</span>));
|
||
</pre></div>
|
||
<p>If we were to run the above program with <code>--help</code> the <code>[values: fast, slow]</code> portion of
|
||
the help text would be omitted.</p>
|
||
</div><h4 id='method.hide_default_value' class="method"><code id='hide_default_value.v'>pub fn <a href='#method.hide_default_value' class='fnname'>hide_default_value</a>(self, hide: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.bool.html">bool</a>) -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a class='srclink' href='../../src/clap/args/arg.rs.html#1897-1903' title='goto source code'>[src]</a></h4><div class='docblock'><p>Specifies if the default value of an argument should be displayed in the help text or
|
||
not. Defaults to <code>false</code> (i.e. show default value)</p>
|
||
<p>This is useful when default behavior of an arg is explained elsewhere in the help text.</p>
|
||
<h1 id="examples-30" class="section-header"><a href="#examples-30">Examples</a></h1>
|
||
<div class="example-wrap"><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">hide_default_value</span>(<span class="bool-val">true</span>)</pre></div>
|
||
|
||
<div class="example-wrap"><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">"connect"</span>)
|
||
.<span class="ident">arg</span>(<span class="ident">Arg</span>::<span class="ident">with_name</span>(<span class="string">"host"</span>)
|
||
.<span class="ident">long</span>(<span class="string">"host"</span>)
|
||
.<span class="ident">default_value</span>(<span class="string">"localhost"</span>)
|
||
.<span class="ident">hide_default_value</span>(<span class="bool-val">true</span>));
|
||
</pre></div>
|
||
<p>If we were to run the above program with <code>--help</code> the <code>[default: localhost]</code> portion of
|
||
the help text would be omitted.</p>
|
||
</div><h4 id='method.index' class="method"><code id='index.v'>pub 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>) -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a class='srclink' href='../../src/clap/args/arg.rs.html#1952-1955' title='goto source code'>[src]</a></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 <a href="./struct.Arg.html#method.short"><code>Arg::short</code></a>, or <a href="./struct.Arg.html#method.long"><code>Arg::long</code></a> 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 <a href="./struct.Arg.html#method.multiple"><code>Arg::multiple(true)</code></a>, only the <strong>last</strong> positional 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, <a href="./struct.App.html"><code>App</code></a> will <a href="https://doc.rust-lang.org/std/macro.panic!.html"><code>panic!</code></a> 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-31" class="section-header"><a href="#examples-31">Examples</a></h1>
|
||
<div class="example-wrap"><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></div>
|
||
|
||
<div class="example-wrap"><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">"prog"</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">"prog"</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>
|
||
</div><h4 id='method.multiple' class="method"><code id='multiple.v'>pub 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>) -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a class='srclink' href='../../src/clap/args/arg.rs.html#2148-2154' title='goto source code'>[src]</a></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>multiple(true)</code> for an <a href="./struct.Arg.html#method.takes_value">option</a> with no other details, allows multiple values
|
||
<strong>and</strong> multiple occurrences because it isn't possible to have 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 expected 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 <a href="./struct.Arg.html#method.number_of_values"><code>Arg::number_of_values(1)</code></a> in coordination with
|
||
<a href="./struct.Arg.html#method.multiple"><code>Arg::multiple(true)</code></a>.</p>
|
||
<p><strong>WARNING:</strong></p>
|
||
<p>When using args with <code>multiple(true)</code> on <a href="./struct.Arg.html#method.takes_value">options</a> or <a href="./struct.Arg.html#method.index">positionals</a> (i.e. those args that
|
||
accept values) and <a href="./struct.SubCommand.html">subcommands</a>, one needs to consider the possibility of an argument value
|
||
being the same as a valid subcommand. By default <code>clap</code> will parse the argument in question
|
||
as a value <em>only if</em> a value is possible at that moment. Otherwise it will be parsed as a
|
||
subcommand. In effect, this means using <code>multiple(true)</code> with no additional parameters and
|
||
a possible value that coincides with a subcommand name, the subcommand cannot be called
|
||
unless another argument is passed first.</p>
|
||
<p>As an example, consider a CLI with an option <code>--ui-paths=<paths>...</code> and subcommand <code>signer</code></p>
|
||
<p>The following would be parsed as values to <code>--ui-paths</code>.</p>
|
||
<pre><code class="language-notrust">$ program --ui-paths path1 path2 signer
|
||
</code></pre>
|
||
<p>This is because <code>--ui-paths</code> accepts multiple values. <code>clap</code> will continue parsing values
|
||
until another argument is reached and it knows <code>--ui-paths</code> is done.</p>
|
||
<p>By adding additional parameters to <code>--ui-paths</code> we can solve this issue. Consider adding
|
||
<a href="./struct.Arg.html#method.number_of_values"><code>Arg::number_of_values(1)</code></a> as discussed above. The following are all valid, and <code>signer</code>
|
||
is parsed as both a subcommand and a value in the second case.</p>
|
||
<pre><code class="language-notrust">$ program --ui-paths path1 signer
|
||
$ program --ui-paths path1 --ui-paths signer signer
|
||
</code></pre>
|
||
<h1 id="examples-32" class="section-header"><a href="#examples-32">Examples</a></h1>
|
||
<div class="example-wrap"><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="bool-val">true</span>)</pre></div>
|
||
<p>An example with flags</p>
|
||
|
||
<div class="example-wrap"><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">"prog"</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="bool-val">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">"prog"</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></div>
|
||
<p>An example with options</p>
|
||
|
||
<div class="example-wrap"><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">"prog"</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="bool-val">true</span>)
|
||
.<span class="ident">takes_value</span>(<span class="bool-val">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">"prog"</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="kw">_</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></div>
|
||
<p>This is functionally equivalent to the example above</p>
|
||
|
||
<div class="example-wrap"><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">"prog"</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="bool-val">true</span>)
|
||
.<span class="ident">takes_value</span>(<span class="bool-val">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">"prog"</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="kw">_</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="kw">_</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></div>
|
||
<p>A common mistake is to define an option which allows multiples, and a positional argument</p>
|
||
|
||
<div class="example-wrap"><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">"prog"</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="bool-val">true</span>)
|
||
.<span class="ident">takes_value</span>(<span class="bool-val">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">"prog"</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="kw">_</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></div>
|
||
<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>
|
||
|
||
<div class="example-wrap"><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">"prog"</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="bool-val">true</span>)
|
||
.<span class="ident">takes_value</span>(<span class="bool-val">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">"prog"</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="kw">_</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></div>
|
||
<p>As a final example, notice if we define <a href="./struct.Arg.html#method.number_of_values"><code>Arg::number_of_values(1)</code></a> and try to run the
|
||
problem example above, it would have been a runtime error with a pretty message to the
|
||
user :)</p>
|
||
|
||
<div class="example-wrap"><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">"prog"</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="bool-val">true</span>)
|
||
.<span class="ident">takes_value</span>(<span class="bool-val">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">"prog"</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>
|
||
</div><h4 id='method.value_terminator' class="method"><code id='value_terminator.v'>pub fn <a href='#method.value_terminator' class='fnname'>value_terminator</a>(self, term: &'b <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.str.html">str</a>) -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a class='srclink' href='../../src/clap/args/arg.rs.html#2201-2205' title='goto source code'>[src]</a></h4><div class='docblock'><p>Specifies a value that <em>stops</em> parsing multiple values of a give argument. By default when
|
||
one sets <a href="./struct.Arg.html#method.multiple"><code>multiple(true)</code></a> on an argument, clap will continue parsing values for that
|
||
argument until it reaches another valid argument, or one of the other more specific settings
|
||
for multiple values is used (such as <a href="./struct.Arg.html#method.min_values"><code>min_values</code></a>, <a href="./struct.Arg.html#method.max_values"><code>max_values</code></a> or
|
||
<a href="./struct.Arg.html#method.number_of_values"><code>number_of_values</code></a>).</p>
|
||
<p><strong>NOTE:</strong> This setting only applies to <a href="./struct.Arg.html#method.takes_value">options</a> and <a href="./struct.Arg.html#method.index">positional arguments</a></p>
|
||
<p><strong>NOTE:</strong> When the terminator is passed in on the command line, it is <strong>not</strong> stored as one
|
||
of the values</p>
|
||
<h1 id="examples-33" class="section-header"><a href="#examples-33">Examples</a></h1>
|
||
<div class="example-wrap"><pre class="rust rust-example-rendered">
|
||
<span class="ident">Arg</span>::<span class="ident">with_name</span>(<span class="string">"vals"</span>)
|
||
.<span class="ident">takes_value</span>(<span class="bool-val">true</span>)
|
||
.<span class="ident">multiple</span>(<span class="bool-val">true</span>)
|
||
.<span class="ident">value_terminator</span>(<span class="string">";"</span>)</pre></div>
|
||
<p>The following example uses two arguments, a sequence of commands, and the location in which
|
||
to perform them</p>
|
||
|
||
<div class="example-wrap"><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">"prog"</span>)
|
||
.<span class="ident">arg</span>(<span class="ident">Arg</span>::<span class="ident">with_name</span>(<span class="string">"cmds"</span>)
|
||
.<span class="ident">multiple</span>(<span class="bool-val">true</span>)
|
||
.<span class="ident">allow_hyphen_values</span>(<span class="bool-val">true</span>)
|
||
.<span class="ident">value_terminator</span>(<span class="string">";"</span>))
|
||
.<span class="ident">arg</span>(<span class="ident">Arg</span>::<span class="ident">with_name</span>(<span class="string">"location"</span>))
|
||
.<span class="ident">get_matches_from</span>(<span class="macro">vec</span><span class="macro">!</span>[
|
||
<span class="string">"prog"</span>, <span class="string">"find"</span>, <span class="string">"-type"</span>, <span class="string">"f"</span>, <span class="string">"-name"</span>, <span class="string">"special"</span>, <span class="string">";"</span>, <span class="string">"/home/clap"</span>
|
||
]);
|
||
<span class="kw">let</span> <span class="ident">cmds</span>: <span class="ident">Vec</span><span class="op"><</span><span class="kw">_</span><span class="op">></span> <span class="op">=</span> <span class="ident">m</span>.<span class="ident">values_of</span>(<span class="string">"cmds"</span>).<span class="ident">unwrap</span>().<span class="ident">collect</span>();
|
||
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="kw-2">&</span><span class="ident">cmds</span>, <span class="kw-2">&</span>[<span class="string">"find"</span>, <span class="string">"-type"</span>, <span class="string">"f"</span>, <span class="string">"-name"</span>, <span class="string">"special"</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">"location"</span>), <span class="prelude-val">Some</span>(<span class="string">"/home/clap"</span>));</pre></div>
|
||
</div><h4 id='method.global' class="method"><code id='global.v'>pub 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>) -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a class='srclink' href='../../src/clap/args/arg.rs.html#2250-2256' title='goto source code'>[src]</a></h4><div class='docblock'><p>Specifies that an argument can be matched to all child <a href="./struct.SubCommand.html"><code>SubCommand</code></a>s.</p>
|
||
<p><strong>NOTE:</strong> Global arguments <em>only</em> propagate down, <strong>not</strong> up (to parent commands), however
|
||
their values once a user uses them will be propagated back up to parents. In effect, this
|
||
means one should <em>define</em> all global arguments at the top level, however it doesn't matter
|
||
where the user <em>uses</em> the global argument.</p>
|
||
<h1 id="examples-34" class="section-header"><a href="#examples-34">Examples</a></h1>
|
||
<div class="example-wrap"><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="bool-val">true</span>)</pre></div>
|
||
<p>For example, assume an application 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 <a href="./struct.Arg.html"><code>Arg</code></a> definitions.</p>
|
||
|
||
<div class="example-wrap"><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">"prog"</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="bool-val">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">"prog"</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>
|
||
</div><h4 id='method.empty_values' class="method"><code id='empty_values.v'>pub 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>) -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a class='srclink' href='../../src/clap/args/arg.rs.html#2292-2299' title='goto source code'>[src]</a></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 <a href="./struct.Arg.html#method.takes_value"><code>Arg::takes_value(true)</code></a> when set to <code>false</code></p>
|
||
<h1 id="examples-35" class="section-header"><a href="#examples-35">Examples</a></h1>
|
||
<div class="example-wrap"><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="bool-val">false</span>)</pre></div>
|
||
<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>
|
||
|
||
<div class="example-wrap"><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">"prog"</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="bool-val">false</span>))
|
||
.<span class="ident">get_matches_from_safe</span>(<span class="macro">vec</span><span class="macro">!</span>[
|
||
<span class="string">"prog"</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>
|
||
</div><h4 id='method.hidden' class="method"><code id='hidden.v'>pub 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>) -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a class='srclink' href='../../src/clap/args/arg.rs.html#2344-2350' title='goto source code'>[src]</a></h4><div class='docblock'><p>Hides an argument from help message output.</p>
|
||
<p><strong>NOTE:</strong> Implicitly sets <a href="./struct.Arg.html#method.hidden_short_help"><code>Arg::hidden_short_help(true)</code></a> and <a href="./struct.Arg.html#method.hidden_long_help"><code>Arg::hidden_long_help(true)</code></a>
|
||
when set to true</p>
|
||
<p><strong>NOTE:</strong> This does <strong>not</strong> hide the argument from usage strings on error</p>
|
||
<h1 id="examples-36" class="section-header"><a href="#examples-36">Examples</a></h1>
|
||
<div class="example-wrap"><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="bool-val">true</span>)</pre></div>
|
||
<p>Setting <code>hidden(true)</code> will hide the argument when displaying help text</p>
|
||
|
||
<div class="example-wrap"><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">"prog"</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="bool-val">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">"prog"</span>, <span class="string">"--help"</span>
|
||
]);</pre></div>
|
||
<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 id='possible_values.v'>pub 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>) -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a class='srclink' href='../../src/clap/args/arg.rs.html#2399-2408' title='goto source code'>[src]</a></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 <a href="./struct.Arg.html#method.takes_value">options</a> and <a href="./struct.Arg.html#method.index">positional arguments</a></p>
|
||
<h1 id="examples-37" class="section-header"><a href="#examples-37">Examples</a></h1>
|
||
<div class="example-wrap"><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="bool-val">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></div>
|
||
|
||
<div class="example-wrap"><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">"prog"</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="bool-val">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">"prog"</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>
|
||
<p>The next example shows a failed parse from using a value which wasn't defined as one of the
|
||
possible values.</p>
|
||
|
||
<div class="example-wrap"><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">"prog"</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="bool-val">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">"prog"</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>
|
||
</div><h4 id='method.possible_value' class="method"><code id='possible_value.v'>pub 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>) -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a class='srclink' href='../../src/clap/args/arg.rs.html#2463-2470' title='goto source code'>[src]</a></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>
|
||
<p><strong>NOTE:</strong> This setting only applies to <a href="./struct.Arg.html#method.takes_value">options</a> and <a href="./struct.Arg.html#method.index">positional arguments</a></p>
|
||
<h1 id="examples-38" class="section-header"><a href="#examples-38">Examples</a></h1>
|
||
<div class="example-wrap"><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="bool-val">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></div>
|
||
|
||
<div class="example-wrap"><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">"prog"</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="bool-val">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">"prog"</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>
|
||
<p>The next example shows a failed parse from using a value which wasn't defined as one of the
|
||
possible values.</p>
|
||
|
||
<div class="example-wrap"><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">"prog"</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="bool-val">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">"prog"</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>
|
||
</div><h4 id='method.case_insensitive' class="method"><code id='case_insensitive.v'>pub fn <a href='#method.case_insensitive' class='fnname'>case_insensitive</a>(self, ci: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.bool.html">bool</a>) -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a class='srclink' href='../../src/clap/args/arg.rs.html#2517-2523' title='goto source code'>[src]</a></h4><div class='docblock'><p>When used with <a href="../../structopt/clap/struct.Arg.html#method.possible_values" title="`Arg::possible_values`"><code>Arg::possible_values</code></a> it allows the argument value to pass validation even if
|
||
the case differs from that of the specified <code>possible_value</code>.</p>
|
||
<p><strong>Pro Tip:</strong> Use this setting with <a href="./macro.arg_enum.html"><code>arg_enum!</code></a></p>
|
||
<h1 id="examples-39" class="section-header"><a href="#examples-39">Examples</a></h1>
|
||
<div class="example-wrap"><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">"pv"</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="bool-val">true</span>)
|
||
.<span class="ident">possible_value</span>(<span class="string">"test123"</span>)
|
||
.<span class="ident">case_insensitive</span>(<span class="bool-val">true</span>))
|
||
.<span class="ident">get_matches_from</span>(<span class="macro">vec</span><span class="macro">!</span>[
|
||
<span class="string">"pv"</span>, <span class="string">"--option"</span>, <span class="string">"TeSt123"</span>,
|
||
]);
|
||
|
||
<span class="macro">assert</span><span class="macro">!</span>(<span class="ident">m</span>.<span class="ident">value_of</span>(<span class="string">"option"</span>).<span class="ident">unwrap</span>().<span class="ident">eq_ignore_ascii_case</span>(<span class="string">"test123"</span>));</pre></div>
|
||
<p>This setting also works when multiple values can be defined:</p>
|
||
|
||
<div class="example-wrap"><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">"pv"</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">short</span>(<span class="string">"-o"</span>)
|
||
.<span class="ident">long</span>(<span class="string">"--option"</span>)
|
||
.<span class="ident">takes_value</span>(<span class="bool-val">true</span>)
|
||
.<span class="ident">possible_value</span>(<span class="string">"test123"</span>)
|
||
.<span class="ident">possible_value</span>(<span class="string">"test321"</span>)
|
||
.<span class="ident">multiple</span>(<span class="bool-val">true</span>)
|
||
.<span class="ident">case_insensitive</span>(<span class="bool-val">true</span>))
|
||
.<span class="ident">get_matches_from</span>(<span class="macro">vec</span><span class="macro">!</span>[
|
||
<span class="string">"pv"</span>, <span class="string">"--option"</span>, <span class="string">"TeSt123"</span>, <span class="string">"teST123"</span>, <span class="string">"tESt321"</span>
|
||
]);
|
||
|
||
<span class="kw">let</span> <span class="ident">matched_vals</span> <span class="op">=</span> <span class="ident">m</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="kw">_</span><span class="op">></span><span class="op">></span>();
|
||
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="kw-2">&</span><span class="kw-2">*</span><span class="ident">matched_vals</span>, <span class="kw-2">&</span>[<span class="string">"TeSt123"</span>, <span class="string">"teST123"</span>, <span class="string">"tESt321"</span>]);</pre></div>
|
||
</div><h4 id='method.group' class="method"><code id='group.v'>pub 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>) -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a class='srclink' href='../../src/clap/args/arg.rs.html#2555-2562' title='goto source code'>[src]</a></h4><div class='docblock'><p>Specifies the name of the <a href="./struct.ArgGroup.html"><code>ArgGroup</code></a> the argument belongs to.</p>
|
||
<h1 id="examples-40" class="section-header"><a href="#examples-40">Examples</a></h1>
|
||
<div class="example-wrap"><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></div>
|
||
<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>
|
||
|
||
<div class="example-wrap"><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">"prog"</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">"prog"</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>
|
||
</div><h4 id='method.groups' class="method"><code id='groups.v'>pub fn <a href='#method.groups' class='fnname'>groups</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>) -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a class='srclink' href='../../src/clap/args/arg.rs.html#2595-2604' title='goto source code'>[src]</a></h4><div class='docblock'><p>Specifies the names of multiple <a href="./struct.ArgGroup.html"><code>ArgGroup</code></a>'s the argument belongs to.</p>
|
||
<h1 id="examples-41" class="section-header"><a href="#examples-41">Examples</a></h1>
|
||
<div class="example-wrap"><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">groups</span>(<span class="kw-2">&</span>[<span class="string">"mode"</span>, <span class="string">"verbosity"</span>])</pre></div>
|
||
<p>Arguments can be members of multiple groups and then the group checked as if it
|
||
was one of said arguments.</p>
|
||
|
||
<div class="example-wrap"><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">"prog"</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">groups</span>(<span class="kw-2">&</span>[<span class="string">"mode"</span>, <span class="string">"verbosity"</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">groups</span>(<span class="kw-2">&</span>[<span class="string">"mode"</span>, <span class="string">"verbosity"</span>]))
|
||
.<span class="ident">get_matches_from</span>(<span class="macro">vec</span><span class="macro">!</span>[
|
||
<span class="string">"prog"</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>));
|
||
<span class="macro">assert</span><span class="macro">!</span>(<span class="ident">m</span>.<span class="ident">is_present</span>(<span class="string">"verbosity"</span>));</pre></div>
|
||
</div><h4 id='method.number_of_values' class="method"><code id='number_of_values.v'>pub 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>) -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a class='srclink' href='../../src/clap/args/arg.rs.html#2642-2646' title='goto source code'>[src]</a></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 <a href="./struct.Arg.html#method.multiple"><code>Arg::multiple(true)</code></a> to be set. Setting
|
||
<a href="./struct.Arg.html#method.multiple"><code>Arg::multiple(true)</code></a> would allow <code>-f <file> <file> <file> -f <file> <file> <file></code> where
|
||
as <em>not</em> setting <a href="./struct.Arg.html#method.multiple"><code>Arg::multiple(true)</code></a> would only allow one occurrence of this argument.</p>
|
||
<h1 id="examples-42" class="section-header"><a href="#examples-42">Examples</a></h1>
|
||
<div class="example-wrap"><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></div>
|
||
<p>Not supplying the correct number of values is an error</p>
|
||
|
||
<div class="example-wrap"><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">"prog"</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="bool-val">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">"prog"</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>
|
||
</div><h4 id='method.validator' class="method"><code id='validator.v'>pub fn <a href='#method.validator' class='fnname'>validator</a><F>(self, f: F) -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b> <span class="where fmt-newline">where<br> F: <a class="trait" href="https://doc.rust-lang.org/nightly/core/ops/function/trait.Fn.html" title="trait core::ops::function::Fn">Fn</a>(<a class="struct" href="https://doc.rust-lang.org/nightly/alloc/string/struct.String.html" title="struct alloc::string::String">String</a>) -> <a class="enum" href="https://doc.rust-lang.org/nightly/core/result/enum.Result.html" title="enum core::result::Result">Result</a><<a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.unit.html">()</a>, <a class="struct" href="https://doc.rust-lang.org/nightly/alloc/string/struct.String.html" title="struct alloc::string::String">String</a>> + 'static, </span></code><a class='srclink' href='../../src/clap/args/arg.rs.html#2684-2690' title='goto source code'>[src]</a></h4><div class='docblock'><p>Allows one to perform a custom validation on the argument value. You provide a closure
|
||
which accepts a <a href="https://doc.rust-lang.org/std/string/struct.String.html"><code>String</code></a> value, and return a <a href="https://doc.rust-lang.org/std/result/enum.Result.html"><code>Result</code></a> where the <a href="https://doc.rust-lang.org/std/result/enum.Result.html#variant.Err"><code>Err(String)</code></a> 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 as all errors will appear as
|
||
<code>error: Invalid value for '<arg>': <YOUR MESSAGE></code> where <code><arg></code> is replaced by the actual
|
||
arg, and <code><YOUR MESSAGE></code> is the <code>String</code> you return as the error.</p>
|
||
<p><strong>NOTE:</strong> There is a small performance hit for using validators, as they are implemented
|
||
with <a href="https://doc.rust-lang.org/std/rc/struct.Rc.html"><code>Rc</code></a> 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-43" class="section-header"><a href="#examples-43">Examples</a></h1>
|
||
<div class="example-wrap"><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="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">"prog"</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">"prog"</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>
|
||
</div><h4 id='method.validator_os' class="method"><code id='validator_os.v'>pub fn <a href='#method.validator_os' class='fnname'>validator_os</a><F>(self, f: F) -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b> <span class="where fmt-newline">where<br> F: <a class="trait" href="https://doc.rust-lang.org/nightly/core/ops/function/trait.Fn.html" title="trait core::ops::function::Fn">Fn</a>(&<a class="struct" href="https://doc.rust-lang.org/nightly/std/ffi/os_str/struct.OsStr.html" title="struct std::ffi::os_str::OsStr">OsStr</a>) -> <a class="enum" href="https://doc.rust-lang.org/nightly/core/result/enum.Result.html" title="enum core::result::Result">Result</a><<a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.unit.html">()</a>, <a class="struct" href="https://doc.rust-lang.org/nightly/std/ffi/os_str/struct.OsString.html" title="struct std::ffi::os_str::OsString">OsString</a>> + 'static, </span></code><a class='srclink' href='../../src/clap/args/arg.rs.html#2722-2728' title='goto source code'>[src]</a></h4><div class='docblock'><p>Works identically to Validator but is intended to be used with values that could
|
||
contain non UTF-8 formatted strings.</p>
|
||
<h1 id="examples-44" class="section-header"><a href="#examples-44">Examples</a></h1>
|
||
<div class="example-wrap"><pre class="rust rust-example-rendered">
|
||
<span class="kw">fn</span> <span class="ident">has_ampersand</span>(<span class="ident">v</span>: <span class="kw-2">&</span><span class="ident">OsStr</span>) <span class="op">-</span><span class="op">></span> <span class="prelude-ty">Result</span><span class="op"><</span>(), <span class="ident">OsString</span><span class="op">></span> {
|
||
<span class="kw">if</span> <span class="ident">v</span>.<span class="ident">as_bytes</span>().<span class="ident">iter</span>().<span class="ident">any</span>(<span class="op">|</span><span class="ident">b</span><span class="op">|</span> <span class="kw-2">*</span><span class="ident">b</span> <span class="op">=</span><span class="op">=</span> <span class="string">b'&'</span>) { <span class="kw">return</span> <span class="prelude-val">Ok</span>(()); }
|
||
<span class="prelude-val">Err</span>(<span class="ident">OsString</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">"prog"</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_os</span>(<span class="ident">has_ampersand</span>))
|
||
.<span class="ident">get_matches_from_safe</span>(<span class="macro">vec</span><span class="macro">!</span>[
|
||
<span class="string">"prog"</span>, <span class="string">"Fish & chips"</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">"Fish & chips"</span>));</pre></div>
|
||
</div><h4 id='method.max_values' class="method"><code id='max_values.v'>pub 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>) -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a class='srclink' href='../../src/clap/args/arg.rs.html#2786-2790' title='goto source code'>[src]</a></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 <em>not</em> implicitly set <a href="./struct.Arg.html#method.multiple"><code>Arg::multiple(true)</code></a>. This is because
|
||
<code>-o val -o val</code> is multiple occurrences but a single value and <code>-o val1 val2</code> is a single
|
||
occurrence with multiple values. For positional arguments this <strong>does</strong> set
|
||
<a href="./struct.Arg.html#method.multiple"><code>Arg::multiple(true)</code></a> because there is no way to determine the difference between multiple
|
||
occurrences and multiple values.</p>
|
||
<h1 id="examples-45" class="section-header"><a href="#examples-45">Examples</a></h1>
|
||
<div class="example-wrap"><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></div>
|
||
<p>Supplying less than the maximum number of values is allowed</p>
|
||
|
||
<div class="example-wrap"><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">"prog"</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="bool-val">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">"prog"</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="kw">_</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></div>
|
||
<p>Supplying more than the maximum number of values is an error</p>
|
||
|
||
<div class="example-wrap"><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">"prog"</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="bool-val">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">"prog"</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>
|
||
</div><h4 id='method.min_values' class="method"><code id='min_values.v'>pub 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>) -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a class='srclink' href='../../src/clap/args/arg.rs.html#2849-2852' title='goto source code'>[src]</a></h4><div class='docblock'><p>Specifies the <em>minimum</em> number of values 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 <a href="./struct.Arg.html#method.multiple"><code>Arg::multiple(true)</code></a>. This is because
|
||
<code>-o val -o val</code> is multiple occurrences but a single value and <code>-o val1 val2</code> is a single
|
||
occurrence with multiple values. For positional arguments this <strong>does</strong> set
|
||
<a href="./struct.Arg.html#method.multiple"><code>Arg::multiple(true)</code></a> because there is no way to determine the difference between multiple
|
||
occurrences and multiple values.</p>
|
||
<h1 id="examples-46" class="section-header"><a href="#examples-46">Examples</a></h1>
|
||
<div class="example-wrap"><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></div>
|
||
<p>Supplying more than the minimum number of values is allowed</p>
|
||
|
||
<div class="example-wrap"><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">"prog"</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="bool-val">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">"prog"</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="kw">_</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></div>
|
||
<p>Supplying less than the minimum number of values is an error</p>
|
||
|
||
<div class="example-wrap"><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">"prog"</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="bool-val">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">"prog"</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>
|
||
</div><h4 id='method.use_delimiter' class="method"><code id='use_delimiter.v'>pub 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>) -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a class='srclink' href='../../src/clap/args/arg.rs.html#2900-2913' title='goto source code'>[src]</a></h4><div class='docblock'><p>Specifies whether or not an argument should allow grouping of multiple values via a
|
||
delimiter. I.e. should <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 default is <code>false</code>. When set to <code>true</code> the default <a href="./struct.Arg.html#method.value_delimiter"><code>Arg::value_delimiter</code></a>
|
||
is the comma <code>,</code>.</p>
|
||
<h1 id="examples-47" class="section-header"><a href="#examples-47">Examples</a></h1>
|
||
<p>The following example shows the default behavior.</p>
|
||
|
||
<div class="example-wrap"><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">"prog"</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="bool-val">true</span>)
|
||
.<span class="ident">takes_value</span>(<span class="bool-val">true</span>))
|
||
.<span class="ident">get_matches_from</span>(<span class="macro">vec</span><span class="macro">!</span>[
|
||
<span class="string">"prog"</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="kw">_</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>
|
||
<p>The next example shows the difference when turning delimiters off. This is the default
|
||
behavior</p>
|
||
|
||
<div class="example-wrap"><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">"prog"</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="bool-val">false</span>)
|
||
.<span class="ident">takes_value</span>(<span class="bool-val">true</span>))
|
||
.<span class="ident">get_matches_from</span>(<span class="macro">vec</span><span class="macro">!</span>[
|
||
<span class="string">"prog"</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>
|
||
</div><h4 id='method.require_delimiter' class="method"><code id='require_delimiter.v'>pub fn <a href='#method.require_delimiter' class='fnname'>require_delimiter</a>(self, d: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.bool.html">bool</a>) -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a class='srclink' href='../../src/clap/args/arg.rs.html#2987-2998' title='goto source code'>[src]</a></h4><div class='docblock'><p>Specifies that <em>multiple values</em> may only be set using the delimiter. This means if an
|
||
if an option is encountered, and no delimiter is found, it automatically assumed that no
|
||
additional values for that option follow. This is unlike the default, where it is generally
|
||
assumed that more values will follow regardless of whether or not a delimiter is used.</p>
|
||
<p><strong>NOTE:</strong> The default is <code>false</code>.</p>
|
||
<p><strong>NOTE:</strong> Setting this to true implies <a href="./struct.Arg.html#method.use_delimiter"><code>Arg::use_delimiter(true)</code></a></p>
|
||
<p><strong>NOTE:</strong> It's a good idea to inform the user that use of a delimiter is required, either
|
||
through help text or other means.</p>
|
||
<h1 id="examples-48" class="section-header"><a href="#examples-48">Examples</a></h1>
|
||
<p>These examples demonstrate what happens when <code>require_delimiter(true)</code> is used. Notice
|
||
everything works in this first example, as we use a delimiter, as expected.</p>
|
||
|
||
<div class="example-wrap"><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">"prog"</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">short</span>(<span class="string">"o"</span>)
|
||
.<span class="ident">takes_value</span>(<span class="bool-val">true</span>)
|
||
.<span class="ident">multiple</span>(<span class="bool-val">true</span>)
|
||
.<span class="ident">require_delimiter</span>(<span class="bool-val">true</span>))
|
||
.<span class="ident">get_matches_from</span>(<span class="macro">vec</span><span class="macro">!</span>[
|
||
<span class="string">"prog"</span>, <span class="string">"-o"</span>, <span class="string">"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">"opt"</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">"opt"</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="kw">_</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>
|
||
<p>In this next example, we will <em>not</em> use a delimiter. Notice it's now an error.</p>
|
||
|
||
<div class="example-wrap"><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">"prog"</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">short</span>(<span class="string">"o"</span>)
|
||
.<span class="ident">takes_value</span>(<span class="bool-val">true</span>)
|
||
.<span class="ident">multiple</span>(<span class="bool-val">true</span>)
|
||
.<span class="ident">require_delimiter</span>(<span class="bool-val">true</span>))
|
||
.<span class="ident">get_matches_from_safe</span>(<span class="macro">vec</span><span class="macro">!</span>[
|
||
<span class="string">"prog"</span>, <span class="string">"-o"</span>, <span class="string">"val1"</span>, <span class="string">"val2"</span>, <span class="string">"val3"</span>,
|
||
]);
|
||
|
||
<span class="macro">assert</span><span class="macro">!</span>(<span class="ident">res</span>.<span class="ident">is_err</span>());
|
||
<span class="kw">let</span> <span class="ident">err</span> <span class="op">=</span> <span class="ident">res</span>.<span class="ident">unwrap_err</span>();
|
||
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">err</span>.<span class="ident">kind</span>, <span class="ident">ErrorKind</span>::<span class="ident">UnknownArgument</span>);</pre></div>
|
||
<p>What's happening is <code>-o</code> is getting <code>val1</code>, and because delimiters are required yet none
|
||
were present, it stops parsing <code>-o</code>. At this point it reaches <code>val2</code> and because no
|
||
positional arguments have been defined, it's an error of an unexpected argument.</p>
|
||
<p>In this final example, we contrast the above with <code>clap</code>'s default behavior where the above
|
||
is <em>not</em> an error.</p>
|
||
|
||
<div class="example-wrap"><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">"prog"</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">short</span>(<span class="string">"o"</span>)
|
||
.<span class="ident">takes_value</span>(<span class="bool-val">true</span>)
|
||
.<span class="ident">multiple</span>(<span class="bool-val">true</span>))
|
||
.<span class="ident">get_matches_from</span>(<span class="macro">vec</span><span class="macro">!</span>[
|
||
<span class="string">"prog"</span>, <span class="string">"-o"</span>, <span class="string">"val1"</span>, <span class="string">"val2"</span>, <span class="string">"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">"opt"</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">"opt"</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="kw">_</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>
|
||
</div><h4 id='method.value_delimiter' class="method"><code id='value_delimiter.v'>pub 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>) -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a class='srclink' href='../../src/clap/args/arg.rs.html#3023-3033' title='goto source code'>[src]</a></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 <a href="./struct.Arg.html#method.use_delimiter"><code>Arg::use_delimiter(true)</code></a></p>
|
||
<p><strong>NOTE:</strong> implicitly sets <a href="./struct.Arg.html#method.takes_value"><code>Arg::takes_value(true)</code></a></p>
|
||
<h1 id="examples-49" class="section-header"><a href="#examples-49">Examples</a></h1>
|
||
<div class="example-wrap"><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">"prog"</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="ident">get_matches_from</span>(<span class="macro">vec</span><span class="macro">!</span>[
|
||
<span class="string">"prog"</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="kw">_</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>
|
||
</div><h4 id='method.value_names' class="method"><code id='value_names.v'>pub 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>) -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a class='srclink' href='../../src/clap/args/arg.rs.html#3094-3114' title='goto source code'>[src]</a></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 <a href="./struct.Arg.html#method.next_line_help"><code>Arg::next_line_help(true)</code></a> 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 <a href="./struct.Arg.html#method.number_of_values"><code>Arg::number_of_values</code></a> 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 <a href="./struct.Arg.html#method.takes_value"><code>Arg::takes_value(true)</code></a></p>
|
||
<p><strong>NOTE:</strong> Does <em>not</em> require or imply <a href="./struct.Arg.html#method.multiple"><code>Arg::multiple(true)</code></a>.</p>
|
||
<h1 id="examples-50" class="section-header"><a href="#examples-50">Examples</a></h1>
|
||
<div class="example-wrap"><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></div>
|
||
|
||
<div class="example-wrap"><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">"prog"</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">"prog"</span>, <span class="string">"--help"</span>
|
||
]);</pre></div>
|
||
<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 id='value_name.v'>pub 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>) -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a class='srclink' href='../../src/clap/args/arg.rs.html#3162-3173' title='goto source code'>[src]</a></h4><div class='docblock'><p>Specifies the name for value of <a href="./struct.Arg.html#method.takes_value">option</a> or <a href="./struct.Arg.html#method.index">positional</a> arguments inside of help
|
||
documentation. 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 <a href="./struct.Arg.html#method.takes_value"><code>Arg::takes_value(true)</code></a></p>
|
||
<h1 id="examples-51" class="section-header"><a href="#examples-51">Examples</a></h1>
|
||
<div class="example-wrap"><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></div>
|
||
|
||
<div class="example-wrap"><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">"prog"</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">"prog"</span>, <span class="string">"--help"</span>
|
||
]);</pre></div>
|
||
<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 id='default_value.v'>pub 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>) -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a class='srclink' href='../../src/clap/args/arg.rs.html#3238-3240' title='goto source code'>[src]</a></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, <a href="./struct.ArgMatches.html#method.occurrences_of"><code>ArgMatches::occurrences_of</code></a>
|
||
will return <code>0</code> even though the <a href="./struct.ArgMatches.html#method.value_of"><code>ArgMatches::value_of</code></a> will return the default specified.</p>
|
||
<p><strong>NOTE:</strong> If the user <em>does not</em> use this argument at runtime <a href="./struct.ArgMatches.html#method.is_present"><code>ArgMatches::is_present</code></a> will
|
||
still return <code>true</code>. If you wish to determine whether the argument was used at runtime or
|
||
not, consider <a href="./struct.ArgMatches.html#method.occurrences_of"><code>ArgMatches::occurrences_of</code></a> which will return <code>0</code> if the argument was <em>not</em>
|
||
used at runtime.</p>
|
||
<p><strong>NOTE:</strong> This setting is perfectly compatible with <a href="./struct.Arg.html#method.default_value_if"><code>Arg::default_value_if</code></a> but slightly
|
||
different. <code>Arg::default_value</code> <em>only</em> takes affect when the user has not provided this arg
|
||
at runtime. <code>Arg::default_value_if</code> however only takes affect when the user has not provided
|
||
a value at runtime <strong>and</strong> these other conditions are met as well. If you have set
|
||
<code>Arg::default_value</code> and <code>Arg::default_value_if</code>, and the user <strong>did not</strong> provide a this
|
||
arg at runtime, nor did were the conditions met for <code>Arg::default_value_if</code>, the
|
||
<code>Arg::default_value</code> will be applied.</p>
|
||
<p><strong>NOTE:</strong> This implicitly sets <a href="./struct.Arg.html#method.takes_value"><code>Arg::takes_value(true)</code></a>.</p>
|
||
<p><strong>NOTE:</strong> This setting effectively disables <code>AppSettings::ArgRequiredElseHelp</code> if used in
|
||
conjunction as it ensures that some argument will always be present.</p>
|
||
<h1 id="examples-52" class="section-header"><a href="#examples-52">Examples</a></h1>
|
||
<p>First we use the default value without providing any value at runtime.</p>
|
||
|
||
<div class="example-wrap"><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">"prog"</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">"prog"</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>
|
||
<p>Next we provide a value at runtime to override the default.</p>
|
||
|
||
<div class="example-wrap"><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">"prog"</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">"prog"</span>, <span class="string">"--myopt=non_default"</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">"non_default"</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">1</span>);</pre></div>
|
||
</div><h4 id='method.default_value_os' class="method"><code id='default_value_os.v'>pub fn <a href='#method.default_value_os' class='fnname'>default_value_os</a>(self, val: &'a <a class="struct" href="https://doc.rust-lang.org/nightly/std/ffi/os_str/struct.OsStr.html" title="struct std::ffi::os_str::OsStr">OsStr</a>) -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a class='srclink' href='../../src/clap/args/arg.rs.html#3246-3250' title='goto source code'>[src]</a></h4><div class='docblock'><p>Provides a default value in the exact same manner as <a href="../../structopt/clap/struct.Arg.html#method.default_value" title="`Arg::default_value`"><code>Arg::default_value</code></a>
|
||
only using [<code>OsStr</code>]s instead.
|
||
<a href="../../structopt/clap/struct.Arg.html#method.default_value" title="`Arg::default_value`"><code>Arg::default_value</code></a>: ./struct.Arg.html#method.default_value
|
||
[<code>OsStr</code>]: https://doc.rust-lang.org/std/ffi/struct.OsStr.html</p>
|
||
</div><h4 id='method.default_value_if' class="method"><code id='default_value_if.v'>pub fn <a href='#method.default_value_if' class='fnname'>default_value_if</a>(<br> self, <br> arg: &'a <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.str.html">str</a>, <br> val: <a class="enum" href="https://doc.rust-lang.org/nightly/core/option/enum.Option.html" title="enum core::option::Option">Option</a><&'b <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.str.html">str</a>>, <br> default: &'b <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.str.html">str</a><br>) -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a class='srclink' href='../../src/clap/args/arg.rs.html#3348-3354' title='goto source code'>[src]</a></h4><div class='docblock'><p>Specifies the value of the argument if <code>arg</code> has been used at runtime. If <code>val</code> is set to
|
||
<code>None</code>, <code>arg</code> only needs to be present. If <code>val</code> is set to <code>"some-val"</code> then <code>arg</code> must be
|
||
present at runtime <strong>and</strong> have the value <code>val</code>.</p>
|
||
<p><strong>NOTE:</strong> This setting is perfectly compatible with <a href="./struct.Arg.html#method.default_value"><code>Arg::default_value</code></a> but slightly
|
||
different. <code>Arg::default_value</code> <em>only</em> takes affect when the user has not provided this arg
|
||
at runtime. This setting however only takes affect when the user has not provided a value at
|
||
runtime <strong>and</strong> these other conditions are met as well. If you have set <code>Arg::default_value</code>
|
||
and <code>Arg::default_value_if</code>, and the user <strong>did not</strong> provide a this arg at runtime, nor did
|
||
were the conditions met for <code>Arg::default_value_if</code>, the <code>Arg::default_value</code> will be
|
||
applied.</p>
|
||
<p><strong>NOTE:</strong> This implicitly sets <a href="./struct.Arg.html#method.takes_value"><code>Arg::takes_value(true)</code></a>.</p>
|
||
<p><strong>NOTE:</strong> If using YAML the values should be laid out as follows (<code>None</code> can be represented
|
||
as <code>null</code> in YAML)</p>
|
||
<pre><code class="language-yaml">default_value_if:
|
||
- [arg, val, default]
|
||
</code></pre>
|
||
<h1 id="examples-53" class="section-header"><a href="#examples-53">Examples</a></h1>
|
||
<p>First we use the default value only if another arg is present at runtime.</p>
|
||
|
||
<div class="example-wrap"><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">"prog"</span>)
|
||
.<span class="ident">arg</span>(<span class="ident">Arg</span>::<span class="ident">with_name</span>(<span class="string">"flag"</span>)
|
||
.<span class="ident">long</span>(<span class="string">"flag"</span>))
|
||
.<span class="ident">arg</span>(<span class="ident">Arg</span>::<span class="ident">with_name</span>(<span class="string">"other"</span>)
|
||
.<span class="ident">long</span>(<span class="string">"other"</span>)
|
||
.<span class="ident">default_value_if</span>(<span class="string">"flag"</span>, <span class="prelude-val">None</span>, <span class="string">"default"</span>))
|
||
.<span class="ident">get_matches_from</span>(<span class="macro">vec</span><span class="macro">!</span>[
|
||
<span class="string">"prog"</span>, <span class="string">"--flag"</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">"other"</span>), <span class="prelude-val">Some</span>(<span class="string">"default"</span>));</pre></div>
|
||
<p>Next we run the same test, but without providing <code>--flag</code>.</p>
|
||
|
||
<div class="example-wrap"><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">"prog"</span>)
|
||
.<span class="ident">arg</span>(<span class="ident">Arg</span>::<span class="ident">with_name</span>(<span class="string">"flag"</span>)
|
||
.<span class="ident">long</span>(<span class="string">"flag"</span>))
|
||
.<span class="ident">arg</span>(<span class="ident">Arg</span>::<span class="ident">with_name</span>(<span class="string">"other"</span>)
|
||
.<span class="ident">long</span>(<span class="string">"other"</span>)
|
||
.<span class="ident">default_value_if</span>(<span class="string">"flag"</span>, <span class="prelude-val">None</span>, <span class="string">"default"</span>))
|
||
.<span class="ident">get_matches_from</span>(<span class="macro">vec</span><span class="macro">!</span>[
|
||
<span class="string">"prog"</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">"other"</span>), <span class="prelude-val">None</span>);</pre></div>
|
||
<p>Now lets only use the default value if <code>--opt</code> contains the value <code>special</code>.</p>
|
||
|
||
<div class="example-wrap"><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">"prog"</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">takes_value</span>(<span class="bool-val">true</span>)
|
||
.<span class="ident">long</span>(<span class="string">"opt"</span>))
|
||
.<span class="ident">arg</span>(<span class="ident">Arg</span>::<span class="ident">with_name</span>(<span class="string">"other"</span>)
|
||
.<span class="ident">long</span>(<span class="string">"other"</span>)
|
||
.<span class="ident">default_value_if</span>(<span class="string">"opt"</span>, <span class="prelude-val">Some</span>(<span class="string">"special"</span>), <span class="string">"default"</span>))
|
||
.<span class="ident">get_matches_from</span>(<span class="macro">vec</span><span class="macro">!</span>[
|
||
<span class="string">"prog"</span>, <span class="string">"--opt"</span>, <span class="string">"special"</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">"other"</span>), <span class="prelude-val">Some</span>(<span class="string">"default"</span>));</pre></div>
|
||
<p>We can run the same test and provide any value <em>other than</em> <code>special</code> and we won't get a
|
||
default value.</p>
|
||
|
||
<div class="example-wrap"><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">"prog"</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">takes_value</span>(<span class="bool-val">true</span>)
|
||
.<span class="ident">long</span>(<span class="string">"opt"</span>))
|
||
.<span class="ident">arg</span>(<span class="ident">Arg</span>::<span class="ident">with_name</span>(<span class="string">"other"</span>)
|
||
.<span class="ident">long</span>(<span class="string">"other"</span>)
|
||
.<span class="ident">default_value_if</span>(<span class="string">"opt"</span>, <span class="prelude-val">Some</span>(<span class="string">"special"</span>), <span class="string">"default"</span>))
|
||
.<span class="ident">get_matches_from</span>(<span class="macro">vec</span><span class="macro">!</span>[
|
||
<span class="string">"prog"</span>, <span class="string">"--opt"</span>, <span class="string">"hahaha"</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">"other"</span>), <span class="prelude-val">None</span>);</pre></div>
|
||
</div><h4 id='method.default_value_if_os' class="method"><code id='default_value_if_os.v'>pub fn <a href='#method.default_value_if_os' class='fnname'>default_value_if_os</a>(<br> self, <br> arg: &'a <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.str.html">str</a>, <br> val: <a class="enum" href="https://doc.rust-lang.org/nightly/core/option/enum.Option.html" title="enum core::option::Option">Option</a><&'b <a class="struct" href="https://doc.rust-lang.org/nightly/std/ffi/os_str/struct.OsStr.html" title="struct std::ffi::os_str::OsStr">OsStr</a>>, <br> default: &'b <a class="struct" href="https://doc.rust-lang.org/nightly/std/ffi/os_str/struct.OsStr.html" title="struct std::ffi::os_str::OsStr">OsStr</a><br>) -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a class='srclink' href='../../src/clap/args/arg.rs.html#3360-3376' title='goto source code'>[src]</a></h4><div class='docblock'><p>Provides a conditional default value in the exact same manner as <a href="../../structopt/clap/struct.Arg.html#method.default_value_if" title="`Arg::default_value_if`"><code>Arg::default_value_if</code></a>
|
||
only using [<code>OsStr</code>]s instead.
|
||
<a href="../../structopt/clap/struct.Arg.html#method.default_value_if" title="`Arg::default_value_if`"><code>Arg::default_value_if</code></a>: ./struct.Arg.html#method.default_value_if
|
||
[<code>OsStr</code>]: https://doc.rust-lang.org/std/ffi/struct.OsStr.html</p>
|
||
</div><h4 id='method.default_value_ifs' class="method"><code id='default_value_ifs.v'>pub fn <a href='#method.default_value_ifs' class='fnname'>default_value_ifs</a>(<br> self, <br> ifs: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.slice.html">&[</a><a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.tuple.html">(</a>&'a <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.str.html">str</a>, <a class="enum" href="https://doc.rust-lang.org/nightly/core/option/enum.Option.html" title="enum core::option::Option">Option</a><&'b <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.str.html">str</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.tuple.html">)</a><a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.slice.html">]</a><br>) -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a class='srclink' href='../../src/clap/args/arg.rs.html#3462-3471' title='goto source code'>[src]</a></h4><div class='docblock'><p>Specifies multiple values and conditions in the same manner as <a href="../../structopt/clap/struct.Arg.html#method.default_value_if" title="`Arg::default_value_if`"><code>Arg::default_value_if</code></a>.
|
||
The method takes a slice of tuples in the <code>(arg, Option<val>, default)</code> format.</p>
|
||
<p><strong>NOTE</strong>: The conditions are stored in order and evaluated in the same order. I.e. the first
|
||
if multiple conditions are true, the first one found will be applied and the ultimate value.</p>
|
||
<p><strong>NOTE:</strong> If using YAML the values should be laid out as follows</p>
|
||
<pre><code class="language-yaml">default_value_if:
|
||
- [arg, val, default]
|
||
- [arg2, null, default2]
|
||
</code></pre>
|
||
<h1 id="examples-54" class="section-header"><a href="#examples-54">Examples</a></h1>
|
||
<p>First we use the default value only if another arg is present at runtime.</p>
|
||
|
||
<div class="example-wrap"><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">"prog"</span>)
|
||
.<span class="ident">arg</span>(<span class="ident">Arg</span>::<span class="ident">with_name</span>(<span class="string">"flag"</span>)
|
||
.<span class="ident">long</span>(<span class="string">"flag"</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">"opt"</span>)
|
||
.<span class="ident">takes_value</span>(<span class="bool-val">true</span>))
|
||
.<span class="ident">arg</span>(<span class="ident">Arg</span>::<span class="ident">with_name</span>(<span class="string">"other"</span>)
|
||
.<span class="ident">long</span>(<span class="string">"other"</span>)
|
||
.<span class="ident">default_value_ifs</span>(<span class="kw-2">&</span>[
|
||
(<span class="string">"flag"</span>, <span class="prelude-val">None</span>, <span class="string">"default"</span>),
|
||
(<span class="string">"opt"</span>, <span class="prelude-val">Some</span>(<span class="string">"channal"</span>), <span class="string">"chan"</span>),
|
||
]))
|
||
.<span class="ident">get_matches_from</span>(<span class="macro">vec</span><span class="macro">!</span>[
|
||
<span class="string">"prog"</span>, <span class="string">"--opt"</span>, <span class="string">"channal"</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">"other"</span>), <span class="prelude-val">Some</span>(<span class="string">"chan"</span>));</pre></div>
|
||
<p>Next we run the same test, but without providing <code>--flag</code>.</p>
|
||
|
||
<div class="example-wrap"><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">"prog"</span>)
|
||
.<span class="ident">arg</span>(<span class="ident">Arg</span>::<span class="ident">with_name</span>(<span class="string">"flag"</span>)
|
||
.<span class="ident">long</span>(<span class="string">"flag"</span>))
|
||
.<span class="ident">arg</span>(<span class="ident">Arg</span>::<span class="ident">with_name</span>(<span class="string">"other"</span>)
|
||
.<span class="ident">long</span>(<span class="string">"other"</span>)
|
||
.<span class="ident">default_value_ifs</span>(<span class="kw-2">&</span>[
|
||
(<span class="string">"flag"</span>, <span class="prelude-val">None</span>, <span class="string">"default"</span>),
|
||
(<span class="string">"opt"</span>, <span class="prelude-val">Some</span>(<span class="string">"channal"</span>), <span class="string">"chan"</span>),
|
||
]))
|
||
.<span class="ident">get_matches_from</span>(<span class="macro">vec</span><span class="macro">!</span>[
|
||
<span class="string">"prog"</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">"other"</span>), <span class="prelude-val">None</span>);</pre></div>
|
||
<p>We can also see that these values are applied in order, and if more than one condition is
|
||
true, only the first evaluated "wins"</p>
|
||
|
||
<div class="example-wrap"><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">"prog"</span>)
|
||
.<span class="ident">arg</span>(<span class="ident">Arg</span>::<span class="ident">with_name</span>(<span class="string">"flag"</span>)
|
||
.<span class="ident">long</span>(<span class="string">"flag"</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">"opt"</span>)
|
||
.<span class="ident">takes_value</span>(<span class="bool-val">true</span>))
|
||
.<span class="ident">arg</span>(<span class="ident">Arg</span>::<span class="ident">with_name</span>(<span class="string">"other"</span>)
|
||
.<span class="ident">long</span>(<span class="string">"other"</span>)
|
||
.<span class="ident">default_value_ifs</span>(<span class="kw-2">&</span>[
|
||
(<span class="string">"flag"</span>, <span class="prelude-val">None</span>, <span class="string">"default"</span>),
|
||
(<span class="string">"opt"</span>, <span class="prelude-val">Some</span>(<span class="string">"channal"</span>), <span class="string">"chan"</span>),
|
||
]))
|
||
.<span class="ident">get_matches_from</span>(<span class="macro">vec</span><span class="macro">!</span>[
|
||
<span class="string">"prog"</span>, <span class="string">"--opt"</span>, <span class="string">"channal"</span>, <span class="string">"--flag"</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">"other"</span>), <span class="prelude-val">Some</span>(<span class="string">"default"</span>));</pre></div>
|
||
</div><h4 id='method.default_value_ifs_os' class="method"><code id='default_value_ifs_os.v'>pub fn <a href='#method.default_value_ifs_os' class='fnname'>default_value_ifs_os</a>(<br> self, <br> ifs: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.slice.html">&[</a><a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.tuple.html">(</a>&'a <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.str.html">str</a>, <a class="enum" href="https://doc.rust-lang.org/nightly/core/option/enum.Option.html" title="enum core::option::Option">Option</a><&'b <a class="struct" href="https://doc.rust-lang.org/nightly/std/ffi/os_str/struct.OsStr.html" title="struct std::ffi::os_str::OsStr">OsStr</a>>, &'b <a class="struct" href="https://doc.rust-lang.org/nightly/std/ffi/os_str/struct.OsStr.html" title="struct std::ffi::os_str::OsStr">OsStr</a><a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.tuple.html">)</a><a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.slice.html">]</a><br>) -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a class='srclink' href='../../src/clap/args/arg.rs.html#3478-3483' title='goto source code'>[src]</a></h4><div class='docblock'><p>Provides multiple conditional default values in the exact same manner as
|
||
<a href="../../structopt/clap/struct.Arg.html#method.default_value_ifs" title="`Arg::default_value_ifs`"><code>Arg::default_value_ifs</code></a> only using [<code>OsStr</code>]s instead.
|
||
<a href="../../structopt/clap/struct.Arg.html#method.default_value_ifs" title="`Arg::default_value_ifs`"><code>Arg::default_value_ifs</code></a>: ./struct.Arg.html#method.default_value_ifs
|
||
[<code>OsStr</code>]: https://doc.rust-lang.org/std/ffi/struct.OsStr.html</p>
|
||
</div><h4 id='method.env' class="method"><code id='env.v'>pub fn <a href='#method.env' class='fnname'>env</a>(self, name: &'a <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.str.html">str</a>) -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a class='srclink' href='../../src/clap/args/arg.rs.html#3590-3592' title='goto source code'>[src]</a></h4><div class='docblock'><p>Specifies that if the value is not passed in as an argument, that it should be retrieved
|
||
from the environment, if available. If it is not present in the environment, then default
|
||
rules will apply.</p>
|
||
<p><strong>NOTE:</strong> If the user <em>does not</em> use this argument at runtime, <a href="./struct.ArgMatches.html#method.occurrences_of"><code>ArgMatches::occurrences_of</code></a>
|
||
will return <code>0</code> even though the <a href="./struct.ArgMatches.html#method.value_of"><code>ArgMatches::value_of</code></a> will return the default specified.</p>
|
||
<p><strong>NOTE:</strong> If the user <em>does not</em> use this argument at runtime <a href="./struct.ArgMatches.html#method.is_present"><code>ArgMatches::is_present</code></a> will
|
||
return <code>true</code> if the variable is present in the environment . If you wish to determine whether
|
||
the argument was used at runtime or not, consider <a href="./struct.ArgMatches.html#method.occurrences_of"><code>ArgMatches::occurrences_of</code></a> which will
|
||
return <code>0</code> if the argument was <em>not</em> used at runtime.</p>
|
||
<p><strong>NOTE:</strong> This implicitly sets <a href="./struct.Arg.html#method.takes_value"><code>Arg::takes_value(true)</code></a>.</p>
|
||
<p><strong>NOTE:</strong> If <a href="./struct.Arg.html#method.multiple"><code>Arg::multiple(true)</code></a> is set then <a href="./struct.Arg.html#method.use_delimiter"><code>Arg::use_delimiter(true)</code></a> should also be
|
||
set. Otherwise, only a single argument will be returned from the environment variable. The
|
||
default delimiter is <code>,</code> and follows all the other delimiter rules.</p>
|
||
<h1 id="examples-55" class="section-header"><a href="#examples-55">Examples</a></h1>
|
||
<p>In this example, we show the variable coming from the environment:</p>
|
||
|
||
<div class="example-wrap"><pre class="rust rust-example-rendered">
|
||
|
||
<span class="ident">env</span>::<span class="ident">set_var</span>(<span class="string">"MY_FLAG"</span>, <span class="string">"env"</span>);
|
||
|
||
<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">"prog"</span>)
|
||
.<span class="ident">arg</span>(<span class="ident">Arg</span>::<span class="ident">with_name</span>(<span class="string">"flag"</span>)
|
||
.<span class="ident">long</span>(<span class="string">"flag"</span>)
|
||
.<span class="ident">env</span>(<span class="string">"MY_FLAG"</span>))
|
||
.<span class="ident">get_matches_from</span>(<span class="macro">vec</span><span class="macro">!</span>[
|
||
<span class="string">"prog"</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">"flag"</span>), <span class="prelude-val">Some</span>(<span class="string">"env"</span>));</pre></div>
|
||
<p>In this example, we show the variable coming from an option on the CLI:</p>
|
||
|
||
<div class="example-wrap"><pre class="rust rust-example-rendered">
|
||
|
||
<span class="ident">env</span>::<span class="ident">set_var</span>(<span class="string">"MY_FLAG"</span>, <span class="string">"env"</span>);
|
||
|
||
<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">"prog"</span>)
|
||
.<span class="ident">arg</span>(<span class="ident">Arg</span>::<span class="ident">with_name</span>(<span class="string">"flag"</span>)
|
||
.<span class="ident">long</span>(<span class="string">"flag"</span>)
|
||
.<span class="ident">env</span>(<span class="string">"MY_FLAG"</span>))
|
||
.<span class="ident">get_matches_from</span>(<span class="macro">vec</span><span class="macro">!</span>[
|
||
<span class="string">"prog"</span>, <span class="string">"--flag"</span>, <span class="string">"opt"</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">"flag"</span>), <span class="prelude-val">Some</span>(<span class="string">"opt"</span>));</pre></div>
|
||
<p>In this example, we show the variable coming from the environment even with the
|
||
presence of a default:</p>
|
||
|
||
<div class="example-wrap"><pre class="rust rust-example-rendered">
|
||
|
||
<span class="ident">env</span>::<span class="ident">set_var</span>(<span class="string">"MY_FLAG"</span>, <span class="string">"env"</span>);
|
||
|
||
<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">"prog"</span>)
|
||
.<span class="ident">arg</span>(<span class="ident">Arg</span>::<span class="ident">with_name</span>(<span class="string">"flag"</span>)
|
||
.<span class="ident">long</span>(<span class="string">"flag"</span>)
|
||
.<span class="ident">env</span>(<span class="string">"MY_FLAG"</span>)
|
||
.<span class="ident">default_value</span>(<span class="string">"default"</span>))
|
||
.<span class="ident">get_matches_from</span>(<span class="macro">vec</span><span class="macro">!</span>[
|
||
<span class="string">"prog"</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">"flag"</span>), <span class="prelude-val">Some</span>(<span class="string">"env"</span>));</pre></div>
|
||
<p>In this example, we show the use of multiple values in a single environment variable:</p>
|
||
|
||
<div class="example-wrap"><pre class="rust rust-example-rendered">
|
||
|
||
<span class="ident">env</span>::<span class="ident">set_var</span>(<span class="string">"MY_FLAG_MULTI"</span>, <span class="string">"env1,env2"</span>);
|
||
|
||
<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">"prog"</span>)
|
||
.<span class="ident">arg</span>(<span class="ident">Arg</span>::<span class="ident">with_name</span>(<span class="string">"flag"</span>)
|
||
.<span class="ident">long</span>(<span class="string">"flag"</span>)
|
||
.<span class="ident">env</span>(<span class="string">"MY_FLAG_MULTI"</span>)
|
||
.<span class="ident">multiple</span>(<span class="bool-val">true</span>)
|
||
.<span class="ident">use_delimiter</span>(<span class="bool-val">true</span>))
|
||
.<span class="ident">get_matches_from</span>(<span class="macro">vec</span><span class="macro">!</span>[
|
||
<span class="string">"prog"</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">"flag"</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="kw">_</span><span class="op">></span><span class="op">></span>(), <span class="macro">vec</span><span class="macro">!</span>[<span class="string">"env1"</span>, <span class="string">"env2"</span>]);</pre></div>
|
||
</div><h4 id='method.env_os' class="method"><code id='env_os.v'>pub fn <a href='#method.env_os' class='fnname'>env_os</a>(self, name: &'a <a class="struct" href="https://doc.rust-lang.org/nightly/std/ffi/os_str/struct.OsStr.html" title="struct std::ffi::os_str::OsStr">OsStr</a>) -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a class='srclink' href='../../src/clap/args/arg.rs.html#3597-3602' title='goto source code'>[src]</a></h4><div class='docblock'><p>Specifies that if the value is not passed in as an argument, that it should be retrieved
|
||
from the environment if available in the exact same manner as <a href="../../structopt/clap/struct.Arg.html#method.env" title="`Arg::env`"><code>Arg::env</code></a> only using
|
||
[<code>OsStr</code>]s instead.</p>
|
||
</div><h4 id='method.hide_env_values' class="method"><code id='hide_env_values.v'>pub fn <a href='#method.hide_env_values' class='fnname'>hide_env_values</a>(self, hide: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.bool.html">bool</a>) -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a class='srclink' href='../../src/clap/args/arg.rs.html#3605-3611' title='goto source code'>[src]</a></h4><div class='docblock'><p>@TODO @p2 @docs @release: write docs</p>
|
||
</div><h4 id='method.next_line_help' class="method"><code id='next_line_help.v'>pub 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>) -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a class='srclink' href='../../src/clap/args/arg.rs.html#3658-3665' title='goto source code'>[src]</a></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
|
||
<a href="./enum.AppSettings.html#variant.NextLineHelp"><code>AppSettings::NextLineHelp</code></a></p>
|
||
<h1 id="examples-56" class="section-header"><a href="#examples-56">Examples</a></h1>
|
||
<div class="example-wrap"><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">"prog"</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="bool-val">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="bool-val">true</span>))
|
||
.<span class="ident">get_matches_from</span>(<span class="macro">vec</span><span class="macro">!</span>[
|
||
<span class="string">"prog"</span>, <span class="string">"--help"</span>
|
||
]);</pre></div>
|
||
<p>The above example displays the following help message</p>
|
||
<pre><code class="language-notrust">nlh
|
||
|
||
USAGE:
|
||
nlh [FLAGS] [OPTIONS]
|
||
|
||
FLAGS:
|
||
-h, --help Prints help information
|
||
-V, --version Prints version information
|
||
|
||
OPTIONS:
|
||
-o, --long-option-flag <value1> <value2>
|
||
Some really long help and complex
|
||
help that makes more sense to be
|
||
on a line after the option
|
||
</code></pre>
|
||
</div><h4 id='method.display_order' class="method"><code id='display_order.v'>pub 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>) -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a class='srclink' href='../../src/clap/args/arg.rs.html#3722-3725' title='goto source code'>[src]</a></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 <a href="./struct.Arg.html#method.index">positional arguments</a> which are always displayed in
|
||
<a href="./struct.Arg.html#method.index">index</a> order.</p>
|
||
<h1 id="examples-57" class="section-header"><a href="#examples-57">Examples</a></h1>
|
||
<div class="example-wrap"><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">"prog"</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="bool-val">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="bool-val">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">"prog"</span>, <span class="string">"--help"</span>
|
||
]);</pre></div>
|
||
<p>The above example displays the following help message</p>
|
||
<pre><code class="language-notrust">cust-ord
|
||
|
||
USAGE:
|
||
cust-ord [FLAGS] [OPTIONS]
|
||
|
||
FLAGS:
|
||
-h, --help Prints help information
|
||
-V, --version Prints version information
|
||
|
||
OPTIONS:
|
||
-O, --other-option <b> I should be first!
|
||
-o, --long-option <a> Some help and text
|
||
</code></pre>
|
||
</div><h4 id='method.raw' class="method"><code id='raw.v'>pub fn <a href='#method.raw' class='fnname'>raw</a>(self, raw: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.bool.html">bool</a>) -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a class='srclink' href='../../src/clap/args/arg.rs.html#3746-3748' title='goto source code'>[src]</a></h4><div class='docblock'><p>Indicates that all parameters passed after this should not be parsed
|
||
individually, but rather passed in their entirety. It is worth noting
|
||
that setting this requires all values to come after a <code>--</code> to indicate they
|
||
should all be captured. For example:</p>
|
||
<pre><code class="language-notrust">--foo something -- -v -v -v -b -b -b --baz -q -u -x
|
||
</code></pre>
|
||
<p>Will result in everything after <code>--</code> to be considered one raw argument. This behavior
|
||
may not be exactly what you are expecting and using <a href="./enum.AppSettings.html#variant.TrailingVarArg"><code>AppSettings::TrailingVarArg</code></a>
|
||
may be more appropriate.</p>
|
||
<p><strong>NOTE:</strong> Implicitly sets <a href="./struct.Arg.html#method.multiple"><code>Arg::multiple(true)</code></a>, <a href="./struct.Arg.html#method.allow_hyphen_values"><code>Arg::allow_hyphen_values(true)</code></a>, and
|
||
<a href="./struct.Arg.html#method.last"><code>Arg::last(true)</code></a> when set to <code>true</code></p>
|
||
</div><h4 id='method.hidden_short_help' class="method"><code id='hidden_short_help.v'>pub fn <a href='#method.hidden_short_help' class='fnname'>hidden_short_help</a>(self, hide: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.bool.html">bool</a>) -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a class='srclink' href='../../src/clap/args/arg.rs.html#3819-3825' title='goto source code'>[src]</a></h4><div class='docblock'><p>Hides an argument from short help message output.</p>
|
||
<p><strong>NOTE:</strong> This does <strong>not</strong> hide the argument from usage strings on error</p>
|
||
<p><strong>NOTE:</strong> Setting this option will cause next-line-help output style to be used
|
||
when long help (<code>--help</code>) is called.</p>
|
||
<h1 id="examples-58" class="section-header"><a href="#examples-58">Examples</a></h1>
|
||
<div class="example-wrap"><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_short_help</span>(<span class="bool-val">true</span>)</pre></div>
|
||
<p>Setting <code>hidden_short_help(true)</code> will hide the argument when displaying short help text</p>
|
||
|
||
<div class="example-wrap"><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">"prog"</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_short_help</span>(<span class="bool-val">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">"prog"</span>, <span class="string">"-h"</span>
|
||
]);</pre></div>
|
||
<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>
|
||
<p>However, when --help is called</p>
|
||
|
||
<div class="example-wrap"><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">"prog"</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_short_help</span>(<span class="bool-val">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">"prog"</span>, <span class="string">"--help"</span>
|
||
]);</pre></div>
|
||
<p>Then the following would be displayed</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.hidden_long_help' class="method"><code id='hidden_long_help.v'>pub fn <a href='#method.hidden_long_help' class='fnname'>hidden_long_help</a>(self, hide: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.bool.html">bool</a>) -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a class='srclink' href='../../src/clap/args/arg.rs.html#3896-3902' title='goto source code'>[src]</a></h4><div class='docblock'><p>Hides an argument from long help message output.</p>
|
||
<p><strong>NOTE:</strong> This does <strong>not</strong> hide the argument from usage strings on error</p>
|
||
<p><strong>NOTE:</strong> Setting this option will cause next-line-help output style to be used
|
||
when long help (<code>--help</code>) is called.</p>
|
||
<h1 id="examples-59" class="section-header"><a href="#examples-59">Examples</a></h1>
|
||
<div class="example-wrap"><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_long_help</span>(<span class="bool-val">true</span>)</pre></div>
|
||
<p>Setting <code>hidden_long_help(true)</code> will hide the argument when displaying long help text</p>
|
||
|
||
<div class="example-wrap"><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">"prog"</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_long_help</span>(<span class="bool-val">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">"prog"</span>, <span class="string">"--help"</span>
|
||
]);</pre></div>
|
||
<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>
|
||
<p>However, when -h is called</p>
|
||
|
||
<div class="example-wrap"><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">"prog"</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_long_help</span>(<span class="bool-val">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">"prog"</span>, <span class="string">"-h"</span>
|
||
]);</pre></div>
|
||
<p>Then the following would be displayed</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.is_set' class="method"><code id='is_set.v'>pub fn <a href='#method.is_set' class='fnname'>is_set</a>(&self, s: <a class="enum" href="../../structopt/clap/enum.ArgSettings.html" title="enum structopt::clap::ArgSettings">ArgSettings</a>) -> <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.bool.html">bool</a></code><a class='srclink' href='../../src/clap/args/arg.rs.html#3907-3909' title='goto source code'>[src]</a></h4><div class='docblock'><p>Checks if one of the <a href="./enum.ArgSettings.html"><code>ArgSettings</code></a> settings is set for the argument.</p>
|
||
</div><h4 id='method.set' class="method"><code id='set.v'>pub fn <a href='#method.set' class='fnname'>set</a>(self, s: <a class="enum" href="../../structopt/clap/enum.ArgSettings.html" title="enum structopt::clap::ArgSettings">ArgSettings</a>) -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a class='srclink' href='../../src/clap/args/arg.rs.html#3914-3917' title='goto source code'>[src]</a></h4><div class='docblock'><p>Sets one of the <a href="./enum.ArgSettings.html"><code>ArgSettings</code></a> settings for the argument.</p>
|
||
</div><h4 id='method.unset' class="method"><code id='unset.v'>pub fn <a href='#method.unset' class='fnname'>unset</a>(self, s: <a class="enum" href="../../structopt/clap/enum.ArgSettings.html" title="enum structopt::clap::ArgSettings">ArgSettings</a>) -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a class='srclink' href='../../src/clap/args/arg.rs.html#3922-3925' title='goto source code'>[src]</a></h4><div class='docblock'><p>Unsets one of the <a href="./enum.ArgSettings.html"><code>ArgSettings</code></a> settings for the argument.</p>
|
||
</div></div><h2 id='implementations' class='small-section-header'>Trait Implementations<a href='#implementations' class='anchor'></a></h2><div id='implementations-list'><h3 id='impl-PartialEq%3CArg%3C%27n%2C%20%27e%3E%3E' class='impl'><code class='in-band'>impl<'n, 'e> <a class="trait" href="https://doc.rust-lang.org/nightly/core/cmp/trait.PartialEq.html" title="trait core::cmp::PartialEq">PartialEq</a><<a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'n, 'e>> for <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'n, 'e></code><a href='#impl-PartialEq%3CArg%3C%27n%2C%20%27e%3E%3E' class='anchor'></a><a class='srclink' href='../../src/clap/args/arg.rs.html#3950-3954' title='goto source code'>[src]</a></h3><div class='impl-items'><h4 id='method.eq' class="method hidden"><code id='eq.v'>fn <a href='https://doc.rust-lang.org/nightly/core/cmp/trait.PartialEq.html#tymethod.eq' class='fnname'>eq</a>(&self, other: &<a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'n, 'e>) -> <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.bool.html">bool</a></code><a class='srclink' href='../../src/clap/args/arg.rs.html#3951-3953' title='goto source code'>[src]</a></h4><div class='docblock hidden'><p>This method tests for <code>self</code> and <code>other</code> values to be equal, and is used by <code>==</code>. <a href="https://doc.rust-lang.org/nightly/core/cmp/trait.PartialEq.html#tymethod.eq">Read more</a></p>
|
||
</div><h4 id='method.ne' class="method hidden"><code id='ne.v'><span class="docblock attributes">#[must_use]
|
||
</span>fn <a href='https://doc.rust-lang.org/nightly/core/cmp/trait.PartialEq.html#method.ne' class='fnname'>ne</a>(&self, other: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.reference.html">&</a>Rhs) -> <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.bool.html">bool</a></code><span class='since' title='Stable since Rust version 1.0.0'>1.0.0</span><a class='srclink' href='https://doc.rust-lang.org/nightly/src/core/cmp.rs.html#200' title='goto source code'>[src]</a></h4><div class='docblock hidden'><p>This method tests for <code>!=</code>.</p>
|
||
</div></div><h3 id='impl-Clone' class='impl'><code class='in-band'>impl<'a, 'b> <a class="trait" href="https://doc.rust-lang.org/nightly/core/clone/trait.Clone.html" title="trait core::clone::Clone">Clone</a> for <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b> <span class="where fmt-newline">where<br> 'a: 'b, </span></code><a href='#impl-Clone' class='anchor'></a><a class='srclink' href='../../src/clap/args/arg.rs.html#42' title='goto source code'>[src]</a></h3><div class='impl-items'><h4 id='method.clone' class="method hidden"><code id='clone.v'>fn <a href='https://doc.rust-lang.org/nightly/core/clone/trait.Clone.html#tymethod.clone' class='fnname'>clone</a>(&self) -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a class='srclink' href='../../src/clap/args/arg.rs.html#42' title='goto source code'>[src]</a></h4><div class='docblock hidden'><p>Returns a copy of the value. <a href="https://doc.rust-lang.org/nightly/core/clone/trait.Clone.html#tymethod.clone">Read more</a></p>
|
||
</div><h4 id='method.clone_from' class="method hidden"><code id='clone_from.v'>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: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.reference.html">&</a>Self)</code><span class='since' title='Stable since Rust version 1.0.0'>1.0.0</span><a class='srclink' href='https://doc.rust-lang.org/nightly/src/core/clone.rs.html#131-133' title='goto source code'>[src]</a></h4><div class='docblock hidden'><p>Performs copy-assignment from <code>source</code>. <a href="https://doc.rust-lang.org/nightly/core/clone/trait.Clone.html#method.clone_from">Read more</a></p>
|
||
</div></div><h3 id='impl-Default' class='impl'><code class='in-band'>impl<'a, 'b> <a class="trait" href="https://doc.rust-lang.org/nightly/core/default/trait.Default.html" title="trait core::default::Default">Default</a> for <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b> <span class="where fmt-newline">where<br> 'a: 'b, </span></code><a href='#impl-Default' class='anchor'></a><a class='srclink' href='../../src/clap/args/arg.rs.html#42' title='goto source code'>[src]</a></h3><div class='impl-items'><h4 id='method.default' class="method hidden"><code id='default.v'>fn <a href='https://doc.rust-lang.org/nightly/core/default/trait.Default.html#tymethod.default' class='fnname'>default</a>() -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a class='srclink' href='../../src/clap/args/arg.rs.html#42' title='goto source code'>[src]</a></h4><div class='docblock hidden'><p>Returns the "default value" for a type. <a href="https://doc.rust-lang.org/nightly/core/default/trait.Default.html#tymethod.default">Read more</a></p>
|
||
</div></div><h3 id='impl-From%3C%26%27z%20Arg%3C%27a%2C%20%27b%3E%3E' class='impl'><code class='in-band'>impl<'a, 'b, 'z> <a class="trait" href="https://doc.rust-lang.org/nightly/core/convert/trait.From.html" title="trait core::convert::From">From</a><&'z <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b>> for <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a href='#impl-From%3C%26%27z%20Arg%3C%27a%2C%20%27b%3E%3E' class='anchor'></a><a class='srclink' href='../../src/clap/args/arg.rs.html#3938-3948' title='goto source code'>[src]</a></h3><div class='impl-items'><h4 id='method.from' class="method hidden"><code id='from.v'>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="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b>) -> <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a class='srclink' href='../../src/clap/args/arg.rs.html#3939-3947' title='goto source code'>[src]</a></h4><div class='docblock hidden'><p>Performs the conversion.</p>
|
||
</div></div></div><h2 id='synthetic-implementations' class='small-section-header'>Auto Trait Implementations<a href='#synthetic-implementations' class='anchor'></a></h2><div id='synthetic-implementations-list'><h3 id='impl-Sync' class='impl'><code class='in-band'>impl<'a, 'b> !<a class="trait" href="https://doc.rust-lang.org/nightly/core/marker/trait.Sync.html" title="trait core::marker::Sync">Sync</a> for <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a href='#impl-Sync' class='anchor'></a></h3><div class='impl-items'></div><h3 id='impl-Send' class='impl'><code class='in-band'>impl<'a, 'b> !<a class="trait" href="https://doc.rust-lang.org/nightly/core/marker/trait.Send.html" title="trait core::marker::Send">Send</a> for <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a href='#impl-Send' class='anchor'></a></h3><div class='impl-items'></div><h3 id='impl-Unpin' class='impl'><code class='in-band'>impl<'a, 'b> <a class="trait" href="https://doc.rust-lang.org/nightly/core/marker/trait.Unpin.html" title="trait core::marker::Unpin">Unpin</a> for <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a href='#impl-Unpin' class='anchor'></a></h3><div class='impl-items'></div><h3 id='impl-RefUnwindSafe' class='impl'><code class='in-band'>impl<'a, 'b> !<a class="trait" href="https://doc.rust-lang.org/nightly/std/panic/trait.RefUnwindSafe.html" title="trait std::panic::RefUnwindSafe">RefUnwindSafe</a> for <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a href='#impl-RefUnwindSafe' class='anchor'></a></h3><div class='impl-items'></div><h3 id='impl-UnwindSafe' class='impl'><code class='in-band'>impl<'a, 'b> !<a class="trait" href="https://doc.rust-lang.org/nightly/std/panic/trait.UnwindSafe.html" title="trait std::panic::UnwindSafe">UnwindSafe</a> for <a class="struct" href="../../structopt/clap/struct.Arg.html" title="struct structopt::clap::Arg">Arg</a><'a, 'b></code><a href='#impl-UnwindSafe' class='anchor'></a></h3><div class='impl-items'></div></div><h2 id='blanket-implementations' class='small-section-header'>Blanket Implementations<a href='#blanket-implementations' class='anchor'></a></h2><div id='blanket-implementations-list'><h3 id='impl-Into%3CU%3E' class='impl'><code class='in-band'>impl<T, U> <a class="trait" href="https://doc.rust-lang.org/nightly/core/convert/trait.Into.html" title="trait core::convert::Into">Into</a><U> for T <span class="where fmt-newline">where<br> U: <a class="trait" href="https://doc.rust-lang.org/nightly/core/convert/trait.From.html" title="trait core::convert::From">From</a><T>, </span></code><a href='#impl-Into%3CU%3E' class='anchor'></a><a class='srclink' href='https://doc.rust-lang.org/nightly/src/core/convert.rs.html#543-548' title='goto source code'>[src]</a></h3><div class='impl-items'><h4 id='method.into' class="method hidden"><code id='into.v'>fn <a href='https://doc.rust-lang.org/nightly/core/convert/trait.Into.html#tymethod.into' class='fnname'>into</a>(self) -> U</code><a class='srclink' href='https://doc.rust-lang.org/nightly/src/core/convert.rs.html#545-547' title='goto source code'>[src]</a></h4><div class='docblock hidden'><p>Performs the conversion.</p>
|
||
</div></div><h3 id='impl-From%3CT%3E' class='impl'><code class='in-band'>impl<T> <a class="trait" href="https://doc.rust-lang.org/nightly/core/convert/trait.From.html" title="trait core::convert::From">From</a><T> for T</code><a href='#impl-From%3CT%3E' class='anchor'></a><a class='srclink' href='https://doc.rust-lang.org/nightly/src/core/convert.rs.html#552-554' title='goto source code'>[src]</a></h3><div class='impl-items'><h4 id='method.from-1' class="method hidden"><code id='from.v-1'>fn <a href='https://doc.rust-lang.org/nightly/core/convert/trait.From.html#tymethod.from' class='fnname'>from</a>(t: T) -> T</code><a class='srclink' href='https://doc.rust-lang.org/nightly/src/core/convert.rs.html#553' title='goto source code'>[src]</a></h4><div class='docblock hidden'><p>Performs the conversion.</p>
|
||
</div></div><h3 id='impl-ToOwned' class='impl'><code class='in-band'>impl<T> <a class="trait" href="https://doc.rust-lang.org/nightly/alloc/borrow/trait.ToOwned.html" title="trait alloc::borrow::ToOwned">ToOwned</a> for T <span class="where fmt-newline">where<br> T: <a class="trait" href="https://doc.rust-lang.org/nightly/core/clone/trait.Clone.html" title="trait core::clone::Clone">Clone</a>, </span></code><a href='#impl-ToOwned' class='anchor'></a><a class='srclink' href='https://doc.rust-lang.org/nightly/src/alloc/borrow.rs.html#81-92' title='goto source code'>[src]</a></h3><div class='impl-items'><h4 id='associatedtype.Owned' class="type"><code id='Owned.t'>type <a href='https://doc.rust-lang.org/nightly/alloc/borrow/trait.ToOwned.html#associatedtype.Owned' class="type">Owned</a> = T</code></h4><div class='docblock'><p>The resulting type after obtaining ownership.</p>
|
||
</div><h4 id='method.to_owned' class="method hidden"><code id='to_owned.v'>fn <a href='https://doc.rust-lang.org/nightly/alloc/borrow/trait.ToOwned.html#tymethod.to_owned' class='fnname'>to_owned</a>(&self) -> T</code><a class='srclink' href='https://doc.rust-lang.org/nightly/src/alloc/borrow.rs.html#85-87' title='goto source code'>[src]</a></h4><div class='docblock hidden'><p>Creates owned data from borrowed data, usually by cloning. <a href="https://doc.rust-lang.org/nightly/alloc/borrow/trait.ToOwned.html#tymethod.to_owned">Read more</a></p>
|
||
</div><h4 id='method.clone_into' class="method hidden"><code id='clone_into.v'>fn <a href='https://doc.rust-lang.org/nightly/alloc/borrow/trait.ToOwned.html#method.clone_into' class='fnname'>clone_into</a>(&self, target: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.reference.html">&mut </a>T)</code><a class='srclink' href='https://doc.rust-lang.org/nightly/src/alloc/borrow.rs.html#89-91' title='goto source code'>[src]</a></h4><div class='stability hidden'><div class='stab unstable'><details><summary><span class='emoji'>🔬</span> This is a nightly-only experimental API. (<code>toowned_clone_into</code>)</summary><p>recently added</p>
|
||
</details></div></div><div class='docblock hidden'><p>Uses borrowed data to replace owned data, usually by cloning. <a href="https://doc.rust-lang.org/nightly/alloc/borrow/trait.ToOwned.html#method.clone_into">Read more</a></p>
|
||
</div></div><h3 id='impl-TryFrom%3CU%3E' class='impl'><code class='in-band'>impl<T, U> <a class="trait" href="https://doc.rust-lang.org/nightly/core/convert/trait.TryFrom.html" title="trait core::convert::TryFrom">TryFrom</a><U> for T <span class="where fmt-newline">where<br> U: <a class="trait" href="https://doc.rust-lang.org/nightly/core/convert/trait.Into.html" title="trait core::convert::Into">Into</a><T>, </span></code><a href='#impl-TryFrom%3CU%3E' class='anchor'></a><a class='srclink' href='https://doc.rust-lang.org/nightly/src/core/convert.rs.html#571-577' title='goto source code'>[src]</a></h3><div class='impl-items'><h4 id='associatedtype.Error' class="type"><code id='Error.t'>type <a href='https://doc.rust-lang.org/nightly/core/convert/trait.TryFrom.html#associatedtype.Error' class="type">Error</a> = <a class="enum" href="https://doc.rust-lang.org/nightly/core/convert/enum.Infallible.html" title="enum core::convert::Infallible">Infallible</a></code></h4><div class='docblock'><p>The type returned in the event of a conversion error.</p>
|
||
</div><h4 id='method.try_from' class="method hidden"><code id='try_from.v'>fn <a href='https://doc.rust-lang.org/nightly/core/convert/trait.TryFrom.html#tymethod.try_from' class='fnname'>try_from</a>(value: U) -> <a class="enum" href="https://doc.rust-lang.org/nightly/core/result/enum.Result.html" title="enum core::result::Result">Result</a><T, <T as <a class="trait" href="https://doc.rust-lang.org/nightly/core/convert/trait.TryFrom.html" title="trait core::convert::TryFrom">TryFrom</a><U>>::<a class="type" href="https://doc.rust-lang.org/nightly/core/convert/trait.TryFrom.html#associatedtype.Error" title="type core::convert::TryFrom::Error">Error</a>></code><a class='srclink' href='https://doc.rust-lang.org/nightly/src/core/convert.rs.html#574-576' title='goto source code'>[src]</a></h4><div class='docblock hidden'><p>Performs the conversion.</p>
|
||
</div></div><h3 id='impl-TryInto%3CU%3E' class='impl'><code class='in-band'>impl<T, U> <a class="trait" href="https://doc.rust-lang.org/nightly/core/convert/trait.TryInto.html" title="trait core::convert::TryInto">TryInto</a><U> for T <span class="where fmt-newline">where<br> U: <a class="trait" href="https://doc.rust-lang.org/nightly/core/convert/trait.TryFrom.html" title="trait core::convert::TryFrom">TryFrom</a><T>, </span></code><a href='#impl-TryInto%3CU%3E' class='anchor'></a><a class='srclink' href='https://doc.rust-lang.org/nightly/src/core/convert.rs.html#559-566' title='goto source code'>[src]</a></h3><div class='impl-items'><h4 id='associatedtype.Error-1' class="type"><code id='Error.t-1'>type <a href='https://doc.rust-lang.org/nightly/core/convert/trait.TryInto.html#associatedtype.Error' class="type">Error</a> = <U as <a class="trait" href="https://doc.rust-lang.org/nightly/core/convert/trait.TryFrom.html" title="trait core::convert::TryFrom">TryFrom</a><T>>::<a class="type" href="https://doc.rust-lang.org/nightly/core/convert/trait.TryFrom.html#associatedtype.Error" title="type core::convert::TryFrom::Error">Error</a></code></h4><div class='docblock'><p>The type returned in the event of a conversion error.</p>
|
||
</div><h4 id='method.try_into' class="method hidden"><code id='try_into.v'>fn <a href='https://doc.rust-lang.org/nightly/core/convert/trait.TryInto.html#tymethod.try_into' class='fnname'>try_into</a>(self) -> <a class="enum" href="https://doc.rust-lang.org/nightly/core/result/enum.Result.html" title="enum core::result::Result">Result</a><U, <U as <a class="trait" href="https://doc.rust-lang.org/nightly/core/convert/trait.TryFrom.html" title="trait core::convert::TryFrom">TryFrom</a><T>>::<a class="type" href="https://doc.rust-lang.org/nightly/core/convert/trait.TryFrom.html#associatedtype.Error" title="type core::convert::TryFrom::Error">Error</a>></code><a class='srclink' href='https://doc.rust-lang.org/nightly/src/core/convert.rs.html#563-565' title='goto source code'>[src]</a></h4><div class='docblock hidden'><p>Performs the conversion.</p>
|
||
</div></div><h3 id='impl-BorrowMut%3CT%3E' class='impl'><code class='in-band'>impl<T> <a class="trait" href="https://doc.rust-lang.org/nightly/core/borrow/trait.BorrowMut.html" title="trait core::borrow::BorrowMut">BorrowMut</a><T> for T <span class="where fmt-newline">where<br> T: ?<a class="trait" href="https://doc.rust-lang.org/nightly/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a>, </span></code><a href='#impl-BorrowMut%3CT%3E' class='anchor'></a><a class='srclink' href='https://doc.rust-lang.org/nightly/src/core/borrow.rs.html#218-220' title='goto source code'>[src]</a></h3><div class='impl-items'><h4 id='method.borrow_mut' class="method hidden"><code id='borrow_mut.v'>fn <a href='https://doc.rust-lang.org/nightly/core/borrow/trait.BorrowMut.html#tymethod.borrow_mut' class='fnname'>borrow_mut</a>(&mut self) -> <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.reference.html">&mut </a>T</code><a class='srclink' href='https://doc.rust-lang.org/nightly/src/core/borrow.rs.html#219' title='goto source code'>[src]</a></h4><div class='docblock hidden'><p>Mutably borrows from an owned value. <a href="https://doc.rust-lang.org/nightly/core/borrow/trait.BorrowMut.html#tymethod.borrow_mut">Read more</a></p>
|
||
</div></div><h3 id='impl-Borrow%3CT%3E' class='impl'><code class='in-band'>impl<T> <a class="trait" href="https://doc.rust-lang.org/nightly/core/borrow/trait.Borrow.html" title="trait core::borrow::Borrow">Borrow</a><T> for T <span class="where fmt-newline">where<br> T: ?<a class="trait" href="https://doc.rust-lang.org/nightly/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a>, </span></code><a href='#impl-Borrow%3CT%3E' class='anchor'></a><a class='srclink' href='https://doc.rust-lang.org/nightly/src/core/borrow.rs.html#213-215' title='goto source code'>[src]</a></h3><div class='impl-items'><h4 id='method.borrow' class="method hidden"><code id='borrow.v'>fn <a href='https://doc.rust-lang.org/nightly/core/borrow/trait.Borrow.html#tymethod.borrow' class='fnname'>borrow</a>(&self) -> <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.reference.html">&</a>T</code><a class='srclink' href='https://doc.rust-lang.org/nightly/src/core/borrow.rs.html#214' title='goto source code'>[src]</a></h4><div class='docblock hidden'><p>Immutably borrows from an owned value. <a href="https://doc.rust-lang.org/nightly/core/borrow/trait.Borrow.html#tymethod.borrow">Read more</a></p>
|
||
</div></div><h3 id='impl-Any' class='impl'><code class='in-band'>impl<T> <a class="trait" href="https://doc.rust-lang.org/nightly/core/any/trait.Any.html" title="trait core::any::Any">Any</a> for T <span class="where fmt-newline">where<br> T: 'static + ?<a class="trait" href="https://doc.rust-lang.org/nightly/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a>, </span></code><a href='#impl-Any' class='anchor'></a><a class='srclink' href='https://doc.rust-lang.org/nightly/src/core/any.rs.html#100-102' title='goto source code'>[src]</a></h3><div class='impl-items'><h4 id='method.type_id' class="method hidden"><code id='type_id.v'>fn <a href='https://doc.rust-lang.org/nightly/core/any/trait.Any.html#tymethod.type_id' class='fnname'>type_id</a>(&self) -> <a class="struct" href="https://doc.rust-lang.org/nightly/core/any/struct.TypeId.html" title="struct core::any::TypeId">TypeId</a></code><a class='srclink' href='https://doc.rust-lang.org/nightly/src/core/any.rs.html#101' title='goto source code'>[src]</a></h4><div class='docblock hidden'><p>Gets the <code>TypeId</code> of <code>self</code>. <a href="https://doc.rust-lang.org/nightly/core/any/trait.Any.html#tymethod.type_id">Read more</a></p>
|
||
</div></div></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><kbd>?</kbd></dt><dd>Show this help dialog</dd><dt><kbd>S</kbd></dt><dd>Focus the search field</dd><dt><kbd>↑</kbd></dt><dd>Move up in search results</dd><dt><kbd>↓</kbd></dt><dd>Move down in search results</dd><dt><kbd>↹</kbd></dt><dd>Switch tab</dd><dt><kbd>⏎</kbd></dt><dd>Go to active search result</dd><dt><kbd>+</kbd></dt><dd>Expand all sections</dd><dt><kbd>-</kbd></dt><dd>Collapse all sections</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><p>Search multiple things at once by splitting your query with comma (e.g., <code>str,u8</code> or <code>String,struct:Vec,test</code>)</p></div></div></aside><script>window.rootPath = "../../";window.currentCrate = "structopt";</script><script src="../../aliases.js"></script><script src="../../main.js"></script><script defer src="../../search-index.js"></script></body></html> |