From ab41d7f38219544750e6e1426076dc498073191b Mon Sep 17 00:00:00 2001 From: Kevin K Date: Mon, 31 Aug 2015 23:50:17 -0400 Subject: [PATCH] docs(YAML): adds examples for using YAML to build a CLI --- examples/17_yaml.rs | 45 +++++++++++++++++++++ examples/17_yaml.yml | 96 ++++++++++++++++++++++++++++++++++++++++++++ src/app/app.rs | 11 ++++- tests/app.yml | 3 +- 4 files changed, 153 insertions(+), 2 deletions(-) create mode 100644 examples/17_yaml.rs create mode 100644 examples/17_yaml.yml diff --git a/examples/17_yaml.rs b/examples/17_yaml.rs new file mode 100644 index 00000000000..f75e425637a --- /dev/null +++ b/examples/17_yaml.rs @@ -0,0 +1,45 @@ +// In order to use YAML to define your CLI you must compile clap with the "yaml" feature becasue +// 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; + +use clap::App; + +fn main() { + // 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 + // similiar 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 { + "fast" => println!("We're really going now!"), + "slow" => println!("Awwww, too slow :(") + _ => unreachable!() + } + } else { + println!("--mode wasn't used..."); + } +} \ No newline at end of file diff --git a/examples/17_yaml.yml b/examples/17_yaml.yml new file mode 100644 index 00000000000..cef185bd520 --- /dev/null +++ b/examples/17_yaml.yml @@ -0,0 +1,96 @@ +name: yml_app +version: 1.0 +about: an example using a .yml file to build a CLI +author: Kevin K. + +# 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 ] + - 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 + 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 nae 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. + # 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 'arg_groups:' +# object of this file +arg_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/src/app/app.rs b/src/app/app.rs index 30377fd337f..2899262d529 100644 --- a/src/app/app.rs +++ b/src/app/app.rs @@ -148,7 +148,16 @@ impl<'a, 'v, 'ab, 'u, 'h, 'ar> App<'a, 'v, 'ab, 'u, 'h, 'ar>{ } } - /// Creates a new instace of `App` from a .yml (YAML) file. + /// Creates a new instace of `App` from a .yml (YAML) file. The YAML file must be properly + /// formatted or this function will panic!(). A full example of supported YAML objects can be + /// found in `examples/17_yaml.rs` and `examples/17_yaml.yml`. + /// + /// In order to use this function you must compile with the `features = ["yaml"]` in your + /// settings for `[dependencies.clap]` table of your `Cargo.toml` + /// + /// Note, due to how the YAML objects are built there is a convienience macro for loading the + /// YAML file (relative to the current file, like modules work). That YAML object can then be + /// passed to this function. /// /// # Example /// diff --git a/tests/app.yml b/tests/app.yml index e4c020993fe..4c45be71daa 100644 --- a/tests/app.yml +++ b/tests/app.yml @@ -2,7 +2,8 @@ name: claptests version: 1.0 about: tests clap library author: Kevin K. -settings: ArgRequiredElseHelp +settings: + - ArgRequiredElseHelp args: - opt: short: o