diff options
Diffstat (limited to 'examples')
-rw-r--r-- | examples/README.md | 2 | ||||
-rw-r--r-- | examples/after_help.rs | 24 | ||||
-rw-r--r-- | examples/at_least_two.rs | 15 | ||||
-rw-r--r-- | examples/basic.rs | 24 | ||||
-rw-r--r-- | examples/deny_missing_docs.rs | 20 | ||||
-rw-r--r-- | examples/doc_comments.rs | 50 | ||||
-rw-r--r-- | examples/enum_in_args.rs | 15 | ||||
-rw-r--r-- | examples/enum_in_args_with_strum.rs | 15 | ||||
-rw-r--r-- | examples/enum_tuple.rs | 16 | ||||
-rw-r--r-- | examples/env.rs | 17 | ||||
-rw-r--r-- | examples/example.rs | 23 | ||||
-rw-r--r-- | examples/flatten.rs | 17 | ||||
-rw-r--r-- | examples/gen_completions.rs | 14 | ||||
-rw-r--r-- | examples/git.rs | 18 | ||||
-rw-r--r-- | examples/group.rs | 20 | ||||
-rw-r--r-- | examples/keyvalue.rs | 15 | ||||
-rw-r--r-- | examples/negative_flag.rs | 13 | ||||
-rw-r--r-- | examples/no_version.rs | 11 | ||||
-rw-r--r-- | examples/rename_all.rs | 19 | ||||
-rw-r--r-- | examples/required_if.rs | 19 | ||||
-rw-r--r-- | examples/subcommand_aliases.rs | 17 |
21 files changed, 382 insertions, 2 deletions
diff --git a/examples/README.md b/examples/README.md index b485393..1475e2a 100644 --- a/examples/README.md +++ b/examples/README.md @@ -31,7 +31,7 @@ How to extract subcommands' args into external structs. ### [Environment variables](env.rs) -How to use environment variable fallback an how it interacts with `default_value`. +How to use environment variable fallback and how it interacts with `default_value`. ### [Advanced](example.rs) diff --git a/examples/after_help.rs b/examples/after_help.rs index db2845f..75816c7 100644 --- a/examples/after_help.rs +++ b/examples/after_help.rs @@ -1,4 +1,28 @@ //! How to append a postscript to the help message generated. +//! +//! Running this example with --help prints this message: +//! ----------------------------------------------------- +//! structopt 0.3.25 +//! I am a program and I do things. +//! +//! Sometimes they even work. +//! +//! USAGE: +//! after_help [FLAGS] +//! +//! FLAGS: +//! -d +//! Release the dragon +//! +//! -h, --help +//! Prints help information +//! +//! -V, --version +//! Prints version information +//! +//! +//! Beware `-d`, dragons be here +//! ----------------------------------------------------- use structopt::StructOpt; diff --git a/examples/at_least_two.rs b/examples/at_least_two.rs index 683db50..a4eb002 100644 --- a/examples/at_least_two.rs +++ b/examples/at_least_two.rs @@ -1,5 +1,20 @@ //! How to require presence of at least N values, //! like `val1 val2 ... valN ... valM`. +//! +//! Running this example with --help prints this message: +//! ----------------------------------------------------- +//! structopt 0.3.25 +//! +//! USAGE: +//! at_least_two <foos>... +//! +//! FLAGS: +//! -h, --help Prints help information +//! -V, --version Prints version information +//! +//! ARGS: +//! <foos>... +//! ----------------------------------------------------- use structopt::StructOpt; diff --git a/examples/basic.rs b/examples/basic.rs index 510e0e0..33e4415 100644 --- a/examples/basic.rs +++ b/examples/basic.rs @@ -1,4 +1,28 @@ //! A somewhat comprehensive example of a typical `StructOpt` usage.use +//! +//! Running this example with --help prints this message: +//! ----------------------------------------------------- +//! basic 0.3.25 +//! A basic example +//! +//! USAGE: +//! basic [FLAGS] [OPTIONS] --output <output> [--] [FILE]... +//! +//! FLAGS: +//! -d, --debug Activate debug mode +//! -h, --help Prints help information +//! -V, --version Prints version information +//! -v, --verbose Verbose mode (-v, -vv, -vvv, etc.) +//! +//! OPTIONS: +//! -l, --level <level>... admin_level to consider +//! -c, --nb-cars <nb-cars> Number of cars +//! -o, --output <output> Output file +//! -s, --speed <speed> Set speed [default: 42] +//! +//! ARGS: +//! <FILE>... Files to process +//! ----------------------------------------------------- use std::path::PathBuf; use structopt::StructOpt; diff --git a/examples/deny_missing_docs.rs b/examples/deny_missing_docs.rs index 82b1e63..05ceca9 100644 --- a/examples/deny_missing_docs.rs +++ b/examples/deny_missing_docs.rs @@ -10,6 +10,26 @@ // https://github.com/rust-lang/rust/issues/24584 is fixed //! A test to check that structopt compiles with deny(missing_docs) +//! +//! Running this example with --help prints this message: +//! ----------------------------------------------------- +//! structopt 0.3.25 +//! Some subcommands +//! +//! USAGE: +//! deny_missing_docs [FLAGS] [SUBCOMMAND] +//! +//! FLAGS: +//! -h, --help Prints help information +//! -V, --version Prints version information +//! -v +//! +//! SUBCOMMANDS: +//! a command A +//! b command B +//! c command C +//! help Prints this message or the help of the given subcommand(s) +//! ----------------------------------------------------- #![deny(missing_docs)] diff --git a/examples/doc_comments.rs b/examples/doc_comments.rs index 810101f..3d22152 100644 --- a/examples/doc_comments.rs +++ b/examples/doc_comments.rs @@ -1,4 +1,54 @@ //! How to use doc comments in place of `help/long_help`. +//! +//! Running this example with --help prints this message: +//! ----------------------------------------------------- +//! basic 0.3.25 +//! A basic example for the usage of doc comments as replacement of the arguments `help`, `long_help`, `about` and +//! `long_about` +//! +//! USAGE: +//! doc_comments [FLAGS] <SUBCOMMAND> +//! +//! FLAGS: +//! -f, --first-flag +//! Just use doc comments to replace `help`, `long_help`, `about` or `long_about` input +//! +//! -h, --help +//! Prints help information +//! +//! -s, --second-flag +//! Split between `help` and `long_help`. +//! +//! In the previous case structopt is going to present the whole comment both as text for the `help` and the +//! `long_help` argument. +//! +//! But if the doc comment is formatted like this example -- with an empty second line splitting the heading and +//! the rest of the comment -- only the first line is used as `help` argument. The `long_help` argument will +//! still contain the whole comment. +//! +//! ## Attention +//! +//! Any formatting next to empty lines that could be used inside a doc comment is currently not preserved. If +//! lists or other well formatted content is required it is necessary to use the related structopt argument with +//! a raw string as shown on the `third_flag` description. +//! -t, --third-flag +//! This is a raw string. +//! +//! It can be used to pass well formatted content (e.g. lists or source +//! code) in the description: +//! +//! - first example list entry +//! - second example list entry +//! +//! -V, --version +//! Prints version information +//! +//! +//! SUBCOMMANDS: +//! first The same rules described previously for flags. Are also true for in regards of sub-commands +//! help Prints this message or the help of the given subcommand(s) +//! second Applicable for both `about` an `help` +//! ----------------------------------------------------- use structopt::StructOpt; diff --git a/examples/enum_in_args.rs b/examples/enum_in_args.rs index 70347da..0722140 100644 --- a/examples/enum_in_args.rs +++ b/examples/enum_in_args.rs @@ -1,4 +1,19 @@ //! How to use `arg_enum!` with `StructOpt`. +//! +//! Running this example with --help prints this message: +//! ----------------------------------------------------- +//! structopt 0.3.25 +//! +//! USAGE: +//! enum_in_args <i> +//! +//! FLAGS: +//! -h, --help Prints help information +//! -V, --version Prints version information +//! +//! ARGS: +//! <i> Important argument [possible values: Foo, Bar, FooBar] +//! ----------------------------------------------------- use clap::arg_enum; use structopt::StructOpt; diff --git a/examples/enum_in_args_with_strum.rs b/examples/enum_in_args_with_strum.rs index a045a48..7893e78 100644 --- a/examples/enum_in_args_with_strum.rs +++ b/examples/enum_in_args_with_strum.rs @@ -1,3 +1,18 @@ +//! Running this example with --help prints this message: +//! ----------------------------------------------------- +//! structopt 0.3.25 +//! +//! USAGE: +//! enum_in_args_with_strum [OPTIONS] +//! +//! FLAGS: +//! -h, --help Prints help information +//! -V, --version Prints version information +//! +//! OPTIONS: +//! --format <format> [default: txt] [possible values: txt, md, html] +//! ----------------------------------------------------- + use structopt::StructOpt; use strum::{EnumString, EnumVariantNames, VariantNames}; diff --git a/examples/enum_tuple.rs b/examples/enum_tuple.rs index 0bad2e6..a88adc2 100644 --- a/examples/enum_tuple.rs +++ b/examples/enum_tuple.rs @@ -1,4 +1,20 @@ //! How to extract subcommands' args into external structs. +//! +//! Running this example with --help prints this message: +//! ----------------------------------------------------- +//! classify 0.3.25 +//! +//! USAGE: +//! enum_tuple <SUBCOMMAND> +//! +//! FLAGS: +//! -h, --help Prints help information +//! -V, --version Prints version information +//! +//! SUBCOMMANDS: +//! foo +//! help Prints this message or the help of the given subcommand(s) +//! ----------------------------------------------------- use structopt::StructOpt; diff --git a/examples/env.rs b/examples/env.rs index 0477089..437f3c6 100644 --- a/examples/env.rs +++ b/examples/env.rs @@ -1,5 +1,22 @@ //! How to use environment variable fallback an how it //! interacts with `default_value`. +//! +//! Running this example with --help prints this message: +//! ----------------------------------------------------- +//! env 0.3.25 +//! Example for allowing to specify options via environment variables +//! +//! USAGE: +//! env [OPTIONS] --api-url <api-url> +//! +//! FLAGS: +//! -h, --help Prints help information +//! -V, --version Prints version information +//! +//! OPTIONS: +//! --api-url <api-url> URL for the API server [env: API_URL=] +//! --retries <retries> Number of retries [env: RETRIES=] [default: 5] +//! ----------------------------------------------------- use structopt::StructOpt; diff --git a/examples/example.rs b/examples/example.rs index 71cc124..4dfd341 100644 --- a/examples/example.rs +++ b/examples/example.rs @@ -1,4 +1,27 @@ //! Somewhat complex example of usage of structopt. +//! +//! Running this example with --help prints this message: +//! ----------------------------------------------------- +//! example 0.3.25 +//! An example of StructOpt usage +//! +//! USAGE: +//! example [FLAGS] [OPTIONS] <input> [--] [output] +//! +//! FLAGS: +//! -d, --debug Activate debug mode +//! -h, --help Prints help information +//! -V, --version Prints version information +//! +//! OPTIONS: +//! --log <log> Log file, stdout if no file, no logging if not present +//! --optv <optv>... +//! -s, --speed <speed> Set speed [default: 42] +//! +//! ARGS: +//! <input> Input file +//! <output> Output file, stdout if not present +//! ----------------------------------------------------- use structopt::StructOpt; diff --git a/examples/flatten.rs b/examples/flatten.rs index d51647f..19208ec 100644 --- a/examples/flatten.rs +++ b/examples/flatten.rs @@ -1,4 +1,21 @@ //! How to use flattening. +//! +//! Running this example with --help prints this message: +//! ----------------------------------------------------- +//! structopt 0.3.25 +//! +//! USAGE: +//! flatten [FLAGS] -g <group> -u <user> +//! +//! FLAGS: +//! -h, --help Prints help information +//! -V, --version Prints version information +//! -v switch verbosity on +//! +//! OPTIONS: +//! -g <group> daemon group +//! -u <user> daemon user +//! ----------------------------------------------------- use structopt::StructOpt; diff --git a/examples/gen_completions.rs b/examples/gen_completions.rs index 6dbd97f..e9e9693 100644 --- a/examples/gen_completions.rs +++ b/examples/gen_completions.rs @@ -6,6 +6,20 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. +//! Running this example with --help prints this message: +//! ----------------------------------------------------- +//! structopt 0.3.25 +//! An example of how to generate bash completions with structopt +//! +//! USAGE: +//! gen_completions [FLAGS] +//! +//! FLAGS: +//! -d, --debug Activate debug mode +//! -h, --help Prints help information +//! -V, --version Prints version information +//! ----------------------------------------------------- + use structopt::clap::Shell; use structopt::StructOpt; diff --git a/examples/git.rs b/examples/git.rs index 494e9d1..6e4137b 100644 --- a/examples/git.rs +++ b/examples/git.rs @@ -2,6 +2,24 @@ //! as well as a demonstration of adding documentation to subcommands. //! Documentation can be added either through doc comments or //! `help`/`about` attributes. +//! +//! Running this example with --help prints this message: +//! ----------------------------------------------------- +//! git 0.3.25 +//! the stupid content tracker +//! +//! USAGE: +//! git <SUBCOMMAND> +//! +//! FLAGS: +//! -h, --help Prints help information +//! -V, --version Prints version information +//! +//! SUBCOMMANDS: +//! add +//! fetch fetch branches from remote repository +//! help Prints this message or the help of the given subcommand(s) +//! ----------------------------------------------------- use structopt::StructOpt; diff --git a/examples/group.rs b/examples/group.rs index d53de6a..16ca366 100644 --- a/examples/group.rs +++ b/examples/group.rs @@ -1,4 +1,24 @@ //! How to use `clap::Arg::group` +//! +//! Running this example with --help prints this message: +//! ----------------------------------------------------- +//! structopt 0.3.25 +//! +//! USAGE: +//! group [OPTIONS] <--method <method>|--get|--head|--post|--put|--delete> +//! +//! FLAGS: +//! --delete HTTP DELETE +//! --get HTTP GET +//! -h, --help Prints help information +//! --head HTTP HEAD +//! --post HTTP POST +//! --put HTTP PUT +//! -V, --version Prints version information +//! +//! OPTIONS: +//! --method <method> Set a custom HTTP verb +//! ----------------------------------------------------- use structopt::{clap::ArgGroup, StructOpt}; diff --git a/examples/keyvalue.rs b/examples/keyvalue.rs index 12ce6fc..92acafa 100644 --- a/examples/keyvalue.rs +++ b/examples/keyvalue.rs @@ -1,4 +1,19 @@ //! How to parse "key=value" pairs with structopt. +//! +//! Running this example with --help prints this message: +//! ----------------------------------------------------- +//! structopt 0.3.25 +//! +//! USAGE: +//! keyvalue [OPTIONS] +//! +//! FLAGS: +//! -h, --help Prints help information +//! -V, --version Prints version information +//! +//! OPTIONS: +//! -D <defines>... +//! ----------------------------------------------------- use std::error::Error; use structopt::StructOpt; diff --git a/examples/negative_flag.rs b/examples/negative_flag.rs index b178bf5..0d9337c 100644 --- a/examples/negative_flag.rs +++ b/examples/negative_flag.rs @@ -1,5 +1,18 @@ //! How to add `no-thing` flag which is `true` by default and //! `false` if passed. +//! +//! Running this example with --help prints this message: +//! ----------------------------------------------------- +//! structopt 0.3.25 +//! +//! USAGE: +//! negative_flag [FLAGS] +//! +//! FLAGS: +//! -h, --help Prints help information +//! -V, --version Prints version information +//! --no-verbose +//! ----------------------------------------------------- use structopt::StructOpt; diff --git a/examples/no_version.rs b/examples/no_version.rs index a542ec1..5fc6274 100644 --- a/examples/no_version.rs +++ b/examples/no_version.rs @@ -1,4 +1,15 @@ //! How to completely remove version. +//! +//! Running this example with --help prints this message: +//! ----------------------------------------------------- +//! no_version +//! +//! USAGE: +//! no_version +//! +//! FLAGS: +//! -h, --help Prints help information +//! ----------------------------------------------------- use structopt::clap::AppSettings; use structopt::StructOpt; diff --git a/examples/rename_all.rs b/examples/rename_all.rs index c7c3538..6958c01 100644 --- a/examples/rename_all.rs +++ b/examples/rename_all.rs @@ -20,7 +20,24 @@ //! //! - **Lower Case**: Keep all letters lowercase and remove word boundaries. //! -//! - **Upper Case**: Keep all letters upperrcase and remove word boundaries. +//! - **Upper Case**: Keep all letters uppercase and remove word boundaries. +//! +//! Running this example with --help prints this message: +//! ----------------------------------------------------- +//! rename_all 0.3.25 +//! +//! USAGE: +//! rename_all <SUBCOMMAND> +//! +//! FLAGS: +//! -h, --help Prints help information +//! -V, --version Prints version information +//! +//! SUBCOMMANDS: +//! FIRST_COMMAND A screaming loud first command. Only use if necessary +//! SecondCommand Not nearly as loud as the first command +//! help Prints this message or the help of the given subcommand(s) +//! ----------------------------------------------------- use structopt::StructOpt; diff --git a/examples/required_if.rs b/examples/required_if.rs index cb6b414..e3497b2 100644 --- a/examples/required_if.rs +++ b/examples/required_if.rs @@ -1,4 +1,23 @@ //! How to use `required_if` with structopt. +//! +//! Running this example with --help prints this message: +//! ----------------------------------------------------- +//! structopt 0.3.25 +//! +//! USAGE: +//! required_if -o <out-type> [FILE] +//! +//! FLAGS: +//! -h, --help Prints help information +//! -V, --version Prints version information +//! +//! OPTIONS: +//! -o <out-type> Where to write the output: to `stdout` or `file` +//! +//! ARGS: +//! <FILE> File name: only required when `out-type` is set to `file` +//! ----------------------------------------------------- + use structopt::StructOpt; #[derive(Debug, StructOpt, PartialEq)] diff --git a/examples/subcommand_aliases.rs b/examples/subcommand_aliases.rs index 30b8cc3..1837ddb 100644 --- a/examples/subcommand_aliases.rs +++ b/examples/subcommand_aliases.rs @@ -1,4 +1,21 @@ //! How to assign some aliases to subcommands +//! +//! Running this example with --help prints this message: +//! ----------------------------------------------------- +//! structopt 0.3.25 +//! +//! USAGE: +//! subcommand_aliases <SUBCOMMAND> +//! +//! FLAGS: +//! -h, --help Prints help information +//! -V, --version Prints version information +//! +//! SUBCOMMANDS: +//! bar +//! foo +//! help Prints this message or the help of the given subcommand(s) +//! ----------------------------------------------------- use structopt::clap::AppSettings; use structopt::StructOpt; |