| <!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="The abstract representation of a command line argument. Used to set all the options and relationships that define a valid argument for the program."><meta name="keywords" content="rust, rustlang, rust-lang, Arg"><title>Arg in clap - Rust</title><link rel="preload" as="font" type="font/woff2" crossorigin href="../SourceSerif4-Regular.ttf.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../FiraSans-Regular.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../FiraSans-Medium.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../SourceCodePro-Regular.ttf.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../SourceSerif4-Bold.ttf.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../SourceCodePro-Semibold.ttf.woff2"><link rel="stylesheet" href="../normalize.css"><link rel="stylesheet" href="../rustdoc.css" id="mainThemeStyle"><link rel="stylesheet" href="../ayu.css" disabled><link rel="stylesheet" href="../dark.css" disabled><link rel="stylesheet" href="../light.css" id="themeStyle"><script id="default-settings" ></script><script src="../storage.js"></script><script defer src="sidebar-items.js"></script><script defer src="../main.js"></script><noscript><link rel="stylesheet" href="../noscript.css"></noscript><link rel="alternate icon" type="image/png" href="../favicon-16x16.png"><link rel="alternate icon" type="image/png" href="../favicon-32x32.png"><link rel="icon" type="image/svg+xml" href="../favicon.svg"></head><body class="rustdoc struct"><!--[if lte IE 11]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><nav class="mobile-topbar"><button class="sidebar-menu-toggle">☰</button><a class="sidebar-logo" href="../clap/index.html"><div class="logo-container"><img class="rust-logo" src="../rust-logo.svg" alt="logo"></div></a><h2></h2></nav><nav class="sidebar"><a class="sidebar-logo" href="../clap/index.html"><div class="logo-container"><img class="rust-logo" src="../rust-logo.svg" alt="logo"></div></a><h2 class="location"><a href="#">Arg</a></h2><div class="sidebar-elems"><section><h3><a href="#implementations">Methods</a></h3><ul class="block"><li><a href="#method.alias">alias</a></li><li><a href="#method.aliases">aliases</a></li><li><a href="#method.allow_hyphen_values">allow_hyphen_values</a></li><li><a href="#method.case_insensitive">case_insensitive</a></li><li><a href="#method.conflicts_with">conflicts_with</a></li><li><a href="#method.conflicts_with_all">conflicts_with_all</a></li><li><a href="#method.default_value">default_value</a></li><li><a href="#method.default_value_if">default_value_if</a></li><li><a href="#method.default_value_if_os">default_value_if_os</a></li><li><a href="#method.default_value_ifs">default_value_ifs</a></li><li><a href="#method.default_value_ifs_os">default_value_ifs_os</a></li><li><a href="#method.default_value_os">default_value_os</a></li><li><a href="#method.display_order">display_order</a></li><li><a href="#method.empty_values">empty_values</a></li><li><a href="#method.env">env</a></li><li><a href="#method.env_os">env_os</a></li><li><a href="#method.from_usage">from_usage</a></li><li><a href="#method.global">global</a></li><li><a href="#method.group">group</a></li><li><a href="#method.groups">groups</a></li><li><a href="#method.help">help</a></li><li><a href="#method.hidden">hidden</a></li><li><a href="#method.hidden_long_help">hidden_long_help</a></li><li><a href="#method.hidden_short_help">hidden_short_help</a></li><li><a href="#method.hide_default_value">hide_default_value</a></li><li><a href="#method.hide_env_values">hide_env_values</a></li><li><a href="#method.hide_possible_values">hide_possible_values</a></li><li><a href="#method.index">index</a></li><li><a href="#method.is_set">is_set</a></li><li><a href="#method.last">last</a></li><li><a href="#method.long">long</a></li><li><a href="#method.long_help">long_help</a></li><li><a href="#method.max_values">max_values</a></li><li><a href="#method.min_values">min_values</a></li><li><a href="#method.multiple">multiple</a></li><li><a href="#method.next_line_help">next_line_help</a></li><li><a href="#method.number_of_values">number_of_values</a></li><li><a href="#method.overrides_with">overrides_with</a></li><li><a href="#method.overrides_with_all">overrides_with_all</a></li><li><a href="#method.possible_value">possible_value</a></li><li><a href="#method.possible_values">possible_values</a></li><li><a href="#method.raw">raw</a></li><li><a href="#method.require_delimiter">require_delimiter</a></li><li><a href="#method.require_equals">require_equals</a></li><li><a href="#method.required">required</a></li><li><a href="#method.required_if">required_if</a></li><li><a href="#method.required_ifs">required_ifs</a></li><li><a href="#method.required_unless">required_unless</a></li><li><a href="#method.required_unless_all">required_unless_all</a></li><li><a href="#method.required_unless_one">required_unless_one</a></li><li><a href="#method.requires">requires</a></li><li><a href="#method.requires_all">requires_all</a></li><li><a href="#method.requires_if">requires_if</a></li><li><a href="#method.requires_ifs">requires_ifs</a></li><li><a href="#method.set">set</a></li><li><a href="#method.short">short</a></li><li><a href="#method.takes_value">takes_value</a></li><li><a href="#method.unset">unset</a></li><li><a href="#method.use_delimiter">use_delimiter</a></li><li><a href="#method.validator">validator</a></li><li><a href="#method.validator_os">validator_os</a></li><li><a href="#method.value_delimiter">value_delimiter</a></li><li><a href="#method.value_name">value_name</a></li><li><a href="#method.value_names">value_names</a></li><li><a href="#method.value_terminator">value_terminator</a></li><li><a href="#method.visible_alias">visible_alias</a></li><li><a href="#method.visible_aliases">visible_aliases</a></li><li><a href="#method.with_name">with_name</a></li></ul><h3><a href="#trait-implementations">Trait Implementations</a></h3><ul class="block"><li><a href="#impl-Clone-for-Arg%3C%27a%2C%20%27b%3E">Clone</a></li><li><a href="#impl-Default-for-Arg%3C%27a%2C%20%27b%3E">Default</a></li><li><a href="#impl-From%3C%26%27z%20Arg%3C%27a%2C%20%27b%3E%3E-for-Arg%3C%27a%2C%20%27b%3E">From<&'z Arg<'a, 'b>></a></li><li><a href="#impl-PartialEq%3CArg%3C%27n%2C%20%27e%3E%3E-for-Arg%3C%27n%2C%20%27e%3E">PartialEq<Arg<'n, 'e>></a></li></ul><h3><a href="#synthetic-implementations">Auto Trait Implementations</a></h3><ul class="block"><li><a href="#impl-RefUnwindSafe-for-Arg%3C%27a%2C%20%27b%3E">!RefUnwindSafe</a></li><li><a href="#impl-Send-for-Arg%3C%27a%2C%20%27b%3E">!Send</a></li><li><a href="#impl-Sync-for-Arg%3C%27a%2C%20%27b%3E">!Sync</a></li><li><a href="#impl-Unpin-for-Arg%3C%27a%2C%20%27b%3E">Unpin</a></li><li><a href="#impl-UnwindSafe-for-Arg%3C%27a%2C%20%27b%3E">!UnwindSafe</a></li></ul><h3><a href="#blanket-implementations">Blanket Implementations</a></h3><ul class="block"><li><a href="#impl-Any-for-Arg%3C%27a%2C%20%27b%3E">Any</a></li><li><a href="#impl-Borrow%3CT%3E-for-Arg%3C%27a%2C%20%27b%3E">Borrow<T></a></li><li><a href="#impl-BorrowMut%3CT%3E-for-Arg%3C%27a%2C%20%27b%3E">BorrowMut<T></a></li><li><a href="#impl-From%3CT%3E-for-Arg%3C%27a%2C%20%27b%3E">From<T></a></li><li><a href="#impl-Into%3CU%3E-for-Arg%3C%27a%2C%20%27b%3E">Into<U></a></li><li><a href="#impl-ToOwned-for-Arg%3C%27a%2C%20%27b%3E">ToOwned</a></li><li><a href="#impl-TryFrom%3CU%3E-for-Arg%3C%27a%2C%20%27b%3E">TryFrom<U></a></li><li><a href="#impl-TryInto%3CU%3E-for-Arg%3C%27a%2C%20%27b%3E">TryInto<U></a></li></ul></section><h2><a href="index.html">In clap</a></h2></div></nav><main><div class="width-limiter"><nav class="sub"><form class="search-form"><div class="search-container"><span></span><input class="search-input" name="search" autocomplete="off" spellcheck="false" placeholder="Click or press ‘S’ to search, ‘?’ for more options…" type="search"><div id="help-button" title="help" tabindex="-1"><a href="../help.html">?</a></div><div id="settings-menu" tabindex="-1"><a href="../settings.html" title="settings"><img width="22" height="22" alt="Change settings" src="../wheel.svg"></a></div></div></form></nav><section id="main-content" class="content"><div class="main-heading"><h1 class="fqn">Struct <a href="index.html">clap</a>::<wbr><a class="struct" href="#">Arg</a><button id="copy-path" onclick="copy_path(this)" title="Copy item path to clipboard"><img src="../clipboard.svg" width="19" height="18" alt="Copy item path"></button></h1><span class="out-of-band"><a class="srclink" href="../src/clap/args/arg.rs.html#49-63">source</a> · <a id="toggle-all-docs" href="javascript:void(0)" title="collapse all docs">[<span class="inner">−</span>]</a></span></div><div class="item-decl"><pre class="rust struct"><code>pub struct Arg<'a, 'b><span class="where fmt-newline">where<br> 'a: 'b,</span>{ /* private fields */ }</code></pre></div><details class="rustdoc-toggle top-doc" open><summary class="hideme"><span>Expand description</span></summary><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> |
| <h2 id="examples"><a href="#examples">Examples</a></h2> |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="comment">// Using the traditional builder pattern and setting each option manually |
| </span><span class="kw">let </span>cfg = Arg::with_name(<span class="string">"config"</span>) |
| .short(<span class="string">"c"</span>) |
| .long(<span class="string">"config"</span>) |
| .takes_value(<span class="bool-val">true</span>) |
| .value_name(<span class="string">"FILE"</span>) |
| .help(<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>input = Arg::from_usage(<span class="string">"-i, --input=[FILE] 'Provides an input file to the program'"</span>);</code></pre></div> |
| </div></details><h2 id="implementations" class="small-section-header">Implementations<a href="#implementations" class="anchor"></a></h2><div id="implementations-list"><details class="rustdoc-toggle implementors-toggle" open><summary><section id="impl-Arg%3C%27a%2C%20%27b%3E" class="impl has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#65-3943">source</a><a href="#impl-Arg%3C%27a%2C%20%27b%3E" class="anchor"></a><h3 class="code-header">impl<'a, 'b> <a class="struct" href="struct.Arg.html" title="struct clap::Arg">Arg</a><'a, 'b></h3></section></summary><div class="impl-items"><details class="rustdoc-toggle method-toggle" open><summary><section id="method.with_name" class="method has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#83-88">source</a><h4 class="code-header">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>) -> Self</h4></section></summary><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> |
| <h5 id="examples-1"><a href="#examples-1">Examples</a></h5> |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code>Arg::with_name(<span class="string">"config"</span>)</code></pre></div> |
| </div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.from_usage" class="method has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#301-304">source</a><h4 class="code-header">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>) -> Self</h4></section></summary><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> |
| <h5 id="syntax"><a href="#syntax">Syntax</a></h5> |
| <p>Usage strings typically following the form:</p> |
| <div class="example-wrap"><pre class="language-notrust"><code>[explicit name] [short] [long] [value names] [help string]</code></pre></div> |
| <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> |
| <h6 id="explicit-name"><a href="#explicit-name">Explicit Name</a></h6> |
| <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> |
| <div class="example-wrap"><pre class="language-notrust"><code>[ename] -s, --long 'some flag' |
| <rname> -r, --longer 'some other flag'</code></pre></div><h6 id="short"><a href="#short">Short</a></h6> |
| <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> |
| <div class="example-wrap"><pre class="language-notrust"><code>-s, --long 'some flag' |
| <rname> -r [val], --longer 'some option'</code></pre></div><h6 id="long"><a href="#long">Long</a></h6> |
| <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> |
| <div class="example-wrap"><pre class="language-notrust"><code>-s, --some 'some flag' |
| --rapid=[FILE] 'some option'</code></pre></div><h6 id="values-value-notation"><a href="#values-value-notation">Values (Value Notation)</a></h6> |
| <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> |
| <div class="example-wrap"><pre class="language-notrust"><code>-s, --some [FILE] 'some option' |
| --rapid=<SPEED>... 'some required multiple option'</code></pre></div><h6 id="help-string"><a href="#help-string">Help String</a></h6> |
| <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> |
| <div class="example-wrap"><pre class="language-notrust"><code>-s, --some [FILE] 'some option' |
| --rapid=<SPEED>... 'some required multiple option'</code></pre></div><h6 id="additional-sigils"><a href="#additional-sigils">Additional Sigils</a></h6> |
| <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> |
| <h5 id="examples-2"><a href="#examples-2">Examples</a></h5> |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code>App::new(<span class="string">"prog"</span>) |
| .args(<span class="kw-2">&</span>[ |
| Arg::from_usage(<span class="string">"--config <FILE> 'a required file for the configuration and no short'"</span>), |
| Arg::from_usage(<span class="string">"-d, --debug... 'turns on debugging information and allows multiples'"</span>), |
| Arg::from_usage(<span class="string">"[input] 'an optional input file to use'"</span>) |
| ])</code></pre></div> |
| </div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.short" class="method has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#342-345">source</a><h4 class="code-header">pub fn <a href="#method.short" class="fnname">short</a><S: <a class="trait" href="https://doc.rust-lang.org/nightly/core/convert/trait.AsRef.html" title="trait core::convert::AsRef">AsRef</a><<a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.str.html">str</a>>>(self, s: S) -> Self</h4></section></summary><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> |
| <h5 id="examples-3"><a href="#examples-3">Examples</a></h5> |
| <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"><code>Arg::with_name(<span class="string">"config"</span>) |
| .short(<span class="string">"c"</span>)</code></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"><code><span class="kw">let </span>m = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"config"</span>) |
| .short(<span class="string">"c"</span>)) |
| .get_matches_from(<span class="macro">vec!</span>[ |
| <span class="string">"prog"</span>, <span class="string">"-c" |
| </span>]); |
| |
| <span class="macro">assert!</span>(m.is_present(<span class="string">"config"</span>));</code></pre></div> |
| </div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.long" class="method has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#382-385">source</a><h4 class="code-header">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>) -> Self</h4></section></summary><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> |
| <h5 id="examples-4"><a href="#examples-4">Examples</a></h5> |
| <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"><code>Arg::with_name(<span class="string">"cfg"</span>) |
| .long(<span class="string">"config"</span>)</code></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"><code><span class="kw">let </span>m = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"cfg"</span>) |
| .long(<span class="string">"config"</span>)) |
| .get_matches_from(<span class="macro">vec!</span>[ |
| <span class="string">"prog"</span>, <span class="string">"--config" |
| </span>]); |
| |
| <span class="macro">assert!</span>(m.is_present(<span class="string">"cfg"</span>));</code></pre></div> |
| </div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.alias" class="method has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#408-415">source</a><h4 class="code-header">pub fn <a href="#method.alias" class="fnname">alias</a><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>>>(self, name: S) -> Self</h4></section></summary><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> |
| <h5 id="examples-5"><a href="#examples-5">Examples</a></h5> |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">let </span>m = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"test"</span>) |
| .long(<span class="string">"test"</span>) |
| .alias(<span class="string">"alias"</span>) |
| .takes_value(<span class="bool-val">true</span>)) |
| .get_matches_from(<span class="macro">vec!</span>[ |
| <span class="string">"prog"</span>, <span class="string">"--alias"</span>, <span class="string">"cool" |
| </span>]); |
| <span class="macro">assert!</span>(m.is_present(<span class="string">"test"</span>)); |
| <span class="macro">assert_eq!</span>(m.value_of(<span class="string">"test"</span>), <span class="prelude-val">Some</span>(<span class="string">"cool"</span>));</code></pre></div> |
| </div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.aliases" class="method has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#438-447">source</a><h4 class="code-header">pub fn <a href="#method.aliases" class="fnname">aliases</a>(self, names: &[&'b <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.str.html">str</a>]) -> Self</h4></section></summary><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> |
| <h5 id="examples-6"><a href="#examples-6">Examples</a></h5> |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">let </span>m = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"test"</span>) |
| .long(<span class="string">"test"</span>) |
| .aliases(<span class="kw-2">&</span>[<span class="string">"do-stuff"</span>, <span class="string">"do-tests"</span>, <span class="string">"tests"</span>]) |
| .help(<span class="string">"the file to add"</span>) |
| .required(<span class="bool-val">false</span>)) |
| .get_matches_from(<span class="macro">vec!</span>[ |
| <span class="string">"prog"</span>, <span class="string">"--do-tests" |
| </span>]); |
| <span class="macro">assert!</span>(m.is_present(<span class="string">"test"</span>));</code></pre></div> |
| </div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.visible_alias" class="method has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#469-476">source</a><h4 class="code-header">pub fn <a href="#method.visible_alias" class="fnname">visible_alias</a><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>>>(self, name: S) -> Self</h4></section></summary><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="struct.Arg.html#method.alias" title="Arg::alias"><code>Arg::alias</code></a>, except that they are visible inside the help message.</p> |
| <h5 id="examples-7"><a href="#examples-7">Examples</a></h5> |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">let </span>m = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"test"</span>) |
| .visible_alias(<span class="string">"something-awesome"</span>) |
| .long(<span class="string">"test"</span>) |
| .takes_value(<span class="bool-val">true</span>)) |
| .get_matches_from(<span class="macro">vec!</span>[ |
| <span class="string">"prog"</span>, <span class="string">"--something-awesome"</span>, <span class="string">"coffee" |
| </span>]); |
| <span class="macro">assert!</span>(m.is_present(<span class="string">"test"</span>)); |
| <span class="macro">assert_eq!</span>(m.value_of(<span class="string">"test"</span>), <span class="prelude-val">Some</span>(<span class="string">"coffee"</span>));</code></pre></div> |
| </div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.visible_aliases" class="method has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#496-505">source</a><h4 class="code-header">pub fn <a href="#method.visible_aliases" class="fnname">visible_aliases</a>(self, names: &[&'b <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.str.html">str</a>]) -> Self</h4></section></summary><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="struct.Arg.html#method.aliases" title="Arg::aliases"><code>Arg::aliases</code></a>, except that they are visible inside the help message.</p> |
| <h5 id="examples-8"><a href="#examples-8">Examples</a></h5> |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">let </span>m = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"test"</span>) |
| .long(<span class="string">"test"</span>) |
| .visible_aliases(<span class="kw-2">&</span>[<span class="string">"something"</span>, <span class="string">"awesome"</span>, <span class="string">"cool"</span>])) |
| .get_matches_from(<span class="macro">vec!</span>[ |
| <span class="string">"prog"</span>, <span class="string">"--awesome" |
| </span>]); |
| <span class="macro">assert!</span>(m.is_present(<span class="string">"test"</span>));</code></pre></div> |
| </div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.help" class="method has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#557-560">source</a><h4 class="code-header">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>) -> Self</h4></section></summary><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> |
| <h5 id="examples-9"><a href="#examples-9">Examples</a></h5> |
| <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"><code>Arg::with_name(<span class="string">"config"</span>) |
| .help(<span class="string">"The config file used by the myprog"</span>)</code></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"><code><span class="kw">let </span>m = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"cfg"</span>) |
| .long(<span class="string">"config"</span>) |
| .help(<span class="string">"Some help text describing the --config arg"</span>)) |
| .get_matches_from(<span class="macro">vec!</span>[ |
| <span class="string">"prog"</span>, <span class="string">"--help" |
| </span>]);</code></pre></div> |
| <p>The above example displays</p> |
| <div class="example-wrap"><pre class="language-notrust"><code>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></div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.long_help" class="method has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#628-631">source</a><h4 class="code-header">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>) -> Self</h4></section></summary><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> |
| <h5 id="examples-10"><a href="#examples-10">Examples</a></h5> |
| <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"><code>Arg::with_name(<span class="string">"config"</span>) |
| .long_help( |
| <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>)</code></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"><code><span class="kw">let </span>m = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"cfg"</span>) |
| .long(<span class="string">"config"</span>) |
| .long_help( |
| <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>)) |
| .get_matches_from(<span class="macro">vec!</span>[ |
| <span class="string">"prog"</span>, <span class="string">"--help" |
| </span>]);</code></pre></div> |
| <p>The above example displays</p> |
| <div class="example-wrap"><pre class="language-notrust"><code>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></div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.last" class="method has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#705-711">source</a><h4 class="code-header">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>) -> Self</h4></section></summary><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> |
| <h5 id="examples-11"><a href="#examples-11">Examples</a></h5> |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code>Arg::with_name(<span class="string">"args"</span>) |
| .last(<span class="bool-val">true</span>)</code></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"><code><span class="kw">let </span>res = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"first"</span>)) |
| .arg(Arg::with_name(<span class="string">"second"</span>)) |
| .arg(Arg::with_name(<span class="string">"third"</span>).last(<span class="bool-val">true</span>)) |
| .get_matches_from_safe(<span class="macro">vec!</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>(res.is_ok()); |
| <span class="kw">let </span>m = res.unwrap(); |
| <span class="macro">assert_eq!</span>(m.value_of(<span class="string">"third"</span>), <span class="prelude-val">Some</span>(<span class="string">"three"</span>)); |
| <span class="macro">assert!</span>(m.value_of(<span class="string">"second"</span>).is_none());</code></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"><code><span class="kw">let </span>res = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"first"</span>)) |
| .arg(Arg::with_name(<span class="string">"second"</span>)) |
| .arg(Arg::with_name(<span class="string">"third"</span>).last(<span class="bool-val">true</span>)) |
| .get_matches_from_safe(<span class="macro">vec!</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>(res.is_err()); |
| <span class="macro">assert_eq!</span>(res.unwrap_err().kind, ErrorKind::UnknownArgument);</code></pre></div> |
| </div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.required" class="method has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#764-770">source</a><h4 class="code-header">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>) -> Self</h4></section></summary><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> |
| <h5 id="examples-12"><a href="#examples-12">Examples</a></h5> |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code>Arg::with_name(<span class="string">"config"</span>) |
| .required(<span class="bool-val">true</span>)</code></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"><code><span class="kw">let </span>res = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"cfg"</span>) |
| .required(<span class="bool-val">true</span>) |
| .takes_value(<span class="bool-val">true</span>) |
| .long(<span class="string">"config"</span>)) |
| .get_matches_from_safe(<span class="macro">vec!</span>[ |
| <span class="string">"prog"</span>, <span class="string">"--config"</span>, <span class="string">"file.conf" |
| </span>]); |
| |
| <span class="macro">assert!</span>(res.is_ok());</code></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"><code><span class="kw">let </span>res = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"cfg"</span>) |
| .required(<span class="bool-val">true</span>) |
| .takes_value(<span class="bool-val">true</span>) |
| .long(<span class="string">"config"</span>)) |
| .get_matches_from_safe(<span class="macro">vec!</span>[ |
| <span class="string">"prog" |
| </span>]); |
| |
| <span class="macro">assert!</span>(res.is_err()); |
| <span class="macro">assert_eq!</span>(res.unwrap_err().kind, ErrorKind::MissingRequiredArgument);</code></pre></div> |
| </div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.require_equals" class="method has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#826-833">source</a><h4 class="code-header">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>) -> Self</h4></section></summary><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> |
| <h5 id="examples-13"><a href="#examples-13">Examples</a></h5> |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code>Arg::with_name(<span class="string">"config"</span>) |
| .long(<span class="string">"config"</span>) |
| .takes_value(<span class="bool-val">true</span>) |
| .require_equals(<span class="bool-val">true</span>)</code></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"><code><span class="kw">let </span>res = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"cfg"</span>) |
| .require_equals(<span class="bool-val">true</span>) |
| .takes_value(<span class="bool-val">true</span>) |
| .long(<span class="string">"config"</span>)) |
| .get_matches_from_safe(<span class="macro">vec!</span>[ |
| <span class="string">"prog"</span>, <span class="string">"--config=file.conf" |
| </span>]); |
| |
| <span class="macro">assert!</span>(res.is_ok());</code></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"><code><span class="kw">let </span>res = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"cfg"</span>) |
| .require_equals(<span class="bool-val">true</span>) |
| .takes_value(<span class="bool-val">true</span>) |
| .long(<span class="string">"config"</span>)) |
| .get_matches_from_safe(<span class="macro">vec!</span>[ |
| <span class="string">"prog"</span>, <span class="string">"--config"</span>, <span class="string">"file.conf" |
| </span>]); |
| |
| <span class="macro">assert!</span>(res.is_err()); |
| <span class="macro">assert_eq!</span>(res.unwrap_err().kind, ErrorKind::EmptyValue);</code></pre></div> |
| </div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.allow_hyphen_values" class="method has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#891-897">source</a><h4 class="code-header">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>) -> Self</h4></section></summary><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> |
| <h5 id="examples-14"><a href="#examples-14">Examples</a></h5> |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code>Arg::with_name(<span class="string">"pattern"</span>) |
| .allow_hyphen_values(<span class="bool-val">true</span>)</code></pre></div> |
| |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">let </span>m = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"pat"</span>) |
| .allow_hyphen_values(<span class="bool-val">true</span>) |
| .takes_value(<span class="bool-val">true</span>) |
| .long(<span class="string">"pattern"</span>)) |
| .get_matches_from(<span class="macro">vec!</span>[ |
| <span class="string">"prog"</span>, <span class="string">"--pattern"</span>, <span class="string">"-file" |
| </span>]); |
| |
| <span class="macro">assert_eq!</span>(m.value_of(<span class="string">"pat"</span>), <span class="prelude-val">Some</span>(<span class="string">"-file"</span>));</code></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"><code><span class="kw">let </span>res = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"pat"</span>) |
| .takes_value(<span class="bool-val">true</span>) |
| .long(<span class="string">"pattern"</span>)) |
| .get_matches_from_safe(<span class="macro">vec!</span>[ |
| <span class="string">"prog"</span>, <span class="string">"--pattern"</span>, <span class="string">"-file" |
| </span>]); |
| |
| <span class="macro">assert!</span>(res.is_err()); |
| <span class="macro">assert_eq!</span>(res.unwrap_err().kind, ErrorKind::UnknownArgument);</code></pre></div> |
| </div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.required_unless" class="method has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#954-961">source</a><h4 class="code-header">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>) -> Self</h4></section></summary><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> |
| <h5 id="examples-15"><a href="#examples-15">Examples</a></h5> |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code>Arg::with_name(<span class="string">"config"</span>) |
| .required_unless(<span class="string">"debug"</span>)</code></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"><code><span class="kw">let </span>res = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"cfg"</span>) |
| .required_unless(<span class="string">"dbg"</span>) |
| .takes_value(<span class="bool-val">true</span>) |
| .long(<span class="string">"config"</span>)) |
| .arg(Arg::with_name(<span class="string">"dbg"</span>) |
| .long(<span class="string">"debug"</span>)) |
| .get_matches_from_safe(<span class="macro">vec!</span>[ |
| <span class="string">"prog"</span>, <span class="string">"--debug" |
| </span>]); |
| |
| <span class="macro">assert!</span>(res.is_ok());</code></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"><code><span class="kw">let </span>res = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"cfg"</span>) |
| .required_unless(<span class="string">"dbg"</span>) |
| .takes_value(<span class="bool-val">true</span>) |
| .long(<span class="string">"config"</span>)) |
| .arg(Arg::with_name(<span class="string">"dbg"</span>) |
| .long(<span class="string">"debug"</span>)) |
| .get_matches_from_safe(<span class="macro">vec!</span>[ |
| <span class="string">"prog" |
| </span>]); |
| |
| <span class="macro">assert!</span>(res.is_err()); |
| <span class="macro">assert_eq!</span>(res.unwrap_err().kind, ErrorKind::MissingRequiredArgument);</code></pre></div> |
| </div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.required_unless_all" class="method has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#1026-1036">source</a><h4 class="code-header">pub fn <a href="#method.required_unless_all" class="fnname">required_unless_all</a>(self, names: &[&'a <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.str.html">str</a>]) -> Self</h4></section></summary><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> |
| <h5 id="examples-16"><a href="#examples-16">Examples</a></h5> |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code>Arg::with_name(<span class="string">"config"</span>) |
| .required_unless_all(<span class="kw-2">&</span>[<span class="string">"cfg"</span>, <span class="string">"dbg"</span>])</code></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"><code><span class="kw">let </span>res = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"cfg"</span>) |
| .required_unless_all(<span class="kw-2">&</span>[<span class="string">"dbg"</span>, <span class="string">"infile"</span>]) |
| .takes_value(<span class="bool-val">true</span>) |
| .long(<span class="string">"config"</span>)) |
| .arg(Arg::with_name(<span class="string">"dbg"</span>) |
| .long(<span class="string">"debug"</span>)) |
| .arg(Arg::with_name(<span class="string">"infile"</span>) |
| .short(<span class="string">"i"</span>) |
| .takes_value(<span class="bool-val">true</span>)) |
| .get_matches_from_safe(<span class="macro">vec!</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>(res.is_ok());</code></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"><code><span class="kw">let </span>res = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"cfg"</span>) |
| .required_unless_all(<span class="kw-2">&</span>[<span class="string">"dbg"</span>, <span class="string">"infile"</span>]) |
| .takes_value(<span class="bool-val">true</span>) |
| .long(<span class="string">"config"</span>)) |
| .arg(Arg::with_name(<span class="string">"dbg"</span>) |
| .long(<span class="string">"debug"</span>)) |
| .arg(Arg::with_name(<span class="string">"infile"</span>) |
| .short(<span class="string">"i"</span>) |
| .takes_value(<span class="bool-val">true</span>)) |
| .get_matches_from_safe(<span class="macro">vec!</span>[ |
| <span class="string">"prog" |
| </span>]); |
| |
| <span class="macro">assert!</span>(res.is_err()); |
| <span class="macro">assert_eq!</span>(res.unwrap_err().kind, ErrorKind::MissingRequiredArgument);</code></pre></div> |
| </div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.required_unless_one" class="method has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#1102-1111">source</a><h4 class="code-header">pub fn <a href="#method.required_unless_one" class="fnname">required_unless_one</a>(self, names: &[&'a <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.str.html">str</a>]) -> Self</h4></section></summary><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> |
| <h5 id="examples-17"><a href="#examples-17">Examples</a></h5> |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code>Arg::with_name(<span class="string">"config"</span>) |
| .required_unless_all(<span class="kw-2">&</span>[<span class="string">"cfg"</span>, <span class="string">"dbg"</span>])</code></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"><code><span class="kw">let </span>res = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"cfg"</span>) |
| .required_unless_one(<span class="kw-2">&</span>[<span class="string">"dbg"</span>, <span class="string">"infile"</span>]) |
| .takes_value(<span class="bool-val">true</span>) |
| .long(<span class="string">"config"</span>)) |
| .arg(Arg::with_name(<span class="string">"dbg"</span>) |
| .long(<span class="string">"debug"</span>)) |
| .arg(Arg::with_name(<span class="string">"infile"</span>) |
| .short(<span class="string">"i"</span>) |
| .takes_value(<span class="bool-val">true</span>)) |
| .get_matches_from_safe(<span class="macro">vec!</span>[ |
| <span class="string">"prog"</span>, <span class="string">"--debug" |
| </span>]); |
| |
| <span class="macro">assert!</span>(res.is_ok());</code></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"><code><span class="kw">let </span>res = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"cfg"</span>) |
| .required_unless_one(<span class="kw-2">&</span>[<span class="string">"dbg"</span>, <span class="string">"infile"</span>]) |
| .takes_value(<span class="bool-val">true</span>) |
| .long(<span class="string">"config"</span>)) |
| .arg(Arg::with_name(<span class="string">"dbg"</span>) |
| .long(<span class="string">"debug"</span>)) |
| .arg(Arg::with_name(<span class="string">"infile"</span>) |
| .short(<span class="string">"i"</span>) |
| .takes_value(<span class="bool-val">true</span>)) |
| .get_matches_from_safe(<span class="macro">vec!</span>[ |
| <span class="string">"prog" |
| </span>]); |
| |
| <span class="macro">assert!</span>(res.is_err()); |
| <span class="macro">assert_eq!</span>(res.unwrap_err().kind, ErrorKind::MissingRequiredArgument);</code></pre></div> |
| </div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.conflicts_with" class="method has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#1150-1157">source</a><h4 class="code-header">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>) -> Self</h4></section></summary><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> |
| <h5 id="examples-18"><a href="#examples-18">Examples</a></h5> |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code>Arg::with_name(<span class="string">"config"</span>) |
| .conflicts_with(<span class="string">"debug"</span>)</code></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"><code><span class="kw">let </span>res = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"cfg"</span>) |
| .takes_value(<span class="bool-val">true</span>) |
| .conflicts_with(<span class="string">"debug"</span>) |
| .long(<span class="string">"config"</span>)) |
| .arg(Arg::with_name(<span class="string">"debug"</span>) |
| .long(<span class="string">"debug"</span>)) |
| .get_matches_from_safe(<span class="macro">vec!</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>(res.is_err()); |
| <span class="macro">assert_eq!</span>(res.unwrap_err().kind, ErrorKind::ArgumentConflict);</code></pre></div> |
| </div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.conflicts_with_all" class="method has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#1200-1209">source</a><h4 class="code-header">pub fn <a href="#method.conflicts_with_all" class="fnname">conflicts_with_all</a>(self, names: &[&'a <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.str.html">str</a>]) -> Self</h4></section></summary><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> |
| <h5 id="examples-19"><a href="#examples-19">Examples</a></h5> |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code>Arg::with_name(<span class="string">"config"</span>) |
| .conflicts_with_all(<span class="kw-2">&</span>[<span class="string">"debug"</span>, <span class="string">"input"</span>])</code></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"><code><span class="kw">let </span>res = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"cfg"</span>) |
| .takes_value(<span class="bool-val">true</span>) |
| .conflicts_with_all(<span class="kw-2">&</span>[<span class="string">"debug"</span>, <span class="string">"input"</span>]) |
| .long(<span class="string">"config"</span>)) |
| .arg(Arg::with_name(<span class="string">"debug"</span>) |
| .long(<span class="string">"debug"</span>)) |
| .arg(Arg::with_name(<span class="string">"input"</span>) |
| .index(<span class="number">1</span>)) |
| .get_matches_from_safe(<span class="macro">vec!</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>(res.is_err()); |
| <span class="macro">assert_eq!</span>(res.unwrap_err().kind, ErrorKind::ArgumentConflict);</code></pre></div> |
| </div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.overrides_with" class="method has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#1309-1316">source</a><h4 class="code-header">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>) -> Self</h4></section></summary><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> |
| <h5 id="examples-20"><a href="#examples-20">Examples</a></h5> |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">let </span>m = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::from_usage(<span class="string">"-f, --flag 'some flag'"</span>) |
| .conflicts_with(<span class="string">"debug"</span>)) |
| .arg(Arg::from_usage(<span class="string">"-d, --debug 'other flag'"</span>)) |
| .arg(Arg::from_usage(<span class="string">"-c, --color 'third flag'"</span>) |
| .overrides_with(<span class="string">"flag"</span>)) |
| .get_matches_from(<span class="macro">vec!</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>(m.is_present(<span class="string">"color"</span>)); |
| <span class="macro">assert!</span>(m.is_present(<span class="string">"debug"</span>)); <span class="comment">// even though flag conflicts with debug, it's as if flag |
| // was never used because it was overridden with color |
| </span><span class="macro">assert!</span>(!m.is_present(<span class="string">"flag"</span>));</code></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"><code><span class="kw">let </span>m = App::new(<span class="string">"posix"</span>) |
| .arg(Arg::from_usage(<span class="string">"--flag 'some flag'"</span>).overrides_with(<span class="string">"flag"</span>)) |
| .get_matches_from(<span class="macro">vec!</span>[<span class="string">"posix"</span>, <span class="string">"--flag"</span>, <span class="string">"--flag"</span>]); |
| <span class="macro">assert!</span>(m.is_present(<span class="string">"flag"</span>)); |
| <span class="macro">assert_eq!</span>(m.occurrences_of(<span class="string">"flag"</span>), <span class="number">1</span>);</code></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"><code><span class="kw">let </span>m = App::new(<span class="string">"posix"</span>) |
| .arg(Arg::from_usage(<span class="string">"--flag... 'some flag'"</span>).overrides_with(<span class="string">"flag"</span>)) |
| .get_matches_from(<span class="macro">vec!</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>(m.is_present(<span class="string">"flag"</span>)); |
| <span class="macro">assert_eq!</span>(m.occurrences_of(<span class="string">"flag"</span>), <span class="number">4</span>);</code></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"><code><span class="kw">let </span>m = App::new(<span class="string">"posix"</span>) |
| .arg(Arg::from_usage(<span class="string">"--opt [val] 'some option'"</span>).overrides_with(<span class="string">"opt"</span>)) |
| .get_matches_from(<span class="macro">vec!</span>[<span class="string">""</span>, <span class="string">"--opt=some"</span>, <span class="string">"--opt=other"</span>]); |
| <span class="macro">assert!</span>(m.is_present(<span class="string">"opt"</span>)); |
| <span class="macro">assert_eq!</span>(m.occurrences_of(<span class="string">"opt"</span>), <span class="number">1</span>); |
| <span class="macro">assert_eq!</span>(m.value_of(<span class="string">"opt"</span>), <span class="prelude-val">Some</span>(<span class="string">"other"</span>));</code></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"><code><span class="kw">let </span>m = App::new(<span class="string">"posix"</span>) |
| .arg(Arg::from_usage(<span class="string">"--opt [val]... 'some option'"</span>) |
| .overrides_with(<span class="string">"opt"</span>)) |
| .get_matches_from(<span class="macro">vec!</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>(m.is_present(<span class="string">"opt"</span>)); |
| <span class="macro">assert_eq!</span>(m.occurrences_of(<span class="string">"opt"</span>), <span class="number">2</span>); |
| <span class="macro">assert_eq!</span>(m.values_of(<span class="string">"opt"</span>).unwrap().collect::<Vec<<span class="kw">_</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>]);</code></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"><code><span class="kw">let </span>m = App::new(<span class="string">"posix"</span>) |
| .arg(Arg::from_usage(<span class="string">"--opt [val] 'some option'"</span>) |
| .overrides_with(<span class="string">"opt"</span>) |
| .use_delimiter(<span class="bool-val">false</span>)) |
| .get_matches_from(<span class="macro">vec!</span>[<span class="string">""</span>, <span class="string">"--opt=some,other"</span>, <span class="string">"--opt=one,two"</span>]); |
| <span class="macro">assert!</span>(m.is_present(<span class="string">"opt"</span>)); |
| <span class="macro">assert_eq!</span>(m.occurrences_of(<span class="string">"opt"</span>), <span class="number">1</span>); |
| <span class="macro">assert_eq!</span>(m.values_of(<span class="string">"opt"</span>).unwrap().collect::<Vec<<span class="kw">_</span>>>(), <span class="kw-2">&</span>[<span class="string">"one,two"</span>]);</code></pre></div> |
| </div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.overrides_with_all" class="method has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#1345-1354">source</a><h4 class="code-header">pub fn <a href="#method.overrides_with_all" class="fnname">overrides_with_all</a>(self, names: &[&'a <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.str.html">str</a>]) -> Self</h4></section></summary><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> |
| <h5 id="examples-21"><a href="#examples-21">Examples</a></h5> |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">let </span>m = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::from_usage(<span class="string">"-f, --flag 'some flag'"</span>) |
| .conflicts_with(<span class="string">"color"</span>)) |
| .arg(Arg::from_usage(<span class="string">"-d, --debug 'other flag'"</span>)) |
| .arg(Arg::from_usage(<span class="string">"-c, --color 'third flag'"</span>) |
| .overrides_with_all(<span class="kw-2">&</span>[<span class="string">"flag"</span>, <span class="string">"debug"</span>])) |
| .get_matches_from(<span class="macro">vec!</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>(m.is_present(<span class="string">"color"</span>)); <span class="comment">// even though flag conflicts with color, it's as if flag |
| // and debug were never used because they were overridden |
| // with color |
| </span><span class="macro">assert!</span>(!m.is_present(<span class="string">"debug"</span>)); |
| <span class="macro">assert!</span>(!m.is_present(<span class="string">"flag"</span>));</code></pre></div> |
| </div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.requires" class="method has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#1411-1418">source</a><h4 class="code-header">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>) -> Self</h4></section></summary><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> |
| <h5 id="examples-22"><a href="#examples-22">Examples</a></h5> |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code>Arg::with_name(<span class="string">"config"</span>) |
| .requires(<span class="string">"input"</span>)</code></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"><code><span class="kw">let </span>res = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"cfg"</span>) |
| .takes_value(<span class="bool-val">true</span>) |
| .requires(<span class="string">"input"</span>) |
| .long(<span class="string">"config"</span>)) |
| .arg(Arg::with_name(<span class="string">"input"</span>) |
| .index(<span class="number">1</span>)) |
| .get_matches_from_safe(<span class="macro">vec!</span>[ |
| <span class="string">"prog" |
| </span>]); |
| |
| <span class="macro">assert!</span>(res.is_ok()); <span class="comment">// We didn't use cfg, so input wasn't required</span></code></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"><code><span class="kw">let </span>res = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"cfg"</span>) |
| .takes_value(<span class="bool-val">true</span>) |
| .requires(<span class="string">"input"</span>) |
| .long(<span class="string">"config"</span>)) |
| .arg(Arg::with_name(<span class="string">"input"</span>) |
| .index(<span class="number">1</span>)) |
| .get_matches_from_safe(<span class="macro">vec!</span>[ |
| <span class="string">"prog"</span>, <span class="string">"--config"</span>, <span class="string">"file.conf" |
| </span>]); |
| |
| <span class="macro">assert!</span>(res.is_err()); |
| <span class="macro">assert_eq!</span>(res.unwrap_err().kind, ErrorKind::MissingRequiredArgument);</code></pre></div> |
| </div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.requires_if" class="method has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#1479-1486">source</a><h4 class="code-header">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>) -> Self</h4></section></summary><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> |
| <div class="example-wrap"><pre class="language-yaml"><code>requires_if: |
| - [val, arg]</code></pre></div><h5 id="examples-23"><a href="#examples-23">Examples</a></h5> |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code>Arg::with_name(<span class="string">"config"</span>) |
| .requires_if(<span class="string">"val"</span>, <span class="string">"arg"</span>)</code></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"><code><span class="kw">let </span>res = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"cfg"</span>) |
| .takes_value(<span class="bool-val">true</span>) |
| .requires_if(<span class="string">"my.cfg"</span>, <span class="string">"other"</span>) |
| .long(<span class="string">"config"</span>)) |
| .arg(Arg::with_name(<span class="string">"other"</span>)) |
| .get_matches_from_safe(<span class="macro">vec!</span>[ |
| <span class="string">"prog"</span>, <span class="string">"--config"</span>, <span class="string">"some.cfg" |
| </span>]); |
| |
| <span class="macro">assert!</span>(res.is_ok()); <span class="comment">// We didn't use --config=my.cfg, so other wasn't required</span></code></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"><code><span class="kw">let </span>res = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"cfg"</span>) |
| .takes_value(<span class="bool-val">true</span>) |
| .requires_if(<span class="string">"my.cfg"</span>, <span class="string">"input"</span>) |
| .long(<span class="string">"config"</span>)) |
| .arg(Arg::with_name(<span class="string">"input"</span>)) |
| .get_matches_from_safe(<span class="macro">vec!</span>[ |
| <span class="string">"prog"</span>, <span class="string">"--config"</span>, <span class="string">"my.cfg" |
| </span>]); |
| |
| <span class="macro">assert!</span>(res.is_err()); |
| <span class="macro">assert_eq!</span>(res.unwrap_err().kind, ErrorKind::MissingRequiredArgument);</code></pre></div> |
| </div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.requires_ifs" class="method has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#1539-1552">source</a><h4 class="code-header">pub fn <a href="#method.requires_ifs" class="fnname">requires_ifs</a>(self, ifs: &[(&'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>)]) -> Self</h4></section></summary><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> |
| <div class="example-wrap"><pre class="language-yaml"><code>requires_if: |
| - [val, arg] |
| - [val2, arg2]</code></pre></div><h5 id="examples-24"><a href="#examples-24">Examples</a></h5> |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code>Arg::with_name(<span class="string">"config"</span>) |
| .requires_ifs(<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>), |
| ])</code></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"><code><span class="kw">let </span>res = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"cfg"</span>) |
| .takes_value(<span class="bool-val">true</span>) |
| .requires_ifs(<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>), |
| ]) |
| .long(<span class="string">"config"</span>)) |
| .arg(Arg::with_name(<span class="string">"opt"</span>) |
| .long(<span class="string">"option"</span>) |
| .takes_value(<span class="bool-val">true</span>)) |
| .arg(Arg::with_name(<span class="string">"other"</span>)) |
| .get_matches_from_safe(<span class="macro">vec!</span>[ |
| <span class="string">"prog"</span>, <span class="string">"--config"</span>, <span class="string">"special.conf" |
| </span>]); |
| |
| <span class="macro">assert!</span>(res.is_err()); <span class="comment">// We used --config=special.conf so --option <val> is required |
| </span><span class="macro">assert_eq!</span>(res.unwrap_err().kind, ErrorKind::MissingRequiredArgument);</code></pre></div> |
| </div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.required_if" class="method has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#1617-1624">source</a><h4 class="code-header">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>) -> Self</h4></section></summary><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> |
| <div class="example-wrap"><pre class="language-yaml"><code>required_if: |
| - [arg, val]</code></pre></div><h5 id="examples-25"><a href="#examples-25">Examples</a></h5> |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code>Arg::with_name(<span class="string">"config"</span>) |
| .required_if(<span class="string">"other_arg"</span>, <span class="string">"value"</span>)</code></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"><code><span class="kw">let </span>res = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"cfg"</span>) |
| .takes_value(<span class="bool-val">true</span>) |
| .required_if(<span class="string">"other"</span>, <span class="string">"special"</span>) |
| .long(<span class="string">"config"</span>)) |
| .arg(Arg::with_name(<span class="string">"other"</span>) |
| .long(<span class="string">"other"</span>) |
| .takes_value(<span class="bool-val">true</span>)) |
| .get_matches_from_safe(<span class="macro">vec!</span>[ |
| <span class="string">"prog"</span>, <span class="string">"--other"</span>, <span class="string">"not-special" |
| </span>]); |
| |
| <span class="macro">assert!</span>(res.is_ok()); <span class="comment">// We didn't use --other=special, so "cfg" wasn't required</span></code></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"><code><span class="kw">let </span>res = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"cfg"</span>) |
| .takes_value(<span class="bool-val">true</span>) |
| .required_if(<span class="string">"other"</span>, <span class="string">"special"</span>) |
| .long(<span class="string">"config"</span>)) |
| .arg(Arg::with_name(<span class="string">"other"</span>) |
| .long(<span class="string">"other"</span>) |
| .takes_value(<span class="bool-val">true</span>)) |
| .get_matches_from_safe(<span class="macro">vec!</span>[ |
| <span class="string">"prog"</span>, <span class="string">"--other"</span>, <span class="string">"special" |
| </span>]); |
| |
| <span class="macro">assert!</span>(res.is_err()); |
| <span class="macro">assert_eq!</span>(res.unwrap_err().kind, ErrorKind::MissingRequiredArgument);</code></pre></div> |
| </div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.required_ifs" class="method has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#1706-1719">source</a><h4 class="code-header">pub fn <a href="#method.required_ifs" class="fnname">required_ifs</a>(self, ifs: &[(&'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>)]) -> Self</h4></section></summary><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> |
| <div class="example-wrap"><pre class="language-yaml"><code>required_if: |
| - [arg, val] |
| - [arg2, val2]</code></pre></div><h5 id="examples-26"><a href="#examples-26">Examples</a></h5> |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code>Arg::with_name(<span class="string">"config"</span>) |
| .required_ifs(<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>) |
| ])</code></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"><code><span class="kw">let </span>res = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"cfg"</span>) |
| .required_ifs(<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>) |
| ]) |
| .takes_value(<span class="bool-val">true</span>) |
| .long(<span class="string">"config"</span>)) |
| .arg(Arg::with_name(<span class="string">"extra"</span>) |
| .takes_value(<span class="bool-val">true</span>) |
| .long(<span class="string">"extra"</span>)) |
| .arg(Arg::with_name(<span class="string">"option"</span>) |
| .takes_value(<span class="bool-val">true</span>) |
| .long(<span class="string">"option"</span>)) |
| .get_matches_from_safe(<span class="macro">vec!</span>[ |
| <span class="string">"prog"</span>, <span class="string">"--option"</span>, <span class="string">"other" |
| </span>]); |
| |
| <span class="macro">assert!</span>(res.is_ok()); <span class="comment">// We didn't use --option=spec, or --extra=val so "cfg" isn't required</span></code></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"><code><span class="kw">let </span>res = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"cfg"</span>) |
| .required_ifs(<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>) |
| ]) |
| .takes_value(<span class="bool-val">true</span>) |
| .long(<span class="string">"config"</span>)) |
| .arg(Arg::with_name(<span class="string">"extra"</span>) |
| .takes_value(<span class="bool-val">true</span>) |
| .long(<span class="string">"extra"</span>)) |
| .arg(Arg::with_name(<span class="string">"option"</span>) |
| .takes_value(<span class="bool-val">true</span>) |
| .long(<span class="string">"option"</span>)) |
| .get_matches_from_safe(<span class="macro">vec!</span>[ |
| <span class="string">"prog"</span>, <span class="string">"--option"</span>, <span class="string">"spec" |
| </span>]); |
| |
| <span class="macro">assert!</span>(res.is_err()); |
| <span class="macro">assert_eq!</span>(res.unwrap_err().kind, ErrorKind::MissingRequiredArgument);</code></pre></div> |
| </div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.requires_all" class="method has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#1783-1796">source</a><h4 class="code-header">pub fn <a href="#method.requires_all" class="fnname">requires_all</a>(self, names: &[&'a <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.str.html">str</a>]) -> Self</h4></section></summary><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> |
| <h5 id="examples-27"><a href="#examples-27">Examples</a></h5> |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code>Arg::with_name(<span class="string">"config"</span>) |
| .requires_all(<span class="kw-2">&</span>[<span class="string">"input"</span>, <span class="string">"output"</span>])</code></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"><code><span class="kw">let </span>res = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"cfg"</span>) |
| .takes_value(<span class="bool-val">true</span>) |
| .requires(<span class="string">"input"</span>) |
| .long(<span class="string">"config"</span>)) |
| .arg(Arg::with_name(<span class="string">"input"</span>) |
| .index(<span class="number">1</span>)) |
| .arg(Arg::with_name(<span class="string">"output"</span>) |
| .index(<span class="number">2</span>)) |
| .get_matches_from_safe(<span class="macro">vec!</span>[ |
| <span class="string">"prog" |
| </span>]); |
| |
| <span class="macro">assert!</span>(res.is_ok()); <span class="comment">// We didn't use cfg, so input and output weren't required</span></code></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"><code><span class="kw">let </span>res = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"cfg"</span>) |
| .takes_value(<span class="bool-val">true</span>) |
| .requires_all(<span class="kw-2">&</span>[<span class="string">"input"</span>, <span class="string">"output"</span>]) |
| .long(<span class="string">"config"</span>)) |
| .arg(Arg::with_name(<span class="string">"input"</span>) |
| .index(<span class="number">1</span>)) |
| .arg(Arg::with_name(<span class="string">"output"</span>) |
| .index(<span class="number">2</span>)) |
| .get_matches_from_safe(<span class="macro">vec!</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>(res.is_err()); |
| <span class="comment">// We didn't use output |
| </span><span class="macro">assert_eq!</span>(res.unwrap_err().kind, ErrorKind::MissingRequiredArgument);</code></pre></div> |
| <p>[<code>Arg::requires_all(&[arg, arg2])</code>]: ./struct.Arg.html#method.requires_all</p> |
| </div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.takes_value" class="method has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#1836-1842">source</a><h4 class="code-header">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>) -> Self</h4></section></summary><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> |
| <h5 id="examples-28"><a href="#examples-28">Examples</a></h5> |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code>Arg::with_name(<span class="string">"config"</span>) |
| .takes_value(<span class="bool-val">true</span>)</code></pre></div> |
| |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">let </span>m = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"mode"</span>) |
| .long(<span class="string">"mode"</span>) |
| .takes_value(<span class="bool-val">true</span>)) |
| .get_matches_from(<span class="macro">vec!</span>[ |
| <span class="string">"prog"</span>, <span class="string">"--mode"</span>, <span class="string">"fast" |
| </span>]); |
| |
| <span class="macro">assert!</span>(m.is_present(<span class="string">"mode"</span>)); |
| <span class="macro">assert_eq!</span>(m.value_of(<span class="string">"mode"</span>), <span class="prelude-val">Some</span>(<span class="string">"fast"</span>));</code></pre></div> |
| </div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.hide_possible_values" class="method has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#1872-1878">source</a><h4 class="code-header">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>) -> Self</h4></section></summary><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> |
| <h5 id="examples-29"><a href="#examples-29">Examples</a></h5> |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code>Arg::with_name(<span class="string">"config"</span>) |
| .hide_possible_values(<span class="bool-val">true</span>)</code></pre></div> |
| |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">let </span>m = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"mode"</span>) |
| .long(<span class="string">"mode"</span>) |
| .possible_values(<span class="kw-2">&</span>[<span class="string">"fast"</span>, <span class="string">"slow"</span>]) |
| .takes_value(<span class="bool-val">true</span>) |
| .hide_possible_values(<span class="bool-val">true</span>)); |
| </code></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></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.hide_default_value" class="method has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#1906-1912">source</a><h4 class="code-header">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>) -> Self</h4></section></summary><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> |
| <h5 id="examples-30"><a href="#examples-30">Examples</a></h5> |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code>Arg::with_name(<span class="string">"config"</span>) |
| .hide_default_value(<span class="bool-val">true</span>)</code></pre></div> |
| |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">let </span>m = App::new(<span class="string">"connect"</span>) |
| .arg(Arg::with_name(<span class="string">"host"</span>) |
| .long(<span class="string">"host"</span>) |
| .default_value(<span class="string">"localhost"</span>) |
| .hide_default_value(<span class="bool-val">true</span>)); |
| </code></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></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.index" class="method has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#1961-1964">source</a><h4 class="code-header">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>) -> Self</h4></section></summary><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> |
| <h5 id="panics"><a href="#panics">Panics</a></h5> |
| <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> |
| <h5 id="examples-31"><a href="#examples-31">Examples</a></h5> |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code>Arg::with_name(<span class="string">"config"</span>) |
| .index(<span class="number">1</span>)</code></pre></div> |
| |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">let </span>m = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"mode"</span>) |
| .index(<span class="number">1</span>)) |
| .arg(Arg::with_name(<span class="string">"debug"</span>) |
| .long(<span class="string">"debug"</span>)) |
| .get_matches_from(<span class="macro">vec!</span>[ |
| <span class="string">"prog"</span>, <span class="string">"--debug"</span>, <span class="string">"fast" |
| </span>]); |
| |
| <span class="macro">assert!</span>(m.is_present(<span class="string">"mode"</span>)); |
| <span class="macro">assert_eq!</span>(m.value_of(<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" |
| // *not* first argument</span></code></pre></div> |
| </div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.multiple" class="method has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#2157-2163">source</a><h4 class="code-header">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>) -> Self</h4></section></summary><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> |
| <div class="example-wrap"><pre class="language-notrust"><code>$ program --ui-paths path1 path2 signer</code></pre></div> |
| <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> |
| <div class="example-wrap"><pre class="language-notrust"><code>$ program --ui-paths path1 signer |
| $ program --ui-paths path1 --ui-paths signer signer</code></pre></div><h5 id="examples-32"><a href="#examples-32">Examples</a></h5> |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code>Arg::with_name(<span class="string">"debug"</span>) |
| .short(<span class="string">"d"</span>) |
| .multiple(<span class="bool-val">true</span>)</code></pre></div> |
| <p>An example with flags</p> |
| |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">let </span>m = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"verbose"</span>) |
| .multiple(<span class="bool-val">true</span>) |
| .short(<span class="string">"v"</span>)) |
| .get_matches_from(<span class="macro">vec!</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>(m.is_present(<span class="string">"verbose"</span>)); |
| <span class="macro">assert_eq!</span>(m.occurrences_of(<span class="string">"verbose"</span>), <span class="number">3</span>);</code></pre></div> |
| <p>An example with options</p> |
| |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">let </span>m = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"file"</span>) |
| .multiple(<span class="bool-val">true</span>) |
| .takes_value(<span class="bool-val">true</span>) |
| .short(<span class="string">"F"</span>)) |
| .get_matches_from(<span class="macro">vec!</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>(m.is_present(<span class="string">"file"</span>)); |
| <span class="macro">assert_eq!</span>(m.occurrences_of(<span class="string">"file"</span>), <span class="number">1</span>); <span class="comment">// notice only one occurrence |
| </span><span class="kw">let </span>files: Vec<<span class="kw">_</span>> = m.values_of(<span class="string">"file"</span>).unwrap().collect(); |
| <span class="macro">assert_eq!</span>(files, [<span class="string">"file1"</span>, <span class="string">"file2"</span>, <span class="string">"file3"</span>]);</code></pre></div> |
| <p>This is functionally equivalent to the example above</p> |
| |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">let </span>m = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"file"</span>) |
| .multiple(<span class="bool-val">true</span>) |
| .takes_value(<span class="bool-val">true</span>) |
| .short(<span class="string">"F"</span>)) |
| .get_matches_from(<span class="macro">vec!</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>files: Vec<<span class="kw">_</span>> = m.values_of(<span class="string">"file"</span>).unwrap().collect(); |
| <span class="macro">assert_eq!</span>(files, [<span class="string">"file1"</span>, <span class="string">"file2"</span>, <span class="string">"file3"</span>]); |
| |
| <span class="macro">assert!</span>(m.is_present(<span class="string">"file"</span>)); |
| <span class="macro">assert_eq!</span>(m.occurrences_of(<span class="string">"file"</span>), <span class="number">3</span>); <span class="comment">// Notice 3 occurrences |
| </span><span class="kw">let </span>files: Vec<<span class="kw">_</span>> = m.values_of(<span class="string">"file"</span>).unwrap().collect(); |
| <span class="macro">assert_eq!</span>(files, [<span class="string">"file1"</span>, <span class="string">"file2"</span>, <span class="string">"file3"</span>]);</code></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"><code><span class="kw">let </span>m = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"file"</span>) |
| .multiple(<span class="bool-val">true</span>) |
| .takes_value(<span class="bool-val">true</span>) |
| .short(<span class="string">"F"</span>)) |
| .arg(Arg::with_name(<span class="string">"word"</span>) |
| .index(<span class="number">1</span>)) |
| .get_matches_from(<span class="macro">vec!</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>(m.is_present(<span class="string">"file"</span>)); |
| <span class="kw">let </span>files: Vec<<span class="kw">_</span>> = m.values_of(<span class="string">"file"</span>).unwrap().collect(); |
| <span class="macro">assert_eq!</span>(files, [<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>(!m.is_present(<span class="string">"word"</span>)); <span class="comment">// but we clearly used word!</span></code></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"><code><span class="kw">let </span>m = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"file"</span>) |
| .multiple(<span class="bool-val">true</span>) |
| .takes_value(<span class="bool-val">true</span>) |
| .number_of_values(<span class="number">1</span>) |
| .short(<span class="string">"F"</span>)) |
| .arg(Arg::with_name(<span class="string">"word"</span>) |
| .index(<span class="number">1</span>)) |
| .get_matches_from(<span class="macro">vec!</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>(m.is_present(<span class="string">"file"</span>)); |
| <span class="kw">let </span>files: Vec<<span class="kw">_</span>> = m.values_of(<span class="string">"file"</span>).unwrap().collect(); |
| <span class="macro">assert_eq!</span>(files, [<span class="string">"file1"</span>, <span class="string">"file2"</span>, <span class="string">"file3"</span>]); |
| <span class="macro">assert!</span>(m.is_present(<span class="string">"word"</span>)); |
| <span class="macro">assert_eq!</span>(m.value_of(<span class="string">"word"</span>), <span class="prelude-val">Some</span>(<span class="string">"word"</span>));</code></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"><code><span class="kw">let </span>res = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"file"</span>) |
| .multiple(<span class="bool-val">true</span>) |
| .takes_value(<span class="bool-val">true</span>) |
| .number_of_values(<span class="number">1</span>) |
| .short(<span class="string">"F"</span>)) |
| .arg(Arg::with_name(<span class="string">"word"</span>) |
| .index(<span class="number">1</span>)) |
| .get_matches_from_safe(<span class="macro">vec!</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>(res.is_err()); |
| <span class="macro">assert_eq!</span>(res.unwrap_err().kind, ErrorKind::UnknownArgument);</code></pre></div> |
| </div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.value_terminator" class="method has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#2210-2214">source</a><h4 class="code-header">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>) -> Self</h4></section></summary><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> |
| <h5 id="examples-33"><a href="#examples-33">Examples</a></h5> |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code>Arg::with_name(<span class="string">"vals"</span>) |
| .takes_value(<span class="bool-val">true</span>) |
| .multiple(<span class="bool-val">true</span>) |
| .value_terminator(<span class="string">";"</span>)</code></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"><code><span class="kw">let </span>m = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"cmds"</span>) |
| .multiple(<span class="bool-val">true</span>) |
| .allow_hyphen_values(<span class="bool-val">true</span>) |
| .value_terminator(<span class="string">";"</span>)) |
| .arg(Arg::with_name(<span class="string">"location"</span>)) |
| .get_matches_from(<span class="macro">vec!</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>cmds: Vec<<span class="kw">_</span>> = m.values_of(<span class="string">"cmds"</span>).unwrap().collect(); |
| <span class="macro">assert_eq!</span>(<span class="kw-2">&</span>cmds, <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>(m.value_of(<span class="string">"location"</span>), <span class="prelude-val">Some</span>(<span class="string">"/home/clap"</span>));</code></pre></div> |
| </div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.global" class="method has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#2259-2265">source</a><h4 class="code-header">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>) -> Self</h4></section></summary><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> |
| <h5 id="examples-34"><a href="#examples-34">Examples</a></h5> |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code>Arg::with_name(<span class="string">"debug"</span>) |
| .short(<span class="string">"d"</span>) |
| .global(<span class="bool-val">true</span>)</code></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"><code><span class="kw">let </span>m = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"verb"</span>) |
| .long(<span class="string">"verbose"</span>) |
| .short(<span class="string">"v"</span>) |
| .global(<span class="bool-val">true</span>)) |
| .subcommand(SubCommand::with_name(<span class="string">"test"</span>)) |
| .subcommand(SubCommand::with_name(<span class="string">"do-stuff"</span>)) |
| .get_matches_from(<span class="macro">vec!</span>[ |
| <span class="string">"prog"</span>, <span class="string">"do-stuff"</span>, <span class="string">"--verbose" |
| </span>]); |
| |
| <span class="macro">assert_eq!</span>(m.subcommand_name(), <span class="prelude-val">Some</span>(<span class="string">"do-stuff"</span>)); |
| <span class="kw">let </span>sub_m = m.subcommand_matches(<span class="string">"do-stuff"</span>).unwrap(); |
| <span class="macro">assert!</span>(sub_m.is_present(<span class="string">"verb"</span>));</code></pre></div> |
| </div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.empty_values" class="method has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#2301-2308">source</a><h4 class="code-header">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>) -> Self</h4></section></summary><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> |
| <h5 id="examples-35"><a href="#examples-35">Examples</a></h5> |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code>Arg::with_name(<span class="string">"file"</span>) |
| .long(<span class="string">"file"</span>) |
| .empty_values(<span class="bool-val">false</span>)</code></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"><code><span class="kw">let </span>res = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"cfg"</span>) |
| .long(<span class="string">"config"</span>) |
| .short(<span class="string">"v"</span>) |
| .empty_values(<span class="bool-val">false</span>)) |
| .get_matches_from_safe(<span class="macro">vec!</span>[ |
| <span class="string">"prog"</span>, <span class="string">"--config=" |
| </span>]); |
| |
| <span class="macro">assert!</span>(res.is_err()); |
| <span class="macro">assert_eq!</span>(res.unwrap_err().kind, ErrorKind::EmptyValue);</code></pre></div> |
| </div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.hidden" class="method has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#2353-2359">source</a><h4 class="code-header">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>) -> Self</h4></section></summary><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> |
| <h5 id="examples-36"><a href="#examples-36">Examples</a></h5> |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code>Arg::with_name(<span class="string">"debug"</span>) |
| .hidden(<span class="bool-val">true</span>)</code></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"><code><span class="kw">let </span>m = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"cfg"</span>) |
| .long(<span class="string">"config"</span>) |
| .hidden(<span class="bool-val">true</span>) |
| .help(<span class="string">"Some help text describing the --config arg"</span>)) |
| .get_matches_from(<span class="macro">vec!</span>[ |
| <span class="string">"prog"</span>, <span class="string">"--help" |
| </span>]);</code></pre></div> |
| <p>The above example displays</p> |
| <div class="example-wrap"><pre class="language-notrust"><code>helptest |
| |
| USAGE: |
| helptest [FLAGS] |
| |
| FLAGS: |
| -h, --help Prints help information |
| -V, --version Prints version information</code></pre></div></div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.possible_values" class="method has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#2408-2417">source</a><h4 class="code-header">pub fn <a href="#method.possible_values" class="fnname">possible_values</a>(self, names: &[&'b <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.str.html">str</a>]) -> Self</h4></section></summary><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> |
| <h5 id="examples-37"><a href="#examples-37">Examples</a></h5> |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code>Arg::with_name(<span class="string">"mode"</span>) |
| .takes_value(<span class="bool-val">true</span>) |
| .possible_values(<span class="kw-2">&</span>[<span class="string">"fast"</span>, <span class="string">"slow"</span>, <span class="string">"medium"</span>])</code></pre></div> |
| |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">let </span>m = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"mode"</span>) |
| .long(<span class="string">"mode"</span>) |
| .takes_value(<span class="bool-val">true</span>) |
| .possible_values(<span class="kw-2">&</span>[<span class="string">"fast"</span>, <span class="string">"slow"</span>, <span class="string">"medium"</span>])) |
| .get_matches_from(<span class="macro">vec!</span>[ |
| <span class="string">"prog"</span>, <span class="string">"--mode"</span>, <span class="string">"fast" |
| </span>]); |
| <span class="macro">assert!</span>(m.is_present(<span class="string">"mode"</span>)); |
| <span class="macro">assert_eq!</span>(m.value_of(<span class="string">"mode"</span>), <span class="prelude-val">Some</span>(<span class="string">"fast"</span>));</code></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"><code><span class="kw">let </span>res = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"mode"</span>) |
| .long(<span class="string">"mode"</span>) |
| .takes_value(<span class="bool-val">true</span>) |
| .possible_values(<span class="kw-2">&</span>[<span class="string">"fast"</span>, <span class="string">"slow"</span>, <span class="string">"medium"</span>])) |
| .get_matches_from_safe(<span class="macro">vec!</span>[ |
| <span class="string">"prog"</span>, <span class="string">"--mode"</span>, <span class="string">"wrong" |
| </span>]); |
| <span class="macro">assert!</span>(res.is_err()); |
| <span class="macro">assert_eq!</span>(res.unwrap_err().kind, ErrorKind::InvalidValue);</code></pre></div> |
| </div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.possible_value" class="method has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#2472-2479">source</a><h4 class="code-header">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>) -> Self</h4></section></summary><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> |
| <h5 id="examples-38"><a href="#examples-38">Examples</a></h5> |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code>Arg::with_name(<span class="string">"mode"</span>) |
| .takes_value(<span class="bool-val">true</span>) |
| .possible_value(<span class="string">"fast"</span>) |
| .possible_value(<span class="string">"slow"</span>) |
| .possible_value(<span class="string">"medium"</span>)</code></pre></div> |
| |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">let </span>m = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"mode"</span>) |
| .long(<span class="string">"mode"</span>) |
| .takes_value(<span class="bool-val">true</span>) |
| .possible_value(<span class="string">"fast"</span>) |
| .possible_value(<span class="string">"slow"</span>) |
| .possible_value(<span class="string">"medium"</span>)) |
| .get_matches_from(<span class="macro">vec!</span>[ |
| <span class="string">"prog"</span>, <span class="string">"--mode"</span>, <span class="string">"fast" |
| </span>]); |
| <span class="macro">assert!</span>(m.is_present(<span class="string">"mode"</span>)); |
| <span class="macro">assert_eq!</span>(m.value_of(<span class="string">"mode"</span>), <span class="prelude-val">Some</span>(<span class="string">"fast"</span>));</code></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"><code><span class="kw">let </span>res = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"mode"</span>) |
| .long(<span class="string">"mode"</span>) |
| .takes_value(<span class="bool-val">true</span>) |
| .possible_value(<span class="string">"fast"</span>) |
| .possible_value(<span class="string">"slow"</span>) |
| .possible_value(<span class="string">"medium"</span>)) |
| .get_matches_from_safe(<span class="macro">vec!</span>[ |
| <span class="string">"prog"</span>, <span class="string">"--mode"</span>, <span class="string">"wrong" |
| </span>]); |
| <span class="macro">assert!</span>(res.is_err()); |
| <span class="macro">assert_eq!</span>(res.unwrap_err().kind, ErrorKind::InvalidValue);</code></pre></div> |
| </div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.case_insensitive" class="method has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#2526-2532">source</a><h4 class="code-header">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>) -> Self</h4></section></summary><div class="docblock"><p>When used with <a href="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> |
| <h5 id="examples-39"><a href="#examples-39">Examples</a></h5> |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">let </span>m = App::new(<span class="string">"pv"</span>) |
| .arg(Arg::with_name(<span class="string">"option"</span>) |
| .long(<span class="string">"--option"</span>) |
| .takes_value(<span class="bool-val">true</span>) |
| .possible_value(<span class="string">"test123"</span>) |
| .case_insensitive(<span class="bool-val">true</span>)) |
| .get_matches_from(<span class="macro">vec!</span>[ |
| <span class="string">"pv"</span>, <span class="string">"--option"</span>, <span class="string">"TeSt123"</span>, |
| ]); |
| |
| <span class="macro">assert!</span>(m.value_of(<span class="string">"option"</span>).unwrap().eq_ignore_ascii_case(<span class="string">"test123"</span>));</code></pre></div> |
| <p>This setting also works when multiple values can be defined:</p> |
| |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">let </span>m = App::new(<span class="string">"pv"</span>) |
| .arg(Arg::with_name(<span class="string">"option"</span>) |
| .short(<span class="string">"-o"</span>) |
| .long(<span class="string">"--option"</span>) |
| .takes_value(<span class="bool-val">true</span>) |
| .possible_value(<span class="string">"test123"</span>) |
| .possible_value(<span class="string">"test321"</span>) |
| .multiple(<span class="bool-val">true</span>) |
| .case_insensitive(<span class="bool-val">true</span>)) |
| .get_matches_from(<span class="macro">vec!</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>matched_vals = m.values_of(<span class="string">"option"</span>).unwrap().collect::<Vec<<span class="kw">_</span>>>(); |
| <span class="macro">assert_eq!</span>(<span class="kw-2">&*</span>matched_vals, <span class="kw-2">&</span>[<span class="string">"TeSt123"</span>, <span class="string">"teST123"</span>, <span class="string">"tESt321"</span>]);</code></pre></div> |
| </div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.group" class="method has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#2564-2571">source</a><h4 class="code-header">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>) -> Self</h4></section></summary><div class="docblock"><p>Specifies the name of the <a href="./struct.ArgGroup.html"><code>ArgGroup</code></a> the argument belongs to.</p> |
| <h5 id="examples-40"><a href="#examples-40">Examples</a></h5> |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code>Arg::with_name(<span class="string">"debug"</span>) |
| .long(<span class="string">"debug"</span>) |
| .group(<span class="string">"mode"</span>)</code></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"><code><span class="kw">let </span>m = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"debug"</span>) |
| .long(<span class="string">"debug"</span>) |
| .group(<span class="string">"mode"</span>)) |
| .arg(Arg::with_name(<span class="string">"verbose"</span>) |
| .long(<span class="string">"verbose"</span>) |
| .group(<span class="string">"mode"</span>)) |
| .get_matches_from(<span class="macro">vec!</span>[ |
| <span class="string">"prog"</span>, <span class="string">"--debug" |
| </span>]); |
| <span class="macro">assert!</span>(m.is_present(<span class="string">"mode"</span>));</code></pre></div> |
| </div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.groups" class="method has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#2604-2613">source</a><h4 class="code-header">pub fn <a href="#method.groups" class="fnname">groups</a>(self, names: &[&'a <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.str.html">str</a>]) -> Self</h4></section></summary><div class="docblock"><p>Specifies the names of multiple <a href="./struct.ArgGroup.html"><code>ArgGroup</code></a>’s the argument belongs to.</p> |
| <h5 id="examples-41"><a href="#examples-41">Examples</a></h5> |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code>Arg::with_name(<span class="string">"debug"</span>) |
| .long(<span class="string">"debug"</span>) |
| .groups(<span class="kw-2">&</span>[<span class="string">"mode"</span>, <span class="string">"verbosity"</span>])</code></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"><code><span class="kw">let </span>m = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"debug"</span>) |
| .long(<span class="string">"debug"</span>) |
| .groups(<span class="kw-2">&</span>[<span class="string">"mode"</span>, <span class="string">"verbosity"</span>])) |
| .arg(Arg::with_name(<span class="string">"verbose"</span>) |
| .long(<span class="string">"verbose"</span>) |
| .groups(<span class="kw-2">&</span>[<span class="string">"mode"</span>, <span class="string">"verbosity"</span>])) |
| .get_matches_from(<span class="macro">vec!</span>[ |
| <span class="string">"prog"</span>, <span class="string">"--debug" |
| </span>]); |
| <span class="macro">assert!</span>(m.is_present(<span class="string">"mode"</span>)); |
| <span class="macro">assert!</span>(m.is_present(<span class="string">"verbosity"</span>));</code></pre></div> |
| </div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.number_of_values" class="method has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#2651-2655">source</a><h4 class="code-header">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>) -> Self</h4></section></summary><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> |
| <h5 id="examples-42"><a href="#examples-42">Examples</a></h5> |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code>Arg::with_name(<span class="string">"file"</span>) |
| .short(<span class="string">"f"</span>) |
| .number_of_values(<span class="number">3</span>)</code></pre></div> |
| <p>Not supplying the correct number of values is an error</p> |
| |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">let </span>res = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"file"</span>) |
| .takes_value(<span class="bool-val">true</span>) |
| .number_of_values(<span class="number">2</span>) |
| .short(<span class="string">"F"</span>)) |
| .get_matches_from_safe(<span class="macro">vec!</span>[ |
| <span class="string">"prog"</span>, <span class="string">"-F"</span>, <span class="string">"file1" |
| </span>]); |
| |
| <span class="macro">assert!</span>(res.is_err()); |
| <span class="macro">assert_eq!</span>(res.unwrap_err().kind, ErrorKind::WrongNumberOfValues);</code></pre></div> |
| </div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.validator" class="method has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#2693-2699">source</a><h4 class="code-header">pub fn <a href="#method.validator" class="fnname">validator</a><F>(self, f: F) -> Self<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></h4></section></summary><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> |
| <h5 id="examples-43"><a href="#examples-43">Examples</a></h5> |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">fn </span>has_at(v: String) -> <span class="prelude-ty">Result</span><(), String> { |
| <span class="kw">if </span>v.contains(<span class="string">"@"</span>) { <span class="kw">return </span><span class="prelude-val">Ok</span>(()); } |
| <span class="prelude-val">Err</span>(String::from(<span class="string">"The value did not contain the required @ sigil"</span>)) |
| } |
| <span class="kw">let </span>res = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"file"</span>) |
| .index(<span class="number">1</span>) |
| .validator(has_at)) |
| .get_matches_from_safe(<span class="macro">vec!</span>[ |
| <span class="string">"prog"</span>, <span class="string">"some@file" |
| </span>]); |
| <span class="macro">assert!</span>(res.is_ok()); |
| <span class="macro">assert_eq!</span>(res.unwrap().value_of(<span class="string">"file"</span>), <span class="prelude-val">Some</span>(<span class="string">"some@file"</span>));</code></pre></div> |
| </div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.validator_os" class="method has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#2731-2737">source</a><h4 class="code-header">pub fn <a href="#method.validator_os" class="fnname">validator_os</a><F>(self, f: F) -> Self<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></h4></section></summary><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> |
| <h5 id="examples-44"><a href="#examples-44">Examples</a></h5> |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">fn </span>has_ampersand(v: <span class="kw-2">&</span>OsStr) -> <span class="prelude-ty">Result</span><(), OsString> { |
| <span class="kw">if </span>v.as_bytes().iter().any(|b| <span class="kw-2">*</span>b == <span class="string">b'&'</span>) { <span class="kw">return </span><span class="prelude-val">Ok</span>(()); } |
| <span class="prelude-val">Err</span>(OsString::from(<span class="string">"The value did not contain the required & sigil"</span>)) |
| } |
| <span class="kw">let </span>res = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"file"</span>) |
| .index(<span class="number">1</span>) |
| .validator_os(has_ampersand)) |
| .get_matches_from_safe(<span class="macro">vec!</span>[ |
| <span class="string">"prog"</span>, <span class="string">"Fish & chips" |
| </span>]); |
| <span class="macro">assert!</span>(res.is_ok()); |
| <span class="macro">assert_eq!</span>(res.unwrap().value_of(<span class="string">"file"</span>), <span class="prelude-val">Some</span>(<span class="string">"Fish & chips"</span>));</code></pre></div> |
| </div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.max_values" class="method has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#2795-2799">source</a><h4 class="code-header">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>) -> Self</h4></section></summary><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> |
| <h5 id="examples-45"><a href="#examples-45">Examples</a></h5> |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code>Arg::with_name(<span class="string">"file"</span>) |
| .short(<span class="string">"f"</span>) |
| .max_values(<span class="number">3</span>)</code></pre></div> |
| <p>Supplying less than the maximum number of values is allowed</p> |
| |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">let </span>res = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"file"</span>) |
| .takes_value(<span class="bool-val">true</span>) |
| .max_values(<span class="number">3</span>) |
| .short(<span class="string">"F"</span>)) |
| .get_matches_from_safe(<span class="macro">vec!</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>(res.is_ok()); |
| <span class="kw">let </span>m = res.unwrap(); |
| <span class="kw">let </span>files: Vec<<span class="kw">_</span>> = m.values_of(<span class="string">"file"</span>).unwrap().collect(); |
| <span class="macro">assert_eq!</span>(files, [<span class="string">"file1"</span>, <span class="string">"file2"</span>]);</code></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"><code><span class="kw">let </span>res = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"file"</span>) |
| .takes_value(<span class="bool-val">true</span>) |
| .max_values(<span class="number">2</span>) |
| .short(<span class="string">"F"</span>)) |
| .get_matches_from_safe(<span class="macro">vec!</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>(res.is_err()); |
| <span class="macro">assert_eq!</span>(res.unwrap_err().kind, ErrorKind::TooManyValues);</code></pre></div> |
| </div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.min_values" class="method has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#2858-2861">source</a><h4 class="code-header">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>) -> Self</h4></section></summary><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> |
| <h5 id="examples-46"><a href="#examples-46">Examples</a></h5> |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code>Arg::with_name(<span class="string">"file"</span>) |
| .short(<span class="string">"f"</span>) |
| .min_values(<span class="number">3</span>)</code></pre></div> |
| <p>Supplying more than the minimum number of values is allowed</p> |
| |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">let </span>res = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"file"</span>) |
| .takes_value(<span class="bool-val">true</span>) |
| .min_values(<span class="number">2</span>) |
| .short(<span class="string">"F"</span>)) |
| .get_matches_from_safe(<span class="macro">vec!</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>(res.is_ok()); |
| <span class="kw">let </span>m = res.unwrap(); |
| <span class="kw">let </span>files: Vec<<span class="kw">_</span>> = m.values_of(<span class="string">"file"</span>).unwrap().collect(); |
| <span class="macro">assert_eq!</span>(files, [<span class="string">"file1"</span>, <span class="string">"file2"</span>, <span class="string">"file3"</span>]);</code></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"><code><span class="kw">let </span>res = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"file"</span>) |
| .takes_value(<span class="bool-val">true</span>) |
| .min_values(<span class="number">2</span>) |
| .short(<span class="string">"F"</span>)) |
| .get_matches_from_safe(<span class="macro">vec!</span>[ |
| <span class="string">"prog"</span>, <span class="string">"-F"</span>, <span class="string">"file1" |
| </span>]); |
| |
| <span class="macro">assert!</span>(res.is_err()); |
| <span class="macro">assert_eq!</span>(res.unwrap_err().kind, ErrorKind::TooFewValues);</code></pre></div> |
| </div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.use_delimiter" class="method has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#2909-2921">source</a><h4 class="code-header">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>) -> Self</h4></section></summary><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> |
| <h5 id="examples-47"><a href="#examples-47">Examples</a></h5> |
| <p>The following example shows the default behavior.</p> |
| |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">let </span>delims = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"option"</span>) |
| .long(<span class="string">"option"</span>) |
| .use_delimiter(<span class="bool-val">true</span>) |
| .takes_value(<span class="bool-val">true</span>)) |
| .get_matches_from(<span class="macro">vec!</span>[ |
| <span class="string">"prog"</span>, <span class="string">"--option=val1,val2,val3"</span>, |
| ]); |
| |
| <span class="macro">assert!</span>(delims.is_present(<span class="string">"option"</span>)); |
| <span class="macro">assert_eq!</span>(delims.occurrences_of(<span class="string">"option"</span>), <span class="number">1</span>); |
| <span class="macro">assert_eq!</span>(delims.values_of(<span class="string">"option"</span>).unwrap().collect::<Vec<<span class="kw">_</span>>>(), [<span class="string">"val1"</span>, <span class="string">"val2"</span>, <span class="string">"val3"</span>]);</code></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"><code><span class="kw">let </span>nodelims = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"option"</span>) |
| .long(<span class="string">"option"</span>) |
| .use_delimiter(<span class="bool-val">false</span>) |
| .takes_value(<span class="bool-val">true</span>)) |
| .get_matches_from(<span class="macro">vec!</span>[ |
| <span class="string">"prog"</span>, <span class="string">"--option=val1,val2,val3"</span>, |
| ]); |
| |
| <span class="macro">assert!</span>(nodelims.is_present(<span class="string">"option"</span>)); |
| <span class="macro">assert_eq!</span>(nodelims.occurrences_of(<span class="string">"option"</span>), <span class="number">1</span>); |
| <span class="macro">assert_eq!</span>(nodelims.value_of(<span class="string">"option"</span>).unwrap(), <span class="string">"val1,val2,val3"</span>);</code></pre></div> |
| </div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.require_delimiter" class="method has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#2995-3006">source</a><h4 class="code-header">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>) -> Self</h4></section></summary><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> |
| <h5 id="examples-48"><a href="#examples-48">Examples</a></h5> |
| <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"><code><span class="kw">let </span>delims = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"opt"</span>) |
| .short(<span class="string">"o"</span>) |
| .takes_value(<span class="bool-val">true</span>) |
| .multiple(<span class="bool-val">true</span>) |
| .require_delimiter(<span class="bool-val">true</span>)) |
| .get_matches_from(<span class="macro">vec!</span>[ |
| <span class="string">"prog"</span>, <span class="string">"-o"</span>, <span class="string">"val1,val2,val3"</span>, |
| ]); |
| |
| <span class="macro">assert!</span>(delims.is_present(<span class="string">"opt"</span>)); |
| <span class="macro">assert_eq!</span>(delims.values_of(<span class="string">"opt"</span>).unwrap().collect::<Vec<<span class="kw">_</span>>>(), [<span class="string">"val1"</span>, <span class="string">"val2"</span>, <span class="string">"val3"</span>]);</code></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"><code><span class="kw">let </span>res = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"opt"</span>) |
| .short(<span class="string">"o"</span>) |
| .takes_value(<span class="bool-val">true</span>) |
| .multiple(<span class="bool-val">true</span>) |
| .require_delimiter(<span class="bool-val">true</span>)) |
| .get_matches_from_safe(<span class="macro">vec!</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>(res.is_err()); |
| <span class="kw">let </span>err = res.unwrap_err(); |
| <span class="macro">assert_eq!</span>(err.kind, ErrorKind::UnknownArgument);</code></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"><code><span class="kw">let </span>delims = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"opt"</span>) |
| .short(<span class="string">"o"</span>) |
| .takes_value(<span class="bool-val">true</span>) |
| .multiple(<span class="bool-val">true</span>)) |
| .get_matches_from(<span class="macro">vec!</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>(delims.is_present(<span class="string">"opt"</span>)); |
| <span class="macro">assert_eq!</span>(delims.values_of(<span class="string">"opt"</span>).unwrap().collect::<Vec<<span class="kw">_</span>>>(), [<span class="string">"val1"</span>, <span class="string">"val2"</span>, <span class="string">"val3"</span>]);</code></pre></div> |
| </div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.value_delimiter" class="method has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#3031-3041">source</a><h4 class="code-header">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>) -> Self</h4></section></summary><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> |
| <h5 id="examples-49"><a href="#examples-49">Examples</a></h5> |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">let </span>m = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"config"</span>) |
| .short(<span class="string">"c"</span>) |
| .long(<span class="string">"config"</span>) |
| .value_delimiter(<span class="string">";"</span>)) |
| .get_matches_from(<span class="macro">vec!</span>[ |
| <span class="string">"prog"</span>, <span class="string">"--config=val1;val2;val3" |
| </span>]); |
| |
| <span class="macro">assert_eq!</span>(m.values_of(<span class="string">"config"</span>).unwrap().collect::<Vec<<span class="kw">_</span>>>(), [<span class="string">"val1"</span>, <span class="string">"val2"</span>, <span class="string">"val3"</span>])</code></pre></div> |
| </div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.value_names" class="method has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#3102-3122">source</a><h4 class="code-header">pub fn <a href="#method.value_names" class="fnname">value_names</a>(self, names: &[&'b <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.str.html">str</a>]) -> Self</h4></section></summary><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> |
| <h5 id="examples-50"><a href="#examples-50">Examples</a></h5> |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code>Arg::with_name(<span class="string">"speed"</span>) |
| .short(<span class="string">"s"</span>) |
| .value_names(<span class="kw-2">&</span>[<span class="string">"fast"</span>, <span class="string">"slow"</span>])</code></pre></div> |
| |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">let </span>m = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"io"</span>) |
| .long(<span class="string">"io-files"</span>) |
| .value_names(<span class="kw-2">&</span>[<span class="string">"INFILE"</span>, <span class="string">"OUTFILE"</span>])) |
| .get_matches_from(<span class="macro">vec!</span>[ |
| <span class="string">"prog"</span>, <span class="string">"--help" |
| </span>]);</code></pre></div> |
| <p>Running the above program produces the following output</p> |
| <div class="example-wrap"><pre class="language-notrust"><code>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></div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.value_name" class="method has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#3170-3181">source</a><h4 class="code-header">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>) -> Self</h4></section></summary><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> |
| <h5 id="examples-51"><a href="#examples-51">Examples</a></h5> |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code>Arg::with_name(<span class="string">"cfg"</span>) |
| .long(<span class="string">"config"</span>) |
| .value_name(<span class="string">"FILE"</span>)</code></pre></div> |
| |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">let </span>m = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"config"</span>) |
| .long(<span class="string">"config"</span>) |
| .value_name(<span class="string">"FILE"</span>)) |
| .get_matches_from(<span class="macro">vec!</span>[ |
| <span class="string">"prog"</span>, <span class="string">"--help" |
| </span>]);</code></pre></div> |
| <p>Running the above program produces the following output</p> |
| <div class="example-wrap"><pre class="language-notrust"><code>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></div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.default_value" class="method has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#3246-3248">source</a><h4 class="code-header">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>) -> Self</h4></section></summary><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> |
| <h5 id="examples-52"><a href="#examples-52">Examples</a></h5> |
| <p>First we use the default value without providing any value at runtime.</p> |
| |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">let </span>m = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"opt"</span>) |
| .long(<span class="string">"myopt"</span>) |
| .default_value(<span class="string">"myval"</span>)) |
| .get_matches_from(<span class="macro">vec!</span>[ |
| <span class="string">"prog" |
| </span>]); |
| |
| <span class="macro">assert_eq!</span>(m.value_of(<span class="string">"opt"</span>), <span class="prelude-val">Some</span>(<span class="string">"myval"</span>)); |
| <span class="macro">assert!</span>(m.is_present(<span class="string">"opt"</span>)); |
| <span class="macro">assert_eq!</span>(m.occurrences_of(<span class="string">"opt"</span>), <span class="number">0</span>);</code></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"><code><span class="kw">let </span>m = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"opt"</span>) |
| .long(<span class="string">"myopt"</span>) |
| .default_value(<span class="string">"myval"</span>)) |
| .get_matches_from(<span class="macro">vec!</span>[ |
| <span class="string">"prog"</span>, <span class="string">"--myopt=non_default" |
| </span>]); |
| |
| <span class="macro">assert_eq!</span>(m.value_of(<span class="string">"opt"</span>), <span class="prelude-val">Some</span>(<span class="string">"non_default"</span>)); |
| <span class="macro">assert!</span>(m.is_present(<span class="string">"opt"</span>)); |
| <span class="macro">assert_eq!</span>(m.occurrences_of(<span class="string">"opt"</span>), <span class="number">1</span>);</code></pre></div> |
| </div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.default_value_os" class="method has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#3254-3258">source</a><h4 class="code-header">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>) -> Self</h4></section></summary><div class="docblock"><p>Provides a default value in the exact same manner as <a href="struct.Arg.html#method.default_value" title="Arg::default_value"><code>Arg::default_value</code></a> |
| only using <a href="https://doc.rust-lang.org/nightly/std/ffi/os_str/struct.OsStr.html" title="OsStr"><code>OsStr</code></a>s instead. |
| <a href="struct.Arg.html#method.default_value" title="Arg::default_value"><code>Arg::default_value</code></a>: ./struct.Arg.html#method.default_value |
| <a href="https://doc.rust-lang.org/nightly/std/ffi/os_str/struct.OsStr.html" title="OsStr"><code>OsStr</code></a>: https://doc.rust-lang.org/std/ffi/struct.OsStr.html</p> |
| </div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.default_value_if" class="method has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#3356-3362">source</a><h4 class="code-header">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>) -> Self</h4></section></summary><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> |
| <div class="example-wrap"><pre class="language-yaml"><code>default_value_if: |
| - [arg, val, default]</code></pre></div><h5 id="examples-53"><a href="#examples-53">Examples</a></h5> |
| <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"><code><span class="kw">let </span>m = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"flag"</span>) |
| .long(<span class="string">"flag"</span>)) |
| .arg(Arg::with_name(<span class="string">"other"</span>) |
| .long(<span class="string">"other"</span>) |
| .default_value_if(<span class="string">"flag"</span>, <span class="prelude-val">None</span>, <span class="string">"default"</span>)) |
| .get_matches_from(<span class="macro">vec!</span>[ |
| <span class="string">"prog"</span>, <span class="string">"--flag" |
| </span>]); |
| |
| <span class="macro">assert_eq!</span>(m.value_of(<span class="string">"other"</span>), <span class="prelude-val">Some</span>(<span class="string">"default"</span>));</code></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"><code><span class="kw">let </span>m = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"flag"</span>) |
| .long(<span class="string">"flag"</span>)) |
| .arg(Arg::with_name(<span class="string">"other"</span>) |
| .long(<span class="string">"other"</span>) |
| .default_value_if(<span class="string">"flag"</span>, <span class="prelude-val">None</span>, <span class="string">"default"</span>)) |
| .get_matches_from(<span class="macro">vec!</span>[ |
| <span class="string">"prog" |
| </span>]); |
| |
| <span class="macro">assert_eq!</span>(m.value_of(<span class="string">"other"</span>), <span class="prelude-val">None</span>);</code></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"><code><span class="kw">let </span>m = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"opt"</span>) |
| .takes_value(<span class="bool-val">true</span>) |
| .long(<span class="string">"opt"</span>)) |
| .arg(Arg::with_name(<span class="string">"other"</span>) |
| .long(<span class="string">"other"</span>) |
| .default_value_if(<span class="string">"opt"</span>, <span class="prelude-val">Some</span>(<span class="string">"special"</span>), <span class="string">"default"</span>)) |
| .get_matches_from(<span class="macro">vec!</span>[ |
| <span class="string">"prog"</span>, <span class="string">"--opt"</span>, <span class="string">"special" |
| </span>]); |
| |
| <span class="macro">assert_eq!</span>(m.value_of(<span class="string">"other"</span>), <span class="prelude-val">Some</span>(<span class="string">"default"</span>));</code></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"><code><span class="kw">let </span>m = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"opt"</span>) |
| .takes_value(<span class="bool-val">true</span>) |
| .long(<span class="string">"opt"</span>)) |
| .arg(Arg::with_name(<span class="string">"other"</span>) |
| .long(<span class="string">"other"</span>) |
| .default_value_if(<span class="string">"opt"</span>, <span class="prelude-val">Some</span>(<span class="string">"special"</span>), <span class="string">"default"</span>)) |
| .get_matches_from(<span class="macro">vec!</span>[ |
| <span class="string">"prog"</span>, <span class="string">"--opt"</span>, <span class="string">"hahaha" |
| </span>]); |
| |
| <span class="macro">assert_eq!</span>(m.value_of(<span class="string">"other"</span>), <span class="prelude-val">None</span>);</code></pre></div> |
| </div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.default_value_if_os" class="method has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#3368-3384">source</a><h4 class="code-header">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>) -> Self</h4></section></summary><div class="docblock"><p>Provides a conditional default value in the exact same manner as <a href="struct.Arg.html#method.default_value_if" title="Arg::default_value_if"><code>Arg::default_value_if</code></a> |
| only using <a href="https://doc.rust-lang.org/nightly/std/ffi/os_str/struct.OsStr.html" title="OsStr"><code>OsStr</code></a>s instead. |
| <a href="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 |
| <a href="https://doc.rust-lang.org/nightly/std/ffi/os_str/struct.OsStr.html" title="OsStr"><code>OsStr</code></a>: https://doc.rust-lang.org/std/ffi/struct.OsStr.html</p> |
| </div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.default_value_ifs" class="method has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#3470-3479">source</a><h4 class="code-header">pub fn <a href="#method.default_value_ifs" class="fnname">default_value_ifs</a>(<br> self,<br> ifs: &[(&'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>)]<br>) -> Self</h4></section></summary><div class="docblock"><p>Specifies multiple values and conditions in the same manner as <a href="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> |
| <div class="example-wrap"><pre class="language-yaml"><code>default_value_if: |
| - [arg, val, default] |
| - [arg2, null, default2]</code></pre></div><h5 id="examples-54"><a href="#examples-54">Examples</a></h5> |
| <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"><code><span class="kw">let </span>m = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"flag"</span>) |
| .long(<span class="string">"flag"</span>)) |
| .arg(Arg::with_name(<span class="string">"opt"</span>) |
| .long(<span class="string">"opt"</span>) |
| .takes_value(<span class="bool-val">true</span>)) |
| .arg(Arg::with_name(<span class="string">"other"</span>) |
| .long(<span class="string">"other"</span>) |
| .default_value_ifs(<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>), |
| ])) |
| .get_matches_from(<span class="macro">vec!</span>[ |
| <span class="string">"prog"</span>, <span class="string">"--opt"</span>, <span class="string">"channal" |
| </span>]); |
| |
| <span class="macro">assert_eq!</span>(m.value_of(<span class="string">"other"</span>), <span class="prelude-val">Some</span>(<span class="string">"chan"</span>));</code></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"><code><span class="kw">let </span>m = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"flag"</span>) |
| .long(<span class="string">"flag"</span>)) |
| .arg(Arg::with_name(<span class="string">"other"</span>) |
| .long(<span class="string">"other"</span>) |
| .default_value_ifs(<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>), |
| ])) |
| .get_matches_from(<span class="macro">vec!</span>[ |
| <span class="string">"prog" |
| </span>]); |
| |
| <span class="macro">assert_eq!</span>(m.value_of(<span class="string">"other"</span>), <span class="prelude-val">None</span>);</code></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"><code><span class="kw">let </span>m = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"flag"</span>) |
| .long(<span class="string">"flag"</span>)) |
| .arg(Arg::with_name(<span class="string">"opt"</span>) |
| .long(<span class="string">"opt"</span>) |
| .takes_value(<span class="bool-val">true</span>)) |
| .arg(Arg::with_name(<span class="string">"other"</span>) |
| .long(<span class="string">"other"</span>) |
| .default_value_ifs(<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>), |
| ])) |
| .get_matches_from(<span class="macro">vec!</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>(m.value_of(<span class="string">"other"</span>), <span class="prelude-val">Some</span>(<span class="string">"default"</span>));</code></pre></div> |
| </div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.default_value_ifs_os" class="method has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#3485-3490">source</a><h4 class="code-header">pub fn <a href="#method.default_value_ifs_os" class="fnname">default_value_ifs_os</a>(<br> self,<br> ifs: &[(&'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>)]<br>) -> Self</h4></section></summary><div class="docblock"><p>Provides multiple conditional default values in the exact same manner as |
| <a href="struct.Arg.html#method.default_value_ifs" title="Arg::default_value_ifs"><code>Arg::default_value_ifs</code></a> only using <a href="https://doc.rust-lang.org/nightly/std/ffi/os_str/struct.OsStr.html" title="OsStr"><code>OsStr</code></a>s instead. |
| <a href="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 |
| <a href="https://doc.rust-lang.org/nightly/std/ffi/os_str/struct.OsStr.html" title="OsStr"><code>OsStr</code></a>: https://doc.rust-lang.org/std/ffi/struct.OsStr.html</p> |
| </div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.env" class="method has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#3597-3599">source</a><h4 class="code-header">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>) -> Self</h4></section></summary><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> |
| <h5 id="examples-55"><a href="#examples-55">Examples</a></h5> |
| <p>In this example, we show the variable coming from the environment:</p> |
| |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code> |
| env::set_var(<span class="string">"MY_FLAG"</span>, <span class="string">"env"</span>); |
| |
| <span class="kw">let </span>m = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"flag"</span>) |
| .long(<span class="string">"flag"</span>) |
| .env(<span class="string">"MY_FLAG"</span>)) |
| .get_matches_from(<span class="macro">vec!</span>[ |
| <span class="string">"prog" |
| </span>]); |
| |
| <span class="macro">assert_eq!</span>(m.value_of(<span class="string">"flag"</span>), <span class="prelude-val">Some</span>(<span class="string">"env"</span>));</code></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"><code> |
| env::set_var(<span class="string">"MY_FLAG"</span>, <span class="string">"env"</span>); |
| |
| <span class="kw">let </span>m = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"flag"</span>) |
| .long(<span class="string">"flag"</span>) |
| .env(<span class="string">"MY_FLAG"</span>)) |
| .get_matches_from(<span class="macro">vec!</span>[ |
| <span class="string">"prog"</span>, <span class="string">"--flag"</span>, <span class="string">"opt" |
| </span>]); |
| |
| <span class="macro">assert_eq!</span>(m.value_of(<span class="string">"flag"</span>), <span class="prelude-val">Some</span>(<span class="string">"opt"</span>));</code></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"><code> |
| env::set_var(<span class="string">"MY_FLAG"</span>, <span class="string">"env"</span>); |
| |
| <span class="kw">let </span>m = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"flag"</span>) |
| .long(<span class="string">"flag"</span>) |
| .env(<span class="string">"MY_FLAG"</span>) |
| .default_value(<span class="string">"default"</span>)) |
| .get_matches_from(<span class="macro">vec!</span>[ |
| <span class="string">"prog" |
| </span>]); |
| |
| <span class="macro">assert_eq!</span>(m.value_of(<span class="string">"flag"</span>), <span class="prelude-val">Some</span>(<span class="string">"env"</span>));</code></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"><code> |
| env::set_var(<span class="string">"MY_FLAG_MULTI"</span>, <span class="string">"env1,env2"</span>); |
| |
| <span class="kw">let </span>m = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"flag"</span>) |
| .long(<span class="string">"flag"</span>) |
| .env(<span class="string">"MY_FLAG_MULTI"</span>) |
| .multiple(<span class="bool-val">true</span>) |
| .use_delimiter(<span class="bool-val">true</span>)) |
| .get_matches_from(<span class="macro">vec!</span>[ |
| <span class="string">"prog" |
| </span>]); |
| |
| <span class="macro">assert_eq!</span>(m.values_of(<span class="string">"flag"</span>).unwrap().collect::<Vec<<span class="kw">_</span>>>(), <span class="macro">vec!</span>[<span class="string">"env1"</span>, <span class="string">"env2"</span>]);</code></pre></div> |
| </div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.env_os" class="method has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#3604-3609">source</a><h4 class="code-header">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>) -> Self</h4></section></summary><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="struct.Arg.html#method.env" title="Arg::env"><code>Arg::env</code></a> only using |
| <a href="https://doc.rust-lang.org/nightly/std/ffi/os_str/struct.OsStr.html" title="OsStr"><code>OsStr</code></a>s instead.</p> |
| </div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.hide_env_values" class="method has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#3612-3618">source</a><h4 class="code-header">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>) -> Self</h4></section></summary><div class="docblock"><p>@TODO @p2 @docs @release: write docs</p> |
| </div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.next_line_help" class="method has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#3665-3672">source</a><h4 class="code-header">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>) -> Self</h4></section></summary><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> |
| <h5 id="examples-56"><a href="#examples-56">Examples</a></h5> |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">let </span>m = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"opt"</span>) |
| .long(<span class="string">"long-option-flag"</span>) |
| .short(<span class="string">"o"</span>) |
| .takes_value(<span class="bool-val">true</span>) |
| .value_names(<span class="kw-2">&</span>[<span class="string">"value1"</span>, <span class="string">"value2"</span>]) |
| .help(<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>) |
| .next_line_help(<span class="bool-val">true</span>)) |
| .get_matches_from(<span class="macro">vec!</span>[ |
| <span class="string">"prog"</span>, <span class="string">"--help" |
| </span>]);</code></pre></div> |
| <p>The above example displays the following help message</p> |
| <div class="example-wrap"><pre class="language-notrust"><code>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></div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.display_order" class="method has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#3729-3732">source</a><h4 class="code-header">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>) -> Self</h4></section></summary><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> |
| <h5 id="examples-57"><a href="#examples-57">Examples</a></h5> |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">let </span>m = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"a"</span>) <span class="comment">// Typically args are grouped alphabetically by name. |
| // Args without a display_order have a value of 999 and are |
| // displayed alphabetically with all other 999 valued args. |
| </span>.long(<span class="string">"long-option"</span>) |
| .short(<span class="string">"o"</span>) |
| .takes_value(<span class="bool-val">true</span>) |
| .help(<span class="string">"Some help and text"</span>)) |
| .arg(Arg::with_name(<span class="string">"b"</span>) |
| .long(<span class="string">"other-option"</span>) |
| .short(<span class="string">"O"</span>) |
| .takes_value(<span class="bool-val">true</span>) |
| .display_order(<span class="number">1</span>) <span class="comment">// In order to force this arg to appear *first* |
| // all we have to do is give it a value lower than 999. |
| // Any other args with a value of 1 will be displayed |
| // alphabetically with this one...then 2 values, then 3, etc. |
| </span>.help(<span class="string">"I should be first!"</span>)) |
| .get_matches_from(<span class="macro">vec!</span>[ |
| <span class="string">"prog"</span>, <span class="string">"--help" |
| </span>]);</code></pre></div> |
| <p>The above example displays the following help message</p> |
| <div class="example-wrap"><pre class="language-notrust"><code>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></div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.raw" class="method has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#3753-3755">source</a><h4 class="code-header">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>) -> Self</h4></section></summary><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> |
| <div class="example-wrap"><pre class="language-notrust"><code>--foo something -- -v -v -v -b -b -b --baz -q -u -x</code></pre></div> |
| <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></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.hidden_short_help" class="method has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#3826-3832">source</a><h4 class="code-header">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>) -> Self</h4></section></summary><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> |
| <h5 id="examples-58"><a href="#examples-58">Examples</a></h5> |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code>Arg::with_name(<span class="string">"debug"</span>) |
| .hidden_short_help(<span class="bool-val">true</span>)</code></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"><code><span class="kw">let </span>m = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"cfg"</span>) |
| .long(<span class="string">"config"</span>) |
| .hidden_short_help(<span class="bool-val">true</span>) |
| .help(<span class="string">"Some help text describing the --config arg"</span>)) |
| .get_matches_from(<span class="macro">vec!</span>[ |
| <span class="string">"prog"</span>, <span class="string">"-h" |
| </span>]);</code></pre></div> |
| <p>The above example displays</p> |
| <div class="example-wrap"><pre class="language-notrust"><code>helptest |
| |
| USAGE: |
| helptest [FLAGS] |
| |
| FLAGS: |
| -h, --help Prints help information |
| -V, --version Prints version information</code></pre></div> |
| <p>However, when –help is called</p> |
| |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">let </span>m = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"cfg"</span>) |
| .long(<span class="string">"config"</span>) |
| .hidden_short_help(<span class="bool-val">true</span>) |
| .help(<span class="string">"Some help text describing the --config arg"</span>)) |
| .get_matches_from(<span class="macro">vec!</span>[ |
| <span class="string">"prog"</span>, <span class="string">"--help" |
| </span>]);</code></pre></div> |
| <p>Then the following would be displayed</p> |
| <div class="example-wrap"><pre class="language-notrust"><code>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></div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.hidden_long_help" class="method has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#3903-3909">source</a><h4 class="code-header">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>) -> Self</h4></section></summary><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> |
| <h5 id="examples-59"><a href="#examples-59">Examples</a></h5> |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code>Arg::with_name(<span class="string">"debug"</span>) |
| .hidden_long_help(<span class="bool-val">true</span>)</code></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"><code><span class="kw">let </span>m = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"cfg"</span>) |
| .long(<span class="string">"config"</span>) |
| .hidden_long_help(<span class="bool-val">true</span>) |
| .help(<span class="string">"Some help text describing the --config arg"</span>)) |
| .get_matches_from(<span class="macro">vec!</span>[ |
| <span class="string">"prog"</span>, <span class="string">"--help" |
| </span>]);</code></pre></div> |
| <p>The above example displays</p> |
| <div class="example-wrap"><pre class="language-notrust"><code>helptest |
| |
| USAGE: |
| helptest [FLAGS] |
| |
| FLAGS: |
| -h, --help Prints help information |
| -V, --version Prints version information</code></pre></div> |
| <p>However, when -h is called</p> |
| |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">let </span>m = App::new(<span class="string">"prog"</span>) |
| .arg(Arg::with_name(<span class="string">"cfg"</span>) |
| .long(<span class="string">"config"</span>) |
| .hidden_long_help(<span class="bool-val">true</span>) |
| .help(<span class="string">"Some help text describing the --config arg"</span>)) |
| .get_matches_from(<span class="macro">vec!</span>[ |
| <span class="string">"prog"</span>, <span class="string">"-h" |
| </span>]);</code></pre></div> |
| <p>Then the following would be displayed</p> |
| <div class="example-wrap"><pre class="language-notrust"><code>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></div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.is_set" class="method has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#3914-3916">source</a><h4 class="code-header">pub fn <a href="#method.is_set" class="fnname">is_set</a>(&self, s: <a class="enum" href="enum.ArgSettings.html" title="enum clap::ArgSettings">ArgSettings</a>) -> <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.bool.html">bool</a></h4></section></summary><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></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.set" class="method has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#3921-3924">source</a><h4 class="code-header">pub fn <a href="#method.set" class="fnname">set</a>(self, s: <a class="enum" href="enum.ArgSettings.html" title="enum clap::ArgSettings">ArgSettings</a>) -> Self</h4></section></summary><div class="docblock"><p>Sets one of the <a href="./enum.ArgSettings.html"><code>ArgSettings</code></a> settings for the argument.</p> |
| </div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.unset" class="method has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#3929-3932">source</a><h4 class="code-header">pub fn <a href="#method.unset" class="fnname">unset</a>(self, s: <a class="enum" href="enum.ArgSettings.html" title="enum clap::ArgSettings">ArgSettings</a>) -> Self</h4></section></summary><div class="docblock"><p>Unsets one of the <a href="./enum.ArgSettings.html"><code>ArgSettings</code></a> settings for the argument.</p> |
| </div></details></div></details></div><h2 id="trait-implementations" class="small-section-header">Trait Implementations<a href="#trait-implementations" class="anchor"></a></h2><div id="trait-implementations-list"><details class="rustdoc-toggle implementors-toggle" open><summary><section id="impl-Clone-for-Arg%3C%27a%2C%20%27b%3E" class="impl has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#48">source</a><a href="#impl-Clone-for-Arg%3C%27a%2C%20%27b%3E" class="anchor"></a><h3 class="code-header">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="struct.Arg.html" title="struct clap::Arg">Arg</a><'a, 'b><span class="where fmt-newline">where<br> 'a: 'b,</span></h3></section></summary><div class="impl-items"><details class="rustdoc-toggle method-toggle" open><summary><section id="method.clone" class="method trait-impl has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#48">source</a><a href="#method.clone" class="anchor"></a><h4 class="code-header">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="struct.Arg.html" title="struct clap::Arg">Arg</a><'a, 'b></h4></section></summary><div class='docblock'>Returns a copy of the value. <a href="https://doc.rust-lang.org/nightly/core/clone/trait.Clone.html#tymethod.clone">Read more</a></div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.clone_from" class="method trait-impl has-srclink"><span class="rightside"><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#132-134">source</a></span><a href="#method.clone_from" class="anchor"></a><h4 class="code-header">const 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)</h4></section></summary><div class='docblock'>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></div></details></div></details><details class="rustdoc-toggle implementors-toggle" open><summary><section id="impl-Default-for-Arg%3C%27a%2C%20%27b%3E" class="impl has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#48">source</a><a href="#impl-Default-for-Arg%3C%27a%2C%20%27b%3E" class="anchor"></a><h3 class="code-header">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="struct.Arg.html" title="struct clap::Arg">Arg</a><'a, 'b><span class="where fmt-newline">where<br> 'a: 'b,</span></h3></section></summary><div class="impl-items"><details class="rustdoc-toggle method-toggle" open><summary><section id="method.default" class="method trait-impl has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#48">source</a><a href="#method.default" class="anchor"></a><h4 class="code-header">fn <a href="https://doc.rust-lang.org/nightly/core/default/trait.Default.html#tymethod.default" class="fnname">default</a>() -> <a class="struct" href="struct.Arg.html" title="struct clap::Arg">Arg</a><'a, 'b></h4></section></summary><div class='docblock'>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></div></details></div></details><details class="rustdoc-toggle implementors-toggle" open><summary><section id="impl-From%3C%26%27z%20Arg%3C%27a%2C%20%27b%3E%3E-for-Arg%3C%27a%2C%20%27b%3E" class="impl has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#3945-3955">source</a><a href="#impl-From%3C%26%27z%20Arg%3C%27a%2C%20%27b%3E%3E-for-Arg%3C%27a%2C%20%27b%3E" class="anchor"></a><h3 class="code-header">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="struct.Arg.html" title="struct clap::Arg">Arg</a><'a, 'b>> for <a class="struct" href="struct.Arg.html" title="struct clap::Arg">Arg</a><'a, 'b></h3></section></summary><div class="impl-items"><details class="rustdoc-toggle method-toggle" open><summary><section id="method.from" class="method trait-impl has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#3946-3954">source</a><a href="#method.from" class="anchor"></a><h4 class="code-header">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="struct.Arg.html" title="struct clap::Arg">Arg</a><'a, 'b>) -> Self</h4></section></summary><div class='docblock'>Converts to this type from the input type.</div></details></div></details><details class="rustdoc-toggle implementors-toggle" open><summary><section id="impl-PartialEq%3CArg%3C%27n%2C%20%27e%3E%3E-for-Arg%3C%27n%2C%20%27e%3E" class="impl has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#3957-3961">source</a><a href="#impl-PartialEq%3CArg%3C%27n%2C%20%27e%3E%3E-for-Arg%3C%27n%2C%20%27e%3E" class="anchor"></a><h3 class="code-header">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="struct.Arg.html" title="struct clap::Arg">Arg</a><'n, 'e>> for <a class="struct" href="struct.Arg.html" title="struct clap::Arg">Arg</a><'n, 'e></h3></section></summary><div class="impl-items"><details class="rustdoc-toggle method-toggle" open><summary><section id="method.eq" class="method trait-impl has-srclink"><a class="srclink rightside" href="../src/clap/args/arg.rs.html#3958-3960">source</a><a href="#method.eq" class="anchor"></a><h4 class="code-header">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="struct.Arg.html" title="struct clap::Arg">Arg</a><'n, 'e>) -> <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.bool.html">bool</a></h4></section></summary><div class='docblock'>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></div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.ne" class="method trait-impl has-srclink"><span class="rightside"><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#227">source</a></span><a href="#method.ne" class="anchor"></a><h4 class="code-header">const 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></h4></section></summary><div class='docblock'>This method tests for <code>!=</code>. The default implementation is almost always |
| sufficient, and should not be overridden without very good reason. <a href="https://doc.rust-lang.org/nightly/core/cmp/trait.PartialEq.html#method.ne">Read more</a></div></details></div></details></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"><section id="impl-RefUnwindSafe-for-Arg%3C%27a%2C%20%27b%3E" class="impl has-srclink"><a href="#impl-RefUnwindSafe-for-Arg%3C%27a%2C%20%27b%3E" class="anchor"></a><h3 class="code-header">impl<'a, 'b> !<a class="trait" href="https://doc.rust-lang.org/nightly/core/panic/unwind_safe/trait.RefUnwindSafe.html" title="trait core::panic::unwind_safe::RefUnwindSafe">RefUnwindSafe</a> for <a class="struct" href="struct.Arg.html" title="struct clap::Arg">Arg</a><'a, 'b></h3></section><section id="impl-Send-for-Arg%3C%27a%2C%20%27b%3E" class="impl has-srclink"><a href="#impl-Send-for-Arg%3C%27a%2C%20%27b%3E" class="anchor"></a><h3 class="code-header">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="struct.Arg.html" title="struct clap::Arg">Arg</a><'a, 'b></h3></section><section id="impl-Sync-for-Arg%3C%27a%2C%20%27b%3E" class="impl has-srclink"><a href="#impl-Sync-for-Arg%3C%27a%2C%20%27b%3E" class="anchor"></a><h3 class="code-header">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="struct.Arg.html" title="struct clap::Arg">Arg</a><'a, 'b></h3></section><section id="impl-Unpin-for-Arg%3C%27a%2C%20%27b%3E" class="impl has-srclink"><a href="#impl-Unpin-for-Arg%3C%27a%2C%20%27b%3E" class="anchor"></a><h3 class="code-header">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="struct.Arg.html" title="struct clap::Arg">Arg</a><'a, 'b></h3></section><section id="impl-UnwindSafe-for-Arg%3C%27a%2C%20%27b%3E" class="impl has-srclink"><a href="#impl-UnwindSafe-for-Arg%3C%27a%2C%20%27b%3E" class="anchor"></a><h3 class="code-header">impl<'a, 'b> !<a class="trait" href="https://doc.rust-lang.org/nightly/core/panic/unwind_safe/trait.UnwindSafe.html" title="trait core::panic::unwind_safe::UnwindSafe">UnwindSafe</a> for <a class="struct" href="struct.Arg.html" title="struct clap::Arg">Arg</a><'a, 'b></h3></section></div><h2 id="blanket-implementations" class="small-section-header">Blanket Implementations<a href="#blanket-implementations" class="anchor"></a></h2><div id="blanket-implementations-list"><details class="rustdoc-toggle implementors-toggle"><summary><section id="impl-Any-for-Arg%3C%27a%2C%20%27b%3E" class="impl has-srclink"><a class="srclink rightside" href="https://doc.rust-lang.org/nightly/src/core/any.rs.html#200">source</a><a href="#impl-Any-for-Arg%3C%27a%2C%20%27b%3E" class="anchor"></a><h3 class="code-header">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></h3></section></summary><div class="impl-items"><details class="rustdoc-toggle method-toggle" open><summary><section id="method.type_id" class="method trait-impl has-srclink"><a class="srclink rightside" href="https://doc.rust-lang.org/nightly/src/core/any.rs.html#201">source</a><a href="#method.type_id" class="anchor"></a><h4 class="code-header">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></h4></section></summary><div class='docblock'>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></div></details></div></details><details class="rustdoc-toggle implementors-toggle"><summary><section id="impl-Borrow%3CT%3E-for-Arg%3C%27a%2C%20%27b%3E" class="impl has-srclink"><a class="srclink rightside" href="https://doc.rust-lang.org/nightly/src/core/borrow.rs.html#211">source</a><a href="#impl-Borrow%3CT%3E-for-Arg%3C%27a%2C%20%27b%3E" class="anchor"></a><h3 class="code-header">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></h3></section></summary><div class="impl-items"><details class="rustdoc-toggle method-toggle" open><summary><section id="method.borrow" class="method trait-impl has-srclink"><span class="rightside"><span class="since" title="const unstable">const: <a href="https://github.com/rust-lang/rust/issues/91522" title="Tracking issue for const_borrow">unstable</a></span> · <a class="srclink" href="https://doc.rust-lang.org/nightly/src/core/borrow.rs.html#213">source</a></span><a href="#method.borrow" class="anchor"></a><h4 class="code-header">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</h4></section></summary><div class='docblock'>Immutably borrows from an owned value. <a href="https://doc.rust-lang.org/nightly/core/borrow/trait.Borrow.html#tymethod.borrow">Read more</a></div></details></div></details><details class="rustdoc-toggle implementors-toggle"><summary><section id="impl-BorrowMut%3CT%3E-for-Arg%3C%27a%2C%20%27b%3E" class="impl has-srclink"><a class="srclink rightside" href="https://doc.rust-lang.org/nightly/src/core/borrow.rs.html#220">source</a><a href="#impl-BorrowMut%3CT%3E-for-Arg%3C%27a%2C%20%27b%3E" class="anchor"></a><h3 class="code-header">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></h3></section></summary><div class="impl-items"><details class="rustdoc-toggle method-toggle" open><summary><section id="method.borrow_mut" class="method trait-impl has-srclink"><span class="rightside"><span class="since" title="const unstable">const: <a href="https://github.com/rust-lang/rust/issues/91522" title="Tracking issue for const_borrow">unstable</a></span> · <a class="srclink" href="https://doc.rust-lang.org/nightly/src/core/borrow.rs.html#221">source</a></span><a href="#method.borrow_mut" class="anchor"></a><h4 class="code-header">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</h4></section></summary><div class='docblock'>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></div></details></div></details><details class="rustdoc-toggle implementors-toggle"><summary><section id="impl-From%3CT%3E-for-Arg%3C%27a%2C%20%27b%3E" class="impl has-srclink"><a class="srclink rightside" href="https://doc.rust-lang.org/nightly/src/core/convert/mod.rs.html#733">source</a><a href="#impl-From%3CT%3E-for-Arg%3C%27a%2C%20%27b%3E" class="anchor"></a><h3 class="code-header">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</h3></section></summary><div class="impl-items"><details class="rustdoc-toggle method-toggle" open><summary><section id="method.from-1" class="method trait-impl has-srclink"><span class="rightside"><span class="since" title="const unstable">const: <a href="https://github.com/rust-lang/rust/issues/88674" title="Tracking issue for const_convert">unstable</a></span> · <a class="srclink" href="https://doc.rust-lang.org/nightly/src/core/convert/mod.rs.html#736">source</a></span><a href="#method.from-1" class="anchor"></a><h4 class="code-header">fn <a href="https://doc.rust-lang.org/nightly/core/convert/trait.From.html#tymethod.from" class="fnname">from</a>(t: T) -> T</h4></section></summary><div class="docblock"><p>Returns the argument unchanged.</p> |
| </div></details></div></details><details class="rustdoc-toggle implementors-toggle"><summary><section id="impl-Into%3CU%3E-for-Arg%3C%27a%2C%20%27b%3E" class="impl has-srclink"><a class="srclink rightside" href="https://doc.rust-lang.org/nightly/src/core/convert/mod.rs.html#717">source</a><a href="#impl-Into%3CU%3E-for-Arg%3C%27a%2C%20%27b%3E" class="anchor"></a><h3 class="code-header">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></h3></section></summary><div class="impl-items"><details class="rustdoc-toggle method-toggle" open><summary><section id="method.into" class="method trait-impl has-srclink"><span class="rightside"><span class="since" title="const unstable">const: <a href="https://github.com/rust-lang/rust/issues/88674" title="Tracking issue for const_convert">unstable</a></span> · <a class="srclink" href="https://doc.rust-lang.org/nightly/src/core/convert/mod.rs.html#725">source</a></span><a href="#method.into" class="anchor"></a><h4 class="code-header">fn <a href="https://doc.rust-lang.org/nightly/core/convert/trait.Into.html#tymethod.into" class="fnname">into</a>(self) -> U</h4></section></summary><div class="docblock"><p>Calls <code>U::from(self)</code>.</p> |
| <p>That is, this conversion is whatever the implementation of |
| <code><a href="https://doc.rust-lang.org/nightly/core/convert/trait.From.html" title="From">From</a><T> for U</code> chooses to do.</p> |
| </div></details></div></details><details class="rustdoc-toggle implementors-toggle"><summary><section id="impl-ToOwned-for-Arg%3C%27a%2C%20%27b%3E" class="impl has-srclink"><a class="srclink rightside" href="https://doc.rust-lang.org/nightly/src/alloc/borrow.rs.html#83">source</a><a href="#impl-ToOwned-for-Arg%3C%27a%2C%20%27b%3E" class="anchor"></a><h3 class="code-header">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></h3></section></summary><div class="impl-items"><details class="rustdoc-toggle" open><summary><section id="associatedtype.Owned" class="associatedtype trait-impl has-srclink"><a href="#associatedtype.Owned" class="anchor"></a><h4 class="code-header">type <a href="https://doc.rust-lang.org/nightly/alloc/borrow/trait.ToOwned.html#associatedtype.Owned" class="associatedtype">Owned</a> = T</h4></section></summary><div class='docblock'>The resulting type after obtaining ownership.</div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.to_owned" class="method trait-impl has-srclink"><a class="srclink rightside" href="https://doc.rust-lang.org/nightly/src/alloc/borrow.rs.html#88">source</a><a href="#method.to_owned" class="anchor"></a><h4 class="code-header">fn <a href="https://doc.rust-lang.org/nightly/alloc/borrow/trait.ToOwned.html#tymethod.to_owned" class="fnname">to_owned</a>(&self) -> T</h4></section></summary><div class='docblock'>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></div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.clone_into" class="method trait-impl has-srclink"><a class="srclink rightside" href="https://doc.rust-lang.org/nightly/src/alloc/borrow.rs.html#92">source</a><a href="#method.clone_into" class="anchor"></a><h4 class="code-header">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)</h4></section></summary><div class='docblock'>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></div></details></div></details><details class="rustdoc-toggle implementors-toggle"><summary><section id="impl-TryFrom%3CU%3E-for-Arg%3C%27a%2C%20%27b%3E" class="impl has-srclink"><a class="srclink rightside" href="https://doc.rust-lang.org/nightly/src/core/convert/mod.rs.html#775">source</a><a href="#impl-TryFrom%3CU%3E-for-Arg%3C%27a%2C%20%27b%3E" class="anchor"></a><h3 class="code-header">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></h3></section></summary><div class="impl-items"><details class="rustdoc-toggle" open><summary><section id="associatedtype.Error-1" class="associatedtype trait-impl has-srclink"><a href="#associatedtype.Error-1" class="anchor"></a><h4 class="code-header">type <a href="https://doc.rust-lang.org/nightly/core/convert/trait.TryFrom.html#associatedtype.Error" class="associatedtype">Error</a> = <a class="enum" href="https://doc.rust-lang.org/nightly/core/convert/enum.Infallible.html" title="enum core::convert::Infallible">Infallible</a></h4></section></summary><div class='docblock'>The type returned in the event of a conversion error.</div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.try_from" class="method trait-impl has-srclink"><span class="rightside"><span class="since" title="const unstable">const: <a href="https://github.com/rust-lang/rust/issues/88674" title="Tracking issue for const_convert">unstable</a></span> · <a class="srclink" href="https://doc.rust-lang.org/nightly/src/core/convert/mod.rs.html#781">source</a></span><a href="#method.try_from" class="anchor"></a><h4 class="code-header">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="associatedtype" href="https://doc.rust-lang.org/nightly/core/convert/trait.TryFrom.html#associatedtype.Error" title="type core::convert::TryFrom::Error">Error</a>></h4></section></summary><div class='docblock'>Performs the conversion.</div></details></div></details><details class="rustdoc-toggle implementors-toggle"><summary><section id="impl-TryInto%3CU%3E-for-Arg%3C%27a%2C%20%27b%3E" class="impl has-srclink"><a class="srclink rightside" href="https://doc.rust-lang.org/nightly/src/core/convert/mod.rs.html#760">source</a><a href="#impl-TryInto%3CU%3E-for-Arg%3C%27a%2C%20%27b%3E" class="anchor"></a><h3 class="code-header">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></h3></section></summary><div class="impl-items"><details class="rustdoc-toggle" open><summary><section id="associatedtype.Error" class="associatedtype trait-impl has-srclink"><a href="#associatedtype.Error" class="anchor"></a><h4 class="code-header">type <a href="https://doc.rust-lang.org/nightly/core/convert/trait.TryInto.html#associatedtype.Error" class="associatedtype">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="associatedtype" href="https://doc.rust-lang.org/nightly/core/convert/trait.TryFrom.html#associatedtype.Error" title="type core::convert::TryFrom::Error">Error</a></h4></section></summary><div class='docblock'>The type returned in the event of a conversion error.</div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.try_into" class="method trait-impl has-srclink"><span class="rightside"><span class="since" title="const unstable">const: <a href="https://github.com/rust-lang/rust/issues/88674" title="Tracking issue for const_convert">unstable</a></span> · <a class="srclink" href="https://doc.rust-lang.org/nightly/src/core/convert/mod.rs.html#766">source</a></span><a href="#method.try_into" class="anchor"></a><h4 class="code-header">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="associatedtype" href="https://doc.rust-lang.org/nightly/core/convert/trait.TryFrom.html#associatedtype.Error" title="type core::convert::TryFrom::Error">Error</a>></h4></section></summary><div class='docblock'>Performs the conversion.</div></details></div></details></div></section></div></main><div id="rustdoc-vars" data-root-path="../" data-current-crate="clap" data-themes="ayu,dark,light" data-resource-suffix="" data-rustdoc-version="1.66.0-nightly (5c8bff74b 2022-10-21)" ></div></body></html> |
