diff options
Diffstat (limited to 'clap/examples')
26 files changed, 0 insertions, 1550 deletions
diff --git a/clap/examples/01a_quick_example.rs b/clap/examples/01a_quick_example.rs deleted file mode 100644 index c7fa20f..0000000 --- a/clap/examples/01a_quick_example.rs +++ /dev/null @@ -1,79 +0,0 @@ -extern crate clap; - -use clap::{App, SubCommand}; - -fn main() { - - // This example shows how to create an application with several arguments using usage strings, which can be - // far less verbose that shown in 01b_QuickExample.rs, but is more readable. The downside is you cannot set - // the more advanced configuration options using this method (well...actually you can, you'll see ;) ) - // - // The example below is functionally identical to the 01b_quick_example.rs and 01c_quick_example.rs - // - // Create an application with 5 possible arguments (2 auto generated) and 2 subcommands (1 auto generated) - // - A config file - // + Uses "-c filename" or "--config filename" - // - An output file - // + A positional argument (i.e. "$ myapp output_filename") - // - A debug flag - // + Uses "-d" or "--debug" - // + Allows multiple occurrences of such as "-dd" (for vary levels of debugging, as an example) - // - A help flag (automatically generated by clap) - // + Uses "-h" or "--help" (Only autogenerated if you do NOT specify your own "-h" or "--help") - // - A version flag (automatically generated by clap) - // + Uses "-V" or "--version" (Only autogenerated if you do NOT specify your own "-V" or "--version") - // - A subcommand "test" (subcommands behave like their own apps, with their own arguments - // + Used by "$ myapp test" with the following arguments - // > A list flag - // = Uses "-l" (usage is "$ myapp test -l" - // > A help flag (automatically generated by clap - // = Uses "-h" or "--help" (full usage "$ myapp test -h" or "$ myapp test --help") - // > A version flag (automatically generated by clap - // = Uses "-V" or "--version" (full usage "$ myapp test -V" or "$ myapp test --version") - // - A subcommand "help" (automatically generated by clap because we specified a subcommand of our own) - // + Used by "$ myapp help" (same functionality as "-h" or "--help") - let matches = App::new("MyApp") - .version("1.0") - .author("Kevin K. <kbknapp@gmail.com>") - .about("Does awesome things") - .args_from_usage("-c, --config=[FILE] 'Sets a custom config file' - <output> 'Sets an optional output file' - -d... 'Turn debugging information on'") - .subcommand(SubCommand::with_name("test") - .about("does testing things") - .arg_from_usage("-l, --list 'lists test values'")) - .get_matches(); - - // You can check the value provided by positional arguments, or option arguments - if let Some(o) = matches.value_of("output") { - println!("Value for output: {}", o); - } - - if let Some(c) = matches.value_of("config") { - println!("Value for config: {}", c); - } - - // You can see how many times a particular flag or argument occurred - // Note, only flags can have multiple occurrences - match matches.occurrences_of("d") { - 0 => println!("Debug mode is off"), - 1 => println!("Debug mode is kind of on"), - 2 => println!("Debug mode is on"), - 3 | _ => println!("Don't be crazy"), - } - - // You can check for the existence of subcommands, and if found use their - // matches just as you would the top level app - if let Some(matches) = matches.subcommand_matches("test") { - // "$ myapp test" was run - if matches.is_present("list") { - // "$ myapp test -l" was run - println!("Printing testing lists..."); - } else { - println!("Not printing testing lists..."); - } - } - - - // Continued program logic goes here... -} diff --git a/clap/examples/01b_quick_example.rs b/clap/examples/01b_quick_example.rs deleted file mode 100644 index 7f455a8..0000000 --- a/clap/examples/01b_quick_example.rs +++ /dev/null @@ -1,93 +0,0 @@ -extern crate clap; - -use clap::{App, Arg, SubCommand}; - -fn main() { - - // This method shows the traditional, and slightly more configurable way to set up arguments. This method is - // more verbose, but allows setting more configuration options, and even supports easier dynamic generation. - // - // The example below is functionally identical to the 01a_quick_example.rs and 01c_quick_example.rs - // - // *NOTE:* You can actually achieve the best of both worlds by using Arg::from_usage() (instead of Arg::with_name()) - // and *then* setting any additional properties. - // - // Create an application with 5 possible arguments (2 auto generated) and 2 subcommands (1 auto generated) - // - A config file - // + Uses "-c filename" or "--config filename" - // - An output file - // + A positional argument (i.e. "$ myapp output_filename") - // - A debug flag - // + Uses "-d" or "--debug" - // + Allows multiple occurrences of such as "-dd" (for vary levels of debugging, as an example) - // - A help flag (automatically generated by clap) - // + Uses "-h" or "--help" (Only autogenerated if you do NOT specify your own "-h" or "--help") - // - A version flag (automatically generated by clap) - // + Uses "-V" or "--version" (Only autogenerated if you do NOT specify your own "-V" or "--version") - // - A subcommand "test" (subcommands behave like their own apps, with their own arguments - // + Used by "$ myapp test" with the following arguments - // > A list flag - // = Uses "-l" (usage is "$ myapp test -l" - // > A help flag (automatically generated by clap - // = Uses "-h" or "--help" (full usage "$ myapp test -h" or "$ myapp test --help") - // > A version flag (automatically generated by clap - // = Uses "-V" or "--version" (full usage "$ myapp test -V" or "$ myapp test --version") - // - A subcommand "help" (automatically generated by clap because we specified a subcommand of our own) - // + Used by "$ myapp help" (same functionality as "-h" or "--help") - let matches = App::new("MyApp") - .version("1.0") - .author("Kevin K. <kbknapp@gmail.com>") - .about("Does awesome things") - .arg(Arg::with_name("config") - .short("c") - .long("config") - .value_name("FILE") - .help("Sets a custom config file") - .takes_value(true)) - .arg(Arg::with_name("output") - .help("Sets an optional output file") - .index(1)) - .arg(Arg::with_name("debug") - .short("d") - .multiple(true) - .help("Turn debugging information on")) - .subcommand(SubCommand::with_name("test") - .about("does testing things") - .arg(Arg::with_name("list") - .short("l") - .help("lists test values"))) - .get_matches(); - - // You can check the value provided by positional arguments, or option arguments - if let Some(o) = matches.value_of("output") { - println!("Value for output: {}", o); - } - - if let Some(c) = matches.value_of("config") { - println!("Value for config: {}", c); - } - - // You can see how many times a particular flag or argument occurred - // Note, only flags can have multiple occurrences - match matches.occurrences_of("debug") { - 0 => println!("Debug mode is off"), - 1 => println!("Debug mode is kind of on"), - 2 => println!("Debug mode is on"), - 3 | _ => println!("Don't be crazy"), - } - - // You can check for the existence of subcommands, and if found use their - // matches just as you would the top level app - if let Some(matches) = matches.subcommand_matches("test") { - // "$ myapp test" was run - if matches.is_present("list") { - // "$ myapp test -l" was run - println!("Printing testing lists..."); - } else { - println!("Not printing testing lists..."); - } - } - - - // Continued program logic goes here... -} diff --git a/clap/examples/01c_quick_example.rs b/clap/examples/01c_quick_example.rs deleted file mode 100644 index 071bdc0..0000000 --- a/clap/examples/01c_quick_example.rs +++ /dev/null @@ -1,75 +0,0 @@ -#[macro_use] -extern crate clap; - -fn main() { - // This example shows how to create an application with several arguments using macro builder. - // It combines the simplicity of the from_usage methods and the performance of the Builder Pattern. - // - // The example below is functionally identical to the one in 01a_quick_example.rs and 01b_quick_example.rs - // - // Create an application with 5 possible arguments (2 auto generated) and 2 subcommands (1 auto generated) - // - A config file - // + Uses "-c filename" or "--config filename" - // - An output file - // + A positional argument (i.e. "$ myapp output_filename") - // - A debug flag - // + Uses "-d" or "--debug" - // + Allows multiple occurrences of such as "-dd" (for vary levels of debugging, as an example) - // - A help flag (automatically generated by clap) - // + Uses "-h" or "--help" (Only autogenerated if you do NOT specify your own "-h" or "--help") - // - A version flag (automatically generated by clap) - // + Uses "-V" or "--version" (Only autogenerated if you do NOT specify your own "-V" or "--version") - // - A subcommand "test" (subcommands behave like their own apps, with their own arguments - // + Used by "$ myapp test" with the following arguments - // > A list flag - // = Uses "-l" (usage is "$ myapp test -l" - // > A help flag (automatically generated by clap - // = Uses "-h" or "--help" (full usage "$ myapp test -h" or "$ myapp test --help") - // > A version flag (automatically generated by clap - // = Uses "-V" or "--version" (full usage "$ myapp test -V" or "$ myapp test --version") - // - A subcommand "help" (automatically generated by clap because we specified a subcommand of our own) - // + Used by "$ myapp help" (same functionality as "-h" or "--help") - let matches = clap_app!(myapp => - (version: "1.0") - (author: "Kevin K. <kbknapp@gmail.com>") - (about: "Does awesome things") - (@arg CONFIG: -c --config +takes_value "Sets a custom config file") - (@arg INPUT: +required "Sets the input file to use") - (@arg debug: -d ... "Sets the level of debugging information") - (@subcommand test => - (about: "controls testing features") - (version: "1.3") - (author: "Someone E. <someone_else@other.com>") - (@arg verbose: -v --verbose "Print test information verbosely") - ) - ).get_matches(); - - // Calling .unwrap() is safe here because "INPUT" is required (if "INPUT" wasn't - // required we could have used an 'if let' to conditionally get the value) - println!("Using input file: {}", matches.value_of("INPUT").unwrap()); - - // Gets a value for config if supplied by user, or defaults to "default.conf" - let config = matches.value_of("CONFIG").unwrap_or("default.conf"); - println!("Value for config: {}", config); - - // Vary the output based on how many times the user used the "debug" flag - // (i.e. 'myapp -d -d -d' or 'myapp -ddd' vs 'myapp -d' - match matches.occurrences_of("debug") { - 0 => println!("Debug mode is off"), - 1 => println!("Debug mode is kind of on"), - 2 => println!("Debug mode is on"), - 3 | _ => println!("Don't be crazy"), - } - - // You can information about subcommands by requesting their matches by name - // (as below), requesting just the name used, or both at the same time - if let Some(matches) = matches.subcommand_matches("test") { - if matches.is_present("verbose") { - println!("Printing verbosely..."); - } else { - println!("Printing normally..."); - } - } - - // more program logic goes here... -} diff --git a/clap/examples/02_apps.rs b/clap/examples/02_apps.rs deleted file mode 100644 index 8e45640..0000000 --- a/clap/examples/02_apps.rs +++ /dev/null @@ -1,30 +0,0 @@ -extern crate clap; - -use clap::App; - -fn main() { - // Apps describe the top level application - // - // You create an App and set various options on that App using the "builder pattern" - // - // The options (version(), author(), about()) aren't mandatory, but recommended. There is - // another option, usage(), which is an exception to the rule. This should only be used when - // the default usage string automatically generated by clap doesn't suffice. - // - // You also set all the valid arguments your App should accept via the arg(), args(), arg_from_usage() - // and args_from_usage() (as well as subcommands via the subcommand() and subcommands() methods) which - // will be covered later. - // - // Once all options have been set, call one of the .get_matches* family of methods in order to - // start the parsing and find all valid command line arguments that supplied by the user at - // runtime. The name given to new() will be displayed when the version or help flags are used. - App::new("MyApp") - .version("1.0") - .author("Kevin K. <kbknapp@gmail.com>") - .about("Does awesome things") - .get_matches(); - - // This example doesn't do much, but it *does* give automatic -h, --help, -V, and --version functionality ;) - - // Continued program logic goes here... -} diff --git a/clap/examples/03_args.rs b/clap/examples/03_args.rs deleted file mode 100644 index c62d576..0000000 --- a/clap/examples/03_args.rs +++ /dev/null @@ -1,84 +0,0 @@ -extern crate clap; - -use clap::{App, Arg}; - -fn main() { - // Args describe a possible valid argument which may be supplied by the user at runtime. There - // are three different types of arguments (flags, options, and positional) as well as a fourth - // special type of argument, called SubCommands (which will be discussed separately). - // - // Args are described in the same manner as Apps using the "builder pattern" with multiple - // methods describing various settings for the individual arguments. Or by supplying a "usage" - // string. Both methods have their pros and cons. - // - // Arguments can be added to applications in two manners, one at a time with the arg(), and - // arg_from_usage() method, or multiple arguments at once via a Vec<Arg> inside the args() method, - // or a single &str describing multiple Args (one per line) supplied to args_from_usage(). - // - // There are various options which can be set for a given argument, some apply to any of the - // three types of arguments, some only apply one or two of the types. *NOTE* if you set - // incompatible options on a single argument, clap will panic! at runtime. This is by design, - // so that you know right away an error was made by the developer, not the end user. - // - // # Help and Version - // clap automatically generates a help and version flag for you, unless you specify your - // own. By default help uses "-h" and "--help", and version uses "-V" and "--version". You can - // safely override "-V" and "-h" to your own arguments, and "--help" and "--version" will still - // be automatically generated for you. - let matches = App::new("MyApp") - // All application settings go here... - - // A simple "Flag" argument example (i.e. "-d") using the builder pattern - .arg(Arg::with_name("debug") - .help("turn on debugging information") - .short("d")) - - // Two arguments, one "Option" argument (i.e. one that takes a value) such - // as "-c some", and one positional argument (i.e. "myapp some_file") - .args(&[ - Arg::with_name("config") - .help("sets the config file to use") - .takes_value(true) - .short("c") - .long("config"), - Arg::with_name("input") - .help("the input file to use") - .index(1) - .required(true) - ]) - - // *Note* the following two examples are convenience methods, if you wish - // to still get the full configurability of Arg::with_name() and the readability - // of arg_from_usage(), you can instantiate a new Arg with Arg::from_usage() and - // still be able to set all the additional properties, just like Arg::with_name() - // - // - // One "Flag" using a usage string - .arg_from_usage("--license 'display the license file'") - - // Two args, one "Positional", and one "Option" using a usage string - .args_from_usage("[output] 'Supply an output file to use' - -i, --int=[IFACE] 'Set an interface to use'") - .get_matches(); - - // Here are some examples of using the arguments defined above. Keep in mind that this is only - // an example, and may be somewhat contrived - // - // First we check if debugging should be on or not - println!("Debugging mode is: {}", if matches.is_present("debug") { "ON" } else { "OFF" }); - - // Next we print the config file we're using, if any was defined with either -c <file> or - // --config <file> - if let Some(config) = matches.value_of("config") { - println!("A config file was passed in: {}", config); - } - - // Let's print the <INPUT> file the user passed in. We can use .unwrap() here becase the arg is - // required, and parsing would have failed if the user forgot it - println!("Using input file: {}", matches.value_of("input").unwrap()); - - // We could continue checking for and using arguments in this manner, such as "license", - // "output", and "interface". Keep in mind that "output" and "interface" are optional, so you - // shouldn't call .unwrap(). Instead, prefer using an 'if let' expression as we did with - // "config" -} diff --git a/clap/examples/04_using_matches.rs b/clap/examples/04_using_matches.rs deleted file mode 100644 index a0a986f..0000000 --- a/clap/examples/04_using_matches.rs +++ /dev/null @@ -1,54 +0,0 @@ -extern crate clap; - -use clap::{App, Arg}; - -fn main() { - - // Once all App settings (including all arguments) have been set, you call get_matches() which - // parses the string provided by the user, and returns all the valid matches to the ones you - // specified. - // - // You can then query the matches struct to get information about how the user ran the program - // at startup. - // - // For this example, let's assume you created an App which accepts three arguments (plus two - // generated by clap), a flag to display debugging information triggered with "-d" or - // "--debug" as well as an option argument which specifies a custom configuration file to use - // triggered with "-c file" or "--config file" or "--config=file" and finally a positional - // argument which is the input file we want to work with, this will be the only required - // argument. - let matches = App::new("MyApp") - .about("Parses an input file to do awesome things") - .version("1.0") - .author("Kevin K. <kbknapp@gmail.com>") - .arg(Arg::with_name("debug") - .help("turn on debugging information") - .short("d") - .long("debug")) - .arg(Arg::with_name("config") - .help("sets the config file to use") - .short("c") - .long("config")) - .arg(Arg::with_name("input") - .help("the input file to use") - .index(1) - .required(true)) - .get_matches(); - - // We can find out whether or not debugging was turned on - if matches.is_present("debug") { - println!("Debugging is turned on"); - } - - // If we wanted to do some custom initialization based off some configuration file - // provided by the user, we could get the file (A string of the file) - if let Some(file) = matches.value_of("config") { - println!("Using config file: {}", file); - } - - // Because "input" is required we can safely call unwrap() because had the user NOT - // specified a value, clap would have explained the error the user, and exited. - println!("Doing real work with file: {}", matches.value_of("input").unwrap() ); - - // Continued program logic goes here... -} diff --git a/clap/examples/05_flag_args.rs b/clap/examples/05_flag_args.rs deleted file mode 100644 index a6b8945..0000000 --- a/clap/examples/05_flag_args.rs +++ /dev/null @@ -1,56 +0,0 @@ -extern crate clap; - -use clap::{App, Arg}; - -fn main() { - - // Of the three argument types, flags are the most simple. Flags are simple switches which can - // be either "on" or "off" - // - // clap also supports multiple occurrences of flags, the common example is "verbosity" where a - // user could want a little information with "-v" or tons of information with "-v -v" or "-vv" - let matches = App::new("MyApp") - // Regular App configuration goes here... - - // We'll add a flag that represents an awesome meter... - // - // I'll explain each possible setting that "flags" accept. Keep in mind - // that you DO NOT need to set each of these for every flag, only the ones - // you want for your individual case. - .arg(Arg::with_name("awesome") - .help("turns up the awesome") // Displayed when showing help info - .short("a") // Trigger this arg with "-a" - .long("awesome") // Trigger this arg with "--awesome" - .multiple(true) // This flag should allow multiple - // occurrences such as "-aaa" or "-a -a" - .requires("config") // Says, "If the user uses -a, they MUST - // also use this other 'config' arg too" - // Can also specify a list using - // requires_all(Vec<&str>) - .conflicts_with("output") // Opposite of requires(), says "if the - // user uses -a, they CANNOT use 'output'" - // also has a conflicts_with_all(Vec<&str>) - ) - // NOTE: In order to compile this example, comment out requires() and - // conflicts_with() because we have not defined an "output" or "config" - // argument. - .get_matches(); - - // We can find out whether or not awesome was used - if matches.is_present("awesome") { - println!("Awesomeness is turned on"); - } - - // If we set the multiple() option of a flag we can check how many times the user specified - // - // Note: if we did not specify the multiple() option, and the user used "awesome" we would get - // a 1 (no matter how many times they actually used it), or a 0 if they didn't use it at all - match matches.occurrences_of("awesome") { - 0 => println!("Nothing is awesome"), - 1 => println!("Some things are awesome"), - 2 => println!("Lots of things are awesome"), - 3 | _ => println!("EVERYTHING is awesome!"), - } - - // Continued program logic goes here... -} diff --git a/clap/examples/06_positional_args.rs b/clap/examples/06_positional_args.rs deleted file mode 100644 index 1f29612..0000000 --- a/clap/examples/06_positional_args.rs +++ /dev/null @@ -1,56 +0,0 @@ -extern crate clap; - -use clap::{App, Arg}; - -fn main() { - - // Positional arguments are those values after the program name which are not preceded by any - // identifier (such as "myapp some_file"). Positionals support many of the same options as - // flags, as well as a few additional ones. - let matches = App::new("MyApp") - // Regular App configuration goes here... - - // We'll add two positional arguments, a input file, and a config file. - // - // I'll explain each possible setting that "positionals" accept. Keep in - // mind that you DO NOT need to set each of these for every flag, only the - // ones that apply to your individual case. - .arg(Arg::with_name("input") - .help("the input file to use") // Displayed when showing help info - .index(1) // Set the order in which the user must - // specify this argument (Starts at 1) - .requires("config") // Says, "If the user uses "input", they MUST - // also use this other 'config' arg too" - // Can also specify a list using - // requires_all(Vec<&str>) - .conflicts_with("output") // Opposite of requires(), says "if the - // user uses -a, they CANNOT use 'output'" - // also has a conflicts_with_all(Vec<&str>) - .required(true) // By default this argument MUST be present - // NOTE: mutual exclusions take precedence over - // required arguments - ) - .arg(Arg::with_name("config") - .help("the config file to use") - .index(2)) // Note, we do not need to specify required(true) - // if we don't want to, because "input" already - // requires "config" - // Note, we also do not need to specify requires("input") - // because requires lists are automatically two-way - - // NOTE: In order to compile this example, comment out conflicts_with() - // because we have not defined an "output" argument. - .get_matches(); - - // We can find out whether or not "input" or "config" were used - if matches.is_present("input") { - println!("An input file was specified"); - } - - // We can also get the values for those arguments - if let Some(in_file) = matches.value_of("input") { - // It's safe to call unwrap() because of the required options we set above - println!("Doing work with {} and {}", in_file, matches.value_of("config").unwrap()); - } - // Continued program logic goes here... -} diff --git a/clap/examples/07_option_args.rs b/clap/examples/07_option_args.rs deleted file mode 100644 index 85ff0e5..0000000 --- a/clap/examples/07_option_args.rs +++ /dev/null @@ -1,71 +0,0 @@ -extern crate clap; - -use clap::{App, Arg}; - -fn main() { - - // Option arguments are those that take an additional value, such as "-c value". In clap they - // support three types of specification, those with short() as "-o some", or those with long() - // as "--option value" or "--option=value" - // - // Options also support a multiple setting, which is discussed in the example below. - let matches = App::new("MyApp") - // Regular App configuration goes here... - - // Assume we have an application that accepts an input file via the "-i file" - // or the "--input file" (as well as "--input=file"). - // Below every setting supported by option arguments is discussed. - // NOTE: You DO NOT need to specify each setting, only those which apply - // to your particular case. - .arg(Arg::with_name("input") - .help("the input file to use") // Displayed when showing help info - .takes_value(true) // MUST be set to true in order to be an "option" argument - .short("i") // This argument is triggered with "-i" - .long("input") // This argument is triggered with "--input" - .multiple(true) // Set to true if you wish to allow multiple occurrences - // such as "-i file -i other_file -i third_file" - .required(true) // By default this argument MUST be present - // NOTE: mutual exclusions take precedence over - // required arguments - .requires("config") // Says, "If the user uses "input", they MUST - // also use this other 'config' arg too" - // Can also specify a list using - // requires_all(Vec<&str>) - .conflicts_with("output") // Opposite of requires(), says "if the - // user uses -a, they CANNOT use 'output'" - // also has a conflicts_with_all(Vec<&str>) - ) - // 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(); - - // We can find out whether or not "input" was used - if matches.is_present("input") { - println!("An input file was specified"); - } - - // We can also get the value for "input" - // - // NOTE: If we specified multiple(), this will only return the _FIRST_ - // occurrence - if let Some(in_file) = matches.value_of("input") { - println!("An input file: {}", in_file); - } - - // If we specified the multiple() setting we can get all the values - if let Some(in_v) = matches.values_of("input") { - for in_file in in_v { - println!("An input file: {}", in_file); - } - } - - // We can see how many times the option was used with the occurrences_of() method - // - // NOTE: Just like with flags, if we did not specify the multiple() setting this will only - // return 1 no matter how many times the argument was used (unless it wasn't used at all, in - // in which case 0 is returned) - println!("The \"input\" argument was used {} times", matches.occurrences_of("input")); - - // Continued program logic goes here... -} diff --git a/clap/examples/08_subcommands.rs b/clap/examples/08_subcommands.rs deleted file mode 100644 index 73bd098..0000000 --- a/clap/examples/08_subcommands.rs +++ /dev/null @@ -1,57 +0,0 @@ -extern crate clap; - -use clap::{App, Arg, SubCommand}; - -fn main() { - - // SubCommands function exactly like sub-Apps, because that's exactly what they are. Each - // instance of a SubCommand can have it's own version, author(s), Args, and even it's own - // subcommands. - // - // # Help and Version - // Just like Apps, each subcommand will get it's own "help" and "version" flags automatically - // generated. Also, like Apps, you can override "-V" or "-h" safely and still get "--help" and - // "--version" auto generated. - // - // NOTE: If you specify a subcommand for your App, clap will also autogenerate a "help" - // subcommand along with "-h" and "--help" (applies to sub-subcommands as well). - // - // Just like arg() and args(), subcommands can be specified one at a time via subcommand() or - // multiple ones at once with a Vec<SubCommand> provided to subcommands(). - let matches = App::new("MyApp") - // Normal App and Arg configuration goes here... - - // 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::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 - .author("Kevin K.") // And authors - .arg(Arg::with_name("input") // And their own arguments - .help("the file to add") - .index(1) - .required(true))) - .get_matches(); - - // You can check if a subcommand was used like normal - if matches.is_present("add") { - println!("'myapp add' was run."); - } - - // You can get the independent subcommand matches (which function exactly like App matches) - if let Some(matches) = matches.subcommand_matches("add") { - // Safe to use unwrap() because of the required() option - println!("Adding file: {}", matches.value_of("input").unwrap()); - } - - // You can also match on a subcommand's name - match matches.subcommand_name() { - Some("add") => println!("'myapp add' was used"), - None => println!("No subcommand was used"), - _ => println!("Some other subcommand was used"), - } - - // Continued program logic goes here... -} diff --git a/clap/examples/09_auto_version.rs b/clap/examples/09_auto_version.rs deleted file mode 100644 index dfd221f..0000000 --- a/clap/examples/09_auto_version.rs +++ /dev/null @@ -1,29 +0,0 @@ -#[macro_use] -extern crate clap; - -use clap::App; - -fn main() { - // You can have clap pull the application version directly from your Cargo.toml starting with - // clap v0.4.14 on crates.io (or master#a81f915 on github). Using Rust's env! macro like this: - // - // let version = format!("{}.{}.{}{}", - // env!("CARGO_PKG_VERSION_MAJOR"), - // env!("CARGO_PKG_VERSION_MINOR"), - // env!("CARGO_PKG_VERSION_PATCH"), - // option_env!("CARGO_PKG_VERSION_PRE").unwrap_or("")); - // - // Starting from v0.6.6 on crates.io you can also use the crate_version!() macro instead of - // manually using the env!() macros. Under the hood, the macro uses this exact method to get - // the version. - // - // Thanks to https://github.com/jhelwig for pointing this out - App::new("myapp") - .about("does awesome things") - // use crate_version! to pull the version number - .version(crate_version!()) - .get_matches(); - - // running this app with the -V or --version will display whatever version is in your - // Cargo.toml, the default being: myapp 0.0.1 -} diff --git a/clap/examples/10_default_values.rs b/clap/examples/10_default_values.rs deleted file mode 100644 index ca50981..0000000 --- a/clap/examples/10_default_values.rs +++ /dev/null @@ -1,40 +0,0 @@ -extern crate clap; - -use clap::{App, Arg}; - -fn main() { - // There are two ways in which to get a default value, one is to use claps Arg::default_value - // method, and the other is to use Rust's built in Option::unwrap_or method. - // - // I'll demo both here. - // - // First, we'll use clap's Arg::default_value with an "INPUT" file. - let matches = App::new("myapp").about("does awesome things") - .arg(Arg::with_name("INPUT") - .help("The input file to use") // Note, we don't need to specify - // anything like, "Defaults to..." - // because clap will automatically - // generate that for us, and place - // it in the help text - .default_value("input.txt") - .index(1)) - - // Next we'll use the Option::unwrap_or method on this "CONFIG" option - .arg(Arg::with_name("CONFIG") - // Note that we have to manually include some verbiage to the user - // telling them what the default will be. - .help("The config file to use (default is \"config.json\")") - .short("c") - .takes_value(true)) - .get_matches(); - - // It's safe to call unwrap because the value with either be what the user input at runtime - // or "input.txt" - let input = matches.value_of("INPUT").unwrap(); - - // Using Option::unwrap_or we get the same affect, but without the added help text injection - let config_file = matches.value_of("CONFIG").unwrap_or("config.json"); - - println!("The input file is: {}", input); - println!("The config file is: {}", config_file); -} diff --git a/clap/examples/11_only_specific_values.rs b/clap/examples/11_only_specific_values.rs deleted file mode 100644 index 3445218..0000000 --- a/clap/examples/11_only_specific_values.rs +++ /dev/null @@ -1,33 +0,0 @@ -extern crate clap; - -use clap::{App, Arg}; - -fn main() { - // If you have arguments of specific values you want to test for, you can use the - // .possible_values() method of Arg - // - // This allows you specify the valid values for that argument. If the user does not use one of - // those specific values, they will receive a graceful exit with error message informing them - // of the mistake, and what the possible valid values are - // - // For this example, assume you want one positional argument of either "fast" or "slow" - // i.e. the only possible ways to run the program are "myprog fast" or "myprog slow" - let matches = App::new("myapp").about("does awesome things") - .arg(Arg::with_name("MODE") - .help("What mode to run the program in") - .index(1) - .possible_values(&["fast", "slow"]) - .required(true)) - .get_matches(); - - // Note, it's safe to call unwrap() because the arg is required - match matches.value_of("MODE").unwrap() { - "fast" => { - // Do fast things... - }, - "slow" => { - // Do slow things... - }, - _ => unreachable!() - } -} diff --git a/clap/examples/12_typed_values.rs b/clap/examples/12_typed_values.rs deleted file mode 100644 index 3d03e4f..0000000 --- a/clap/examples/12_typed_values.rs +++ /dev/null @@ -1,50 +0,0 @@ -#[macro_use] -extern crate clap; - -use clap::App; - -fn main() { - // You can use some convenience macros provided by clap to get typed values, so long as the - // type you specify implements std::str::FromStr - // - // This works for both single, and multiple values (multiple values returns a Vec<T>) - // - // There are also two ways in which to get types, those where failures cause the program to exit - // with an error and usage string, and those which return a Result<T,String> or Result<Vec<T>,String> - // respectively. Both methods support single and multiple values. - // - // The macro which returns a Result allows you decide what to do upon a failure, exit, provide a - // default value, etc. You have control. But it also means you have to write the code or boiler plate - // to handle those instances. - // - // That is why the second method exists, so you can simply get a T or Vec<T> back, or be sure the - // program will exit gracefully. The catch is, the second method should *only* be used on required - // arguments, because if the argument isn't found, it exits. Just FYI ;) - // - // The following example shows both methods. - // - // **NOTE:** to use the macros, you must include #[macro_use] just above the 'extern crate clap;' - // declaration in your crate root. - let matches = App::new("myapp") - // Create two arguments, a required positional which accepts multiple values - // and an optional '-l value' - .args_from_usage( - "<seq>... 'A sequence of whole positive numbers, i.e. 20 25 30' - -l [len] 'A length to use, defaults to 10 when omitted'") - .get_matches(); - - // Here we get a value of type u32 from our optional -l argument. - // If the value provided to len fails to parse, we default to 10 - // - // Using other methods such as unwrap_or_else(|e| println!("{}",e)) - // are possible too. - let len = value_t!(matches, "len", u32).unwrap_or(10); - - println!("len ({}) + 2 = {}", len, len + 2); - - // This code loops through all the values provided to "seq" and adds 2 - // If seq fails to parse, the program exits, you don't have an option - for v in values_t!(matches, "seq", u32).unwrap_or_else(|e| e.exit()) { - println!("Sequence part {} + 2: {}", v, v + 2); - } -} diff --git a/clap/examples/13a_enum_values_automatic.rs b/clap/examples/13a_enum_values_automatic.rs deleted file mode 100644 index 1abe5cb..0000000 --- a/clap/examples/13a_enum_values_automatic.rs +++ /dev/null @@ -1,68 +0,0 @@ -// You can use clap's value_t! macro with a custom enum by implementing the std::str::FromStr -// trait which is very straight forward. There are three ways to do this, for simple enums -// meaning those that don't require 'pub' or any '#[derive()]' directives you can use clap's -// simple_enum! macro. For those that require 'pub' or any '#[derive()]'s you can use clap's -// arg_enum! macro. The third way is to implement std::str::FromStr manually. -// -// In most circumstances using either simple_enum! or arg_enum! is fine. -// -// In the following example we will create two enums using macros, assign a positional argument -// that accepts only one of those values, and use clap to parse the argument. - -// Add clap like normal -#[macro_use] -extern crate clap; - -use clap::{App, Arg}; - -// Using arg_enum! is more like traditional enum declarations -// -// **NOTE:** Only bare variants are supported -arg_enum!{ - #[derive(Debug)] - pub enum Oof { - Rab, - Zab, - Xuq - } -} - -arg_enum!{ - #[derive(Debug)] - enum Foo { - Bar, - Baz, - Qux - } -} - -fn main() { - // Create the application like normal - let enum_vals = ["fast", "slow"]; - let m = App::new("myapp") - // Use a single positional argument that is required - .arg(Arg::from_usage("<foo> 'The Foo to use'") - .possible_values(&Foo::variants())) - .arg(Arg::from_usage("<speed> 'The speed to use'") - // You can define a list of possible values if you want the values to be - // displayed in the help information. Whether you use possible_values() or - // not, the valid values will ALWAYS be displayed on a failed parse. - .possible_values(&enum_vals)) - // For the second positional, lets not use possible_values() just to show the difference - .arg_from_usage("<oof> 'The Oof to use'") - .get_matches(); - - let t = value_t!(m.value_of("foo"), Foo).unwrap_or_else(|e| e.exit()); - let t2 = value_t!(m.value_of("oof"), Oof).unwrap_or_else(|e| e.exit()); - - - // Now we can use our enum like normal. - match t { - Foo::Bar => println!("Found a Bar"), - Foo::Baz => println!("Found a Baz"), - Foo::Qux => println!("Found a Qux") - } - - // Since our Oof derives Debug, we can do this: - println!("Oof: {:?}", t2); -} diff --git a/clap/examples/13b_enum_values_manual.rs b/clap/examples/13b_enum_values_manual.rs deleted file mode 100644 index 81ffe5e..0000000 --- a/clap/examples/13b_enum_values_manual.rs +++ /dev/null @@ -1,54 +0,0 @@ -// In the following example we will create an enum with 4 values, assign a positional argument -// that accepts only one of those values, and use clap to parse the argument. -// -// Start with bringing the trait into scope. -use std::str::FromStr; - -// Add clap like normal -#[macro_use] -extern crate clap; - -use clap::{App, Arg}; - -// Define your enum -enum Vals { - Foo, - Bar, - Baz, - Qux -} - -// Implement the trait -impl FromStr for Vals { - type Err = &'static str; - - fn from_str(s: &str) -> Result<Self, Self::Err> { - match s { - "Foo" => Ok(Vals::Foo), - "Bar" => Ok(Vals::Bar), - "Baz" => Ok(Vals::Baz), - "Qux" => Ok(Vals::Qux), - _ => Err("no match") - } - } -} - -fn main() { - // Create the application like normal - let m = App::new("myapp") - // Use a single positional argument that is required - .arg(Arg::from_usage("<type> 'The type to use'") - // Define the list of possible values - .possible_values(&["Foo", "Bar", "Baz", "Qux"])) - .get_matches(); - - let t = value_t!(m, "type", Vals).unwrap_or_else(|e| e.exit()); - - // Now we can use our enum like normal. - match t { - Vals::Foo => println!("Found a Foo"), - Vals::Bar => println!("Found a Bar"), - Vals::Baz => println!("Found a Baz"), - Vals::Qux => println!("Found a Qux") - } -} diff --git a/clap/examples/14_groups.rs b/clap/examples/14_groups.rs deleted file mode 100644 index e160464..0000000 --- a/clap/examples/14_groups.rs +++ /dev/null @@ -1,87 +0,0 @@ -/// `ArgGroup`s are a family of related arguments and way for you to say, "Any of these arguments". -/// By placing arguments in a logical group, you can make easier requirement and exclusion rules -/// instead of having to list each individually, or when you want a rule to apply "any but not all" -/// arguments. -/// -/// For instance, you can make an entire `ArgGroup` required, this means that one (and *only* one) -/// argument from that group must be present. Using more than one argument from an `ArgGroup` causes -/// a failure (graceful exit). -/// -/// You can also do things such as name an `ArgGroup` as a confliction or requirement, meaning any -/// of the arguments that belong to that group will cause a failure if present, or must present -/// respectively. -/// -/// Perhaps the most common use of `ArgGroup`s is to require one and *only* one argument to be -/// present out of a given set. Imagine that you had multiple arguments, and you want one of them to -/// be required, but making all of them required isn't feasible because perhaps they conflict with -/// each other. For example, lets say that you were building an application where one could set a -/// given version number by supplying a string with an option argument, i.e. `--set-ver v1.2.3`, you -/// also wanted to support automatically using a previous version number and simply incrementing one -/// of the three numbers. So you create three flags `--major`, `--minor`, and `--patch`. All of -/// these arguments shouldn't be used at one time but you want to specify that *at least one* of -/// them is used. For this, you can create a group. - -extern crate clap; - -use clap::{App, Arg, ArgGroup}; - -fn main() { - // Create application like normal - let matches = App::new("myapp") - // Add the version arguments - .args_from_usage("--set-ver [ver] 'set version manually' - --major 'auto inc major' - --minor 'auto inc minor' - --patch 'auto inc patch'") - // Create a group, make it required, and add the above arguments - .group(ArgGroup::with_name("vers") - .required(true) - .args(&["ver", "major", "minor", "patch"])) - // Arguments can also be added to a group individually, these two arguments - // are part of the "input" group which is not required - .arg(Arg::from_usage("[INPUT_FILE] 'some regular input'") - .group("input")) - .arg(Arg::from_usage("--spec-in [SPEC_IN] 'some special input argument'") - .group("input")) - // Now let's assume we have a -c [config] argument which requires one of - // (but **not** both) the "input" arguments - .arg(Arg::with_name("config") - .short("c") - .takes_value(true) - .requires("input")) - .get_matches(); - - // Let's assume the old version 1.2.3 - let mut major = 1; - let mut minor = 2; - let mut patch = 3; - - // See if --set-ver was used to set the version manually - let version = if let Some(ver) = matches.value_of("ver") { - format!("{}", ver) - } else { - // Increment the one requested (in a real program, we'd reset the lower numbers) - let (maj, min, pat) = (matches.is_present("major"), - matches.is_present("minor"), - matches.is_present("patch")); - match (maj, min, pat) { - (true, _, _) => major += 1, - (_, true, _) => minor += 1, - (_, _, true) => patch += 1, - _ => unreachable!(), - }; - format!("{}.{}.{}", major, minor, patch) - }; - - println!("Version: {}", version); - - // Check for usage of -c - if matches.is_present("config") { - let input = matches.value_of("INPUT_FILE").unwrap_or(matches.value_of("SPEC_IN").unwrap()); - println!("Doing work using input {} and config {}", - input, - matches.value_of("config").unwrap()); - } - - -} diff --git a/clap/examples/15_custom_validator.rs b/clap/examples/15_custom_validator.rs deleted file mode 100644 index a5c0d42..0000000 --- a/clap/examples/15_custom_validator.rs +++ /dev/null @@ -1,37 +0,0 @@ -extern crate clap; - -use clap::{App, Arg}; - -fn main() { - // You can define a function (or a closure) to use as a validator to argument values. The - // function must accept a String and return Result<(), String> where Err(String) is the message - // displayed to the user. - - let matches = App::new("myapp") - // Application logic goes here... - .arg(Arg::with_name("input") - .help("the input file to use") - .index(1) - .required(true) - // You can pass in a closure, or a function - .validator(is_png)) - .get_matches(); - - // Here we can call .unwrap() because the argument is required. - println!("The .PNG file is: {}", matches.value_of("input").unwrap()); -} - -fn is_png(val: String) -> Result<(), String> { - // val is the argument value passed in by the user - // val has type of String. - if val.ends_with(".png") { - Ok(()) - } else { - // clap automatically adds "error: " to the beginning - // of the message. - Err(String::from("the file format must be png.")) - } - // Of course, you can do more complicated validation as - // well, but for the simplicity, this example only checks - // if the value passed in ends with ".png" or not. -} diff --git a/clap/examples/16_app_settings.rs b/clap/examples/16_app_settings.rs deleted file mode 100644 index ab1d185..0000000 --- a/clap/examples/16_app_settings.rs +++ /dev/null @@ -1,41 +0,0 @@ -extern crate clap; - -use clap::{App, AppSettings, SubCommand}; - -fn main() { - // You can use AppSettings to change the application level behavior of clap. .setting() function - // of App struct takes AppSettings enum as argument. There is also .settings() function which - // takes slice of AppSettings enum. You can learn more about AppSettings in the documentation, - // which also has examples on each setting. - // - // This example will only show usage of one AppSettings setting. See documentation for more - // information. - - let matches = App::new("myapp") - .setting(AppSettings::SubcommandsNegateReqs) - // Negates requirement of parent command. - - .arg_from_usage("<input> 'input file to use'") - // Required positional argument called input. This - // will be only required if subcommand is not present. - - .subcommand(SubCommand::with_name("test") - .about("does some testing")) - // if program is invoked with subcommand, you do not - // need to specify the <input> argument anymore due to - // the AppSettings::SubcommandsNegateReqs setting. - - .get_matches(); - - // Calling unwrap() on "input" would not be advised here, because although it's required, - // if the user uses a subcommand, those requirements are no longer required. Hence, we should - // use some sort of 'if let' construct - if let Some(inp) = matches.value_of("input") { - println!("The input file is: {}", inp); - } - - match matches.subcommand() { - ("test", _) => println!("The 'test' subcommand was used"), - _ => unreachable!() - } -} diff --git a/clap/examples/17_yaml.rs b/clap/examples/17_yaml.rs deleted file mode 100644 index 3353d73..0000000 --- a/clap/examples/17_yaml.rs +++ /dev/null @@ -1,53 +0,0 @@ -// In order to use YAML to define your CLI you must compile clap with the "yaml" feature because -// it's **not** included by default. -// -// In order to do this, ensure your Cargo.toml looks like one of the following: -// -// [dependencies.clap] -// features = ["yaml"] -// -// __OR__ -// -// [dependencies] -// clap = { features = ["yaml"] } - - -// Using yaml requires calling a clap macro `load_yaml!()` so we must use the '#[macro_use]' -// directive -#[macro_use] -extern crate clap; - -#[cfg(feature = "yaml")] -fn main() { - use clap::App; - - // To load a yaml file containing our CLI definition such as the example '17_yaml.yml' we can - // use the convenience macro which loads the file at compile relative to the current file - // similar to how modules are found. - // - // Then we pass that yaml object to App to build the CLI. - // - // Finally we call get_matches() to start the parsing process. We use the matches just as we - // normally would - let yml = load_yaml!("17_yaml.yml"); - let m = App::from_yaml(yml).get_matches(); - - // Because the example 17_yaml.yml is rather large we'll just look a single arg so you can - // see that it works... - if let Some(mode) = m.value_of("mode") { - match mode { - "vi" => println!("You are using vi"), - "emacs" => println!("You are using emacs..."), - _ => unreachable!() - } - } else { - println!("--mode <MODE> wasn't used..."); - } -} - -#[cfg(not(feature = "yaml"))] -fn main() { - // As stated above, if clap is not compiled with the YAML feature, it is disabled. - println!("YAML feature is disabled."); - println!("Pass --features yaml to cargo when trying this example."); -} diff --git a/clap/examples/17_yaml.yml b/clap/examples/17_yaml.yml deleted file mode 100644 index b0d58b3..0000000 --- a/clap/examples/17_yaml.yml +++ /dev/null @@ -1,97 +0,0 @@ -name: yml_app -version: "1.0" -about: an example using a .yml file to build a CLI -author: Kevin K. <kbknapp@gmail.com> - -# AppSettings can be defined as a list and are **not** ascii case sensitive -settings: - - ArgRequiredElseHelp - -# All Args must be defined in the 'args:' list where the name of the arg, is the -# key to a Hash object -args: - # The name of this argument, is 'opt' which will be used to access the value - # later in your Rust code - - opt: - help: example option argument from yaml - short: o - long: option - multiple: true - takes_value: true - - pos: - help: example positional argument from yaml - index: 1 - # A list of possible values can be defined as a list - possible_values: - - fast - - slow - - flag: - help: demo flag argument - short: F - multiple: true - global: true - # Conflicts, mutual overrides, and requirements can all be defined as a - # list, where the key is the name of the other argument - conflicts_with: - - opt - requires: - - pos - - mode: - long: mode - help: shows an option with specific values - # possible_values can also be defined in this list format - possible_values: [ vi, emacs ] - takes_value: true - - mvals: - long: mult-vals - help: demos an option which has two named values - # value names can be described in a list, where the help will be shown - # --mult-vals <one> <two> - value_names: - - one - - two - - minvals: - long: min-vals - multiple: true - help: you must supply at least two values to satisfy me - min_values: 2 - - maxvals: - long: max-vals - multiple: true - help: you can only supply a max of 3 values for me! - max_values: 3 - -# All subcommands must be listed in the 'subcommand:' object, where the key to -# the list is the name of the subcommand, and all settings for that command are -# are part of a Hash object -subcommands: - # The name of this subcommand will be 'subcmd' which can be accessed in your - # Rust code later - - subcmd: - about: demos subcommands from yaml - version: "0.1" - author: Kevin K. <kbknapp@gmail.com> - # Subcommand args are exactly like App args - args: - - scopt: - short: B - multiple: true - help: example subcommand option - takes_value: true - - scpos1: - help: example subcommand positional - index: 1 - -# ArgGroups are supported as well, and must be sepcified in the 'groups:' -# object of this file -groups: - # the name of the ArgGoup is specified here - - min-max-vals: - # All args and groups that are a part of this group are set here - args: - - minvals - - maxvals - # setting conflicts is done the same manner as setting 'args:' - # - # to make this group required, you could set 'required: true' but for - # this example we won't do that. diff --git a/clap/examples/18_builder_macro.rs b/clap/examples/18_builder_macro.rs deleted file mode 100644 index 6bdce47..0000000 --- a/clap/examples/18_builder_macro.rs +++ /dev/null @@ -1,84 +0,0 @@ -#[macro_use] -extern crate clap; - -// Note, there isn't a need for "use clap::{ ... };" Because the clap_app! macro uses -// $crate:: internally - -fn main() { - - // Validation example testing that a file exists - let file_exists = |path| { - if std::fs::metadata(path).is_ok() { - Ok(()) - } else { - Err(String::from("File doesn't exist")) - } - }; - - // External module may contain this subcommand. If this exists in another module, a function is - // required to access it. Recommend `fn clap() -> Clap::SubCommand`. - let external_sub_command = clap_app!( @subcommand foo => - (@arg bar: -b "Bar") - ); - - let matches = clap_app!(MyApp => - (@setting SubcommandRequiredElseHelp) - (version: "1.0") - (author: "Alice") - (about: "Does awesome things") - (@arg config: -c --config <conf> #{1, 2} {file_exists} "Sets a custom config file") - (@arg proxyHostname: --("proxy-hostname") +takes_value "Sets the hostname of the proxy to use") - (@arg input: * "Input file") - (@group test => - (@attributes +required) - (@arg output: "Sets an optional output file") - (@arg debug: -d ... "Turn debugging information on") - ) - (subcommand: external_sub_command) - (@subcommand test => - (about: "does testing things") - (version: "2.5") - (@arg list: -l "Lists test values") - (@arg test_req: -r requires[list] "Tests requirement for listing") - (@arg aaaa: --aaaa +takes_value { - |a| if a.contains('a') { - Ok(()) - } else { - Err(String::from("string does not contain at least one a")) - } - } "Test if the argument contains an a") - ) - ).get_matches(); - - // You can check the value provided by positional arguments, or option arguments - if let Some(o) = matches.value_of("output") { - println!("Value for output: {}", o); - } - - if let Some(c) = matches.value_of("config") { - println!("Value for config: {}", c); - } - - // You can see how many times a particular flag or argument occurred - // Note, only flags can have multiple occurrences - match matches.occurrences_of("debug") { - 0 => println!("Debug mode is off"), - 1 => println!("Debug mode is kind of on"), - 2 => println!("Debug mode is on"), - 3 | _ => println!("Don't be crazy"), - } - - // You can check for the existence of subcommands, and if found use their - // matches just as you would the top level app - if let Some(matches) = matches.subcommand_matches("test") { - // "$ myapp test" was run - if matches.is_present("list") { - // "$ myapp test -l" was run - println!("Printing testing lists..."); - } else { - println!("Not printing testing lists..."); - } - } - - // Continued program logic goes here... -} diff --git a/clap/examples/19_auto_authors.rs b/clap/examples/19_auto_authors.rs deleted file mode 100644 index afbb985..0000000 --- a/clap/examples/19_auto_authors.rs +++ /dev/null @@ -1,15 +0,0 @@ -#[macro_use] -extern crate clap; - -use clap::App; - -fn main() { - App::new("myapp") - .about("does awesome things") - // use crate_authors! to pull the author(s) names from the Cargo.toml - .author(crate_authors!()) - .get_matches(); - - // running this app with -h will display whatever author(s) are in your - // Cargo.toml -} diff --git a/clap/examples/20_subcommands.rs b/clap/examples/20_subcommands.rs deleted file mode 100644 index f80f46d..0000000 --- a/clap/examples/20_subcommands.rs +++ /dev/null @@ -1,143 +0,0 @@ -// Working with subcommands is simple. There are a few key points to remember when working with -// subcommands in clap. First, SubCommands are really just Apps. This means they can have their own -// settings, version, authors, args, and even their own subcommands. The next thing to remember is -// that subcommands are set up in a tree like hierarchy. -// -// An ASCII art depiction may help explain this better. Using a fictional version of git as the demo -// subject. Imagine the following are all subcommands of git (note, the author is aware these aren't -// actually all subcommands in the real git interface, but it makes explanation easier) -// -// Top Level App (git) TOP -// | -// ----------------------------------------- -// / | \ \ -// clone push add commit LEVEL 1 -// | / \ / \ | -// url origin remote ref name message LEVEL 2 -// / /\ -// path remote local LEVEL 3 -// -// Given the above fictional subcommand hierarchy, valid runtime uses would be (not an all inclusive -// list): -// -// $ git clone url -// $ git push origin path -// $ git add ref local -// $ git commit message -// -// Notice only one command per "level" may be used. You could not, for example, do: -// -// $ git clone url push origin path -// -// It's also important to know that subcommands each have their own set of matches and may have args -// with the same name as other subcommands in a different part of the tree hierarchy (i.e. the arg -// names aren't in a flat namespace). -// -// In order to use subcommands in clap, you only need to know which subcommand you're at in your -// tree, and which args are defined on that subcommand. -// -// Let's make a quick program to illustrate. We'll be using the same example as above but for -// brevity sake we won't implement all of the subcommands, only a few. - -extern crate clap; - -use clap::{App, Arg, SubCommand, AppSettings}; - -fn main() { - - let matches = App::new("git") - .about("A fictional versioning CLI") - .version("1.0") - .author("Me") - .subcommand(SubCommand::with_name("clone") - .about("clones repos") - .arg(Arg::with_name("repo") - .help("The repo to clone") - .required(true))) - .subcommand(SubCommand::with_name("push") - .about("pushes things") - .setting(AppSettings::SubcommandRequiredElseHelp) - .subcommand(SubCommand::with_name("remote") // Subcommands can have their own subcommands, - // which in turn have their own subcommands - .about("pushes remote things") - .arg(Arg::with_name("repo") - .required(true) - .help("The remote repo to push things to"))) - .subcommand(SubCommand::with_name("local") - .about("pushes local things"))) - .subcommand(SubCommand::with_name("add") - .about("adds things") - .author("Someone Else") // Subcommands can list different authors - .version("v2.0 (I'm versioned differently") // or different version from their parents - .setting(AppSettings::ArgRequiredElseHelp) // They can even have different settings - .arg(Arg::with_name("stuff") - .long("stuff") - .help("Stuff to add") - .takes_value(true) - .multiple(true))) - .get_matches(); - - // At this point, the matches we have point to git. Keep this in mind... - - // You can check if one of git's subcommands was used - if matches.is_present("clone") { - println!("'git clone' was run."); - } - - // You can see which subcommand was used - if let Some(subcommand) = matches.subcommand_name() { - println!("'git {}' was used", subcommand); - - // It's important to note, this *only* check's git's DIRECT children, **NOT** it's - // grandchildren, great grandchildren, etc. - // - // i.e. if the command `git push remove --stuff foo` was run, the above will only print out, - // `git push` was used. We'd need to get push's matches to see further into the tree - } - - // An alternative to checking the name is matching on known names. Again notice that only the - // direct children are matched here. - match matches.subcommand_name() { - Some("clone") => println!("'git clone' was used"), - Some("push") => println!("'git push' was used"), - Some("add") => println!("'git add' was used"), - None => println!("No subcommand was used"), - _ => unreachable!(), // Assuming you've listed all direct children above, this is unreachable - } - - // You could get the independent subcommand matches, although this is less common - if let Some(clone_matches) = matches.subcommand_matches("clone") { - // Now we have a reference to clone's matches - println!("Cloning repo: {}", clone_matches.value_of("repo").unwrap()); - } - - // The most common way to handle subcommands is via a combined approach using - // `ArgMatches::subcommand` which returns a tuple of both the name and matches - match matches.subcommand() { - ("clone", Some(clone_matches)) =>{ - // Now we have a reference to clone's matches - println!("Cloning {}", clone_matches.value_of("repo").unwrap()); - }, - ("push", Some(push_matches)) =>{ - // Now we have a reference to push's matches - match push_matches.subcommand() { - ("remote", Some(remote_matches)) =>{ - // Now we have a reference to remote's matches - println!("Pushing to {}", remote_matches.value_of("repo").unwrap()); - }, - ("local", Some(_)) =>{ - println!("'git push local' was used"); - }, - _ => unreachable!(), - } - }, - ("add", Some(add_matches)) =>{ - // Now we have a reference to add's matches - println!("Adding {}", add_matches.values_of("stuff").unwrap().collect::<Vec<_>>().join(", ")); - }, - ("", None) => println!("No subcommand was used"), // If no subcommand was used it'll match the tuple ("", None) - _ => unreachable!(), // If all subcommands are defined above, anything else is unreachable!() - } - - // Continued program logic goes here... -} diff --git a/clap/examples/21_aliases.rs b/clap/examples/21_aliases.rs deleted file mode 100644 index 3be0445..0000000 --- a/clap/examples/21_aliases.rs +++ /dev/null @@ -1,39 +0,0 @@ -extern crate clap; - -use clap::{App, Arg, SubCommand}; - -fn main() { - - let matches = App::new("MyApp") - .subcommand(SubCommand::with_name("ls") - .aliases(&["list", "dir"]) - .about("Adds files to myapp") - .version("0.1") - .author("Kevin K.") - .arg(Arg::with_name("input") - .help("the file to add") - .index(1) - .required(true)) - ) - .get_matches(); - - // You can check if a subcommand was used like normal - if matches.is_present("add") { - println!("'myapp add' was run."); - } - - // You can get the independent subcommand matches (which function exactly like App matches) - if let Some(matches) = matches.subcommand_matches("add") { - // Safe to use unwrap() because of the required() option - println!("Adding file: {}", matches.value_of("input").unwrap()); - } - - // You can also match on a subcommand's name - match matches.subcommand_name() { - Some("add") => println!("'myapp add' was used"), - None => println!("No subcommand was used"), - _ => println!("Some other subcommand was used"), - } - - // Continued program logic goes here... -} diff --git a/clap/examples/22_stop_parsing_with_--.rs b/clap/examples/22_stop_parsing_with_--.rs deleted file mode 100644 index a5ba5b3..0000000 --- a/clap/examples/22_stop_parsing_with_--.rs +++ /dev/null @@ -1,25 +0,0 @@ -extern crate clap; - -use clap::{App, Arg}; - -/// myprog -f -p=bob -- sloppy slop slop -fn main() { - - let matches = App::new("myprog") - .arg(Arg::with_name("eff") - .short("f")) - .arg(Arg::with_name("pea") - .short("p") - .takes_value(true)) - .arg(Arg::with_name("slop") - .multiple(true) - .last(true)) - .get_matches(); - - - println!("-f used: {:?}", matches.is_present("eff")); - println!("-p's value: {:?}", matches.value_of("pea")); - println!("'slops' values: {:?}", matches.values_of("slop").map(|vals| vals.collect::<Vec<_>>())); - - // Continued program logic goes here... -} |