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

Merge pull request #2412 from clap-rs/docs

Browse source 
Apply cargo-intraconv
This commit is contained in:
Pavan Kumar Sunkara 2021-03-13 18:11:52 +05:30 committed by GitHub
commit dd352be191
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
15 changed files with 330 additions and 430 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
clap_derive/src/lib.rs
View file

@ -16,7 +16,7 @@
#![doc(html_root_url = "https://docs.rs/clap_derive/3.0.0-beta.2")]
//! This crate is custom derive for clap. It should not be used
//! directly. See [clap documentation](https://docs.rs/clap)
//! directly. See [clap documentation](clap)
//! for the usage of `#[derive(Clap)]`.
#![forbid(unsafe_code)]

22
clap_generate/src/generators/mod.rs
View file

@ -29,12 +29,12 @@ pub trait Generator {
/// ```
fn file_name(name: &str) -> String;
/// Generates output out of [`clap::App`](../clap/struct.App.html).
/// Generates output out of [`clap::App`](super::clap::App).
///
/// # Examples
///
/// The following example generator displays the [`clap::App`](../clap/struct.App.html)
/// as if it is printed using [`std::println`](https://doc.rust-lang.org/std/macro.println.html).
/// The following example generator displays the [`clap::App`](super::clap::App)
/// as if it is printed using [`std::println`](std::println!).
///
/// ```
/// use std::{io::Write, fmt::write};
@ -72,7 +72,7 @@ pub trait Generator {
///
/// **NOTE:** `path` should not contain the root `bin_name`.
///
/// [clap]: ../clap/struct.App.html
/// [clap]: super::clap::App
fn find_subcommand_with_path<'help, 'app>(
p: &'app App<'help>,
path: Vec<&str>,
@ -86,7 +86,7 @@ pub trait Generator {
app
}
/// Gets subcommands of [`clap::App`](../clap/struct.App.html) in the form of `("name", "bin_name")`.
/// Gets subcommands of [`clap::App`](super::clap::App) in the form of `("name", "bin_name")`.
///
/// Subcommand `rustup toolchain install` would be converted to
/// `("install", "rustup toolchain install")`.
@ -115,8 +115,8 @@ pub trait Generator {
subcmds
}
/// Gets all the short options, their visible aliases and flags of a [`clap::App`](../clap/struct.App.html).
/// Includes `h` and `V` depending on the [`clap::AppSettings`](../clap/enum.AppSettings.html).
/// Gets all the short options, their visible aliases and flags of a [`clap::App`](super::clap::App).
/// Includes `h` and `V` depending on the [`clap::AppSettings`](super::clap::AppSettings).
fn shorts_and_visible_aliases(p: &App) -> Vec<char> {
debug!("shorts: name={}", p.get_name());
@ -140,8 +140,8 @@ pub trait Generator {
.collect()
}
/// Gets all the long options, their visible aliases and flags of a [`clap::App`](../clap/struct.App.html).
/// Includes `help` and `version` depending on the [`clap::AppSettings`](../clap/enum.AppSettings.html).
/// Gets all the long options, their visible aliases and flags of a [`clap::App`](super::clap::App).
/// Includes `help` and `version` depending on the [`clap::AppSettings`](super::clap::AppSettings).
fn longs_and_visible_aliases(p: &App) -> Vec<String> {
debug!("longs: name={}", p.get_name());
@ -170,8 +170,8 @@ pub trait Generator {
.collect()
}
/// Gets all the flags of a [`clap::App`](../clap/struct.App.html).
/// Includes `help` and `version` depending on the [`clap::AppSettings`](../clap/enum.AppSettings.html).
/// Gets all the flags of a [`clap::App`](super::clap::App).
/// Includes `help` and `version` depending on the [`clap::AppSettings`](super::clap::AppSettings).
fn flags<'help>(p: &App<'help>) -> Vec<Arg<'help>> {
debug!("flags: name={}", p.get_name());
p.get_flags().cloned().collect()

4
clap_generate/src/lib.rs
View file

@ -125,7 +125,7 @@ pub use shell::Shell;
/// Assuming we compiled with debug mode, it would be somewhere similar to
/// `<project>/target/debug/build/myapp-<hash>/out/myapp.bash`.
///
/// **NOTE:** Please look at the individual [generators](./generators/index.html)
/// **NOTE:** Please look at the individual [generators]
/// to see the name of the files generated.
pub fn generate_to<G, S, T>(app: &mut clap::App, bin_name: S, out_dir: T)
where
@ -152,7 +152,7 @@ where
///
/// # Examples
///
/// Assuming a separate `cli.rs` like the [example above](./fn.generate_to.html),
/// Assuming a separate `cli.rs` like the [example above](generate_to()),
/// we can let users generate a completion script using a command:
///
/// ```ignore

192
src/build/app/mod.rs
View file

@ -59,7 +59,7 @@ use crate::{
///
/// // Your program logic starts here...
/// ```
/// [`App::get_matches`]: ./struct.App.html#method.get_matches
/// [`App::get_matches`]: App::get_matches()
#[derive(Default, Debug, Clone, PartialEq, Eq)]
pub struct App<'help> {
pub(crate) id: Id,
@ -130,7 +130,7 @@ impl<'help> App<'help> {
/// Get the help message specified via [`App::about`].
///
/// [`App::about`]: ./struct.App.html#method.about
/// [`App::about`]: App::about()
#[inline]
pub fn get_about(&self) -> Option<&str> {
self.about.as_deref()
@ -313,9 +313,8 @@ impl<'help> App<'help> {
/// Returns `true` if the given [`AppSettings`] variant is currently set in
/// this `App` (checks both [local] and [global settings]).
///
/// [`AppSettings`]: ./enum.AppSettings.html
/// [local]: ./struct.App.html#method.setting
/// [global settings]: ./struct.App.html#method.global_setting
/// [local]: App::setting()
/// [global settings]: App::global_setting()
#[inline]
pub fn is_set(&self, s: AppSettings) -> bool {
self.settings.is_set(s) || self.g_settings.is_set(s)
@ -458,9 +457,9 @@ impl<'help> App<'help> {
/// .about("Does really amazing things for great people")
/// # ;
/// ```
/// [long format]: ./struct.App.html#method.long_about
/// [short format]: ./struct.App.html#method.about
/// [`App::about`]: ./struct.App.html#method.about
/// [long format]: App::long_about()
/// [short format]: App::about()
/// [`App::about`]: App::about()
pub fn about<S: Into<&'help str>>(mut self, about: S) -> Self {
self.about = Some(about.into());
self
@ -492,9 +491,9 @@ impl<'help> App<'help> {
/// a few lines of text, but that's ok!")
/// # ;
/// ```
/// [long format]: ./struct.App.html#method.long_about
/// [short format]: ./struct.App.html#method.about
/// [`App::about`]: ./struct.App.html#method.about
/// [long format]: App::long_about()
/// [short format]: App::about()
/// [`App::about`]: App::about()
pub fn long_about<S: Into<&'help str>>(mut self, about: S) -> Self {
self.long_about = Some(about.into());
self
@ -518,7 +517,6 @@ impl<'help> App<'help> {
/// // continued logic goes here, such as `app.get_matches()` etc.
/// ```
///
/// [`crate_name!`]: ./macro.crate_name.html
pub fn name<S: Into<String>>(mut self, name: S) -> Self {
self.name = name.into();
self
@ -540,7 +538,7 @@ impl<'help> App<'help> {
/// # ;
/// ```
///
/// [`App::after_help`]: ./struct.App.html#method.after_help
/// [`App::after_help`]: App::after_help()
pub fn after_help<S: Into<&'help str>>(mut self, help: S) -> Self {
self.after_help = Some(help.into());
self
@ -563,7 +561,7 @@ impl<'help> App<'help> {
/// like, for real, be careful with this!")
/// # ;
/// ```
/// [`App::after_long_help`]: ./struct.App.html#method.after_long_help
/// [`App::after_long_help`]: App::after_long_help()
pub fn after_long_help<S: Into<&'help str>>(mut self, help: S) -> Self {
self.after_long_help = Some(help.into());
self
@ -584,7 +582,7 @@ impl<'help> App<'help> {
/// .before_help("Some info I'd like to appear before the help info")
/// # ;
/// ```
/// [`App::before_help`]: ./struct.App.html#method.before_help
/// [`App::before_help`]: App::before_help()
pub fn before_help<S: Into<&'help str>>(mut self, help: S) -> Self {
self.before_help = Some(help.into());
self
@ -605,7 +603,7 @@ impl<'help> App<'help> {
/// .before_long_help("Some verbose and long info I'd like to appear before the help info")
/// # ;
/// ```
/// [`App::before_long_help`]: ./struct.App.html#method.before_long_help
/// [`App::before_long_help`]: App::before_long_help()
pub fn before_long_help<S: Into<&'help str>>(mut self, help: S) -> Self {
self.before_long_help = Some(help.into());
self
@ -634,7 +632,7 @@ impl<'help> App<'help> {
/// let sync_matches = matches.subcommand_matches("sync").unwrap();
/// assert!(sync_matches.is_present("search"));
/// ```
/// [`Arg::short`]: ./struct.Arg.html#method.short
/// [`Arg::short`]: Arg::short()
pub fn short_flag(mut self, short: char) -> Self {
self.short_flag = Some(short);
self
@ -670,7 +668,7 @@ impl<'help> App<'help> {
/// assert!(sync_matches.is_present("search"));
/// ```
///
/// [`Arg::long`]: ./struct.Arg.html#method.long
/// [`Arg::long`]: Arg::long()
pub fn long_flag(mut self, long: &'help str) -> Self {
self.long_flag = Some(long.trim_start_matches(|c| c == '-'));
self
@ -701,7 +699,7 @@ impl<'help> App<'help> {
/// ```
/// [`crate_version!`]: ./macro.crate_version!.html
/// [`examples/`]: https://github.com/clap-rs/clap/tree/master/examples
/// [`App::long_version`]: ./struct.App.html#method.long_version
/// [`App::long_version`]: App::long_version()
pub fn version<S: Into<&'help str>>(mut self, ver: S) -> Self {
self.version = Some(ver.into());
self
@ -741,7 +739,7 @@ impl<'help> App<'help> {
/// ```
/// [`crate_version!`]: ./macro.crate_version!.html
/// [`examples/`]: https://github.com/kbknapp/clap-rs/tree/master/examples
/// [`App::version`]: ./struct.App.html#method.version
/// [`App::version`]: App::version()
pub fn long_version<S: Into<&'help str>>(mut self, ver: S) -> Self {
self.long_version = Some(ver.into());
self
@ -787,7 +785,7 @@ impl<'help> App<'help> {
/// .override_usage("myapp [-clDas] <some_file>")
/// # ;
/// ```
/// [`ArgMatches::usage`]: ./struct.ArgMatches.html#method.usage
/// [`ArgMatches::usage`]: ArgMatches::usage()
pub fn override_usage<S: Into<&'help str>>(mut self, usage: S) -> Self {
self.usage_str = Some(usage.into());
self
@ -828,7 +826,7 @@ impl<'help> App<'help> {
/// work Do some work")
/// # ;
/// ```
/// [`Arg::override_help`]: ./struct.Arg.html#method.override_help
/// [`Arg::override_help`]: Arg::override_help()
pub fn override_help<S: Into<&'help str>>(mut self, help: S) -> Self {
self.help_str = Some(help.into());
self
@ -875,13 +873,12 @@ impl<'help> App<'help> {
/// .help_template("{bin} ({version}) - {usage}")
/// # ;
/// ```
/// [`App::about`]: ./struct.App.html#method.about
/// [`App::long_about`]: ./struct.App.html#method.long_about
/// [`App::after_help`]: ./struct.App.html#method.after_help
/// [`App::after_long_help`]: ./struct.App.html#method.after_long_help
/// [`App::before_help`]: ./struct.App.html#method.before_help
/// [`App::before_long_help`]: ./struct.App.html#method.before_long_help
/// [`AppSettings::UnifiedHelpMessage`]: ./enum.AppSettings.html#variant.UnifiedHelpMessage
/// [`App::about`]: App::about()
/// [`App::long_about`]: App::long_about()
/// [`App::after_help`]: App::after_help()
/// [`App::after_long_help`]: App::after_long_help()
/// [`App::before_help`]: App::before_help()
/// [`App::before_long_help`]: App::before_long_help()
pub fn help_template<S: Into<&'help str>>(mut self, s: S) -> Self {
self.template = Some(s.into());
self
@ -900,7 +897,6 @@ impl<'help> App<'help> {
/// .setting(AppSettings::WaitOnError)
/// # ;
/// ```
/// [`AppSettings`]: ./enum.AppSettings.html
#[inline]
pub fn setting(mut self, setting: AppSettings) -> Self {
self.settings.set(setting);
@ -919,7 +915,6 @@ impl<'help> App<'help> {
/// .unset_setting(AppSettings::ColorAuto)
/// # ;
/// ```
/// [`AppSettings`]: ./enum.AppSettings.html
#[inline]
pub fn unset_setting(mut self, setting: AppSettings) -> Self {
self.settings.unset(setting);
@ -941,7 +936,6 @@ impl<'help> App<'help> {
/// .global_setting(AppSettings::SubcommandRequired)
/// # ;
/// ```
/// [`AppSettings`]: ./enum.AppSettings.html
#[inline]
pub fn global_setting(mut self, setting: AppSettings) -> Self {
self.settings.set(setting);
@ -965,8 +959,7 @@ impl<'help> App<'help> {
/// .unset_global_setting(AppSettings::ColorAuto)
/// # ;
/// ```
/// [`AppSettings`]: ./enum.AppSettings.html
/// [global]: ./struct.App.html#method.global_setting
/// [global]: App::global_setting()
#[inline]
pub fn unset_global_setting(mut self, setting: AppSettings) -> Self {
self.settings.unset(setting);
@ -1056,7 +1049,7 @@ impl<'help> App<'help> {
/// )
/// # ;
/// ```
/// [argument]: ./struct.Arg.html
/// [argument]: Arg
pub fn arg<A: Into<Arg<'help>>>(mut self, a: A) -> Self {
let mut arg = a.into();
if let Some(help_heading) = self.current_help_heading {
@ -1074,9 +1067,9 @@ impl<'help> App<'help> {
/// This is useful if the default `FLAGS`, `OPTIONS`, or `ARGS` headings are
/// not specific enough for one's use case.
///
/// [`App::arg`]: ./struct.App.html#method.arg
/// [`App::help_heading`]: ./struct.App.html#method.help_heading
/// [`App::stop_custom_headings`]: ./struct.App.html#method.stop_custom_headings
/// [`App::arg`]: App::arg()
/// [`App::help_heading`]: App::help_heading()
/// [`App::stop_custom_headings`]: App::stop_custom_headings()
#[inline]
pub fn help_heading(mut self, heading: &'help str) -> Self {
self.current_help_heading = Some(heading);
@ -1085,7 +1078,7 @@ impl<'help> App<'help> {
/// Stop using [custom argument headings] and return to default headings.
///
/// [custom argument headings]: ./struct.App.html#method.help_heading
/// [custom argument headings]: App::help_heading()
#[inline]
pub fn stop_custom_headings(mut self) -> Self {
self.current_help_heading = None;
@ -1105,7 +1098,7 @@ impl<'help> App<'help> {
/// ])
/// # ;
/// ```
/// [arguments]: ./struct.Arg.html
/// [arguments]: Arg
pub fn args<I, T>(mut self, args: I) -> Self
where
I: IntoIterator<Item = T>,
@ -1143,8 +1136,7 @@ impl<'help> App<'help> {
/// .get_matches_from(vec!["myprog", "do-stuff"]);
/// assert_eq!(m.subcommand_name(), Some("test"));
/// ```
/// [`ArgMatches`]: ./struct.ArgMatches.html
/// [`App::visible_alias`]: ./struct.App.html#method.visible_alias
/// [`App::visible_alias`]: App::visible_alias()
pub fn alias<S: Into<&'help str>>(mut self, name: S) -> Self {
self.aliases.push((name.into(), false));
self
@ -1221,8 +1213,7 @@ impl<'help> App<'help> {
/// .get_matches_from(vec!["myprog", "do-tests"]);
/// assert_eq!(m.subcommand_name(), Some("test"));
/// ```
/// [`ArgMatches`]: ./struct.ArgMatches.html
/// [`App::visible_aliases`]: ./struct.App.html#method.visible_aliases
/// [`App::visible_aliases`]: App::visible_aliases()
pub fn aliases(mut self, names: &[&'help str]) -> Self {
self.aliases.extend(names.iter().map(|n| (*n, false)));
self
@ -1308,8 +1299,7 @@ impl<'help> App<'help> {
/// .get_matches_from(vec!["myprog", "do-stuff"]);
/// assert_eq!(m.subcommand_name(), Some("test"));
/// ```
/// [`ArgMatches`]: ./struct.ArgMatches.html
/// [`App::alias`]: ./struct.App.html#method.alias
/// [`App::alias`]: App::alias()
pub fn visible_alias<S: Into<&'help str>>(mut self, name: S) -> Self {
self.aliases.push((name.into(), true));
self
@ -1328,7 +1318,7 @@ impl<'help> App<'help> {
/// .get_matches_from(vec!["myprog", "-d"]);
/// assert_eq!(m.subcommand_name(), Some("test"));
/// ```
/// [`App::short_flag_alias`]: ./struct.App.html#method.short_flag_alias
/// [`App::short_flag_alias`]: App::short_flag_alias()
pub fn visible_short_flag_alias(mut self, name: char) -> Self {
if name == '-' {
panic!("short alias name cannot be `-`");
@ -1350,7 +1340,7 @@ impl<'help> App<'help> {
/// .get_matches_from(vec!["myprog", "--testing"]);
/// assert_eq!(m.subcommand_name(), Some("test"));
/// ```
/// [`App::long_flag_alias`]: ./struct.App.html#method.long_flag_alias
/// [`App::long_flag_alias`]: App::long_flag_alias()
pub fn visible_long_flag_alias(mut self, name: &'help str) -> Self {
self.long_flag_aliases.push((name, true));
self
@ -1381,8 +1371,7 @@ impl<'help> App<'help> {
/// .get_matches_from(vec!["myprog", "do-stuff"]);
/// assert_eq!(m.subcommand_name(), Some("test"));
/// ```
/// [`ArgMatches`]: ./struct.ArgMatches.html
/// [`App::alias`]: ./struct.App.html#method.alias
/// [`App::alias`]: App::alias()
pub fn visible_aliases(mut self, names: &[&'help str]) -> Self {
self.aliases.extend(names.iter().map(|n| (*n, true)));
self
@ -1401,7 +1390,7 @@ impl<'help> App<'help> {
/// .get_matches_from(vec!["myprog", "-t"]);
/// assert_eq!(m.subcommand_name(), Some("test"));
/// ```
/// [`App::short_flag_aliases`]: ./struct.App.html#method.short_flag_aliases
/// [`App::short_flag_aliases`]: App::short_flag_aliases()
pub fn visible_short_flag_aliases(mut self, names: &[char]) -> Self {
for s in names {
if s == &'-' {
@ -1425,7 +1414,7 @@ impl<'help> App<'help> {
/// .get_matches_from(vec!["myprog", "--testing"]);
/// assert_eq!(m.subcommand_name(), Some("test"));
/// ```
/// [`App::long_flag_aliases`]: ./struct.App.html#method.long_flag_aliases
/// [`App::long_flag_aliases`]: App::long_flag_aliases()
pub fn visible_long_flag_aliases(mut self, names: &[&'help str]) -> Self {
for s in names {
self.long_flag_aliases.push((s, true));
@ -1535,7 +1524,7 @@ impl<'help> App<'help> {
/// assert_eq!(m.value_of("format"), Some("json"));
/// ```
///
/// [`App::replace`]: ./struct.App.html#method.replace
/// [`App::replace`]: App::replace()
#[inline]
pub fn replace(mut self, name: &'help str, target: &'help [&'help str]) -> Self {
self.replacers.insert(name, target);
@ -1574,7 +1563,6 @@ impl<'help> App<'help> {
/// .required(true))
/// # ;
/// ```
/// [`ArgGroup`]: ./struct.ArgGroup.html
#[inline]
pub fn group<G: Into<ArgGroup<'help>>>(mut self, group: G) -> Self {
self.groups.push(group.into());
@ -1603,8 +1591,6 @@ impl<'help> App<'help> {
/// ])
/// # ;
/// ```
/// [`ArgGroup`]: ./struct.ArgGroup.html
/// [`App`]: ./struct.App.html
pub fn groups<I, T>(mut self, groups: I) -> Self
where
I: IntoIterator<Item = T>,
@ -1631,7 +1617,6 @@ impl<'help> App<'help> {
/// .arg("<config> 'Required configuration file to use'"))
/// # ;
/// ```
/// [`App`]: ./struct.App.html
#[inline]
pub fn subcommand<S: Into<App<'help>>>(mut self, subcmd: S) -> Self {
self.subcommands.push(subcmd.into());
@ -1652,8 +1637,7 @@ impl<'help> App<'help> {
/// App::new("debug").about("Controls debug functionality")])
/// # ;
/// ```
/// [`App`]: ./struct.App.html
/// [`IntoIterator`]: https://doc.rust-lang.org/std/iter/trait.IntoIterator.html
/// [`IntoIterator`]: std::iter::IntoIterator
pub fn subcommands<I, T>(mut self, subcmds: I) -> Self
where
I: IntoIterator<Item = T>,
@ -1739,8 +1723,6 @@ impl<'help> App<'help> {
/// let res = app.try_get_matches_from_mut(vec!["foo", "-B"]);
/// assert!(res.is_ok());
/// ```
/// [`Arg`]: ./struct.Arg.html
/// [`App`]: ./struct.App.html
pub fn mut_arg<T, F>(mut self, arg_id: T, f: F) -> Self
where
F: FnOnce(Arg<'help>) -> Arg<'help>,
@ -1776,10 +1758,10 @@ impl<'help> App<'help> {
/// let mut app = App::new("myprog");
/// app.print_help();
/// ```
/// [`io::stdout()`]: https://doc.rust-lang.org/std/io/fn.stdout.html
/// [`BufWriter`]: https://doc.rust-lang.org/std/io/struct.BufWriter.html
/// [`-h` (short)]: ./struct.Arg.html#method.about
/// [`--help` (long)]: ./struct.Arg.html#method.long_about
/// [`io::stdout()`]: std::io::stdout()
/// [`BufWriter`]: std::io::BufWriter
/// [`-h` (short)]: Arg::about()
/// [`--help` (long)]: Arg::long_about()
pub fn print_help(&mut self) -> io::Result<()> {
self._build();
@ -1802,10 +1784,10 @@ impl<'help> App<'help> {
/// let mut app = App::new("myprog");
/// app.print_long_help();
/// ```
/// [`io::stdout()`]: https://doc.rust-lang.org/std/io/fn.stdout.html
/// [`BufWriter`]: https://doc.rust-lang.org/std/io/struct.BufWriter.html
/// [`-h` (short)]: ./struct.Arg.html#method.about
/// [`--help` (long)]: ./struct.Arg.html#method.long_about
/// [`io::stdout()`]: std::io::stdout()
/// [`BufWriter`]: std::io::BufWriter
/// [`-h` (short)]: Arg::about()
/// [`--help` (long)]: Arg::long_about()
pub fn print_long_help(&mut self) -> io::Result<()> {
self._build();
@ -1830,9 +1812,9 @@ impl<'help> App<'help> {
/// let mut out = io::stdout();
/// app.write_help(&mut out).expect("failed to write to stdout");
/// ```
/// [`io::Write`]: https://doc.rust-lang.org/std/io/trait.Write.html
/// [`-h` (short)]: ./struct.Arg.html#method.about
/// [`--help` (long)]: ./struct.Arg.html#method.long_about
/// [`io::Write`]: std::io::Write
/// [`-h` (short)]: Arg::about()
/// [`--help` (long)]: Arg::long_about()
pub fn write_help<W: Write>(&mut self, w: &mut W) -> io::Result<()> {
self._build();
@ -1856,9 +1838,9 @@ impl<'help> App<'help> {
/// let mut out = io::stdout();
/// app.write_long_help(&mut out).expect("failed to write to stdout");
/// ```
/// [`io::Write`]: https://doc.rust-lang.org/std/io/trait.Write.html
/// [`-h` (short)]: ./struct.Arg.html#method.about
/// [`--help` (long)]: ./struct.Arg.html#method.long_about
/// [`io::Write`]: std::io::Write
/// [`-h` (short)]: Arg::about()
/// [`--help` (long)]: Arg::long_about()
pub fn write_long_help<W: Write>(&mut self, w: &mut W) -> io::Result<()> {
self._build();
@ -1884,9 +1866,9 @@ impl<'help> App<'help> {
/// let app = App::new("myprog");
/// println!("{}", app.render_version());
/// ```
/// [`io::Write`]: https://doc.rust-lang.org/std/io/trait.Write.html
/// [`-V` (short)]: ./struct.App.html#method.version
/// [`--version` (long)]: ./struct.App.html#method.long_version
/// [`io::Write`]: std::io::Write
/// [`-V` (short)]: App::version()
/// [`--version` (long)]: App::long_version()
/// [ANSI escape codes]: https://en.wikipedia.org/wiki/ANSI_escape_code
pub fn render_version(&self) -> String {
self._render_version(false)
@ -1909,9 +1891,9 @@ impl<'help> App<'help> {
/// let app = App::new("myprog");
/// println!("{}", app.render_long_version());
/// ```
/// [`io::Write`]: https://doc.rust-lang.org/std/io/trait.Write.html
/// [`-V` (short)]: ./struct.App.html#method.version
/// [`--version` (long)]: ./struct.App.html#method.long_version
/// [`io::Write`]: std::io::Write
/// [`-V` (short)]: App::version()
/// [`--version` (long)]: App::long_version()
/// [ANSI escape codes]: https://en.wikipedia.org/wiki/ANSI_escape_code
pub fn render_long_version(&self) -> String {
self._render_version(true)
@ -1941,7 +1923,7 @@ impl<'help> App<'help> {
/// // Args and options go here...
/// .get_matches();
/// ```
/// [`env::args_os`]: https://doc.rust-lang.org/std/env/fn.args_os.html
/// [`env::args_os`]: std::env::args_os()
#[inline]
pub fn get_matches(self) -> ArgMatches {
self.get_matches_from(&mut env::args_os())
@ -1958,8 +1940,8 @@ impl<'help> App<'help> {
/// ;
/// let matches = app.get_matches_mut();
/// ```
/// [`env::args_os`]: https://doc.rust-lang.org/std/env/fn.args_os.html
/// [`App::get_matches`]: ./struct.App.html#method.get_matches
/// [`env::args_os`]: std::env::args_os()
/// [`App::get_matches`]: App::get_matches()
pub fn get_matches_mut(&mut self) -> ArgMatches {
self.try_get_matches_from_mut(&mut env::args_os())
.unwrap_or_else(|e| {
@ -1999,14 +1981,12 @@ impl<'help> App<'help> {
/// .try_get_matches()
/// .unwrap_or_else(|e| e.exit());
/// ```
/// [`env::args_os`]: https://doc.rust-lang.org/std/env/fn.args_os.html
/// [`ErrorKind::DisplayHelp`]: ./enum.ErrorKind.html#variant.DisplayHelp
/// [`ErrorKind::DisplayVersion`]: ./enum.ErrorKind.html#variant.DisplayVersion
/// [`Error::exit`]: ./struct.Error.html#method.exit
/// [`std::process::exit`]: https://doc.rust-lang.org/std/process/fn.exit.html
/// [`clap::Result`]: ./type.Result.html
/// [`clap::Error`]: ./struct.Error.html
/// [`kind`]: ./struct.Error.html
/// [`env::args_os`]: std::env::args_os()
/// [`Error::exit`]: Error::exit()
/// [`std::process::exit`]: std::process::exit()
/// [`clap::Result`]: Result
/// [`clap::Error`]: Error
/// [`kind`]: Error
#[inline]
pub fn try_get_matches(self) -> ClapResult<ArgMatches> {
// Start the parsing
@ -2030,10 +2010,9 @@ impl<'help> App<'help> {
/// // Args and options go here...
/// .get_matches_from(arg_vec);
/// ```
/// [`App::get_matches`]: ./struct.App.html#method.get_matches
/// [`clap::Result`]: ./type.Result.html
/// [`Vec`]: https://doc.rust-lang.org/std/vec/struct.Vec.html
/// [`AppSettings::NoBinaryName`]: ./enum.AppSettings.html#variant.NoBinaryName
/// [`App::get_matches`]: App::get_matches()
/// [`clap::Result`]: Result
/// [`Vec`]: std::vec::Vec
pub fn get_matches_from<I, T>(mut self, itr: I) -> ArgMatches
where
I: IntoIterator<Item = T>,
@ -2083,16 +2062,13 @@ impl<'help> App<'help> {
/// .try_get_matches_from(arg_vec)
/// .unwrap_or_else(|e| e.exit());
/// ```
/// [`App::get_matches_from`]: ./struct.App.html#method.get_matches_from
/// [`App::try_get_matches`]: ./struct.App.html#method.try_get_matches
/// [`ErrorKind::DisplayHelp`]: ./enum.ErrorKind.html#variant.DisplayHelp
/// [`ErrorKind::DisplayVersion`]: ./enum.ErrorKind.html#variant.DisplayVersion
/// [`Error::exit`]: ./struct.Error.html#method.exit
/// [`std::process::exit`]: https://doc.rust-lang.org/std/process/fn.exit.html
/// [`clap::Error`]: ./struct.Error.html
/// [`Error::exit`]: ./struct.Error.html#method.exit
/// [`kind`]: ./struct.Error.html
/// [`AppSettings::NoBinaryName`]: ./enum.AppSettings.html#variant.NoBinaryName
/// [`App::get_matches_from`]: App::get_matches_from()
/// [`App::try_get_matches`]: App::try_get_matches()
/// [`Error::exit`]: Error::exit()
/// [`std::process::exit`]: std::process::exit()
/// [`clap::Error`]: Error
/// [`Error::exit`]: Error::exit()
/// [`kind`]: Error
pub fn try_get_matches_from<I, T>(mut self, itr: I) -> ClapResult<ArgMatches>
where
I: IntoIterator<Item = T>,
@ -2119,9 +2095,7 @@ impl<'help> App<'help> {
/// let matches = app.try_get_matches_from_mut(arg_vec)
/// .unwrap_or_else(|e| e.exit());
/// ```
/// [`App`]: ./struct.App.html
/// [`App::try_get_matches_from`]: ./struct.App.html#method.try_get_matches_from
/// [`AppSettings::NoBinaryName`]: ./enum.AppSettings.html#variant.NoBinaryName
/// [`App::try_get_matches_from`]: App::try_get_matches_from()
pub fn try_get_matches_from_mut<I, T>(&mut self, itr: I) -> ClapResult<ArgMatches>
where
I: IntoIterator<Item = T>,

42
src/build/app/settings.rs
View file

@ -155,7 +155,6 @@ impl_settings! { AppSettings, AppFlags,
/// **NOTE:** When these settings are used, they apply only to current command, and are *not*
/// propagated down or up through child or parent subcommands
///
/// [`App`]: ./struct.App.html
#[derive(Debug, PartialEq, Copy, Clone)]
pub enum AppSettings {
/// Specifies that any invalid UTF-8 code points should *not* be treated as an error.
@ -193,10 +192,10 @@ pub enum AppSettings {
/// let m = r.unwrap();
/// assert_eq!(m.value_of_os("arg").unwrap().as_bytes(), &[0xe9]);
/// ```
/// [`ArgMatches::os_value_of`]: ./struct.ArgMatches.html#method.os_value_of
/// [`ArgMatches::os_values_of`]: ./struct.ArgMatches.html#method.os_values_of
/// [`ArgMatches::lossy_value_of`]: ./struct.ArgMatches.html#method.lossy_value_of
/// [`ArgMatches::lossy_values_of`]: ./struct.ArgMatches.html#method.lossy_values_of
/// [`ArgMatches::os_value_of`]: ArgMatches::os_value_of()
/// [`ArgMatches::os_values_of`]: ArgMatches::os_values_of()
/// [`ArgMatches::lossy_value_of`]: ArgMatches::lossy_value_of()
/// [`ArgMatches::lossy_values_of`]: ArgMatches::lossy_values_of()
/// [``]: ./struct..html
AllowInvalidUtf8,
@ -222,13 +221,13 @@ pub enum AppSettings {
/// assert_eq!(m.value_of("neg"), Some("-20"));
/// # ;
/// ```
/// [`Arg::allow_hyphen_values`]: ./struct.Arg.html#method.allow_hyphen_values
/// [`Arg::allow_hyphen_values`]: Arg::allow_hyphen_values()
AllowLeadingHyphen,
/// Specifies that all arguments override themselves. This is the equivalent to saying the `foo`
/// arg using [`Arg::overrides_with("foo")`] for all defined arguments.
///
/// [`Arg::overrides_with("foo")`]: ./struct.Arg.html#method.overrides_with
/// [`Arg::overrides_with("foo")`]: Arg::overrides_with()
AllArgsOverrideSelf,
/// Allows negative numbers to pass as values. This is similar to
@ -250,7 +249,7 @@ pub enum AppSettings {
/// let m = res.unwrap();
/// assert_eq!(m.value_of("num").unwrap(), "-20");
/// ```
/// [`AllowLeadingHyphen`]: ./enum.AppSettings.html#variant.AllowLeadingHyphen
/// [`AllowLeadingHyphen`]: AppSettings::AllowLeadingHyphen
AllowNegativeNumbers,
/// Allows one to implement two styles of CLIs where positionals can be used out of order.
@ -357,7 +356,7 @@ pub enum AppSettings {
/// assert_eq!(m.value_of("bar"), None);
/// assert_eq!(m.values_of("baz").unwrap().collect::<Vec<_>>(), &["baz1", "baz2", "baz3"]);
/// ```
/// [required]: ./struct.Arg.html#method.required
/// [required]: Arg::required()
AllowMissingPositional,
/// Specifies that an unexpected positional argument,
@ -391,9 +390,7 @@ pub enum AppSettings {
/// _ => {},
/// }
/// ```
/// [`ErrorKind::UnknownArgument`]: ./enum.ErrorKind.html#variant.UnknownArgument
/// [``]: ./struct..html
/// [`ArgMatches`]: ./struct.ArgMatches.html
AllowExternalSubcommands,
/// Specifies that use of a valid [argument] negates [subcomands] being used after. By default
@ -415,7 +412,7 @@ pub enum AppSettings {
/// # ;
/// ```
/// [subcommands]: ./struct..html
/// [argument]: ./struct.Arg.html
/// [argument]: Arg
ArgsNegateSubcommands,
/// Specifies that the help text should be displayed (and then exit gracefully),
@ -435,7 +432,7 @@ pub enum AppSettings {
/// # ;
/// ```
/// [``]: ./struct..html
/// [`Arg::default_value`]: ./struct.Arg.html#method.default_value
/// [`Arg::default_value`]: Arg::default_value()
ArgRequiredElseHelp,
/// Instructs the parser to stop when encountering a subcommand instead of greedily consuming
@ -596,8 +593,7 @@ pub enum AppSettings {
/// .setting(AppSettings::DontDelimitTrailingValues)
/// .get_matches();
/// ```
/// [`AppSettings::TrailingVarArg`]: ./enum.AppSettings.html#variant.TrailingVarArg
/// [`Arg::use_delimiter(false)`]: ./struct.Arg.html#method.use_delimiter
/// [`Arg::use_delimiter(false)`]: Arg::use_delimiter()
DontDelimitTrailingValues,
/// Disables `-h` and `--help` [`App`] without affecting any of the [`SubCommand`]s
@ -627,8 +623,6 @@ pub enum AppSettings {
/// assert!(res.is_err());
/// assert_eq!(res.unwrap_err().kind, ErrorKind::DisplayHelp);
/// ```
/// [`SubCommand`]: ./struct.SubCommand.html
/// [`App`]: ./struct.App.html
DisableHelpFlag,
/// Disables the `help` subcommand
@ -682,7 +676,6 @@ pub enum AppSettings {
/// assert_eq!(res.unwrap_err().kind, ErrorKind::DisplayVersion);
/// ```
/// [``]: ./struct..html
/// [`App`]: ./struct.App.html
DisableVersionFlag,
/// Disables `-V` and `--version` for all [`subcommand`]s of this [`App`]
@ -702,7 +695,6 @@ pub enum AppSettings {
/// assert!(res.is_err());
/// assert_eq!(res.unwrap_err().kind, ErrorKind::UnknownArgument);
/// ```
/// [`App`]: ./struct.App.html
/// [``]: ./struct..html
DisableVersionForSubcommands,
@ -812,9 +804,8 @@ pub enum AppSettings {
/// assert_eq!(m.subcommand_name(), Some("test"));
/// ```
/// [`subcommands`]: ./struct..html
/// [positional/free arguments]: ./struct.Arg.html#method.index
/// [aliases]: ./struct.App.html#method.alias
/// [`AppSettings::ArgsNegateSubcommands`]: ./enum.AppSettings.html#variant.ArgsNegateSubcommands
/// [positional/free arguments]: Arg::index()
/// [aliases]: App::alias()
InferSubcommands,
/// Specifies that the parser should not assume the first argument passed is the binary name.
@ -888,7 +879,7 @@ pub enum AppSettings {
/// assert!(noerr.is_ok());
/// # ;
/// ```
/// [`Arg::required(true)`]: ./struct.Arg.html#method.required
/// [`Arg::required(true)`]: Arg::required()
/// [``]: ./struct..html
SubcommandsNegateReqs,
@ -911,8 +902,6 @@ pub enum AppSettings {
/// # ;
/// ```
/// [``]: ./struct..html
/// [`AppSettings::SubcommandRequired`]: ./enum.AppSettings.html#variant.SubcommandRequired
/// [`AppSettings::ArgRequiredElseHelp`]: ./enum.AppSettings.html#variant.ArgRequiredElseHelp
SubcommandRequiredElseHelp,
/// Specifies that any invalid UTF-8 code points should be treated as an error and fail
@ -945,7 +934,6 @@ pub enum AppSettings {
/// assert_eq!(m.unwrap_err().kind, ErrorKind::InvalidUtf8);
/// ```
/// [``]: ./struct..html
/// [`ErrorKind::InvalidUtf8`]: ./enum.ErrorKind.html#variant.InvalidUtf8
StrictUtf8,
/// Allows specifying that if no [``] is present at runtime,
@ -990,7 +978,7 @@ pub enum AppSettings {
/// let trail: Vec<&str> = m.values_of("cmd").unwrap().collect();
/// assert_eq!(trail, ["arg1", "-r", "val1"]);
/// ```
/// [`Arg::multiple(true)`]: ./struct.Arg.html#method.multiple
/// [`Arg::multiple(true)`]: Arg::multiple()
TrailingVarArg,
/// Groups flags and options together, presenting a more unified help message

330
src/build/arg/mod.rs
View file

@ -78,7 +78,6 @@ impl Default for ArgProvider {
/// // Using a usage string (setting a similar argument to the one above)
/// let input = Arg::from("-i, --input=[FILE] 'Provides an input file to the program'");
/// ```
/// [`Arg`]: ./struct.Arg.html
#[allow(missing_debug_implementations)]
#[derive(Default, Clone)]
pub struct Arg<'help> {
@ -296,8 +295,7 @@ impl<'help> Arg<'help> {
/// Arg::new("config")
/// # ;
/// ```
/// [`Arg::takes_value(true)`]: ./struct.Arg.html#method.takes_value
/// [`Arg`]: ./struct.Arg.html
/// [`Arg::takes_value(true)`]: Arg::takes_value()
pub fn new<S: Into<&'help str>>(n: S) -> Self {
let name = n.into();
Arg {
@ -346,7 +344,7 @@ impl<'help> Arg<'help> {
///
/// assert!(m.is_present("config"));
/// ```
/// [`short`]: ./struct.Arg.html#method.short
/// [`short`]: Arg::short()
#[inline]
pub fn short(mut self, s: char) -> Self {
if s == '-' {
@ -418,7 +416,6 @@ impl<'help> Arg<'help> {
/// assert!(m.is_present("test"));
/// assert_eq!(m.value_of("test"), Some("cool"));
/// ```
/// [`Arg`]: ./struct.Arg.html
pub fn alias<S: Into<&'help str>>(mut self, name: S) -> Self {
self.aliases.push((name.into(), false));
self
@ -444,7 +441,6 @@ impl<'help> Arg<'help> {
/// assert!(m.is_present("test"));
/// assert_eq!(m.value_of("test"), Some("cool"));
/// ```
/// [`Arg`]: ./struct.Arg.html
pub fn short_alias(mut self, name: char) -> Self {
if name == '-' {
panic!("short alias name cannot be `-`");
@ -474,7 +470,6 @@ impl<'help> Arg<'help> {
/// ]);
/// assert!(m.is_present("test"));
/// ```
/// [`Arg`]: ./struct.Arg.html
pub fn aliases(mut self, names: &[&'help str]) -> Self {
self.aliases.extend(names.iter().map(|&x| (x, false)));
self
@ -500,7 +495,6 @@ impl<'help> Arg<'help> {
/// ]);
/// assert!(m.is_present("test"));
/// ```
/// [`Arg`]: ./struct.Arg.html
pub fn short_aliases(mut self, names: &[char]) -> Self {
for s in names {
if s == &'-' {
@ -529,8 +523,7 @@ impl<'help> Arg<'help> {
/// assert!(m.is_present("test"));
/// assert_eq!(m.value_of("test"), Some("coffee"));
/// ```
/// [`Arg`]: ./struct.Arg.html
/// [`App::alias`]: ./struct.Arg.html#method.alias
/// [`App::alias`]: Arg::alias()
pub fn visible_alias<S: Into<&'help str>>(mut self, name: S) -> Self {
self.aliases.push((name.into(), true));
self
@ -554,8 +547,7 @@ impl<'help> Arg<'help> {
/// assert!(m.is_present("test"));
/// assert_eq!(m.value_of("test"), Some("coffee"));
/// ```
/// [`Arg`]: ./struct.Arg.html
/// [`App::alias`]: ./struct.Arg.html#method.short_alias
/// [`App::alias`]: Arg::short_alias()
pub fn visible_short_alias(mut self, name: char) -> Self {
if name == '-' {
panic!("short alias name cannot be `-`");
@ -581,8 +573,7 @@ impl<'help> Arg<'help> {
/// ]);
/// assert!(m.is_present("test"));
/// ```
/// [`Arg`]: ./struct.Arg.html
/// [`App::aliases`]: ./struct.Arg.html#method.aliases
/// [`App::aliases`]: Arg::aliases()
pub fn visible_aliases(mut self, names: &[&'help str]) -> Self {
self.aliases.extend(names.iter().map(|n| (*n, true)));
self
@ -604,8 +595,7 @@ impl<'help> Arg<'help> {
/// ]);
/// assert!(m.is_present("test"));
/// ```
/// [`Arg`]: ./struct.Arg.html
/// [`App::aliases`]: ./struct.Arg.html#method.short_aliases
/// [`App::aliases`]: Arg::short_aliases()
pub fn visible_short_aliases(mut self, names: &[char]) -> Self {
for n in names {
if n == &'-' {
@ -665,7 +655,7 @@ impl<'help> Arg<'help> {
/// -h, --help Prints help information
/// -V, --version Prints version information
/// ```
/// [`Arg::long_about`]: ./struct.Arg.html#method.long_about
/// [`Arg::long_about`]: Arg::long_about()
#[inline]
pub fn about(mut self, h: &'help str) -> Self {
self.about = Some(h);
@ -737,7 +727,7 @@ impl<'help> Arg<'help> {
/// -V, --version
/// Prints version information
/// ```
/// [`Arg::about`]: ./struct.Arg.html#method.about
/// [`Arg::about`]: Arg::about()
#[inline]
pub fn long_about(mut self, h: &'help str) -> Self {
self.long_about = Some(h);
@ -795,7 +785,7 @@ impl<'help> Arg<'help> {
/// assert!(res.is_err());
/// assert_eq!(res.unwrap_err().kind, ErrorKind::MissingRequiredArgument);
/// ```
/// [required]: ./struct.Arg.html#method.required
/// [required]: Arg::required()
pub fn required_unless_present<T: Key>(mut self, arg_id: T) -> Self {
self.r_unless.push(arg_id.into());
self
@ -863,9 +853,9 @@ impl<'help> Arg<'help> {
/// assert!(res.is_err());
/// assert_eq!(res.unwrap_err().kind, ErrorKind::MissingRequiredArgument);
/// ```
/// [required]: ./struct.Arg.html#method.required
/// [`Arg::required_unless_present_any`]: ./struct.Arg.html#method.required_unless_present_any
/// [`Arg::required_unless_present_all(names)`]: ./struct.Arg.html#method.required_unless_present_all
/// [required]: Arg::required()
/// [`Arg::required_unless_present_any`]: Arg::required_unless_present_any()
/// [`Arg::required_unless_present_all(names)`]: Arg::required_unless_present_all()
pub fn required_unless_present_all<T, I>(mut self, names: I) -> Self
where
I: IntoIterator<Item = T>,
@ -939,9 +929,9 @@ impl<'help> Arg<'help> {
/// assert!(res.is_err());
/// assert_eq!(res.unwrap_err().kind, ErrorKind::MissingRequiredArgument);
/// ```
/// [required]: ./struct.Arg.html#method.required
/// [`Arg::required_unless_present_any(names)`]: ./struct.Arg.html#method.required_unless_present_any
/// [`Arg::required_unless_present_all`]: ./struct.Arg.html#method.required_unless_present_all
/// [required]: Arg::required()
/// [`Arg::required_unless_present_any(names)`]: Arg::required_unless_present_any()
/// [`Arg::required_unless_present_all`]: Arg::required_unless_present_all()
pub fn required_unless_present_any<T, I>(mut self, names: I) -> Self
where
I: IntoIterator<Item = T>,
@ -993,8 +983,8 @@ impl<'help> Arg<'help> {
/// assert_eq!(res.unwrap_err().kind, ErrorKind::ArgumentConflict);
/// ```
///
/// [`Arg::conflicts_with_all(names)`]: ./struct.Arg.html#method.conflicts_with_all
/// [`Arg::exclusive(true)`]: ./struct.Arg.html#method.exclusive
/// [`Arg::conflicts_with_all(names)`]: Arg::conflicts_with_all()
/// [`Arg::exclusive(true)`]: Arg::exclusive()
pub fn conflicts_with<T: Key>(mut self, arg_id: T) -> Self {
self.blacklist.push(arg_id.into());
self
@ -1045,8 +1035,8 @@ impl<'help> Arg<'help> {
/// assert!(res.is_err());
/// assert_eq!(res.unwrap_err().kind, ErrorKind::ArgumentConflict);
/// ```
/// [`Arg::conflicts_with`]: ./struct.Arg.html#method.conflicts_with
/// [`Arg::exclusive(true)`]: ./struct.Arg.html#method.exclusive
/// [`Arg::conflicts_with`]: Arg::conflicts_with()
/// [`Arg::exclusive(true)`]: Arg::exclusive()
pub fn conflicts_with_all(mut self, names: &[&str]) -> Self {
self.blacklist.extend(names.iter().map(Id::from));
self
@ -1197,8 +1187,8 @@ impl<'help> Arg<'help> {
/// assert_eq!(m.occurrences_of("opt"), 1);
/// assert_eq!(m.values_of("opt").unwrap().collect::<Vec<_>>(), &["one,two"]);
/// ```
/// [`Multiple*`]: ./enum.ArgSettings.html#variant.MultipleValues
/// [`UseValueDelimiter`]: ./enum.ArgSettings.html#variant.UseValueDelimiter
/// [`Multiple*`]: ArgSettings::MultipleValues
/// [`UseValueDelimiter`]: ArgSettings::UseValueDelimiter
pub fn overrides_with<T: Key>(mut self, arg_id: T) -> Self {
self.overrides.push(arg_id.into());
self
@ -1288,9 +1278,9 @@ impl<'help> Arg<'help> {
/// assert!(res.is_err());
/// assert_eq!(res.unwrap_err().kind, ErrorKind::MissingRequiredArgument);
/// ```
/// [`Arg::requires(name)`]: ./struct.Arg.html#method.requires
/// [Conflicting]: ./struct.Arg.html#method.conflicts_with
/// [override]: ./struct.Arg.html#method.overrides_with
/// [`Arg::requires(name)`]: Arg::requires()
/// [Conflicting]: Arg::conflicts_with()
/// [override]: Arg::overrides_with()
pub fn requires<T: Key>(mut self, arg_id: T) -> Self {
self.requires.push((None, arg_id.into()));
self
@ -1355,9 +1345,9 @@ impl<'help> Arg<'help> {
/// assert!(res.is_err());
/// assert_eq!(res.unwrap_err().kind, ErrorKind::MissingRequiredArgument);
/// ```
/// [`Arg::requires(name)`]: ./struct.Arg.html#method.requires
/// [Conflicting]: ./struct.Arg.html#method.conflicts_with
/// [override]: ./struct.Arg.html#method.overrides_with
/// [`Arg::requires(name)`]: Arg::requires()
/// [Conflicting]: Arg::conflicts_with()
/// [override]: Arg::overrides_with()
pub fn requires_if<T: Key>(mut self, val: &'help str, arg_id: T) -> Self {
self.requires.push((Some(val), arg_id.into()));
self
@ -1411,9 +1401,9 @@ impl<'help> Arg<'help> {
/// assert!(res.is_err()); // We used --config=special.conf so --option <val> is required
/// assert_eq!(res.unwrap_err().kind, ErrorKind::MissingRequiredArgument);
/// ```
/// [`Arg::requires(name)`]: ./struct.Arg.html#method.requires
/// [Conflicting]: ./struct.Arg.html#method.conflicts_with
/// [override]: ./struct.Arg.html#method.overrides_with
/// [`Arg::requires(name)`]: Arg::requires()
/// [Conflicting]: Arg::conflicts_with()
/// [override]: Arg::overrides_with()
pub fn requires_ifs<T: Key>(mut self, ifs: &[(&'help str, T)]) -> Self {
self.requires
.extend(ifs.iter().map(|(val, arg)| (Some(*val), Id::from(arg))));
@ -1471,9 +1461,9 @@ impl<'help> Arg<'help> {
/// assert!(res.is_err());
/// assert_eq!(res.unwrap_err().kind, ErrorKind::MissingRequiredArgument);
/// ```
/// [`Arg::requires(name)`]: ./struct.Arg.html#method.requires
/// [Conflicting]: ./struct.Arg.html#method.conflicts_with
/// [required]: ./struct.Arg.html#method.required
/// [`Arg::requires(name)`]: Arg::requires()
/// [Conflicting]: Arg::conflicts_with()
/// [required]: Arg::required()
pub fn required_if_eq<T: Key>(mut self, arg_id: T, val: &'help str) -> Self {
self.r_ifs.push((arg_id.into(), val));
self
@ -1556,9 +1546,9 @@ impl<'help> Arg<'help> {
/// assert!(res.is_err());
/// assert_eq!(res.unwrap_err().kind, ErrorKind::MissingRequiredArgument);
/// ```
/// [`Arg::requires(name)`]: ./struct.Arg.html#method.requires
/// [Conflicting]: ./struct.Arg.html#method.conflicts_with
/// [required]: ./struct.Arg.html#method.required
/// [`Arg::requires(name)`]: Arg::requires()
/// [Conflicting]: Arg::conflicts_with()
/// [required]: Arg::required()
pub fn required_if_eq_any<T: Key>(mut self, ifs: &[(T, &'help str)]) -> Self {
self.r_ifs
.extend(ifs.iter().map(|(id, val)| (Id::from_ref(id), *val)));
@ -1642,7 +1632,7 @@ impl<'help> Arg<'help> {
/// assert!(res.is_err());
/// assert_eq!(res.unwrap_err().kind, ErrorKind::MissingRequiredArgument);
/// ```
/// [required]: ./struct.Arg.html#method.required
/// [required]: Arg::required()
pub fn required_if_eq_all<T: Key>(mut self, ifs: &[(T, &'help str)]) -> Self {
self.r_ifs_all
.extend(ifs.iter().map(|(id, val)| (Id::from_ref(id), *val)));
@ -1708,8 +1698,8 @@ impl<'help> Arg<'help> {
/// // We didn't use output
/// assert_eq!(res.unwrap_err().kind, ErrorKind::MissingRequiredArgument);
/// ```
/// [Conflicting]: ./struct.Arg.html#method.conflicts_with
/// [override]: ./struct.Arg.html#method.overrides_with
/// [Conflicting]: Arg::conflicts_with()
/// [override]: Arg::overrides_with()
pub fn requires_all<T: Key>(mut self, names: &[T]) -> Self {
self.requires.extend(names.iter().map(|s| (None, s.into())));
self
@ -1760,10 +1750,9 @@ impl<'help> Arg<'help> {
/// assert_eq!(m.value_of("mode"), Some("fast")); // notice index(1) means "first positional"
/// // *not* first argument
/// ```
/// [`Arg::short`]: ./struct.Arg.html#method.short
/// [`Arg::long`]: ./struct.Arg.html#method.long
/// [`Arg::multiple(true)`]: ./struct.Arg.html#method.multiple
/// [`App`]: ./struct.App.html
/// [`Arg::short`]: Arg::short()
/// [`Arg::long`]: Arg::long()
/// [`Arg::multiple(true)`]: Arg::multiple()
/// [`panic!`]: https://doc.rust-lang.org/std/macro.panic!.html
#[inline]
pub fn index(mut self, idx: usize) -> Self {
@ -1811,12 +1800,12 @@ impl<'help> Arg<'help> {
/// assert_eq!(&cmds, &["find", "-type", "f", "-name", "special"]);
/// assert_eq!(m.value_of("location"), Some("/home/clap"));
/// ```
/// [options]: ./struct.Arg.html#method.takes_value
/// [positional arguments]: ./struct.Arg.html#method.index
/// [`multiple(true)`]: ./struct.Arg.html#method.multiple
/// [`min_values`]: ./struct.Arg.html#method.min_values
/// [`number_of_values`]: ./struct.Arg.html#method.number_of_values
/// [`max_values`]: ./struct.Arg.html#method.max_values
/// [options]: Arg::takes_value()
/// [positional arguments]: Arg::index()
/// [`multiple(true)`]: Arg::multiple()
/// [`min_values`]: Arg::min_values()
/// [`number_of_values`]: Arg::number_of_values()
/// [`max_values`]: Arg::max_values()
#[inline]
pub fn value_terminator(mut self, term: &'help str) -> Self {
self.terminator = Some(term);
@ -1868,8 +1857,8 @@ impl<'help> Arg<'help> {
/// assert!(res.is_err());
/// assert_eq!(res.unwrap_err().kind, ErrorKind::InvalidValue);
/// ```
/// [options]: ./struct.Arg.html#method.takes_value
/// [positional arguments]: ./struct.Arg.html#method.index
/// [options]: Arg::takes_value()
/// [positional arguments]: Arg::index()
pub fn possible_values(mut self, names: &[&'help str]) -> Self {
self.possible_vals.extend(names);
self.takes_value(true)
@ -1926,8 +1915,8 @@ impl<'help> Arg<'help> {
/// assert!(res.is_err());
/// assert_eq!(res.unwrap_err().kind, ErrorKind::InvalidValue);
/// ```
/// [options]: ./struct.Arg.html#method.takes_value
/// [positional arguments]: ./struct.Arg.html#method.index
/// [options]: Arg::takes_value()
/// [positional arguments]: Arg::index()
pub fn possible_value(mut self, name: &'help str) -> Self {
self.possible_vals.push(name);
self.takes_value(true)
@ -1962,7 +1951,6 @@ impl<'help> Arg<'help> {
/// ]);
/// assert!(m.is_present("mode"));
/// ```
/// [`ArgGroup`]: ./struct.ArgGroup.html
pub fn group<T: Key>(mut self, group_id: T) -> Self {
self.groups.push(group_id.into());
self
@ -1998,7 +1986,6 @@ impl<'help> Arg<'help> {
/// assert!(m.is_present("mode"));
/// assert!(m.is_present("verbosity"));
/// ```
/// [`ArgGroup`]: ./struct.ArgGroup.html
pub fn groups<T: Key>(mut self, group_ids: &[T]) -> Self {
self.groups.extend(group_ids.iter().map(Id::from));
self
@ -2039,7 +2026,7 @@ impl<'help> Arg<'help> {
/// assert!(res.is_err());
/// assert_eq!(res.unwrap_err().kind, ErrorKind::WrongNumberOfValues);
/// ```
/// [`Arg::multiple(true)`]: ./struct.Arg.html#method.multiple
/// [`Arg::multiple(true)`]: Arg::multiple()
#[inline]
pub fn number_of_values(mut self, qty: usize) -> Self {
self.num_vals = Some(qty);
@ -2078,10 +2065,10 @@ impl<'help> Arg<'help> {
/// assert!(res.is_ok());
/// assert_eq!(res.unwrap().value_of("file"), Some("some@file"));
/// ```
/// [`String`]: https://doc.rust-lang.org/std/string/struct.String.html
/// [`Result`]: https://doc.rust-lang.org/std/result/enum.Result.html
/// [`Err(String)`]: https://doc.rust-lang.org/std/result/enum.Result.html#variant.Err
/// [`Arc`]: https://doc.rust-lang.org/std/sync/struct.Arc.html
/// [`String`]: std::string::String
/// [`Result`]: std::result::Result
/// [`Err(String)`]: std::result::Result::Err
/// [`Arc`]: std::sync::Arc
pub fn validator<F, O, E>(mut self, mut f: F) -> Self
where
F: FnMut(&str) -> Result<O, E> + Send + 'help,
@ -2117,12 +2104,12 @@ impl<'help> Arg<'help> {
/// assert!(res.is_ok());
/// assert_eq!(res.unwrap().value_of("file"), Some("Fish & chips"));
/// ```
/// [`String`]: https://doc.rust-lang.org/std/string/struct.String.html
/// [`OsStr`]: https://doc.rust-lang.org/std/ffi/struct.OsStr.html
/// [`OsString`]: https://doc.rust-lang.org/std/ffi/struct.OsString.html
/// [`Result`]: https://doc.rust-lang.org/std/result/enum.Result.html
/// [`Err(String)`]: https://doc.rust-lang.org/std/result/enum.Result.html#variant.Err
/// [`Rc`]: https://doc.rust-lang.org/std/rc/struct.Rc.html
/// [`String`]: std::string::String
/// [`OsStr`]: std::ffi::OsStr
/// [`OsString`]: std::ffi::OsString
/// [`Result`]: std::result::Result
/// [`Err(String)`]: std::result::Result::Err
/// [`Rc`]: std::rc::Rc
pub fn validator_os<F, O, E>(mut self, mut f: F) -> Self
where
F: FnMut(&OsStr) -> Result<O, E> + Send + 'help,
@ -2188,8 +2175,6 @@ impl<'help> Arg<'help> {
/// assert!(res.is_err());
/// assert_eq!(res.err().unwrap().kind, ErrorKind::ValueValidation)
/// ```
/// [`Arg::validator()`]: ./struct.Arg.html#method.validator
/// [`RegexRef`]: ./struct.RegexRef.html
#[cfg(feature = "regex")]
pub fn validator_regex(
self,
@ -2261,7 +2246,7 @@ impl<'help> Arg<'help> {
/// assert!(res.is_err());
/// assert_eq!(res.unwrap_err().kind, ErrorKind::UnknownArgument);
/// ```
/// [`Arg::multiple(true)`]: ./struct.Arg.html#method.multiple
/// [`Arg::multiple(true)`]: Arg::multiple()
#[inline]
pub fn max_values(mut self, qty: usize) -> Self {
self.max_vals = Some(qty);
@ -2324,7 +2309,7 @@ impl<'help> Arg<'help> {
/// assert!(res.is_err());
/// assert_eq!(res.unwrap_err().kind, ErrorKind::TooFewValues);
/// ```
/// [`Arg::multiple(true)`]: ./struct.Arg.html#method.multiple
/// [`Arg::multiple(true)`]: Arg::multiple()
#[inline]
pub fn min_values(mut self, qty: usize) -> Self {
self.min_vals = Some(qty);
@ -2352,8 +2337,8 @@ impl<'help> Arg<'help> {
///
/// assert_eq!(m.values_of("config").unwrap().collect::<Vec<_>>(), ["val1", "val2", "val3"])
/// ```
/// [`Arg::use_delimiter(true)`]: ./struct.Arg.html#method.use_delimiter
/// [`Arg::takes_value(true)`]: ./struct.Arg.html#method.takes_value
/// [`Arg::use_delimiter(true)`]: Arg::use_delimiter()
/// [`Arg::takes_value(true)`]: Arg::takes_value()
#[inline]
pub fn value_delimiter(mut self, d: &str) -> Self {
self.val_delim = Some(
@ -2419,10 +2404,10 @@ impl<'help> Arg<'help> {
/// OPTIONS:
/// --io-files <INFILE> <OUTFILE> Some help text
/// ```
/// [`Arg::next_line_help(true)`]: ./struct.Arg.html#method.next_line_help
/// [`Arg::number_of_values`]: ./struct.Arg.html#method.number_of_values
/// [`Arg::takes_value(true)`]: ./struct.Arg.html#method.takes_value
/// [`Arg::multiple(true)`]: ./struct.Arg.html#method.multiple
/// [`Arg::next_line_help(true)`]: Arg::next_line_help()
/// [`Arg::number_of_values`]: Arg::number_of_values()
/// [`Arg::takes_value(true)`]: Arg::takes_value()
/// [`Arg::multiple(true)`]: Arg::multiple()
pub fn value_names(mut self, names: &[&'help str]) -> Self {
let mut i = self.val_names.len();
for s in names {
@ -2477,9 +2462,9 @@ impl<'help> Arg<'help> {
/// OPTIONS:
/// --config <FILE> Some help text
/// ```
/// [option]: ./struct.Arg.html#method.takes_value
/// [positional]: ./struct.Arg.html#method.index
/// [`Arg::takes_value(true)`]: ./struct.Arg.html#method.takes_value
/// [option]: Arg::takes_value()
/// [positional]: Arg::index()
/// [`Arg::takes_value(true)`]: Arg::takes_value()
pub fn value_name(mut self, name: &'help str) -> Self {
let l = self.val_names.len();
self.val_names.insert(l, name);
@ -2544,11 +2529,11 @@ impl<'help> Arg<'help> {
/// assert!(m.is_present("opt"));
/// assert_eq!(m.occurrences_of("opt"), 1);
/// ```
/// [`ArgMatches::occurrences_of`]: ./struct.ArgMatches.html#method.occurrences_of
/// [`ArgMatches::value_of`]: ./struct.ArgMatches.html#method.value_of
/// [`Arg::takes_value(true)`]: ./struct.Arg.html#method.takes_value
/// [`ArgMatches::is_present`]: ./struct.ArgMatches.html#method.is_present
/// [`Arg::default_value_if`]: ./struct.Arg.html#method.default_value_if
/// [`ArgMatches::occurrences_of`]: ArgMatches::occurrences_of()
/// [`ArgMatches::value_of`]: ArgMatches::value_of()
/// [`Arg::takes_value(true)`]: Arg::takes_value()
/// [`ArgMatches::is_present`]: ArgMatches::is_present()
/// [`Arg::default_value_if`]: Arg::default_value_if()
#[inline]
pub fn default_value(self, val: &'help str) -> Self {
self.default_values_os(&[OsStr::new(val)])
@ -2557,8 +2542,8 @@ impl<'help> Arg<'help> {
/// Provides a default value in the exact same manner as [`Arg::default_value`]
/// only using [`OsStr`]s instead.
///
/// [`Arg::default_value`]: ./struct.Arg.html#method.default_value
/// [`OsStr`]: https://doc.rust-lang.org/std/ffi/struct.OsStr.html
/// [`Arg::default_value`]: Arg::default_value()
/// [`OsStr`]: std::ffi::OsStr
#[inline]
pub fn default_value_os(self, val: &'help OsStr) -> Self {
self.default_values_os(&[val])
@ -2566,7 +2551,7 @@ impl<'help> Arg<'help> {
/// Like [`Arg::default_value`] but for args taking multiple values
///
/// [`Arg::default_value`]: ./struct.Arg.html#method.default_value
/// [`Arg::default_value`]: Arg::default_value()
#[inline]
pub fn default_values(self, vals: &[&'help str]) -> Self {
let vals_vec: Vec<_> = vals.iter().map(|val| OsStr::new(*val)).collect();
@ -2576,8 +2561,8 @@ impl<'help> Arg<'help> {
/// Provides default values in the exact same manner as [`Arg::default_values`]
/// only using [`OsStr`]s instead.
///
/// [`Arg::default_values`]: ./struct.Arg.html#method.default_values
/// [`OsStr`]: https://doc.rust-lang.org/std/ffi/struct.OsStr.html
/// [`Arg::default_values`]: Arg::default_values()
/// [`OsStr`]: std::ffi::OsStr
#[inline]
pub fn default_values_os(mut self, vals: &[&'help OsStr]) -> Self {
self.default_vals = vals.to_vec();
@ -2651,11 +2636,11 @@ impl<'help> Arg<'help> {
/// assert!(m.is_present("color"));
/// assert_eq!(m.occurrences_of("color"), 1);
/// ```
/// [`ArgMatches::occurrences_of`]: ./struct.ArgMatches.html#method.occurrences_of
/// [`ArgMatches::value_of`]: ./struct.ArgMatches.html#method.value_of
/// [`Arg::takes_value(true)`]: ./struct.Arg.html#method.takes_value
/// [`ArgMatches::is_present`]: ./struct.ArgMatches.html#method.is_present
/// [`Arg::default_value`]: ./struct.Arg.html#method.default_value
/// [`ArgMatches::occurrences_of`]: ArgMatches::occurrences_of()
/// [`ArgMatches::value_of`]: ArgMatches::value_of()
/// [`Arg::takes_value(true)`]: Arg::takes_value()
/// [`ArgMatches::is_present`]: ArgMatches::is_present()
/// [`Arg::default_value`]: Arg::default_value()
#[inline]
pub fn default_missing_value(self, val: &'help str) -> Self {
self.default_missing_values_os(&[OsStr::new(val)])
@ -2664,8 +2649,8 @@ impl<'help> Arg<'help> {
/// Provides a default value in the exact same manner as [`Arg::default_missing_value`]
/// only using [`OsStr`]s instead.
///
/// [`Arg::default_missing_value`]: ./struct.Arg.html#method.default_missing_value
/// [`OsStr`]: https://doc.rust-lang.org/std/ffi/struct.OsStr.html
/// [`Arg::default_missing_value`]: Arg::default_missing_value()
/// [`OsStr`]: std::ffi::OsStr
#[inline]
pub fn default_missing_value_os(self, val: &'help OsStr) -> Self {
self.default_missing_values_os(&[val])
@ -2673,7 +2658,7 @@ impl<'help> Arg<'help> {
/// Like [`Arg::default_missing_value`] but for args taking multiple values
///
/// [`Arg::default_missing_value`]: ./struct.Arg.html#method.default_missing_value
/// [`Arg::default_missing_value`]: Arg::default_missing_value()
#[inline]
pub fn default_missing_values(self, vals: &[&'help str]) -> Self {
let vals_vec: Vec<_> = vals.iter().map(|val| OsStr::new(*val)).collect();
@ -2683,8 +2668,8 @@ impl<'help> Arg<'help> {
/// Provides default values in the exact same manner as [`Arg::default_missing_values`]
/// only using [`OsStr`]s instead.
///
/// [`Arg::default_missing_values`]: ./struct.Arg.html#method.default_missing_values
/// [`OsStr`]: https://doc.rust-lang.org/std/ffi/struct.OsStr.html
/// [`Arg::default_missing_values`]: Arg::default_missing_values()
/// [`OsStr`]: std::ffi::OsStr
#[inline]
pub fn default_missing_values_os(mut self, vals: &[&'help OsStr]) -> Self {
self.default_missing_vals = vals.to_vec();
@ -2803,8 +2788,8 @@ impl<'help> Arg<'help> {
///
/// assert_eq!(m.value_of("other"), None);
/// ```
/// [`Arg::takes_value(true)`]: ./struct.Arg.html#method.takes_value
/// [`Arg::default_value`]: ./struct.Arg.html#method.default_value
/// [`Arg::takes_value(true)`]: Arg::takes_value()
/// [`Arg::default_value`]: Arg::default_value()
pub fn default_value_if<T: Key>(
self,
arg_id: T,
@ -2817,8 +2802,8 @@ impl<'help> Arg<'help> {
/// Provides a conditional default value in the exact same manner as [`Arg::default_value_if`]
/// only using [`OsStr`]s instead.
///
/// [`Arg::default_value_if`]: ./struct.Arg.html#method.default_value_if
/// [`OsStr`]: https://doc.rust-lang.org/std/ffi/struct.OsStr.html
/// [`Arg::default_value_if`]: Arg::default_value_if()
/// [`OsStr`]: std::ffi::OsStr
pub fn default_value_if_os<T: Key>(
mut self,
arg_id: T,
@ -2913,8 +2898,8 @@ impl<'help> Arg<'help> {
///
/// assert_eq!(m.value_of("other"), Some("default"));
/// ```
/// [`Arg::takes_value(true)`]: ./struct.Arg.html#method.takes_value
/// [`Arg::default_value_if`]: ./struct.Arg.html#method.default_value_if
/// [`Arg::takes_value(true)`]: Arg::takes_value()
/// [`Arg::default_value_if`]: Arg::default_value_if()
pub fn default_value_ifs<T: Key>(
mut self,
ifs: &[(T, Option<&'help str>, Option<&'help str>)],
@ -2928,8 +2913,8 @@ impl<'help> Arg<'help> {
/// Provides multiple conditional default values in the exact same manner as
/// [`Arg::default_value_ifs`] only using [`OsStr`]s instead.
///
/// [`Arg::default_value_ifs`]: ./struct.Arg.html#method.default_value_ifs
/// [`OsStr`]: https://doc.rust-lang.org/std/ffi/struct.OsStr.html
/// [`Arg::default_value_ifs`]: Arg::default_value_ifs()
/// [`OsStr`]: std::ffi::OsStr
pub fn default_value_ifs_os<T: Key>(
mut self,
ifs: &[(T, Option<&'help OsStr>, Option<&'help OsStr>)],
@ -3060,12 +3045,12 @@ impl<'help> Arg<'help> {
///
/// assert_eq!(m.values_of("flag").unwrap().collect::<Vec<_>>(), vec!["env1", "env2"]);
/// ```
/// [`ArgMatches::occurrences_of`]: ./struct.ArgMatches.html#method.occurrences_of
/// [`ArgMatches::value_of`]: ./struct.ArgMatches.html#method.value_of
/// [`ArgMatches::is_present`]: ./struct.ArgMatches.html#method.is_present
/// [`Arg::takes_value(true)`]: ./struct.Arg.html#method.takes_value
/// [`Arg::multiple(true)`]: ./struct.Arg.html#method.multiple
/// [`Arg::use_delimiter(true)`]: ./struct.Arg.html#method.use_delimiter
/// [`ArgMatches::occurrences_of`]: ArgMatches::occurrences_of()
/// [`ArgMatches::value_of`]: ArgMatches::value_of()
/// [`ArgMatches::is_present`]: ArgMatches::is_present()
/// [`Arg::takes_value(true)`]: Arg::takes_value()
/// [`Arg::multiple(true)`]: Arg::multiple()
/// [`Arg::use_delimiter(true)`]: Arg::use_delimiter()
#[inline]
pub fn env(self, name: &'help str) -> Self {
self.env_os(OsStr::new(name))
@ -3133,8 +3118,8 @@ impl<'help> Arg<'help> {
/// -O, --other-option <b> I should be first!
/// -o, --long-option <a> Some help and text
/// ```
/// [positional arguments]: ./struct.Arg.html#method.index
/// [index]: ./struct.Arg.html#method.index
/// [positional arguments]: Arg::index()
/// [index]: Arg::index()
#[inline]
pub fn display_order(mut self, ord: usize) -> Self {
self.disp_ord = ord;
@ -3213,13 +3198,8 @@ impl<'help> Arg<'help> {
/// assert!(res.is_err());
/// assert_eq!(res.unwrap_err().kind, ErrorKind::UnknownArgument);
/// ```
/// [index]: ./struct.Arg.html#method.index
/// [`AppSettings::DontCollapseArgsInUsage`]: ./enum.AppSettings.html#variant.DontCollapseArgsInUsage
/// [`AppSettings::ArgsNegateSubcommands`]: ./enum.AppSettings.html#variant.ArgsNegateSubcommands
/// [`AppSettings::SubcommandsNegateReqs`]: ./enum.AppSettings.html#variant.SubcommandsNegateReqs
/// [`ArgSettings::Required`]: ./enum.ArgSettings.html#variant.Required
/// [`UnknownArgument`]: ./enum.ErrorKind.html#variant.UnknownArgument
/// [`ArgSettings::Last`]: ./enum.ArgSettings.html#variant.Last
/// [index]: Arg::index()
/// [`UnknownArgument`]: ErrorKind::UnknownArgument
#[inline]
pub fn last(self, l: bool) -> Self {
if l {
@ -3283,7 +3263,7 @@ impl<'help> Arg<'help> {
/// assert!(res.is_err());
/// assert_eq!(res.unwrap_err().kind, ErrorKind::MissingRequiredArgument);
/// ```
/// [`Required`]: ./enum.ArgSettings.html#variant.Required
/// [`Required`]: ArgSettings::Required
#[inline]
pub fn required(self, r: bool) -> Self {
if r {
@ -3329,9 +3309,9 @@ impl<'help> Arg<'help> {
/// assert!(m.is_present("mode"));
/// assert_eq!(m.value_of("mode"), Some("fast"));
/// ```
/// [`Arg::value_delimiter(char)`]: ./struct.Arg.html#method.value_delimiter
/// [`Arg::unset_setting(ArgSettings::UseValueDelimiter)`]: ./enum.ArgSettings.html#variant.UseValueDelimiter
/// [multiple values]: ./enum.ArgSettings.html#variant.MultipleValues
/// [`Arg::value_delimiter(char)`]: Arg::value_delimiter()
/// [`Arg::unset_setting(ArgSettings::UseValueDelimiter)`]: ArgSettings::UseValueDelimiter
/// [multiple values]: ArgSettings::MultipleValues
#[inline]
pub fn takes_value(self, tv: bool) -> Self {
if tv {
@ -3398,10 +3378,7 @@ impl<'help> Arg<'help> {
/// assert!(res.is_err());
/// assert_eq!(res.unwrap_err().kind, ErrorKind::UnknownArgument);
/// ```
/// [`ArgSettings::AllowHyphenValues`]: ./enum.ArgSettings.html#variant.AllowHyphenValues
/// [`ArgSettings::MultipleValues`]: ./enum.ArgSettings.html#variant.MultipleValues
/// [`ArgSettings::MultipleOccurrences`]: ./enum.ArgSettings.html#variant.MultipleOccurrences
/// [`Arg::number_of_values(1)`]: ./struct.Arg.html#method.number_of_values
/// [`Arg::number_of_values(1)`]: Arg::number_of_values()
#[inline]
pub fn allow_hyphen_values(self, a: bool) -> Self {
if a {
@ -3461,7 +3438,7 @@ impl<'help> Arg<'help> {
/// assert!(res.is_err());
/// assert_eq!(res.unwrap_err().kind, ErrorKind::NoEquals);
/// ```
/// [`RequireEquals`]: ./enum.ArgSettings.html#variant.RequireEquals
/// [`RequireEquals`]: ArgSettings::RequireEquals
#[inline]
pub fn require_equals(self, r: bool) -> Self {
if r {
@ -3509,11 +3486,9 @@ impl<'help> Arg<'help> {
/// let sub_m = m.subcommand_matches("do-stuff").unwrap();
/// assert!(sub_m.is_present("verb"));
/// ```
/// [``]: ./struct.App.html#method.subcommand
/// [required]: ./enum.ArgSettings.html#variant.Required
/// [`ArgMatches`]: ./struct.ArgMatches.html
/// [`ArgMatches::is_present("flag")`]: ./struct.ArgMatches.html#method.is_present
/// [`Arg`]: ./struct.Arg.html
/// [``]: App::subcommand()
/// [required]: ArgSettings::Required
/// [`ArgMatches::is_present("flag")`]: ArgMatches::is_present()
#[inline]
pub fn global(mut self, g: bool) -> Self {
self.global = g;
@ -3593,8 +3568,6 @@ impl<'help> Arg<'help> {
/// assert!(delims.is_present("opt"));
/// assert_eq!(delims.values_of("opt").unwrap().collect::<Vec<_>>(), ["val1", "val2", "val3"]);
/// ```
/// [`ArgSettings::UseValueDelimiter`]: ./enum.ArgSettings.html#variant.UseValueDelimiter
/// [`ArgSettings::TakesValue`]: ./enum.ArgSettings.html#variant.TakesValue
#[inline]
pub fn require_delimiter(self, d: bool) -> Self {
if d {
@ -3824,7 +3797,7 @@ impl<'help> Arg<'help> {
/// assert_eq!(nodelims.occurrences_of("option"), 1);
/// assert_eq!(nodelims.value_of("option").unwrap(), "val1,val2,val3");
/// ```
/// [`Arg::value_delimiter`]: ./struct.Arg.html#method.value_delimiter
/// [`Arg::value_delimiter`]: Arg::value_delimiter()
#[inline]
pub fn use_delimiter(mut self, d: bool) -> Self {
if d {
@ -3960,7 +3933,6 @@ impl<'help> Arg<'help> {
/// help that makes more sense to be
/// on a line after the option
/// ```
/// [`AppSettings::NextLineHelp`]: ./enum.AppSettings.html#variant.NextLineHelp
#[inline]
pub fn next_line_help(self, nlh: bool) -> Self {
if nlh {
@ -4144,17 +4116,17 @@ impl<'help> Arg<'help> {
/// assert!(res.is_err());
/// assert_eq!(res.unwrap_err().kind, ErrorKind::UnknownArgument);
/// ```
/// [option]: ./enum.ArgSettings.html#variant.TakesValue
/// [options]: ./enum.ArgSettings.html#variant.TakesValue
/// [subcommands]: ./struct.App.html#method.subcommand
/// [positionals]: ./struct.Arg.html#method.index
/// [`Arg::number_of_values(1)`]: ./struct.Arg.html#method.number_of_values
/// [`MultipleOccurrences`]: ./enum.ArgSettings.html#variant.MultipleOccurrences
/// [`MultipleValues`]: ./enum.ArgSettings.html#variant.MultipleValues
/// [maximum number of values]: ./struct.Arg.html#method.max_values
/// [specific number of values]: ./struct.Arg.html#method.number_of_values
/// [maximum]: ./struct.Arg.html#method.max_values
/// [specific]: ./struct.Arg.html#method.number_of_values
/// [option]: ArgSettings::TakesValue
/// [options]: ArgSettings::TakesValue
/// [subcommands]: App::subcommand()
/// [positionals]: Arg::index()
/// [`Arg::number_of_values(1)`]: Arg::number_of_values()
/// [`MultipleOccurrences`]: ArgSettings::MultipleOccurrences
/// [`MultipleValues`]: ArgSettings::MultipleValues
/// [maximum number of values]: Arg::max_values()
/// [specific number of values]: Arg::number_of_values()
/// [maximum]: Arg::max_values()
/// [specific]: Arg::number_of_values()
#[inline]
pub fn multiple(self, multi: bool) -> Self {
self.multiple_occurrences(multi).multiple_values(multi)
@ -4213,7 +4185,6 @@ impl<'help> Arg<'help> {
/// assert!(res.is_err());
/// assert_eq!(res.unwrap_err().kind, ErrorKind::EmptyValue);
/// ```
/// [`ArgSettings::TakesValue`]: ./enum.ArgSettings.html#variant.TakesValue
#[inline]
pub fn forbid_empty_values(self, empty: bool) -> Self {
if empty {
@ -4284,17 +4255,17 @@ impl<'help> Arg<'help> {
/// let files: Vec<_> = m.values_of("file").unwrap().collect();
/// assert_eq!(files, ["file1", "file2", "file3"]);
/// ```
/// [option]: ./enum.ArgSettings.html#variant.TakesValue
/// [options]: ./enum.ArgSettings.html#variant.TakesValue
/// [subcommands]: ./struct.App.html#method.subcommand
/// [positionals]: ./struct.Arg.html#method.index
/// [`Arg::number_of_values(1)`]: ./struct.Arg.html#method.number_of_values
/// [`MultipleOccurrences`]: ./enum.ArgSettings.html#variant.MultipleOccurrences
/// [`MultipleValues`]: ./enum.ArgSettings.html#variant.MultipleValues
/// [maximum number of values]: ./struct.Arg.html#method.max_values
/// [specific number of values]: ./struct.Arg.html#method.number_of_values
/// [maximum]: ./struct.Arg.html#method.max_values
/// [specific]: ./struct.Arg.html#method.number_of_values
/// [option]: ArgSettings::TakesValue
/// [options]: ArgSettings::TakesValue
/// [subcommands]: App::subcommand()
/// [positionals]: Arg::index()
/// [`Arg::number_of_values(1)`]: Arg::number_of_values()
/// [`MultipleOccurrences`]: ArgSettings::MultipleOccurrences
/// [`MultipleValues`]: ArgSettings::MultipleValues
/// [maximum number of values]: Arg::max_values()
/// [specific number of values]: Arg::number_of_values()
/// [maximum]: Arg::max_values()
/// [specific]: Arg::number_of_values()
#[inline]
pub fn multiple_occurrences(self, multi: bool) -> Self {
if multi {
@ -4319,11 +4290,10 @@ impl<'help> Arg<'help> {
/// **NOTE:** Implicitly sets [`Arg::takes_value(true)`] [`Arg::multiple(true)`], [`Arg::allow_hyphen_values(true)`], and
/// [`Arg::last(true)`] when set to `true`
///
/// [`Arg::takes_value(true)`]: ./struct.Arg.html#method.takes_value
/// [`Arg::multiple(true)`]: ./struct.Arg.html#method.multiple
/// [`Arg::allow_hyphen_values(true)`]: ./struct.Arg.html#method.allow_hyphen_values
/// [`Arg::last(true)`]: ./struct.Arg.html#method.last
/// [`AppSettings::TrailingVarArg`]: ./enum.AppSettings.html#variant.TrailingVarArg
/// [`Arg::takes_value(true)`]: Arg::takes_value()
/// [`Arg::multiple(true)`]: Arg::multiple()
/// [`Arg::allow_hyphen_values(true)`]: Arg::allow_hyphen_values()
/// [`Arg::last(true)`]: Arg::last()
#[inline]
pub fn raw(self, raw: bool) -> Self {
self.takes_value(raw)
@ -4491,7 +4461,6 @@ impl<'help> Arg<'help> {
// @TODO @docs @v3-beta: write better docs as ArgSettings is now critical
/// Checks if one of the [`ArgSettings`] is set for the argument
///
/// [`ArgSettings`]: ./enum.ArgSettings.html
#[inline]
pub fn is_set(&self, s: ArgSettings) -> bool {
self.settings.is_set(s)
@ -4510,7 +4479,6 @@ impl<'help> Arg<'help> {
/// .setting(ArgSettings::TakesValue)
/// # ;
/// ```
/// [`ArgSettings`]: ./enum.ArgSettings.html
#[inline]
pub fn setting(mut self, setting: ArgSettings) -> Self {
self.settings.set(setting);
@ -4529,7 +4497,6 @@ impl<'help> Arg<'help> {
/// .unset_setting(ArgSettings::Required)
/// # ;
/// ```
/// [`ArgSettings`]: ./enum.ArgSettings.html
#[inline]
pub fn unset_setting(mut self, setting: ArgSettings) -> Self {
self.settings.unset(setting);
@ -4660,7 +4627,6 @@ impl<'help> From<&'help Yaml> for Arg<'help> {
/// let yaml = load_yaml!("arg.yaml");
/// let arg = Arg::from(yaml);
/// ```
/// [`Arg`]: ./struct.Arg.html
#[allow(clippy::cognitive_complexity)]
fn from(y: &'help Yaml) -> Self {
let y = y.as_hash().unwrap();

2
src/build/arg/regex.rs
View file

@ -8,7 +8,7 @@ use std::borrow::Cow;
///
/// Essentially a [`Cow`] wrapper with custom convenience traits.
///
/// [`Cow`]: https://doc.rust-lang.org/std/borrow/enum.Cow.html
/// [`Cow`]: std::borrow::Cow
#[derive(Debug, Clone)]
pub struct RegexRef<'a>(Cow<'a, Regex>);

7
src/build/arg/settings.rs
View file

@ -68,10 +68,9 @@ impl Default for ArgFlags {
/// methods [`Arg::setting`], [`Arg::unset_setting`], and [`Arg::is_set`]. This is what the
/// [`Arg`] methods which accept a `bool` use internally.
///
/// [`Arg`]: ./struct.Arg.html
/// [`Arg::setting`]: ./struct.Arg.html#method.setting
/// [`Arg::unset_setting`]: ./struct.Arg.html#method.unset_setting
/// [`Arg::is_set`]: ./struct.Arg.html#method.is_set
/// [`Arg::setting`]: Arg::setting()
/// [`Arg::unset_setting`]: Arg::unset_setting()
/// [`Arg::is_set`]: Arg::is_set()
#[derive(Debug, PartialEq, Copy, Clone)]
pub enum ArgSettings {
/// Specifies that an arg must be used

3
src/build/arg/value_hint.rs
View file

@ -49,8 +49,7 @@ pub enum ValueHint {
/// command line `my_app ls -la /` will be parsed as `["ls", "-la", "/"]` and clap won't try to
/// parse the `-la` argument itself.
///
/// [`.multiple(true)`]: ./struct.Arg.html#method.multiple
/// [`AppSettings::TrailingVarArg`]: ./enum.AppSettings.html#variant.TrailingVarArg
/// [`.multiple(true)`]: Arg::multiple()
CommandWithArguments,
/// Name of a local operating system user.
Username,

30
src/build/arg_group.rs
View file

@ -70,11 +70,11 @@ use yaml_rust::Yaml;
/// assert!(matches.is_present("vers"));
/// // we could also alternatively check each arg individually (not shown here)
/// ```
/// [`ArgGroup::multiple(true)`]: ./struct.ArgGroup.html#method.multiple
/// [`ArgGroup::multiple(false)`]: ./struct.ArgGroup.html#method.multiple
/// [arguments]: ./struct.Arg.html
/// [conflict]: ./struct.Arg.html#method.conflicts_with
/// [requirement]: ./struct.Arg.html#method.requires
/// [`ArgGroup::multiple(true)`]: ArgGroup::multiple()
/// [`ArgGroup::multiple(false)`]: ArgGroup::multiple()
/// [arguments]: Arg
/// [conflict]: Arg::conflicts_with()
/// [requirement]: Arg::requires()
#[derive(Default, Debug, PartialEq, Eq)]
pub struct ArgGroup<'help> {
pub(crate) id: Id,
@ -133,7 +133,7 @@ impl<'help> ArgGroup<'help> {
/// // but we can also check individually if needed
/// assert!(m.is_present("flag"));
/// ```
/// [argument]: ./struct.Arg.html
/// [argument]: Arg
pub fn arg<T: Key>(mut self, arg_id: T) -> Self {
self.args.push(arg_id.into());
self
@ -158,7 +158,7 @@ impl<'help> ArgGroup<'help> {
/// // but we can also check individually if needed
/// assert!(m.is_present("flag"));
/// ```
/// [arguments]: ./struct.Arg.html
/// [arguments]: Arg
pub fn args<T: Key>(mut self, ns: &[T]) -> Self {
for n in ns {
self = self.arg(n);
@ -205,7 +205,6 @@ impl<'help> ArgGroup<'help> {
/// let err = result.unwrap_err();
/// assert_eq!(err.kind, ErrorKind::ArgumentConflict);
/// ```
/// [`Arg`]: ./struct.Arg.html
#[inline]
pub fn multiple(mut self, m: bool) -> Self {
self.multiple = m;
@ -243,9 +242,8 @@ impl<'help> ArgGroup<'help> {
/// let err = result.unwrap_err();
/// assert_eq!(err.kind, ErrorKind::MissingRequiredArgument);
/// ```
/// [`App`]: ./struct.App.html
/// [``]: ./struct..html
/// [`ArgGroup::multiple`]: ./struct.ArgGroup.html#method.multiple
/// [`ArgGroup::multiple`]: ArgGroup::multiple()
#[inline]
pub fn required(mut self, r: bool) -> Self {
self.required = r;
@ -280,8 +278,8 @@ impl<'help> ArgGroup<'help> {
/// let err = result.unwrap_err();
/// assert_eq!(err.kind, ErrorKind::MissingRequiredArgument);
/// ```
/// [required group]: ./struct.ArgGroup.html#method.required
/// [argument requirement rules]: ./struct.Arg.html#method.requires
/// [required group]: ArgGroup::required()
/// [argument requirement rules]: Arg::requires()
pub fn requires<T: Key>(mut self, id: T) -> Self {
self.requires.push(id.into());
self
@ -317,8 +315,8 @@ impl<'help> ArgGroup<'help> {
/// let err = result.unwrap_err();
/// assert_eq!(err.kind, ErrorKind::MissingRequiredArgument);
/// ```
/// [required group]: ./struct.ArgGroup.html#method.required
/// [argument requirement rules]: ./struct.Arg.html#method.requires_all
/// [required group]: ArgGroup::required()
/// [argument requirement rules]: Arg::requires_all()
pub fn requires_all(mut self, ns: &[&'help str]) -> Self {
for n in ns {
self = self.requires(n);
@ -352,7 +350,7 @@ impl<'help> ArgGroup<'help> {
/// let err = result.unwrap_err();
/// assert_eq!(err.kind, ErrorKind::ArgumentConflict);
/// ```
/// [argument exclusion rules]: ./struct.Arg.html#method.conflicts_with
/// [argument exclusion rules]: Arg::conflicts_with()
pub fn conflicts_with<T: Key>(mut self, id: T) -> Self {
self.conflicts.push(id.into());
self
@ -387,7 +385,7 @@ impl<'help> ArgGroup<'help> {
/// let err = result.unwrap_err();
/// assert_eq!(err.kind, ErrorKind::ArgumentConflict);
/// ```
/// [argument exclusion rules]: ./struct.Arg.html#method.conflicts_with_all
/// [argument exclusion rules]: Arg::conflicts_with_all()
pub fn conflicts_with_all(mut self, ns: &[&'help str]) -> Self {
for n in ns {
self = self.conflicts_with(n);

5
src/derive.rs
View file

@ -66,10 +66,6 @@ use std::ffi::OsString;
/// }
/// ```
///
/// [`App`]: ./struct.App.html
/// [`ArgMatches`]: ./struct.ArgMatches.html
/// [`FromArgMatches`]: ./trait.FromArgMatches.html
/// [`IntoApp`]: ./trait.IntoApp.html
pub trait Clap: FromArgMatches + IntoApp + Sized {
/// Parse from `std::env::args_os()`, exit on error
fn parse() -> Self {
@ -146,7 +142,6 @@ pub trait IntoApp: Sized {
/// Converts an instance of [`ArgMatches`] to a consumer defined struct.
///
/// [`ArgMatches`]: ./struct.ArgMatches.html
pub trait FromArgMatches: Sized {
/// It's common to have an "application context" struct (sometimes called
/// config) that represents all the normalized values after being processed by

18
src/macros.rs
View file

@ -170,7 +170,7 @@ macro_rules! crate_name {
///
/// Equivalent to using the `crate_*!` macros with their respective fields.
///
/// Provided separator is for the [`crate_authors!`](macro.crate_authors.html) macro,
/// Provided separator is for the [`crate_authors!`] macro,
/// refer to the documentation therefor.
///
/// **NOTE:** Changing the values in your `Cargo.toml` does not trigger a re-build automatically,
@ -285,14 +285,14 @@ macro_rules! app_from_crate {
/// * `(@arg "something-else": --"something-else")`
/// * `(@subcommand "something-else" => ...)`
///
/// [`Arg::short`]: ./struct.Arg.html#method.short
/// [`Arg::long`]: ./struct.Arg.html#method.long
/// [`Arg::multiple(true)`]: ./struct.Arg.html#method.multiple
/// [`Arg::value_name`]: ./struct.Arg.html#method.value_name
/// [`Arg::min_values(min)`]: ./struct.Arg.html#method.min_values
/// [`Arg::max_values(max)`]: ./struct.Arg.html#method.max_values
/// [`Arg::validator`]: ./struct.Arg.html#method.validator
/// [`Arg::conflicts_with`]: ./struct.Arg.html#method.conflicts_with
/// [`Arg::short`]: Arg::short()
/// [`Arg::long`]: Arg::long()
/// [`Arg::multiple(true)`]: Arg::multiple()
/// [`Arg::value_name`]: Arg::value_name()
/// [`Arg::min_values(min)`]: Arg::min_values()
/// [`Arg::max_values(max)`]: Arg::max_values()
/// [`Arg::validator`]: Arg::validator()
/// [`Arg::conflicts_with`]: Arg::conflicts_with()
#[macro_export]
macro_rules! clap_app {
(@app ($builder:expr)) => { $builder };

2
src/output/help.rs
View file

@ -962,7 +962,7 @@ impl<'help, 'app, 'parser, 'writer> Help<'help, 'app, 'parser, 'writer> {
///
/// For details about the template language see [`App::help_template`].
///
/// [`App::help_template`]: ./struct.App.html#method.help_template
/// [`App::help_template`]: App::help_template()
fn write_templated_help(&mut self, template: &str) -> io::Result<()> {
debug!("Help::write_templated_help");

31
src/parse/errors.rs
View file

@ -17,7 +17,7 @@ use crate::{
/// Short hand for [`Result`] type
///
/// [`Result`]: https://doc.rust-lang.org/std/result/enum.Result.html
/// [`Result`]: std::result::Result
pub type Result<T> = StdResult<T, Error>;
/// Command line argument parser kind of error
@ -38,7 +38,6 @@ pub enum ErrorKind {
/// assert!(result.is_err());
/// assert_eq!(result.unwrap_err().kind, ErrorKind::InvalidValue);
/// ```
/// [`Arg`]: ./struct.Arg.html
InvalidValue,
/// Occurs when a user provides a flag, option, argument or subcommand which isn't defined.
@ -76,7 +75,7 @@ pub enum ErrorKind {
/// assert_eq!(result.unwrap_err().kind, ErrorKind::InvalidSubcommand);
/// ```
/// [``]: ./struct..html
/// [`UnknownArgument`]: ./enum.ErrorKind.html#variant.UnknownArgument
/// [`UnknownArgument`]: ErrorKind::UnknownArgument
InvalidSubcommand,
/// Occurs when the user provides an unrecognized [``] which either
@ -102,8 +101,8 @@ pub enum ErrorKind {
/// assert_eq!(result.unwrap_err().kind, ErrorKind::UnrecognizedSubcommand);
/// ```
/// [``]: ./struct..html
/// [`InvalidSubcommand`]: ./enum.ErrorKind.html#variant.InvalidSubcommand
/// [`UnknownArgument`]: ./enum.ErrorKind.html#variant.UnknownArgument
/// [`InvalidSubcommand`]: ErrorKind::InvalidSubcommand
/// [`UnknownArgument`]: ErrorKind::UnknownArgument
UnrecognizedSubcommand,
/// Occurs when the user provides an empty value for an option that does not allow empty
@ -179,7 +178,7 @@ pub enum ErrorKind {
/// assert!(result.is_err());
/// assert_eq!(result.unwrap_err().kind, ErrorKind::TooManyValues);
/// ```
/// [`Arg::max_values`]: ./struct.Arg.html#method.max_values
/// [`Arg::max_values`]: Arg::max_values()
TooManyValues,
/// Occurs when the user provides fewer values for an argument than were defined by setting
@ -197,7 +196,7 @@ pub enum ErrorKind {
/// assert!(result.is_err());
/// assert_eq!(result.unwrap_err().kind, ErrorKind::TooFewValues);
/// ```
/// [`Arg::min_values`]: ./struct.Arg.html#method.min_values
/// [`Arg::min_values`]: Arg::min_values()
TooFewValues,
/// Occurs when the user provides a different number of values for an argument than what's
@ -218,8 +217,8 @@ pub enum ErrorKind {
/// assert_eq!(result.unwrap_err().kind, ErrorKind::WrongNumberOfValues);
/// ```
///
/// [`Arg::number_of_values`]: ./struct.Arg.html#method.number_of_values
/// [`Arg::value_names`]: ./struct.Arg.html#method.value_names
/// [`Arg::number_of_values`]: Arg::number_of_values()
/// [`Arg::value_names`]: Arg::value_names()
WrongNumberOfValues,
/// Occurs when the user provides two values which conflict with each other and can't be used
@ -273,7 +272,6 @@ pub enum ErrorKind {
/// assert_eq!(err.unwrap_err().kind, ErrorKind::MissingSubcommand);
/// # ;
/// ```
/// [`AppSettings::SubcommandRequired`]: ./enum.AppSettings.html#variant.SubcommandRequired
MissingSubcommand,
/// Occurs when the user provides multiple values to an argument which doesn't allow that.
@ -317,7 +315,6 @@ pub enum ErrorKind {
/// assert!(result.is_err());
/// assert_eq!(result.unwrap_err().kind, ErrorKind::InvalidUtf8);
/// ```
/// [`AppSettings::StrictUtf8`]: ./enum.AppSettings.html#variant.StrictUtf8
InvalidUtf8,
/// Not a true "error" as it means `--help` or similar was used.
@ -356,9 +353,7 @@ pub enum ErrorKind {
/// assert!(result.is_err());
/// assert_eq!(result.unwrap_err().kind, ErrorKind::DisplayHelpOnMissingArgumentOrSubcommand);
/// ```
/// [`AppSettings::ArgRequiredElseHelp`]: ./enum.AppSettings.html#variant.ArgRequiredElseHelp
/// [`AppSettings::SubcommandRequiredElseHelp`]: ./enum.AppSettings.html#variant.SubcommandRequiredElseHelp
/// [`subcommand`]: ./struct.App.html#method.subcommand
/// [`subcommand`]: App::subcommand()
DisplayHelpOnMissingArgumentOrSubcommand,
/// Not a true "error" as it means `--version` or similar was used.
@ -379,20 +374,20 @@ pub enum ErrorKind {
/// into type `T`, but the argument you requested wasn't used. I.e. you asked for an argument
/// with name `config` to be converted, but `config` wasn't used by the user.
///
/// [`ArgMatches::value_of_t`]: ./struct.ArgMatches.html#method.value_of_t
/// [`ArgMatches::value_of_t`]: ArgMatches::value_of_t()
ArgumentNotFound,
/// Represents an [I/O error].
/// Can occur when writing to `stderr` or `stdout` or reading a configuration file.
///
/// [I/O error]: https://doc.rust-lang.org/std/io/struct.Error.html
/// [I/O error]: std::io::Error
Io,
/// Represents a [Format error] (which is a part of [`Display`]).
/// Typically caused by writing to `stderr` or `stdout`.
///
/// [`Display`]: https://doc.rust-lang.org/std/fmt/trait.Display.html
/// [Format error]: https://doc.rust-lang.org/std/fmt/struct.Error.html
/// [`Display`]: std::fmt::Display
/// [Format error]: std::fmt::Error
Format,
}

70
src/parse/matches/arg_matches.rs
View file

@ -72,7 +72,7 @@ pub(crate) struct SubCommand {
/// }
/// }
/// ```
/// [`App::get_matches`]: ./struct.App.html#method.get_matches
/// [`App::get_matches`]: App::get_matches()
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ArgMatches {
pub(crate) args: IndexMap<Id, MatchedArg>,
@ -115,12 +115,12 @@ impl ArgMatches {
///
/// assert_eq!(m.value_of("output"), Some("something"));
/// ```
/// [option]: ./struct.Arg.html#method.takes_value
/// [positional]: ./struct.Arg.html#method.index
/// [`ArgMatches::values_of`]: ./struct.ArgMatches.html#method.values_of
/// [option]: Arg::takes_value()
/// [positional]: Arg::index()
/// [`ArgMatches::values_of`]: ArgMatches::values_of()
/// [`panic!`]: https://doc.rust-lang.org/std/macro.panic!.html
/// [`default_value`]: ./struct.Arg.html#method.default_value
/// [`occurrences_of`]: ./struct.ArgMatches.html#method.occurrences_of
/// [`default_value`]: Arg::default_value()
/// [`occurrences_of`]: ArgMatches::occurrences_of()
pub fn value_of<T: Key>(&self, id: T) -> Option<&str> {
if let Some(arg) = self.args.get(&Id::from(id)) {
if let Some(v) = arg.get_val(0) {
@ -155,9 +155,9 @@ impl ArgMatches {
/// OsString::from_vec(vec![b'H', b'i', b' ', 0xe9, b'!'])]);
/// assert_eq!(&*m.value_of_lossy("arg").unwrap(), "Hi \u{FFFD}!");
/// ```
/// [`default_value`]: ./struct.Arg.html#method.default_value
/// [`occurrences_of`]: ./struct.ArgMatches.html#method.occurrences_of
/// [`Arg::values_of_lossy`]: ./struct.ArgMatches.html#method.values_of_lossy
/// [`default_value`]: Arg::default_value()
/// [`occurrences_of`]: ArgMatches::occurrences_of()
/// [`Arg::values_of_lossy`]: ArgMatches::values_of_lossy()
pub fn value_of_lossy<T: Key>(&self, id: T) -> Option<Cow<'_, str>> {
if let Some(arg) = self.args.get(&Id::from(id)) {
if let Some(v) = arg.get_val(0) {
@ -195,10 +195,10 @@ impl ArgMatches {
/// OsString::from_vec(vec![b'H', b'i', b' ', 0xe9, b'!'])]);
/// assert_eq!(&*m.value_of_os("arg").unwrap().as_bytes(), [b'H', b'i', b' ', 0xe9, b'!']);
/// ```
/// [`default_value`]: ./struct.Arg.html#method.default_value
/// [`occurrences_of`]: ./struct.ArgMatches.html#method.occurrences_of
/// [`String`]: https://doc.rust-lang.org/std/string/struct.String.html
/// [`ArgMatches::values_of_os`]: ./struct.ArgMatches.html#method.values_of_os
/// [`default_value`]: Arg::default_value()
/// [`occurrences_of`]: ArgMatches::occurrences_of()
/// [`String`]: std::string::String
/// [`ArgMatches::values_of_os`]: ArgMatches::values_of_os()
pub fn value_of_os<T: Key>(&self, id: T) -> Option<&OsStr> {
self.args
.get(&Id::from(id))
@ -228,8 +228,7 @@ impl ArgMatches {
/// let vals: Vec<&str> = m.values_of("output").unwrap().collect();
/// assert_eq!(vals, ["val1", "val2", "val3"]);
/// ```
/// [`Values`]: ./struct.Values.html
/// [`Iterator`]: https://doc.rust-lang.org/std/iter/trait.Iterator.html
/// [`Iterator`]: std::iter::Iterator
pub fn values_of<T: Key>(&self, id: T) -> Option<Values> {
self.args.get(&Id::from(id)).map(|arg| {
fn to_str_slice(o: &OsString) -> &str {
@ -319,10 +318,9 @@ impl ArgMatches {
/// assert_eq!(itr.next(), Some(OsStr::from_bytes(&[0xe9, b'!'])));
/// assert_eq!(itr.next(), None);
/// ```
/// [`OsValues`]: ./struct.OsValues.html
/// [`Iterator`]: https://doc.rust-lang.org/std/iter/trait.Iterator.html
/// [`OsString`]: https://doc.rust-lang.org/std/ffi/struct.OsString.html
/// [`String`]: https://doc.rust-lang.org/std/string/struct.String.html
/// [`Iterator`]: std::iter::Iterator
/// [`OsString`]: std::ffi::OsString
/// [`String`]: std::string::String
pub fn values_of_os<T: Key>(&self, id: T) -> Option<OsValues> {
fn to_str_slice(o: &OsString) -> &OsStr {
o
@ -366,9 +364,7 @@ impl ArgMatches {
/// let _: u32 = also_len;
/// ```
///
/// [`std::str::FromStr`]: https://doc.rust-lang.org/std/str/trait.FromStr.html
/// [`ErrorKind`]: enum.ErrorKind.html
/// [`ArgMatches::values_of_t`]: ./struct.ArgMatches.html#method.values_of_t
/// [`ArgMatches::values_of_t`]: ArgMatches::values_of_t()
/// [`panic!`]: https://doc.rust-lang.org/std/macro.panic!.html
pub fn value_of_t<R>(&self, name: &str) -> Result<R, Error>
where
@ -422,7 +418,6 @@ impl ArgMatches {
/// let _: u32 = also_len;
/// ```
///
/// [`std::str::FromStr`]: https://doc.rust-lang.org/std/str/trait.FromStr.html
/// [`panic!`]: https://doc.rust-lang.org/std/macro.panic!.html
pub fn value_of_t_or_exit<R>(&self, name: &str) -> R
where
@ -460,7 +455,6 @@ impl ArgMatches {
/// let _: Vec<u32> = also_len;
/// ```
///
/// [`std::str::FromStr`]: https://doc.rust-lang.org/std/str/trait.FromStr.html
/// [`panic!`]: https://doc.rust-lang.org/std/macro.panic!.html
pub fn values_of_t<R>(&self, name: &str) -> Result<Vec<R>, Error>
where
@ -514,7 +508,6 @@ impl ArgMatches {
/// let _: Vec<u32> = also_len;
/// ```
///
/// [`std::str::FromStr`]: https://doc.rust-lang.org/std/str/trait.FromStr.html
/// [`panic!`]: https://doc.rust-lang.org/std/macro.panic!.html
pub fn values_of_t_or_exit<R>(&self, name: &str) -> Vec<R>
where
@ -543,8 +536,8 @@ impl ArgMatches {
/// assert!(m.is_present("debug"));
/// ```
///
/// [`default_value`]: ./struct.Arg.html#method.default_value
/// [`occurrences_of`]: ./struct.ArgMatches.html#method.occurrences_of
/// [`default_value`]: Arg::default_value()
/// [`occurrences_of`]: ArgMatches::occurrences_of()
pub fn is_present<T: Key>(&self, id: T) -> bool {
let id = Id::from(id);
@ -729,8 +722,7 @@ impl ArgMatches {
/// assert_eq!(m.index_of("option"), Some(2));
/// assert_eq!(m.indices_of("option").unwrap().collect::<Vec<_>>(), &[2, 3, 4]);
/// ```
/// [`ArgMatches`]: ./struct.ArgMatches.html
/// [delimiter]: ./struct.Arg.html#method.value_delimiter
/// [delimiter]: Arg::value_delimiter()
pub fn index_of<T: Key>(&self, name: T) -> Option<usize> {
if let Some(arg) = self.args.get(&Id::from(name)) {
if let Some(i) = arg.get_index(0) {
@ -810,9 +802,8 @@ impl ArgMatches {
/// // ^0 ^1 ^2
/// assert_eq!(m.indices_of("option").unwrap().collect::<Vec<_>>(), &[2]);
/// ```
/// [`ArgMatches`]: ./struct.ArgMatches.html
/// [`ArgMatches::index_of`]: ./struct.ArgMatches.html#method.index_of
/// [delimiter]: ./struct.Arg.html#method.value_delimiter
/// [`ArgMatches::index_of`]: ArgMatches::index_of()
/// [delimiter]: Arg::value_delimiter()
pub fn indices_of<T: Key>(&self, id: T) -> Option<Indices<'_>> {
self.args.get(&Id::from(id)).map(|arg| Indices {
iter: arg.indices(),
@ -848,8 +839,6 @@ impl ArgMatches {
/// }
/// ```
/// [`Subcommand`]: ./struct..html
/// [`App`]: ./struct.App.html
/// [`ArgMatches`]: ./struct.ArgMatches.html
pub fn subcommand_matches<T: Key>(&self, id: T) -> Option<&ArgMatches> {
if let Some(ref s) = self.subcommand {
if s.id == id.into() {
@ -915,8 +904,6 @@ impl ArgMatches {
/// }
/// ```
/// [`Subcommand`]: ./struct..html
/// [`App`]: ./struct.App.html
/// [`ArgMatches`]: ./struct.ArgMatches.html
#[inline]
pub fn subcommand_name(&self) -> Option<&str> {
self.subcommand.as_ref().map(|sc| &*sc.name)
@ -967,8 +954,8 @@ impl ArgMatches {
/// _ => {},
/// }
/// ```
/// [`ArgMatches::subcommand_matches`]: ./struct.ArgMatches.html#method.subcommand_matches
/// [`ArgMatches::subcommand_name`]: ./struct.ArgMatches.html#method.subcommand_name
/// [`ArgMatches::subcommand_matches`]: ArgMatches::subcommand_matches()
/// [`ArgMatches::subcommand_name`]: ArgMatches::subcommand_name()
#[inline]
pub fn subcommand(&self) -> Option<(&str, &ArgMatches)> {
self.subcommand.as_ref().map(|sc| (&*sc.name, &sc.matches))
@ -1000,7 +987,7 @@ impl ArgMatches {
/// assert_eq!(values.next(), Some("val2"));
/// assert_eq!(values.next(), None);
/// ```
/// [`ArgMatches::values_of`]: ./struct.ArgMatches.html#method.values_of
/// [`ArgMatches::values_of`]: ArgMatches::values_of()
#[derive(Clone)]
#[allow(missing_debug_implementations)]
pub struct Values<'a> {
@ -1092,8 +1079,7 @@ impl<'a> Default for GroupedValues<'a> {
/// OsString::from_vec(vec![b'H', b'i', b' ', 0xe9, b'!'])]);
/// assert_eq!(&*m.value_of_os("arg").unwrap().as_bytes(), [b'H', b'i', b' ', 0xe9, b'!']);
/// ```
/// [`ArgMatches::values_of_os`]: ./struct.ArgMatches.html#method.values_of_os
/// [`Values`]: ./struct.Values.html
/// [`ArgMatches::values_of_os`]: ArgMatches::values_of_os()
#[derive(Clone)]
#[allow(missing_debug_implementations)]
pub struct OsValues<'a> {
@ -1150,7 +1136,7 @@ impl Default for OsValues<'_> {
/// assert_eq!(indices.next(), Some(3));
/// assert_eq!(indices.next(), None);
/// ```
/// [`ArgMatches::indices_of`]: ./struct.ArgMatches.html#method.indices_of
/// [`ArgMatches::indices_of`]: ArgMatches::indices_of()
#[derive(Clone)]
#[allow(missing_debug_implementations)]
pub struct Indices<'a> {