From 3312893ddaef3f44d68d8d26ed3d08010be50d97 Mon Sep 17 00:00:00 2001 From: Kevin K Date: Sat, 14 May 2016 16:25:00 -0400 Subject: [PATCH] docs: inter-links all types and pages All doc pages should now be inter-linked between other doc pages and Rust documentation. Closes #505 --- src/app/help.rs | 6 +- src/app/mod.rs | 253 ++++++++++++++++++---------- src/app/settings.rs | 103 +++++++----- src/args/arg.rs | 362 ++++++++++++++++++++++++---------------- src/args/arg_matches.rs | 99 +++++++---- src/args/group.rs | 11 +- src/args/settings.rs | 8 +- src/args/subcommand.rs | 6 +- src/errors.rs | 68 +++++--- src/lib.rs | 2 +- src/macros.rs | 44 +++-- 11 files changed, 613 insertions(+), 349 deletions(-) diff --git a/src/app/help.rs b/src/app/help.rs index eac29c62..7cbc2d81 100644 --- a/src/app/help.rs +++ b/src/app/help.rs @@ -73,9 +73,9 @@ macro_rules! color { }; } -/// CLAP Help Writer. +/// `clap` Help Writer. /// -/// Wraps a writer stream providing different methods to generate help for CLAP objects. +/// Wraps a writer stream providing different methods to generate help for `clap` objects. pub struct Help<'a> { writer: &'a mut Write, next_line_help: bool, @@ -86,7 +86,7 @@ pub struct Help<'a> { // Public Functions impl<'a> Help<'a> { - /// Create a new Help instance. + /// Create a new `Help` instance. pub fn new(w: &'a mut Write, next_line_help: bool, hide_pv: bool, color: bool) -> Self { Help { writer: w, diff --git a/src/app/mod.rs b/src/app/mod.rs index 69ade73a..87c2888c 100644 --- a/src/app/mod.rs +++ b/src/app/mod.rs @@ -30,12 +30,12 @@ use errors::Result as ClapResult; /// 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 -/// `.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). +/// [`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 +/// also appear in any order (so long as one of the [`App::get_matches`] methods is the last method /// called). /// /// # Examples @@ -55,6 +55,7 @@ use errors::Result as ClapResult; /// /// // Your program logic starts here... /// ``` +/// [`App::get_matches`]: ./struct.App.html#method.get_matches #[allow(missing_debug_implementations)] pub struct App<'a, 'b> where 'a: 'b @@ -80,10 +81,10 @@ impl<'a, 'b> App<'a, 'b> { App { p: Parser::with_name(n.into()) } } - /// Creates a new instace of `App` from a .yml (YAML) file. A full example of supported YAML - /// objects can be found in `examples/17_yaml.rs` and `examples/17_yaml.yml`. One great use for - /// using YAML is when supporting multiple languages and dialects, as each language could be a - /// distinct YAML file and determined at compiletime via `cargo` "features" in your + /// Creates a new instace of [`App`] from a .yml (YAML) file. A full example of supported YAML + /// objects can be found in [`examples/17_yaml.rs`] and [`examples/17_yaml.yml`]. One great use + /// for using YAML is when supporting multiple languages and dialects, as each language could + /// be a distinct YAML file and determined at compiletime via `cargo` "features" in your /// `Cargo.toml` /// /// In order to use this function you must compile `clap` with the `features = ["yaml"]` in @@ -95,14 +96,14 @@ impl<'a, 'b> App<'a, 'b> { /// /// # Panics /// - /// The YAML file must be properly formatted or this function will panic!(). A good way to + /// The YAML file must be properly formatted or this function will [`panic!`]. A good way to /// ensure this doesn't happen is to run your program with the `--help` switch. If this passes /// without error, you needn't worry because the YAML is properly formatted. /// /// # Examples /// /// The following example shows how to load a properly formatted YAML file to build an instnace - /// of an `App` struct. + /// of an [`App`] struct. /// /// ```ignore /// # use clap::App; @@ -111,6 +112,10 @@ impl<'a, 'b> App<'a, 'b> { /// /// // continued logic goes here, such as `app.get_matches()` etc. /// ``` + /// [`App`]: ./struct.App.html + /// [`examples/17_yaml.rs`]: https://github.com/kbknapp/clap-rs/blob/master/examples/17_yaml.rs + /// [`examples/17_yaml.yml`]: https://github.com/kbknapp/clap-rs/blob/master/examples/17_yaml.yml + /// [`panic!`]: https://doc.rust-lang.org/std/macro.panic!.html #[cfg(feature = "yaml")] pub fn from_yaml(yaml: &'a Yaml) -> App<'a, 'a> { App::from(yaml) @@ -120,9 +125,9 @@ impl<'a, 'b> App<'a, 'b> { /// request the help information with `--help` or `-h`. /// /// **Pro-tip:** If you turn on unstable features you can use `clap`s - /// convienience macro `crate_authors!` to automatically set your + /// convienience macro [`crate_authors!`] to automatically set your /// application's author to the same thing as your crate at compile time. - /// See the `examples/` + /// See the [`examples/`] /// directory for more information /// /// # Examples @@ -133,6 +138,8 @@ impl<'a, 'b> App<'a, 'b> { /// .author("Me, me@mymain.com") /// # ; /// ``` + /// [`crate_authors!`]: ./macro.crate_authors!.html + /// [`examples/`]: https://github.com/kbknapp/clap-rs/tree/master/examples pub fn author>(mut self, author: S) -> Self { self.p.meta.author = Some(author.into()); self @@ -145,7 +152,7 @@ impl<'a, 'b> App<'a, 'b> { /// **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. + /// **NOTE:** This command **should not** be used for [`SubCommand`]s. /// /// # Examples /// @@ -155,6 +162,7 @@ impl<'a, 'b> App<'a, 'b> { /// .bin_name("my_binary") /// # ; /// ``` + /// [`SubCommand`]: ./struct.SubCommand.html pub fn bin_name>(mut self, name: S) -> Self { self.p.meta.bin_name = Some(name.into()); self @@ -213,8 +221,8 @@ impl<'a, 'b> App<'a, 'b> { /// Sets a string of the version number to be displayed when displaying version or help /// information. /// - /// **Pro-tip:** Use `clap`s convienience macro `crate_version!` to automatically set your - /// application's version to the same thing as your crate at compile time. See the `examples/` + /// **Pro-tip:** Use `clap`s convienience 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 @@ -225,6 +233,8 @@ impl<'a, 'b> App<'a, 'b> { /// .version("v0.1.24") /// # ; /// ``` + /// [`crate_authors!`]: ./macro.crate_authors!.html + /// [`examples/`]: https://github.com/kbknapp/clap-rs/tree/master/examples pub fn version>(mut self, ver: S) -> Self { self.p.meta.version = Some(ver.into()); self @@ -233,7 +243,7 @@ impl<'a, 'b> App<'a, 'b> { /// 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` + /// 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! @@ -253,6 +263,7 @@ impl<'a, 'b> App<'a, 'b> { /// .usage("myapp [-clDas] ") /// # ; /// ``` + /// [`ArgMatches::usage`]: ./struct.ArgMatches.html#method.usage pub fn usage>(mut self, usage: S) -> Self { self.p.meta.usage_str = Some(usage.into()); self @@ -267,7 +278,7 @@ impl<'a, 'b> App<'a, 'b> { /// /// **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 `.help()` for them as well. + /// specify a [`Arg::help`] for them as well. /// /// # Examples /// @@ -291,19 +302,23 @@ impl<'a, 'b> App<'a, 'b> { /// work Do some work") /// # ; /// ``` + /// [`Arg::help`]: ./struct.Arg.html#method.help pub fn help>(mut self, help: S) -> Self { self.p.meta.help_str = Some(help.into()); self } - /// Sets the short version of the `help` argument without the preceding `-`. + /// Sets the [`short`] for the auto-generated `help` argument. /// - /// By default `clap` automatically assigns `h`, but this can be overridden 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. + /// 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 `-` chacter will be used as the `short` version + /// non `-` chacter will be used as the [`short`] version /// /// # Examples /// @@ -313,16 +328,20 @@ impl<'a, 'b> App<'a, 'b> { /// .help_short("H") // Using an uppercase `H` instead of the default lowercase `h` /// # ; /// ``` + /// [`short`]: ./struct.Arg.html#method.short pub fn help_short + 'b>(mut self, s: S) -> Self { self.p.help_short(s.as_ref()); self } - /// Sets the short version of the `version` argument without the preceding `-`. + /// Sets the [`short`] for the auto-generated `version` argument. /// - /// By default `clap` automatically assigns `V`, but this can be overridden by defining your - /// own argument with a uppercase `V` as the `short`. `clap` lazily generates these version - /// arguments **after** you've defined any arguments of your own. + /// 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 `-` chacter will be used as the `short` version @@ -335,6 +354,7 @@ impl<'a, 'b> App<'a, 'b> { /// .version_short("v") // Using a lowercase `v` instead of the default capital `V` /// # ; /// ``` + /// [`short`]: ./struct.Arg.html#method.short pub fn version_short>(mut self, s: S) -> Self { self.p.version_short(s.as_ref()); self @@ -373,9 +393,9 @@ impl<'a, 'b> App<'a, 'b> { self } - /// Enables a single Application level settings. + /// Enables a single command, or [`SubCommand`], level settings. /// - /// See `AppSettings` for a full list of possibilities and examples. + /// See [`AppSettings`] for a full list of possibilities and examples. /// /// # Examples /// @@ -386,14 +406,16 @@ impl<'a, 'b> App<'a, 'b> { /// .setting(AppSettings::WaitOnError) /// # ; /// ``` + /// [`SubCommand`]: ./struct.SubCommand.html + /// [`AppSettings`]: ./enum.AppSettings.html pub fn setting(mut self, setting: AppSettings) -> Self { self.p.set(setting); self } - /// Enables multiple Application level settings + /// Enables multiple command, or [`SubCommand`], level settings /// - /// See `AppSettings` for a full list of possibilities and examples. + /// See [`AppSettings`] for a full list of possibilities and examples. /// /// # Examples /// @@ -404,6 +426,8 @@ impl<'a, 'b> App<'a, 'b> { /// AppSettings::WaitOnError]) /// # ; /// ``` + /// [`SubCommand`]: ./struct.SubCommand.html + /// [`AppSettings`]: ./enum.AppSettings.html pub fn settings(mut self, settings: &[AppSettings]) -> Self { for s in settings { self.p.set(*s); @@ -411,7 +435,7 @@ impl<'a, 'b> App<'a, 'b> { self } - /// Adds an argument to the list of valid possibilties. + /// Adds an [argument] to the list of valid possibilties. /// /// # Examples /// @@ -431,12 +455,13 @@ impl<'a, 'b> App<'a, 'b> { /// ) /// # ; /// ``` + /// [argument]: ./struct.Arg.html pub fn arg> + 'a>(mut self, a: A) -> Self { self.p.add_arg(a.borrow()); self } - /// Adds multiple arguments to the list of valid possibilties + /// Adds multiple [arguments] to the list of valid possibilties /// /// # Examples /// @@ -449,6 +474,7 @@ impl<'a, 'b> App<'a, 'b> { /// ) /// # ; /// ``` + /// [arguments]: ./struct.Arg.html pub fn args(mut self, args: &[Arg<'a, 'b>]) -> Self { for arg in args { self.p.add_arg(arg); @@ -456,11 +482,11 @@ impl<'a, 'b> App<'a, 'b> { self } - /// A convienience method for adding a single argument from a usage type string. The string - /// used follows the same rules and syntax as `Arg::from_usage()` + /// A convienience 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. + /// properties of the [`Arg`] other than what [`Arg::from_usage`] supports. /// /// # Examples /// @@ -470,16 +496,19 @@ impl<'a, 'b> App<'a, 'b> { /// .arg_from_usage("-c --config= 'Sets a configuration file to use'") /// # ; /// ``` + /// [arguments]: ./struct.Arg.html + /// [`Arg`]: ./struct.Arg.html + /// [`Arg::from_usage`]: ./struct.Arg.html#method.from_usage pub fn arg_from_usage(mut self, usage: &'a str) -> Self { self.p.add_arg(&Arg::from_usage(usage)); 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. + /// 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. + /// **NOTE:** Like [`App::arg_from_usage`] the downside is you only set properties for the + /// [`Arg`]s which [`Arg::from_usage`] supports. /// /// # Examples /// @@ -493,6 +522,10 @@ impl<'a, 'b> App<'a, 'b> { /// ) /// # ; /// ``` + /// [arguments]: ./struct.Arg.html + /// [`Arg::from_usage`]: ./struct.Arg.html#method.from_usage + /// [`App::arg_from_usage`]: ./struct.App.html#method.arg_from_usage + /// [`Arg`]: ./struct.Arg.html pub fn args_from_usage(mut self, usage: &'a str) -> Self { for line in usage.lines() { let l = line.trim(); @@ -504,10 +537,10 @@ impl<'a, 'b> App<'a, 'b> { 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 existing of this command, - /// and not all vairants. + /// 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 existing of + /// this command, and not all vairants. /// /// # Examples /// @@ -519,6 +552,7 @@ impl<'a, 'b> App<'a, 'b> { /// .get_matches_from(vec!["myprog", "do-stuff"]); /// assert_eq!(m.subcommand_name(), Some("test")); /// ``` + /// [`SubCommand`]: ./struct.SubCommand.html pub fn alias>(mut self, name: S) -> Self { if let Some(ref mut als) = self.p.meta.aliases { als.push(name.into()); @@ -528,10 +562,10 @@ impl<'a, 'b> App<'a, 'b> { 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 existing of this command, - /// and not all vairants. + /// 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 existing of + /// this command, and not all vairants. /// /// # Examples /// @@ -547,6 +581,7 @@ impl<'a, 'b> App<'a, 'b> { /// .get_matches_from(vec!["myprog", "do-tests"]); /// assert_eq!(m.subcommand_name(), Some("test")); /// ``` + /// [`SubCommand`]: ./struct.SubCommand.html pub fn aliases(mut self, names: &[&'b str]) -> Self { if let Some(ref mut als) = self.p.meta.aliases { for n in names { @@ -558,24 +593,25 @@ impl<'a, 'b> App<'a, 'b> { 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. + /// 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. + /// 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 benfit of `ArgGroup`s is that you can extract a value from a group instead of - /// determining exactly which argument was used. + /// Another added benfit 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 + /// 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. + /// 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. /// /// ```no_run /// # use clap::{App, ArgGroup}; @@ -590,12 +626,13 @@ impl<'a, 'b> App<'a, 'b> { /// .required(true)) /// # ; /// ``` + /// [`ArgGroup`]: ./struct.ArgGroup.html pub fn group(mut self, group: ArgGroup<'a>) -> Self { self.p.add_group(group); self } - /// Adds multiple `ArgGroup`s to the application at once. + /// Adds multiple [`ArgGroup`]s to the [`App`] at once. /// /// # Examples /// @@ -618,6 +655,8 @@ impl<'a, 'b> App<'a, 'b> { /// ]) /// # ; /// ``` + /// [`ArgGroup`]: ./struct.ArgGroup.html + /// [`App`]: ./struct.App.html pub fn groups(mut self, groups: &[ArgGroup<'a>]) -> Self { for g in groups { self = self.group(g.into()); @@ -625,10 +664,10 @@ impl<'a, 'b> App<'a, 'b> { self } - /// Adds a subcommand to the list of valid possibilties. Subcommands are effectively sub-apps, - /// because they can contain their own arguments, subcommands, version, usage, etc. They also - /// function just like apps, in that they get their own auto generated help, version, and - /// usage. + /// Adds a [`SubCommand`] to the list of valid possibilties. 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 /// @@ -640,17 +679,19 @@ impl<'a, 'b> App<'a, 'b> { /// .arg_from_usage(" 'Required configuration file to use'")) /// # ; /// ``` + /// [`SubCommand`]: ./struct.SubCommand.html + /// [`App`]: ./struct.App.html pub fn subcommand(mut self, subcmd: App<'a, 'b>) -> Self { self.p.add_subcommand(subcmd); self } - /// Adds multiple subcommands to the list of valid possibilties by iterating over a Vec of - /// `SubCommand`s + /// Adds multiple subcommands to the list of valid possibilties by iterating over an + /// [`IntoIterator`] of [`SubCommand`]s /// /// # Examples /// - /// ```no_run + /// ```rust /// # use clap::{App, Arg, SubCommand}; /// # App::new("myprog") /// .subcommands( vec![ @@ -659,6 +700,8 @@ impl<'a, 'b> App<'a, 'b> { /// SubCommand::with_name("debug").about("Controls debug functionality")]) /// # ; /// ``` + /// [`SubCommand`]: ./struct.SubCommand.html + /// [`IntoIterator`]: https://doc.rust-lang.org/std/iter/trait.IntoIterator.html pub fn subcommands(mut self, subcmds: I) -> Self where I: IntoIterator> { @@ -668,7 +711,7 @@ impl<'a, 'b> App<'a, 'b> { self } - /// Allows custom ordering of subcommands within the help message. Subcommands with a lower + /// 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 @@ -714,44 +757,49 @@ impl<'a, 'b> App<'a, 'b> { /// beta I should be first! /// alpha Some help and text /// ``` + /// [`SubCommand`]: ./struct.SubCommand.html pub fn display_order(mut self, ord: usize) -> Self { self.p.meta.disp_ord = ord; self } - /// Prints the full help message to `io::stdout()` using a `BufWriter` + /// Prints the full help message to [`io::stdout()`] using a [`BufWriter`] /// /// # Examples /// - /// ```no_run + /// ```rust /// # use clap::App; /// let 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 pub fn print_help(&self) -> ClapResult<()> { let out = io::stdout(); let mut buf_w = BufWriter::new(out.lock()); self.write_help(&mut buf_w) } - /// Writes the full help message to the user to a `io::Write` object + /// Writes the full help message to the user to a [`io::Write`] object /// /// # Examples /// - /// ```no_run + /// ```rust /// # use clap::App; /// use std::io; /// let mut app = App::new("myprog"); /// let mut out = io::stdout(); /// app.write_help(&mut out).ok().expect("failed to write to stdout"); /// ``` + /// [`io::Write`]: https://doc.rust-lang.org/std/io/trait.Write.html pub fn write_help(&self, w: &mut W) -> ClapResult<()> { Help::write_app_help(w, &self) } /// Starts the parsing process, upon a failed parse an error will be displayed to the user and - /// the process with exit with the appropriate error code. By default this method gets matches - /// from `env::args_os` + /// the process with 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 /// @@ -761,18 +809,18 @@ impl<'a, 'b> App<'a, 'b> { /// // Args and options go here... /// .get_matches(); /// ``` + /// [`env::args_os`]: https://doc.rust-lang.org/std/env/fn.args_os.html pub fn get_matches(self) -> ArgMatches<'a> { self.get_matches_from(&mut env::args_os()) } - /// Starts the parsing process. This method will return a `Result` type instead of exiting the - /// the process on failed parse. By default this method gets matches - /// from `env::args_os` + /// Starts the parsing process. This method will return a [`clap::Result`] type instead of exiting + /// the 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 an error, where the `kind` is a `ErrorKind::HelpDisplayed` - /// or `ErrorKind::VersionDisplayed` respectively. You must call `error.exit()` or - /// perform a `std::process::exit`. + /// 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 /// @@ -783,17 +831,25 @@ impl<'a, 'b> App<'a, 'b> { /// .get_matches_safe() /// .unwrap_or_else( |e| e.exit() ); /// ``` + /// [`env::args_os`]: https://doc.rust-lang.org/std/env/fn.args_os.html + /// [`ErrorKind::HelpDisplayed`]: ./enum.ErrorKind.html#variant.HelpDisplayed + /// [`ErrorKind::VersionDisplayed`]: ./enum.ErrorKind.html#variant.VersionDisplayed + /// [`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 pub fn get_matches_safe(self) -> ClapResult> { // Start the parsing self.get_matches_from_safe(&mut env::args_os()) } - /// Starts the parsing process. Like `App::get_matches` this method does not return a `Result` + /// 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. + /// 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 + /// [`AppSettings::NoBinaryName`] is used /// /// # Examples /// @@ -805,6 +861,10 @@ impl<'a, 'b> App<'a, 'b> { /// // 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 pub fn get_matches_from(mut self, itr: I) -> ArgMatches<'a> where I: IntoIterator, T: Into @@ -815,16 +875,16 @@ impl<'a, 'b> App<'a, 'b> { }) } - /// Starts the parsing process. A combination of `App::get_matches_from`, and - /// `App::get_matches_safe` + /// 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 an error, where the `kind` is a `ErrorKind::HelpDisplayed` - /// or `ErrorKind::VersionDisplayed` respectively. You must call `error.exit()` or - /// perform a `std::process::exit` yourself. + /// 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 + /// [`AppSettings::NoBinaryName`] is used /// /// # Examples /// @@ -837,6 +897,16 @@ impl<'a, 'b> App<'a, 'b> { /// .get_matches_from_safe(arg_vec) /// .unwrap_or_else( |e| { panic!("An error occurs: {}", e) }); /// ``` + /// [`App::get_matches_from`]: ./struct.App.html#method.get_matches_from + /// [`App::get_matches_safe`]: ./struct.App.html#method.get_matches_safe + /// [`ErrorKind::HelpDisplayed`]: ./enum.ErrorKind.html#variant.HelpDisplayed + /// [`ErrorKind::VersionDisplayed`]: ./enum.ErrorKind.html#variant.VersionDisplayed + /// [`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 pub fn get_matches_from_safe(mut self, itr: I) -> ClapResult> where I: IntoIterator, T: Into @@ -844,12 +914,12 @@ impl<'a, 'b> App<'a, 'b> { self.get_matches_from_safe_borrow(itr) } - /// 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* + /// 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 + /// [`AppSettings::NoBinaryName`] is used /// /// # Examples /// @@ -862,6 +932,9 @@ impl<'a, 'b> App<'a, 'b> { /// let matches = app.get_matches_from_safe_borrow(arg_vec) /// .unwrap_or_else( |e| { panic!("An error occurs: {}", e) }); /// ``` + /// [`App`]: ./struct.App.html + /// [`App::get_matches_from_safe`]: ./struct.App.html#method.get_matches_from_safe + /// [`AppSettings::NoBinaryName`]: ./enum.AppSettings.html#variant.NoBinaryName pub fn get_matches_from_safe_borrow(&mut self, itr: I) -> ClapResult> where I: IntoIterator, T: Into diff --git a/src/app/settings.rs b/src/app/settings.rs index ab19017b..752ddb27 100644 --- a/src/app/settings.rs +++ b/src/app/settings.rs @@ -77,16 +77,18 @@ impl AppFlags { } } -/// Application level settings, which affect how `App` operates +/// Application level settings, which affect how [`App`] operates /// /// **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 { - /// Allows subcommands to override all requirements of the parent command. For example - /// if you had a subcommand or top level application which had a required argument that - /// are only required as long as there is no subcommand present, using this setting would allow - /// you set those arguments to `required(true)` and yet receive no error so long as the user + /// Allows [`SubCommand`]s to override all requirements of the parent command. For example if you + /// had a subcommand or top level application which had a required argument that are only + /// required as long as there is no subcommand present, using this setting would allow you set + /// those arguments to [`Arg::required(true)`] and yet receive no error so long as the user /// uses a valid subcommand instead. /// /// **NOTE:** This defaults to false (using subcommand does *not* negate requirements) @@ -124,10 +126,13 @@ pub enum AppSettings { /// assert!(noerr.is_ok()); /// # ; /// ``` + /// [`Arg::required(true)`]: ./struct.Arg.html#method.required + /// [`SubCommand`]: ./struct.SubCommand.html SubcommandsNegateReqs, - /// Allows specifying that if no subcommand is present at runtime, error and exit gracefully + /// Allows specifying that if no [`SubCommand`] is present at runtime, error and exit + /// gracefully /// - /// **NOTE:** This defaults to false (subcommands do *not* need to be present) + /// **NOTE:** This defaults to `false` (subcommands do *not* need to be present) /// /// # Examples /// @@ -143,11 +148,12 @@ pub enum AppSettings { /// assert_eq!(err.unwrap_err().kind, ErrorKind::MissingSubcommand); /// # ; /// ``` + /// [`SubCommand`]: ./struct.SubCommand.html SubcommandRequired, /// Specifies that the help text should be displayed (and then exit gracefully), if no /// arguments are present at runtime (i.e. an empty run such as, `$ myprog`. /// - /// **NOTE:** Subcommands count as arguments + /// **NOTE:** [`SubCommand`]s count as arguments /// /// # Examples /// @@ -157,9 +163,10 @@ pub enum AppSettings { /// .setting(AppSettings::ArgRequiredElseHelp) /// # ; /// ``` + /// [`SubCommand`]: ./struct.SubCommand.html ArgRequiredElseHelp, - /// Specifies to version of the current command for all child subcommands. (Defaults to false; - /// subcommands have independant version strings from their parents) + /// Specifies to use the version of the current command for all child [`SubCommand`]. (Defaults + /// to `false`; subcommands have independant version strings from their parents) /// /// **NOTE:** The version for the current command **and** this setting must be set **prior** to /// adding any child subcommands @@ -176,9 +183,10 @@ pub enum AppSettings { /// // running `$ myprog test --version` will display /// // "myprog-test v1.1" /// ``` + /// [`SubCommand`]: ./struct.SubCommand.html GlobalVersion, - /// Disables `-V` and `--version` for all subcommands (Defaults to false; subcommands have - /// version flags) + /// Disables `-V` and `--version` for all [`SubCommand`]s (Defaults to `false`; subcommands + /// *do* have version flags) /// /// **NOTE:** This setting must be set **prior** adding any subcommands /// @@ -196,9 +204,12 @@ pub enum AppSettings { /// assert!(res.is_err()); /// assert_eq!(res.unwrap_err().kind, ErrorKind::UnknownArgument); /// ``` + /// [`SubCommand`]: ./struct.SubCommand.html VersionlessSubcommands, /// Groups flags and options together presenting a more unified help message (a la `getopts` or - /// `docopt` style). The default is the auto-generated help message groups flags, options + /// `docopt` style). + /// + /// The default is that the auto-generated help message will group flags, and options /// separately. /// /// **NOTE:** This setting is cosmetic only and does not affect any functionality. @@ -220,7 +231,7 @@ pub enum AppSettings { /// Windows where a user tries to open the binary by double-clicking instead of using the /// command line. /// - /// **NOTE:** This setting is **not** recursive with subcommands, meaning if you wish this + /// **NOTE:** This setting is **not** recursive with [`SubCommand`]s, meaning if you wish this /// behavior for all subcommands, you must set this on each command (needing this is extremely /// rare) /// @@ -232,16 +243,17 @@ pub enum AppSettings { /// .setting(AppSettings::WaitOnError) /// # ; /// ``` + /// [`SubCommand`]: ./struct.SubCommand.html WaitOnError, /// Specifies that the help text should be displayed (and then exit gracefully), if no - /// subcommands are present at runtime (i.e. an empty run such as, `$ myprog`. + /// [`SubCommand`]s are present at runtime (i.e. an empty run such as, `$ myprog`. /// - /// **NOTE:** This should *not* be used with `.subcommand_required()` as they do the same - /// thing, except this prints the help text, and the other prints an error. + /// **NOTE:** This should *not* be used with [`AppSettings::SubcommandRequired`] as they do + /// nearly same thing; this prints the help text, and the other prints an error. /// /// **NOTE:** If the user specifies arguments at runtime, but no subcommand the help text will /// still be displayed and exit. If this is *not* the desired result, consider using - /// `ArgRequiredElseHelp` instead. + /// [`AppSettings::ArgRequiredElseHelp`] instead. /// /// # Examples /// @@ -251,8 +263,11 @@ pub enum AppSettings { /// .setting(AppSettings::SubcommandRequiredElseHelp) /// # ; /// ``` + /// [`SubCommand`]: ./struct.SubCommand.html + /// [`AppSettings::SubcommandRequired`]: ./enum.AppSettings.html#variant.SubcommandRequired + /// [`AppSettings::ArgRequiredElseHelp`]: ./enum.AppSettings.html#variant.ArgRequiredElseHelp SubcommandRequiredElseHelp, - /// Specifies that this subcommand should be hidden from help messages + /// Specifies that this [`SubCommand`] should be hidden from help messages /// /// # Examples /// @@ -263,14 +278,15 @@ pub enum AppSettings { /// .setting(AppSettings::Hidden)) /// # ; /// ``` + /// [`SubCommand`]: ./struct.SubCommand.html Hidden, /// Specifies that the final positional argument is a "VarArg" and that `clap` should not /// attempt to parse any further args. /// /// The values of the trailing positional argument will contain all args from itself on. /// - /// **NOTE:** The final positional argument **must** have `.multiple(true)` or the usage string - /// equivalent. + /// **NOTE:** The final positional argument **must** have [`Arg::multiple(true)`] or the usage + /// string equivalent. /// /// # Examples /// @@ -284,6 +300,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 TrailingVarArg, /// Specifies that the parser should not assume the first argument passed is the binary name. /// This is normally the case when using a "daemon" style mode, or an interactive CLI where one @@ -302,13 +319,14 @@ pub enum AppSettings { /// assert_eq!(cmds, ["command", "set"]); /// ``` NoBinaryName, - /// Specifies that an unexpected argument positional arguments which would otherwise cause a - /// `ErrorKind::UnknownArgument` error, should instead be treated as a subcommand in the - /// `ArgMatches` struct. + /// Specifies that an unexpected positional argument, which would otherwise cause a + /// [`ErrorKind::UnknownArgument`] error, should instead be treated as a [`SubCommand`] within + /// the [`ArgMatches`] struct. /// /// **NOTE:** Use this setting with caution, as a truly unexpected argument (i.e. one that is - /// *NOT* an external subcommand) will not cause an error and instead be treatd as a potential - /// subcommand. You shoud inform the user appropriatly. + /// *NOT* an external subcommand) will **not** cause an error and instead be treatd as a + /// potential subcommand. One should check for such cases manually and inform the user + /// appropriatly. /// /// # Examples /// @@ -331,12 +349,15 @@ pub enum AppSettings { /// _ => {}, /// } /// ``` + /// [`ErrorKind::UnknownArgument`]: ./enum.ErrorKind.html#variant.UnknownArgument + /// [`SubCommand`]: ./struct.SubCommand.html + /// [`ArgMatches`]: ./struct.ArgMatches.html AllowExternalSubcommands, /// Specifies that any invalid UTF-8 code points should be treated as an error and fail - /// with a `ErrorKind::InvalidUtf8` error. + /// with a [`ErrorKind::InvalidUtf8`] error. /// - /// **NOTE:** This rule only applies to argument values, as flags, options, and subcommands - /// themselves only allow valid UTF-8 code points. + /// **NOTE:** This rule only applies to argument values. Things such as flags, options, and + /// [`SubCommand`]s themselves only allow valid UTF-8 code points. /// /// # Platform Specific /// @@ -360,16 +381,19 @@ pub enum AppSettings { /// assert_eq!(m.unwrap_err().kind, ErrorKind::InvalidUtf8); /// } /// ``` + /// [`SubCommand`]: ./struct.SubCommand.html + /// [`ErrorKind::InvalidUtf8`]: ./enum.ErrorKind.html#variant.InvalidUtf8 StrictUtf8, /// Specifies that any invalid UTF-8 code points should *not* be treated as an error. This is /// the default behavior of `clap` /// - /// **NOTE:** Using argument values with invalid UTF-8 code points requires using Either - /// `ArgMatches::os_value(s)_of` or `ArgMatches::lossy_value(s)_of` for those particular - /// arguments which may contain invalid UTF-8 values + /// **NOTE:** Using argument values with invalid UTF-8 code points requires using + /// [`ArgMatches::os_value_of`], [`ArgMatches::os_values_of`], [`ArgMatches::lossy_value_of`], + /// or [`ArgMatches::lossy_values_of`] for those particular arguments which may contain invalid + /// UTF-8 values /// - /// **NOTE:** This rule only applies to argument values, as flags, options, and subcommands - /// themselves only allow valid UTF-8 code points. + /// **NOTE:** This rule only applies to argument values, as flags, options, and + /// [`SubCommand`]s themselves only allow valid UTF-8 code points. /// /// # Platform Specific /// @@ -394,9 +418,13 @@ 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 AllowInvalidUtf8, /// Specifies that leading hyphens are allowed in argument *values*, such as negative numbers - /// `-10` + /// `-10` (which would otherwise be parsed as another flag or option) /// /// **NOTE:** This can only be set application wide and not on a per argument basis. /// @@ -425,8 +453,6 @@ pub enum AppSettings { HidePossibleValuesInHelp, /// Places the help string for all arguments on the line after the argument /// - /// **NOTE:** This setting is cosmetic only and does not affect any functionality. - /// /// # Examples /// /// ```no_run @@ -436,7 +462,7 @@ pub enum AppSettings { /// .get_matches(); /// ``` NextLineHelp, - /// Displays the arguments and subcommands in the help message in the order that they were + /// Displays the arguments and [`SubCommand`]s in the help message in the order that they were /// declared in, vice alphabetically which is the default. /// /// # Examples @@ -447,6 +473,7 @@ pub enum AppSettings { /// .setting(AppSettings::DeriveDisplayOrder) /// .get_matches(); /// ``` + /// [`SubCommand`]: ./struct.SubCommand.html DeriveDisplayOrder, /// Uses colorized help messages. /// diff --git a/src/args/arg.rs b/src/args/arg.rs index 83fe8eb4..cb0e74fa 100644 --- a/src/args/arg.rs +++ b/src/args/arg.rs @@ -12,7 +12,7 @@ use args::settings::{ArgFlags, ArgSettings}; /// The abstract representation of a command line argument. Used to set all the options and /// relationships that define a valid argument for the program. /// -/// There are two methods for constructing `Arg`s, using the builder pattern and setting options +/// There are two methods for constructing [`Arg`]s, using the builder pattern and setting options /// manually, or using a usage string which is far less verbose but has fewer options. You can also /// use a combination of the two methods to achieve the best of both worlds. /// @@ -30,6 +30,7 @@ use args::settings::{ArgFlags, ArgSettings}; /// // Using a usage string (setting a similar argument to the one above) /// let input = Arg::from_usage("-i, --input=[FILE] 'Provides an input file to the program'"); /// ``` +/// [`Arg`]: ./struct.Arg.html #[allow(missing_debug_implementations)] pub struct Arg<'a, 'b> where 'a: 'b @@ -105,11 +106,11 @@ impl<'a, 'b> Default for Arg<'a, 'b> { impl<'a, 'b> Arg<'a, 'b> { - /// Creates a new instance of `Arg` using a unique string name. The name will be used to get + /// Creates a new instance of [`Arg`] using a unique string name. The name will be used to get /// information about whether or not the argument was used at runtime, get values, set /// relationships with other args, etc.. /// - /// **NOTE:** In the case of arguments that take values (i.e. `takes_value(true)`) + /// **NOTE:** In the case of arguments that take values (i.e. [`Arg::takes_value(true)`]) /// and positional arguments (i.e. those without a preceding `-` or `--`) the name will also /// be displayed when the user prints the usage/help information of the program. /// @@ -120,11 +121,13 @@ impl<'a, 'b> Arg<'a, 'b> { /// Arg::with_name("config") /// # ; /// ``` + /// [`Arg::takes_value(true)`]: ./struct.Arg.html#method.takes_value + /// [`Arg`]: ./struct.Arg.html pub fn with_name(n: &'a str) -> Self { Arg { name: n, ..Default::default() } } - /// Creates a new instance of `Arg` from a .yml (YAML) file. + /// Creates a new instance of [`Arg`] from a .yml (YAML) file. /// /// # Examples /// @@ -133,6 +136,7 @@ impl<'a, 'b> Arg<'a, 'b> { /// let yml = load_yaml!("arg.yml"); /// let arg = Arg::from_yaml(yml); /// ``` + /// [`Arg`]: ./struct.Arg.html #[cfg(feature = "yaml")] pub fn from_yaml<'y>(y: &'y BTreeMap) -> Arg<'y, 'y> { // We WANT this to panic on error...so expect() is good. @@ -229,14 +233,14 @@ impl<'a, 'b> Arg<'a, 'b> { a } - /// Creates a new instance of `Arg` from a usage string. Allows creation of basic settings for - /// the `Arg`. The syntax is flexible, but there are some rules to follow. + /// Creates a new instance of [`Arg`] from a usage string. Allows creation of basic settings + /// for the [`Arg`]. The syntax is flexible, but there are some rules to follow. /// /// **NOTE**: Not all settings may be set using the usage string method. Some properties are /// only available via the builder pattern. /// - /// **NOTE**: Only ASCII values in `from_usage` strings are officially supported. Some UTF-8 - /// codepoints may work just fine, but this is not guaranteed. + /// **NOTE**: Only ASCII values are officially supported in [`Arg::from_usage`] strings. Some + /// UTF-8 codepoints may work just fine, but this is not guaranteed. /// /// # Syntax /// @@ -358,6 +362,8 @@ impl<'a, 'b> Arg<'a, 'b> { /// ]) /// # ; /// ``` + /// [`Arg`]: ./struct.Arg.html + /// [`Arg::from_usage`]: ./struct.Arg.html#method.from_usage pub fn from_usage(u: &'a str) -> Self { let parser = UsageParser::from_usage(u); parser.parse() @@ -365,17 +371,18 @@ impl<'a, 'b> Arg<'a, 'b> { /// Sets the short version of the argument without the preceding `-`. /// - /// By default `clap` automatically assigns `V` and `h` to display version and help information - /// respectively. You may use `V` or `h` for your own purposes, in which case `clap` simply - /// will not assign those to the displaying of version or help. + /// By default `clap` automatically assigns `V` and `h` to the auto-generated `version` and + /// `help` arguments respectively. You may use the uppercase `V` or lowercase `h` for your own + /// arguments, in which case `clap` simply will not assign those to the auto-generated + /// `version` or `help` arguments. /// /// **NOTE:** Any leading `-` characters will be stripped, and only the first - /// non `-` character will be used as the `short` version + /// non `-` character will be used as the [`short`] version /// /// # Examples /// - /// To set `short` use a single valid UTF-8 codepoint. If you supply a leading `-` such as `-c` - /// it will be stripped. + /// To set [`short`] use a single valid UTF-8 code point. If you supply a leading `-` such as + /// `-c`, the `-` will be stripped. /// /// ```rust /// # use clap::{App, Arg}; @@ -384,7 +391,7 @@ impl<'a, 'b> Arg<'a, 'b> { /// # ; /// ``` /// - /// Setting `short` allows using the argument via a single hyphen (`-`) such as `-c` + /// Setting [`short`] allows using the argument via a single hyphen (`-`) such as `-c` /// /// ```rust /// # use clap::{App, Arg}; @@ -397,6 +404,7 @@ impl<'a, 'b> Arg<'a, 'b> { /// /// assert!(m.is_present("config")); /// ``` + /// [`short`]: ./struct.Arg.html#method.short pub fn short>(mut self, s: S) -> Self { self.short = s.as_ref().trim_left_matches(|c| c == '-').chars().nth(0); self @@ -404,10 +412,10 @@ impl<'a, 'b> Arg<'a, 'b> { /// Sets the long version of the argument without the preceding `--`. /// - /// By default `clap` automatically assigns `version` and `help` to display version and help - /// information respectively. You may use `version` or `help` for your own purposes, in which - /// case `clap` simply will not assign those to the displaying of version or help automatically, - /// and you will have to do so manually. + /// By default `clap` automatically assigns `version` and `help` to the auto-generated + /// `version` and `help` arguments respectively. You may use the word `version` or `help` for + /// the long form of your own arguments, in which case `clap` simply will not assign those to + /// the auto-generated `version` or `help` arguments. /// /// **NOTE:** Any leading `-` characters will be stripped /// @@ -432,7 +440,7 @@ impl<'a, 'b> Arg<'a, 'b> { /// .arg(Arg::with_name("cfg") /// .long("config")) /// .get_matches_from(vec![ - /// "shorttest", "--config" + /// "longtest", "--config" /// ]); /// /// assert!(m.is_present("cfg")); @@ -447,9 +455,11 @@ impl<'a, 'b> Arg<'a, 'b> { /// /// # Examples /// - /// Any valid `String` slice is allowed as help (i.e. only valid UTF-8). The one exception is - /// one wishes to include a newline in the help text. To include a newline **and** be properly - /// aligned with all other arguments help text, it must be specified via `{n}` instead of `\n`. + /// Any valid UTF-8 is allowed in the help text. The one exception is when one wishes to + /// include a newline in the help text and have the following text be properly aligned with all + /// the other help text. To include a newline **and** be properly aligned with all other + /// arguments help text, it must be specified via a tag inside curly braces, like so `{n}`. + /// Using the standard `\n` will produce a newline, but it will not be properly aligned. /// /// ```rust /// # use clap::{App, Arg}; @@ -461,7 +471,7 @@ impl<'a, 'b> Arg<'a, 'b> { /// Setting `help` displays a short message to the side of the argument when the user passes /// `-h` or `--help` (by default). /// - /// ```ignore + /// ```rust /// # use clap::{App, Arg}; /// let m = App::new("helptest") /// .arg(Arg::with_name("cfg") @@ -470,8 +480,6 @@ impl<'a, 'b> Arg<'a, 'b> { /// .get_matches_from(vec![ /// "shorttest", "--help" /// ]); - /// - /// // ... /// ``` /// /// The above example displays @@ -496,7 +504,10 @@ impl<'a, 'b> Arg<'a, 'b> { /// required, when no other conflicting rules have been evaluated. Conflicting rules take /// precedence over being required. **Default:** `false` /// - /// **NOTE:** Flags (i.e. not positional, or arguments that take values) cannot be required. + /// **NOTE:** Flags (i.e. not positional, or arguments that take values) cannot be required by + /// default. This is simply because if a flag should be required, it should simply be implied + /// as no additional information is required from user. Flags by their very nature are simply + /// yes/no, or true/false. /// /// # Examples /// @@ -507,7 +518,7 @@ impl<'a, 'b> Arg<'a, 'b> { /// # ; /// ``` /// - /// Setting `required(true)` requires that the argument be used at runtime. + /// Setting [`Arg::required(true)`] requires that the argument be used at runtime. /// /// ```rust /// # use clap::{App, Arg}; @@ -523,7 +534,7 @@ impl<'a, 'b> Arg<'a, 'b> { /// assert!(res.is_ok()); /// ``` /// - /// Setting `required(true)` and *not* supplying that argument is an error. + /// Setting [`Arg::required(true)`] and *not* supplying that argument is an error. /// /// ```rust /// # use clap::{App, Arg, ErrorKind}; @@ -539,6 +550,7 @@ impl<'a, 'b> Arg<'a, 'b> { /// assert!(res.is_err()); /// assert_eq!(res.unwrap_err().kind, ErrorKind::MissingRequiredArgument); /// ``` + /// [`Arg::required(true)`]: ./struct.Arg.html#method.required pub fn required(self, r: bool) -> Self { if r { self.set(ArgSettings::Required) @@ -550,7 +562,7 @@ impl<'a, 'b> Arg<'a, 'b> { /// Sets an arg that override this arg's required setting. (i.e. this arg will be required /// unless this other argument is present). /// - /// **Pro Tip:** Using `Arg::required_unless` implies `Arg::required` and is therefore not + /// **Pro Tip:** Using [`Arg::required_unless`] implies [`Arg::required`] and is therefore not /// mandatory to also set. /// /// # Examples @@ -562,9 +574,9 @@ impl<'a, 'b> Arg<'a, 'b> { /// # ; /// ``` /// - /// Setting `required_unless(name)` requires that the argument be used at runtime *unless* - /// `name` is present. In the following example, the required argument is *not* provided, but - /// it's not an error because the `unless` arg has been supplied. + /// Setting [`Arg::required_unless(name)`] requires that the argument be used at runtime + /// *unless* `name` is present. In the following example, the required argument is *not* + /// provided, but it's not an error because the `unless` arg has been supplied. /// /// ```rust /// # use clap::{App, Arg}; @@ -582,7 +594,7 @@ impl<'a, 'b> Arg<'a, 'b> { /// assert!(res.is_ok()); /// ``` /// - /// Setting `required_unless(name)` and *not* supplying `name` or this arg is an error. + /// Setting [`Arg::required_unless(name)`] and *not* supplying `name` or this arg is an error. /// /// ```rust /// # use clap::{App, Arg, ErrorKind}; @@ -600,6 +612,9 @@ impl<'a, 'b> Arg<'a, 'b> { /// assert!(res.is_err()); /// assert_eq!(res.unwrap_err().kind, ErrorKind::MissingRequiredArgument); /// ``` + /// [`Arg::required_unless`]: ./struct.Arg.html#method.required_unless + /// [`Arg::required`]: ./struct.Arg.html#method.required + /// [`Arg::required_unless(name)`]: ./struct.Arg.html#method.required_unless pub fn required_unless(mut self, name: &'a str) -> Self { if let Some(ref mut vec) = self.r_unless { vec.push(name); @@ -613,7 +628,7 @@ impl<'a, 'b> Arg<'a, 'b> { /// all these other argument are present). /// /// **NOTE:** If you wish for the this argument to only be required if *one of* these args are - /// present see `Arg::required_unless_one` + /// present see [`Arg::required_unless_one`] /// /// # Examples /// @@ -624,9 +639,10 @@ impl<'a, 'b> Arg<'a, 'b> { /// # ; /// ``` /// - /// Setting `required_unless_all(names)` requires that the argument be used at runtime *unless* - /// *all* the args in `names` are present. In the following example, the required argument is - /// *not* provided, but it's not an error because all the `unless` args have been supplied. + /// Setting [`Arg::required_unless_all(names)`] requires that the argument be used at runtime + /// *unless* *all* the args in `names` are present. In the following example, the required + /// argument is *not* provided, but it's not an error because all the `unless` args have been + /// supplied. /// /// ```rust /// # use clap::{App, Arg}; @@ -647,8 +663,8 @@ impl<'a, 'b> Arg<'a, 'b> { /// assert!(res.is_ok()); /// ``` /// - /// Setting `required_unless_all(names)` and *not* supplying *all* of `names` or this arg is an - /// error. + /// Setting [`Arg::required_unless_all(names)`] and *not* supplying *all* of `names` or this + /// arg is an error. /// /// ```rust /// # use clap::{App, Arg, ErrorKind}; @@ -669,6 +685,8 @@ impl<'a, 'b> Arg<'a, 'b> { /// assert!(res.is_err()); /// assert_eq!(res.unwrap_err().kind, ErrorKind::MissingRequiredArgument); /// ``` + /// [`Arg::required_unless_one`]: ./struct.Arg.html#method.required_unless_one + /// [`Arg::required_unless_all(names)`]: ./struct.Arg.html#method.required_unless_all pub fn required_unless_all(mut self, names: &[&'a str]) -> Self { if let Some(ref mut vec) = self.r_unless { for s in names { @@ -681,11 +699,11 @@ impl<'a, 'b> Arg<'a, 'b> { self.required(true) } - /// Sets args that override this arg's required setting. (i.e. this arg will be required unless - /// *at least one of* these other argument are present). + /// Sets args that override this arg's [required] setting. (i.e. this arg will be required + /// unless *at least one of* these other argument are present). /// /// **NOTE:** If you wish for the this argument to only be required if *all of* these args are - /// present see `Arg::required_unless_all` + /// present see [`Arg::required_unless_all`] /// /// # Examples /// @@ -696,10 +714,10 @@ impl<'a, 'b> Arg<'a, 'b> { /// # ; /// ``` /// - /// Setting `required_unless_one(names)` requires that the argument be used at runtime *unless* - /// *at least one of* the args in `names` are present. In the following example, the required - /// argument is *not* provided, but it's not an error because one the `unless` args have been - /// supplied. + /// Setting [`Arg::required_unless_one(names)`] requires that the argument be used at runtime + /// *unless* *at least one of* the args in `names` are present. In the following example, the + /// required argument is *not* provided, but it's not an error because one the `unless` args + /// have been supplied. /// /// ```rust /// # use clap::{App, Arg}; @@ -720,8 +738,8 @@ impl<'a, 'b> Arg<'a, 'b> { /// assert!(res.is_ok()); /// ``` /// - /// Setting `required_unless_one(names)` and *not* supplying *at least one of* `names` or this - /// arg is an error. + /// Setting [`Arg::required_unless_one(names)`] and *not* supplying *at least one of* `names` + /// or this arg is an error. /// /// ```rust /// # use clap::{App, Arg, ErrorKind}; @@ -742,6 +760,9 @@ impl<'a, 'b> Arg<'a, 'b> { /// assert!(res.is_err()); /// assert_eq!(res.unwrap_err().kind, ErrorKind::MissingRequiredArgument); /// ``` + /// [required]: ./struct.Arg.html#method.required + /// [`Arg::required_unless_one(names)`]: ./struct.Arg.html#method.required_unless_one + /// [`Arg::required_unless_all`]: ./struct.Arg.html#method.required_unless_all pub fn required_unless_one(mut self, names: &[&'a str]) -> Self { if let Some(ref mut vec) = self.r_unless { for s in names { @@ -799,7 +820,7 @@ impl<'a, 'b> Arg<'a, 'b> { self } - /// The same as `Arg::conflicts_with` but allows specifying multiple two-way conlicts per + /// The same as [`Arg::conflicts_with`] but allows specifying multiple two-way conlicts per /// argument. /// /// **NOTE:** Conflicting rules take precedence over being required by default. Conflict rules @@ -839,6 +860,7 @@ impl<'a, 'b> Arg<'a, 'b> { /// assert!(res.is_err()); /// assert_eq!(res.unwrap_err().kind, ErrorKind::ArgumentConflict); /// ``` + /// [`Arg::conflicts_with`]: ./struct.Arg.html#method.conflicts_with pub fn conflicts_with_all(mut self, names: &[&'a str]) -> Self { if let Some(ref mut vec) = self.blacklist { for s in names { @@ -924,7 +946,7 @@ impl<'a, 'b> Arg<'a, 'b> { /// Sets an argument by name that is required when this one is present I.e. when /// using this argument, the following argument *must* be present. /// - /// **NOTE:** Conflicting rules and override rules take precedence over being required + /// **NOTE:** [Conflicting] rules and [override] rules take precedence over being required /// /// # Examples /// @@ -935,8 +957,9 @@ impl<'a, 'b> Arg<'a, 'b> { /// # ; /// ``` /// - /// Setting `requires("arg")` requires that the argument be used at runtime if the defining - /// argument is used. If the defining argument isn't used, the other arguemnt isn't required + /// Setting [`Arg::requires(name)`] requires that the argument be used at runtime if the + /// defining argument is used. If the defining argument isn't used, the other arguemnt isn't + /// required /// /// ```rust /// # use clap::{App, Arg}; @@ -954,7 +977,7 @@ impl<'a, 'b> Arg<'a, 'b> { /// assert!(res.is_ok()); // We didn't use cfg, so input wasn't required /// ``` /// - /// Setting `requires("arg")` and *not* supplying that argument is an error. + /// Setting [`Arg::requires(name)`] and *not* supplying that argument is an error. /// /// ```rust /// # use clap::{App, Arg, ErrorKind}; @@ -972,6 +995,9 @@ impl<'a, 'b> Arg<'a, 'b> { /// 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 pub fn requires(mut self, name: &'a str) -> Self { if let Some(ref mut vec) = self.requires { vec.push(name); @@ -984,7 +1010,7 @@ impl<'a, 'b> Arg<'a, 'b> { /// Sets multiple arguments by names that are required when this one is present I.e. when /// using this argument, the following arguments *must* be present. /// - /// **NOTE:** Mutually exclusive and override rules take precedence over being required + /// **NOTE:** [Conflicting] rules and [override] rules take precedence over being required /// by default. /// /// # Examples @@ -996,9 +1022,9 @@ impl<'a, 'b> Arg<'a, 'b> { /// # ; /// ``` /// - /// Setting `requires_all(&["arg", "arg2"])` requires that all the arguments be used at runtime - /// if the defining argument is used. If the defining argument isn't used, the other arguemnt - /// isn't required + /// Setting [`Arg::requires_all(&[arg, arg2])`] requires that all the arguments be used at + /// runtime if the defining argument is used. If the defining argument isn't used, the other + /// arguemnt isn't required /// /// ```rust /// # use clap::{App, Arg}; @@ -1018,7 +1044,8 @@ impl<'a, 'b> Arg<'a, 'b> { /// assert!(res.is_ok()); // We didn't use cfg, so input and output weren't required /// ``` /// - /// Setting `requires_all(&["arg", "arg2"])` and *not* supplying all the arguments is an error. + /// Setting [`Arg::requires_all(&[arg, arg2])`] and *not* supplying all the arguments is an + /// error. /// /// ```rust /// # use clap::{App, Arg, ErrorKind}; @@ -1039,6 +1066,9 @@ impl<'a, 'b> Arg<'a, 'b> { /// // 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 + /// [`Arg::requires_all(&[arg, arg2])`]: ./struct.Arg.html#method.requires_all pub fn requires_all(mut self, names: &[&'a str]) -> Self { if let Some(ref mut vec) = self.requires { for s in names { @@ -1058,10 +1088,10 @@ impl<'a, 'b> Arg<'a, 'b> { /// * Using an equals and no space such as `-o=value` or `--option=value` /// * Use a short and no space such as `-ovalue` /// - /// **NOTE:** By default, values are delimted by commas, meaning `--option=val1,val2,val3` is - /// is three values for the `--option` argument. If you wish to change the delimiter to another - /// character you can use `Arg::value_delimiter(char)`, alternatively you can delimiting values - /// **OFF** by using `Arg::use_delimiter(false)` + /// **NOTE:** By default, args which allow [multiple values] are delimted by commas, meaning + /// `--option=val1,val2,val3` is is three values for the `--option` argument. If you wish to + /// change the delimiter to another character you can use [`Arg::value_delimiter(char)`], + /// alternatively you can delimiting values **OFF** by using [`Arg::use_delimiter(false)`] /// /// # Examples /// @@ -1083,6 +1113,9 @@ impl<'a, 'b> Arg<'a, 'b> { /// assert!(m.is_present("mode")); /// assert_eq!(m.value_of("mode"), Some("fast")); /// ``` + /// [`Arg::value_delimiter(char)`]: ./struct.Arg.html#method.value_delimiter + /// [`Arg::use_delimiter(false)`]: ./struct.Arg.html#method.use_delimiter + /// [multiple values]: ./struct.Arg.html#method.multiple pub fn takes_value(self, tv: bool) -> Self { if tv { self.set(ArgSettings::TakesValue) @@ -1096,18 +1129,18 @@ impl<'a, 'b> Arg<'a, 'b> { /// **NOTE:** The index refers to position according to **other positional argument**. It does /// not define position in the argument list as a whole. /// - /// **NOTE:** If no `short`, or `long` have been defined, you can optionally leave off the - /// `index` method, and the index will be assigned in order of evaluation. Utilizing the - /// `index` method allows for setting indexes out of order + /// **NOTE:** If no [`Arg::short`], or [`Arg::long`] have been defined, you can optionally + /// leave off the `index` method, and the index will be assigned in order of evaluation. + /// Utilizing the `index` method allows for setting indexes out of order /// - /// **NOTE:** When utilized with `multiple(true)`, only the **last** psoitional argument may - /// be defined as multiple (i.e. with the highest index) + /// **NOTE:** When utilized with [`Arg::multiple(true)`], only the **last** psoitional argument + /// may be defined as multiple (i.e. with the highest index) /// /// # Panics /// - /// Although not in this method directly, `App` will `panic!` if indexes are skipped (such as - /// defining `index(1)` and `index(3)` but not `index(2)`, or a positional argument is defined - /// as multiple and is not the highest index + /// Although not in this method directly, [`App`] will [`panic!`] if indexes are skipped (such + /// as defining `index(1)` and `index(3)` but not `index(2)`, or a positional argument is + /// defined as multiple and is not the highest index /// /// # Examples /// @@ -1131,6 +1164,11 @@ impl<'a, 'b> Arg<'a, 'b> { /// 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 + /// [`panic!`]: https://doc.rust-lang.org/std/macro.panic!.html pub fn index(mut self, idx: u64) -> Self { self.index = Some(idx); self @@ -1146,18 +1184,18 @@ impl<'a, 'b> Arg<'a, 'b> { /// /// **WARNING:** /// - /// Setting `multipe(true)` for an option allows multiple values **and** multiple occurrences - /// because it isn't possible to more occurrences than values for options. Because multiple - /// values are allowed, `--option val1 val2 val3` is perfectly valid, be careful when designing - /// a CLI where positional arguments are expectd after a option which accepts multiple values, - /// as `clap` will continue parsing *values* until it reaches the max or specific number of - /// values defined, or another flag or option. + /// Setting `multiple(true)` for an [option] with no other details, allows multiple values + /// **and** multiple occurrences because it isn't possible to more occurrences than values for + /// options. Because multiple values are allowed, `--option val1 val2 val3` is perfectly valid, + /// be careful when designing a CLI where positional arguments are expectd after a option which + /// accepts multiple values, as `clap` will continue parsing *values* until it reaches the max + /// or specific number of values defined, or another flag or option. /// /// **Pro Tip**: /// /// It's possible to define an option which allows multiple occurrences, but only one value per - /// occurrence. To do this use `Arg::number_of_values(1)` in coordination with - /// `Arg::multiple(true)`. + /// occurrence. To do this use [`Arg::number_of_values(1)`] in coordination with + /// [`Arg::multiple(true)`]. /// /// # Examples /// @@ -1260,8 +1298,9 @@ impl<'a, 'b> Arg<'a, 'b> { /// assert!(m.is_present("word")); /// assert_eq!(m.value_of("word"), Some("word")); /// ``` - /// As a final example, notice if we define `number_of_values(1)` and try to run the problem - /// example above, it would have been a runtime error with a pretty message to the user :) + /// As a final example, notice if we define [`Arg::number_of_values(1)`] and try to run the + /// problem example above, it would have been a runtime error with a pretty message to the + /// user :) /// /// ```rust /// # use clap::{App, Arg, ErrorKind}; @@ -1278,6 +1317,9 @@ impl<'a, 'b> Arg<'a, 'b> { /// assert!(res.is_err()); /// assert_eq!(res.unwrap_err().kind, ErrorKind::UnknownArgument); /// ``` + /// [option]: ./struct.Arg.html#method.takes_value + /// [`Arg::number_of_values(1)`]: ./struct.Arg.html#method.number_of_values + /// [`Arg::multiple(true)`]: ./struct.Arg.html#method.multiple pub fn multiple(self, multi: bool) -> Self { if multi { self.set(ArgSettings::Multiple) @@ -1286,16 +1328,16 @@ impl<'a, 'b> Arg<'a, 'b> { } } - /// Specifies that an argument can be matched to all child subcommands. + /// Specifies that an argument can be matched to all child [`SubCommand`]s. /// /// **NOTE:** Global arguments *only* propagate down, **not** up (to parent commands) /// - /// **NOTE:** Global arguments *cannot* be required. + /// **NOTE:** Global arguments *cannot* be [required]. /// /// **NOTE:** Global arguments, when matched, *only* exist in the command's matches that they /// were matched to. For example, if you defined a `--flag` global argument in the top most /// parent command, but the user supplied the arguments `top cmd1 cmd2 --flag` *only* `cmd2`'s - /// `ArgMatches` would return `true` if tested for `.is_present("flag")`. + /// [`ArgMatches`] would return `true` if tested for [`ArgMatches::is_present("flag")`]. /// /// # Examples /// @@ -1309,7 +1351,7 @@ impl<'a, 'b> Arg<'a, 'b> { /// /// For example, assume an appliction with two subcommands, and you'd like to define a /// `--verbose` flag that can be called on any of the subcommands and parent, but you don't - /// want to clutter the source with three duplicate `Arg` definitions. + /// want to clutter the source with three duplicate [`Arg`] definitions. /// /// ```rust /// # use clap::{App, Arg, SubCommand}; @@ -1326,6 +1368,11 @@ impl<'a, 'b> Arg<'a, 'b> { /// let sub_m = m.subcommand_matches("do-stuff").unwrap(); /// assert!(sub_m.is_present("verb")); /// ``` + /// [`SubCommand`]: ./struct.SubCommand.html + /// [required]: ./struct.Arg.html#method.required + /// [`ArgMatches`]: ./struct.ArgMatches.html + /// [`ArgMatches::is_present("flag")`]: ./struct.ArgMatches.html#method.is_present + /// [`Arg`]: ./struct.Arg.html pub fn global(self, g: bool) -> Self { if g { self.set(ArgSettings::Global) @@ -1339,7 +1386,7 @@ impl<'a, 'b> Arg<'a, 'b> { /// /// **NOTE:** Defaults to `true` (Explicitly empty values are allowed) /// - /// **NOTE:** Implicitly sets `takes_value(true)` when set to `false` + /// **NOTE:** Implicitly sets [`Arg::takes_value(true)`] when set to `false` /// /// # Examples /// @@ -1365,6 +1412,7 @@ impl<'a, 'b> Arg<'a, 'b> { /// assert!(res.is_err()); /// assert_eq!(res.unwrap_err().kind, ErrorKind::EmptyValue); /// ``` + /// [`Arg::takes_value(true)`]: ./struct.Arg.html#method.takes_value pub fn empty_values(mut self, ev: bool) -> Self { if ev { self.set(ArgSettings::EmptyValues) @@ -1388,7 +1436,7 @@ impl<'a, 'b> Arg<'a, 'b> { /// ``` /// Setting `hidden(true)` will hide the argument when displaying help text /// - /// ```ignore + /// ```rust /// # use clap::{App, Arg}; /// let m = App::new("helptest") /// .arg(Arg::with_name("cfg") @@ -1398,8 +1446,6 @@ impl<'a, 'b> Arg<'a, 'b> { /// .get_matches_from(vec![ /// "shorttest", "--help" /// ]); - /// - /// // ... /// ``` /// /// The above example displays @@ -1422,10 +1468,10 @@ impl<'a, 'b> Arg<'a, 'b> { } } - /// Specifies a list of possible values for this argument. At runtime, `clap` verifies that only - /// one of the specified values was used, or fails with an error message. + /// Specifies a list of possible values for this argument. At runtime, `clap` verifies that + /// only one of the specified values was used, or fails with an error message. /// - /// **NOTE:** This setting only applies to options and positional arguments + /// **NOTE:** This setting only applies to [options] and [positional arguments] /// /// # Examples /// @@ -1463,6 +1509,8 @@ impl<'a, 'b> Arg<'a, 'b> { /// 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 pub fn possible_values(mut self, names: &[&'b str]) -> Self { if let Some(ref mut vec) = self.possible_vals { for s in names { @@ -1477,6 +1525,8 @@ impl<'a, 'b> Arg<'a, 'b> { /// Specifies a possible value for this argument, one at a time. At runtime, `clap` verifies /// that only one of the specified values was used, or fails with error message. /// + /// **NOTE:** This setting only applies to [options] and [positional arguments] + /// /// # Examples /// /// ```rust @@ -1519,6 +1569,8 @@ impl<'a, 'b> Arg<'a, 'b> { /// 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 pub fn possible_value(mut self, name: &'b str) -> Self { if let Some(ref mut vec) = self.possible_vals { vec.push(name); @@ -1528,7 +1580,7 @@ impl<'a, 'b> Arg<'a, 'b> { self } - /// Specifies the name of the group the argument belongs to. + /// Specifies the name of the [`ArgGroup`] the argument belongs to. /// /// # Examples /// @@ -1555,6 +1607,7 @@ impl<'a, 'b> Arg<'a, 'b> { /// .get_matches_from(vec!["posvals", "--debug"]); /// assert!(m.is_present("mode")); /// ``` + /// [`ArgGroup`]: ./struct.ArgGroup.html pub fn group(mut self, name: &'a str) -> Self { self.group = Some(name); self @@ -1565,9 +1618,9 @@ impl<'a, 'b> Arg<'a, 'b> { /// `.number_of_values(3)`, and this argument wouldn't be satisfied unless the user provided /// 3 and only 3 values. /// - /// **NOTE:** Does *not* require `.multiple(true)` to be set. Setting `.multiple(true)` would - /// allow `-f -f ` where as *not* setting - /// `.multiple(true)` would only allow one occurrence of this argument. + /// **NOTE:** Does *not* require [`Arg::multiple(true)`] to be set. Setting + /// [`Arg::multiple(true)`] would allow `-f -f ` where + /// as *not* setting [`Arg::multiple(true)`] would only allow one occurrence of this argument. /// /// # Examples /// @@ -1593,22 +1646,23 @@ impl<'a, 'b> Arg<'a, 'b> { /// assert!(res.is_err()); /// assert_eq!(res.unwrap_err().kind, ErrorKind::WrongNumberOfValues); /// ``` + /// [`Arg::multiple(true)`]: ./struct.Arg.html#method.multiple pub fn number_of_values(mut self, qty: u64) -> Self { self.num_vals = Some(qty); self } - /// Allows one to perform a custom validation on the argument value. You provide a closure which - /// accepts a `String` value, a `Result` where the `Err(String)` is a message displayed to the - /// user. + /// Allows one to perform a custom validation on the argument value. You provide a closure + /// which accepts a [`String`] value, and return a [`Result`] where the [`Err(String)`] is a + /// message displayed to the user. /// /// **NOTE:** The error message does *not* need to contain the `error:` portion, only the /// message. /// /// **NOTE:** There is a small performance hit for using validators, as they are implemented - /// with `Rc` pointers. And the value to be checked will be allocated an extra time in order to - /// to be passed to the closure. This performance hit is extremely minimal in the grand scheme - /// of things. + /// with [`Rc`] pointers. And the value to be checked will be allocated an extra time in order + /// to to be passed to the closure. This performance hit is extremely minimal in the grand + /// scheme of things. /// /// # Examples /// @@ -1628,6 +1682,10 @@ impl<'a, 'b> Arg<'a, 'b> { /// 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 + /// [`Rc`]: https://doc.rust-lang.org/std/rc/struct.Rc.html pub fn validator(mut self, f: F) -> Self where F: Fn(String) -> Result<(), String> + 'static { @@ -1636,14 +1694,14 @@ impl<'a, 'b> Arg<'a, 'b> { } /// Specifies the *maximum* number of values are for this argument. For example, if you had a - /// `-f ` argument where you wanted up to 3 'files' you would set - /// `.max_values(3)`, and this argument would be satisfied if the user provided, 1, 2, or 3 - /// values. + /// `-f ` argument where you wanted up to 3 'files' you would set `.max_values(3)`, and + /// this argument would be satisfied if the user provided, 1, 2, or 3 values. /// - /// **NOTE:** This does not implicitly set `mulitple(true)`. This is because `-o val -o val` is - /// multiples occurrences but a single value and `-o val1 val2` is a single occurence with - /// multple values. For positional arguments this **does** set `multiple(true)` because there - /// is no way to determine the diffrence between multiple occureces and multiple values. + /// **NOTE:** This does *not* implicitly set [`Arg::mulitple(true)`]. This is because + /// `-o val -o val` is multiples occurrences but a single value and `-o val1 val2` is a single + /// occurence with multple values. For positional arguments this **does** set + /// [`Arg::multiple(true)`] because there is no way to determine the diffrence between multiple + /// occureces and multiple values. /// /// # Examples /// @@ -1686,6 +1744,7 @@ impl<'a, 'b> Arg<'a, 'b> { /// assert!(res.is_err()); /// assert_eq!(res.unwrap_err().kind, ErrorKind::TooManyValues); /// ``` + /// [`Arg::mulitple(true)`]: ./struct.Arg.html#method.multiple pub fn max_values(mut self, qty: u64) -> Self { self.max_vals = Some(qty); self @@ -1696,10 +1755,11 @@ impl<'a, 'b> Arg<'a, 'b> { /// `.min_values(2)`, and this argument would be satisfied if the user provided, 2 or more /// values. /// - /// **NOTE:** This does not implicitly set `mulitple(true)`. This is because `-o val -o val` is - /// multiples occurrences but a single value and `-o val1 val2` is a single occurence with - /// multple values. For positional arguments this **does** set `multiple(true)` because there - /// is no way to determine the diffrence between multiple occureces and multiple values. + /// **NOTE:** This does not implicitly set [`Arg::mulitple(true)`]. This is because + /// `-o val -o val` is multiples occurrences but a single value and `-o val1 val2` is a single + /// occurence with multple values. For positional arguments this **does** set + /// [`Arg::multiple(true)`] because there is no way to determine the diffrence between multiple + /// occureces and multiple values. /// /// # Examples /// @@ -1742,6 +1802,7 @@ impl<'a, 'b> Arg<'a, 'b> { /// assert!(res.is_err()); /// assert_eq!(res.unwrap_err().kind, ErrorKind::TooFewValues); /// ``` + /// [`Arg::mulitple(true)`]: ./struct.Arg.html#method.multiple pub fn min_values(mut self, qty: u64) -> Self { self.min_vals = Some(qty); self.set(ArgSettings::TakesValue) @@ -1753,7 +1814,7 @@ impl<'a, 'b> Arg<'a, 'b> { /// value delimiter for all arguments that accept values (options and positional arguments) /// /// **NOTE:** The defalt is `true`. Setting the value to `true` will reset any previous use of - /// `Arg::value_delimiter` back to the default of `,` (comma). + /// [`Arg::value_delimiter`] back to the default of `,` (comma). /// /// # Examples /// @@ -1792,6 +1853,7 @@ impl<'a, 'b> Arg<'a, 'b> { /// 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 pub fn use_delimiter(mut self, d: bool) -> Self { if d { self.val_delim = Some(','); @@ -1804,9 +1866,9 @@ impl<'a, 'b> Arg<'a, 'b> { /// Specifies the separator to use when values are clumped together, defaults to `,` (comma). /// - /// **NOTE:** implicitly sets `Arg::use_delimiter(true)` + /// **NOTE:** implicitly sets [`Arg::use_delimiter(true)`] /// - /// **NOTE:** implicitly sets `Arg::takes_value(true)` + /// **NOTE:** implicitly sets [`Arg::takes_value(true)`] /// /// # Examples /// @@ -1824,6 +1886,8 @@ impl<'a, 'b> Arg<'a, 'b> { /// /// assert_eq!(m.values_of("config").unwrap().collect::>(), ["val1", "val2", "val3"]) /// ``` + /// [`Arg::use_delimiter(true)`]: ./struct.Arg.html#method.use_delimiter + /// [`Arg::takes_value(true)`]: ./struct.Arg.html#method.takes_value pub fn value_delimiter(mut self, d: &str) -> Self { self = self.set(ArgSettings::TakesValue); self = self.set(ArgSettings::UseValueDelimiter); @@ -1842,16 +1906,16 @@ impl<'a, 'b> Arg<'a, 'b> { /// using, such as `FILE`, `INTERFACE`, etc. Although not required, it's somewhat convention to /// use all capital letters for the value name. /// - /// **Pro Tip:** It may help to use `Arg::next_line_help(true)` if there are long, or multiple - /// value names in order to not throw off the help text alignment of all options. + /// **Pro Tip:** It may help to use [`Arg::next_line_help(true)`] if there are long, or + /// multiple value names in order to not throw off the help text alignment of all options. /// - /// **NOTE:** This implicitly sets `.number_of_values()` if the number of value names is + /// **NOTE:** This implicitly sets [`Arg::number_of_values`] if the number of value names is /// greater than one. I.e. be aware that the number of "names" you set for the values, will be /// the *exact* number of values required to satisfy this argument /// - /// **NOTE:** implicitly sets `Arg::takes_value(true)` + /// **NOTE:** implicitly sets [`Arg::takes_value(true)`] /// - /// **NOTE:** Does *not* require or imply `.multiple(true)`. + /// **NOTE:** Does *not* require or imply [`Arg::multiple(true)`]. /// /// # Examples /// @@ -1888,6 +1952,10 @@ impl<'a, 'b> Arg<'a, 'b> { /// OPTIONS: /// --io-files 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 pub fn value_names(mut self, names: &[&'b str]) -> Self { self.setb(ArgSettings::TakesValue); if let Some(ref mut vals) = self.val_names { @@ -1906,13 +1974,13 @@ impl<'a, 'b> Arg<'a, 'b> { self } - /// Specifies the name for value of option or positional arguments inside of help documenation. - /// This name is cosmetic only, the name is **not** used to access arguments. This setting can - /// be very helpful when describing the type of input the user should be using, such as `FILE`, - /// `INTERFACE`, etc. Although not required, it's somewhat convention to use all capital - /// letters for the value name. + /// Specifies the name for value of [option] or [positional] arguments inside of help + /// documenation. This name is cosmetic only, the name is **not** used to access arguments. + /// This setting can be very helpful when describing the type of input the user should be + /// using, such as `FILE`, `INTERFACE`, etc. Although not required, it's somewhat convention to + /// use all capital letters for the value name. /// - /// **NOTE:** implicitly sets `Arg::takes_value(true)` + /// **NOTE:** implicitly sets [`Arg::takes_value(true)`] /// /// # Examples /// @@ -1949,6 +2017,9 @@ impl<'a, 'b> Arg<'a, 'b> { /// OPTIONS: /// --config 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 pub fn value_name(mut self, name: &'b str) -> Self { self.setb(ArgSettings::TakesValue); if let Some(ref mut vals) = self.val_names { @@ -1964,15 +2035,15 @@ impl<'a, 'b> Arg<'a, 'b> { /// Specifies the value of the argument when *not* specified at runtime. /// - /// **NOTE:** If the user *does not* use this argument at runtime, `ArgMatches::occurrences_of` - /// will return `0` even though the `value_of` will return the default specified. + /// **NOTE:** If the user *does not* use this argument at runtime, [`ArgMatches::occurrences_of`] + /// will return `0` even though the [`ArgMatches::value_of`] will return the default specified. /// - /// **NOTE:** If the user *does not* use this argument at runtime `ArgMatches::is_present` will + /// **NOTE:** If the user *does not* use this argument at runtime [`ArgMatches::is_present`] will /// still return `true`. If you wish to determine whether the argument was used at runtime or - /// not, consider `ArgMatches::occurrences_of` which will return `0` if the argument was *not* + /// not, consider [`ArgMatches::occurrences_of`] which will return `0` if the argument was *not* /// used at runtmie. /// - /// **NOTE:** This implicitly sets `Arg::takes_value(true)`. + /// **NOTE:** This implicitly sets [`Arg::takes_value(true)`]. /// /// # Examples /// @@ -1990,6 +2061,10 @@ impl<'a, 'b> Arg<'a, 'b> { /// assert!(m.is_present("opt")); /// assert_eq!(m.occurrences_of("opt"), 0); /// ``` + /// [`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 pub fn default_value(mut self, val: &'a str) -> Self { self.setb(ArgSettings::TakesValue); self.default_val = Some(val); @@ -2000,7 +2075,8 @@ impl<'a, 'b> Arg<'a, 'b> { /// indented once. This can be helpful for arguments with very long or complex help messages. /// This can also be helpful for arguments with very long flag names, or many/long value names. /// - /// **NOTE:** To apply this setting to all arguments consider using `AppSettings::NextLineHelp` + /// **NOTE:** To apply this setting to all arguments consider using + /// [`AppSettings::NextLineHelp`] /// /// # Examples /// @@ -2023,7 +2099,7 @@ impl<'a, 'b> Arg<'a, 'b> { /// /// The above example displays the following help message /// - /// ```ignore + /// ```notrust /// nlh /// /// USAGE: @@ -2039,6 +2115,7 @@ impl<'a, 'b> Arg<'a, 'b> { /// help that makes more sense to be /// on a line after the option /// ``` + /// [`AppSettings::NextLineHelp`]: ./enum.AppSettings.html#variant.NextLineHelp pub fn next_line_help(mut self, nlh: bool) -> Self { if nlh { self.setb(ArgSettings::NextLineHelp); @@ -2056,8 +2133,8 @@ impl<'a, 'b> Arg<'a, 'b> { /// /// **NOTE:** The default is 999 for all arguments. /// - /// **NOTE:** This setting is ignored for positional arguments which are always displayed in - /// index order. + /// **NOTE:** This setting is ignored for [positional arguments] which are always displayed in + /// [index] order. /// /// # Examples /// @@ -2087,7 +2164,7 @@ impl<'a, 'b> Arg<'a, 'b> { /// /// The above example displays the following help message /// - /// ```ignore + /// ```notrust /// cust-ord /// /// USAGE: @@ -2101,23 +2178,28 @@ impl<'a, 'b> Arg<'a, 'b> { /// -O, --other-option I should be first! /// -o, --long-option Some help and text /// ``` + /// [positional arguments]: ./struct.Arg.html#method.index + /// [index]: ./struct.Arg.html#method.index pub fn display_order(mut self, ord: usize) -> Self { self.disp_ord = ord; self } - /// Checks if one of the `ArgSettings` settings is set for the argument + /// Checks if one of the [`ArgSettings`] settings is set for the argument + /// [`ArgSettings`]: ./enum.ArgSettings.html pub fn is_set(&self, s: ArgSettings) -> bool { self.settings.is_set(s) } - /// Sets one of the `ArgSettings` settings for the argument + /// Sets one of the [`ArgSettings`] settings for the argument + /// [`ArgSettings`]: ./enum.ArgSettings.html pub fn set(mut self, s: ArgSettings) -> Self { self.setb(s); self } - /// Unsets one of the `ArgSettings` settings for the argument + /// Unsets one of the [`ArgSettings`] settings for the argument + /// [`ArgSettings`]: ./enum.ArgSettings.html pub fn unset(mut self, s: ArgSettings) -> Self { self.unsetb(s); self diff --git a/src/args/arg_matches.rs b/src/args/arg_matches.rs index ea603d7c..c86e7cda 100644 --- a/src/args/arg_matches.rs +++ b/src/args/arg_matches.rs @@ -11,7 +11,7 @@ use args::MatchedArg; use INVALID_UTF8; /// Used to get information about the arguments that where supplied to the program at runtime by -/// the user. New instances of this struct are obtained by using the `App::get_matches` family of +/// the user. New instances of this struct are obtained by using the [`App::get_matches`] family of /// methods. /// /// # Examples @@ -56,6 +56,7 @@ use INVALID_UTF8; /// } /// } /// ``` +/// [`App::get_matches`]: ./struct.App.html#method.get_matches #[derive(Debug, Clone)] pub struct ArgMatches<'a> { #[doc(hidden)] @@ -82,16 +83,17 @@ impl<'a> ArgMatches<'a> { ArgMatches { ..Default::default() } } - /// Gets the value of a specific option or positional argument (i.e. an argument that takes + /// Gets the value of a specific [option] or [positional] argument (i.e. an argument that takes /// an additional value at runtime). If the option wasn't present at runtime /// it returns `None`. /// /// *NOTE:* If getting a value for an option or positional argument that allows multiples, - /// prefer `values_of()` as `value_of()` will only return the *first* value. + /// prefer [`ArgMatches::values_of`] as `ArgMatches::value_of` will only return the *first* + /// value. /// /// # Panics /// - /// This method will `panic!` if the value contains invalid UTF-8 code points. + /// This method will [`panic!`] if the value contains invalid UTF-8 code points. /// /// # Examples /// @@ -104,6 +106,10 @@ impl<'a> ArgMatches<'a> { /// /// 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 + /// [`panic!`]: https://doc.rust-lang.org/std/macro.panic!.html pub fn value_of>(&self, name: S) -> Option<&str> { if let Some(ref arg) = self.args.get(name.as_ref()) { if let Some(v) = arg.vals.values().nth(0) { @@ -118,7 +124,7 @@ impl<'a> ArgMatches<'a> { /// invalid points will be replaced with `\u{FFFD}` /// /// *NOTE:* If getting a value for an option or positional argument that allows multiples, - /// prefer `values_of_lossy()` as `value_of_lossy()` will only return the *first* value. + /// prefer [`Arg::values_of_lossy`] as `value_of_lossy()` will only return the *first* value. /// /// # Examples /// @@ -134,6 +140,7 @@ impl<'a> ArgMatches<'a> { /// OsString::from_vec(vec![b'H', b'i', b' ', 0xe9, b'!'])]); /// assert_eq!(&*m.value_of_lossy("arg").unwrap(), "Hi \u{FFFD}!"); /// ``` + /// [`Arg::values_of_lossy`]: ./struct.ArgMatches.html#method.values_of_lossy pub fn value_of_lossy>(&'a self, name: S) -> Option> { if let Some(arg) = self.args.get(name.as_ref()) { if let Some(v) = arg.vals.values().nth(0) { @@ -145,12 +152,13 @@ impl<'a> ArgMatches<'a> { /// Gets the OS version of a string value of a specific argument. If the option wasn't present /// at runtime it returns `None`. An OS value on Unix-like systems is any series of bytes, - /// regardless of whether or not they contain valid UTF-8 code points. Since `String`s in Rust - /// are guaranteed to be valid UTF-8, a valid filename on a Unix system as an argument value may - /// contain invalid UTF-8 code points. + /// regardless of whether or not they contain valid UTF-8 code points. Since [`String`]s in + /// Rust are guaranteed to be valid UTF-8, a valid filename on a Unix system as an argument + /// value may contain invalid UTF-8 code points. /// /// *NOTE:* If getting a value for an option or positional argument that allows multiples, - /// prefer `values_of_os()` as `value_of_os()` will only return the *first* value. + /// prefer [`ArgMatches::values_of_os`] as `Arg::value_of_os` will only return the *first* + /// value. /// /// # Examples /// @@ -166,14 +174,17 @@ impl<'a> ArgMatches<'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'!']); /// ``` + /// [`String`]: https://doc.rust-lang.org/std/string/struct.String.html + /// [`ArgMatches::values_of_os`]: ./struct.ArgMatches.html#method.values_of_os pub fn value_of_os>(&self, name: S) -> Option<&OsStr> { self.args .get(name.as_ref()) .map_or(None, |arg| arg.vals.values().nth(0).map(|v| v.as_os_str())) } - /// Gets an Iterator of values of a specific argument (i.e. an argument that takes multiple - /// values at runtime). If the option wasn't present at runtime it returns `None` + /// Gets a [`Values`] struct which implements [`Iterator`] for values of a specific argument + /// (i.e. an argument that takes multiple values at runtime). If the option wasn't present at + /// runtime it returns `None` /// /// # Panics /// @@ -194,6 +205,8 @@ impl<'a> ArgMatches<'a> { /// 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 pub fn values_of>(&'a self, name: S) -> Option> { if let Some(ref arg) = self.args.get(name.as_ref()) { fn to_str_slice(o: &OsString) -> &str { @@ -205,9 +218,9 @@ impl<'a> ArgMatches<'a> { None } - /// Gets the lossy values of a specific argument If the option wasn't present at runtime - /// it returns `None`. A lossy value is one which contains invalid UTF-8 code points, those - /// invalid points will be replaced with `\u{FFFD}` + /// Gets the lossy values of a specific argument. If the option wasn't present at runtime + /// it returns `None`. A lossy value is one where if it contains invalid UTF-8 code points, + /// those invalid points will be replaced with `\u{FFFD}` /// /// # Examples /// @@ -236,11 +249,11 @@ impl<'a> ArgMatches<'a> { None } - /// Gets the OS version of a string value of a specific argument If the option wasn't present - /// at runtime it returns `None`. An OS value on Unix-like systems is any series of bytes, - /// regardless of whether or not they contain valid UTF-8 code points. Since `String`s in Rust - /// are guaranteed to be valid UTF-8, a valid filename as an argument value on Linux (for - /// example) may contain invalid UTF-8 code points. + /// Gets a [`OsValues`] struct which is implements [`Iterator`] for [`OsString`] values of a + /// specific argument. If the option wasn't present at runtime it returns `None`. An OS value + /// on Unix-like systems is any series of bytes, regardless of whether or not they contain + /// valid UTF-8 code points. Since [`String`]s in Rust are guaranteed to be valid UTF-8, a valid + /// filename as an argument value on Linux (for example) may contain invalid UTF-8 code points. /// /// # Examples /// @@ -262,6 +275,10 @@ impl<'a> ArgMatches<'a> { /// assert_eq!(itr.next(), Some(&*OsString::from_vec(vec![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 pub fn values_of_os>(&'a self, name: S) -> Option> { fn to_str_slice(o: &OsString) -> &OsStr { &*o @@ -301,7 +318,8 @@ impl<'a> ArgMatches<'a> { /// it will return `0`. /// /// **NOTE:** This returns the number of times the argument was used, *not* the number of - /// values. For example, `-o val1 val2 val3 -o val4` would return `2`. + /// values. For example, `-o val1 val2 val3 -o val4` would return `2` (2 occurrences, but 4 + /// values). /// /// # Examples /// @@ -339,9 +357,9 @@ impl<'a> ArgMatches<'a> { self.args.get(name.as_ref()).map_or(0, |a| a.occurs) } - /// Because subcommands are essentially "sub-apps" they have their own `ArgMatches` as well. - /// This method returns the `ArgMatches` for a particular subcommand or None if the subcommand - /// wasn't present at runtime. + /// Because [`Subcommand`]s are essentially "sub-[`App`]s" they have their own [`ArgMatches`] + /// as well. This method returns the [`ArgMatches`] for a particular subcommand or `None` if + /// the subcommand wasn't present at runtime. /// /// # Examples /// @@ -367,6 +385,9 @@ impl<'a> ArgMatches<'a> { /// assert_eq!(sub_m.value_of("opt"), Some("val")); /// } /// ``` + /// [`Subcommand`]: ./struct.SubCommand.html + /// [`App`]: ./struct.App.html + /// [`ArgMatches`]: ./struct.ArgMatches.html pub fn subcommand_matches>(&self, name: S) -> Option<&ArgMatches<'a>> { if let Some(ref s) = self.subcommand { if s.name == name.as_ref() { @@ -376,10 +397,10 @@ impl<'a> ArgMatches<'a> { None } - /// Because subcommands are essentially "sub-apps" they have their own `ArgMatches` as well. - /// But simply getting the sub-`ArgMatches` doesn't help much if we don't also know which - /// subcommand was actually used. This method returns the name of the subcommand that was used - /// at runtime, or `None` if one wasn't. + /// Because [`Subcommand`]s are essentially "sub-[`App`]s" they have their own [`ArgMatches`] + /// as well.But simply getting the sub-[`ArgMatches`] doesn't help much if we don't also know + /// which subcommand was actually used. This method returns the name of the subcommand that was + /// used at runtime, or `None` if one wasn't. /// /// *NOTE*: Subcommands form a hierarchy, where multiple subcommands can be used at runtime, /// but only a single subcommand from any group of sibling commands may used at once. @@ -431,12 +452,15 @@ impl<'a> ArgMatches<'a> { /// _ => {}, // Either no subcommand or one not tested for... /// } /// ``` + /// [`Subcommand`]: ./struct.SubCommand.html + /// [`App`]: ./struct.App.html + /// [`ArgMatches`]: ./struct.ArgMatches.html pub fn subcommand_name(&self) -> Option<&str> { self.subcommand.as_ref().map(|sc| &sc.name[..]) } - /// This brings together `ArgMatches::subcommand_matches` and `ArgMatches::subcommand_name` by - /// returning a tuple with both pieces of information. + /// This brings together [`ArgMatches::subcommand_matches`] and [`ArgMatches::subcommand_name`] + /// by returning a tuple with both pieces of information. /// /// # Examples /// @@ -479,11 +503,13 @@ impl<'a> ArgMatches<'a> { /// _ => {}, /// } /// ``` + /// [`ArgMatches::subcommand_matches`]: ./struct.ArgMatches.html#method.subcommand_matches + /// [`ArgMatches::subcommand_name`]: ./struct.ArgMatches.html#method.subcommand_name pub fn subcommand(&self) -> (&str, Option<&ArgMatches<'a>>) { self.subcommand.as_ref().map_or(("", None), |sc| (&sc.name[..], Some(&sc.matches))) } - /// Returns a string slice of the usage statement for the `App` (or `SubCommand`) + /// Returns a string slice of the usage statement for the [`App`] or [`SubCommand`] /// /// # Examples /// @@ -495,6 +521,8 @@ impl<'a> ArgMatches<'a> { /// /// println!("{}", app_m.usage()); /// ``` + /// [`Subcommand`]: ./struct.SubCommand.html + /// [`App`]: ./struct.App.html pub fn usage(&self) -> &str { self.usage.as_ref().map_or("", |u| &u[..]) } @@ -506,7 +534,8 @@ impl<'a> ArgMatches<'a> { // commit: be5e1fa3c26e351761b33010ddbdaf5f05dbcc33 // license: MIT - Copyright (c) 2015 The Rust Project Developers -/// An iterator for getting multiple values out of an argument via the `Arg::values_of` method. +/// An iterator for getting multiple values out of an argument via the [`ArgMatches::values_of`] +/// method. /// /// # Examples /// @@ -519,6 +548,7 @@ impl<'a> ArgMatches<'a> { /// /// assert_eq!(m.value_of("output"), Some("something")); /// ``` +/// [`ArgMatches::values_of`]: ./struct.ArgMatches.html#method.values_of #[derive(Clone)] #[allow(missing_debug_implementations)] pub struct Values<'a> { @@ -589,8 +619,9 @@ impl<'a, V> DoubleEndedIterator for Iter<'a, V> { } } -/// An iterator for getting multiple values out of an argument via the `Arg::values_of_os` method. -/// Usage of this iterator allows values which contain invalid UTF-8 code points unlike `Values`. +/// An iterator for getting multiple values out of an argument via the [`ArgMatches::values_of_os`] +/// method. Usage of this iterator allows values which contain invalid UTF-8 code points unlike +/// [`Values`]. /// /// # Examples /// @@ -606,6 +637,8 @@ impl<'a, V> DoubleEndedIterator for Iter<'a, V> { /// 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 #[derive(Clone)] #[allow(missing_debug_implementations)] pub struct OsValues<'a> { diff --git a/src/args/group.rs b/src/args/group.rs index d234e664..d95ba7db 100644 --- a/src/args/group.rs +++ b/src/args/group.rs @@ -98,7 +98,7 @@ impl<'a> ArgGroup<'a> { ArgGroup::from(y.as_hash().unwrap()) } - /// Adds an argument to this group by name + /// Adds an [argument] to this group by name /// /// # Examples /// @@ -110,6 +110,7 @@ impl<'a> ArgGroup<'a> { /// .arg("config") /// # ; /// ``` + /// [argument]: ./struct.Arg.html pub fn arg(mut self, n: &'a str) -> Self { assert!(self.name != n, "ArgGroup '{}' can not have same name as arg inside it", @@ -118,7 +119,7 @@ impl<'a> ArgGroup<'a> { self } - /// Adds multiple arguments to this group by name + /// Adds multiple [arguments] to this group by name /// /// # Examples /// @@ -131,6 +132,7 @@ impl<'a> ArgGroup<'a> { /// .args(&["config", "input"]) /// # ; /// ``` + /// [arguments]: ./struct.Arg.html pub fn args(mut self, ns: &[&'a str]) -> Self { for n in ns { self = self.arg(n); @@ -143,7 +145,8 @@ impl<'a> ArgGroup<'a> { /// that one, and only one argument from this group *must* be present at runtime (unless /// conflicting with another argument). /// - /// **NOTE:** This setting only applies to the current `App` / `SubCommand`, and not globally. + /// **NOTE:** This setting only applies to the current [`App`] / [`SubCommand`], and not + /// globally. /// /// # Examples /// @@ -157,6 +160,8 @@ impl<'a> ArgGroup<'a> { /// .required(true) /// # ; /// ``` + /// [`App`]: ./struct.App.html + /// [`SubCommand`]: ./struct.SubCommand.html pub fn required(mut self, r: bool) -> Self { self.required = r; self diff --git a/src/args/settings.rs b/src/args/settings.rs index 03143653..c4573c07 100644 --- a/src/args/settings.rs +++ b/src/args/settings.rs @@ -44,7 +44,10 @@ impl Default for ArgFlags { } /// Various settings that apply to arguments and may be set, unset, and checked via getter/setter -/// methods `Arg::set`, `Arg::unset`, and `Arg::is_set` +/// methods [`Arg::set`], [`Arg::unset`], and [`Arg::is_set`] +/// [`Arg::set`]: ./struct.Arg.html#method.set +/// [`Arg::unset`]: ./struct.Arg.html#method.unset +/// [`Arg::is_set`]: ./struct.Arg.html#method.is_set #[derive(Debug, PartialEq, Copy, Clone)] pub enum ArgSettings { /// The argument must be used @@ -53,7 +56,8 @@ pub enum ArgSettings { Multiple, /// The argument allows empty values such as `--option ""` EmptyValues, - /// The argument should be propagated down through all child subcommands + /// The argument should be propagated down through all child [`SubCommands`] + /// [`SubCommand`]: ./struct.SubCommand.html Global, /// The argument should **not** be shown in help text Hidden, diff --git a/src/args/subcommand.rs b/src/args/subcommand.rs index 77abe981..e18e6036 100644 --- a/src/args/subcommand.rs +++ b/src/args/subcommand.rs @@ -7,8 +7,8 @@ use ArgMatches; /// The abstract representation of a command line subcommand. /// /// This struct describes all the valid options of the subcommand for the program. Subcommands are -/// essentially "sub apps" and contain all the same possibilities (such as their own arguments, -/// subcommands, and settings). +/// essentially "sub-[`App`]s" and contain all the same possibilities (such as their own +/// [arguments], subcommands, and settings). /// /// # Examples /// @@ -23,6 +23,8 @@ use ArgMatches; /// .index(1))) /// # ; /// ``` +/// [`App`]: ./struct.App.html +/// [arguments]: ./struct.Arg.html #[derive(Debug, Clone)] pub struct SubCommand<'a> { #[doc(hidden)] diff --git a/src/errors.rs b/src/errors.rs index dc33c597..aa5db714 100644 --- a/src/errors.rs +++ b/src/errors.rs @@ -10,13 +10,14 @@ use fmt::Format; use suggestions; use args::any_arg::AnyArg; -/// Short hand for result type +/// Short hand for [`Result`] type +/// [`Result`]: https://doc.rust-lang.org/std/result/enum.Result.html pub type Result = StdResult; /// Command line argument parser kind of error #[derive(Debug, Copy, Clone, PartialEq)] pub enum ErrorKind { - /// Occurs when an `Arg` has a set of possible values, and the user provides a value which + /// Occurs when an [`Arg`] has a set of possible values, and the user provides a value which /// isn't in that set. /// /// # Examples @@ -31,6 +32,7 @@ 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, or argument which wasn't defined. /// @@ -45,9 +47,9 @@ pub enum ErrorKind { /// assert_eq!(result.unwrap_err().kind, ErrorKind::UnknownArgument); /// ``` UnknownArgument, - /// Occurs when the user provids an unrecognized subcommand which meets the threshold for being - /// similar enough to an existing subcommand so as to not cause the more general - /// `UnknownArgument` error. + /// Occurs when the user provids an unrecognized [`SubCommand`] which meets the threshold for + /// being similar enough to an existing subcommand so as to not cause the more general + /// [`UnknownArgument`] error. /// /// # Examples /// @@ -63,13 +65,15 @@ pub enum ErrorKind { /// assert!(result.is_err()); /// assert_eq!(result.unwrap_err().kind, ErrorKind::InvalidSubcommand); /// ``` + /// [`SubCommand`]: ./struct.SubCommand.html + /// [`UnknownArgument`]: ./enum.ErrorKind.html#variant.UnknownArgument InvalidSubcommand, - /// Occurs when the user provids an unrecognized subcommand which does not meet the threshold - /// for being similar enough to an existing subcommand so as to not cause the more detailed - /// `InvalidSubcommand` error. + /// Occurs when the user provids an unrecognized [`SubCommand`] which does not meet the + /// threshold for being similar enough to an existing subcommand so as to not cause the more + /// detailed [`InvalidSubcommand`] error. /// /// This error typically happens when passing additional subcommand names to the `help` - /// subcommand. Otherwise, the more general `UnknownArgument` error is used. + /// subcommand. Otherwise, the more general [`UnknownArgument`] error is used. /// /// # Examples /// @@ -85,6 +89,9 @@ pub enum ErrorKind { /// assert!(result.is_err()); /// assert_eq!(result.unwrap_err().kind, ErrorKind::UnrecognizedSubcommand); /// ``` + /// [`SubCommand`]: ./struct.SubCommand.html + /// [`InvalidSubcommand`]: ./enum.ErrorKind.html#variant.InvalidSubcommand + /// [`UnknownArgument`]: ./enum.ErrorKind.html#variant.UnknownArgument UnrecognizedSubcommand, /// Occurs when the user provides an empty value for an option that does not allow empty /// values. @@ -125,7 +132,7 @@ pub enum ErrorKind { /// ``` ValueValidation, /// Occurs when a user provides more values for an argument than were defined by setting - /// `Arg::max_values`. + /// [`Arg::max_values`]. /// /// # Examples /// @@ -139,9 +146,10 @@ pub enum ErrorKind { /// assert!(result.is_err()); /// assert_eq!(result.unwrap_err().kind, ErrorKind::TooManyValues); /// ``` + /// [`Arg::max_values`]: ./struct.Arg.html#method.max_values TooManyValues, /// Occurs when the user provides fewer values for an argument than were defined by setting - /// `Arg::min_values`. + /// [`Arg::min_values`]. /// /// # Examples /// @@ -155,10 +163,11 @@ pub enum ErrorKind { /// assert!(result.is_err()); /// assert_eq!(result.unwrap_err().kind, ErrorKind::TooFewValues); /// ``` + /// [`Arg::min_values`]: ./struct.Arg.html#method.min_values TooFewValues, /// Occurs when the user provides a different number of values for an argument than what's - /// been defined by setting `Arg::number_of_values` or than was implicitly set by - /// `Arg::value_names`. + /// been defined by setting [`Arg::number_of_values`] or than was implicitly set by + /// [`Arg::value_names`]. /// /// # Examples /// @@ -173,6 +182,9 @@ pub enum ErrorKind { /// assert!(result.is_err()); /// assert_eq!(result.unwrap_err().kind, ErrorKind::WrongNumberOfValues); /// ``` + /// [`Arg::number_of_values`] + /// [`Arg::number_of_values`]: ./struct.Arg.html#method.number_of_values + /// [`Arg::value_names`]: ./struct.Arg.html#method.value_names WrongNumberOfValues, /// Occurs when the user provides two values which conflict with each other and can't be used /// together. @@ -206,8 +218,8 @@ pub enum ErrorKind { /// assert_eq!(result.unwrap_err().kind, ErrorKind::MissingRequiredArgument); /// ``` MissingRequiredArgument, - /// Occurs when a subcommand is required (as defined by `AppSettings::SubcommandRequired`), but - /// the user does not provide one. + /// Occurs when a subcommand is required (as defined by [`AppSettings::SubcommandRequired`]), + /// but the user does not provide one. /// /// # Examples /// @@ -223,9 +235,10 @@ pub enum ErrorKind { /// assert_eq!(err.unwrap_err().kind, ErrorKind::MissingSubcommand); /// # ; /// ``` + /// [`AppSettings::SubcommandRequired`]: ./enum.AppSettings.html#variant.SubcommandRequired MissingSubcommand, - /// Occurs when either an argument or subcommand is required, as defined by - /// `AppSettings::ArgRequiredElseHelp` but the user did not provide one. + /// Occurs when either an argument or [`SubCommand`] is required, as defined by + /// [`AppSettings::ArgRequiredElseHelp`] but the user did not provide one. /// /// # Examples /// @@ -241,6 +254,8 @@ pub enum ErrorKind { /// assert!(result.is_err()); /// assert_eq!(result.unwrap_err().kind, ErrorKind::MissingArgumentOrSubcommand); /// ``` + /// [`SubCommand`]: ./struct.SubCommand.html + /// [`AppSettings::ArgRequiredElseHelp`]: ./enum.AppSettings.html#variant.ArgRequiredElseHelp MissingArgumentOrSubcommand, /// Occurs when the user provides an argument multiple times which has not been set to allow /// multiple uses. @@ -259,7 +274,7 @@ pub enum ErrorKind { /// ``` UnexpectedMultipleUsage, /// Occurs when the user provides a value containing invalid UTF-8 for an argument and - /// `AppSettings::StrictUtf8` is set. + /// [`AppSettings::StrictUtf8`] is set. /// /// # Platform Speicific /// @@ -282,6 +297,7 @@ 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. The help message will be sent /// to `stdout`. @@ -312,13 +328,19 @@ pub enum ErrorKind { /// assert_eq!(result.unwrap_err().kind, ErrorKind::VersionDisplayed); /// ``` VersionDisplayed, - /// Occurs when using the `value_t!` and `values_t!` macros to convert an argument value 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. + /// Occurs when using the [`value_t!`] and [`values_t!`] macros to convert an argument value + /// 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. + /// [`value_t!`]: ./macro.value_t!.html + /// [`values_t!`]: ./macro.values_t!.html ArgumentNotFound, - /// Represents an I/O error, typically while writing to `stderr` or `stdout`. + /// Represents an [I/O error], typically while writing to `stderr` or `stdout`. + /// [I/O error]: https://doc.rust-lang.org/std/io/struct.Error.html Io, - /// Represents an Rust Display Format error, typically white writing to `stderr` or `stdout`. + /// Represents an Rust's [Format error] as part of [`Display`] , typically while 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 Format, } diff --git a/src/lib.rs b/src/lib.rs index 55d7b560..9571b346 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,4 +1,4 @@ -// Copyright ⓒ 2015-2016 Kevin B. Knapp and clap-rs contributors. +// Copyright ⓒ 2015-2016 Kevin B. Knapp and [`clap-rs` contributors](https://github.com/kbknapp/clap-rs/blob/master/CONTRIBUTORS.md). // Licensed under the MIT license // (see LICENSE or ) All files in the project carrying such // notice may not be copied, modified, or distributed except according to those terms. diff --git a/src/macros.rs b/src/macros.rs index 4f653c0f..77cd13b7 100644 --- a/src/macros.rs +++ b/src/macros.rs @@ -27,11 +27,11 @@ macro_rules! load_yaml { ); } -/// Convenience macro getting a typed value `T` where `T` implements `std::str::FromStr` from an +/// Convenience macro getting a typed value `T` where `T` implements [`std::str::FromStr`] from an /// argument value. This macro returns a `Result` which allows you as the developer to /// decide what you'd like to do on a failed parse. There are two types of errors, parse failures /// and those where the argument wasn't present (such as a non-required argument). You can use -/// it to get a single value, or a iterator as with the `ArgMatches::values_of` +/// it to get a single value, or a iterator as with the [`ArgMatches::values_of`] /// /// # Examples /// @@ -50,6 +50,9 @@ macro_rules! load_yaml { /// println!("{} + 2: {}", len, len + 2); /// # } /// ``` +/// [`std::str::FromStr`]: https://doc.rust-lang.org/std/str/trait.FromStr.html +/// [`ArgMatches::values_of`]: ./struct.ArgMatches.html#method.values_of +/// [`Result`]: https://doc.rust-lang.org/std/result/enum.Result.html #[macro_export] macro_rules! value_t { ($m:ident, $v:expr, $t:ty) => { @@ -69,11 +72,11 @@ macro_rules! value_t { }; } -/// Convenience macro getting a typed value `T` where `T` implements `std::str::FromStr` or -/// exiting upon error instead of returning a `Result` +/// Convenience macro getting a typed value `T` where `T` implements [`std::str::FromStr`] or +/// exiting upon error, instead of returning a [`Result`] type. /// /// **NOTE:** This macro is for backwards compatibility sake. Prefer -/// `value_t!(/* ... */).unwrap_or_else(|e| e.exit())` +/// [`value_t!(/* ... */).unwrap_or_else(|e| e.exit())`] /// /// # Examples /// @@ -92,6 +95,9 @@ macro_rules! value_t { /// println!("{} + 2: {}", len, len + 2); /// # } /// ``` +/// [`std::str::FromStr`]: https://doc.rust-lang.org/std/str/trait.FromStr.html +/// [`Result`]: https://doc.rust-lang.org/std/result/enum.Result.html +/// [`value_t!(/* ... */).unwrap_or_else(|e| e.exit())`]: ./macro.value_t!.html #[macro_export] macro_rules! value_t_or_exit { ($m:ident, $v:expr, $t:ty) => { @@ -111,9 +117,9 @@ macro_rules! value_t_or_exit { }; } -/// Convenience macro getting a typed value `Vec` where `T` implements `std::str::FromStr` This -/// macro returns a `clap::Result>` (`Result, clap::Error>`) which allows you as the -/// developer to decide what you'd like to do on a failed parse. +/// Convenience macro getting a typed value [`Vec`] where `T` implements [`std::str::FromStr`] +/// This macro returns a [`clap::Result>`] which allows you as the developer to decide +/// what you'd like to do on a failed parse. /// /// # Examples /// @@ -137,6 +143,9 @@ macro_rules! value_t_or_exit { /// } /// # } /// ``` +/// [`std::str::FromStr`]: https://doc.rust-lang.org/std/str/trait.FromStr.html +/// [`Vec`]: https://doc.rust-lang.org/std/vec/struct.Vec.html +/// [`clap::Result>`]: ./type.Result.html #[macro_export] macro_rules! values_t { ($m:ident, $v:expr, $t:ty) => { @@ -166,11 +175,11 @@ macro_rules! values_t { }; } -/// Convenience macro getting a typed value `Vec` where `T` implements `std::str::FromStr` or -/// exiting upon error. +/// Convenience macro getting a typed value [`Vec`] where `T` implements [`std::str::FromStr`] +/// or exiting upon error. /// /// **NOTE:** This macro is for backwards compatibility sake. Prefer -/// `values_t!(/* ... */).unwrap_or_else(|e| e.exit())` +/// [`values_t!(/* ... */).unwrap_or_else(|e| e.exit())`] /// /// # Examples /// @@ -195,6 +204,9 @@ macro_rules! values_t { /// } /// # } /// ``` +/// [`values_t!(/* ... */).unwrap_or_else(|e| e.exit())`]: ./macro.values_t!.html +/// [`std::str::FromStr`]: https://doc.rust-lang.org/std/str/trait.FromStr.html +/// [`Vec`]: https://doc.rust-lang.org/std/vec/struct.Vec.html #[macro_export] macro_rules! values_t_or_exit { ($m:ident, $v:expr, $t:ty) => { @@ -243,12 +255,12 @@ macro_rules! _clap_count_exprs { /// Convenience macro to generate more complete enums with variants to be used as a type when /// parsing arguments. This enum also provides a `variants()` function which can be used to -/// retrieve a `Vec<&'static str>` of the variant names, as well as implementing `FromStr` and -/// `Display` automatically. +/// retrieve a `Vec<&'static str>` of the variant names, as well as implementing [`FromStr`] and +/// [`Display`] automatically. /// /// **NOTE:** Case insensitivity is supported for ASCII characters only /// -/// **NOTE:** This macro automatically implements std::str::FromStr and std::fmt::Display +/// **NOTE:** This macro automatically implements [`std::str::FromStr`] and [`std::fmt::Display`] /// /// **NOTE:** These enums support pub (or not) and uses of the #[derive()] traits /// @@ -277,6 +289,10 @@ macro_rules! _clap_count_exprs { /// // Use f like any other Foo variant... /// } /// ``` +/// [`FromStr`]: https://doc.rust-lang.org/std/str/trait.FromStr.html +/// [`std::str::FromStr`]: https://doc.rust-lang.org/std/str/trait.FromStr.html +/// [`Display`]: https://doc.rust-lang.org/std/fmt/trait.Display.html +/// [`std::fmt::Display`]: https://doc.rust-lang.org/std/fmt/trait.Display.html #[macro_export] macro_rules! arg_enum { (@as_item $($i:item)*) => ($($i)*);