From 71104015953309842043f1f0960484c4a05b0694 Mon Sep 17 00:00:00 2001 From: Hugo Osvaldo Barrera Date: Wed, 5 Jan 2022 17:54:33 +0100 Subject: [PATCH] docs: Fix messed up highlighting This just affects how it's rendered; rather than attempting to highlight these blocks as a shell script, they'll get highlighted as console output. See the rendered versions for a better comparison. --- Cargo.toml | 2 +- examples/cargo-example-derive.md | 8 ++- examples/cargo-example.md | 8 ++- examples/demo.md | 3 +- examples/derive_ref/custom-bool.md | 6 +- examples/escaped-positional-derive.md | 15 +++-- examples/escaped-positional.md | 15 +++-- examples/git-derive.md | 12 +++- examples/git.md | 12 +++- examples/keyvalue-derive.md | 6 +- examples/multicall-busybox.md | 10 ++- examples/multicall-hostname.md | 3 +- examples/pacman.md | 13 ++-- examples/tutorial_builder/README.md | 95 ++++++++++++++++++++++----- examples/tutorial_derive/README.md | 89 ++++++++++++++++++++----- 15 files changed, 230 insertions(+), 67 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index f91b5ba1e7f..59304214134 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -138,7 +138,7 @@ criterion = "0.3.2" trybuild = "1.0.18" rustversion = "1" # Cutting out `filesystem` feature -trycmd = { version = "0.8.3", default-features = false, features = ["color-auto", "diff", "examples"] } +trycmd = { version = "0.9", default-features = false, features = ["color-auto", "diff", "examples"] } [[example]] name = "demo" diff --git a/examples/cargo-example-derive.md b/examples/cargo-example-derive.md index 7f5ac4fa19d..994c6d4d80c 100644 --- a/examples/cargo-example-derive.md +++ b/examples/cargo-example-derive.md @@ -6,7 +6,7 @@ The crate [`clap-cargo`](https://github.com/crate-ci/clap-cargo) can help in mimicking cargo's interface. The help looks like: -```bash +```console $ cargo-example-derive --help cargo @@ -19,6 +19,7 @@ OPTIONS: SUBCOMMANDS: example-derive A simple to use, efficient, and full-featured Command Line Argument Parser help Print this message or the help of the given subcommand(s) + $ cargo-example-derive example-derive --help cargo-example-derive [..] A simple to use, efficient, and full-featured Command Line Argument Parser @@ -30,12 +31,15 @@ OPTIONS: -h, --help Print help information --manifest-path -V, --version Print version information + ``` Then to directly invoke the command, run: -```bash +```console $ cargo-example-derive example-derive None + $ cargo-example-derive example-derive --manifest-path Cargo.toml Some("Cargo.toml") + ``` diff --git a/examples/cargo-example.md b/examples/cargo-example.md index aafd8dd49a8..9279cc49250 100644 --- a/examples/cargo-example.md +++ b/examples/cargo-example.md @@ -6,7 +6,7 @@ The crate [`clap-cargo`](https://github.com/crate-ci/clap-cargo) can help in mimicking cargo's interface. The help looks like: -```bash +```console $ cargo-example --help cargo @@ -19,6 +19,7 @@ OPTIONS: SUBCOMMANDS: example A simple to use, efficient, and full-featured Command Line Argument Parser help Print this message or the help of the given subcommand(s) + $ cargo-example example --help cargo-example [..] A simple to use, efficient, and full-featured Command Line Argument Parser @@ -30,12 +31,15 @@ OPTIONS: -h, --help Print help information --manifest-path -V, --version Print version information + ``` Then to directly invoke the command, run: -```bash +```console $ cargo-example example None + $ cargo-example example --manifest-path Cargo.toml Some("Cargo.toml") + ``` diff --git a/examples/demo.md b/examples/demo.md index 0194eeac7bf..9b0e7e260f1 100644 --- a/examples/demo.md +++ b/examples/demo.md @@ -3,7 +3,7 @@ **This requires enabling the `derive` feature flag.** Used to validate README.md's content -```bash +```console $ demo --help clap [..] A simple to use, efficient, and full-featured Command Line Argument Parser @@ -16,4 +16,5 @@ OPTIONS: -h, --help Print help information -n, --name Name of the person to greet -V, --version Print version information + ``` diff --git a/examples/derive_ref/custom-bool.md b/examples/derive_ref/custom-bool.md index f57a1d3bbdf..2769f20e8f9 100644 --- a/examples/derive_ref/custom-bool.md +++ b/examples/derive_ref/custom-bool.md @@ -2,7 +2,7 @@ Example of overriding the magic `bool` behavior -```bash +```console $ custom-bool --help clap [..] A simple to use, efficient, and full-featured Command Line Argument Parser @@ -18,6 +18,7 @@ OPTIONS: --foo -h, --help Print help information -V, --version Print version information + $ custom-bool ? failed error: The following required arguments were not provided: @@ -28,16 +29,19 @@ USAGE: custom-bool[EXE] [OPTIONS] --foo For more information try --help + $ custom-bool --foo true false [examples/derive_ref/custom-bool.rs:31] opt = Opt { foo: true, bar: false, boom: false, } + $ custom-bool --foo true --bar true false [examples/derive_ref/custom-bool.rs:31] opt = Opt { foo: true, bar: true, boom: false, } + ``` diff --git a/examples/escaped-positional-derive.md b/examples/escaped-positional-derive.md index 3bb63a6b471..3b5f8fe5652 100644 --- a/examples/escaped-positional-derive.md +++ b/examples/escaped-positional-derive.md @@ -5,7 +5,7 @@ You can use `--` to escape further arguments. Let's see what this looks like in the help: -```bash +```console $ escaped-positional-derive --help clap [..] A simple to use, efficient, and full-featured Command Line Argument Parser @@ -21,18 +21,20 @@ OPTIONS: -h, --help Print help information -p -V, --version Print version information + ``` Here is a baseline without any arguments: -```bash +```console $ escaped-positional-derive -f used: false -p's value: None 'slops' values: [] + ``` Notice that we can't pass positional arguments before `--`: -```bash +```console $ escaped-positional-derive foo bar ? failed error: Found argument 'foo' which wasn't expected, or isn't valid in this context @@ -41,20 +43,23 @@ USAGE: escaped-positional-derive[EXE] [OPTIONS] [-- ...] For more information try --help + ``` But you can after: -```bash +```console $ escaped-positional-derive -f -p=bob -- sloppy slop slop -f used: true -p's value: Some("bob") 'slops' values: ["sloppy", "slop", "slop"] + ``` As mentioned, the parser will directly pass everything through: -```bash +```console $ escaped-positional-derive -- -f -p=bob sloppy slop slop -f used: false -p's value: None 'slops' values: ["-f", "-p=bob", "sloppy", "slop", "slop"] + ``` diff --git a/examples/escaped-positional.md b/examples/escaped-positional.md index cdae05499fd..1f71a87369d 100644 --- a/examples/escaped-positional.md +++ b/examples/escaped-positional.md @@ -5,7 +5,7 @@ You can use `--` to escape further arguments. Let's see what this looks like in the help: -```bash +```console $ escaped-positional --help clap [..] A simple to use, efficient, and full-featured Command Line Argument Parser @@ -21,18 +21,20 @@ OPTIONS: -h, --help Print help information -p -V, --version Print version information + ``` Here is a baseline without any arguments: -```bash +```console $ escaped-positional -f used: false -p's value: None 'slops' values: [] + ``` Notice that we can't pass positional arguments before `--`: -```bash +```console $ escaped-positional foo bar ? failed error: Found argument 'foo' which wasn't expected, or isn't valid in this context @@ -41,20 +43,23 @@ USAGE: escaped-positional[EXE] [OPTIONS] [-- ...] For more information try --help + ``` But you can after: -```bash +```console $ escaped-positional -f -p=bob -- sloppy slop slop -f used: true -p's value: Some("bob") 'slops' values: ["sloppy", "slop", "slop"] + ``` As mentioned, the parser will directly pass everything through: -```bash +```console $ escaped-positional -- -f -p=bob sloppy slop slop -f used: false -p's value: None 'slops' values: ["-f", "-p=bob", "sloppy", "slop", "slop"] + ``` diff --git a/examples/git-derive.md b/examples/git-derive.md index bd3f2ed0182..d33ce19bcad 100644 --- a/examples/git-derive.md +++ b/examples/git-derive.md @@ -5,7 +5,7 @@ Git is an example of several common subcommand patterns. Help: -```bash +```console $ git-derive ? failed git @@ -22,6 +22,7 @@ SUBCOMMANDS: clone Clones repos help Print this message or the help of the given subcommand(s) push pushes things + $ git-derive help git A fictional versioning CLI @@ -37,6 +38,7 @@ SUBCOMMANDS: clone Clones repos help Print this message or the help of the given subcommand(s) push pushes things + $ git-derive help add git-derive[EXE]-add adds things @@ -49,10 +51,11 @@ ARGS: OPTIONS: -h, --help Print help information + ``` A basic argument: -```bash +```console $ git-derive add ? failed git-derive[EXE]-add @@ -66,12 +69,15 @@ ARGS: OPTIONS: -h, --help Print help information + $ git-derive add Cargo.toml Cargo.lock Adding ["Cargo.toml", "Cargo.lock"] + ``` External subcommands: -```bash +```console $ git-derive custom-tool arg1 --foo bar Calling out to "custom-tool" with ["arg1", "--foo", "bar"] + ``` diff --git a/examples/git.md b/examples/git.md index ec4bc0a9ef0..64c2f9413e1 100644 --- a/examples/git.md +++ b/examples/git.md @@ -3,7 +3,7 @@ Git is an example of several common subcommand patterns. Help: -```bash +```console $ git ? failed git @@ -20,6 +20,7 @@ SUBCOMMANDS: clone Clones repos help Print this message or the help of the given subcommand(s) push pushes things + $ git help git A fictional versioning CLI @@ -35,6 +36,7 @@ SUBCOMMANDS: clone Clones repos help Print this message or the help of the given subcommand(s) push pushes things + $ git help add git[EXE]-add adds things @@ -47,10 +49,11 @@ ARGS: OPTIONS: -h, --help Print help information + ``` A basic argument: -```bash +```console $ git add ? failed git[EXE]-add @@ -64,12 +67,15 @@ ARGS: OPTIONS: -h, --help Print help information + $ git add Cargo.toml Cargo.lock Adding ["Cargo.toml", "Cargo.lock"] + ``` External subcommands: -```bash +```console $ git custom-tool arg1 --foo bar Calling out to "custom-tool" with ["arg1", "--foo", "bar"] + ``` diff --git a/examples/keyvalue-derive.md b/examples/keyvalue-derive.md index 25ee1a0c917..65748bc3925 100644 --- a/examples/keyvalue-derive.md +++ b/examples/keyvalue-derive.md @@ -2,7 +2,7 @@ **This requires enabling the `derive` feature flag.** -```bash +```console $ keyvalue-derive --help clap @@ -12,16 +12,20 @@ USAGE: OPTIONS: -D -h, --help Print help information + $ keyvalue-derive -D Foo=10 -D Alice=30 Args { defines: [("Foo", 10), ("Alice", 30)] } + $ keyvalue-derive -D Foo ? failed error: Invalid value for '-D ': invalid KEY=value: no `=` found in `Foo` For more information try --help + $ keyvalue-derive -D Foo=Bar ? failed error: Invalid value for '-D ': invalid digit found in string For more information try --help + ``` diff --git a/examples/multicall-busybox.md b/examples/multicall-busybox.md index fbb79291494..040b0088fe9 100644 --- a/examples/multicall-busybox.md +++ b/examples/multicall-busybox.md @@ -6,24 +6,27 @@ See the documentation for clap::AppSettings::Multicall for rationale. This example omits every command except true and false, which are the most trivial to implement, -```bash +```console $ busybox true ? 0 + $ busybox false ? 1 + ``` *Note: without the links setup, we can't demonstrate the multicall behavior* But includes the `--install` option as an example of why it can be useful for the main program to take arguments that aren't applet subcommands. -```bash +```console $ busybox --install ? failed ... + ``` Though users must pass something: -```bash +```console $ busybox ? failed busybox @@ -39,4 +42,5 @@ APPLETS: false does nothing unsuccessfully help Print this message or the help of the given subcommand(s) true does nothing successfully + ``` diff --git a/examples/multicall-hostname.md b/examples/multicall-hostname.md index cc20c532708..a59aa0ab8cd 100644 --- a/examples/multicall-hostname.md +++ b/examples/multicall-hostname.md @@ -6,8 +6,9 @@ See the documentation for clap::AppSettings::Multicall for rationale. This example omits the implementation of displaying address config -```bash +```console $ hostname www + ``` *Note: without the links setup, we can't demonstrate the multicall behavior* diff --git a/examples/pacman.md b/examples/pacman.md index bf60dd3c211..daa26dc8b21 100644 --- a/examples/pacman.md +++ b/examples/pacman.md @@ -3,29 +3,34 @@ [`pacman`](https://wiki.archlinux.org/index.php/pacman) defines subcommands via flags. Here, `-S` is a short flag subcommand: -```bash +```console $ pacman -S package Installing package... + ``` Here `--sync` is a long flag subcommand: -```bash +```console $ pacman --sync package Installing package... + ``` Now the short flag subcommand (`-S`) with a long flag: -```bash +```console $ pacman -S --search name Searching for name... + ``` And the various forms of short flags that work: -``` +```console $ pacman -S -s name Searching for name... + $ pacman -Ss name Searching for name... + ``` *(users can "stack" short subcommands with short flags or with other short flag subcommands)* diff --git a/examples/tutorial_builder/README.md b/examples/tutorial_builder/README.md index e67df66028a..2679806f926 100644 --- a/examples/tutorial_builder/README.md +++ b/examples/tutorial_builder/README.md @@ -23,7 +23,7 @@ You can create an application with several arguments using usage strings. [Example:](01_quick.rs) -```bash +```console $ 01_quick --help clap [..] A simple to use, efficient, and full-featured Command Line Argument Parser @@ -43,19 +43,22 @@ OPTIONS: SUBCOMMANDS: help Print this message or the help of the given subcommand(s) test does testing things + ``` By default, the program does nothing: -```bash +```console $ 01_quick Debug mode is off + ``` But you can mix and match the various features -```bash +```console $ 01_quick -dd test Debug mode is on Not printing testing lists... + ``` ## Configuring the Parser @@ -63,7 +66,7 @@ Not printing testing lists... You use the `App` the start building a parser. [Example:](02_apps.rs) -```bash +```console $ 02_apps --help MyApp 1.0 Kevin K. @@ -77,15 +80,17 @@ OPTIONS: --one --two -V, --version Print version information + $ 02_apps --version MyApp 1.0 + ``` You can use `app_from_crate!()` to fill these fields in from your `Cargo.toml` file. **This requires the `cargo` feature flag.** [Example:](02_crate.rs) -```bash +```console $ 02_crate --help clap [..] A simple to use, efficient, and full-featured Command Line Argument Parser @@ -98,8 +103,10 @@ OPTIONS: --one --two -V, --version Print version information + $ 02_crate --version clap [..] + ``` You can use `AppSettings` to change the application level behavior of clap. You @@ -107,7 +114,7 @@ can apply the setting to the top level command (`app.setting()`) or to it and all subcommands (`app.global_setting()`). [Example:](02_app_settings.rs) -```bash +```console $ 02_app_settings --help clap [..] A simple to use, efficient, and full-featured Command Line Argument Parser @@ -120,9 +127,11 @@ OPTIONS: --one -h, --help Print help information -V, --version Print version information + $ 02_app_settings --one -1 --one -3 --two 10 two: "10" one: "-3" + ``` ## Adding Arguments @@ -132,7 +141,7 @@ one: "-3" Flags are switches that can be on/off: [Example:](03_01_flag_bool.rs) -```bash +```console $ 03_01_flag_bool --help clap [..] A simple to use, efficient, and full-featured Command Line Argument Parser @@ -144,10 +153,13 @@ OPTIONS: -h, --help Print help information -v, --verbose -V, --version Print version information + $ 03_01_flag_bool verbose: false + $ 03_01_flag_bool --verbose verbose: true + $ 03_01_flag_bool --verbose --verbose ? failed error: The argument '--verbose' was provided more than once, but cannot be used multiple times @@ -156,12 +168,13 @@ USAGE: 03_01_flag_bool[EXE] [OPTIONS] For more information try --help + ``` Or counted. [Example:](03_01_flag_count.rs) -```bash +```console $ 03_01_flag_count --help clap [..] A simple to use, efficient, and full-featured Command Line Argument Parser @@ -173,12 +186,16 @@ OPTIONS: -h, --help Print help information -v, --verbose -V, --version Print version information + $ 03_01_flag_count verbose: 0 + $ 03_01_flag_count --verbose verbose: 1 + $ 03_01_flag_count --verbose --verbose verbose: 2 + ``` ### Options @@ -186,7 +203,7 @@ verbose: 2 Flags can also accept a value. [Example:](03_02_option.rs) -```bash +```console $ 03_02_option --help clap [..] A simple to use, efficient, and full-featured Command Line Argument Parser @@ -198,18 +215,25 @@ OPTIONS: -h, --help Print help information -n, --name -V, --version Print version information + $ 03_02_option name: None + $ 03_02_option --name bob name: Some("bob") + $ 03_02_option --name=bob name: Some("bob") + $ 03_02_option -n bob name: Some("bob") + $ 03_02_option -n=bob name: Some("bob") + $ 03_02_option -nbob name: Some("bob") + ``` ### Positionals @@ -217,7 +241,7 @@ name: Some("bob") Or you can have users specify values by their position on the command-line: [Example:](03_03_positional.rs) -```bash +```console $ 03_03_positional --help clap [..] A simple to use, efficient, and full-featured Command Line Argument Parser @@ -231,10 +255,13 @@ ARGS: OPTIONS: -h, --help Print help information -V, --version Print version information + $ 03_03_positional NAME: None + $ 03_03_positional bob NAME: Some("bob") + ``` ### Subcommands @@ -244,7 +271,7 @@ instance of a Subcommand can have its own version, author(s), Args, and even its subcommands. [Example:](03_04_subcommands.rs) -```bash +```console $ 03_04_subcommands ? failed clap [..] @@ -260,6 +287,7 @@ OPTIONS: SUBCOMMANDS: add Adds files to myapp help Print this message or the help of the given subcommand(s) + $ 03_04_subcommands help clap [..] A simple to use, efficient, and full-featured Command Line Argument Parser @@ -274,6 +302,7 @@ OPTIONS: SUBCOMMANDS: add Adds files to myapp help Print this message or the help of the given subcommand(s) + $ 03_04_subcommands help add 03_04_subcommands[EXE]-add [..] Adds files to myapp @@ -287,16 +316,20 @@ ARGS: OPTIONS: -h, --help Print help information -V, --version Print version information + $ 03_04_subcommands add bob 'myapp add' was used, name is: Some("bob") + ``` Because we set `AppSettings::PropagateVersion`: -```bash +```console $ 03_04_subcommands --version clap [..] + $ 03_04_subcommands add --version 03_04_subcommands[EXE]-add [..] + ``` ### Defaults @@ -306,7 +339,7 @@ optional, you work with a `Option` and can `unwrap_or`. Alternatively, you can set `Arg::default_value`. [Example:](03_05_default_values.rs) -```bash +```console $ 03_05_default_values --help clap [..] A simple to use, efficient, and full-featured Command Line Argument Parser @@ -320,10 +353,13 @@ ARGS: OPTIONS: -h, --help Print help information -V, --version Print version information + $ 03_05_default_values NAME: "alice" + $ 03_05_default_values bob NAME: "bob" + ``` ## Validation @@ -338,7 +374,7 @@ those specific values, they will receive a graceful exit with error message info of the mistake, and what the possible valid values are [Example:](04_01_possible.rs) -```bash +```console $ 04_01_possible --help clap [..] A simple to use, efficient, and full-featured Command Line Argument Parser @@ -352,10 +388,13 @@ ARGS: OPTIONS: -h, --help Print help information -V, --version Print version information + $ 04_01_possible fast Hare + $ 04_01_possible slow Tortoise + $ 04_01_possible medium ? failed error: "medium" isn't a valid value for '' @@ -365,12 +404,13 @@ USAGE: 04_01_possible[EXE] For more information try --help + ``` When enabling the `derive` feature, you can use `ArgEnum` to take care of the boiler plate for you, giving the same results. [Example:](04_01_enum.rs) -```bash +```console $ 04_01_enum --help clap [..] A simple to use, efficient, and full-featured Command Line Argument Parser @@ -384,10 +424,13 @@ ARGS: OPTIONS: -h, --help Print help information -V, --version Print version information + $ 04_01_enum fast Hare + $ 04_01_enum slow Tortoise + $ 04_01_enum medium ? failed error: "medium" isn't a valid value for '' @@ -397,6 +440,7 @@ USAGE: 04_01_enum[EXE] For more information try --help + ``` ### Validated values @@ -404,7 +448,7 @@ For more information try --help More generally, you can validate and parse into any data type. [Example:](04_02_validate.rs) -```bash +```console $ 04_02_validate --help clap [..] A simple to use, efficient, and full-featured Command Line Argument Parser @@ -418,13 +462,16 @@ ARGS: OPTIONS: -h, --help Print help information -V, --version Print version information + $ 04_02_validate 22 PORT = 22 + $ 04_02_validate foobar ? failed error: Invalid value for '': invalid digit found in string For more information try --help + ``` ### Argument Relations @@ -440,7 +487,7 @@ be required, but making all of them required isn't feasible because perhaps they each other. [Example:](04_03_relations.rs) -```bash +```console $ 04_03_relations --help clap [..] A simple to use, efficient, and full-featured Command Line Argument Parser @@ -460,6 +507,7 @@ OPTIONS: --set-ver set version manually --spec-in some special input argument -V, --version Print version information + $ 04_03_relations ? failed error: The following required arguments were not provided: @@ -469,8 +517,10 @@ USAGE: 04_03_relations[EXE] [OPTIONS] <--set-ver |--major|--minor|--patch> [INPUT_FILE] For more information try --help + $ 04_03_relations --major Version: 2.2.3 + $ 04_03_relations --major --minor ? failed error: The argument '--major' cannot be used with '--minor' @@ -479,6 +529,7 @@ USAGE: 04_03_relations[EXE] <--set-ver |--major|--minor|--patch> For more information try --help + $ 04_03_relations --major -c config.toml ? failed error: The following required arguments were not provided: @@ -488,9 +539,11 @@ USAGE: 04_03_relations[EXE] -c <--set-ver |--major|--minor|--patch> > For more information try --help + $ 04_03_relations --major -c config.toml --spec-in input.txt Version: 2.2.3 Doing work using input input.txt and config config.toml + ``` ### Custom Validation @@ -498,7 +551,7 @@ Doing work using input input.txt and config config.toml As a last resort, you can create custom errors with the basics of clap's formatting. [Example:](04_04_custom.rs) -```bash +```console $ 04_04_custom --help clap [..] A simple to use, efficient, and full-featured Command Line Argument Parser @@ -518,6 +571,7 @@ OPTIONS: --set-ver set version manually --spec-in some special input argument -V, --version Print version information + $ 04_04_custom ? failed error: Cam only modify one version field @@ -526,8 +580,10 @@ USAGE: 04_04_custom[EXE] [OPTIONS] [INPUT_FILE] For more information try --help + $ 04_04_custom --major Version: 2.2.3 + $ 04_04_custom --major --minor ? failed error: Cam only modify one version field @@ -536,6 +592,7 @@ USAGE: 04_04_custom[EXE] [OPTIONS] [INPUT_FILE] For more information try --help + $ 04_04_custom --major -c config.toml ? failed Version: 2.2.3 @@ -545,9 +602,11 @@ USAGE: 04_04_custom[EXE] [OPTIONS] [INPUT_FILE] For more information try --help + $ 04_04_custom --major -c config.toml --spec-in input.txt Version: 2.2.3 Doing work using input input.txt and config config.toml + ``` ## Tips diff --git a/examples/tutorial_derive/README.md b/examples/tutorial_derive/README.md index 478aa69a7d2..a85a1f44226 100644 --- a/examples/tutorial_derive/README.md +++ b/examples/tutorial_derive/README.md @@ -24,7 +24,7 @@ You can create an application declaratively with a `struct` and some attributes. **This requires enabling the `derive` feature flag.** [Example:](01_quick.rs) -```bash +```console $ 01_quick_derive --help clap [..] A simple to use, efficient, and full-featured Command Line Argument Parser @@ -44,19 +44,22 @@ OPTIONS: SUBCOMMANDS: help Print this message or the help of the given subcommand(s) test does testing things + ``` By default, the program does nothing: -```bash +```console $ 01_quick_derive Debug mode is off + ``` But you can mix and match the various features -```bash +```console $ 01_quick_derive -dd test Debug mode is on Not printing testing lists... + ``` ## Configuring the Parser @@ -64,7 +67,7 @@ Not printing testing lists... You use the `App` the start building a parser. [Example:](02_apps.rs) -```bash +```console $ 02_apps_derive --help MyApp 1.0 Kevin K. @@ -78,14 +81,16 @@ OPTIONS: --one --two -V, --version Print version information + $ 02_apps_derive --version MyApp 1.0 + ``` You can use `app_from_crate!()` to fill these fields in from your `Cargo.toml` file. [Example:](02_crate.rs) -```bash +```console $ 02_crate_derive --help clap [..] A simple to use, efficient, and full-featured Command Line Argument Parser @@ -98,8 +103,10 @@ OPTIONS: --one --two -V, --version Print version information + $ 02_crate_derive --version clap [..] + ``` You can use `AppSettings` to change the application level behavior of clap. You @@ -107,7 +114,7 @@ can apply the setting to the top level command (`app.setting()`) or to it and all subcommands (`app.global_setting()`). [Example:](02_app_settings.rs) -```bash +```console $ 02_app_settings_derive --help clap [..] A simple to use, efficient, and full-featured Command Line Argument Parser @@ -120,9 +127,11 @@ OPTIONS: --one -h, --help Print help information -V, --version Print version information + $ 02_app_settings_derive --one -1 --one -3 --two 10 two: "10" one: "-3" + ``` ## Adding Arguments @@ -132,7 +141,7 @@ one: "-3" Flags are switches that can be on/off: [Example:](03_01_flag_bool.rs) -```bash +```console $ 03_01_flag_bool_derive --help clap [..] A simple to use, efficient, and full-featured Command Line Argument Parser @@ -144,10 +153,13 @@ OPTIONS: -h, --help Print help information -v, --verbose -V, --version Print version information + $ 03_01_flag_bool_derive verbose: false + $ 03_01_flag_bool_derive --verbose verbose: true + $ 03_01_flag_bool_derive --verbose --verbose ? failed error: The argument '--verbose' was provided more than once, but cannot be used multiple times @@ -156,12 +168,13 @@ USAGE: 03_01_flag_bool_derive[EXE] [OPTIONS] For more information try --help + ``` Or counted. [Example:](03_01_flag_count.rs) -```bash +```console $ 03_01_flag_count_derive --help clap [..] A simple to use, efficient, and full-featured Command Line Argument Parser @@ -173,12 +186,16 @@ OPTIONS: -h, --help Print help information -v, --verbose -V, --version Print version information + $ 03_01_flag_count_derive verbose: 0 + $ 03_01_flag_count_derive --verbose verbose: 1 + $ 03_01_flag_count_derive --verbose --verbose verbose: 2 + ``` ### Options @@ -186,7 +203,7 @@ verbose: 2 Flags can also accept a value. [Example:](03_02_option.rs) -```bash +```console $ 03_02_option_derive --help clap [..] A simple to use, efficient, and full-featured Command Line Argument Parser @@ -198,18 +215,25 @@ OPTIONS: -h, --help Print help information -n, --name -V, --version Print version information + $ 03_02_option_derive name: None + $ 03_02_option_derive --name bob name: Some("bob") + $ 03_02_option_derive --name=bob name: Some("bob") + $ 03_02_option_derive -n bob name: Some("bob") + $ 03_02_option_derive -n=bob name: Some("bob") + $ 03_02_option_derive -nbob name: Some("bob") + ``` ### Positionals @@ -217,7 +241,7 @@ name: Some("bob") Or you can have users specify values by their position on the command-line: [Example:](03_03_positional.rs) -```bash +```console $ 03_03_positional_derive --help clap [..] A simple to use, efficient, and full-featured Command Line Argument Parser @@ -231,10 +255,13 @@ ARGS: OPTIONS: -h, --help Print help information -V, --version Print version information + $ 03_03_positional_derive name: None + $ 03_03_positional_derive bob name: Some("bob") + ``` ### Subcommands @@ -244,7 +271,7 @@ instance of a Subcommand can have its own version, author(s), Args, and even its subcommands. [Example:](03_04_subcommands.rs) -```bash +```console $ 03_04_subcommands_derive ? failed clap [..] @@ -260,6 +287,7 @@ OPTIONS: SUBCOMMANDS: add Adds files to myapp help Print this message or the help of the given subcommand(s) + $ 03_04_subcommands_derive help clap [..] A simple to use, efficient, and full-featured Command Line Argument Parser @@ -274,6 +302,7 @@ OPTIONS: SUBCOMMANDS: add Adds files to myapp help Print this message or the help of the given subcommand(s) + $ 03_04_subcommands_derive help add 03_04_subcommands_derive[EXE]-add [..] Adds files to myapp @@ -287,16 +316,20 @@ ARGS: OPTIONS: -h, --help Print help information -V, --version Print version information + $ 03_04_subcommands_derive add bob 'myapp add' was used, name is: Some("bob") + ``` Because we set `AppSettings::PropagateVersion`: -```bash +```console $ 03_04_subcommands_derive --version clap [..] + $ 03_04_subcommands_derive add --version 03_04_subcommands_derive[EXE]-add [..] + ``` ### Defaults @@ -306,7 +339,7 @@ optional, you work with a `Option` and can `unwrap_or`. Alternatively, you can set `Arg::default_value`. [Example:](03_05_default_values.rs) -```bash +```console $ 03_05_default_values_derive --help clap [..] A simple to use, efficient, and full-featured Command Line Argument Parser @@ -320,10 +353,13 @@ ARGS: OPTIONS: -h, --help Print help information -V, --version Print version information + $ 03_05_default_values_derive name: "alice" + $ 03_05_default_values_derive bob name: "bob" + ``` ## Validation @@ -338,7 +374,7 @@ those specific values, they will receive a graceful exit with error message info of the mistake, and what the possible valid values are [Example:](04_01_enum.rs) -```bash +```console $ 04_01_enum_derive --help clap [..] A simple to use, efficient, and full-featured Command Line Argument Parser @@ -352,10 +388,13 @@ ARGS: OPTIONS: -h, --help Print help information -V, --version Print version information + $ 04_01_enum_derive fast Hare + $ 04_01_enum_derive slow Tortoise + $ 04_01_enum_derive medium ? failed error: "medium" isn't a valid value for '' @@ -365,6 +404,7 @@ USAGE: 04_01_enum_derive[EXE] For more information try --help + ``` ### Validated values @@ -372,7 +412,7 @@ For more information try --help More generally, you can validate and parse into any data type. [Example:](04_02_validate.rs) -```bash +```console $ 04_02_validate_derive --help clap [..] A simple to use, efficient, and full-featured Command Line Argument Parser @@ -386,13 +426,16 @@ ARGS: OPTIONS: -h, --help Print help information -V, --version Print version information + $ 04_02_validate_derive 22 PORT = 22 + $ 04_02_validate_derive foobar ? failed error: Invalid value for '': invalid digit found in string For more information try --help + ``` ### Argument Relations @@ -408,7 +451,7 @@ be required, but making all of them required isn't feasible because perhaps they each other. [Example:](04_03_relations.rs) -```bash +```console $ 04_03_relations_derive --help clap [..] A simple to use, efficient, and full-featured Command Line Argument Parser @@ -428,6 +471,7 @@ OPTIONS: --set-ver set version manually --spec-in some special input argument -V, --version Print version information + $ 04_03_relations_derive ? failed error: The following required arguments were not provided: @@ -437,8 +481,10 @@ USAGE: 04_03_relations_derive[EXE] [OPTIONS] <--set-ver |--major|--minor|--patch> [INPUT_FILE] For more information try --help + $ 04_03_relations_derive --major Version: 2.2.3 + $ 04_03_relations_derive --major --minor ? failed error: The argument '--major' cannot be used with '--minor' @@ -447,6 +493,7 @@ USAGE: 04_03_relations_derive[EXE] <--set-ver |--major|--minor|--patch> For more information try --help + $ 04_03_relations_derive --major -c config.toml ? failed error: The following required arguments were not provided: @@ -456,9 +503,11 @@ USAGE: 04_03_relations_derive[EXE] -c <--set-ver |--major|--minor|--patch> > For more information try --help + $ 04_03_relations_derive --major -c config.toml --spec-in input.txt Version: 2.2.3 Doing work using input input.txt and config config.toml + ``` ### Custom Validation @@ -466,7 +515,7 @@ Doing work using input input.txt and config config.toml As a last resort, you can create custom errors with the basics of clap's formatting. [Example:](04_04_custom.rs) -```bash +```console $ 04_04_custom_derive --help clap [..] A simple to use, efficient, and full-featured Command Line Argument Parser @@ -486,6 +535,7 @@ OPTIONS: --set-ver set version manually --spec-in some special input argument -V, --version Print version information + $ 04_04_custom_derive ? failed error: Cam only modify one version field @@ -494,8 +544,10 @@ USAGE: clap [OPTIONS] [INPUT_FILE] For more information try --help + $ 04_04_custom_derive --major Version: 2.2.3 + $ 04_04_custom_derive --major --minor ? failed error: Cam only modify one version field @@ -504,6 +556,7 @@ USAGE: clap [OPTIONS] [INPUT_FILE] For more information try --help + $ 04_04_custom_derive --major -c config.toml ? failed Version: 2.2.3 @@ -513,9 +566,11 @@ USAGE: clap [OPTIONS] [INPUT_FILE] For more information try --help + $ 04_04_custom_derive --major -c config.toml --spec-in input.txt Version: 2.2.3 Doing work using input input.txt and config config.toml + ``` ## Tips