Mirrors/clap
2
0
Fork 0
mirror of https://github.com/clap-rs/clap synced 2024-12-13 14:22:34 +00:00
Code Issues Projects Releases Packages Wiki Activity

docs(tutorial): Gradually add concepts for args

Browse source
This commit is contained in:
Ed Page 2022-05-03 15:39:56 -05:00
parent 97a5c27d74
commit 253e579781
2 changed files with 144 additions and 138 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

141
examples/tutorial_builder/README.md
View file

@ -5,9 +5,9 @@
1. [Quick Start](#quick-start) 1. [Quick Start](#quick-start)
2. [Configuring the Parser](#configuring-the-parser) 2. [Configuring the Parser](#configuring-the-parser)
3. [Adding Arguments](#adding-arguments) 3. [Adding Arguments](#adding-arguments)
1. [Flags](#flags) 1. [Positionals](#positionals)
2. [Options](#options) 2. [Options](#options)
3. [Positionals](#positionals) 3. [Flags](#flags)
4. [Subcommands](#subcommands) 4. [Subcommands](#subcommands)
5. [Defaults](#defaults) 5. [Defaults](#defaults)
4. Validation 4. Validation
@ -134,9 +134,78 @@ one: "-3"
## Adding Arguments ## Adding Arguments
### Positionals
You can have users specify values by their position on the command-line:
[Example:](03_03_positional.rs)
```console
$ 03_03_positional --help
clap [..]
A simple to use, efficient, and full-featured Command Line Argument Parser
USAGE:
03_03_positional[EXE] [NAME]
ARGS:
<NAME>
OPTIONS:
-h, --help Print help information
-V, --version Print version information
$ 03_03_positional
NAME: None
$ 03_03_positional bob
NAME: Some("bob")
```
### Options
You can name your arguments with a flag:
- Order doesn't matter
- They can be optional
- Intent is clearer
[Example:](03_02_option.rs)
```console
$ 03_02_option --help
clap [..]
A simple to use, efficient, and full-featured Command Line Argument Parser
USAGE:
03_02_option[EXE] [OPTIONS]
OPTIONS:
-h, --help Print help information
-n, --name <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")
```
### Flags ### Flags
Flags are switches that can be on/off: Flags can also be switches that can be on/off:
[Example:](03_01_flag_bool.rs) [Example:](03_01_flag_bool.rs)
```console ```console
@ -196,72 +265,6 @@ verbose: 2
``` ```
### Options
Flags can also accept a value.
[Example:](03_02_option.rs)
```console
$ 03_02_option --help
clap [..]
A simple to use, efficient, and full-featured Command Line Argument Parser
USAGE:
03_02_option[EXE] [OPTIONS]
OPTIONS:
-h, --help Print help information
-n, --name <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
Or you can have users specify values by their position on the command-line:
[Example:](03_03_positional.rs)
```console
$ 03_03_positional --help
clap [..]
A simple to use, efficient, and full-featured Command Line Argument Parser
USAGE:
03_03_positional[EXE] [NAME]
ARGS:
<NAME>
OPTIONS:
-h, --help Print help information
-V, --version Print version information
$ 03_03_positional
NAME: None
$ 03_03_positional bob
NAME: Some("bob")
```
### Subcommands ### Subcommands
Subcommands are defined as `Command`s that get added via `Command::subcommand`. Each Subcommands are defined as `Command`s that get added via `Command::subcommand`. Each

141
examples/tutorial_derive/README.md
View file

@ -5,9 +5,9 @@
1. [Quick Start](#quick-start) 1. [Quick Start](#quick-start)
2. [Configuring the Parser](#configuring-the-parser) 2. [Configuring the Parser](#configuring-the-parser)
3. [Adding Arguments](#adding-arguments) 3. [Adding Arguments](#adding-arguments)
1. [Flags](#flags) 1. [Positionals](#positionals)
2. [Options](#options) 2. [Options](#options)
3. [Positionals](#positionals) 3. [Flags](#flags)
4. [Subcommands](#subcommands) 4. [Subcommands](#subcommands)
5. [Defaults](#defaults) 5. [Defaults](#defaults)
4. Validation 4. Validation
@ -136,9 +136,78 @@ one: "-3"
## Adding Arguments ## Adding Arguments
### Positionals
You can have users specify values by their position on the command-line:
[Example:](03_03_positional.rs)
```console
$ 03_03_positional_derive --help
clap [..]
A simple to use, efficient, and full-featured Command Line Argument Parser
USAGE:
03_03_positional_derive[EXE] [NAME]
ARGS:
<NAME>
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")
```
### Options
You can name your arguments with a flag:
- Order doesn't matter
- They can be optional
- Intent is clearer
[Example:](03_02_option.rs)
```console
$ 03_02_option_derive --help
clap [..]
A simple to use, efficient, and full-featured Command Line Argument Parser
USAGE:
03_02_option_derive[EXE] [OPTIONS]
OPTIONS:
-h, --help Print help information
-n, --name <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")
```
### Flags ### Flags
Flags are switches that can be on/off: Flags can also be switches that can be on/off:
[Example:](03_01_flag_bool.rs) [Example:](03_01_flag_bool.rs)
```console ```console
@ -198,72 +267,6 @@ verbose: 2
``` ```
### Options
Flags can also accept a value.
[Example:](03_02_option.rs)
```console
$ 03_02_option_derive --help
clap [..]
A simple to use, efficient, and full-featured Command Line Argument Parser
USAGE:
03_02_option_derive[EXE] [OPTIONS]
OPTIONS:
-h, --help Print help information
-n, --name <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
Or you can have users specify values by their position on the command-line:
[Example:](03_03_positional.rs)
```console
$ 03_03_positional_derive --help
clap [..]
A simple to use, efficient, and full-featured Command Line Argument Parser
USAGE:
03_03_positional_derive[EXE] [NAME]
ARGS:
<NAME>
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 ### Subcommands
Subcommands are derived with `#[derive(Subcommand)]` and be added via `#[clap(subcommand)]` attribute. Each Subcommands are derived with `#[derive(Subcommand)]` and be added via `#[clap(subcommand)]` attribute. Each