Mirrors/clap
2
0
Fork 0
mirror of https://github.com/clap-rs/clap synced 2024-12-13 14:22:34 +00:00
Code Issues Projects Releases Packages Wiki Activity

chore(clap): rebuild documentation

Browse source
This commit is contained in:
Kevin K 2015-04-16 12:56:51 -04:00
parent 1a192521b6
commit 484584148c
11 changed files with 84 additions and 67 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

61
docs/clap/index.html
View file

@ -43,33 +43,23 @@
<section id='main' class="content mod">
<h1 class='fqn'><span class='in-band'>Crate <a class='mod' href=''>clap</a><wbr></span><span class='out-of-band'><a href='stability.html'>[stability]</a> <span id='render-detail'>
<a id="collapse-all" href="#">[-]</a>&nbsp;<a id="expand-all" href="#">[+]</a>
</span><a id='src-0' href='../src/clap/lib.rs.html#1-902'>[src]</a></span></h1>
</span><a id='src-0' href='../src/clap/lib.rs.html#1-907'>[src]</a></span></h1>
<div class='docblock'>
<h1 id="clap" class='section-header'><a
href="#clap">clap</a></h1>
<p><img src="https://travis-ci.org/kbknapp/clap-rs.svg?branch=master" alt="Travis-CI"> <a href="https://gitter.im/kbknapp/clap-rs?utm_source=badge&amp;utm_medium=badge&amp;utm_campaign=pr-badge&amp;utm_content=badge"><img src="https://badges.gitter.im/Join%20Chat.svg" alt="Join the chat at https://gitter.im/kbknapp/clap-rs"></a></p>
<p>Command Line Argument Parser written in Rust</p>
<p>Command Line Argument Parser for Rust</p>
<p>It is a simple to use and efficient library for parsing command line arguments and subcommands when writing console, or terminal applications.</p>
<h2 id="video-tutorials" class='section-header'><a
href="#video-tutorials">Video Tutorials</a></h2>
<p>I&#39;ve been working on a few short video tutorials about using <code>clap</code>. They&#39;re located on <a href="https://www.youtube.com/playlist?list=PLza5oFLQGTl0Bc_EU_pBNcX-rhVqDTRxv">youtube</a>. </p>
<p><em>Note</em>: The videos have not been updated to include the new <code>from_usage()</code> methods which make building args significantly less verbose. New videos will be added soon.</p>
<p><em>Note</em>: Apologies for the resolution of the first video, it will be updated to a better resolution soon. The other videos have a proper resolution.</p>
<h2 id="about" class='section-header'><a
href="#about">About</a></h2>
<p>You can use <code>clap</code> to lay out a list of possible valid command line arguments and subcommands, then let <code>clap</code> parse <em>and validate</em> the string given by the user at runtime. This means you focus on your applications functionality, not parsing and validating arguments.</p>
<p><code>clap</code> is used to parse <em>and validate</em> the string of command line arguments provided by the user at runtime. You simply provide the list of valid possibilities, and <code>clap</code> handles the rest. This means you focus on your <em>applications</em> functionality, and less on the parsing and validating of arguments.</p>
<p>What is different about <code>clap</code> from other options available is the very simple almost &#39;Pythonic&#39; style in which you define the valid available arguments for your program, while still giving advanced features. <code>clap</code> allows you express complex relationships between arguments in a very simple manner. This means you don&#39;t have to spend tons time learning an entirely new library&#39;s structures and use. The basics of <code>clap</code> can be learned almost intuitively.</p>
<p><code>clap</code> also provides all the traditional version and help switches (or flags) &#39;for free.&#39; It does this by checking list of valid possibilities you supplied and if you haven&#39;t defined those flags already (or only defined some of them), <code>clap</code> will auto-generate the applicable ones (as well as a &quot;help&quot; subcommand so long as other subcommands have been manually defined as well).</p>
<p><code>clap</code> also provides all the traditional version and help switches (or flags) &#39;for free&#39; by parsing the list of developer supplied arguments. If the developer hasn&#39;t defined them already (or only defined some of them), <code>clap</code> will auto-generate the applicable &quot;help&quot; and &quot;version&quot; switches (as well as a &quot;help&quot; subcommand so long as other subcommands have been manually defined as well).</p>
<p>After defining a list of possible valid arguments and subcommands, <code>clap</code> parses the string given by the end-user at runtime then gives you a list of the valid matches and their values. If the user made an error or typo, <code>clap</code> informs them and exits gracefully. This means that you can simply use these matches and values to determine the functioning of your program.</p>
<p>After <code>clap</code> finishes parsing the user provided string, it returns all the matches along with any applicable values. If the user made an error or typo, <code>clap</code> informs them of the mistake and exits gracefully. Because of this, you can make reasonable assumptions in your code, and worry less about error handling.</p>
<h2 id="features" class='section-header'><a
href="#features">Features</a></h2>
@ -79,7 +69,7 @@
<li><strong>Auto-generated Help, Version, and Usage information</strong>
<ul>
<li>Can optionally be fully, or partially overridden if you want a custom help, version, or usage</li>
<li>Can optionally be fully, or partially overridden if you want a custom help, version, or usag</li>
</ul></li>
<li><strong>Flags / Switches</strong> (i.e. bool fields)
@ -93,18 +83,19 @@
<ul>
<li>Optionally supports multiple values (i.e. <code>myprog &lt;file&gt;...</code> such as <code>myprog file1.txt file2.txt</code> being two values for the same &quot;file&quot; argument)</li>
<li>Optionally supports Specific Value Sets (See below)</li>
<li>Supports the unix <code>--</code> meaning, only positional arguments follow</li>
</ul></li>
<li><strong>Option Arguments</strong> (i.e. those that take values as options)
<ul>
<li>Both short and long versions supported (i.e. <code>-o value</code> and <code>--option value</code> or <code>--option=value</code> respectively)</li>
<li>Optionally supports multiple values (i.e. <code>myprog --option &lt;value&gt; --option &lt;other_value&gt;</code>)</li>
<li>Optionally supports multiple values (i.e. <code>myprog -o &lt;value&gt; -o &lt;other_value&gt;</code>)</li>
<li>Optionally supports Specific Value Sets (See below)</li>
</ul></li>
<li><strong>Sub-Commands</strong> (i.e. <code>git add &lt;file&gt;</code> where <code>add</code> is a sub-command of <code>git</code>)
<ul>
<li>Support their own sub-arguments, and sub-commands independant of the parent</li>
<li>Support their own sub-arguments, and sub-sub-commands independant of the parent</li>
<li>Get their own auto-generated Help, Version, and Usage independant of parent</li>
</ul></li>
<li><strong>Requirement Rules</strong>: Arguments can optionally define the following types of requirement rules
@ -121,16 +112,18 @@
<li>Can disallow use of other arguments when present</li>
</ul></li>
<li><strong>Specific Value Sets</strong>: Positional or Option Arguments can optionally define a specific set of allowed values (i.e. imagine a <code>--mode</code> option which may <em>only</em> have one of two values <code>fast</code> or <code>slow</code> such as <code>--mode fast</code> or <code>--mode slow</code>)</li>
<li><strong>Default Values</strong>: Although not specifically provided by <code>clap</code> you can achieve this exact functionality from Rust&#39;s <code>Option&lt;&amp;str&gt;.unwrap_or(&quot;some default&quot;)</code> method</li>
<li><strong>Get Version from Cargo.toml</strong>: <code>clap</code> is fully compatible with Rust&#39;s <code>env!()</code> macro for automatically getting the version from your Cargo.toml. See <code>examples/09_AutoVersion.rs</code> for how to do this (Thanks to <a href="https://github.com/jhelwig">jhelwig</a> for pointing this out)</li>
<li><strong>Typed Values</strong>: You can use several convenience macros provided by <code>clap</code> to get typed values (i.e. <code>i32</code>, <code>u8</code>, etc.) so long as the type you request implements <code>std::fmt::FrmStr</code> See the <code>examples/12_TypedValues.rs</code> or the documentation for more information.</li>
<li><strong>Default Values</strong>: Although not specifically provided by <code>clap</code> you can achieve this exact functionality from Rust&#39;s <code>Option&lt;&amp;str&gt;.unwrap_or(&quot;some default&quot;)</code> method (or <code>Result&lt;T,String&gt;.unwrap_or(T)</code> when using typed values)</li>
<li><strong>Automatic Version from Cargo.toml</strong>: <code>clap</code> is fully compatible with Rust&#39;s <code>env!()</code> macro for automatically setting the version of your application to the version in your Cargo.toml. See <code>examples/09_AutoVersion.rs</code> for how to do this (Thanks to <a href="https://github.com/jhelwig">jhelwig</a> for pointing this out)</li>
<li><strong>Typed Values</strong>: You can use several convenience macros provided by <code>clap</code> to get typed values (i.e. <code>i32</code>, <code>u8</code>, etc.) from positional or option arguments so long as the type you request implements <code>std::str::FromStr</code> See the <code>examples/12_TypedValues.rs</code> or the <a href="http://kbknapp.github.io/clap-rs/docs/clap/index.html">documentation</a> for more information.</li>
</ul>
<h2 id="quick-example" class='section-header'><a
href="#quick-example">Quick Example</a></h2>
<p>The following two examples (which are functionally equivilant, but show two different ways to use <code>clap</code>) show a quick example of some of the basic functionality of <code>clap</code>. For more advanced usage, such as requirements, exclusions, multiple values and occurrences see the <a href="https://www.youtube.com/playlist?list=PLza5oFLQGTl0Bc_EU_pBNcX-rhVqDTRxv">video tutorials</a>, <a href="http://kbknapp.github.io/clap-rs/docs/clap/index.html">documentation</a>, or <code>examples/</code> directory of this repository.</p>
<p>The following two examples show a quick example of some of the very basic functionality of <code>clap</code>. For more advanced usage, such as requirements, exclusions, multiple values and occurrences see the <a href="https://www.youtube.com/playlist?list=PLza5oFLQGTl0Bc_EU_pBNcX-rhVqDTRxv">video tutorials</a>, <a href="http://kbknapp.github.io/clap-rs/docs/clap/index.html">documentation</a>, or <code>examples/</code> directory of this repository.</p>
<p><em>NOTE:</em> Both examples are functionally the same, but show two different ways to use <code>clap</code></p>
<pre id='rust-example-rendered' class='rust '>
<span class='comment'>// (Full example with comments in examples/01_QuickExample.rs)</span>
<span class='comment'>// (Full example with detailed comments in examples/01a_QuickExample.rs)</span>
<span class='kw'>extern</span> <span class='kw'>crate</span> <span class='ident'>clap</span>;
<span class='kw'>use</span> <span class='ident'>clap</span>::{<span class='ident'>Arg</span>, <span class='ident'>App</span>, <span class='ident'>SubCommand</span>};
@ -167,6 +160,8 @@
<span class='number'>3</span> <span class='op'>|</span> _ <span class='op'>=&gt;</span> <span class='macro'>println</span><span class='macro'>!</span>(<span class='string'>&quot;Don&#39;t be crazy&quot;</span>),
}
<span class='comment'>// You can information about subcommands by requesting their matches by name </span>
<span class='comment'>// (as below), requesting just the name used, or both at the same time</span>
<span class='kw'>if</span> <span class='kw'>let</span> <span class='prelude-val'>Some</span>(<span class='ident'>matches</span>) <span class='op'>=</span> <span class='ident'>matches</span>.<span class='ident'>subcommand_matches</span>(<span class='string'>&quot;test&quot;</span>) {
<span class='kw'>if</span> <span class='ident'>matches</span>.<span class='ident'>is_present</span>(<span class='string'>&quot;verbose&quot;</span>) {
<span class='macro'>println</span><span class='macro'>!</span>(<span class='string'>&quot;Printing verbosely...&quot;</span>);
@ -179,9 +174,9 @@
}
</pre>
<p>While the following example is functionally the same as the one above, this method allows more advanced configuration options, or even dynamically generating arguments when desired. Both methods can be used together to get the best of both worlds (see the documentation).</p>
<p>The following example is functionally the same as the one above, but this method allows more advanced configuration options (not shown in this small example), or even dynamically generating arguments when desired. Both methods can be used together to get the best of both worlds (see the documentation, examples, or video tutorials).</p>
<pre id='rust-example-rendered' class='rust '>
<span class='comment'>// (Full example with comments in examples/01_QuickExample.rs)</span>
<span class='comment'>// (Full example with detailed comments in examples/01b_QuickExample.rs)</span>
<span class='kw'>extern</span> <span class='kw'>crate</span> <span class='ident'>clap</span>;
<span class='kw'>use</span> <span class='ident'>clap</span>::{<span class='ident'>Arg</span>, <span class='ident'>App</span>, <span class='ident'>SubCommand</span>};
@ -228,7 +223,9 @@
<span class='number'>2</span> <span class='op'>=&gt;</span> <span class='macro'>println</span><span class='macro'>!</span>(<span class='string'>&quot;Debug mode is on&quot;</span>),
<span class='number'>3</span> <span class='op'>|</span> _ <span class='op'>=&gt;</span> <span class='macro'>println</span><span class='macro'>!</span>(<span class='string'>&quot;Don&#39;t be crazy&quot;</span>),
}
<span class='comment'>// You can information about subcommands by requesting their matches by name </span>
<span class='comment'>// (as below), requesting just the name used, or both at the same time</span>
<span class='kw'>if</span> <span class='kw'>let</span> <span class='prelude-val'>Some</span>(<span class='ident'>matches</span>) <span class='op'>=</span> <span class='ident'>matches</span>.<span class='ident'>subcommand_matches</span>(<span class='string'>&quot;test&quot;</span>) {
<span class='kw'>if</span> <span class='ident'>matches</span>.<span class='ident'>is_present</span>(<span class='string'>&quot;verbose&quot;</span>) {
<span class='macro'>println</span><span class='macro'>!</span>(<span class='string'>&quot;Printing verbosely...&quot;</span>);
@ -295,6 +292,14 @@ SUBCOMMANDS:
<p>You can also find usage examples in the <code>examples/</code> directory of this repo.</p>
<h4 id="video-tutorials" class='section-header'><a
href="#video-tutorials">Video Tutorials</a></h4>
<p>There&#39;s also the video tutorial series <a href="https://www.youtube.com/playlist?list=PLza5oFLQGTl0Bc_EU_pBNcX-rhVqDTRxv">Argument Parsing with Rust</a> that I&#39;ve been working on.</p>
<p><em>Note</em>: Two new videos have just been added (<a href="https://youtu.be/xc6VdedFrG0">08 From Usage</a>, and <a href="https://youtu.be/mZn3C1DnD90">09 Typed Values</a>), if you&#39;re already familiar with <code>clap</code> but want to know more about these two details you can check out those videos without watching the previous few.</p>
<p><em>Note</em>: Apologies for the resolution of the first video, it will be updated to a better resolution soon. The other videos have a proper resolution.</p>
<h2 id="how-to-contribute" class='section-header'><a
href="#how-to-contribute">How to Contribute</a></h2>
<p>Contributions are always welcome! And there is a multitude of ways in which you can help depending on what you like to do, or are good at. Anything from documentation, code cleanup, issue completion, new features, you name it, even filing issues is contributing and greatly appreciated!</p>
@ -361,7 +366,7 @@ SUBCOMMANDS:
<tr>
<td><a class='stability Unmarked' title='No stability level'></a><a class='macro' href='macro.value_t!.html'
title='clap::value_t!'>value_t!</a></td>
<td class='docblock short'><p>Convenience macro getting a typed value <code>T</code> where <code>T</code> implements <code>std::fmt::FrmStr</code>
<td class='docblock short'><p>Convenience macro getting a typed value <code>T</code> where <code>T</code> implements <code>std::str::FromStr</code>
This macro returns a <code>Result&lt;T,String&gt;</code> which allows you as the developer to decide
what you&#39;d like to do on a failed parse. There are two types of errors, parse failures
and those where the argument wasn&#39;t present (such as a non-required argument). </p>
@ -371,7 +376,7 @@ SUBCOMMANDS:
<tr>
<td><a class='stability Unmarked' title='No stability level'></a><a class='macro' href='macro.value_t_or_exit!.html'
title='clap::value_t_or_exit!'>value_t_or_exit!</a></td>
<td class='docblock short'><p>Convenience macro getting a typed value <code>T</code> where <code>T</code> implements <code>std::fmt::FrmStr</code>
<td class='docblock short'><p>Convenience macro getting a typed value <code>T</code> where <code>T</code> implements <code>std::str::FromStr</code>
This macro returns a <code>T</code> or <code>Vec&lt;T&gt;</code> or exits with a usage string upon failure. This
removes some of the boiler plate to handle failures from value_t! above. </p>
</td>

4
docs/clap/macro.value_t!.html
View file

@ -43,7 +43,7 @@
<section id='main' class="content macro">
<h1 class='fqn'><span class='in-band'><a href='index.html'>clap</a>::<wbr><a class='macro' href=''>value_t!</a><wbr></span><span class='out-of-band'><span id='render-detail'>
<a id="collapse-all" href="#">[-]</a>&nbsp;<a id="expand-all" href="#">[+]</a>
</span><a id='src-10458' href='../src/clap/macros.rs.html#84-118'>[src]</a></span></h1>
</span><a id='src-10428' href='../src/clap/macros.rs.html#84-118'>[src]</a></span></h1>
<pre class='rust macro'>
<span class='macro'>macro_rules</span><span class='macro'>!</span> <span class='ident'>value_t</span> {
(<span class='macro-nonterminal'>$</span><span class='macro-nonterminal'>m</span>:<span class='ident'>ident</span>.<span class='ident'>value_of</span>(<span class='macro-nonterminal'>$</span><span class='macro-nonterminal'>v</span>:<span class='ident'>expr</span>), <span class='macro-nonterminal'>$</span><span class='macro-nonterminal'>t</span>:<span class='ident'>ty</span>) <span class='op'>=&gt;</span> {
@ -81,7 +81,7 @@
};
}
</pre>
<div class='docblock'><p>Convenience macro getting a typed value <code>T</code> where <code>T</code> implements <code>std::fmt::FrmStr</code>
<div class='docblock'><p>Convenience macro getting a typed value <code>T</code> where <code>T</code> implements <code>std::str::FromStr</code>
This macro returns a <code>Result&lt;T,String&gt;</code> which allows you as the developer to decide
what you&#39;d like to do on a failed parse. There are two types of errors, parse failures
and those where the argument wasn&#39;t present (such as a non-required argument). </p>

4
docs/clap/macro.value_t_or_exit!.html
View file

@ -43,7 +43,7 @@
<section id='main' class="content macro">
<h1 class='fqn'><span class='in-band'><a href='index.html'>clap</a>::<wbr><a class='macro' href=''>value_t_or_exit!</a><wbr></span><span class='out-of-band'><span id='render-detail'>
<a id="collapse-all" href="#">[-]</a>&nbsp;<a id="expand-all" href="#">[+]</a>
</span><a id='src-10459' href='../src/clap/macros.rs.html#166-215'>[src]</a></span></h1>
</span><a id='src-10429' href='../src/clap/macros.rs.html#166-215'>[src]</a></span></h1>
<pre class='rust macro'>
<span class='macro'>macro_rules</span><span class='macro'>!</span> <span class='ident'>value_t_or_exit</span> {
(<span class='macro-nonterminal'>$</span><span class='macro-nonterminal'>m</span>:<span class='ident'>ident</span>.<span class='ident'>value_of</span>(<span class='macro-nonterminal'>$</span><span class='macro-nonterminal'>v</span>:<span class='ident'>expr</span>), <span class='macro-nonterminal'>$</span><span class='macro-nonterminal'>t</span>:<span class='ident'>ty</span>) <span class='op'>=&gt;</span> {
@ -96,7 +96,7 @@
};
}
</pre>
<div class='docblock'><p>Convenience macro getting a typed value <code>T</code> where <code>T</code> implements <code>std::fmt::FrmStr</code>
<div class='docblock'><p>Convenience macro getting a typed value <code>T</code> where <code>T</code> implements <code>std::str::FromStr</code>
This macro returns a <code>T</code> or <code>Vec&lt;T&gt;</code> or exits with a usage string upon failure. This
removes some of the boiler plate to handle failures from value_t! above. </p>

2
docs/clap/sidebar-items.js
View file

@ -1 +1 @@
initSidebarItems({"macro":[["value_t!","Convenience macro getting a typed value `T` where `T` implements `std::fmt::FrmStr` This macro returns a `Result<T,String>` which allows you as the developer to decide what you'd like to do on a failed parse. There are two types of errors, parse failures and those where the argument wasn't present (such as a non-required argument). "],["value_t_or_exit!","Convenience macro getting a typed value `T` where `T` implements `std::fmt::FrmStr` This macro returns a `T` or `Vec<T>` or exits with a usage string upon failure. This removes some of the boiler plate to handle failures from value_t! above. "]],"struct":[["App","Used to create a representation of a command line program and all possible command line arguments for parsing at runtime."],["Arg","The abstract representation of a command line argument used by the consumer of the library. Used to set all the options and relationships that define a valid argument for the program."],["ArgMatches","Used to get information about the arguments that where supplied to the program at runtime by the user. To get a new instance of this struct you use `.get_matches()` of the `App` struct."],["SubCommand","The abstract representation of a command line subcommand used by the consumer of the library."]]});
initSidebarItems({"macro":[["value_t!","Convenience macro getting a typed value `T` where `T` implements `std::str::FromStr` This macro returns a `Result<T,String>` which allows you as the developer to decide what you'd like to do on a failed parse. There are two types of errors, parse failures and those where the argument wasn't present (such as a non-required argument). "],["value_t_or_exit!","Convenience macro getting a typed value `T` where `T` implements `std::str::FromStr` This macro returns a `T` or `Vec<T>` or exits with a usage string upon failure. This removes some of the boiler plate to handle failures from value_t! above. "]],"struct":[["App","Used to create a representation of a command line program and all possible command line arguments for parsing at runtime."],["Arg","The abstract representation of a command line argument used by the consumer of the library. Used to set all the options and relationships that define a valid argument for the program."],["ArgMatches","Used to get information about the arguments that where supplied to the program at runtime by the user. To get a new instance of this struct you use `.get_matches()` of the `App` struct."],["SubCommand","The abstract representation of a command line subcommand used by the consumer of the library."]]});

2
docs/clap/struct.Arg.html
View file

@ -43,7 +43,7 @@
<section id='main' class="content struct">
<h1 class='fqn'><span class='in-band'>Struct <a href='index.html'>clap</a>::<wbr><a class='struct' href=''>Arg</a><wbr></span><span class='out-of-band'><span id='render-detail'>
<a id="collapse-all" href="#">[-]</a>&nbsp;<a id="expand-all" href="#">[+]</a>
</span><a id='src-8421' href='../src/clap/args/arg.rs.html#31-76'>[src]</a></span></h1>
</span><a id='src-8395' href='../src/clap/args/arg.rs.html#31-76'>[src]</a></span></h1>
<pre class='rust struct'>pub struct Arg&lt;'n, 'l, 'h, 'b, 'p, 'r&gt; {
// some fields omitted
}</pre><div class='docblock'><p>The abstract representation of a command line argument used by the consumer of the library.

2
docs/clap/struct.ArgMatches.html
View file

@ -43,7 +43,7 @@
<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=''>ArgMatches</a><wbr></span><span class='out-of-band'><span id='render-detail'>
<a id="collapse-all" href="#">[-]</a>&nbsp;<a id="expand-all" href="#">[+]</a>
</span><a id='src-9281' href='../src/clap/args/argmatches.rs.html#57-68'>[src]</a></span></h1>
</span><a id='src-9253' href='../src/clap/args/argmatches.rs.html#57-68'>[src]</a></span></h1>
<pre class='rust struct'>pub struct ArgMatches&lt;'a&gt; {
// some fields omitted
}</pre><div class='docblock'><p>Used to get information about the arguments that where supplied to the program at runtime by

2
docs/clap/struct.SubCommand.html
View file

@ -43,7 +43,7 @@
<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=''>SubCommand</a><wbr></span><span class='out-of-band'><span id='render-detail'>
<a id="collapse-all" href="#">[-]</a>&nbsp;<a id="expand-all" href="#">[+]</a>
</span><a id='src-9772' href='../src/clap/args/subcommand.rs.html#23-26'>[src]</a></span></h1>
</span><a id='src-9744' href='../src/clap/args/subcommand.rs.html#23-26'>[src]</a></span></h1>
<pre class='rust struct'>pub struct SubCommand&lt;'a&gt; {
pub name: <a class='struct' href='http://doc.rust-lang.org/nightly/collections/string/struct.String.html' title='collections::string::String'>String</a>,
pub matches: <a class='struct' href='../clap/struct.ArgMatches.html' title='clap::ArgMatches'>ArgMatches</a>&lt;'a&gt;,

8
docs/main.js
View file

@ -78,9 +78,11 @@
return;
}
if (e.which === 191 && $('#help').hasClass('hidden')) { // question mark
e.preventDefault();
$('#help').removeClass('hidden');
if (e.which === 191) { // question mark
if (e.shiftKey && $('#help').hasClass('hidden')) {
e.preventDefault();
$('#help').removeClass('hidden');
}
} else if (e.which === 27) { // esc
if (!$('#help').hasClass('hidden')) {
e.preventDefault();

2
docs/search-index.js
View file

File diff suppressed because one or more lines are too long

60
docs/src/clap/lib.rs.html
View file

@ -942,6 +942,11 @@
<span id="900">900</span>
<span id="901">901</span>
<span id="902">902</span>
<span id="903">903</span>
<span id="904">904</span>
<span id="905">905</span>
<span id="906">906</span>
<span id="907">907</span>
</pre><pre class='rust '>
<span class='attribute'>#<span class='op'>!</span>[<span class='ident'>crate_type</span><span class='op'>=</span> <span class='string'>&quot;lib&quot;</span>]</span>
@ -950,34 +955,24 @@
<span class='doccomment'>//! </span>
<span class='doccomment'>//! ![Travis-CI](https://travis-ci.org/kbknapp/clap-rs.svg?branch=master) [![Join the chat at https://gitter.im/kbknapp/clap-rs](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/kbknapp/clap-rs?utm_source=badge&amp;utm_medium=badge&amp;utm_campaign=pr-badge&amp;utm_content=badge)</span>
<span class='doccomment'>//! </span>
<span class='doccomment'>//! Command Line Argument Parser written in Rust</span>
<span class='doccomment'>//! Command Line Argument Parser for Rust</span>
<span class='doccomment'>//! </span>
<span class='doccomment'>//! It is a simple to use and efficient library for parsing command line arguments and subcommands when writing console, or terminal applications.</span>
<span class='doccomment'>//! </span>
<span class='doccomment'>//! ## Video Tutorials</span>
<span class='doccomment'>//! </span>
<span class='doccomment'>//! I&#39;ve been working on a few short video tutorials about using `clap`. They&#39;re located on [youtube](https://www.youtube.com/playlist?list=PLza5oFLQGTl0Bc_EU_pBNcX-rhVqDTRxv). </span>
<span class='doccomment'>//! </span>
<span class='doccomment'>//! *Note*: The videos have not been updated to include the new `from_usage()` methods which make building args significantly less verbose. New videos will be added soon.</span>
<span class='doccomment'>//! </span>
<span class='doccomment'>//! *Note*: Apologies for the resolution of the first video, it will be updated to a better resolution soon. The other videos have a proper resolution.</span>
<span class='doccomment'>//! </span>
<span class='doccomment'>//! ## About</span>
<span class='doccomment'>//! </span>
<span class='doccomment'>//! You can use `clap` to lay out a list of possible valid command line arguments and subcommands, then let `clap` parse *and validate* the string given by the user at runtime. This means you focus on your applications functionality, not parsing and validating arguments.</span>
<span class='doccomment'>//! `clap` is used to parse *and validate* the string of command line arguments provided by the user at runtime. You simply provide the list of valid possibilities, and `clap` handles the rest. This means you focus on your *applications* functionality, and less on the parsing and validating of arguments.</span>
<span class='doccomment'>//! </span>
<span class='doccomment'>//! What is different about `clap` from other options available is the very simple almost &#39;Pythonic&#39; style in which you define the valid available arguments for your program, while still giving advanced features. `clap` allows you express complex relationships between arguments in a very simple manner. This means you don&#39;t have to spend tons time learning an entirely new library&#39;s structures and use. The basics of `clap` can be learned almost intuitively.</span>
<span class='doccomment'>//! `clap` also provides all the traditional version and help switches (or flags) &#39;for free.&#39; It does this by checking list of valid possibilities you supplied and if you haven&#39;t defined those flags already (or only defined some of them), `clap` will auto-generate the applicable ones (as well as a &quot;help&quot; subcommand so long as other subcommands have been manually defined as well).</span>
<span class='doccomment'>//! </span>
<span class='doccomment'>//! `clap` also provides all the traditional version and help switches (or flags) &#39;for free&#39; by parsing the list of developer supplied arguments. If the developer hasn&#39;t defined them already (or only defined some of them), `clap` will auto-generate the applicable &quot;help&quot; and &quot;version&quot; switches (as well as a &quot;help&quot; subcommand so long as other subcommands have been manually defined as well).</span>
<span class='doccomment'>//! </span>
<span class='doccomment'>//! After defining a list of possible valid arguments and subcommands, `clap` parses the string given by the end-user at runtime then gives you a list of the valid matches and their values. If the user made an error or typo, `clap` informs them and exits gracefully. This means that you can simply use these matches and values to determine the functioning of your program.</span>
<span class='doccomment'>//! After `clap` finishes parsing the user provided string, it returns all the matches along with any applicable values. If the user made an error or typo, `clap` informs them of the mistake and exits gracefully. Because of this, you can make reasonable assumptions in your code, and worry less about error handling.</span>
<span class='doccomment'>//! </span>
<span class='doccomment'>//! ## Features</span>
<span class='doccomment'>//! </span>
<span class='doccomment'>//! Below are a few of the features which `clap` supports, full descriptions and usage can be found in the [documentation](http://kbknapp.github.io/clap-rs/docs/clap/index.html) and `examples/` directory</span>
<span class='doccomment'>//! </span>
<span class='doccomment'>//! * **Auto-generated Help, Version, and Usage information**</span>
<span class='doccomment'>//! - Can optionally be fully, or partially overridden if you want a custom help, version, or usage</span>
<span class='doccomment'>//! - Can optionally be fully, or partially overridden if you want a custom help, version, or usag</span>
<span class='doccomment'>//! * **Flags / Switches** (i.e. bool fields)</span>
<span class='doccomment'>//! - Both short and long versions supported (i.e. `-f` and `--flag` respectively)</span>
<span class='doccomment'>//! - Supports combining short versions (i.e. `-fBgoZ` is the same as `-f -B -g -o -Z`)</span>
@ -985,12 +980,13 @@
<span class='doccomment'>//! * **Positional Arguments** (i.e. those which are based off an index from the program name)</span>
<span class='doccomment'>//! - Optionally supports multiple values (i.e. `myprog &lt;file&gt;...` such as `myprog file1.txt file2.txt` being two values for the same &quot;file&quot; argument)</span>
<span class='doccomment'>//! - Optionally supports Specific Value Sets (See below)</span>
<span class='doccomment'>//! - Supports the unix `--` meaning, only positional arguments follow</span>
<span class='doccomment'>//! * **Option Arguments** (i.e. those that take values as options)</span>
<span class='doccomment'>//! - Both short and long versions supported (i.e. `-o value` and `--option value` or `--option=value` respectively)</span>
<span class='doccomment'>//! - Optionally supports multiple values (i.e. `myprog --option &lt;value&gt; --option &lt;other_value&gt;`)</span>
<span class='doccomment'>//! - Optionally supports multiple values (i.e. `myprog -o &lt;value&gt; -o &lt;other_value&gt;`)</span>
<span class='doccomment'>//! - Optionally supports Specific Value Sets (See below)</span>
<span class='doccomment'>//! * **Sub-Commands** (i.e. `git add &lt;file&gt;` where `add` is a sub-command of `git`)</span>
<span class='doccomment'>//! - Support their own sub-arguments, and sub-commands independant of the parent</span>
<span class='doccomment'>//! - Support their own sub-arguments, and sub-sub-commands independant of the parent</span>
<span class='doccomment'>//! - Get their own auto-generated Help, Version, and Usage independant of parent</span>
<span class='doccomment'>//! * **Requirement Rules**: Arguments can optionally define the following types of requirement rules</span>
<span class='doccomment'>//! - Required by default</span>
@ -1000,16 +996,18 @@
<span class='doccomment'>//! - Can be disallowed when certain arguments are present</span>
<span class='doccomment'>//! - Can disallow use of other arguments when present</span>
<span class='doccomment'>//! * **Specific Value Sets**: Positional or Option Arguments can optionally define a specific set of allowed values (i.e. imagine a `--mode` option which may *only* have one of two values `fast` or `slow` such as `--mode fast` or `--mode slow`)</span>
<span class='doccomment'>//! * **Default Values**: Although not specifically provided by `clap` you can achieve this exact functionality from Rust&#39;s `Option&lt;&amp;str&gt;.unwrap_or(&quot;some default&quot;)` method</span>
<span class='doccomment'>//! * **Get Version from Cargo.toml**: `clap` is fully compatible with Rust&#39;s `env!()` macro for automatically getting the version from your Cargo.toml. See `examples/09_AutoVersion.rs` for how to do this (Thanks to [jhelwig](https://github.com/jhelwig) for pointing this out)</span>
<span class='doccomment'>//! * **Typed Values**: You can use several convenience macros provided by `clap` to get typed values (i.e. `i32`, `u8`, etc.) so long as the type you request implements `std::fmt::FrmStr` See the `examples/12_TypedValues.rs` or the documentation for more information.</span>
<span class='doccomment'>//! * **Default Values**: Although not specifically provided by `clap` you can achieve this exact functionality from Rust&#39;s `Option&lt;&amp;str&gt;.unwrap_or(&quot;some default&quot;)` method (or `Result&lt;T,String&gt;.unwrap_or(T)` when using typed values)</span>
<span class='doccomment'>//! * **Automatic Version from Cargo.toml**: `clap` is fully compatible with Rust&#39;s `env!()` macro for automatically setting the version of your application to the version in your Cargo.toml. See `examples/09_AutoVersion.rs` for how to do this (Thanks to [jhelwig](https://github.com/jhelwig) for pointing this out)</span>
<span class='doccomment'>//! * **Typed Values**: You can use several convenience macros provided by `clap` to get typed values (i.e. `i32`, `u8`, etc.) from positional or option arguments so long as the type you request implements `std::str::FromStr` See the `examples/12_TypedValues.rs` or the [documentation](http://kbknapp.github.io/clap-rs/docs/clap/index.html) for more information.</span>
<span class='doccomment'>//! </span>
<span class='doccomment'>//! ## Quick Example</span>
<span class='doccomment'>//! </span>
<span class='doccomment'>//! The following two examples (which are functionally equivilant, but show two different ways to use `clap`) show a quick example of some of the basic functionality of `clap`. For more advanced usage, such as requirements, exclusions, multiple values and occurrences see the [video tutorials](https://www.youtube.com/playlist?list=PLza5oFLQGTl0Bc_EU_pBNcX-rhVqDTRxv), [documentation](http://kbknapp.github.io/clap-rs/docs/clap/index.html), or `examples/` directory of this repository.</span>
<span class='doccomment'>//! The following two examples show a quick example of some of the very basic functionality of `clap`. For more advanced usage, such as requirements, exclusions, multiple values and occurrences see the [video tutorials](https://www.youtube.com/playlist?list=PLza5oFLQGTl0Bc_EU_pBNcX-rhVqDTRxv), [documentation](http://kbknapp.github.io/clap-rs/docs/clap/index.html), or `examples/` directory of this repository.</span>
<span class='doccomment'>//! </span>
<span class='doccomment'>//! *NOTE:* Both examples are functionally the same, but show two different ways to use `clap`</span>
<span class='doccomment'>//! </span>
<span class='doccomment'>//! ```rust</span>
<span class='doccomment'>//! // (Full example with comments in examples/01_QuickExample.rs)</span>
<span class='doccomment'>//! // (Full example with detailed comments in examples/01a_QuickExample.rs)</span>
<span class='doccomment'>//! extern crate clap;</span>
<span class='doccomment'>//! use clap::{Arg, App, SubCommand};</span>
<span class='doccomment'>//! </span>
@ -1046,6 +1044,8 @@
<span class='doccomment'>//! 3 | _ =&gt; println!(&quot;Don&#39;t be crazy&quot;),</span>
<span class='doccomment'>//! }</span>
<span class='doccomment'>//! </span>
<span class='doccomment'>//! // You can information about subcommands by requesting their matches by name </span>
<span class='doccomment'>//! // (as below), requesting just the name used, or both at the same time</span>
<span class='doccomment'>//! if let Some(matches) = matches.subcommand_matches(&quot;test&quot;) {</span>
<span class='doccomment'>//! if matches.is_present(&quot;verbose&quot;) {</span>
<span class='doccomment'>//! println!(&quot;Printing verbosely...&quot;);</span>
@ -1058,10 +1058,10 @@
<span class='doccomment'>//! }</span>
<span class='doccomment'>//! ```</span>
<span class='doccomment'>//! </span>
<span class='doccomment'>//! While the following example is functionally the same as the one above, this method allows more advanced configuration options, or even dynamically generating arguments when desired. Both methods can be used together to get the best of both worlds (see the documentation).</span>
<span class='doccomment'>//! The following example is functionally the same as the one above, but this method allows more advanced configuration options (not shown in this small example), or even dynamically generating arguments when desired. Both methods can be used together to get the best of both worlds (see the documentation, examples, or video tutorials).</span>
<span class='doccomment'>//! </span>
<span class='doccomment'>//! ```rust</span>
<span class='doccomment'>//! // (Full example with comments in examples/01_QuickExample.rs)</span>
<span class='doccomment'>//! // (Full example with detailed comments in examples/01b_QuickExample.rs)</span>
<span class='doccomment'>//! extern crate clap;</span>
<span class='doccomment'>//! use clap::{Arg, App, SubCommand};</span>
<span class='doccomment'>//! </span>
@ -1108,7 +1108,9 @@
<span class='doccomment'>//! 2 =&gt; println!(&quot;Debug mode is on&quot;),</span>
<span class='doccomment'>//! 3 | _ =&gt; println!(&quot;Don&#39;t be crazy&quot;),</span>
<span class='doccomment'>//! }</span>
<span class='doccomment'>//! </span>
<span class='doccomment'>//! </span>
<span class='doccomment'>//! // You can information about subcommands by requesting their matches by name </span>
<span class='doccomment'>//! // (as below), requesting just the name used, or both at the same time</span>
<span class='doccomment'>//! if let Some(matches) = matches.subcommand_matches(&quot;test&quot;) {</span>
<span class='doccomment'>//! if matches.is_present(&quot;verbose&quot;) {</span>
<span class='doccomment'>//! println!(&quot;Printing verbosely...&quot;);</span>
@ -1177,6 +1179,14 @@
<span class='doccomment'>//! </span>
<span class='doccomment'>//! You can also find usage examples in the `examples/` directory of this repo.</span>
<span class='doccomment'>//! </span>
<span class='doccomment'>//! #### Video Tutorials</span>
<span class='doccomment'>//! </span>
<span class='doccomment'>//! There&#39;s also the video tutorial series [Argument Parsing with Rust](https://www.youtube.com/playlist?list=PLza5oFLQGTl0Bc_EU_pBNcX-rhVqDTRxv) that I&#39;ve been working on.</span>
<span class='doccomment'>//! </span>
<span class='doccomment'>//! *Note*: Two new videos have just been added ([08 From Usage](https://youtu.be/xc6VdedFrG0), and [09 Typed Values](https://youtu.be/mZn3C1DnD90)), if you&#39;re already familiar with `clap` but want to know more about these two details you can check out those videos without watching the previous few.</span>
<span class='doccomment'>//! </span>
<span class='doccomment'>//! *Note*: Apologies for the resolution of the first video, it will be updated to a better resolution soon. The other videos have a proper resolution.</span>
<span class='doccomment'>//! </span>
<span class='doccomment'>//! ## How to Contribute</span>
<span class='doccomment'>//! </span>
<span class='doccomment'>//! Contributions are always welcome! And there is a multitude of ways in which you can help depending on what you like to do, or are good at. Anything from documentation, code cleanup, issue completion, new features, you name it, even filing issues is contributing and greatly appreciated!</span>

4
docs/src/clap/macros.rs.html
View file

@ -287,7 +287,7 @@
};
}
<span class='doccomment'>/// Convenience macro getting a typed value `T` where `T` implements `std::fmt::FrmStr`</span>
<span class='doccomment'>/// Convenience macro getting a typed value `T` where `T` implements `std::str::FromStr`</span>
<span class='doccomment'>/// This macro returns a `Result&lt;T,String&gt;` which allows you as the developer to decide</span>
<span class='doccomment'>/// what you&#39;d like to do on a failed parse. There are two types of errors, parse failures</span>
<span class='doccomment'>/// and those where the argument wasn&#39;t present (such as a non-required argument). </span>
@ -375,7 +375,7 @@
};
}
<span class='doccomment'>/// Convenience macro getting a typed value `T` where `T` implements `std::fmt::FrmStr`</span>
<span class='doccomment'>/// Convenience macro getting a typed value `T` where `T` implements `std::str::FromStr`</span>
<span class='doccomment'>/// This macro returns a `T` or `Vec&lt;T&gt;` or exits with a usage string upon failure. This</span>
<span class='doccomment'>/// removes some of the boiler plate to handle failures from value_t! above. </span>
<span class='doccomment'>///</span>