From 26d5ae3e330d1e150811d5b60b2b01a8f8df854e Mon Sep 17 00:00:00 2001 From: Kevin K Date: Mon, 29 Jun 2015 21:30:25 -0400 Subject: [PATCH 1/5] feat(Help): allows one to fully override the auto-generated help message Allows overriding the entire help message so that nothing is auto-generated Closes #141 --- src/app.rs | 45 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/src/app.rs b/src/app.rs index 81344427154..8d4f3eb7c11 100644 --- a/src/app.rs +++ b/src/app.rs @@ -121,6 +121,7 @@ pub struct App<'a, 'v, 'ab, 'u, 'h, 'ar> { global_args: Vec>, no_sc_error: bool, help_on_no_args: bool, + help_str: Option<&'u str>, help_on_no_sc: bool } @@ -166,6 +167,7 @@ impl<'a, 'v, 'ab, 'u, 'h, 'ar> App<'a, 'v, 'ab, 'u, 'h, 'ar>{ subcmds_neg_reqs: false, global_args: vec![], no_sc_error: false, + help_str: None, help_on_no_args: false, help_on_no_sc: false } @@ -337,6 +339,45 @@ impl<'a, 'v, 'ab, 'u, 'h, 'ar> App<'a, 'v, 'ab, 'u, 'h, 'ar>{ self } + /// Sets a custom help message and overrides the auto-generated one. This should only be used + /// when the auto-gererated message does not suffice. + /// + /// This will be displayed to the user when they use the defailt `--help` or `-h` + /// + /// **NOTE:** This replaces the **entire** help message, so nothing will be auto-gererated. + /// + /// **NOTE:** This **only** replaces the help message for the current command, meaning if you + /// are using subcommands, those help messages will still be auto-gererated unless you + /// specify a `.help()` for them as well. + /// + /// + /// # Example + /// + /// ```no_run + /// # use clap::{App, Arg}; + /// App::new("myapp") + /// .help("myapp v1.0\n\ + /// Does awesome things\n\ + /// (C) me@mail.com\n\n\ + /// + /// USAGE: myapp \n\n\ + /// + /// Options:\n\ + /// -h, --helpe Dispay this message\n\ + /// -V, --version Display version info\n\ + /// -s Do something with stuff\n\ + /// -v Be verbose\n\n\ + /// + /// Commmands:\n\ + /// help Prints this message\n\ + /// work Do some work") + /// # ; + /// ``` + pub fn help(mut self, h: &'u str) -> App<'a, 'v, 'ab, 'u, 'h, 'ar> { + self.help_str = Some(h); + self + } + /// Sets the short version of the `help` argument without the preceding `-`. /// /// By default `clap` automatically assigns `h`, but this can be overridden @@ -1161,6 +1202,10 @@ impl<'a, 'v, 'ab, 'u, 'h, 'ar> App<'a, 'v, 'ab, 'u, 'h, 'ar>{ // Prints the full help message to the user fn print_help(&self) { + if let Some(h) = self.help_str { + println!("{}", h); + return + } self.print_version(false); let flags = !self.flags.is_empty(); let pos = !self.positionals_idx.is_empty(); From d0da3bdd9d1871541907ea9c645322a74d260e07 Mon Sep 17 00:00:00 2001 From: Kevin K Date: Mon, 29 Jun 2015 21:55:44 -0400 Subject: [PATCH 2/5] feat: allows waiting for user input on error In order to pause for user input on error use `.wait_on_error(true)` but it's important to note that this is *not* recursive through subcommands. This is useful on Windows when a user mistakenly opens an application by double clicking it, instead of using the command line or if using a GUI shortcut to run a program. Closes #140 --- src/app.rs | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/src/app.rs b/src/app.rs index 8d4f3eb7c11..5464e2b8b69 100644 --- a/src/app.rs +++ b/src/app.rs @@ -4,6 +4,7 @@ use std::collections::HashSet; use std::collections::HashMap; use std::collections::VecDeque; use std::env; +use std::io::{self, BufRead}; use std::path::Path; use std::vec::IntoIter; use std::process; @@ -120,6 +121,7 @@ pub struct App<'a, 'v, 'ab, 'u, 'h, 'ar> { groups: HashMap<&'ar str, ArgGroup<'ar, 'ar>>, global_args: Vec>, no_sc_error: bool, + wait_on_error: bool, help_on_no_args: bool, help_str: Option<&'u str>, help_on_no_sc: bool @@ -168,6 +170,7 @@ impl<'a, 'v, 'ab, 'u, 'h, 'ar> App<'a, 'v, 'ab, 'u, 'h, 'ar>{ global_args: vec![], no_sc_error: false, help_str: None, + wait_on_error: false, help_on_no_args: false, help_on_no_sc: false } @@ -443,6 +446,31 @@ impl<'a, 'v, 'ab, 'u, 'h, 'ar> App<'a, 'v, 'ab, 'u, 'h, 'ar>{ self } + /// 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}; + /// App::new("myprog") + /// .arg_required_else_help(true) + /// # ; + /// ``` + pub fn wait_on_error(mut self, w: bool) -> App<'a, 'v, 'ab, 'u, 'h, 'ar> { + self.wait_on_error = w; + self + } + /// 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`. /// @@ -1402,6 +1430,12 @@ impl<'a, 'v, 'ab, 'u, 'h, 'ar> App<'a, 'v, 'ab, 'u, 'h, 'ar>{ // Exits with a status code passed to the OS // This is legacy from before std::process::exit() and may be removed evenutally fn exit(&self, status: i32) { + if self.wait_on_error { + println!("\nPress [ENTER] / [RETURN] to continue..."); + let mut s = String::new(); + let i = io::stdin(); + i.lock().read_line(&mut s).unwrap(); + } process::exit(status); } From 274484dfd08fff4859cefd7e9bef3b73d3a9cb5f Mon Sep 17 00:00:00 2001 From: Kevin K Date: Mon, 29 Jun 2015 22:03:05 -0400 Subject: [PATCH 3/5] imp: removes deprecated functions in prep for 1.0 --- src/app.rs | 19 -------- src/args/arg.rs | 99 ------------------------------------------ src/args/subcommand.rs | 17 -------- 3 files changed, 135 deletions(-) diff --git a/src/app.rs b/src/app.rs index 5464e2b8b69..8bfb0748d90 100644 --- a/src/app.rs +++ b/src/app.rs @@ -264,25 +264,6 @@ impl<'a, 'v, 'ab, 'u, 'h, 'ar> App<'a, 'v, 'ab, 'u, 'h, 'ar>{ self } - /// **WARNING:** This method is deprecated. Use `.subcommand_required(true)` instead. - /// - /// 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; - /// App::new("myprog") - /// .subcommands_negate_reqs(true) - /// # ; - /// ``` - pub fn error_on_no_subcommand(mut self, n: bool) -> App<'a, 'v, 'ab, 'u, 'h, 'ar> { - self.no_sc_error = n; - self - } - /// 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) diff --git a/src/args/arg.rs b/src/args/arg.rs index 79ea98ebb0b..f874f21ac89 100644 --- a/src/args/arg.rs +++ b/src/args/arg.rs @@ -94,50 +94,6 @@ pub struct Arg<'n, 'l, 'h, 'g, 'p, 'r> { } impl<'n, 'l, 'h, 'g, 'p, 'r> Arg<'n, 'l, 'h, 'g, 'p, 'r> { - /// **WARNING:** This function is deprecated. Use `Arg::with_name()` instead. - /// - /// Creates a new instace of `Arg` using a unique string name. - /// The name will be used by the library consumer to get information about - /// whether or not the argument was used at runtime. - /// - /// **NOTE:** in the case of arguments that take values (i.e. `takes_value(true)`) - /// and positional arguments (i.e. those without a `-` or `--`) the name will also - /// be displayed when the user prints the usage/help information of the program. - /// - /// - /// - /// # Example - /// - /// ```no_run - /// # use clap::{App, Arg}; - /// # let matches = App::new("myprog") - /// # .arg( - /// Arg::new("conifg") - /// # .short("c") - /// # ).get_matches(); - pub fn new(n: &'n str) -> Arg<'n, 'l, 'h, 'g, 'p, 'r> { - Arg { - name: n, - short: None, - long: None, - help: None, - required: false, - takes_value: false, - multiple: false, - index: None, - possible_vals: None, - blacklist: None, - requires: None, - group: None, - num_vals: None, - val_names: None, - max_vals: None, - min_vals: None, - global: false, - empty_vals: true, - } - } - /// Creates a new instace of `Arg` using a unique string name. /// The name will be used by the library consumer to get information about /// whether or not the argument was used at runtime. @@ -428,61 +384,6 @@ impl<'n, 'l, 'h, 'g, 'p, 'r> Arg<'n, 'l, 'h, 'g, 'p, 'r> { self } - /// **WARNING:** This method is deprecated. Use `.conflicts_with()` instead. - /// - /// Sets a mutually exclusive argument by name. I.e. when using this argument, - /// the following argument can't be present. - /// - /// **NOTE:** Mutually exclusive rules take precedence over being required - /// by default. Mutually exclusive rules only need to be set for one of the two - /// arguments, they do not need to be set for each. - /// - /// # Example - /// - /// ```no_run - /// # use clap::{App, Arg}; - /// # let myprog = App::new("myprog").arg(Arg::with_name("conifg") - /// .mutually_excludes("debug") - /// # ).get_matches(); - pub fn mutually_excludes(mut self, name: &'r str) -> Arg<'n, 'l, 'h, 'g, 'p, 'r> { - if let Some(ref mut vec) = self.blacklist { - vec.push(name); - } else { - let v = vec![name]; - self.blacklist = Some(v); - } - self - } - - /// **WARNING:** This method is deprecated. Use `conflicts_with_all()` instead. - /// - /// Sets a mutually exclusive arguments by names. I.e. when using this argument, - /// the following argument can't be present. - /// - /// **NOTE:** Mutually exclusive rules take precedence over being required - /// by default. Mutually exclusive rules only need to be set for one of the two - /// arguments, they do not need to be set for each. - /// - /// # Example - /// - /// ```no_run - /// # use clap::{App, Arg}; - /// let conf_excludes = ["debug", "input"]; - /// # let myprog = App::new("myprog").arg(Arg::with_name("conifg") - /// .mutually_excludes_all(&conf_excludes) - /// # ).get_matches(); - pub fn mutually_excludes_all(mut self, names: I) - -> Arg<'n, 'l, 'h, 'g, 'p, 'r> - where T: AsRef + 'r, - I: IntoIterator { - if let Some(ref mut vec) = self.blacklist { - names.into_iter().map(|s| vec.push(s.as_ref())).collect::>(); - } else { - self.blacklist = Some(names.into_iter().map(|s| s.as_ref()).collect::>()); - } - self - } - /// Sets a mutually exclusive argument by name. I.e. when using this argument, /// the following argument can't be present. /// diff --git a/src/args/subcommand.rs b/src/args/subcommand.rs index 5a6ff5fff1d..559d3eea111 100644 --- a/src/args/subcommand.rs +++ b/src/args/subcommand.rs @@ -42,21 +42,4 @@ impl<'n, 'a> SubCommand<'n, 'a> { pub fn with_name<'au, 'v, 'ab, 'u, 'h, 'ar>(name: &'ar str) -> App<'au, 'v, 'ab, 'u, 'h, 'ar> { App::new(name) } - - /// **WARNING:** This function is deprecated. Use `SubCommand::with_name()` instead. - /// - /// Creates a new instance of a subcommand requiring a name. Will be displayed - /// to the user when they print version or help and usage information. - /// - /// # Example - /// - /// ```no_run - /// # use clap::{App, Arg, SubCommand}; - /// # let prog = App::new("myprog").subcommand( - /// SubCommand::new("config") - /// # ).get_matches(); - /// ``` - pub fn new<'au, 'v, 'ab, 'u, 'h, 'ar>(name: &'ar str) -> App<'au, 'v, 'ab, 'u, 'h, 'ar> { - App::new(name) - } } From a5b8b3584ba00a00bf9656ba2343f76aa2322a4e Mon Sep 17 00:00:00 2001 From: Kevin K Date: Mon, 29 Jun 2015 22:21:47 -0400 Subject: [PATCH 4/5] test: fixes tests for 1.0 and deprecated functions --- clap-tests/src/main.rs | 6 ++--- examples/01a_QuickExample.rs | 2 +- examples/01b_QuickExample.rs | 2 +- examples/05_FlagArgs.rs | 2 +- examples/06_PositionalArgs.rs | 2 +- examples/07_OptionArgs.rs | 6 ++--- examples/08_SubCommands.rs | 2 +- src/app.rs | 6 ++--- src/args/arg.rs | 6 ++--- src/args/argmatches.rs | 20 +++++++-------- src/args/subcommand.rs | 6 ++--- src/lib.rs | 46 +++++++++++++++++------------------ 12 files changed, 53 insertions(+), 53 deletions(-) diff --git a/clap-tests/src/main.rs b/clap-tests/src/main.rs index 5cc096cefb4..a75a774a600 100644 --- a/clap-tests/src/main.rs +++ b/clap-tests/src/main.rs @@ -19,8 +19,8 @@ fn main() { .arg(Arg::from_usage("-f --flag... 'tests flags'") .global(true)) .args(vec![ - Arg::from_usage("[flag2] -F 'tests flags with exclusions'").mutually_excludes("flag").requires("option2"), - Arg::from_usage("--long-option-2 [option2] 'tests long options with exclusions'").mutually_excludes("option").requires("positional2"), + Arg::from_usage("[flag2] -F 'tests flags with exclusions'").conflicts_with("flag").requires("option2"), + Arg::from_usage("--long-option-2 [option2] 'tests long options with exclusions'").conflicts_with("option").requires("positional2"), Arg::from_usage("[positional2] 'tests positionals with exclusions'"), Arg::from_usage("-O --Option [option3] 'tests options with specific value sets'").possible_values(&opt3_vals), Arg::from_usage("[positional3]... 'tests positionals with specific values'").possible_values(&pos3_vals), @@ -29,7 +29,7 @@ fn main() { Arg::from_usage("--minvals2 [minvals]... 'Tests 2 min vals'").min_values(2), Arg::from_usage("--maxvals3 [maxvals]... 'Tests 3 max vals'").max_values(3) ]) - .subcommand(SubCommand::new("subcmd") + .subcommand(SubCommand::with_name("subcmd") .about("tests subcommands") .version("0.1") .author("Kevin K. ") diff --git a/examples/01a_QuickExample.rs b/examples/01a_QuickExample.rs index 60f3bd0804a..a13f2654264 100644 --- a/examples/01a_QuickExample.rs +++ b/examples/01a_QuickExample.rs @@ -37,7 +37,7 @@ fn main() { .args_from_usage("-c --config=[conf] 'Sets a custom config file' [output] 'Sets an optional output file' [debug]... -d 'Turn debugging information on'") - .subcommand(SubCommand::new("test") + .subcommand(SubCommand::with_name("test") .about("does testing things") .arg_from_usage("[list] -l 'lists test values'")) .get_matches(); diff --git a/examples/01b_QuickExample.rs b/examples/01b_QuickExample.rs index 91b0619231a..24dca7755e4 100644 --- a/examples/01b_QuickExample.rs +++ b/examples/01b_QuickExample.rs @@ -50,7 +50,7 @@ fn main() { .short("d") .multiple(true) .help("Turn debugging information on")) - .subcommand(SubCommand::new("test") + .subcommand(SubCommand::with_name("test") .about("does testing things") .arg(Arg::with_name("list") .short("l") diff --git a/examples/05_FlagArgs.rs b/examples/05_FlagArgs.rs index d54918ade9f..b3b1db9cf6c 100644 --- a/examples/05_FlagArgs.rs +++ b/examples/05_FlagArgs.rs @@ -27,7 +27,7 @@ fn main() { // also use this other 'config' arg too" // Can also specifiy a list using // requires_all(Vec<&str>) - .mutually_excludes("output") // Opposite of requires(), says "if the + .conflicts_with("output") // Opposite of requires(), says "if the // user uses -a, they CANNOT use 'output'" // also has a mutually_excludes_all(Vec<&str>) ) diff --git a/examples/06_PositionalArgs.rs b/examples/06_PositionalArgs.rs index a08330256cf..155895e0ec2 100644 --- a/examples/06_PositionalArgs.rs +++ b/examples/06_PositionalArgs.rs @@ -23,7 +23,7 @@ fn main() { // also use this other 'config' arg too" // Can also specifiy a list using // requires_all(Vec<&str>) - .mutually_excludes("output") // Opposite of requires(), says "if the + .conflicts_with("output") // Opposite of requires(), says "if the // user uses -a, they CANNOT use 'output'" // also has a mutually_excludes_all(Vec<&str>) .required(true) // By default this argument MUST be present diff --git a/examples/07_OptionArgs.rs b/examples/07_OptionArgs.rs index 64240b2c737..19ff7455012 100644 --- a/examples/07_OptionArgs.rs +++ b/examples/07_OptionArgs.rs @@ -31,11 +31,11 @@ fn main() { // also use this other 'config' arg too" // Can also specifiy a list using // requires_all(Vec<&str>) - .mutually_excludes("output") // Opposite of requires(), says "if the + .conflicts_with("output") // Opposite of requires(), says "if the // user uses -a, they CANNOT use 'output'" - // also has a mutually_excludes_all(Vec<&str>) + // also has a conflicts_with_all(Vec<&str>) ) - // NOTE: In order to compile this example, comment out mutually_excludes() + // NOTE: In order to compile this example, comment out conflicts_with() // and requires() because we have not defined an "output" or "config" // argument. .get_matches(); diff --git a/examples/08_SubCommands.rs b/examples/08_SubCommands.rs index ba454544572..f9997fd9be1 100644 --- a/examples/08_SubCommands.rs +++ b/examples/08_SubCommands.rs @@ -24,7 +24,7 @@ fn main() { // In the following example assume we wanted an application which // supported an "add" subcommand, this "add" subcommand also took // one positional argument of a file to add: - .subcommand(SubCommand::new("add") // The name we call argument with + .subcommand(SubCommand::with_name("add") // The name we call argument with .about("Adds files to myapp") // The message displayed in "myapp -h" // or "myapp help" .version("0.1") // Subcommands can have independent version diff --git a/src/app.rs b/src/app.rs index 8bfb0748d90..754199f6b45 100644 --- a/src/app.rs +++ b/src/app.rs @@ -927,7 +927,7 @@ impl<'a, 'v, 'ab, 'u, 'h, 'ar> App<'a, 'v, 'ab, 'u, 'h, 'ar>{ /// ```no_run /// # use clap::{App, Arg, SubCommand}; /// # App::new("myprog") - /// .subcommand(SubCommand::new("config") + /// .subcommand(SubCommand::with_name("config") /// .about("Controls configuration features") /// .arg_from_usage(" 'Required configuration file to use'")) /// // Additional subcommand configuration goes here, such as other arguments... @@ -949,9 +949,9 @@ impl<'a, 'v, 'ab, 'u, 'h, 'ar> App<'a, 'v, 'ab, 'u, 'h, 'ar>{ /// # use clap::{App, Arg, SubCommand}; /// # App::new("myprog") /// .subcommands( vec![ - /// SubCommand::new("config").about("Controls configuration functionality") + /// SubCommand::with_name("config").about("Controls configuration functionality") /// .arg(Arg::with_name("config_file").index(1)), - /// SubCommand::new("debug").about("Controls debug functionality")]) + /// SubCommand::with_name("debug").about("Controls debug functionality")]) /// # ; /// ``` pub fn subcommands(mut self, subcmds: Vec>) diff --git a/src/args/arg.rs b/src/args/arg.rs index f874f21ac89..cb29585ca00 100644 --- a/src/args/arg.rs +++ b/src/args/arg.rs @@ -310,7 +310,7 @@ impl<'n, 'l, 'h, 'g, 'p, 'r> Arg<'n, 'l, 'h, 'g, 'p, 'r> { /// # use clap::{App, Arg}; /// # let matches = App::new("myprog") /// # .arg( - /// # Arg::new("conifg") + /// # Arg::with_name("conifg") /// .short("c") /// # ).get_matches(); pub fn short(mut self, s: &str) -> Arg<'n, 'l, 'h, 'g, 'p, 'r> { @@ -334,7 +334,7 @@ impl<'n, 'l, 'h, 'g, 'p, 'r> Arg<'n, 'l, 'h, 'g, 'p, 'r> { /// # use clap::{App, Arg}; /// # let matches = App::new("myprog") /// # .arg( - /// # Arg::new("conifg") + /// # Arg::with_name("conifg") /// .long("config") /// # ).get_matches(); pub fn long(mut self, l: &'l str) -> Arg<'n, 'l, 'h, 'g, 'p, 'r> { @@ -352,7 +352,7 @@ impl<'n, 'l, 'h, 'g, 'p, 'r> Arg<'n, 'l, 'h, 'g, 'p, 'r> { /// # use clap::{App, Arg}; /// # let matches = App::new("myprog") /// # .arg( - /// # Arg::new("conifg") + /// # Arg::with_name("conifg") /// .help("The config file used by the myprog") /// # ).get_matches(); pub fn help(mut self, h: &'h str) -> Arg<'n, 'l, 'h, 'g, 'p, 'r> { diff --git a/src/args/argmatches.rs b/src/args/argmatches.rs index 0a562278c30..15d0d50a1fe 100644 --- a/src/args/argmatches.rs +++ b/src/args/argmatches.rs @@ -13,11 +13,11 @@ use args::MatchedArg; /// # use clap::{App, Arg}; /// let matches = App::new("MyApp") /// // adding of arguments and configuration goes here... -/// # .arg(Arg::new("config") +/// # .arg(Arg::with_name("config") /// # .long("config") /// # .required(true) /// # .takes_value(true)) -/// # .arg(Arg::new("debug") +/// # .arg(Arg::with_name("debug") /// # .short("d") /// # .multiple(true)) /// .get_matches(); @@ -91,7 +91,7 @@ impl<'n, 'a> ArgMatches<'n, 'a> { /// /// ```no_run /// # use clap::{App, Arg}; - /// # let matches = App::new("myapp").arg(Arg::new("output").takes_value(true)).get_matches(); + /// # let matches = App::new("myapp").arg(Arg::with_name("output").takes_value(true)).get_matches(); /// if let Some(o) = matches.value_of("output") { /// println!("Value for output: {}", o); /// } @@ -115,7 +115,7 @@ impl<'n, 'a> ArgMatches<'n, 'a> { /// /// ```no_run /// # use clap::{App, Arg}; - /// # let matches = App::new("myapp").arg(Arg::new("output").takes_value(true)).get_matches(); + /// # let matches = App::new("myapp").arg(Arg::with_name("output").takes_value(true)).get_matches(); /// // If the program had option "-c" that took a value and was run /// // via "myapp -o some -o other -o file" /// // values_of() would return a [&str; 3] ("some", "other", "file") @@ -141,7 +141,7 @@ impl<'n, 'a> ArgMatches<'n, 'a> { /// /// ```no_run /// # use clap::{App, Arg}; - /// # let matches = App::new("myapp").arg(Arg::new("output").takes_value(true)).get_matches(); + /// # let matches = App::new("myapp").arg(Arg::with_name("output").takes_value(true)).get_matches(); /// if matches.is_present("output") { /// println!("The output argument was used!"); /// } @@ -163,7 +163,7 @@ impl<'n, 'a> ArgMatches<'n, 'a> { /// /// ```no_run /// # use clap::{App, Arg}; - /// # let matches = App::new("myapp").arg(Arg::new("output").takes_value(true)).get_matches(); + /// # let matches = App::new("myapp").arg(Arg::with_name("output").takes_value(true)).get_matches(); /// if matches.occurrences_of("debug") > 1 { /// println!("Debug mode is REALLY on"); /// } else { @@ -185,7 +185,7 @@ impl<'n, 'a> ArgMatches<'n, 'a> { /// /// ```no_run /// # use clap::{App, Arg, SubCommand}; - /// # let app_matches = App::new("myapp").subcommand(SubCommand::new("test")).get_matches(); + /// # let app_matches = App::new("myapp").subcommand(SubCommand::with_name("test")).get_matches(); /// if let Some(matches) = app_matches.subcommand_matches("test") { /// // Use matches as normal /// } @@ -208,7 +208,7 @@ impl<'n, 'a> ArgMatches<'n, 'a> { /// /// ```no_run /// # use clap::{App, Arg, SubCommand}; - /// # let app_matches = App::new("myapp").subcommand(SubCommand::new("test")).get_matches(); + /// # let app_matches = App::new("myapp").subcommand(SubCommand::with_name("test")).get_matches(); /// match app_matches.subcommand_name() { /// Some("test") => {}, // test was used /// Some("config") => {}, // config was used @@ -230,7 +230,7 @@ impl<'n, 'a> ArgMatches<'n, 'a> { /// /// ```no_run /// # use clap::{App, Arg, SubCommand}; - /// # let app_matches = App::new("myapp").subcommand(SubCommand::new("test")).get_matches(); + /// # let app_matches = App::new("myapp").subcommand(SubCommand::with_name("test")).get_matches(); /// match app_matches.subcommand() { /// ("test", Some(matches)) => {}, // test was used /// ("config", Some(matches)) => {}, // config was used @@ -251,7 +251,7 @@ impl<'n, 'a> ArgMatches<'n, 'a> { /// /// ```no_run /// # use clap::{App, Arg, SubCommand}; - /// # let app_matches = App::new("myapp").subcommand(SubCommand::new("test")).get_matches(); + /// # let app_matches = App::new("myapp").subcommand(SubCommand::with_name("test")).get_matches(); /// println!("{}",app_matches.usage()); /// ``` pub fn usage(&self) -> &str { diff --git a/src/args/subcommand.rs b/src/args/subcommand.rs index 559d3eea111..6fa468e5925 100644 --- a/src/args/subcommand.rs +++ b/src/args/subcommand.rs @@ -14,9 +14,9 @@ use ArgMatches; /// # use clap::{App, Arg, SubCommand}; /// # let matches = App::new("myprog") /// # .subcommand( -/// SubCommand::new("conifg") +/// SubCommand::with_name("conifg") /// .about("Used for configuration") -/// .arg(Arg::new("config_file") +/// .arg(Arg::with_name("config_file") /// .help("The configuration file to use") /// .index(1)) /// # ).get_matches(); @@ -36,7 +36,7 @@ impl<'n, 'a> SubCommand<'n, 'a> { /// ```no_run /// # use clap::{App, Arg, SubCommand}; /// # let prog = App::new("myprog").subcommand( - /// SubCommand::new("config") + /// SubCommand::with_name("config") /// # ).get_matches(); /// ``` pub fn with_name<'au, 'v, 'ab, 'u, 'h, 'ar>(name: &'ar str) -> App<'au, 'v, 'ab, 'u, 'h, 'ar> { diff --git a/src/lib.rs b/src/lib.rs index 56924441f18..6a5fdd0130f 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -81,7 +81,7 @@ //! "-c --config=[CONFIG] 'Sets a custom config file' //! 'Sets the input file to use' //! [debug]... -d 'Sets the level of debugging information'") -//! .subcommand(SubCommand::new("test") +//! .subcommand(SubCommand::with_name("test") //! .about("controls testing features") //! .version("1.3") //! .author("Someone E. ") @@ -148,7 +148,7 @@ //! .short("d") //! .multiple(true) //! .help("Sets the level of debugging information")) -//! .subcommand(SubCommand::new("test") +//! .subcommand(SubCommand::with_name("test") //! .about("controls testing features") //! .version("1.3") //! .author("Someone E. ") @@ -374,10 +374,10 @@ //! Old method names will be left around for some time. //! //! * As of 0.10.0 -//! - `SubCommand::new()` -> `SubCommand::with_name()` +//! - `SubCommand::with_name()` -> `SubCommand::with_name()` //! - `App::error_on_no_subcommand()` -> `App::subcommand_required()` //! * As of 0.6.8 -//! - `Arg::new()` -> `Arg::with_name()` +//! - `Arg::with_name()` -> `Arg::with_name()` //! - `Arg::mutually_excludes()` -> `Arg::conflicts_with()` //! - `Arg::mutually_excludes_all()` -> `Arg::conflicts_with_all()` #[cfg(feature = "suggestions")] @@ -484,15 +484,15 @@ mod tests { fn add_multiple_arg() { let _ = App::new("test") .args( vec![ - Arg::new("test").short("s"), - Arg::new("test2").short("l")]) + Arg::with_name("test").short("s"), + Arg::with_name("test2").short("l")]) .get_matches(); } #[test] fn create_flag() { let _ = App::new("test") - .arg(Arg::new("test") + .arg(Arg::with_name("test") .short("t") .long("test") .help("testing testing")) @@ -594,7 +594,7 @@ mod tests { #[test] fn create_positional() { let _ = App::new("test") - .arg(Arg::new("test") + .arg(Arg::with_name("test") .index(1) .help("testing testing")) .get_matches(); @@ -687,7 +687,7 @@ mod tests { #[test] fn create_option() { let _ = App::new("test") - .arg(Arg::new("test") + .arg(Arg::with_name("test") .short("t") .long("test") .takes_value(true) @@ -1281,28 +1281,28 @@ mod tests { #[test] fn create_subcommand() { let _ = App::new("test") - .subcommand(SubCommand::new("some") - .arg(Arg::new("test") + .subcommand(SubCommand::with_name("some") + .arg(Arg::with_name("test") .short("t") .long("test") .takes_value(true) .help("testing testing"))) - .arg(Arg::new("other").long("other")) + .arg(Arg::with_name("other").long("other")) .get_matches(); } #[test] fn create_multiple_subcommands() { let _ = App::new("test") - .subcommands(vec![ SubCommand::new("some") - .arg(Arg::new("test") + .subcommands(vec![ SubCommand::with_name("some") + .arg(Arg::with_name("test") .short("t") .long("test") .takes_value(true) .help("testing testing")), - SubCommand::new("add") - .arg(Arg::new("roster").short("r"))]) - .arg(Arg::new("other").long("other")) + SubCommand::with_name("add") + .arg(Arg::with_name("roster").short("r"))]) + .arg(Arg::with_name("other").long("other")) .get_matches(); } @@ -1310,8 +1310,8 @@ mod tests { #[should_panic] fn unique_arg_names() { App::new("some").args(vec![ - Arg::new("arg").short("a"), - Arg::new("arg").short("b") + Arg::with_name("arg").short("a"), + Arg::with_name("arg").short("b") ]); } @@ -1319,8 +1319,8 @@ mod tests { #[should_panic] fn unique_arg_shorts() { App::new("some").args(vec![ - Arg::new("arg1").short("a"), - Arg::new("arg2").short("a") + Arg::with_name("arg1").short("a"), + Arg::with_name("arg2").short("a") ]); } @@ -1328,8 +1328,8 @@ mod tests { #[should_panic] fn unique_arg_longs() { App::new("some").args(vec![ - Arg::new("arg1").long("long"), - Arg::new("arg2").long("long") + Arg::with_name("arg1").long("long"), + Arg::with_name("arg2").long("long") ]); } } From ff149a29dd9e179865e6d577cd7dc87c54f8f95c Mon Sep 17 00:00:00 2001 From: Kevin K Date: Mon, 29 Jun 2015 22:22:13 -0400 Subject: [PATCH 5/5] docs: adds "whats new" section to readme --- README.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/README.md b/README.md index 67cf8f00fba..9c988b07352 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,16 @@ Command Line Argument Parser for Rust It is a simple to use, efficient, and full featured library for parsing command line arguments and subcommands when writing console, or terminal applications. +## What's New + +If you're already familiar with `clap` but just want to see some new highlights as of **1.0.0-beta** + +* **Deprecated Functions Removed** - In an effort to start a 1.x all deprecated functions have been removed, see the deprecations sections below to update your code (very minimal) +* **Can fully override help** - This allows you fully override the auto-generated help if you so choose +* **Can wait for user input on error** - This is helpful mainly on Windows if a user mistakenly opens your application via double-click, or you'd like to provide a GUI shortcut to run your application + +For full details see the [changelog](https://github.com/kbknapp/clap-rs/blob/master/CHANGELOG.md) + ## About `clap` is used to parse *and validate* the string of command line arguments provided by the user at runtime. You provide the list of valid possibilities, and `clap` handles the rest. This means you focus on your *applications* functionality, and less on the parsing and validating of arguments.