pub struct App<'a, 'b>where
'a: 'b,{ /* private fields */ }
Expand description
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
App::get_matches
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).
NOTE: There aren’t any mandatory “options” that one must set. The “options” may
also appear in any order (so long as one of the App::get_matches
methods is the last method
called).
§Examples
let m = App::new("My Program")
.author("Me, me@mail.com")
.version("1.0.2")
.about("Explains in brief what the program does")
.arg(
Arg::with_name("in_file").index(1)
)
.after_help("Longer explanation to appear after the options when \
displaying the help information from --help or -h")
.get_matches();
// Your program logic starts here...
Implementations§
Source§impl<'a, 'b> App<'a, 'b>
impl<'a, 'b> App<'a, 'b>
Sourcepub fn new<S: Into<String>>(n: S) -> Self
pub fn new<S: Into<String>>(n: S) -> Self
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.
§Examples
let prog = App::new("My Program")
Sourcepub fn get_bin_name(&self) -> Option<&str>
pub fn get_bin_name(&self) -> Option<&str>
Get the name of the binary
Sourcepub fn with_defaults<S: Into<String>>(n: S) -> Self
👎Deprecated since 2.14.1: Can never work; use explicit App::author() and App::version() calls instead
pub fn with_defaults<S: Into<String>>(n: S) -> Self
Creates a new instance of an application requiring a name, but uses the crate_authors!
and crate_version!
macros to fill in the App::author
and App::version
fields.
§Examples
let prog = App::with_defaults("My Program")
Sets a string of author(s) that will be displayed to the user when they
request the help information with --help
or -h
.
Pro-tip: Use clap
s convenience macro crate_authors!
to automatically set your
application’s author(s) to the same thing as your crate at compile time. See the examples/
directory for more information
See the examples/
directory for more information
§Examples
App::new("myprog")
.author("Me, me@mymain.com")
Sourcepub fn bin_name<S: Into<String>>(self, name: S) -> Self
pub fn bin_name<S: Into<String>>(self, name: S) -> Self
Overrides the system-determined binary name. This should only be used when absolutely necessary, such as when the binary name for your application is misleading, or perhaps not how the user should invoke your program.
Pro-tip: When building things such as third party cargo
subcommands, this setting
should be used!
NOTE: This command should not be used for SubCommand
s.
§Examples
App::new("My Program")
.bin_name("my_binary")
Sourcepub fn about<S: Into<&'b str>>(self, about: S) -> Self
pub fn about<S: Into<&'b str>>(self, about: S) -> Self
Sets a string describing what the program does. This will be displayed when displaying help
information with -h
.
NOTE: If only about
is provided, and not App::long_about
but the user requests
--help
clap will still display the contents of about
appropriately
NOTE: Only App::about
is used in completion script generation in order to be
concise
§Examples
App::new("myprog")
.about("Does really amazing things to great people")
Sourcepub fn long_about<S: Into<&'b str>>(self, about: S) -> Self
pub fn long_about<S: Into<&'b str>>(self, about: S) -> Self
Sets a string describing what the program does. This will be displayed when displaying help information.
NOTE: If only long_about
is provided, and not App::about
but the user requests
-h
clap will still display the contents of long_about
appropriately
NOTE: Only App::about
is used in completion script generation in order to be
concise
§Examples
App::new("myprog")
.long_about(
"Does really amazing things to great people. Now let's talk a little
more in depth about how this subcommand really works. It may take about
a few lines of text, but that's ok!")
Sourcepub fn name<S: Into<String>>(self, name: S) -> Self
pub fn name<S: Into<String>>(self, name: S) -> Self
Sets the program’s name. This will be displayed when displaying help information.
Pro-top: This function is particularly useful when configuring a program via
App::from_yaml
in conjunction with the crate_name!
macro to derive the program’s
name from its Cargo.toml
.
§Examples
let yml = load_yaml!("app.yml");
let app = App::from_yaml(yml)
.name(crate_name!());
// continued logic goes here, such as `app.get_matches()` etc.
Sourcepub fn after_help<S: Into<&'b str>>(self, help: S) -> Self
pub fn after_help<S: Into<&'b str>>(self, help: S) -> Self
Adds additional help information to be displayed in addition to auto-generated help. This information is displayed after the auto-generated help information. This is often used to describe how to use the arguments, or caveats to be noted.
§Examples
App::new("myprog")
.after_help("Does really amazing things to great people...but be careful with -R")
Sourcepub fn before_help<S: Into<&'b str>>(self, help: S) -> Self
pub fn before_help<S: Into<&'b str>>(self, help: S) -> Self
Adds additional help information to be displayed in addition to auto-generated help. This information is displayed before the auto-generated help information. This is often used for header information.
§Examples
App::new("myprog")
.before_help("Some info I'd like to appear before the help info")
Sourcepub fn version<S: Into<&'b str>>(self, ver: S) -> Self
pub fn version<S: Into<&'b str>>(self, ver: S) -> Self
Sets a string of the version number to be displayed when displaying version or help
information with -V
.
NOTE: If only version
is provided, and not App::long_version
but the user
requests --version
clap will still display the contents of version
appropriately
Pro-tip: Use clap
s convenience macro crate_version!
to automatically set your
application’s version to the same thing as your crate at compile time. See the examples/
directory for more information
§Examples
App::new("myprog")
.version("v0.1.24")
Sourcepub fn long_version<S: Into<&'b str>>(self, ver: S) -> Self
pub fn long_version<S: Into<&'b str>>(self, ver: S) -> Self
Sets a string of the version number to be displayed when displaying version or help
information with --version
.
NOTE: If only long_version
is provided, and not App::version
but the user
requests -V
clap will still display the contents of long_version
appropriately
Pro-tip: Use clap
s convenience macro crate_version!
to automatically set your
application’s version to the same thing as your crate at compile time. See the examples/
directory for more information
§Examples
App::new("myprog")
.long_version(
"v0.1.24
commit: abcdef89726d
revision: 123
release: 2
binary: myprog")
Sourcepub fn usage<S: Into<&'b str>>(self, usage: S) -> Self
pub fn usage<S: Into<&'b str>>(self, usage: S) -> Self
Sets a custom usage string to override the auto-generated usage string.
This will be displayed to the user when errors are found in argument parsing, or when you
call ArgMatches::usage
CAUTION: Using this setting disables clap
s “context-aware” usage strings. After this
setting is set, this will be the only usage string displayed to the user!
NOTE: You do not need to specify the “USAGE: \n\t” portion, as that will
still be applied by clap
, you only need to specify the portion starting
with the binary name.
NOTE: This will not replace the entire help message, only the portion showing the usage.
§Examples
App::new("myprog")
.usage("myapp [-clDas] <some_file>")
Sourcepub fn help<S: Into<&'b str>>(self, help: S) -> Self
pub fn help<S: Into<&'b str>>(self, help: S) -> Self
Sets a custom help message and overrides the auto-generated one. This should only be used when the auto-generated message does not suffice.
This will be displayed to the user when they use --help
or -h
NOTE: This replaces the entire help message, so nothing will be auto-generated.
NOTE: This only 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 Arg::help
for them as well.
§Examples
App::new("myapp")
.help("myapp v1.0\n\
Does awesome things\n\
(C) me@mail.com\n\n\
USAGE: myapp <opts> <command>\n\n\
Options:\n\
-h, --help Display 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")
Sourcepub fn help_short<S: AsRef<str> + 'b>(self, s: S) -> Self
pub fn help_short<S: AsRef<str> + 'b>(self, s: S) -> Self
Sets the short
for the auto-generated help
argument.
By default clap
automatically assigns h
, but this can be overridden if you have a
different argument which you’d prefer to use the -h
short with. This can be done by
defining your own argument with a lowercase h
as the short
.
clap
lazily generates these help
arguments after you’ve defined any arguments of
your own.
NOTE: Any leading -
characters will be stripped, and only the first
non -
character will be used as the short
version
§Examples
App::new("myprog")
.help_short("H") // Using an uppercase `H` instead of the default lowercase `h`
Sourcepub fn version_short<S: AsRef<str>>(self, s: S) -> Self
pub fn version_short<S: AsRef<str>>(self, s: S) -> Self
Sets the short
for the auto-generated version
argument.
By default clap
automatically assigns V
, but this can be overridden if you have a
different argument which you’d prefer to use the -V
short with. This can be done by
defining your own argument with an uppercase V
as the short
.
clap
lazily generates these version
arguments after you’ve defined any arguments of
your own.
NOTE: Any leading -
characters will be stripped, and only the first
non -
character will be used as the short
version
§Examples
App::new("myprog")
.version_short("v") // Using a lowercase `v` instead of the default capital `V`
Sourcepub fn help_message<S: Into<&'a str>>(self, s: S) -> Self
pub fn help_message<S: Into<&'a str>>(self, s: S) -> Self
Sets the help text for the auto-generated help
argument.
By default clap
sets this to "Prints help information"
, but if you’re using a
different convention for your help messages and would prefer a different phrasing you can
override it.
§Examples
App::new("myprog")
.help_message("Print help information") // Perhaps you want imperative help messages
Sourcepub fn version_message<S: Into<&'a str>>(self, s: S) -> Self
pub fn version_message<S: Into<&'a str>>(self, s: S) -> Self
Sets the help text for the auto-generated version
argument.
By default clap
sets this to "Prints version information"
, but if you’re using a
different convention for your help messages and would prefer a different phrasing then you
can change it.
§Examples
App::new("myprog")
.version_message("Print version information") // Perhaps you want imperative help messages
Sourcepub fn template<S: Into<&'b str>>(self, s: S) -> Self
pub fn template<S: Into<&'b str>>(self, s: S) -> Self
Sets the help template to be used, overriding the default format.
Tags arg given inside curly brackets.
Valid tags are:
{bin}
- Binary name.{version}
- Version number.{author}
- Author information.{about}
- General description (fromApp::about
){usage}
- Automatically generated or given usage string.{all-args}
- Help for all arguments (options, flags, positionals arguments, and subcommands) including titles.{unified}
- Unified help for options and flags. Note, you must also setAppSettings::UnifiedHelpMessage
to fully merge both options and flags, otherwise the ordering is “best effort”{flags}
- Help for flags.{options}
- Help for options.{positionals}
- Help for positionals arguments.{subcommands}
- Help for subcommands.{after-help}
- Help fromApp::after_help
{before-help}
- Help fromApp::before_help
§Examples
App::new("myprog")
.version("1.0")
.template("{bin} ({version}) - {usage}")
NOTE: The template system is, on purpose, very simple. Therefore the tags have to be written in lowercase and without spacing.
Sourcepub fn setting(self, setting: AppSettings) -> Self
pub fn setting(self, setting: AppSettings) -> Self
Enables a single command, or SubCommand
, level settings.
See AppSettings
for a full list of possibilities and examples.
§Examples
App::new("myprog")
.setting(AppSettings::SubcommandRequired)
.setting(AppSettings::WaitOnError)
Sourcepub fn settings(self, settings: &[AppSettings]) -> Self
pub fn settings(self, settings: &[AppSettings]) -> Self
Enables multiple command, or SubCommand
, level settings
See AppSettings
for a full list of possibilities and examples.
§Examples
App::new("myprog")
.settings(&[AppSettings::SubcommandRequired,
AppSettings::WaitOnError])
Sourcepub fn global_setting(self, setting: AppSettings) -> Self
pub fn global_setting(self, setting: AppSettings) -> Self
Enables a single setting that is propagated down through all child SubCommand
s.
See AppSettings
for a full list of possibilities and examples.
NOTE: The setting is only propagated down and not up through parent commands.
§Examples
App::new("myprog")
.global_setting(AppSettings::SubcommandRequired)
Sourcepub fn global_settings(self, settings: &[AppSettings]) -> Self
pub fn global_settings(self, settings: &[AppSettings]) -> Self
Enables multiple settings which are propagated down through all child SubCommand
s.
See AppSettings
for a full list of possibilities and examples.
NOTE: The setting is only propagated down and not up through parent commands.
§Examples
App::new("myprog")
.global_settings(&[AppSettings::SubcommandRequired,
AppSettings::ColoredHelp])
Sourcepub fn unset_setting(self, setting: AppSettings) -> Self
pub fn unset_setting(self, setting: AppSettings) -> Self
Disables a single command, or SubCommand
, level setting.
See AppSettings
for a full list of possibilities and examples.
§Examples
App::new("myprog")
.unset_setting(AppSettings::ColorAuto)
Sourcepub fn unset_settings(self, settings: &[AppSettings]) -> Self
pub fn unset_settings(self, settings: &[AppSettings]) -> Self
Disables multiple command, or SubCommand
, level settings.
See AppSettings
for a full list of possibilities and examples.
§Examples
App::new("myprog")
.unset_settings(&[AppSettings::ColorAuto,
AppSettings::AllowInvalidUtf8])
Sourcepub fn set_term_width(self, width: usize) -> Self
pub fn set_term_width(self, width: usize) -> Self
Sets the terminal width at which to wrap help messages. Defaults to 120
. Using 0
will
ignore terminal widths and use source formatting.
clap
automatically tries to determine the terminal width on Unix, Linux, macOS and Windows
if the wrap_help
cargo “feature” has been used while compiling. If the terminal width
cannot be determined, clap
defaults to 120
.
NOTE: This setting applies globally and not on a per-command basis.
NOTE: This setting must be set before any subcommands are added!
§Platform Specific
Only Unix, Linux, macOS and Windows support automatic determination of terminal width. Even on those platforms, this setting is useful if for any reason the terminal width cannot be determined.
§Examples
App::new("myprog")
.set_term_width(80)
Sourcepub fn max_term_width(self, w: usize) -> Self
pub fn max_term_width(self, w: usize) -> Self
Sets the max terminal width at which to wrap help messages. Using 0
will ignore terminal
widths and use source formatting.
clap
automatically tries to determine the terminal width on Unix, Linux, macOS and Windows
if the wrap_help
cargo “feature” has been used while compiling, but one might want to
limit the size (e.g. when the terminal is running fullscreen).
NOTE: This setting applies globally and not on a per-command basis.
NOTE: This setting must be set before any subcommands are added!
§Platform Specific
Only Unix, Linux, macOS and Windows support automatic determination of terminal width.
§Examples
App::new("myprog")
.max_term_width(100)
Sourcepub fn arg<A: Into<Arg<'a, 'b>>>(self, a: A) -> Self
pub fn arg<A: Into<Arg<'a, 'b>>>(self, a: A) -> Self
Adds an argument to the list of valid possibilities.
§Examples
App::new("myprog")
// Adding a single "flag" argument with a short and help text, using Arg::with_name()
.arg(
Arg::with_name("debug")
.short("d")
.help("turns on debugging mode")
)
// Adding a single "option" argument with a short, a long, and help text using the less
// verbose Arg::from_usage()
.arg(
Arg::from_usage("-c --config=[CONFIG] 'Optionally sets a config file to use'")
)
Sourcepub fn arg_from_usage(self, usage: &'a str) -> Self
pub fn arg_from_usage(self, usage: &'a str) -> Self
A convenience method for adding a single argument from a usage type string. The string
used follows the same rules and syntax as Arg::from_usage
NOTE: The downside to using this method is that you can not set any additional
properties of the Arg
other than what Arg::from_usage
supports.
§Examples
App::new("myprog")
.arg_from_usage("-c --config=<FILE> 'Sets a configuration file to use'")
Sourcepub fn args_from_usage(self, usage: &'a str) -> Self
pub fn args_from_usage(self, usage: &'a str) -> Self
Adds multiple arguments at once from a usage string, one per line. See
Arg::from_usage
for details on the syntax and rules supported.
NOTE: Like App::arg_from_usage
the downside is you only set properties for the
Arg
s which Arg::from_usage
supports.
§Examples
App::new("myprog")
.args_from_usage(
"-c --config=[FILE] 'Sets a configuration file to use'
[debug]... -d 'Sets the debugging level'
<FILE> 'The input file to use'"
)
Sourcepub fn alias<S: Into<&'b str>>(self, name: S) -> Self
pub fn alias<S: Into<&'b str>>(self, name: S) -> Self
Allows adding a SubCommand
alias, which function as “hidden” subcommands that
automatically dispatch as if this subcommand was used. This is more efficient, and easier
than creating multiple hidden subcommands as one only needs to check for the existence of
this command, and not all variants.
§Examples
let m = App::new("myprog")
.subcommand(SubCommand::with_name("test")
.alias("do-stuff"))
.get_matches_from(vec!["myprog", "do-stuff"]);
assert_eq!(m.subcommand_name(), Some("test"));
Sourcepub fn aliases(self, names: &[&'b str]) -> Self
pub fn aliases(self, names: &[&'b str]) -> Self
Allows adding SubCommand
aliases, which function as “hidden” subcommands that
automatically dispatch as if this subcommand was used. This is more efficient, and easier
than creating multiple hidden subcommands as one only needs to check for the existence of
this command, and not all variants.
§Examples
let m = App::new("myprog")
.subcommand(SubCommand::with_name("test")
.aliases(&["do-stuff", "do-tests", "tests"]))
.arg(Arg::with_name("input")
.help("the file to add")
.index(1)
.required(false))
.get_matches_from(vec!["myprog", "do-tests"]);
assert_eq!(m.subcommand_name(), Some("test"));
Sourcepub fn visible_alias<S: Into<&'b str>>(self, name: S) -> Self
pub fn visible_alias<S: Into<&'b str>>(self, name: S) -> Self
Allows adding a SubCommand
alias that functions exactly like those defined with
App::alias
, except that they are visible inside the help message.
§Examples
let m = App::new("myprog")
.subcommand(SubCommand::with_name("test")
.visible_alias("do-stuff"))
.get_matches_from(vec!["myprog", "do-stuff"]);
assert_eq!(m.subcommand_name(), Some("test"));
Sourcepub fn visible_aliases(self, names: &[&'b str]) -> Self
pub fn visible_aliases(self, names: &[&'b str]) -> Self
Allows adding multiple SubCommand
aliases that functions exactly like those defined
with App::aliases
, except that they are visible inside the help message.
§Examples
let m = App::new("myprog")
.subcommand(SubCommand::with_name("test")
.visible_aliases(&["do-stuff", "tests"]))
.get_matches_from(vec!["myprog", "do-stuff"]);
assert_eq!(m.subcommand_name(), Some("test"));
Sourcepub fn group(self, group: ArgGroup<'a>) -> Self
pub fn group(self, group: ArgGroup<'a>) -> Self
Adds an ArgGroup
to the application. ArgGroup
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 ArgGroup
required, meaning that one (and only
one) argument from that group must be present at runtime.
You can also do things such as name an ArgGroup
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.
Another added benefit of ArgGroup
s is that you can extract a value from a group instead
of determining exactly which argument was used.
Finally, using ArgGroup
s to ensure exclusion between arguments is another very common
use
§Examples
The following example demonstrates using an ArgGroup
to ensure that one, and only one,
of the arguments from the specified group is present at runtime.
App::new("app")
.args_from_usage(
"--set-ver [ver] 'set the version manually'
--major 'auto increase major'
--minor 'auto increase minor'
--patch 'auto increase patch'")
.group(ArgGroup::with_name("vers")
.args(&["set-ver", "major", "minor","patch"])
.required(true))
Sourcepub fn groups(self, groups: &[ArgGroup<'a>]) -> Self
pub fn groups(self, groups: &[ArgGroup<'a>]) -> Self
Adds multiple ArgGroup
s to the App
at once.
§Examples
App::new("app")
.args_from_usage(
"--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'")
.groups(&[
ArgGroup::with_name("vers")
.args(&["set-ver", "major", "minor","patch"])
.required(true),
ArgGroup::with_name("input")
.args(&["c", "i"])
])
Sourcepub fn subcommand(self, subcmd: App<'a, 'b>) -> Self
pub fn subcommand(self, subcmd: App<'a, 'b>) -> Self
Adds a SubCommand
to the list of valid possibilities. Subcommands are effectively
sub-App
s, because they can contain their own arguments, subcommands, version, usage,
etc. They also function just like App
s, in that they get their own auto generated help,
version, and usage.
§Examples
App::new("myprog")
.subcommand(SubCommand::with_name("config")
.about("Controls configuration features")
.arg_from_usage("<config> 'Required configuration file to use'"))
Sourcepub fn subcommands<I>(self, subcmds: I) -> Selfwhere
I: IntoIterator<Item = App<'a, 'b>>,
pub fn subcommands<I>(self, subcmds: I) -> Selfwhere
I: IntoIterator<Item = App<'a, 'b>>,
Adds multiple subcommands to the list of valid possibilities by iterating over an
IntoIterator
of SubCommand
s
§Examples
.subcommands( vec![
SubCommand::with_name("config").about("Controls configuration functionality")
.arg(Arg::with_name("config_file").index(1)),
SubCommand::with_name("debug").about("Controls debug functionality")])
Sourcepub fn display_order(self, ord: usize) -> Self
pub fn display_order(self, ord: usize) -> Self
Allows custom ordering of SubCommand
s 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 are allowed. Subcommands with duplicate display orders will be
displayed in alphabetical order.
NOTE: The default is 999 for all subcommands.
§Examples
let m = App::new("cust-ord")
.subcommand(SubCommand::with_name("alpha") // typically subcommands are grouped
// alphabetically by name. Subcommands
// without a display_order have a value of
// 999 and are displayed alphabetically with
// all other 999 subcommands
.about("Some help and text"))
.subcommand(SubCommand::with_name("beta")
.display_order(1) // In order to force this subcommand to appear *first*
// all we have to do is give it a value lower than 999.
// Any other subcommands with a value of 1 will be displayed
// alphabetically with this one...then 2 values, then 3, etc.
.about("I should be first!"))
.get_matches_from(vec![
"cust-ord", "--help"
]);
The above example displays the following help message
cust-ord
USAGE:
cust-ord [FLAGS] [OPTIONS]
FLAGS:
-h, --help Prints help information
-V, --version Prints version information
SUBCOMMANDS:
beta I should be first!
alpha Some help and text
Sourcepub fn print_help(&mut self) -> ClapResult<()>
pub fn print_help(&mut self) -> ClapResult<()>
Prints the full help message to io::stdout()
using a BufWriter
using the same
method as if someone ran -h
to request the help message
NOTE: clap has the ability to distinguish between “short” and “long” help messages
depending on if the user ran -h
(short) or --help
(long)
§Examples
let mut app = App::new("myprog");
app.print_help();
Sourcepub fn print_long_help(&mut self) -> ClapResult<()>
pub fn print_long_help(&mut self) -> ClapResult<()>
Prints the full help message to io::stdout()
using a BufWriter
using the same
method as if someone ran --help
to request the help message
NOTE: clap has the ability to distinguish between “short” and “long” help messages
depending on if the user ran -h
(short) or --help
(long)
§Examples
let mut app = App::new("myprog");
app.print_long_help();
Sourcepub fn write_help<W: Write>(&self, w: &mut W) -> ClapResult<()>
pub fn write_help<W: Write>(&self, w: &mut W) -> ClapResult<()>
Writes the full help message to the user to a io::Write
object in the same method as if
the user ran -h
NOTE: clap has the ability to distinguish between “short” and “long” help messages
depending on if the user ran -h
(short) or --help
(long)
NOTE: There is a known bug where this method does not write propagated global arguments
or autogenerated arguments (i.e. the default help/version args). Prefer
App::write_long_help
instead if possible!
§Examples
use std::io;
let mut app = App::new("myprog");
let mut out = io::stdout();
app.write_help(&mut out).expect("failed to write to stdout");
Sourcepub fn write_long_help<W: Write>(&mut self, w: &mut W) -> ClapResult<()>
pub fn write_long_help<W: Write>(&mut self, w: &mut W) -> ClapResult<()>
Writes the full help message to the user to a io::Write
object in the same method as if
the user ran --help
NOTE: clap has the ability to distinguish between “short” and “long” help messages
depending on if the user ran -h
(short) or --help
(long)
§Examples
use std::io;
let mut app = App::new("myprog");
let mut out = io::stdout();
app.write_long_help(&mut out).expect("failed to write to stdout");
Sourcepub fn write_version<W: Write>(&self, w: &mut W) -> ClapResult<()>
pub fn write_version<W: Write>(&self, w: &mut W) -> ClapResult<()>
Writes the version message to the user to a io::Write
object as if the user ran -V
.
NOTE: clap has the ability to distinguish between “short” and “long” version messages
depending on if the user ran -V
(short) or --version
(long)
§Examples
use std::io;
let mut app = App::new("myprog");
let mut out = io::stdout();
app.write_version(&mut out).expect("failed to write to stdout");
Sourcepub fn write_long_version<W: Write>(&self, w: &mut W) -> ClapResult<()>
pub fn write_long_version<W: Write>(&self, w: &mut W) -> ClapResult<()>
Writes the version message to the user to a io::Write
object
NOTE: clap has the ability to distinguish between “short” and “long” version messages
depending on if the user ran -V
(short) or --version
(long)
§Examples
use std::io;
let mut app = App::new("myprog");
let mut out = io::stdout();
app.write_long_version(&mut out).expect("failed to write to stdout");
Sourcepub fn gen_completions<T: Into<OsString>, S: Into<String>>(
&mut self,
bin_name: S,
for_shell: Shell,
out_dir: T,
)
pub fn gen_completions<T: Into<OsString>, S: Into<String>>( &mut self, bin_name: S, for_shell: Shell, out_dir: T, )
Generate a completions file for a specified shell at compile time.
NOTE: to generate the file at compile time you must use a build.rs
“Build Script”
§Examples
The following example generates a bash completion script via a build.rs
script. In this
simple example, we’ll demo a very small application with only a single subcommand and two
args. Real applications could be many multiple levels deep in subcommands, and have tens or
potentially hundreds of arguments.
First, it helps if we separate out our App
definition into a separate file. Whether you
do this as a function, or bare App definition is a matter of personal preference.
// src/cli.rs
use clap::{App, Arg, SubCommand};
pub fn build_cli() -> App<'static, 'static> {
App::new("compl")
.about("Tests completions")
.arg(Arg::with_name("file")
.help("some input file"))
.subcommand(SubCommand::with_name("test")
.about("tests things")
.arg(Arg::with_name("case")
.long("case")
.takes_value(true)
.help("the case to test")))
}
In our regular code, we can simply call this build_cli()
function, then call
get_matches()
, or any of the other normal methods directly after. For example:
// src/main.rs
mod cli;
fn main() {
let m = cli::build_cli().get_matches();
// normal logic continues...
}
Next, we set up our Cargo.toml
to use a build.rs
build script.
# Cargo.toml
build = "build.rs"
[build-dependencies]
clap = "2.23"
Next, we place a build.rs
in our project root.
extern crate clap;
use clap::Shell;
include!("src/cli.rs");
fn main() {
let outdir = match env::var_os("OUT_DIR") {
None => return,
Some(outdir) => outdir,
};
let mut app = build_cli();
app.gen_completions("myapp", // We need to specify the bin name manually
Shell::Bash, // Then say which shell to build completions for
outdir); // Then say where write the completions to
}
Now, once we compile there will be a {bin_name}.bash
file in the directory.
Assuming we compiled with debug mode, it would be somewhere similar to
<project>/target/debug/build/myapp-<hash>/out/myapp.bash
.
Fish shell completions will use the file format {bin_name}.fish
Sourcepub fn gen_completions_to<W: Write, S: Into<String>>(
&mut self,
bin_name: S,
for_shell: Shell,
buf: &mut W,
)
pub fn gen_completions_to<W: Write, S: Into<String>>( &mut self, bin_name: S, for_shell: Shell, buf: &mut W, )
Generate a completions file for a specified shell at runtime. Until cargo install
can
install extra files like a completion script, this may be used e.g. in a command that
outputs the contents of the completion script, to be redirected into a file by the user.
§Examples
Assuming a separate cli.rs
like the example above,
we can let users generate a completion script using a command:
// src/main.rs
mod cli;
use std::io;
fn main() {
let matches = cli::build_cli().get_matches();
if matches.is_present("generate-bash-completions") {
cli::build_cli().gen_completions_to("myapp", Shell::Bash, &mut io::stdout());
}
// normal logic continues...
}
Usage:
$ myapp generate-bash-completions > /usr/share/bash-completion/completions/myapp.bash
Sourcepub fn get_matches(self) -> ArgMatches<'a>
pub fn get_matches(self) -> ArgMatches<'a>
Starts the parsing process, upon a failed parse an error will be displayed to the user and
the process will exit with the appropriate error code. By default this method gets all user
provided arguments from env::args_os
in order to allow for invalid UTF-8 code points,
which are legal on many platforms.
§Examples
let matches = App::new("myprog")
// Args and options go here...
.get_matches();
Sourcepub fn get_matches_safe(self) -> ClapResult<ArgMatches<'a>>
pub fn get_matches_safe(self) -> ClapResult<ArgMatches<'a>>
Starts the parsing process. This method will return a clap::Result
type instead of exiting
the process on failed parse. By default this method gets matches from env::args_os
NOTE: This method WILL NOT exit when --help
or --version
(or short versions) are
used. It will return a clap::Error
, where the kind
is a
ErrorKind::HelpDisplayed
or ErrorKind::VersionDisplayed
respectively. You must call
Error::exit
or perform a std::process::exit
.
§Examples
let matches = App::new("myprog")
// Args and options go here...
.get_matches_safe()
.unwrap_or_else( |e| e.exit() );
Sourcepub fn get_matches_from<I, T>(self, itr: I) -> ArgMatches<'a>
pub fn get_matches_from<I, T>(self, itr: I) -> ArgMatches<'a>
Starts the parsing process. Like App::get_matches
this method does not return a clap::Result
and will automatically exit with an error message. This method, however, lets you specify
what iterator to use when performing matches, such as a Vec
of your making.
NOTE: The first argument will be parsed as the binary name unless
AppSettings::NoBinaryName
is used
§Examples
let arg_vec = vec!["my_prog", "some", "args", "to", "parse"];
let matches = App::new("myprog")
// Args and options go here...
.get_matches_from(arg_vec);
Sourcepub fn get_matches_from_safe<I, T>(self, itr: I) -> ClapResult<ArgMatches<'a>>
pub fn get_matches_from_safe<I, T>(self, itr: I) -> ClapResult<ArgMatches<'a>>
Starts the parsing process. A combination of App::get_matches_from
, and
App::get_matches_safe
NOTE: This method WILL NOT exit when --help
or --version
(or short versions) are
used. It will return a clap::Error
, where the kind
is a ErrorKind::HelpDisplayed
or ErrorKind::VersionDisplayed
respectively. You must call Error::exit
or
perform a std::process::exit
yourself.
NOTE: The first argument will be parsed as the binary name unless
AppSettings::NoBinaryName
is used
§Examples
let arg_vec = vec!["my_prog", "some", "args", "to", "parse"];
let matches = App::new("myprog")
// Args and options go here...
.get_matches_from_safe(arg_vec)
.unwrap_or_else( |e| { panic!("An error occurs: {}", e) });
Sourcepub fn get_matches_from_safe_borrow<I, T>(
&mut self,
itr: I,
) -> ClapResult<ArgMatches<'a>>
pub fn get_matches_from_safe_borrow<I, T>( &mut self, itr: I, ) -> ClapResult<ArgMatches<'a>>
Starts the parsing process without consuming the App
struct self
. This is normally not
the desired functionality, instead prefer App::get_matches_from_safe
which does
consume self
.
NOTE: The first argument will be parsed as the binary name unless
AppSettings::NoBinaryName
is used
§Examples
let arg_vec = vec!["my_prog", "some", "args", "to", "parse"];
let mut app = App::new("myprog");
// Args and options go here...
let matches = app.get_matches_from_safe_borrow(arg_vec)
.unwrap_or_else( |e| { panic!("An error occurs: {}", e) });
Trait Implementations§
Auto Trait Implementations§
impl<'a, 'b> !Freeze for App<'a, 'b>
impl<'a, 'b> !RefUnwindSafe for App<'a, 'b>
impl<'a, 'b> !Send for App<'a, 'b>
impl<'a, 'b> !Sync for App<'a, 'b>
impl<'a, 'b> Unpin for App<'a, 'b>
impl<'a, 'b> !UnwindSafe for App<'a, 'b>
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
Source§unsafe fn clone_to_uninit(&self, dst: *mut T)
unsafe fn clone_to_uninit(&self, dst: *mut T)
clone_to_uninit
)