599 lines
No EOL
53 KiB
HTML
599 lines
No EOL
53 KiB
HTML
<!DOCTYPE html>
|
||
<html lang="en">
|
||
<head>
|
||
<meta charset="utf-8">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
<meta name="generator" content="rustdoc">
|
||
<meta name="description" content="API documentation for the Rust `App` struct in crate `clap`.">
|
||
<meta name="keywords" content="rust, rustlang, rust-lang, App">
|
||
|
||
<title>clap::App - Rust</title>
|
||
|
||
<link rel="stylesheet" type="text/css" href="../rustdoc.css">
|
||
<link rel="stylesheet" type="text/css" href="../main.css">
|
||
|
||
|
||
|
||
|
||
</head>
|
||
<body class="rustdoc">
|
||
<!--[if lte IE 8]>
|
||
<div class="warning">
|
||
This old browser is unsupported and will most likely display funky
|
||
things.
|
||
</div>
|
||
<![endif]-->
|
||
|
||
|
||
|
||
<nav class="sidebar">
|
||
|
||
<p class='location'><a href='index.html'>clap</a></p><script>window.sidebarCurrent = {name: 'App', ty: 'struct', relpath: ''};</script><script defer src="sidebar-items.js"></script>
|
||
</nav>
|
||
|
||
<nav class="sub">
|
||
<form class="search-form js-only">
|
||
<div class="search-container">
|
||
<input class="search-input" name="search"
|
||
autocomplete="off"
|
||
placeholder="Click or press ‘S’ to search, ‘?’ for more options…"
|
||
type="search">
|
||
</div>
|
||
</form>
|
||
</nav>
|
||
|
||
<section id='main' class="content struct">
|
||
<h1 class='fqn'><span class='in-band'>Struct <a href='index.html'>clap</a>::<wbr><a class='struct' href=''>App</a></span><span class='out-of-band'><span id='render-detail'>
|
||
<a id="toggle-all-docs" href="javascript:void(0)" title="collapse all docs">
|
||
[<span class='inner'>−</span>]
|
||
</a>
|
||
</span><a id='src-2511' class='srclink' href='../src/clap/app/mod.rs.html#59-62' title='goto source code'>[src]</a></span></h1>
|
||
<pre class='rust struct'>pub struct App<'a, 'b> <span class='where'>where 'a: 'b</span> {
|
||
// some fields omitted
|
||
}</pre><div class='docblock'><p>Used to create a representation of a command line program and all possible command line
|
||
arguments. Application settings are set using the "builder pattern" with the
|
||
<code>.get_matches()</code> family of methods being the terminal methods that starts the runtime-parsing
|
||
process. These methods then return information about the user supplied arguments (or lack there
|
||
of).</p>
|
||
|
||
<p><strong>NOTE:</strong> There aren't any mandatory "options" that one must set. The "options" may
|
||
also appear in any order (so long as one of the <code>App::get_matches*</code> methods is the last method
|
||
called).</p>
|
||
|
||
<h1 id='examples' class='section-header'><a href='#examples'>Examples</a></h1>
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>let</span> <span class='ident'>m</span> <span class='op'>=</span> <span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"My Program"</span>)
|
||
.<span class='ident'>author</span>(<span class='string'>"Me, me@mail.com"</span>)
|
||
.<span class='ident'>version</span>(<span class='string'>"1.0.2"</span>)
|
||
.<span class='ident'>about</span>(<span class='string'>"Explains in brief what the program does"</span>)
|
||
.<span class='ident'>arg</span>(
|
||
<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"in_file"</span>).<span class='ident'>index</span>(<span class='number'>1</span>)
|
||
)
|
||
.<span class='ident'>after_help</span>(<span class='string'>"Longer explaination to appear after the options when \
|
||
displaying the help information from --help or -h"</span>)
|
||
.<span class='ident'>get_matches</span>();
|
||
|
||
<span class='comment'>// Your program logic starts here...</span></pre>
|
||
</div><h2 id='methods'>Methods</h2><h3 class='impl'><code>impl<'a, 'b> <a class='struct' href='../clap/struct.App.html' title='clap::App'>App</a><'a, 'b></code></h3><div class='impl-items'><h4 id='method.new' class='method'><code>fn <a href='#method.new' class='fnname'>new</a><S: <a class='trait' href='https://doc.rust-lang.org/nightly/core/convert/trait.Into.html' title='core::convert::Into'>Into</a><<a class='struct' href='https://doc.rust-lang.org/nightly/collections/string/struct.String.html' title='collections::string::String'>String</a>>>(n: S) -> Self</code></h4>
|
||
<div class='docblock'><p>Creates a new instance of an application requiring a name. The name may be, but doesn't
|
||
have to be same as the binary. The name will be displayed to the user when they request to
|
||
print version or help and usage information.</p>
|
||
|
||
<h1 id='examples-1' class='section-header'><a href='#examples-1'>Examples</a></h1>
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>let</span> <span class='ident'>prog</span> <span class='op'>=</span> <span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"My Program"</span>)</pre>
|
||
</div><h4 id='method.author' class='method'><code>fn <a href='#method.author' class='fnname'>author</a><S: <a class='trait' href='https://doc.rust-lang.org/nightly/core/convert/trait.Into.html' title='core::convert::Into'>Into</a><&'b <a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.str.html'>str</a>>>(self, author: S) -> Self</code></h4>
|
||
<div class='docblock'><p>Sets a string of author(s) that will be displayed to the user when they
|
||
request the help information with <code>--help</code> or <code>-h</code>.</p>
|
||
|
||
<p><strong>Pro-tip:</strong> If you turn on unstable features you can use <code>clap</code>s
|
||
convienience macro <code>crate_authors!</code> to automatically set your
|
||
application's author to the same thing as your crate at compile time.
|
||
See the <code>examples/</code>
|
||
directory for more information</p>
|
||
|
||
<h1 id='examples-2' class='section-header'><a href='#examples-2'>Examples</a></h1>
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"myprog"</span>)
|
||
.<span class='ident'>author</span>(<span class='string'>"Me, me@mymain.com"</span>)</pre>
|
||
</div><h4 id='method.bin_name' class='method'><code>fn <a href='#method.bin_name' class='fnname'>bin_name</a><S: <a class='trait' href='https://doc.rust-lang.org/nightly/core/convert/trait.Into.html' title='core::convert::Into'>Into</a><<a class='struct' href='https://doc.rust-lang.org/nightly/collections/string/struct.String.html' title='collections::string::String'>String</a>>>(self, name: S) -> Self</code></h4>
|
||
<div class='docblock'><p>Overrides the system-determined binary name. This should only be used when absolutely
|
||
neccessary, such as when the binary name for your application is misleading, or perhaps
|
||
<em>not</em> how the user should invoke your program.</p>
|
||
|
||
<p><strong>Pro-tip:</strong> When building things such as third party <code>cargo</code> subcommands, this setting
|
||
<strong>should</strong> be used!</p>
|
||
|
||
<p><strong>NOTE:</strong> This command <strong>should not</strong> be used for <code>SubCommand</code>s.</p>
|
||
|
||
<h1 id='examples-3' class='section-header'><a href='#examples-3'>Examples</a></h1>
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"My Program"</span>)
|
||
.<span class='ident'>bin_name</span>(<span class='string'>"my_binary"</span>)</pre>
|
||
</div><h4 id='method.about' class='method'><code>fn <a href='#method.about' class='fnname'>about</a><S: <a class='trait' href='https://doc.rust-lang.org/nightly/core/convert/trait.Into.html' title='core::convert::Into'>Into</a><&'b <a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.str.html'>str</a>>>(self, about: S) -> Self</code></h4>
|
||
<div class='docblock'><p>Sets a string describing what the program does. This will be displayed when displaying help
|
||
information.</p>
|
||
|
||
<h1 id='examples-4' class='section-header'><a href='#examples-4'>Examples</a></h1>
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"myprog"</span>)
|
||
.<span class='ident'>about</span>(<span class='string'>"Does really amazing things to great people"</span>)</pre>
|
||
</div><h4 id='method.after_help' class='method'><code>fn <a href='#method.after_help' class='fnname'>after_help</a><S: <a class='trait' href='https://doc.rust-lang.org/nightly/core/convert/trait.Into.html' title='core::convert::Into'>Into</a><&'b <a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.str.html'>str</a>>>(self, help: S) -> Self</code></h4>
|
||
<div class='docblock'><p>Adds additional help information to be displayed in addition to auto-generated help. This
|
||
information is displayed <strong>after</strong> the auto-generated help information. This is often used
|
||
to describe how to use the arguments, or caveats to be noted.</p>
|
||
|
||
<h1 id='examples-5' class='section-header'><a href='#examples-5'>Examples</a></h1>
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"myprog"</span>)
|
||
.<span class='ident'>after_help</span>(<span class='string'>"Does really amazing things to great people...but be careful with -R"</span>)</pre>
|
||
</div><h4 id='method.before_help' class='method'><code>fn <a href='#method.before_help' class='fnname'>before_help</a><S: <a class='trait' href='https://doc.rust-lang.org/nightly/core/convert/trait.Into.html' title='core::convert::Into'>Into</a><&'b <a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.str.html'>str</a>>>(self, help: S) -> Self</code></h4>
|
||
<div class='docblock'><p>Adds additional help information to be displayed in addition to auto-generated help. This
|
||
information is displayed <strong>before</strong> the auto-generated help information. This is often used
|
||
for header information.</p>
|
||
|
||
<h1 id='examples-6' class='section-header'><a href='#examples-6'>Examples</a></h1>
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"myprog"</span>)
|
||
.<span class='ident'>before_help</span>(<span class='string'>"Some info I'd like to appear before the help info"</span>)</pre>
|
||
</div><h4 id='method.version' class='method'><code>fn <a href='#method.version' class='fnname'>version</a><S: <a class='trait' href='https://doc.rust-lang.org/nightly/core/convert/trait.Into.html' title='core::convert::Into'>Into</a><&'b <a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.str.html'>str</a>>>(self, ver: S) -> Self</code></h4>
|
||
<div class='docblock'><p>Sets a string of the version number to be displayed when displaying version or help
|
||
information.</p>
|
||
|
||
<p><strong>Pro-tip:</strong> Use <code>clap</code>s convienience macro <code>crate_version!</code> to automatically set your
|
||
application's version to the same thing as your crate at compile time. See the <code>examples/</code>
|
||
directory for more information</p>
|
||
|
||
<h1 id='examples-7' class='section-header'><a href='#examples-7'>Examples</a></h1>
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"myprog"</span>)
|
||
.<span class='ident'>version</span>(<span class='string'>"v0.1.24"</span>)</pre>
|
||
</div><h4 id='method.usage' class='method'><code>fn <a href='#method.usage' class='fnname'>usage</a><S: <a class='trait' href='https://doc.rust-lang.org/nightly/core/convert/trait.Into.html' title='core::convert::Into'>Into</a><&'b <a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.str.html'>str</a>>>(self, usage: S) -> Self</code></h4>
|
||
<div class='docblock'><p>Sets a custom usage string to override the auto-generated usage string.</p>
|
||
|
||
<p>This will be displayed to the user when errors are found in argument parsing, or when you
|
||
call <code>ArgMatches::usage</code></p>
|
||
|
||
<p><strong>CAUTION:</strong> Using this setting disables <code>clap</code>s "context-aware" usage strings. After this
|
||
setting is set, this will be the only usage string displayed to the user!</p>
|
||
|
||
<p><strong>NOTE:</strong> You do not need to specify the "USAGE: \n\t" portion, as that will
|
||
still be applied by <code>clap</code>, you only need to specify the portion starting
|
||
with the binary name.</p>
|
||
|
||
<p><strong>NOTE:</strong> This will not replace the entire help message, <em>only</em> the portion
|
||
showing the usage.</p>
|
||
|
||
<h1 id='examples-8' class='section-header'><a href='#examples-8'>Examples</a></h1>
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"myprog"</span>)
|
||
.<span class='ident'>usage</span>(<span class='string'>"myapp [-clDas] <some_file>"</span>)</pre>
|
||
</div><h4 id='method.help' class='method'><code>fn <a href='#method.help' class='fnname'>help</a><S: <a class='trait' href='https://doc.rust-lang.org/nightly/core/convert/trait.Into.html' title='core::convert::Into'>Into</a><&'b <a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.str.html'>str</a>>>(self, help: S) -> Self</code></h4>
|
||
<div class='docblock'><p>Sets a custom help message and overrides the auto-generated one. This should only be used
|
||
when the auto-generated message does not suffice.</p>
|
||
|
||
<p>This will be displayed to the user when they use <code>--help</code> or <code>-h</code></p>
|
||
|
||
<p><strong>NOTE:</strong> This replaces the <strong>entire</strong> help message, so nothing will be auto-generated.</p>
|
||
|
||
<p><strong>NOTE:</strong> This <strong>only</strong> replaces the help message for the current command, meaning if you
|
||
are using subcommands, those help messages will still be auto-generated unless you
|
||
specify a <code>.help()</code> for them as well.</p>
|
||
|
||
<h1 id='examples-9' class='section-header'><a href='#examples-9'>Examples</a></h1>
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"myapp"</span>)
|
||
.<span class='ident'>help</span>(<span class='string'>"myapp v1.0\n\
|
||
Does awesome things\n\
|
||
(C) me@mail.com\n\n\
|
||
|
||
USAGE: myapp <opts> <comamnd>\n\n\
|
||
|
||
Options:\n\
|
||
-h, --helpe Dispay this message\n\
|
||
-V, --version Display version info\n\
|
||
-s <stuff> Do something with stuff\n\
|
||
-v Be verbose\n\n\
|
||
|
||
Commmands:\n\
|
||
help Prints this message\n\
|
||
work Do some work"</span>)</pre>
|
||
</div><h4 id='method.help_short' class='method'><code>fn <a href='#method.help_short' class='fnname'>help_short</a><S: <a class='trait' href='https://doc.rust-lang.org/nightly/core/convert/trait.AsRef.html' title='core::convert::AsRef'>AsRef</a><<a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.str.html'>str</a>> + 'b>(self, s: S) -> Self</code></h4>
|
||
<div class='docblock'><p>Sets the short version of the <code>help</code> argument without the preceding <code>-</code>.</p>
|
||
|
||
<p>By default <code>clap</code> automatically assigns <code>h</code>, but this can be overridden by defining your
|
||
own argument with a lowercase <code>h</code> as the <code>short</code>. <code>clap</code> lazily generates these help
|
||
arguments <strong>after</strong> you've defined any arguments of your own.</p>
|
||
|
||
<p><strong>NOTE:</strong> Any leading <code>-</code> characters will be stripped, and only the first
|
||
non <code>-</code> chacter will be used as the <code>short</code> version</p>
|
||
|
||
<h1 id='examples-10' class='section-header'><a href='#examples-10'>Examples</a></h1>
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"myprog"</span>)
|
||
.<span class='ident'>help_short</span>(<span class='string'>"H"</span>) <span class='comment'>// Using an uppercase `H` instead of the default lowercase `h`</span></pre>
|
||
</div><h4 id='method.version_short' class='method'><code>fn <a href='#method.version_short' class='fnname'>version_short</a><S: <a class='trait' href='https://doc.rust-lang.org/nightly/core/convert/trait.AsRef.html' title='core::convert::AsRef'>AsRef</a><<a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.str.html'>str</a>>>(self, s: S) -> Self</code></h4>
|
||
<div class='docblock'><p>Sets the short version of the <code>version</code> argument without the preceding <code>-</code>.</p>
|
||
|
||
<p>By default <code>clap</code> automatically assigns <code>V</code>, but this can be overridden by defining your
|
||
own argument with a uppercase <code>V</code> as the <code>short</code>. <code>clap</code> lazily generates these version
|
||
arguments <strong>after</strong> you've defined any arguments of your own.</p>
|
||
|
||
<p><strong>NOTE:</strong> Any leading <code>-</code> characters will be stripped, and only the first
|
||
non <code>-</code> chacter will be used as the <code>short</code> version</p>
|
||
|
||
<h1 id='examples-11' class='section-header'><a href='#examples-11'>Examples</a></h1>
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"myprog"</span>)
|
||
.<span class='ident'>version_short</span>(<span class='string'>"v"</span>) <span class='comment'>// Using a lowercase `v` instead of the default capital `V`</span></pre>
|
||
</div><h4 id='method.template' class='method'><code>fn <a href='#method.template' class='fnname'>template</a><S: <a class='trait' href='https://doc.rust-lang.org/nightly/core/convert/trait.Into.html' title='core::convert::Into'>Into</a><&'b <a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.str.html'>str</a>>>(self, s: S) -> Self</code></h4>
|
||
<div class='docblock'><p>Sets the help template to be used, overriding the default format.</p>
|
||
|
||
<p>Tags arg given inside curly brackets:
|
||
Valid tags are:
|
||
* <code>{bin}</code> - Binary name.
|
||
* <code>{version}</code> - Version number.
|
||
* <code>{author}</code> - Author information.
|
||
* <code>{usage}</code> - Automatically generated or given usage string.
|
||
* <code>{all-args}</code> - Help for all arguments (options, flags, positionals arguments,
|
||
and subcommands) including titles.
|
||
* <code>{unified}</code> - Unified help for options and flags.
|
||
* <code>{flags}</code> - Help for flags.
|
||
* <code>{options}</code> - Help for options.
|
||
* <code>{positionals}</code> - Help for positionals arguments.
|
||
* <code>{subcommands}</code> - Help for subcommands.
|
||
* <code>{after-help}</code> - Help for flags.</p>
|
||
|
||
<h1 id='examples-12' class='section-header'><a href='#examples-12'>Examples</a></h1>
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"myprog"</span>)
|
||
.<span class='ident'>version</span>(<span class='string'>"1.0"</span>)
|
||
.<span class='ident'>template</span>(<span class='string'>"{bin} ({version}) - {usage}"</span>)</pre>
|
||
|
||
<p><strong>NOTE:</strong>The template system is, on purpose, very simple. Therefore the tags have to writen
|
||
in the lowercase and without spacing.</p>
|
||
</div><h4 id='method.setting' class='method'><code>fn <a href='#method.setting' class='fnname'>setting</a>(self, setting: <a class='enum' href='../clap/enum.AppSettings.html' title='clap::AppSettings'>AppSettings</a>) -> Self</code></h4>
|
||
<div class='docblock'><p>Enables a single Application level settings.</p>
|
||
|
||
<p>See <code>AppSettings</code> for a full list of possibilities and examples.</p>
|
||
|
||
<h1 id='examples-13' class='section-header'><a href='#examples-13'>Examples</a></h1>
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"myprog"</span>)
|
||
.<span class='ident'>setting</span>(<span class='ident'>AppSettings</span>::<span class='ident'>SubcommandRequired</span>)
|
||
.<span class='ident'>setting</span>(<span class='ident'>AppSettings</span>::<span class='ident'>WaitOnError</span>)</pre>
|
||
</div><h4 id='method.settings' class='method'><code>fn <a href='#method.settings' class='fnname'>settings</a>(self, settings: <a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.slice.html'>&[</a><a class='enum' href='../clap/enum.AppSettings.html' title='clap::AppSettings'>AppSettings</a><a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.slice.html'>]</a>) -> Self</code></h4>
|
||
<div class='docblock'><p>Enables multiple Application level settings</p>
|
||
|
||
<p>See <code>AppSettings</code> for a full list of possibilities and examples.</p>
|
||
|
||
<h1 id='examples-14' class='section-header'><a href='#examples-14'>Examples</a></h1>
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"myprog"</span>)
|
||
.<span class='ident'>settings</span>(<span class='kw-2'>&</span>[<span class='ident'>AppSettings</span>::<span class='ident'>SubcommandRequired</span>,
|
||
<span class='ident'>AppSettings</span>::<span class='ident'>WaitOnError</span>])</pre>
|
||
</div><h4 id='method.arg' class='method'><code>fn <a href='#method.arg' class='fnname'>arg</a><A: <a class='trait' href='https://doc.rust-lang.org/nightly/core/borrow/trait.Borrow.html' title='core::borrow::Borrow'>Borrow</a><<a class='struct' href='../clap/struct.Arg.html' title='clap::Arg'>Arg</a><'a, 'b>> + 'a>(self, a: A) -> Self</code></h4>
|
||
<div class='docblock'><p>Adds an argument to the list of valid possibilties.</p>
|
||
|
||
<h1 id='examples-15' class='section-header'><a href='#examples-15'>Examples</a></h1>
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"myprog"</span>)
|
||
<span class='comment'>// Adding a single "flag" argument with a short and help text, using Arg::with_name()</span>
|
||
.<span class='ident'>arg</span>(
|
||
<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"debug"</span>)
|
||
.<span class='ident'>short</span>(<span class='string'>"d"</span>)
|
||
.<span class='ident'>help</span>(<span class='string'>"turns on debugging mode"</span>)
|
||
)
|
||
<span class='comment'>// Adding a single "option" argument with a short, a long, and help text using the less</span>
|
||
<span class='comment'>// verbose Arg::from_usage()</span>
|
||
.<span class='ident'>arg</span>(
|
||
<span class='ident'>Arg</span>::<span class='ident'>from_usage</span>(<span class='string'>"-c --config=[CONFIG] 'Optionally sets a config file to use'"</span>)
|
||
)</pre>
|
||
</div><h4 id='method.args' class='method'><code>fn <a href='#method.args' class='fnname'>args</a>(self, args: <a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.slice.html'>&[</a><a class='struct' href='../clap/struct.Arg.html' title='clap::Arg'>Arg</a><'a, 'b><a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.slice.html'>]</a>) -> Self</code></h4>
|
||
<div class='docblock'><p>Adds multiple arguments to the list of valid possibilties</p>
|
||
|
||
<h1 id='examples-16' class='section-header'><a href='#examples-16'>Examples</a></h1>
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"myprog"</span>)
|
||
.<span class='ident'>args</span>(
|
||
<span class='kw-2'>&</span>[<span class='ident'>Arg</span>::<span class='ident'>from_usage</span>(<span class='string'>"[debug] -d 'turns on debugging info'"</span>),
|
||
<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"input"</span>).<span class='ident'>index</span>(<span class='number'>1</span>).<span class='ident'>help</span>(<span class='string'>"the input file to use"</span>)]
|
||
)</pre>
|
||
</div><h4 id='method.arg_from_usage' class='method'><code>fn <a href='#method.arg_from_usage' class='fnname'>arg_from_usage</a>(self, usage: &'a <a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.str.html'>str</a>) -> Self</code></h4>
|
||
<div class='docblock'><p>A convienience method for adding a single argument from a usage type string. The string
|
||
used follows the same rules and syntax as <code>Arg::from_usage()</code></p>
|
||
|
||
<p><strong>NOTE:</strong> The downside to using this method is that you can not set any additional
|
||
properties of the <code>Arg</code> other than what <code>Arg::from_usage()</code> supports.</p>
|
||
|
||
<h1 id='examples-17' class='section-header'><a href='#examples-17'>Examples</a></h1>
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"myprog"</span>)
|
||
.<span class='ident'>arg_from_usage</span>(<span class='string'>"-c --config=<FILE> 'Sets a configuration file to use'"</span>)</pre>
|
||
</div><h4 id='method.args_from_usage' class='method'><code>fn <a href='#method.args_from_usage' class='fnname'>args_from_usage</a>(self, usage: &'a <a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.str.html'>str</a>) -> Self</code></h4>
|
||
<div class='docblock'><p>Adds multiple arguments at once from a usage string, one per line. See <code>Arg::from_usage()</code>
|
||
for details on the syntax and rules supported.</p>
|
||
|
||
<p><strong>NOTE:</strong> Like <code>App::arg_from_usage()</code> the downside is you only set properties for the
|
||
<code>Arg</code>s which <code>Arg::from_usage()</code> supports.</p>
|
||
|
||
<h1 id='examples-18' class='section-header'><a href='#examples-18'>Examples</a></h1>
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"myprog"</span>)
|
||
.<span class='ident'>args_from_usage</span>(
|
||
<span class='string'>"-c --config=[FILE] 'Sets a configuration file to use'
|
||
[debug]... -d 'Sets the debugging level'
|
||
<FILE> 'The input file to use'"</span>
|
||
)</pre>
|
||
</div><h4 id='method.group' class='method'><code>fn <a href='#method.group' class='fnname'>group</a>(self, group: <a class='struct' href='../clap/struct.ArgGroup.html' title='clap::ArgGroup'>ArgGroup</a><'a>) -> Self</code></h4>
|
||
<div class='docblock'><p>Adds an <code>ArgGroup</code> to the application. <code>ArgGroup</code>s are a family of related arguments. By
|
||
placing them in a logical group, you can build easier requirement and exclusion rules. For
|
||
instance, you can make an entire <code>ArgGroup</code> required, meaning that one (and <em>only</em> one) argument
|
||
from that group must be present at runtime.</p>
|
||
|
||
<p>You can also do things such as name an <code>ArgGroup</code> as a conflict to another argument.
|
||
Meaning any of the arguments that belong to that group will cause a failure if present with
|
||
the conflicting argument.</p>
|
||
|
||
<p>Another added benfit of <code>ArgGroup</code>s is that you can extract a value from a group instead of
|
||
determining exactly which argument was used.</p>
|
||
|
||
<p>Finally, using <code>ArgGroup</code>s to ensure exclusion between arguments is another very common use</p>
|
||
|
||
<h1 id='examples-19' class='section-header'><a href='#examples-19'>Examples</a></h1>
|
||
<p>The following example demonstrates using an <code>ArgGroup</code> to ensure that one, and only one, of
|
||
the arguments from the specified group is present at runtime.</p>
|
||
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"app"</span>)
|
||
.<span class='ident'>args_from_usage</span>(
|
||
<span class='string'>"--set-ver [ver] 'set the version manually'
|
||
--major 'auto increase major'
|
||
--minor 'auto increase minor'
|
||
--patch 'auto increase patch'"</span>)
|
||
.<span class='ident'>group</span>(<span class='ident'>ArgGroup</span>::<span class='ident'>with_name</span>(<span class='string'>"vers"</span>)
|
||
.<span class='ident'>args</span>(<span class='kw-2'>&</span>[<span class='string'>"set-ver"</span>, <span class='string'>"major"</span>, <span class='string'>"minor"</span>,<span class='string'>"patch"</span>])
|
||
.<span class='ident'>required</span>(<span class='boolval'>true</span>))</pre>
|
||
</div><h4 id='method.groups' class='method'><code>fn <a href='#method.groups' class='fnname'>groups</a>(self, groups: <a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.slice.html'>&[</a><a class='struct' href='../clap/struct.ArgGroup.html' title='clap::ArgGroup'>ArgGroup</a><'a><a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.slice.html'>]</a>) -> Self</code></h4>
|
||
<div class='docblock'><p>Adds multiple <code>ArgGroup</code>s to the application at once.</p>
|
||
|
||
<h1 id='examples-20' class='section-header'><a href='#examples-20'>Examples</a></h1>
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"app"</span>)
|
||
.<span class='ident'>args_from_usage</span>(
|
||
<span class='string'>"--set-ver [ver] 'set the version manually'
|
||
--major 'auto increase major'
|
||
--minor 'auto increase minor'
|
||
--patch 'auto increase patch'
|
||
-c [FILE] 'a config file'
|
||
-i [IFACE] 'an interface'"</span>)
|
||
.<span class='ident'>groups</span>(<span class='kw-2'>&</span>[
|
||
<span class='ident'>ArgGroup</span>::<span class='ident'>with_name</span>(<span class='string'>"vers"</span>)
|
||
.<span class='ident'>args</span>(<span class='kw-2'>&</span>[<span class='string'>"set-ver"</span>, <span class='string'>"major"</span>, <span class='string'>"minor"</span>,<span class='string'>"patch"</span>])
|
||
.<span class='ident'>required</span>(<span class='boolval'>true</span>),
|
||
<span class='ident'>ArgGroup</span>::<span class='ident'>with_name</span>(<span class='string'>"input"</span>)
|
||
.<span class='ident'>args</span>(<span class='kw-2'>&</span>[<span class='string'>"c"</span>, <span class='string'>"i"</span>])
|
||
])</pre>
|
||
</div><h4 id='method.subcommand' class='method'><code>fn <a href='#method.subcommand' class='fnname'>subcommand</a>(self, subcmd: <a class='struct' href='../clap/struct.App.html' title='clap::App'>App</a><'a, 'b>) -> Self</code></h4>
|
||
<div class='docblock'><p>Adds a subcommand to the list of valid possibilties. Subcommands are effectively sub-apps,
|
||
because they can contain their own arguments, subcommands, version, usage, etc. They also
|
||
function just like apps, in that they get their own auto generated help, version, and
|
||
usage.</p>
|
||
|
||
<h1 id='examples-21' class='section-header'><a href='#examples-21'>Examples</a></h1>
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"myprog"</span>)
|
||
.<span class='ident'>subcommand</span>(<span class='ident'>SubCommand</span>::<span class='ident'>with_name</span>(<span class='string'>"config"</span>)
|
||
.<span class='ident'>about</span>(<span class='string'>"Controls configuration features"</span>)
|
||
.<span class='ident'>arg_from_usage</span>(<span class='string'>"<config> 'Required configuration file to use'"</span>))</pre>
|
||
</div><h4 id='method.subcommands' class='method'><code>fn <a href='#method.subcommands' class='fnname'>subcommands</a><I>(self, subcmds: I) -> Self <span class='where'>where I: <a class='trait' href='https://doc.rust-lang.org/nightly/core/iter/traits/trait.IntoIterator.html' title='core::iter::traits::IntoIterator'>IntoIterator</a><Item=<a class='struct' href='../clap/struct.App.html' title='clap::App'>App</a><'a, 'b>></span></code></h4>
|
||
<div class='docblock'><p>Adds multiple subcommands to the list of valid possibilties by iterating over a Vec of
|
||
<code>SubCommand</code>s</p>
|
||
|
||
<h1 id='examples-22' class='section-header'><a href='#examples-22'>Examples</a></h1>
|
||
<pre class='rust rust-example-rendered'>
|
||
.<span class='ident'>subcommands</span>( <span class='macro'>vec</span><span class='macro'>!</span>[
|
||
<span class='ident'>SubCommand</span>::<span class='ident'>with_name</span>(<span class='string'>"config"</span>).<span class='ident'>about</span>(<span class='string'>"Controls configuration functionality"</span>)
|
||
.<span class='ident'>arg</span>(<span class='ident'>Arg</span>::<span class='ident'>with_name</span>(<span class='string'>"config_file"</span>).<span class='ident'>index</span>(<span class='number'>1</span>)),
|
||
<span class='ident'>SubCommand</span>::<span class='ident'>with_name</span>(<span class='string'>"debug"</span>).<span class='ident'>about</span>(<span class='string'>"Controls debug functionality"</span>)])</pre>
|
||
</div><h4 id='method.display_order' class='method'><code>fn <a href='#method.display_order' class='fnname'>display_order</a>(self, ord: <a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.usize.html'>usize</a>) -> Self</code></h4>
|
||
<div class='docblock'><p>Allows custom ordering of subcommands within the help message. Subcommands with a lower
|
||
value will be displayed first in the help message. This is helpful when one would like to
|
||
emphasise frequently used subcommands, or prioritize those towards the top of the list.
|
||
Duplicate values <strong>are</strong> allowed. Subcommands with duplicate display orders will be
|
||
displayed in alphabetical order.</p>
|
||
|
||
<p><strong>NOTE:</strong> The default is 999 for all subcommands.</p>
|
||
|
||
<h1 id='examples-23' class='section-header'><a href='#examples-23'>Examples</a></h1>
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>let</span> <span class='ident'>m</span> <span class='op'>=</span> <span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"cust-ord"</span>)
|
||
.<span class='ident'>subcommand</span>(<span class='ident'>SubCommand</span>::<span class='ident'>with_name</span>(<span class='string'>"alpha"</span>) <span class='comment'>// typically subcommands are grouped</span>
|
||
<span class='comment'>// alphabetically by name. Subcommands</span>
|
||
<span class='comment'>// without a display_order have a value of</span>
|
||
<span class='comment'>// 999 and are displayed alphabetically with</span>
|
||
<span class='comment'>// all other 999 subcommands</span>
|
||
.<span class='ident'>about</span>(<span class='string'>"Some help and text"</span>))
|
||
.<span class='ident'>subcommand</span>(<span class='ident'>SubCommand</span>::<span class='ident'>with_name</span>(<span class='string'>"beta"</span>)
|
||
.<span class='ident'>display_order</span>(<span class='number'>1</span>) <span class='comment'>// In order to force this subcommand to appear *first*</span>
|
||
<span class='comment'>// all we have to do is give it a value lower than 999.</span>
|
||
<span class='comment'>// Any other subcommands with a value of 1 will be displayed</span>
|
||
<span class='comment'>// alphabetically with this one...then 2 values, then 3, etc.</span>
|
||
.<span class='ident'>about</span>(<span class='string'>"I should be first!"</span>))
|
||
.<span class='ident'>get_matches_from</span>(<span class='macro'>vec</span><span class='macro'>!</span>[
|
||
<span class='string'>"cust-ord"</span>, <span class='string'>"--help"</span>
|
||
]);</pre>
|
||
|
||
<p>The above example displays the following help message</p>
|
||
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='ident'>cust</span><span class='op'>-</span><span class='ident'>ord</span>
|
||
|
||
<span class='ident'>USAGE</span>:
|
||
<span class='ident'>cust</span><span class='op'>-</span><span class='ident'>ord</span> [<span class='ident'>FLAGS</span>] [<span class='ident'>OPTIONS</span>]
|
||
|
||
<span class='ident'>FLAGS</span>:
|
||
<span class='op'>-</span><span class='ident'>h</span>, <span class='op'>-</span><span class='op'>-</span><span class='ident'>help</span> <span class='ident'>Prints</span> <span class='ident'>help</span> <span class='ident'>information</span>
|
||
<span class='op'>-</span><span class='ident'>V</span>, <span class='op'>-</span><span class='op'>-</span><span class='ident'>version</span> <span class='ident'>Prints</span> <span class='ident'>version</span> <span class='ident'>information</span>
|
||
|
||
<span class='ident'>SUBCOMMANDS</span>:
|
||
<span class='ident'>beta</span> <span class='ident'>I</span> <span class='ident'>should</span> <span class='ident'>be</span> <span class='macro'>first</span><span class='macro'>!</span>
|
||
<span class='ident'>alpha</span> <span class='prelude-val'>Some</span> <span class='ident'>help</span> <span class='ident'>and</span> <span class='ident'>text</span></pre>
|
||
</div><h4 id='method.print_help' class='method'><code>fn <a href='#method.print_help' class='fnname'>print_help</a>(&self) -> <a class='type' href='../clap/type.Result.html' title='clap::Result'>ClapResult</a><<a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.tuple.html'>()</a>></code></h4>
|
||
<div class='docblock'><p>Prints the full help message to <code>io::stdout()</code> using a <code>BufWriter</code></p>
|
||
|
||
<h1 id='examples-24' class='section-header'><a href='#examples-24'>Examples</a></h1>
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>let</span> <span class='ident'>app</span> <span class='op'>=</span> <span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"myprog"</span>);
|
||
<span class='ident'>app</span>.<span class='ident'>print_help</span>();</pre>
|
||
</div><h4 id='method.write_help' class='method'><code>fn <a href='#method.write_help' class='fnname'>write_help</a><W: <a class='trait' href='https://doc.rust-lang.org/nightly/std/io/trait.Write.html' title='std::io::Write'>Write</a>>(&self, w: &mut W) -> <a class='type' href='../clap/type.Result.html' title='clap::Result'>ClapResult</a><<a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.tuple.html'>()</a>></code></h4>
|
||
<div class='docblock'><p>Writes the full help message to the user to a <code>io::Write</code> object</p>
|
||
|
||
<h1 id='examples-25' class='section-header'><a href='#examples-25'>Examples</a></h1>
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>use</span> <span class='ident'>std</span>::<span class='ident'>io</span>;
|
||
<span class='kw'>let</span> <span class='kw-2'>mut</span> <span class='ident'>app</span> <span class='op'>=</span> <span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"myprog"</span>);
|
||
<span class='kw'>let</span> <span class='kw-2'>mut</span> <span class='ident'>out</span> <span class='op'>=</span> <span class='ident'>io</span>::<span class='ident'>stdout</span>();
|
||
<span class='ident'>app</span>.<span class='ident'>write_help</span>(<span class='kw-2'>&</span><span class='kw-2'>mut</span> <span class='ident'>out</span>).<span class='ident'>ok</span>().<span class='ident'>expect</span>(<span class='string'>"failed to write to stdout"</span>);</pre>
|
||
</div><h4 id='method.get_matches' class='method'><code>fn <a href='#method.get_matches' class='fnname'>get_matches</a>(self) -> <a class='struct' href='../clap/struct.ArgMatches.html' title='clap::ArgMatches'>ArgMatches</a><'a></code></h4>
|
||
<div class='docblock'><p>Starts the parsing process, upon a failed parse an error will be displayed to the user and
|
||
the process with exit with the appropriate error code. By default this method gets matches
|
||
from <code>env::args_os</code></p>
|
||
|
||
<h1 id='examples-26' class='section-header'><a href='#examples-26'>Examples</a></h1>
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>let</span> <span class='ident'>matches</span> <span class='op'>=</span> <span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"myprog"</span>)
|
||
<span class='comment'>// Args and options go here...</span>
|
||
.<span class='ident'>get_matches</span>();</pre>
|
||
</div><h4 id='method.get_matches_safe' class='method'><code>fn <a href='#method.get_matches_safe' class='fnname'>get_matches_safe</a>(self) -> <a class='type' href='../clap/type.Result.html' title='clap::Result'>ClapResult</a><<a class='struct' href='../clap/struct.ArgMatches.html' title='clap::ArgMatches'>ArgMatches</a><'a>></code></h4>
|
||
<div class='docblock'><p>Starts the parsing process. This method will return a <code>Result</code> type instead of exiting the
|
||
the process on failed parse. By default this method gets matches
|
||
from <code>env::args_os</code></p>
|
||
|
||
<p><strong>NOTE:</strong> This method WILL NOT exit when <code>--help</code> or <code>--version</code> (or short versions) are
|
||
used. It will return an error, where the <code>kind</code> is a <code>ErrorKind::HelpDisplayed</code>
|
||
or <code>ErrorKind::VersionDisplayed</code> respectively. You must call <code>error.exit()</code> or
|
||
perform a <code>std::process::exit</code>.</p>
|
||
|
||
<h1 id='examples-27' class='section-header'><a href='#examples-27'>Examples</a></h1>
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>let</span> <span class='ident'>matches</span> <span class='op'>=</span> <span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"myprog"</span>)
|
||
<span class='comment'>// Args and options go here...</span>
|
||
.<span class='ident'>get_matches_safe</span>()
|
||
.<span class='ident'>unwrap_or_else</span>( <span class='op'>|</span><span class='ident'>e</span><span class='op'>|</span> <span class='ident'>e</span>.<span class='ident'>exit</span>() );</pre>
|
||
</div><h4 id='method.get_matches_from' class='method'><code>fn <a href='#method.get_matches_from' class='fnname'>get_matches_from</a><I, T>(self, itr: I) -> <a class='struct' href='../clap/struct.ArgMatches.html' title='clap::ArgMatches'>ArgMatches</a><'a> <span class='where'>where I: <a class='trait' href='https://doc.rust-lang.org/nightly/core/iter/traits/trait.IntoIterator.html' title='core::iter::traits::IntoIterator'>IntoIterator</a><Item=T>, T: <a class='trait' href='https://doc.rust-lang.org/nightly/core/convert/trait.Into.html' title='core::convert::Into'>Into</a><<a class='struct' href='https://doc.rust-lang.org/nightly/std/ffi/os_str/struct.OsString.html' title='std::ffi::os_str::OsString'>OsString</a>></span></code></h4>
|
||
<div class='docblock'><p>Starts the parsing process. Like <code>App::get_matches</code> this method does not return a <code>Result</code>
|
||
and will automatically exit with an error message. This method, however, lets you specify
|
||
what iterator to use when performing matches, such as a <code>Vec</code> of your making.</p>
|
||
|
||
<p><strong>NOTE:</strong> The first argument will be parsed as the binary name unless
|
||
<code>AppSettings::NoBinaryName</code> is used</p>
|
||
|
||
<h1 id='examples-28' class='section-header'><a href='#examples-28'>Examples</a></h1>
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>let</span> <span class='ident'>arg_vec</span> <span class='op'>=</span> <span class='macro'>vec</span><span class='macro'>!</span>[<span class='string'>"my_prog"</span>, <span class='string'>"some"</span>, <span class='string'>"args"</span>, <span class='string'>"to"</span>, <span class='string'>"parse"</span>];
|
||
|
||
<span class='kw'>let</span> <span class='ident'>matches</span> <span class='op'>=</span> <span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"myprog"</span>)
|
||
<span class='comment'>// Args and options go here...</span>
|
||
.<span class='ident'>get_matches_from</span>(<span class='ident'>arg_vec</span>);</pre>
|
||
</div><h4 id='method.get_matches_from_safe' class='method'><code>fn <a href='#method.get_matches_from_safe' class='fnname'>get_matches_from_safe</a><I, T>(self, itr: I) -> <a class='type' href='../clap/type.Result.html' title='clap::Result'>ClapResult</a><<a class='struct' href='../clap/struct.ArgMatches.html' title='clap::ArgMatches'>ArgMatches</a><'a>> <span class='where'>where I: <a class='trait' href='https://doc.rust-lang.org/nightly/core/iter/traits/trait.IntoIterator.html' title='core::iter::traits::IntoIterator'>IntoIterator</a><Item=T>, T: <a class='trait' href='https://doc.rust-lang.org/nightly/core/convert/trait.Into.html' title='core::convert::Into'>Into</a><<a class='struct' href='https://doc.rust-lang.org/nightly/std/ffi/os_str/struct.OsString.html' title='std::ffi::os_str::OsString'>OsString</a>></span></code></h4>
|
||
<div class='docblock'><p>Starts the parsing process. A combination of <code>App::get_matches_from</code>, and
|
||
<code>App::get_matches_safe</code></p>
|
||
|
||
<p><strong>NOTE:</strong> This method WILL NOT exit when <code>--help</code> or <code>--version</code> (or short versions) are
|
||
used. It will return an error, where the <code>kind</code> is a <code>ErrorKind::HelpDisplayed</code>
|
||
or <code>ErrorKind::VersionDisplayed</code> respectively. You must call <code>error.exit()</code> or
|
||
perform a <code>std::process::exit</code> yourself.</p>
|
||
|
||
<p><strong>NOTE:</strong> The first argument will be parsed as the binary name unless
|
||
<code>AppSettings::NoBinaryName</code> is used</p>
|
||
|
||
<h1 id='examples-29' class='section-header'><a href='#examples-29'>Examples</a></h1>
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>let</span> <span class='ident'>arg_vec</span> <span class='op'>=</span> <span class='macro'>vec</span><span class='macro'>!</span>[<span class='string'>"my_prog"</span>, <span class='string'>"some"</span>, <span class='string'>"args"</span>, <span class='string'>"to"</span>, <span class='string'>"parse"</span>];
|
||
|
||
<span class='kw'>let</span> <span class='ident'>matches</span> <span class='op'>=</span> <span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"myprog"</span>)
|
||
<span class='comment'>// Args and options go here...</span>
|
||
.<span class='ident'>get_matches_from_safe</span>(<span class='ident'>arg_vec</span>)
|
||
.<span class='ident'>unwrap_or_else</span>( <span class='op'>|</span><span class='ident'>e</span><span class='op'>|</span> { <span class='macro'>panic</span><span class='macro'>!</span>(<span class='string'>"An error occurs: {}"</span>, <span class='ident'>e</span>) });</pre>
|
||
</div><h4 id='method.get_matches_from_safe_borrow' class='method'><code>fn <a href='#method.get_matches_from_safe_borrow' class='fnname'>get_matches_from_safe_borrow</a><I, T>(&mut self, itr: I) -> <a class='type' href='../clap/type.Result.html' title='clap::Result'>ClapResult</a><<a class='struct' href='../clap/struct.ArgMatches.html' title='clap::ArgMatches'>ArgMatches</a><'a>> <span class='where'>where I: <a class='trait' href='https://doc.rust-lang.org/nightly/core/iter/traits/trait.IntoIterator.html' title='core::iter::traits::IntoIterator'>IntoIterator</a><Item=T>, T: <a class='trait' href='https://doc.rust-lang.org/nightly/core/convert/trait.Into.html' title='core::convert::Into'>Into</a><<a class='struct' href='https://doc.rust-lang.org/nightly/std/ffi/os_str/struct.OsString.html' title='std::ffi::os_str::OsString'>OsString</a>></span></code></h4>
|
||
<div class='docblock'><p>Starts the parsing process without consuming the <code>App</code> struct <code>self</code>. This is normally not
|
||
the desired functionality, instead prefer <code>App::get_matches_from_safe</code> which <em>does</em>
|
||
consume <code>self</code>.</p>
|
||
|
||
<p><strong>NOTE:</strong> The first argument will be parsed as the binary name unless
|
||
<code>AppSettings::NoBinaryName</code> is used</p>
|
||
|
||
<h1 id='examples-30' class='section-header'><a href='#examples-30'>Examples</a></h1>
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>let</span> <span class='ident'>arg_vec</span> <span class='op'>=</span> <span class='macro'>vec</span><span class='macro'>!</span>[<span class='string'>"my_prog"</span>, <span class='string'>"some"</span>, <span class='string'>"args"</span>, <span class='string'>"to"</span>, <span class='string'>"parse"</span>];
|
||
|
||
<span class='kw'>let</span> <span class='kw-2'>mut</span> <span class='ident'>app</span> <span class='op'>=</span> <span class='ident'>App</span>::<span class='ident'>new</span>(<span class='string'>"myprog"</span>);
|
||
<span class='comment'>// Args and options go here...</span>
|
||
<span class='kw'>let</span> <span class='ident'>matches</span> <span class='op'>=</span> <span class='ident'>app</span>.<span class='ident'>get_matches_from_safe_borrow</span>(<span class='ident'>arg_vec</span>)
|
||
.<span class='ident'>unwrap_or_else</span>( <span class='op'>|</span><span class='ident'>e</span><span class='op'>|</span> { <span class='macro'>panic</span><span class='macro'>!</span>(<span class='string'>"An error occurs: {}"</span>, <span class='ident'>e</span>) });</pre>
|
||
</div></div><h2 id='implementations'>Trait Implementations</h2><h3 class='impl'><code>impl<'a, 'b> <a class='trait' href='https://doc.rust-lang.org/nightly/core/clone/trait.Clone.html' title='core::clone::Clone'>Clone</a> for <a class='struct' href='../clap/struct.App.html' title='clap::App'>App</a><'a, 'b></code></h3><div class='impl-items'><h4 id='method.clone' class='method'><code>fn <a href='https://doc.rust-lang.org/nightly/core/clone/trait.Clone.html#tymethod.clone' class='fnname'>clone</a>(&self) -> Self</code></h4>
|
||
<h4 id='method.clone_from' class='method'><code>fn <a href='https://doc.rust-lang.org/nightly/core/clone/trait.Clone.html#method.clone_from' class='fnname'>clone_from</a>(&mut self, source: &Self)</code><span class="since">1.0.0</span></h4>
|
||
</div><h3 class='impl'><code>impl<'n, 'e> <a class='trait' href='https://doc.rust-lang.org/nightly/core/fmt/trait.Display.html' title='core::fmt::Display'>Display</a> for <a class='struct' href='../clap/struct.App.html' title='clap::App'>App</a><'n, 'e></code></h3><div class='impl-items'><h4 id='method.fmt' class='method'><code>fn <a href='https://doc.rust-lang.org/nightly/core/fmt/trait.Display.html#tymethod.fmt' class='fnname'>fmt</a>(&self, f: &mut <a class='struct' href='https://doc.rust-lang.org/nightly/core/fmt/struct.Formatter.html' title='core::fmt::Formatter'>Formatter</a>) -> <a class='type' href='https://doc.rust-lang.org/nightly/core/fmt/type.Result.html' title='core::fmt::Result'>Result</a></code></h4>
|
||
</div></section>
|
||
<section id='search' class="content hidden"></section>
|
||
|
||
<section class="footer"></section>
|
||
|
||
<aside id="help" class="hidden">
|
||
<div>
|
||
<h1 class="hidden">Help</h1>
|
||
|
||
<div class="shortcuts">
|
||
<h2>Keyboard Shortcuts</h2>
|
||
|
||
<dl>
|
||
<dt>?</dt>
|
||
<dd>Show this help dialog</dd>
|
||
<dt>S</dt>
|
||
<dd>Focus the search field</dd>
|
||
<dt>⇤</dt>
|
||
<dd>Move up in search results</dd>
|
||
<dt>⇥</dt>
|
||
<dd>Move down in search results</dd>
|
||
<dt>⏎</dt>
|
||
<dd>Go to active search result</dd>
|
||
</dl>
|
||
</div>
|
||
|
||
<div class="infos">
|
||
<h2>Search Tricks</h2>
|
||
|
||
<p>
|
||
Prefix searches with a type followed by a colon (e.g.
|
||
<code>fn:</code>) to restrict the search to a given type.
|
||
</p>
|
||
|
||
<p>
|
||
Accepted types are: <code>fn</code>, <code>mod</code>,
|
||
<code>struct</code>, <code>enum</code>,
|
||
<code>trait</code>, <code>type</code>, <code>macro</code>,
|
||
and <code>const</code>.
|
||
</p>
|
||
|
||
<p>
|
||
Search functions by type signature (e.g.
|
||
<code>vec -> usize</code> or <code>* -> vec</code>)
|
||
</p>
|
||
</div>
|
||
</div>
|
||
</aside>
|
||
|
||
|
||
|
||
<script>
|
||
window.rootPath = "../";
|
||
window.currentCrate = "clap";
|
||
window.playgroundUrl = "";
|
||
</script>
|
||
<script src="../jquery.js"></script>
|
||
<script src="../main.js"></script>
|
||
|
||
<script defer src="../search-index.js"></script>
|
||
</body>
|
||
</html> |