diff options
Diffstat (limited to 'src/lib.rs')
| -rw-r--r-- | src/lib.rs | 100 |
1 files changed, 61 insertions, 39 deletions
@@ -11,6 +11,14 @@ //! This crate defines the `StructOpt` trait and its custom derive. //! +//! ## Maintenance +//! +//! As clap v3 is now out, and the structopt features are integrated +//! into (almost as-is), structopt is now in maintenance mode: no new +//! feature will be added. +//! +//! Bugs will be fixed, and documentation improvements will be accepted. +//! //! ## Features //! //! If you want to disable all the `clap` features (colors, @@ -60,7 +68,7 @@ //! //! First, let's look at the example: //! -//! ```should_panic +//! ``` //! use std::path::PathBuf; //! use structopt::StructOpt; //! @@ -95,7 +103,10 @@ //! } //! //! fn main() { +//! # /* //! let opt = Opt::from_args(); +//! # */ +//! # let opt = Opt::from_iter(&["binary", "-o", "stdout", "input"]); //! println!("{:?}", opt); //! } //! ``` @@ -134,13 +145,17 @@ //! They are what used to be explicit `#[structopt(raw(...))]` attrs in pre-0.3 `structopt` //! //! Every `structopt attribute` looks like comma-separated sequence of methods: -//! ```rust,ignore +//! ``` +//! # #[derive(structopt::StructOpt)] struct S { +//! # //! #[structopt( //! short, // method with no arguments - always magical //! long = "--long-option", // method with one argument //! required_if("out", "file"), // method with one and more args //! parse(from_os_str = path::to::parser) // some magical methods have their own syntax //! )] +//! # +//! # s: () } mod path { pub(crate) mod to { pub(crate) fn parser(_: &std::ffi::OsStr) {} }} //! ``` //! //! `#[structopt(...)]` attributes can be placed on top of `struct`, `enum`, @@ -172,13 +187,19 @@ //! ## Raw methods //! //! They are the reason why `structopt` is so flexible. **Every and each method from -//! `clap::App/Arg` can be used this way!** +//! `clap::App/Arg` can be used this way!** See the [`clap::App` +//! methods](https://docs.rs/clap/2/clap/struct.App.html) and [`clap::Arg` +//! methods](https://docs.rs/clap/2/clap/struct.Arg.html). //! -//! ```ignore +//! ``` +//! # #[derive(structopt::StructOpt)] struct S { +//! # //! #[structopt( //! global = true, // name = arg form, neat for one-arg methods //! required_if("out", "file") // name(arg1, arg2, ...) form. //! )] +//! # +//! # s: String } //! ``` //! //! The first form can only be used for methods which take only one argument. @@ -322,7 +343,7 @@ //! //! ## Type magic //! -//! One of major things that makes `structopt` so awesome is it's type magic. +//! One of major things that makes `structopt` so awesome is its type magic. //! Do you want optional positional argument? Use `Option<T>`! Or perhaps optional argument //! that optionally takes value (`[--opt=[val]]`)? Use `Option<Option<T>>`! //! @@ -435,7 +456,6 @@ //! /// for its type (in this case 0). //! #[structopt(skip)] //! skipped: u32, -//! //! } //! //! # Opt::from_iter( @@ -452,7 +472,7 @@ //! #[derive(StructOpt)] //! struct Opt { //! #[structopt(default_value = "", long)] -//! prefix: String +//! prefix: String, //! } //! ``` //! @@ -474,7 +494,7 @@ //! struct Opt { //! // just leave the `= "..."` part and structopt will figure it for you //! #[structopt(default_value, long)] -//! prefix: String // `String` implements both `Default` and `ToString` +//! prefix: String, // `String` implements both `Default` and `ToString` //! } //! ``` //! @@ -499,8 +519,8 @@ //! #[derive(StructOpt)] //! #[structopt(about = "I am a program and I work, just pass `-h`")] //! struct Foo { -//! #[structopt(short, help = "Pass `-h` and you'll see me!")] -//! bar: String +//! #[structopt(short, help = "Pass `-h` and you'll see me!")] +//! bar: String, //! } //! ``` //! @@ -513,8 +533,8 @@ //! #[derive(StructOpt)] //! /// I am a program and I work, just pass `-h` //! struct Foo { -//! /// Pass `-h` and you'll see me! -//! bar: String +//! /// Pass `-h` and you'll see me! +//! bar: String, //! } //! ``` //! @@ -555,7 +575,7 @@ //! /// until I'll have destroyed humanity. Enjoy your //! /// pathetic existence, you mere mortals. //! #[structopt(long)] -//! kill_all_humans: bool +//! kill_all_humans: bool, //! } //! ``` //! @@ -632,7 +652,7 @@ //! Also, `structopt` will *still* remove leading and trailing blank lines so //! these formats are equivalent: //! -//! ```ignore +//! ``` //! /** This is a doc comment //! //! Hello! */ @@ -646,6 +666,8 @@ //! /// This is a doc comment //! /// //! /// Hello! +//! # +//! # mod m {} //! ``` //! ______________ //! @@ -665,8 +687,8 @@ //! //! #[derive(StructOpt)] //! struct Foo { -//! #[structopt(short, long, env = "PARAMETER_VALUE")] -//! parameter_value: String +//! #[structopt(short, long, env = "PARAMETER_VALUE")] +//! parameter_value: String, //! } //! ``` //! @@ -688,8 +710,8 @@ //! //! #[derive(StructOpt)] //! struct Foo { -//! #[structopt(long = "secret", env = "SECRET_VALUE", hide_env_values = true)] -//! secret_value: String +//! #[structopt(long = "secret", env = "SECRET_VALUE", hide_env_values = true)] +//! secret_value: String, //! } //! ``` //! @@ -707,8 +729,8 @@ //! //! #[derive(StructOpt)] //! struct Foo { -//! #[structopt(long = "secret", env)] -//! secret_value: String +//! #[structopt(long = "secret", env)] +//! secret_value: String, //! } //! ``` //! @@ -774,21 +796,21 @@ //! #[structopt(short)] //! patch: bool, //! #[structopt(parse(from_os_str))] -//! files: Vec<PathBuf> +//! files: Vec<PathBuf>, //! }, //! Fetch { //! #[structopt(long)] //! dry_run: bool, //! #[structopt(long)] //! all: bool, -//! repository: Option<String> +//! repository: Option<String>, //! }, //! Commit { //! #[structopt(short)] //! message: Option<String>, //! #[structopt(short)] -//! all: bool -//! } +//! all: bool, +//! }, //! } //! ``` //! @@ -807,22 +829,22 @@ //! supervising_faerie: String, //! /// The faerie tree this cookie is being made in. //! tree: Option<String>, -//! #[structopt(subcommand)] // Note that we mark a field as a subcommand -//! cmd: Command +//! #[structopt(subcommand)] // Note that we mark a field as a subcommand +//! cmd: Command, //! } //! //! #[derive(StructOpt)] //! enum Command { //! /// Pound acorns into flour for cookie dough. //! Pound { -//! acorns: u32 +//! acorns: u32, //! }, //! /// Add magical sparkles -- the secret ingredient! //! Sparkle { //! #[structopt(short, parse(from_occurrences))] //! magicality: u64, //! #[structopt(short)] -//! color: String +//! color: String, //! }, //! Finish(Finish), //! } @@ -832,19 +854,19 @@ //! struct Finish { //! #[structopt(short)] //! time: u32, -//! #[structopt(subcommand)] // Note that we mark a field as a subcommand -//! finish_type: FinishType +//! #[structopt(subcommand)] // Note that we mark a field as a subcommand +//! finish_type: FinishType, //! } //! //! // subsubcommand! //! #[derive(StructOpt)] //! enum FinishType { //! Glaze { -//! applications: u32 +//! applications: u32, //! }, //! Powder { //! flavor: String, -//! dips: u32 +//! dips: u32, //! } //! } //! ``` @@ -868,14 +890,14 @@ //! struct Foo { //! file: String, //! #[structopt(subcommand)] -//! cmd: Option<Command> +//! cmd: Option<Command>, //! } //! //! #[derive(StructOpt)] //! enum Command { //! Bar, //! Baz, -//! Quux +//! Quux, //! } //! ``` //! @@ -953,7 +975,7 @@ //! BaseCli(BaseCli), //! Dex { //! arg2: i32, -//! } +//! }, //! } //! ``` //! @@ -1068,10 +1090,10 @@ //! //! // a struct with single custom argument //! #[derive(StructOpt)] -//! struct GenericArgs<T:FromStr> where <T as FromStr>::Err: fmt::Display + fmt::Debug { +//! struct GenericArgs<T: FromStr> where <T as FromStr>::Err: fmt::Display + fmt::Debug { //! generic_arg_1: String, //! generic_arg_2: String, -//! custom_arg_1: T +//! custom_arg_1: T, //! } //! ``` //! @@ -1081,11 +1103,11 @@ //! # use structopt::StructOpt; //! // a struct with multiple custom arguments in a substructure //! #[derive(StructOpt)] -//! struct GenericArgs<T:StructOpt> { +//! struct GenericArgs<T: StructOpt> { //! generic_arg_1: String, //! generic_arg_2: String, //! #[structopt(flatten)] -//! custom_args: T +//! custom_args: T, //! } //! ``` |