From ade367780c366425de462506d256e0f554ed3b9c Mon Sep 17 00:00:00 2001 From: Alexander Kuvaev Date: Sat, 15 Aug 2015 01:16:35 +0300 Subject: [PATCH] docs: fixed docs for previous changes --- src/app.rs | 134 ++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 132 insertions(+), 2 deletions(-) diff --git a/src/app.rs b/src/app.rs index 2ccc2d0a42f..af389ee3272 100644 --- a/src/app.rs +++ b/src/app.rs @@ -55,13 +55,141 @@ enum DidYouMeanMessageStyle { /// Some application options pub enum AppOptions { + /// Allows subcommands to override all requirements of the parent (this command). For example + /// if you had a subcommand or even top level application which had a required arguments that + /// are only required as long as there is no subcommand present. + /// + /// **NOTE:** This defaults to false (using subcommand does *not* negate requirements) + /// + /// # Example + /// + /// ```no_run + /// # use clap::{App, AppOptions}; + /// App::new("myprog") + /// .setting(AppOptions::SubcommandsNagateReqs) + /// # ; + /// ``` SubcommandsNagateReqs, + /// 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) + /// + /// # Example + /// + /// ```no_run + /// # use clap::{App, AppOptions}; + /// App::new("myprog") + /// .setting(AppOptions::SubcommandRequired) + /// # ; + /// ``` SubcommandRequired, + /// Specifies that the help text sould 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 + /// + /// # Example + /// + /// ```no_run + /// # use clap::{App, AppOptions}; + /// App::new("myprog") + /// .setting(AppOptions::ArgRequiredElseHelp) + /// # ; + /// ``` ArgRequiredElseHelp, + /// Uses version of the current command for all subcommands. (Defaults to false; subcommands + /// have independant version strings) + /// + /// **NOTE:** The version for the current command and this setting must be set **prior** to + /// adding any subcommands + /// + /// # Example + /// + /// ```no_run + /// # use clap::{App, Arg, SubCommand, AppOptions}; + /// App::new("myprog") + /// .version("v1.1") + /// .setting(AppOptions::GlobalVersion) + /// .subcommand(SubCommand::with_name("test")) + /// .get_matches(); + /// // running `myprog test --version` will display + /// // "myprog-test v1.1" + /// ``` GlobalVersion, + /// Disables `-V` and `--version` for all subcommands (Defaults to false; subcommands have + /// version flags) + /// + /// **NOTE:** This setting must be set **prior** adding any subcommands + /// + /// **NOTE:** Do not set this value to false, it will have undesired results! + /// + /// # Example + /// + /// ```no_run + /// # use clap::{App, Arg, SubCommand, AppOptions}; + /// App::new("myprog") + /// .version("v1.1") + /// .setting(AppOptions::VersionlessSubcommands) + /// .subcommand(SubCommand::with_name("test")) + /// .get_matches(); + /// // running `myprog test --version` will display unknown argument error + /// ``` VersionlessSubcommands, + /// By default the auto-generated help message groups flags, options, and positional arguments + /// separately. This setting disable that and groups flags and options together presenting a + /// more unified help message (a la getopts or docopt style). + /// + /// **NOTE:** This setting is cosmetic only and does not affect any functionality. + /// + /// # Example + /// + /// ```no_run + /// # use clap::{App, Arg, SubCommand, AppOptions}; + /// App::new("myprog") + /// .setting(AppOptions::UnifiedHelpMessage) + /// .get_matches(); + /// // running `myprog --help` will display a unified "docopt" or "getopts" style help message + /// ``` UnifiedHelpMessage, + /// Will display a message "Press [ENTER]/[RETURN] to continue..." and wait user before + /// exiting + /// + /// This is most useful when writing an application which is run from a GUI shortcut, or on + /// Windows where a user tries to open the binary by double-clicking instead of using the + /// command line (i.e. set `.arg_required_else_help(true)` and `.wait_on_error(true)` to + /// display the help in such a case). + /// + /// **NOTE:** This setting is **not** recursive with subcommands, meaning if you wish this + /// behavior for all subcommands, you must set this on each command (needing this is extremely + /// rare) + /// + /// # Example + /// + /// ```no_run + /// # use clap::{App, Arg, AppOptions}; + /// App::new("myprog") + /// .setting(AppOptions::WaitOnError) + /// # ; + /// ``` WaitOnError, + /// Specifies that the help text sould be displayed (and then exit gracefully), if no + /// subcommands 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 one prints the help text, and one 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 + /// `.arg_required_else_help()` + /// + /// # Example + /// + /// ```no_run + /// # use clap::{App, Arg, AppOptions}; + /// App::new("myprog") + /// .setting(AppOptions::SubcommandRequiredElseHelp) + /// # ; + /// ``` SubcommandRequiredElseHelp, } @@ -559,13 +687,15 @@ impl<'a, 'v, 'ab, 'u, 'h, 'ar> App<'a, 'v, 'ab, 'u, 'h, 'ar>{ /// Enables Application Option, passed as argument /// + /// + /// /// # Example /// /// ```no_run - /// # use clap::{App, Arg}; + /// # use clap::{App, Arg, AppOptions}; /// App::new("myprog") /// .setting(AppOptions::SubcommandRequired) - /// .setting(AppOptions::WaitOnError) + /// .setting(AppOptions::WaitOnError) /// # ; /// ``` pub fn setting(mut self, option: AppOptions) -> Self {