diff --git a/examples/04_UsingMatches.rs b/examples/04_UsingMatches.rs index 962468c9..e9471b57 100644 --- a/examples/04_UsingMatches.rs +++ b/examples/04_UsingMatches.rs @@ -4,19 +4,19 @@ 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. + // 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") @@ -37,18 +37,18 @@ fn main() { // We can find out whether or not debugging was turned on if matches.is_present("debug") { - println!("Debugging is turned on"); + println!("Debugging is turned on"); } - + // If we wanted to 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(ref file) = matches.value_of("config") { - println!("Using config file: {}", file); + println!("Using config file: {}", file); } - // Because "input" is required we can safely call unwrap() because had the user NOT + // 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... -} \ No newline at end of file +} diff --git a/examples/05_FlagArgs.rs b/examples/05_FlagArgs.rs index b3b1db9c..1ab10a27 100644 --- a/examples/05_FlagArgs.rs +++ b/examples/05_FlagArgs.rs @@ -4,43 +4,43 @@ 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" + // 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... + // 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. + // 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 specifiy a list using - // requires_all(Vec<&str>) + .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 specifiy 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 mutually_excludes_all(Vec<&str>) + // user uses -a, they CANNOT use 'output'" + // also has a mutually_excludes_all(Vec<&str>) ) - // NOTE: In order to compile this example, comment out requres() and - // mutually_excludes() because we have not defined an "output" or "config" - // argument. + // NOTE: In order to compile this example, comment out requres() and + // mutually_excludes() 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"); + println!("Awesomeness is turned on"); } - + // If we set the mutliple() 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 diff --git a/examples/06_PositionalArgs.rs b/examples/06_PositionalArgs.rs index 155895e0..70b73f4c 100644 --- a/examples/06_PositionalArgs.rs +++ b/examples/06_PositionalArgs.rs @@ -4,53 +4,53 @@ 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. + // 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... + // 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. + // 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 specifiy a list using - // requires_all(Vec<&str>) + .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 specifiy 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 mutually_excludes_all(Vec<&str>) - .required(true) // By default this argument MUST be present - // NOTE: mutual exclusions take precedence over - // required arguments + // user uses -a, they CANNOT use 'output'" + // also has a mutually_excludes_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 + .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 mutually_excludes() - // because we have not defined an "output" argument. + // NOTE: In order to compile this example, comment out mutually_excludes() + // because we have not defined an "output" argument. .get_matches(); - // We can find out whether or not "input" or "config" were used + // We can find out whether or not "input" or "config" were used if matches.is_present("input") { - println!("An input file was specified"); + println!("An input file was specified"); } - + // We can also get the values for those arguments if let Some(ref 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()); + // 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/examples/07_OptionArgs.rs b/examples/07_OptionArgs.rs index 19ff7455..4a545479 100644 --- a/examples/07_OptionArgs.rs +++ b/examples/07_OptionArgs.rs @@ -4,60 +4,60 @@ 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. + // 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... + // Regular App configuration goes here... - // Assume we an application that accepts an input file via the "-i file" - // or the "--input file" (as wel 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. + // Assume we an application that accepts an input file via the "-i file" + // or the "--input file" (as wel 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 specifiy a list using - // requires_all(Vec<&str>) + .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 specifiy 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>) + // 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. + // 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 + // We can find out whether or not "input" was used if matches.is_present("input") { - println!("An input file was specified"); + 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(ref in_file) = matches.value_of("input") { - println!("An input file: {}", in_file); + println!("An input file: {}", in_file); } // If we specified the multiple() setting we can get all the values if let Some(ref in_v) = matches.values_of("input") { - for in_file in in_v.iter() { - println!("An input file: {}", in_file); - } + for in_file in in_v.iter() { + println!("An input file: {}", in_file); + } } // We can see how many times the option was used with the occurrences_of() method diff --git a/examples/08_SubCommands.rs b/examples/08_SubCommands.rs index f9997fd9..c2ea8083 100644 --- a/examples/08_SubCommands.rs +++ b/examples/08_SubCommands.rs @@ -4,54 +4,54 @@ 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 provided to subcommands(). + // 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 provided to subcommands(). let matches = App::new("MyApp") - // Normal App and Arg configuration goes here... + // 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))) + // 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."); + println!("'myapp add' was run."); } - + // You can get the independent subcommand matches (which function exactly like App matches) if let Some(ref matches) = matches.subcommand_matches("add") { - // Safe to use unwrap() because of the required() option - println!("Adding file: {}", matches.value_of("input").unwrap()); + // 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"), + 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/examples/12_TypedValues.rs b/examples/12_TypedValues.rs index 15871326..e42690b4 100644 --- a/examples/12_TypedValues.rs +++ b/examples/12_TypedValues.rs @@ -4,47 +4,47 @@ 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) - // - // 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 or Result,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 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( - "... 'A sequence of whole positive numbers, i.e. 20 25 30' - -l [len] 'A length to use, defaults to 10 when omitted'") - .get_matches(); + // 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) + // + // 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 or Result,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 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( + "... '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 failes 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.value_of("len"), u32).unwrap_or(10); + // Here we get a value of type u32 from our optional -l argument. + // If the value provided to len failes 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.value_of("len"), u32).unwrap_or(10); - println!("len ({}) + 2 = {}", len, len + 2); + 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 value_t_or_exit!(matches.values_of("seq"), u32) { - println!("Sequence part {} + 2: {}", v, v + 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 value_t_or_exit!(matches.values_of("seq"), u32) { + println!("Sequence part {} + 2: {}", v, v + 2); + } } diff --git a/examples/15_CustomValidator.rs b/examples/15_CustomValidator.rs new file mode 100644 index 00000000..7138c6be --- /dev/null +++ b/examples/15_CustomValidator.rs @@ -0,0 +1,36 @@ +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) + + .validator(|val| { + // 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. + })) + .get_matches(); + + // Continued program logic here... +}