vendor/structopt/README.md

   1 # StructOpt
   2
   3 [![Build status](https://travis-ci.com/TeXitoi/structopt.svg?branch=master)](https://app.travis-ci.com/github/TeXitoi/structopt) [![](https://img.shields.io/crates/v/structopt.svg)](https://crates.io/crates/structopt) [![](https://docs.rs/structopt/badge.svg)](https://docs.rs/structopt)
   4 [![unsafe forbidden](https://img.shields.io/badge/unsafe-forbidden-success.svg)](https://github.com/rust-secure-code/safety-dance/)
   5
   6 Parse command line arguments by defining a struct.  It combines [clap](https://crates.io/crates/clap) with custom derive.
   7
   8 ## Documentation
   9
  10 Find it on [Docs.rs](https://docs.rs/structopt).  You can also check the [examples](https://github.com/TeXitoi/structopt/tree/master/examples) and the [changelog](https://github.com/TeXitoi/structopt/blob/master/CHANGELOG.md).
  11
  12 ## Example
  13
  14 Add `structopt` to your dependencies of your `Cargo.toml`:
  15 ```toml
  16 [dependencies]
  17 structopt = "0.3"
  18 ```
  19
  20 And then, in your rust file:
  21 ```rust
  22 use std::path::PathBuf;
  23 use structopt::StructOpt;
  24
  25 /// A basic example
  26 #[derive(StructOpt, Debug)]
  27 #[structopt(name = "basic")]
  28 struct Opt {
  29     // A flag, true if used in the command line. Note doc comment will
  30     // be used for the help message of the flag. The name of the
  31     // argument will be, by default, based on the name of the field.
  32     /// Activate debug mode
  33     #[structopt(short, long)]
  34     debug: bool,
  35
  36     // The number of occurrences of the `v/verbose` flag
  37     /// Verbose mode (-v, -vv, -vvv, etc.)
  38     #[structopt(short, long, parse(from_occurrences))]
  39     verbose: u8,
  40
  41     /// Set speed
  42     #[structopt(short, long, default_value = "42")]
  43     speed: f64,
  44
  45     /// Output file
  46     #[structopt(short, long, parse(from_os_str))]
  47     output: PathBuf,
  48
  49     // the long option will be translated by default to kebab case,
  50     // i.e. `--nb-cars`.
  51     /// Number of cars
  52     #[structopt(short = "c", long)]
  53     nb_cars: Option<i32>,
  54
  55     /// admin_level to consider
  56     #[structopt(short, long)]
  57     level: Vec<String>,
  58
  59     /// Files to process
  60     #[structopt(name = "FILE", parse(from_os_str))]
  61     files: Vec<PathBuf>,
  62 }
  63
  64 fn main() {
  65     let opt = Opt::from_args();
  66     println!("{:#?}", opt);
  67 }
  68 ```
  69
  70 Using this example:
  71 ```
  72 $ ./basic
  73 error: The following required arguments were not provided:
  74     --output <output>
  75
  76 USAGE:
  77     basic --output <output> --speed <speed>
  78
  79 For more information try --help
  80 $ ./basic --help
  81 basic 0.3.0
  82 Guillaume Pinot <texitoi@texitoi.eu>, others
  83 A basic example
  84
  85 USAGE:
  86     basic [FLAGS] [OPTIONS] --output <output> [--] [file]...
  87
  88 FLAGS:
  89     -d, --debug      Activate debug mode
  90     -h, --help       Prints help information
  91     -V, --version    Prints version information
  92     -v, --verbose    Verbose mode (-v, -vv, -vvv, etc.)
  93
  94 OPTIONS:
  95     -l, --level <level>...     admin_level to consider
  96     -c, --nb-cars <nb-cars>    Number of cars
  97     -o, --output <output>      Output file
  98     -s, --speed <speed>        Set speed [default: 42]
  99
 100 ARGS:
 101     <file>...    Files to process
 102 $ ./basic -o foo.txt
 103 Opt {
 104     debug: false,
 105     verbose: 0,
 106     speed: 42.0,
 107     output: "foo.txt",
 108     nb_cars: None,
 109     level: [],
 110     files: [],
 111 }
 112 $ ./basic -o foo.txt -dvvvs 1337 -l alice -l bob --nb-cars 4 bar.txt baz.txt
 113 Opt {
 114     debug: true,
 115     verbose: 3,
 116     speed: 1337.0,
 117     output: "foo.txt",
 118     nb_cars: Some(
 119         4,
 120     ),
 121     level: [
 122         "alice",
 123         "bob",
 124     ],
 125     files: [
 126         "bar.txt",
 127         "baz.txt",
 128     ],
 129 }
 130 ```
 131
 132 ## StructOpt rustc version policy
 133
 134 - Minimum rustc version modification must be specified in the [changelog](https://github.com/TeXitoi/structopt/blob/master/CHANGELOG.md) and in the [travis configuration](https://github.com/TeXitoi/structopt/blob/master/.travis.yml).
 135 - Contributors can increment minimum rustc version without any justification if the new version is required by the latest version of one of StructOpt's dependencies (`cargo update` will not fail on StructOpt).
 136 - Contributors can increment minimum rustc version if the library user experience is improved.
 137
 138 ## License
 139
 140 Licensed under either of
 141
 142 - Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or <https://www.apache.org/licenses/LICENSE-2.0>)
 143 - MIT license ([LICENSE-MIT](LICENSE-MIT) or <https://opensource.org/licenses/MIT>)
 144
 145 at your option.
 146
 147 ### Contribution
 148
 149 Unless you explicitly state otherwise, any contribution intentionally submitted
 150 for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
 151 dual licensed as above, without any additional terms or conditions.