2016-05-14 20:25:00 +00:00
|
|
|
// Copyright ⓒ 2015-2016 Kevin B. Knapp and [`clap-rs` contributors](https://github.com/kbknapp/clap-rs/blob/master/CONTRIBUTORS.md).
|
2016-01-31 13:03:09 +00:00
|
|
|
// Licensed under the MIT license
|
|
|
|
// (see LICENSE or <http://opensource.org/licenses/MIT>) All files in the project carrying such
|
|
|
|
// notice may not be copied, modified, or distributed except according to those terms.
|
|
|
|
|
2016-11-21 01:48:49 +00:00
|
|
|
//! `clap` is a simple-to-use, efficient, and full-featured library for parsing command line
|
|
|
|
//! arguments and subcommands when writing console/terminal applications.
|
2015-10-01 21:27:29 +00:00
|
|
|
//!
|
|
|
|
//! ## About
|
|
|
|
//!
|
2016-11-21 01:48:49 +00:00
|
|
|
//! `clap` is used to parse *and validate* the string of command line arguments provided by the user
|
|
|
|
//! at runtime. You provide the list of valid possibilities, and `clap` handles the rest. This means
|
|
|
|
//! you focus on your *applications* functionality, and less on the parsing and validating of
|
|
|
|
//! arguments.
|
2016-01-27 22:09:01 +00:00
|
|
|
//!
|
2016-11-21 01:48:49 +00:00
|
|
|
//! `clap` also provides the traditional version and help switches (or flags) 'for free' meaning
|
|
|
|
//! automatically with no configuration. It does this by checking list of valid possibilities you
|
|
|
|
//! supplied and adding only the ones you haven't already defined. If you are using subcommands,
|
|
|
|
//! `clap` will also auto-generate a `help` subcommand for you in addition to the traditional flags.
|
2016-01-27 22:09:01 +00:00
|
|
|
//!
|
2016-11-21 01:48:49 +00:00
|
|
|
//! Once `clap` parses the user provided string of arguments, it returns the matches along with any
|
|
|
|
//! applicable values. If the user made an error or typo, `clap` informs them of the mistake and
|
|
|
|
//! exits gracefully (or returns a `Result` type and allows you to perform any clean up prior to
|
|
|
|
//! exit). Because of this, you can make reasonable assumptions in your code about the validity of
|
|
|
|
//! the arguments.
|
2016-01-27 22:09:01 +00:00
|
|
|
//!
|
|
|
|
//!
|
|
|
|
//! ## Quick Example
|
|
|
|
//!
|
2016-11-21 01:48:49 +00:00
|
|
|
//! The following examples show a quick example of some of the very basic functionality of `clap`.
|
|
|
|
//! For more advanced usage, such as requirements, conflicts, groups, multiple values and
|
|
|
|
//! occurrences see the [documentation](https://docs.rs/clap/), [examples/](examples) directory of
|
|
|
|
//! this repository or the [video tutorials](https://www.youtube.com/playlist?list=PLza5oFLQGTl2Z5T8g1pRkIynR3E0_pc7U).
|
2016-01-27 22:09:01 +00:00
|
|
|
//!
|
2016-11-21 01:48:49 +00:00
|
|
|
//! **NOTE:** All of these examples are functionally the same, but show different styles in which to
|
|
|
|
//! use `clap`
|
2016-01-27 22:09:01 +00:00
|
|
|
//!
|
2016-11-21 01:48:49 +00:00
|
|
|
//! The first example shows a method that allows more advanced configuration options (not shown in
|
|
|
|
//! this small example), or even dynamically generating arguments when desired. The downside is it's
|
|
|
|
//! more verbose.
|
|
|
|
//!
|
2016-11-21 02:27:17 +00:00
|
|
|
//! ```no_run
|
2016-01-27 22:09:01 +00:00
|
|
|
//! // (Full example with detailed comments in examples/01b_quick_example.rs)
|
2015-10-01 21:27:29 +00:00
|
|
|
//! //
|
2016-01-27 22:09:01 +00:00
|
|
|
//! // This example demonstrates clap's full 'builder pattern' style of creating arguments which is
|
|
|
|
//! // more verbose, but allows easier editing, and at times more advanced options, or the possibility
|
|
|
|
//! // to generate arguments dynamically.
|
2015-10-01 21:27:29 +00:00
|
|
|
//! extern crate clap;
|
|
|
|
//! use clap::{Arg, App, SubCommand};
|
2016-11-21 01:48:49 +00:00
|
|
|
//!
|
2015-10-01 21:27:29 +00:00
|
|
|
//! fn main() {
|
2016-01-27 22:09:01 +00:00
|
|
|
//! let matches = App::new("My Super Program")
|
|
|
|
//! .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("INPUT")
|
|
|
|
//! .help("Sets the input file to use")
|
|
|
|
//! .required(true)
|
|
|
|
//! .index(1))
|
|
|
|
//! .arg(Arg::with_name("v")
|
|
|
|
//! .short("v")
|
|
|
|
//! .multiple(true)
|
|
|
|
//! .help("Sets the level of verbosity"))
|
|
|
|
//! .subcommand(SubCommand::with_name("test")
|
|
|
|
//! .about("controls testing features")
|
|
|
|
//! .version("1.3")
|
|
|
|
//! .author("Someone E. <someone_else@other.com>")
|
|
|
|
//! .arg(Arg::with_name("debug")
|
|
|
|
//! .short("d")
|
|
|
|
//! .help("print debug information verbosely")))
|
|
|
|
//! .get_matches();
|
2016-11-21 01:48:49 +00:00
|
|
|
//!
|
2016-01-27 22:09:01 +00:00
|
|
|
//! // Gets a value for config if supplied by user, or defaults to "default.conf"
|
|
|
|
//! let config = matches.value_of("config").unwrap_or("default.conf");
|
2015-10-01 21:27:29 +00:00
|
|
|
//! println!("Value for config: {}", config);
|
2016-11-21 01:48:49 +00:00
|
|
|
//!
|
2016-01-27 22:09:01 +00:00
|
|
|
//! // 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());
|
2016-11-21 01:48:49 +00:00
|
|
|
//!
|
2016-01-27 22:09:01 +00:00
|
|
|
//! // Vary the output based on how many times the user used the "verbose" flag
|
|
|
|
//! // (i.e. 'myprog -v -v -v' or 'myprog -vvv' vs 'myprog -v'
|
|
|
|
//! match matches.occurrences_of("v") {
|
|
|
|
//! 0 => println!("No verbose info"),
|
|
|
|
//! 1 => println!("Some verbose info"),
|
|
|
|
//! 2 => println!("Tons of verbose info"),
|
2015-10-01 21:27:29 +00:00
|
|
|
//! 3 | _ => println!("Don't be crazy"),
|
|
|
|
//! }
|
2016-11-21 01:48:49 +00:00
|
|
|
//!
|
2016-01-27 22:09:01 +00:00
|
|
|
//! // You can handle information about subcommands by requesting their matches by name
|
|
|
|
//! // (as below), requesting just the name used, or both at the same time
|
2015-10-01 21:27:29 +00:00
|
|
|
//! if let Some(matches) = matches.subcommand_matches("test") {
|
2016-01-27 22:09:01 +00:00
|
|
|
//! if matches.is_present("debug") {
|
|
|
|
//! println!("Printing debug info...");
|
2015-10-01 21:27:29 +00:00
|
|
|
//! } else {
|
|
|
|
//! println!("Printing normally...");
|
|
|
|
//! }
|
|
|
|
//! }
|
2016-11-21 01:48:49 +00:00
|
|
|
//!
|
2015-10-01 21:27:29 +00:00
|
|
|
//! // more program logic goes here...
|
|
|
|
//! }
|
|
|
|
//! ```
|
2016-11-21 01:48:49 +00:00
|
|
|
//!
|
|
|
|
//! The next example shows a far less verbose method, but sacrifices some of the advanced
|
|
|
|
//! configuration options (not shown in this small example). This method also takes a *very* minor
|
|
|
|
//! runtime penalty.
|
|
|
|
//!
|
2016-11-21 02:27:17 +00:00
|
|
|
//! ```no_run
|
2016-01-27 22:09:01 +00:00
|
|
|
//! // (Full example with detailed comments in examples/01a_quick_example.rs)
|
2015-10-01 21:27:29 +00:00
|
|
|
//! //
|
2016-10-15 02:58:36 +00:00
|
|
|
//! // This example demonstrates clap's "usage strings" method of creating arguments
|
|
|
|
//! // which is less verbose
|
2015-10-01 21:27:29 +00:00
|
|
|
//! extern crate clap;
|
|
|
|
//! use clap::{Arg, App, SubCommand};
|
2016-11-21 01:48:49 +00:00
|
|
|
//!
|
2015-10-01 21:27:29 +00:00
|
|
|
//! fn main() {
|
|
|
|
//! let matches = App::new("myapp")
|
2016-01-27 22:09:01 +00:00
|
|
|
//! .version("1.0")
|
|
|
|
//! .author("Kevin K. <kbknapp@gmail.com>")
|
|
|
|
//! .about("Does awesome things")
|
|
|
|
//! .args_from_usage(
|
|
|
|
//! "-c, --config=[FILE] 'Sets a custom config file'
|
|
|
|
//! <INPUT> 'Sets the input file to use'
|
|
|
|
//! -v... 'Sets the level of verbosity'")
|
|
|
|
//! .subcommand(SubCommand::with_name("test")
|
|
|
|
//! .about("controls testing features")
|
|
|
|
//! .version("1.3")
|
|
|
|
//! .author("Someone E. <someone_else@other.com>")
|
|
|
|
//! .arg_from_usage("-d, --debug 'Print debug information'"))
|
|
|
|
//! .get_matches();
|
2016-11-21 01:48:49 +00:00
|
|
|
//!
|
2016-01-27 22:09:01 +00:00
|
|
|
//! // Same as previous example...
|
2015-10-01 21:27:29 +00:00
|
|
|
//! }
|
|
|
|
//! ```
|
2016-11-21 01:48:49 +00:00
|
|
|
//!
|
|
|
|
//! This third method shows how you can use a YAML file to build your CLI and keep your Rust source
|
|
|
|
//! tidy or support multiple localized translations by having different YAML files for each
|
|
|
|
//! localization.
|
|
|
|
//!
|
|
|
|
//! First, create the `cli.yml` file to hold your CLI options, but it could be called anything we
|
|
|
|
//! like:
|
|
|
|
//!
|
2015-10-02 00:03:31 +00:00
|
|
|
//! ```yaml
|
2015-10-01 21:27:29 +00:00
|
|
|
//! name: myapp
|
2016-11-21 01:48:49 +00:00
|
|
|
//! version: "1.0"
|
2015-10-01 21:27:29 +00:00
|
|
|
//! author: Kevin K. <kbknapp@gmail.com>
|
|
|
|
//! about: Does awesome things
|
|
|
|
//! args:
|
2016-01-27 22:09:01 +00:00
|
|
|
//! - config:
|
2015-10-01 21:27:29 +00:00
|
|
|
//! short: c
|
|
|
|
//! long: config
|
2016-01-27 22:09:01 +00:00
|
|
|
//! value_name: FILE
|
2015-10-01 21:27:29 +00:00
|
|
|
//! help: Sets a custom config file
|
|
|
|
//! takes_value: true
|
|
|
|
//! - INPUT:
|
|
|
|
//! help: Sets the input file to use
|
|
|
|
//! required: true
|
|
|
|
//! index: 1
|
2016-01-27 22:09:01 +00:00
|
|
|
//! - verbose:
|
|
|
|
//! short: v
|
2015-10-01 21:27:29 +00:00
|
|
|
//! multiple: true
|
2016-01-27 22:09:01 +00:00
|
|
|
//! help: Sets the level of verbosity
|
2015-10-01 21:27:29 +00:00
|
|
|
//! subcommands:
|
|
|
|
//! - test:
|
|
|
|
//! about: controls testing features
|
2016-11-21 01:48:49 +00:00
|
|
|
//! version: "1.3"
|
2015-10-01 21:27:29 +00:00
|
|
|
//! author: Someone E. <someone_else@other.com>
|
|
|
|
//! args:
|
2016-01-27 22:09:01 +00:00
|
|
|
//! - debug:
|
|
|
|
//! short: d
|
|
|
|
//! help: print debug information
|
2015-10-01 21:27:29 +00:00
|
|
|
//! ```
|
2016-11-21 01:48:49 +00:00
|
|
|
//!
|
|
|
|
//! Since this feature requires additional dependencies that not everyone may want, it is *not*
|
|
|
|
//! compiled in by default and we need to enable a feature flag in Cargo.toml:
|
2015-10-01 21:27:29 +00:00
|
|
|
//!
|
2016-11-21 01:48:49 +00:00
|
|
|
//! Simply change your `clap = "~2.19.0"` to `clap = {version = "~2.19.0", features = ["yaml"]}`.
|
2016-10-15 21:37:59 +00:00
|
|
|
//!
|
|
|
|
//! At last we create our `main.rs` file just like we would have with the previous two examples:
|
2016-11-21 01:48:49 +00:00
|
|
|
//!
|
2016-11-21 02:27:17 +00:00
|
|
|
//! ```ignore
|
2015-10-01 21:27:29 +00:00
|
|
|
//! // (Full example with detailed comments in examples/17_yaml.rs)
|
|
|
|
//! //
|
2016-01-27 22:09:01 +00:00
|
|
|
//! // This example demonstrates clap's building from YAML style of creating arguments which is far
|
|
|
|
//! // more clean, but takes a very small performance hit compared to the other two methods.
|
2015-10-01 21:27:29 +00:00
|
|
|
//! #[macro_use]
|
|
|
|
//! extern crate clap;
|
|
|
|
//! use clap::App;
|
2016-11-21 01:48:49 +00:00
|
|
|
//!
|
2015-10-01 21:27:29 +00:00
|
|
|
//! fn main() {
|
2016-01-27 22:09:01 +00:00
|
|
|
//! // The YAML file is found relative to the current file, similar to how modules are found
|
2015-10-01 21:27:29 +00:00
|
|
|
//! let yaml = load_yaml!("cli.yml");
|
|
|
|
//! let matches = App::from_yaml(yaml).get_matches();
|
2016-11-21 01:48:49 +00:00
|
|
|
//!
|
2016-01-27 22:09:01 +00:00
|
|
|
//! // Same as previous examples...
|
2015-10-01 21:27:29 +00:00
|
|
|
//! }
|
|
|
|
//! ```
|
2016-11-21 01:48:49 +00:00
|
|
|
//!
|
|
|
|
//! Finally there is a macro version, which is like a hybrid approach offering the speed of the
|
|
|
|
//! builder pattern (the first example), but without all the verbosity.
|
|
|
|
//!
|
2016-11-21 02:27:17 +00:00
|
|
|
//! ```no_run
|
2016-11-21 01:48:49 +00:00
|
|
|
//! #[macro_use]
|
|
|
|
//! extern crate clap;
|
|
|
|
//!
|
|
|
|
//! fn main() {
|
|
|
|
//! 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();
|
|
|
|
//!
|
|
|
|
//! // Same as before...
|
|
|
|
//! }
|
|
|
|
//! ```
|
|
|
|
//!
|
|
|
|
//! If you were to compile any of the above programs and run them with the flag `--help` or `-h` (or
|
|
|
|
//! `help` subcommand, since we defined `test` as a subcommand) the following would be output
|
|
|
|
//!
|
2016-11-21 02:27:17 +00:00
|
|
|
//! ```text
|
2016-01-27 22:09:01 +00:00
|
|
|
//! $ myprog --help
|
|
|
|
//! My Super Program 1.0
|
2015-10-01 21:27:29 +00:00
|
|
|
//! Kevin K. <kbknapp@gmail.com>
|
|
|
|
//! Does awesome things
|
2016-11-21 01:48:49 +00:00
|
|
|
//!
|
2015-10-01 21:27:29 +00:00
|
|
|
//! USAGE:
|
|
|
|
//! MyApp [FLAGS] [OPTIONS] <INPUT> [SUBCOMMAND]
|
2016-11-21 01:48:49 +00:00
|
|
|
//!
|
2015-10-01 21:27:29 +00:00
|
|
|
//! FLAGS:
|
|
|
|
//! -h, --help Prints this message
|
2016-01-27 22:09:01 +00:00
|
|
|
//! -v Sets the level of verbosity
|
2015-10-01 21:27:29 +00:00
|
|
|
//! -V, --version Prints version information
|
2016-11-21 01:48:49 +00:00
|
|
|
//!
|
2015-10-01 21:27:29 +00:00
|
|
|
//! OPTIONS:
|
2016-01-27 22:09:01 +00:00
|
|
|
//! -c, --config <FILE> Sets a custom config file
|
2016-11-21 01:48:49 +00:00
|
|
|
//!
|
2015-10-01 21:27:29 +00:00
|
|
|
//! ARGS:
|
|
|
|
//! INPUT The input file to use
|
2016-11-21 01:48:49 +00:00
|
|
|
//!
|
2015-10-01 21:27:29 +00:00
|
|
|
//! SUBCOMMANDS:
|
|
|
|
//! help Prints this message
|
|
|
|
//! test Controls testing features
|
|
|
|
//! ```
|
2016-11-21 01:48:49 +00:00
|
|
|
//!
|
|
|
|
//! **NOTE:** You could also run `myapp test --help` to see similar output and options for the
|
|
|
|
//! `test` subcommand.
|
|
|
|
//!
|
2015-10-01 21:27:29 +00:00
|
|
|
//! ## Try it!
|
2016-11-21 01:48:49 +00:00
|
|
|
//!
|
2015-10-01 21:27:29 +00:00
|
|
|
//! ### Pre-Built Test
|
2016-11-21 01:48:49 +00:00
|
|
|
//!
|
2015-10-01 21:27:29 +00:00
|
|
|
//! To try out the pre-built example, use the following steps:
|
2016-11-21 01:48:49 +00:00
|
|
|
//!
|
2016-11-12 07:08:54 +00:00
|
|
|
//! * Clone the repository `$ git clone https://github.com/kbknapp/clap-rs && cd clap-rs/tests`
|
2015-10-01 21:27:29 +00:00
|
|
|
//! * Compile the example `$ cargo build --release`
|
|
|
|
//! * Run the help info `$ ./target/release/claptests --help`
|
|
|
|
//! * Play with the arguments!
|
2016-11-21 01:48:49 +00:00
|
|
|
//!
|
2015-10-01 21:27:29 +00:00
|
|
|
//! ### BYOB (Build Your Own Binary)
|
2016-11-21 01:48:49 +00:00
|
|
|
//!
|
|
|
|
//! To test out `clap`'s default auto-generated help/version follow these steps:
|
2017-02-20 22:13:06 +00:00
|
|
|
//!
|
2016-11-21 01:48:49 +00:00
|
|
|
//! * Create a new cargo project `$ cargo new fake --bin && cd fake`
|
|
|
|
//! * Add `clap` to your `Cargo.toml`
|
2016-11-21 02:27:17 +00:00
|
|
|
//!
|
2016-11-21 01:48:49 +00:00
|
|
|
//! ```toml
|
|
|
|
//! [dependencies]
|
|
|
|
//! clap = "2"
|
|
|
|
//! ```
|
|
|
|
//!
|
|
|
|
//! * Add the following to your `src/main.rs`
|
|
|
|
//!
|
2016-11-21 02:27:17 +00:00
|
|
|
//! ```no_run
|
2015-10-01 21:27:29 +00:00
|
|
|
//! extern crate clap;
|
|
|
|
//! use clap::App;
|
2016-11-21 01:48:49 +00:00
|
|
|
//!
|
2015-10-01 21:27:29 +00:00
|
|
|
//! fn main() {
|
2016-01-27 22:09:01 +00:00
|
|
|
//! App::new("fake").version("v1.0-beta").get_matches();
|
2015-10-01 21:27:29 +00:00
|
|
|
//! }
|
|
|
|
//! ```
|
2016-11-21 01:48:49 +00:00
|
|
|
//!
|
|
|
|
//! * Build your program `$ cargo build --release`
|
|
|
|
//! * Run with help or version `$ ./target/release/fake --help` or `$ ./target/release/fake
|
|
|
|
//! --version`
|
|
|
|
//!
|
2015-10-01 21:27:29 +00:00
|
|
|
//! ## Usage
|
2016-11-21 01:48:49 +00:00
|
|
|
//!
|
|
|
|
//! For full usage, add `clap` as a dependency in your `Cargo.toml` (it is **highly** recommended to
|
|
|
|
//! use the `~major.minor.patch` style versions in your `Cargo.toml`, for more information see
|
|
|
|
//! [Compatibility Policy](#compatibility-policy)) to use from crates.io:
|
|
|
|
//!
|
2016-10-15 02:58:36 +00:00
|
|
|
//! ```toml
|
|
|
|
//! [dependencies]
|
2016-11-21 01:48:49 +00:00
|
|
|
//! clap = "~2.19.0"
|
2016-10-15 02:58:36 +00:00
|
|
|
//! ```
|
2016-11-21 01:48:49 +00:00
|
|
|
//!
|
2016-10-15 02:58:36 +00:00
|
|
|
//! Or get the latest changes from the master branch at github:
|
2016-11-21 01:48:49 +00:00
|
|
|
//!
|
2015-10-02 00:03:31 +00:00
|
|
|
//! ```toml
|
2015-10-01 21:27:29 +00:00
|
|
|
//! [dependencies.clap]
|
|
|
|
//! git = "https://github.com/kbknapp/clap-rs.git"
|
|
|
|
//! ```
|
2016-11-21 01:48:49 +00:00
|
|
|
//!
|
2015-10-01 21:27:29 +00:00
|
|
|
//! Add `extern crate clap;` to your crate root.
|
2016-11-21 01:48:49 +00:00
|
|
|
//!
|
|
|
|
//! Define a list of valid arguments for your program (see the
|
|
|
|
//! [documentation](https://docs.rs/clap/) or [examples/](examples) directory of this repo)
|
|
|
|
//!
|
2015-10-01 21:27:29 +00:00
|
|
|
//! Then run `cargo build` or `cargo update && cargo build` for your project.
|
2016-11-21 01:48:49 +00:00
|
|
|
//!
|
2015-10-01 21:27:29 +00:00
|
|
|
//! ### Optional Dependencies / Features
|
2016-11-21 01:48:49 +00:00
|
|
|
//!
|
2016-10-15 02:58:36 +00:00
|
|
|
//! #### Features enabled by default
|
2016-11-21 01:48:49 +00:00
|
|
|
//!
|
|
|
|
//! * **"suggestions"**: Turns on the `Did you mean '--myoption'?` feature for when users make typos. (builds dependency `strsim`)
|
2017-02-19 16:12:55 +00:00
|
|
|
//! * **"color"**: Turns on colored error messages. This feature only works on non-Windows OSs. (builds dependency `ansi-term` and `atty`)
|
2017-03-05 18:44:16 +00:00
|
|
|
//! * **"wrap_help"**: Wraps the help at the actual terminal width when available, instead of 120 chracters. (builds dependency `term_size`)
|
2016-11-21 01:48:49 +00:00
|
|
|
//!
|
2016-10-15 02:58:36 +00:00
|
|
|
//! To disable these, add this to your `Cargo.toml`:
|
2016-11-21 01:48:49 +00:00
|
|
|
//!
|
2015-10-02 00:03:31 +00:00
|
|
|
//! ```toml
|
2015-10-01 21:27:29 +00:00
|
|
|
//! [dependencies.clap]
|
2016-11-21 01:48:49 +00:00
|
|
|
//! version = "~2.19.0"
|
2015-10-01 21:27:29 +00:00
|
|
|
//! default-features = false
|
|
|
|
//! ```
|
2016-11-21 01:48:49 +00:00
|
|
|
//!
|
2016-01-27 22:09:01 +00:00
|
|
|
//! You can also selectively enable only the features you'd like to include, by adding:
|
2016-11-21 01:48:49 +00:00
|
|
|
//!
|
2015-10-02 00:03:31 +00:00
|
|
|
//! ```toml
|
2015-10-01 21:27:29 +00:00
|
|
|
//! [dependencies.clap]
|
2016-11-21 01:48:49 +00:00
|
|
|
//! version = "~2.19.0"
|
2015-10-01 21:27:29 +00:00
|
|
|
//! default-features = false
|
2016-11-21 01:48:49 +00:00
|
|
|
//!
|
2015-10-01 21:27:29 +00:00
|
|
|
//! # Cherry-pick the features you'd like to use
|
|
|
|
//! features = [ "suggestions", "color" ]
|
|
|
|
//! ```
|
2016-11-21 01:48:49 +00:00
|
|
|
//!
|
2016-10-15 02:58:36 +00:00
|
|
|
//! #### Opt-in features
|
2016-11-21 01:48:49 +00:00
|
|
|
//!
|
|
|
|
//! * **"yaml"**: Enables building CLIs from YAML documents. (builds dependency `yaml-rust`)
|
|
|
|
//! * **"unstable"**: Enables unstable `clap` features that may change from release to release
|
|
|
|
//!
|
|
|
|
//! ### Dependencies Tree
|
|
|
|
//!
|
|
|
|
//! The following graphic depicts `clap`s dependency graph (generated using
|
|
|
|
//! [cargo-graph](https://github.com/kbknapp/cargo-graph)).
|
|
|
|
//!
|
|
|
|
//! * **Dashed** Line: Optional dependency
|
|
|
|
//! * **Red** Color: **NOT** included by default (must use cargo `features` to enable)
|
|
|
|
//! * **Blue** Color: Dev dependency, only used while developing.
|
|
|
|
//!
|
|
|
|
//! ![clap dependencies](clap_dep_graph.png)
|
|
|
|
//!
|
2015-10-01 21:27:29 +00:00
|
|
|
//! ### More Information
|
2016-11-21 01:48:49 +00:00
|
|
|
//!
|
|
|
|
//! You can find complete documentation on the [docs.rs](https://docs.rs/clap/) for this project.
|
|
|
|
//!
|
2016-01-27 22:09:01 +00:00
|
|
|
//! You can also find usage examples in the [examples/](examples) directory of this repo.
|
2016-11-21 01:48:49 +00:00
|
|
|
//!
|
2015-10-01 21:27:29 +00:00
|
|
|
//! #### Video Tutorials
|
2016-11-21 01:48:49 +00:00
|
|
|
//!
|
|
|
|
//! There's also the video tutorial series [Argument Parsing with Rust v2](https://www.youtube.com/playlist?list=PLza5oFLQGTl2Z5T8g1pRkIynR3E0_pc7U).
|
|
|
|
//!
|
|
|
|
//! These videos slowly trickle out as I finish them and currently a work in progress.
|
|
|
|
//!
|
|
|
|
//! ## How to Contribute
|
|
|
|
//!
|
|
|
|
//! Contributions are always welcome! And there is a multitude of ways in which you can help
|
|
|
|
//! depending on what you like to do, or are good at. Anything from documentation, code cleanup,
|
|
|
|
//! issue completion, new features, you name it, even filing issues is contributing and greatly
|
|
|
|
//! appreciated!
|
|
|
|
//!
|
|
|
|
//! Another really great way to help is if you find an interesting, or helpful way in which to use
|
|
|
|
//! `clap`. You can either add it to the [examples/](examples) directory, or file an issue and tell
|
|
|
|
//! me. I'm all about giving credit where credit is due :)
|
|
|
|
//!
|
|
|
|
//! Please read [CONTRIBUTING.md](.github/CONTRIBUTING.md) before you start contributing.
|
|
|
|
//!
|
|
|
|
//!
|
|
|
|
//! ### Testing Code
|
|
|
|
//!
|
|
|
|
//! To test with all features both enabled and disabled, you can run theese commands:
|
|
|
|
//!
|
2016-11-21 02:27:17 +00:00
|
|
|
//! ```text
|
2016-10-15 02:58:36 +00:00
|
|
|
//! $ cargo test --no-default-features
|
2016-11-21 01:48:49 +00:00
|
|
|
//! $ cargo test --features "yaml unstable"
|
|
|
|
//! ```
|
|
|
|
//!
|
|
|
|
//! Alternatively, if you have [`just`](https://github.com/casey/just) installed you can run the
|
|
|
|
//! prebuilt recipies. *Not* using `just` is prfeclty fine as well, it simply bundles commands
|
|
|
|
//! automatically.
|
|
|
|
//!
|
|
|
|
//! For example, to test the code, as above simply run:
|
|
|
|
//!
|
2016-11-21 02:27:17 +00:00
|
|
|
//! ```text
|
2016-11-21 01:48:49 +00:00
|
|
|
//! $ just run-tests`
|
|
|
|
//! ```
|
|
|
|
//!
|
|
|
|
//! From here on, I will lis the appropriate `cargo` command as well as the `just` command.
|
|
|
|
//!
|
|
|
|
//! Sometimes it's helpful to only run a subset of the tests, which can be done via:
|
|
|
|
//!
|
2016-11-21 02:27:17 +00:00
|
|
|
//! ```text
|
2016-11-21 01:48:49 +00:00
|
|
|
//! $ cargo test --test <test_name>
|
|
|
|
//!
|
|
|
|
//! # Or
|
|
|
|
//!
|
|
|
|
//! $ just run-test <test_name>
|
|
|
|
//! ```
|
|
|
|
//!
|
|
|
|
//! ### Linting Code
|
|
|
|
//!
|
|
|
|
//! During the CI process `clap` runs against many different lints using
|
|
|
|
//! [`clippy`](https://github.com/Manishearth/rust-clippy). In order to check if these lints pass on
|
|
|
|
//! your own computer prior to submitting a PR you'll need a nightly compiler.
|
|
|
|
//!
|
|
|
|
//! In order to check the code for lints run either:
|
|
|
|
//!
|
2016-11-21 02:27:17 +00:00
|
|
|
//! ```text
|
2016-11-21 01:48:49 +00:00
|
|
|
//! $ rustup override add nightly
|
|
|
|
//! $ cargo build --features lints
|
|
|
|
//! $ rustup override remove
|
|
|
|
//!
|
|
|
|
//! # Or
|
|
|
|
//!
|
|
|
|
//! $ just lint
|
|
|
|
//! ```
|
|
|
|
//!
|
|
|
|
//! ### Debugging Code
|
|
|
|
//!
|
|
|
|
//! Another helpful technique is to see the `clap` debug output while developing features. In order
|
|
|
|
//! to see the debug output while running the full test suite or individual tests, run:
|
|
|
|
//!
|
2016-11-21 02:27:17 +00:00
|
|
|
//! ```text
|
2016-11-21 01:48:49 +00:00
|
|
|
//! $ cargo test --features debug
|
|
|
|
//!
|
|
|
|
//! # Or for individual tests
|
|
|
|
//! $ cargo test --test <test_name> --features debug
|
|
|
|
//!
|
|
|
|
//! # The corresponding just command for individual debugging tests is:
|
|
|
|
//! $ just debug <test_name>
|
|
|
|
//! ```
|
|
|
|
//!
|
|
|
|
//! ### Goals
|
|
|
|
//!
|
|
|
|
//! There are a few goals of `clap` that I'd like to maintain throughout contributions. If your
|
|
|
|
//! proposed changes break, or go against any of these goals we'll discuss the changes further
|
|
|
|
//! before merging (but will *not* be ignored, all contributes are welcome!). These are by no means
|
|
|
|
//! hard-and-fast rules, as I'm no expert and break them myself from time to time (even if by
|
|
|
|
//! mistake or ignorance).
|
|
|
|
//!
|
|
|
|
//! * Remain backwards compatible when possible
|
|
|
|
//! - If backwards compatibility *must* be broken, use deprecation warnings if at all possible before
|
|
|
|
//! removing legacy code - This does not apply for security concerns
|
|
|
|
//! * Parse arguments quickly
|
|
|
|
//! - Parsing of arguments shouldn't slow down usage of the main program - This is also true of
|
|
|
|
//! generating help and usage information (although *slightly* less stringent, as the program is about
|
|
|
|
//! to exit)
|
|
|
|
//! * Try to be cognizant of memory usage
|
|
|
|
//! - Once parsing is complete, the memory footprint of `clap` should be low since the main program
|
|
|
|
//! is the star of the show
|
|
|
|
//! * `panic!` on *developer* error, exit gracefully on *end-user* error
|
|
|
|
//!
|
|
|
|
//! ### Compatibility Policy
|
|
|
|
//!
|
|
|
|
//! Because `clap` takes SemVer and compatibility seriously, this is the official policy regarding
|
|
|
|
//! breaking changes and previous versions of Rust.
|
|
|
|
//!
|
|
|
|
//! `clap` will pin the minimum required version of Rust to the CI builds. Bumping the minimum
|
|
|
|
//! version of Rust is considered a minor breaking change, meaning *at a minimum* the minor version
|
|
|
|
//! of `clap` will be bumped.
|
|
|
|
//!
|
|
|
|
//! In order to keep from being suprised of breaking changes, it is **highly** recommended to use
|
|
|
|
//! the `~major.minor.patch` style in your `Cargo.toml`:
|
|
|
|
//!
|
2016-11-21 02:27:17 +00:00
|
|
|
//! ```toml
|
|
|
|
//! [dependencies] clap = "~2.19.0"
|
2015-10-01 21:27:29 +00:00
|
|
|
//! ```
|
|
|
|
//!
|
2016-11-21 01:48:49 +00:00
|
|
|
//! This will cause *only* the patch version to be updated upon a `cargo update` call, and therefore
|
|
|
|
//! cannot break due to new features, or bumped minimum versions of Rust.
|
2016-10-15 02:58:36 +00:00
|
|
|
//!
|
2016-11-21 01:48:49 +00:00
|
|
|
//! #### Minimum Version of Rust
|
2016-10-15 02:58:36 +00:00
|
|
|
//!
|
2016-11-21 01:48:49 +00:00
|
|
|
//! `clap` will officially support current stable Rust, minus two releases, but may work with prior
|
|
|
|
//! releases as well. For example, current stable Rust at the time of this writing is 1.13.0,
|
2017-01-08 02:18:59 +00:00
|
|
|
//! meaning `clap` is guaranteed to compile with 1.11.0 and beyond. At the 1.14.0 release, `clap`
|
|
|
|
//! will be guaranteed to compile with 2.12.0 and beyond, etc.
|
2016-11-21 01:48:49 +00:00
|
|
|
//!
|
|
|
|
//! Upon bumping the minimum version of Rust (assuming it's within the stable-2 range), it *must* be
|
|
|
|
//! clearly annotated in the `CHANGELOG.md`
|
|
|
|
//!
|
2015-10-01 21:27:29 +00:00
|
|
|
//! ## License
|
2016-11-21 01:48:49 +00:00
|
|
|
//!
|
|
|
|
//! `clap` is licensed under the MIT license. Please read the [LICENSE-MIT](LICENSE-MIT) file in
|
|
|
|
//! this repository for more information.
|
2015-10-01 23:48:25 +00:00
|
|
|
|
|
|
|
#![crate_type= "lib"]
|
2016-01-11 08:59:56 +00:00
|
|
|
#![deny(
|
2016-01-23 11:46:16 +00:00
|
|
|
missing_docs,
|
2015-10-28 13:57:47 +00:00
|
|
|
missing_debug_implementations,
|
|
|
|
missing_copy_implementations,
|
2015-11-08 06:50:12 +00:00
|
|
|
trivial_casts,
|
2015-10-28 13:57:47 +00:00
|
|
|
unused_import_braces,
|
2016-10-21 13:52:16 +00:00
|
|
|
unused_allocation)]
|
|
|
|
// Lints we'd like to deny but are currently failing for upstream crates
|
|
|
|
// unused_qualifications (bitflags, clippy)
|
|
|
|
// trivial_numeric_casts (bitflags)
|
2016-10-15 17:08:51 +00:00
|
|
|
#![cfg_attr(not(any(feature = "lints", feature = "nightly")), forbid(unstable_features))]
|
|
|
|
#![cfg_attr(feature = "lints", feature(plugin))]
|
|
|
|
#![cfg_attr(feature = "lints", plugin(clippy))]
|
|
|
|
#![cfg_attr(feature = "lints", deny(warnings))]
|
2015-12-19 10:35:44 +00:00
|
|
|
#![cfg_attr(feature = "lints", allow(cyclomatic_complexity))]
|
2016-05-06 21:59:52 +00:00
|
|
|
#![cfg_attr(feature = "lints", allow(doc_markdown))]
|
2015-08-20 01:44:25 +00:00
|
|
|
|
2015-05-05 16:08:09 +00:00
|
|
|
#[cfg(feature = "suggestions")]
|
2015-05-05 09:47:39 +00:00
|
|
|
extern crate strsim;
|
2015-05-05 21:27:36 +00:00
|
|
|
#[cfg(feature = "color")]
|
|
|
|
extern crate ansi_term;
|
2015-08-31 03:26:17 +00:00
|
|
|
#[cfg(feature = "yaml")]
|
|
|
|
extern crate yaml_rust;
|
2016-03-27 18:11:20 +00:00
|
|
|
extern crate unicode_width;
|
2015-09-30 21:14:48 +00:00
|
|
|
#[macro_use]
|
|
|
|
extern crate bitflags;
|
2015-11-08 02:49:04 +00:00
|
|
|
extern crate vec_map;
|
2016-06-30 03:19:08 +00:00
|
|
|
#[cfg(feature = "wrap_help")]
|
|
|
|
extern crate term_size;
|
2016-08-25 01:50:27 +00:00
|
|
|
extern crate unicode_segmentation;
|
2017-02-19 16:12:55 +00:00
|
|
|
#[cfg(feature = "color")]
|
|
|
|
extern crate atty;
|
2015-02-28 03:19:48 +00:00
|
|
|
|
2015-08-31 03:26:17 +00:00
|
|
|
#[cfg(feature = "yaml")]
|
|
|
|
pub use yaml_rust::YamlLoader;
|
2016-05-13 22:52:29 +00:00
|
|
|
pub use args::{Arg, ArgGroup, ArgMatches, ArgSettings, SubCommand, Values, OsValues};
|
2015-11-09 08:48:49 +00:00
|
|
|
pub use app::{App, AppSettings};
|
2015-05-22 22:17:57 +00:00
|
|
|
pub use fmt::Format;
|
2016-01-26 19:02:10 +00:00
|
|
|
pub use errors::{Error, ErrorKind, Result};
|
2016-10-23 00:36:15 +00:00
|
|
|
pub use completions::Shell;
|
2015-02-25 13:37:25 +00:00
|
|
|
|
2015-04-10 15:40:08 +00:00
|
|
|
#[macro_use]
|
|
|
|
mod macros;
|
2015-02-25 13:37:25 +00:00
|
|
|
mod app;
|
|
|
|
mod args;
|
2016-01-25 20:45:50 +00:00
|
|
|
mod usage_parser;
|
2015-05-22 22:17:57 +00:00
|
|
|
mod fmt;
|
2015-11-09 08:48:49 +00:00
|
|
|
mod suggestions;
|
|
|
|
mod errors;
|
2016-01-11 08:59:56 +00:00
|
|
|
mod osstringext;
|
2016-03-27 18:11:20 +00:00
|
|
|
mod strext;
|
2016-06-29 03:38:22 +00:00
|
|
|
mod completions;
|
2016-01-11 08:59:56 +00:00
|
|
|
|
|
|
|
const INTERNAL_ERROR_MSG: &'static str = "Fatal internal error. Please consider filing a bug \
|
|
|
|
report at https://github.com/kbknapp/clap-rs/issues";
|
2016-11-14 18:18:44 +00:00
|
|
|
const INVALID_UTF8: &'static str = "unexpected invalid UTF-8 code point";
|