mirror of
https://github.com/clap-rs/clap
synced 2024-09-20 06:22:06 +00:00
docs(tutorial): Split into separate modules per section
Unsure how much to read into this but some refer to the tutorial a a big wall of ... and maybe breaking it down will help?
This commit is contained in:
parent
5f6d4a3dad
commit
32586c7b63
15 changed files with 565 additions and 473 deletions
25
src/_derive/_tutorial/chapter_0.rs
Normal file
25
src/_derive/_tutorial/chapter_0.rs
Normal file
|
@ -0,0 +1,25 @@
|
|||
//! ## Quick Start
|
||||
//!
|
||||
//! You can create an application declaratively with a `struct` and some
|
||||
//! attributes.
|
||||
//!
|
||||
//! First, ensure `clap` is available with the [`derive` feature flag][crate::_features]:
|
||||
//! ```console
|
||||
//! $ cargo add clap --features derive
|
||||
//! ```
|
||||
//!
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/01_quick.rs")]
|
||||
//! ```
|
||||
//!
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/01_quick.md")]
|
||||
//!
|
||||
//! See also
|
||||
//! - [FAQ: When should I use the builder vs derive APIs?][crate::_faq#when-should-i-use-the-builder-vs-derive-apis]
|
||||
//! - The [cookbook][crate::_cookbook] for more application-focused examples
|
||||
|
||||
#![allow(unused_imports)]
|
||||
use crate::builder::*;
|
||||
|
||||
pub use super::chapter_1 as next;
|
||||
pub use crate::_tutorial as table_of_contents;
|
29
src/_derive/_tutorial/chapter_1.rs
Normal file
29
src/_derive/_tutorial/chapter_1.rs
Normal file
|
@ -0,0 +1,29 @@
|
|||
//! ## Configuring the Parser
|
||||
//!
|
||||
//! You use derive [`Parser`][crate::Parser] to start building a parser.
|
||||
//!
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/02_apps.rs")]
|
||||
//! ```
|
||||
//!
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/02_apps.md")]
|
||||
//!
|
||||
//! You can use [`#[command(author, version, about)]` attribute defaults][super#command-attributes] on the struct to fill these fields in from your `Cargo.toml` file.
|
||||
//!
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/02_crate.rs")]
|
||||
//! ```
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/02_crate.md")]
|
||||
//!
|
||||
//! You can use `#[command]` attributes on the struct to change the application level behavior of clap. Any [`Command`][crate::Command] builder function can be used as an attribute, like [`Command::next_line_help`].
|
||||
//!
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/02_app_settings.rs")]
|
||||
//! ```
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/02_app_settings.md")]
|
||||
#![allow(unused_imports)]
|
||||
use crate::builder::*;
|
||||
|
||||
pub use super::chapter_0 as previous;
|
||||
pub use super::chapter_2 as next;
|
||||
pub use crate::_tutorial as table_of_contents;
|
103
src/_derive/_tutorial/chapter_2.rs
Normal file
103
src/_derive/_tutorial/chapter_2.rs
Normal file
|
@ -0,0 +1,103 @@
|
|||
//! ## Adding Arguments
|
||||
//!
|
||||
//! 1. [Positionals](#positionals)
|
||||
//! 2. [Options](#options)
|
||||
//! 3. [Flags](#flags)
|
||||
//! 4. [Subcommands](#subcommands)
|
||||
//! 5. [Defaults](#defaults)
|
||||
//!
|
||||
//! Arguments are inferred from the fields of your struct.
|
||||
//!
|
||||
//! ### Positionals
|
||||
//!
|
||||
//! You can have users specify values by their position on the command-line:
|
||||
//!
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/03_03_positional.rs")]
|
||||
//! ```
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/03_03_positional.md")]
|
||||
//!
|
||||
//! Note that the [default `ArgAction` is `Set`][super#arg-types]. To
|
||||
//! accept multiple values, override the [action][Arg::action] with [`Append`][crate::ArgAction::Append] via `Vec`:
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/03_03_positional_mult.rs")]
|
||||
//! ```
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/03_03_positional_mult.md")]
|
||||
//!
|
||||
//! ### Options
|
||||
//!
|
||||
//! You can name your arguments with a flag:
|
||||
//! - Order doesn't matter
|
||||
//! - They can be optional
|
||||
//! - Intent is clearer
|
||||
//!
|
||||
//! To specify the flags for an argument, you can use [`#[arg(short = 'n')]`][Arg::short] and/or
|
||||
//! [`#[arg(long = "name")]`][Arg::long] attributes on a field. When no value is given (e.g.
|
||||
//! `#[arg(short)]`), the flag is inferred from the field's name.
|
||||
//!
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/03_02_option.rs")]
|
||||
//! ```
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/03_02_option.md")]
|
||||
//!
|
||||
//! Note that the [default `ArgAction` is `Set`][super#arg-types]. To
|
||||
//! accept multiple occurrences, override the [action][Arg::action] with [`Append`][crate::ArgAction::Append] via `Vec`:
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/03_02_option_mult.rs")]
|
||||
//! ```
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/03_02_option_mult.md")]
|
||||
//!
|
||||
//! ### Flags
|
||||
//!
|
||||
//! Flags can also be switches that can be on/off:
|
||||
//!
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/03_01_flag_bool.rs")]
|
||||
//! ```
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/03_01_flag_bool.md")]
|
||||
//!
|
||||
//! Note that the [default `ArgAction` for a `bool` field is
|
||||
//! `SetTrue`][super#arg-types]. To accept multiple flags, override the [action][Arg::action] with
|
||||
//! [`Count`][crate::ArgAction::Count]:
|
||||
//!
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/03_01_flag_count.rs")]
|
||||
//! ```
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/03_01_flag_count.md")]
|
||||
//!
|
||||
//! This also shows that any[`Arg`][crate::Args] method may be used as an attribute.
|
||||
//!
|
||||
//! ### Subcommands
|
||||
//!
|
||||
//! Subcommands are derived with `#[derive(Subcommand)]` and be added via
|
||||
//! [`#[command(subcommand)]` attribute][super#command-attributes] on the field using that type.
|
||||
//! Each instance of a [Subcommand][crate::Subcommand] can have its own version, author(s), Args,
|
||||
//! and even its own subcommands.
|
||||
//!
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/03_04_subcommands.rs")]
|
||||
//! ```
|
||||
//! We used a struct-variant to define the `add` subcommand.
|
||||
//! Alternatively, you can use a struct for your subcommand's arguments:
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/03_04_subcommands_alt.rs")]
|
||||
//! ```
|
||||
//!
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/03_04_subcommands.md")]
|
||||
//!
|
||||
//! ### Defaults
|
||||
//!
|
||||
//! We've previously showed that arguments can be [`required`][crate::Arg::required] or optional.
|
||||
//! When optional, you work with a `Option` and can `unwrap_or`. Alternatively, you can
|
||||
//! set [`#[arg(default_value_t)]`][super#arg-attributes].
|
||||
//!
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/03_05_default_values.rs")]
|
||||
//! ```
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/03_05_default_values.md")]
|
||||
#![allow(unused_imports)]
|
||||
use crate::builder::*;
|
||||
|
||||
pub use super::chapter_1 as previous;
|
||||
pub use super::chapter_3 as next;
|
||||
pub use crate::_tutorial as table_of_contents;
|
78
src/_derive/_tutorial/chapter_3.rs
Normal file
78
src/_derive/_tutorial/chapter_3.rs
Normal file
|
@ -0,0 +1,78 @@
|
|||
//! ## Validation
|
||||
//!
|
||||
//! 1. [Enumerated values](#enumerated-values)
|
||||
//! 2. [Validated values](#validated-values)
|
||||
//! 3. [Argument Relations](#argument-relations)
|
||||
//! 4. [Custom Validation](#custom-validation)
|
||||
//!
|
||||
//! An appropriate default parser/validator will be selected for the field's type. See
|
||||
//! [`value_parser!`][crate::value_parser!] for more details.
|
||||
//!
|
||||
//! ### Enumerated values
|
||||
//!
|
||||
//! For example, if you have arguments of specific values you want to test for, you can derive
|
||||
//! [`ValueEnum`][super#valueenum-attributes]
|
||||
//! (any [`PossibleValue`] builder function can be used as a `#[value]` attribute on enum variants).
|
||||
//!
|
||||
//! This allows you specify the valid values for that argument. If the user does not use one of
|
||||
//! those specific values, they will receive a graceful exit with error message informing them
|
||||
//! of the mistake, and what the possible valid values are
|
||||
//!
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/04_01_enum.rs")]
|
||||
//! ```
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/04_01_enum.md")]
|
||||
//!
|
||||
//! ### Validated values
|
||||
//!
|
||||
//! More generally, you can validate and parse into any data type with [`Arg::value_parser`].
|
||||
//!
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/04_02_parse.rs")]
|
||||
//! ```
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/04_02_parse.md")]
|
||||
//!
|
||||
//! A [custom parser][TypedValueParser] can be used to improve the error messages or provide additional validation:
|
||||
//!
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/04_02_validate.rs")]
|
||||
//! ```
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/04_02_validate.md")]
|
||||
//!
|
||||
//! See [`Arg::value_parser`][crate::Arg::value_parser] for more details.
|
||||
//!
|
||||
//! ### Argument Relations
|
||||
//!
|
||||
//! You can declare dependencies or conflicts between [`Arg`][crate::Arg]s or even
|
||||
//! [`ArgGroup`][crate::ArgGroup]s.
|
||||
//!
|
||||
//! [`ArgGroup`][crate::ArgGroup]s make it easier to declare relations instead of having to list
|
||||
//! each individually, or when you want a rule to apply "any but not all" arguments.
|
||||
//!
|
||||
//! Perhaps the most common use of [`ArgGroup`][crate::ArgGroup]s is to require one and *only* one
|
||||
//! argument to be present out of a given set. Imagine that you had multiple arguments, and you
|
||||
//! want one of them to be required, but making all of them required isn't feasible because perhaps
|
||||
//! they conflict with each other.
|
||||
//!
|
||||
//! [`ArgGroup`][crate::ArgGroup]s are automatically created for a `struct` with its
|
||||
//! [`ArgGroup::id`][crate::ArgGroup::id] being the struct's name.
|
||||
//!
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/04_03_relations.rs")]
|
||||
//! ```
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/04_03_relations.md")]
|
||||
//!
|
||||
//! ### Custom Validation
|
||||
//!
|
||||
//! As a last resort, you can create custom errors with the basics of clap's formatting.
|
||||
//!
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/04_04_custom.rs")]
|
||||
//! ```
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/04_04_custom.md")]
|
||||
#![allow(unused_imports)]
|
||||
use crate::builder::*;
|
||||
|
||||
pub use super::chapter_2 as previous;
|
||||
pub use super::chapter_4 as next;
|
||||
pub use crate::_tutorial as table_of_contents;
|
15
src/_derive/_tutorial/chapter_4.rs
Normal file
15
src/_derive/_tutorial/chapter_4.rs
Normal file
|
@ -0,0 +1,15 @@
|
|||
//! ## Testing
|
||||
//!
|
||||
//! clap reports most development errors as `debug_assert!`s. Rather than checking every
|
||||
//! subcommand, you should have a test that calls
|
||||
//! [`Command::debug_assert`][crate::Command::debug_assert]:
|
||||
//! ```rust,no_run
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/05_01_assert.rs")]
|
||||
//! ```
|
||||
|
||||
#![allow(unused_imports)]
|
||||
use crate::builder::*;
|
||||
|
||||
pub use super::chapter_3 as previous;
|
||||
pub use super::chapter_5 as next;
|
||||
pub use crate::_tutorial as table_of_contents;
|
14
src/_derive/_tutorial/chapter_5.rs
Normal file
14
src/_derive/_tutorial/chapter_5.rs
Normal file
|
@ -0,0 +1,14 @@
|
|||
//! ## Next Steps
|
||||
//!
|
||||
//! - [Cookbook][crate::_cookbook] for application-focused examples
|
||||
//! - Explore more features in the [Derive reference][super]
|
||||
//! - See also [`Command`], [`Arg`], [`ArgGroup`], and [`PossibleValue`] builder functions which
|
||||
//! can be used as attributes
|
||||
//!
|
||||
//! For support, see [Discussions](https://github.com/clap-rs/clap/discussions)
|
||||
|
||||
#![allow(unused_imports)]
|
||||
use crate::builder::*;
|
||||
|
||||
pub use super::chapter_4 as previous;
|
||||
pub use crate::_tutorial as table_of_contents;
|
|
@ -9,247 +9,28 @@
|
|||
|
||||
//! # Documentation: Derive Tutorial
|
||||
//!
|
||||
//! 1. [Quick Start](#quick-start)
|
||||
//! 2. [Configuring the Parser](#configuring-the-parser)
|
||||
//! 3. [Adding Arguments](#adding-arguments)
|
||||
//! 1. [Positionals](#positionals)
|
||||
//! 2. [Options](#options)
|
||||
//! 3. [Flags](#flags)
|
||||
//! 4. [Subcommands](#subcommands)
|
||||
//! 5. [Defaults](#defaults)
|
||||
//! 4. Validation
|
||||
//! 1. [Enumerated values](#enumerated-values)
|
||||
//! 2. [Validated values](#validated-values)
|
||||
//! 3. [Argument Relations](#argument-relations)
|
||||
//! 4. [Custom Validation](#custom-validation)
|
||||
//! 5. [Testing](#testing)
|
||||
//! 6. [Next Steps](#next-steps)
|
||||
//!
|
||||
//! See also
|
||||
//! - [FAQ: When should I use the builder vs derive APIs?][crate::_faq#when-should-i-use-the-builder-vs-derive-apis]
|
||||
//! - The [cookbook][crate::_cookbook] for more application-focused examples
|
||||
//!
|
||||
//! ## Quick Start
|
||||
//!
|
||||
//! You can create an application declaratively with a `struct` and some
|
||||
//! attributes.
|
||||
//!
|
||||
//! First, ensure `clap` is available with the [`derive` feature flag][crate::_features]:
|
||||
//! ```console
|
||||
//! $ cargo add clap --features derive
|
||||
//! ```
|
||||
//!
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/01_quick.rs")]
|
||||
//! ```
|
||||
//!
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/01_quick.md")]
|
||||
//!
|
||||
//! ## Configuring the Parser
|
||||
//!
|
||||
//! You use derive [`Parser`][crate::Parser] to start building a parser.
|
||||
//!
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/02_apps.rs")]
|
||||
//! ```
|
||||
//!
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/02_apps.md")]
|
||||
//!
|
||||
//! You can use [`#[command(author, version, about)]` attribute defaults][super#command-attributes] on the struct to fill these fields in from your `Cargo.toml` file.
|
||||
//!
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/02_crate.rs")]
|
||||
//! ```
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/02_crate.md")]
|
||||
//!
|
||||
//! You can use `#[command]` attributes on the struct to change the application level behavior of clap. Any [`Command`][crate::Command] builder function can be used as an attribute, like [`Command::next_line_help`].
|
||||
//!
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/02_app_settings.rs")]
|
||||
//! ```
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/02_app_settings.md")]
|
||||
//!
|
||||
//! ## Adding Arguments
|
||||
//!
|
||||
//! Arguments are inferred from the fields of your struct.
|
||||
//!
|
||||
//! ### Positionals
|
||||
//!
|
||||
//! You can have users specify values by their position on the command-line:
|
||||
//!
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/03_03_positional.rs")]
|
||||
//! ```
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/03_03_positional.md")]
|
||||
//!
|
||||
//! Note that the [default `ArgAction` is `Set`][super#arg-types]. To
|
||||
//! accept multiple values, override the [action][Arg::action] with [`Append`][crate::ArgAction::Append] via `Vec`:
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/03_03_positional_mult.rs")]
|
||||
//! ```
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/03_03_positional_mult.md")]
|
||||
//!
|
||||
//! ### Options
|
||||
//!
|
||||
//! You can name your arguments with a flag:
|
||||
//! - Order doesn't matter
|
||||
//! - They can be optional
|
||||
//! - Intent is clearer
|
||||
//!
|
||||
//! To specify the flags for an argument, you can use [`#[arg(short = 'n')]`][Arg::short] and/or
|
||||
//! [`#[arg(long = "name")]`][Arg::long] attributes on a field. When no value is given (e.g.
|
||||
//! `#[arg(short)]`), the flag is inferred from the field's name.
|
||||
//!
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/03_02_option.rs")]
|
||||
//! ```
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/03_02_option.md")]
|
||||
//!
|
||||
//! Note that the [default `ArgAction` is `Set`][super#arg-types]. To
|
||||
//! accept multiple occurrences, override the [action][Arg::action] with [`Append`][crate::ArgAction::Append] via `Vec`:
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/03_02_option_mult.rs")]
|
||||
//! ```
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/03_02_option_mult.md")]
|
||||
//!
|
||||
//! ### Flags
|
||||
//!
|
||||
//! Flags can also be switches that can be on/off:
|
||||
//!
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/03_01_flag_bool.rs")]
|
||||
//! ```
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/03_01_flag_bool.md")]
|
||||
//!
|
||||
//! Note that the [default `ArgAction` for a `bool` field is
|
||||
//! `SetTrue`][super#arg-types]. To accept multiple flags, override the [action][Arg::action] with
|
||||
//! [`Count`][crate::ArgAction::Count]:
|
||||
//!
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/03_01_flag_count.rs")]
|
||||
//! ```
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/03_01_flag_count.md")]
|
||||
//!
|
||||
//! This also shows that any[`Arg`][crate::Args] method may be used as an attribute.
|
||||
//!
|
||||
//! ### Subcommands
|
||||
//!
|
||||
//! Subcommands are derived with `#[derive(Subcommand)]` and be added via
|
||||
//! [`#[command(subcommand)]` attribute][super#command-attributes] on the field using that type.
|
||||
//! Each instance of a [Subcommand][crate::Subcommand] can have its own version, author(s), Args,
|
||||
//! and even its own subcommands.
|
||||
//!
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/03_04_subcommands.rs")]
|
||||
//! ```
|
||||
//! We used a struct-variant to define the `add` subcommand.
|
||||
//! Alternatively, you can use a struct for your subcommand's arguments:
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/03_04_subcommands_alt.rs")]
|
||||
//! ```
|
||||
//!
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/03_04_subcommands.md")]
|
||||
//!
|
||||
//! ### Defaults
|
||||
//!
|
||||
//! We've previously showed that arguments can be [`required`][crate::Arg::required] or optional.
|
||||
//! When optional, you work with a `Option` and can `unwrap_or`. Alternatively, you can
|
||||
//! set [`#[arg(default_value_t)]`][super#arg-attributes].
|
||||
//!
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/03_05_default_values.rs")]
|
||||
//! ```
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/03_05_default_values.md")]
|
||||
//!
|
||||
//! ## Validation
|
||||
//!
|
||||
//! An appropriate default parser/validator will be selected for the field's type. See
|
||||
//! [`value_parser!`][crate::value_parser!] for more details.
|
||||
//!
|
||||
//! ### Enumerated values
|
||||
//!
|
||||
//! For example, if you have arguments of specific values you want to test for, you can derive
|
||||
//! [`ValueEnum`][super#valueenum-attributes]
|
||||
//! (any [`PossibleValue`] builder function can be used as a `#[value]` attribute on enum variants).
|
||||
//!
|
||||
//! This allows you specify the valid values for that argument. If the user does not use one of
|
||||
//! those specific values, they will receive a graceful exit with error message informing them
|
||||
//! of the mistake, and what the possible valid values are
|
||||
//!
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/04_01_enum.rs")]
|
||||
//! ```
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/04_01_enum.md")]
|
||||
//!
|
||||
//! ### Validated values
|
||||
//!
|
||||
//! More generally, you can validate and parse into any data type with [`Arg::value_parser`].
|
||||
//!
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/04_02_parse.rs")]
|
||||
//! ```
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/04_02_parse.md")]
|
||||
//!
|
||||
//! A [custom parser][TypedValueParser] can be used to improve the error messages or provide additional validation:
|
||||
//!
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/04_02_validate.rs")]
|
||||
//! ```
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/04_02_validate.md")]
|
||||
//!
|
||||
//! See [`Arg::value_parser`][crate::Arg::value_parser] for more details.
|
||||
//!
|
||||
//! ### Argument Relations
|
||||
//!
|
||||
//! You can declare dependencies or conflicts between [`Arg`][crate::Arg]s or even
|
||||
//! [`ArgGroup`][crate::ArgGroup]s.
|
||||
//!
|
||||
//! [`ArgGroup`][crate::ArgGroup]s make it easier to declare relations instead of having to list
|
||||
//! each individually, or when you want a rule to apply "any but not all" arguments.
|
||||
//!
|
||||
//! Perhaps the most common use of [`ArgGroup`][crate::ArgGroup]s is to require one and *only* one
|
||||
//! argument to be present out of a given set. Imagine that you had multiple arguments, and you
|
||||
//! want one of them to be required, but making all of them required isn't feasible because perhaps
|
||||
//! they conflict with each other.
|
||||
//!
|
||||
//! [`ArgGroup`][crate::ArgGroup]s are automatically created for a `struct` with its
|
||||
//! [`ArgGroup::id`][crate::ArgGroup::id] being the struct's name.
|
||||
//!
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/04_03_relations.rs")]
|
||||
//! ```
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/04_03_relations.md")]
|
||||
//!
|
||||
//! ### Custom Validation
|
||||
//!
|
||||
//! As a last resort, you can create custom errors with the basics of clap's formatting.
|
||||
//!
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/04_04_custom.rs")]
|
||||
//! ```
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/04_04_custom.md")]
|
||||
//!
|
||||
//! ## Testing
|
||||
//!
|
||||
//! clap reports most development errors as `debug_assert!`s. Rather than checking every
|
||||
//! subcommand, you should have a test that calls
|
||||
//! [`Command::debug_assert`][crate::Command::debug_assert]:
|
||||
//! ```rust,no_run
|
||||
#![doc = include_str!("../../../examples/tutorial_derive/05_01_assert.rs")]
|
||||
//! ```
|
||||
//!
|
||||
//! ## Next Steps
|
||||
//!
|
||||
//! - [Cookbook][crate::_cookbook] for application-focused examples
|
||||
//! - Explore more features in the [Derive reference][super]
|
||||
//! - See also [`Command`], [`Arg`], [`ArgGroup`], and [`PossibleValue`] builder functions which
|
||||
//! can be used as attributes
|
||||
//!
|
||||
//! For support, see [Discussions](https://github.com/clap-rs/clap/discussions)
|
||||
//! 1. [Quick Start][chapter_0]
|
||||
//! 2. [Configuring the Parser][chapter_1]
|
||||
//! 3. [Adding Arguments][chapter_2]
|
||||
//! 1. [Positionals][chapter_2#positionals]
|
||||
//! 2. [Options][chapter_2#options]
|
||||
//! 3. [Flags][chapter_2#flags]
|
||||
//! 4. [Subcommands][chapter_2#subcommands]
|
||||
//! 5. [Defaults][chapter_2#defaults]
|
||||
//! 4. [Validation][chapter_3]
|
||||
//! 1. [Enumerated values][chapter_3#enumerated-values]
|
||||
//! 2. [Validated values][chapter_3#validated-values]
|
||||
//! 3. [Argument Relations][chapter_3#argument-relations]
|
||||
//! 4. [Custom Validation][chapter_3#custom-validation]
|
||||
//! 5. [Testing][chapter_4]
|
||||
//! 6. [Next Steps][chapter_5]
|
||||
|
||||
#![allow(unused_imports)]
|
||||
use crate::builder::Arg;
|
||||
use crate::builder::ArgGroup;
|
||||
use crate::builder::Command;
|
||||
use crate::builder::PossibleValue;
|
||||
use crate::builder::TypedValueParser;
|
||||
use crate::builder::*;
|
||||
|
||||
pub mod chapter_0;
|
||||
pub mod chapter_1;
|
||||
pub mod chapter_2;
|
||||
pub mod chapter_3;
|
||||
pub mod chapter_4;
|
||||
pub mod chapter_5;
|
||||
|
|
24
src/_tutorial/chapter_0.rs
Normal file
24
src/_tutorial/chapter_0.rs
Normal file
|
@ -0,0 +1,24 @@
|
|||
//! ## Quick Start
|
||||
//!
|
||||
//! You can create an application with several arguments using usage strings.
|
||||
//!
|
||||
//! First, ensure `clap` is available:
|
||||
//! ```console
|
||||
//! $ cargo add clap
|
||||
//! ```
|
||||
//!
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../examples/tutorial_builder/01_quick.rs")]
|
||||
//! ```
|
||||
//!
|
||||
#![doc = include_str!("../../examples/tutorial_builder/01_quick.md")]
|
||||
//!
|
||||
//! See also
|
||||
//! - [FAQ: When should I use the builder vs derive APIs?][crate::_faq#when-should-i-use-the-builder-vs-derive-apis]
|
||||
//! - The [cookbook][crate::_cookbook] for more application-focused examples
|
||||
|
||||
#![allow(unused_imports)]
|
||||
use crate::builder::*;
|
||||
|
||||
pub use super::chapter_1 as next;
|
||||
pub use crate::_tutorial as table_of_contents;
|
31
src/_tutorial/chapter_1.rs
Normal file
31
src/_tutorial/chapter_1.rs
Normal file
|
@ -0,0 +1,31 @@
|
|||
//! ## Configuring the Parser
|
||||
//!
|
||||
//! You use [`Command`][crate::Command] to start building a parser.
|
||||
//!
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../examples/tutorial_builder/02_apps.rs")]
|
||||
//! ```
|
||||
//!
|
||||
#![doc = include_str!("../../examples/tutorial_builder/02_apps.md")]
|
||||
//!
|
||||
//! You can use [`command!()`][crate::command!] to fill these fields in from your `Cargo.toml`
|
||||
//! file. **This requires the [`cargo` feature flag][crate::_features].**
|
||||
//!
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../examples/tutorial_builder/02_crate.rs")]
|
||||
//! ```
|
||||
#![doc = include_str!("../../examples/tutorial_builder/02_crate.md")]
|
||||
//!
|
||||
//! You can use [`Command`][crate::Command] methods to change the application level behavior of
|
||||
//! clap, like [`Command::next_line_help`].
|
||||
//!
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../examples/tutorial_builder/02_app_settings.rs")]
|
||||
//! ```
|
||||
#![doc = include_str!("../../examples/tutorial_builder/02_app_settings.md")]
|
||||
#![allow(unused_imports)]
|
||||
use crate::builder::*;
|
||||
|
||||
pub use super::chapter_0 as previous;
|
||||
pub use super::chapter_2 as next;
|
||||
pub use crate::_tutorial as table_of_contents;
|
87
src/_tutorial/chapter_2.rs
Normal file
87
src/_tutorial/chapter_2.rs
Normal file
|
@ -0,0 +1,87 @@
|
|||
//! ## Adding Arguments
|
||||
//!
|
||||
//! 1. [Positionals](#positionals)
|
||||
//! 2. [Options](#options)
|
||||
//! 3. [Flags](#flags)
|
||||
//! 4. [Subcommands](#subcommands)
|
||||
//! 5. [Defaults](#defaults)
|
||||
//!
|
||||
//!
|
||||
//! ### Positionals
|
||||
//!
|
||||
//! You can have users specify values by their position on the command-line:
|
||||
//!
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../examples/tutorial_builder/03_03_positional.rs")]
|
||||
//! ```
|
||||
#![doc = include_str!("../../examples/tutorial_builder/03_03_positional.md")]
|
||||
//!
|
||||
//! Note that the default [`ArgAction`][crate::ArgAction] is [`Set`][crate::ArgAction::Set]. To
|
||||
//! accept multiple values, override the [action][Arg::action] with [`Append`][crate::ArgAction::Append]:
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../examples/tutorial_builder/03_03_positional_mult.rs")]
|
||||
//! ```
|
||||
#![doc = include_str!("../../examples/tutorial_builder/03_03_positional_mult.md")]
|
||||
//!
|
||||
//! ### Options
|
||||
//!
|
||||
//! You can name your arguments with a flag:
|
||||
//! - Order doesn't matter
|
||||
//! - They can be optional
|
||||
//! - Intent is clearer
|
||||
//!
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../examples/tutorial_builder/03_02_option.rs")]
|
||||
//! ```
|
||||
#![doc = include_str!("../../examples/tutorial_builder/03_02_option.md")]
|
||||
//!
|
||||
//! Note that the default [`ArgAction`][crate::ArgAction] is [`Set`][crate::ArgAction::Set]. To
|
||||
//! accept multiple occurrences, override the [action][Arg::action] with [`Append`][crate::ArgAction::Append]:
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../examples/tutorial_builder/03_02_option_mult.rs")]
|
||||
//! ```
|
||||
#![doc = include_str!("../../examples/tutorial_builder/03_02_option_mult.md")]
|
||||
//!
|
||||
//! ### Flags
|
||||
//!
|
||||
//! Flags can also be switches that can be on/off:
|
||||
//!
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../examples/tutorial_builder/03_01_flag_bool.rs")]
|
||||
//! ```
|
||||
#![doc = include_str!("../../examples/tutorial_builder/03_01_flag_bool.md")]
|
||||
//!
|
||||
//! To accept multiple flags, use [`Count`][crate::ArgAction::Count]:
|
||||
//!
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../examples/tutorial_builder/03_01_flag_count.rs")]
|
||||
//! ```
|
||||
#![doc = include_str!("../../examples/tutorial_builder/03_01_flag_count.md")]
|
||||
//!
|
||||
//! ### Subcommands
|
||||
//!
|
||||
//! Subcommands are defined as [`Command`][crate::Command]s that get added via
|
||||
//! [`Command::subcommand`][crate::Command::subcommand]. Each instance of a Subcommand can have its
|
||||
//! own version, author(s), Args, and even its own subcommands.
|
||||
//!
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../examples/tutorial_builder/03_04_subcommands.rs")]
|
||||
//! ```
|
||||
#![doc = include_str!("../../examples/tutorial_builder/03_04_subcommands.md")]
|
||||
//!
|
||||
//! ### Defaults
|
||||
//!
|
||||
//! We've previously showed that arguments can be [`required`][crate::Arg::required] or optional.
|
||||
//! When optional, you work with a `Option` and can `unwrap_or`. Alternatively, you can set
|
||||
//! [`Arg::default_value`][crate::Arg::default_value].
|
||||
//!
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../examples/tutorial_builder/03_05_default_values.rs")]
|
||||
//! ```
|
||||
#![doc = include_str!("../../examples/tutorial_builder/03_05_default_values.md")]
|
||||
#![allow(unused_imports)]
|
||||
use crate::builder::*;
|
||||
|
||||
pub use super::chapter_1 as previous;
|
||||
pub use super::chapter_3 as next;
|
||||
pub use crate::_tutorial as table_of_contents;
|
84
src/_tutorial/chapter_3.rs
Normal file
84
src/_tutorial/chapter_3.rs
Normal file
|
@ -0,0 +1,84 @@
|
|||
//! ## Validation
|
||||
//!
|
||||
//! 1. [Enumerated values](#enumerated-values)
|
||||
//! 2. [Validated values](#validated-values)
|
||||
//! 3. [Argument Relations](#argument-relations)
|
||||
//! 4. [Custom Validation](#custom-validation)
|
||||
//!
|
||||
//! An appropriate default parser/validator will be selected for the field's type. See
|
||||
//! [`value_parser!`][crate::value_parser!] for more details.
|
||||
//!
|
||||
//! ### Enumerated values
|
||||
//!
|
||||
//! If you have arguments of specific values you want to test for, you can use the
|
||||
//! [`PossibleValuesParser`][crate::builder::PossibleValuesParser] or [`Arg::value_parser(["val1",
|
||||
//! ...])`][crate::Arg::value_parser] for short.
|
||||
//!
|
||||
//! This allows you specify the valid values for that argument. If the user does not use one of
|
||||
//! those specific values, they will receive a graceful exit with error message informing them
|
||||
//! of the mistake, and what the possible valid values are
|
||||
//!
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../examples/tutorial_builder/04_01_possible.rs")]
|
||||
//! ```
|
||||
#![doc = include_str!("../../examples/tutorial_builder/04_01_possible.md")]
|
||||
//!
|
||||
//! When enabling the [`derive` feature][crate::_features], you can use
|
||||
//! [`ValueEnum`][crate::ValueEnum] to take care of the boiler plate for you, giving the same
|
||||
//! results.
|
||||
//!
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../examples/tutorial_builder/04_01_enum.rs")]
|
||||
//! ```
|
||||
#![doc = include_str!("../../examples/tutorial_builder/04_01_enum.md")]
|
||||
//!
|
||||
//! ### Validated values
|
||||
//!
|
||||
//! More generally, you can validate and parse into any data type with [`Arg::value_parser`].
|
||||
//!
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../examples/tutorial_builder/04_02_parse.rs")]
|
||||
//! ```
|
||||
#![doc = include_str!("../../examples/tutorial_builder/04_02_parse.md")]
|
||||
//!
|
||||
//! A [custom parser][TypedValueParser] can be used to improve the error messages or provide additional validation:
|
||||
//!
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../examples/tutorial_builder/04_02_validate.rs")]
|
||||
//! ```
|
||||
#![doc = include_str!("../../examples/tutorial_builder/04_02_validate.md")]
|
||||
//!
|
||||
//! See [`Arg::value_parser`][crate::Arg::value_parser] for more details.
|
||||
//!
|
||||
//! ### Argument Relations
|
||||
//!
|
||||
//! You can declare dependencies or conflicts between [`Arg`][crate::Arg]s or even
|
||||
//! [`ArgGroup`][crate::ArgGroup]s.
|
||||
//!
|
||||
//! [`ArgGroup`][crate::ArgGroup]s make it easier to declare relations instead of having to list
|
||||
//! each individually, or when you want a rule to apply "any but not all" arguments.
|
||||
//!
|
||||
//! Perhaps the most common use of [`ArgGroup`][crate::ArgGroup]s is to require one and *only* one
|
||||
//! argument to be present out of a given set. Imagine that you had multiple arguments, and you
|
||||
//! want one of them to be required, but making all of them required isn't feasible because perhaps
|
||||
//! they conflict with each other.
|
||||
//!
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../examples/tutorial_builder/04_03_relations.rs")]
|
||||
//! ```
|
||||
#![doc = include_str!("../../examples/tutorial_builder/04_03_relations.md")]
|
||||
//!
|
||||
//! ### Custom Validation
|
||||
//!
|
||||
//! As a last resort, you can create custom errors with the basics of clap's formatting.
|
||||
//!
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../examples/tutorial_builder/04_04_custom.rs")]
|
||||
//! ```
|
||||
#![doc = include_str!("../../examples/tutorial_builder/04_04_custom.md")]
|
||||
#![allow(unused_imports)]
|
||||
use crate::builder::*;
|
||||
|
||||
pub use super::chapter_2 as previous;
|
||||
pub use super::chapter_4 as next;
|
||||
pub use crate::_tutorial as table_of_contents;
|
15
src/_tutorial/chapter_4.rs
Normal file
15
src/_tutorial/chapter_4.rs
Normal file
|
@ -0,0 +1,15 @@
|
|||
//! ## Testing
|
||||
//!
|
||||
//! clap reports most development errors as `debug_assert!`s. Rather than checking every
|
||||
//! subcommand, you should have a test that calls
|
||||
//! [`Command::debug_assert`][crate::Command::debug_assert]:
|
||||
//! ```rust,no_run
|
||||
#![doc = include_str!("../../examples/tutorial_builder/05_01_assert.rs")]
|
||||
//! ```
|
||||
|
||||
#![allow(unused_imports)]
|
||||
use crate::builder::*;
|
||||
|
||||
pub use super::chapter_3 as previous;
|
||||
pub use super::chapter_5 as next;
|
||||
pub use crate::_tutorial as table_of_contents;
|
12
src/_tutorial/chapter_5.rs
Normal file
12
src/_tutorial/chapter_5.rs
Normal file
|
@ -0,0 +1,12 @@
|
|||
//! ## Next Steps
|
||||
//!
|
||||
//! - [Cookbook][crate::_cookbook] for application-focused examples
|
||||
//! - Explore more features in the [API reference][super]
|
||||
//!
|
||||
//! For support, see [Discussions](https://github.com/clap-rs/clap/discussions)
|
||||
|
||||
#![allow(unused_imports)]
|
||||
use crate::builder::*;
|
||||
|
||||
pub use super::chapter_4 as previous;
|
||||
pub use crate::_tutorial as table_of_contents;
|
|
@ -9,234 +9,28 @@
|
|||
|
||||
//! # Documentation: Builder Tutorial
|
||||
//!
|
||||
//! 1. [Quick Start](#quick-start)
|
||||
//! 2. [Configuring the Parser](#configuring-the-parser)
|
||||
//! 3. [Adding Arguments](#adding-arguments)
|
||||
//! 1. [Positionals](#positionals)
|
||||
//! 2. [Options](#options)
|
||||
//! 3. [Flags](#flags)
|
||||
//! 4. [Subcommands](#subcommands)
|
||||
//! 5. [Defaults](#defaults)
|
||||
//! 4. Validation
|
||||
//! 1. [Enumerated values](#enumerated-values)
|
||||
//! 2. [Validated values](#validated-values)
|
||||
//! 3. [Argument Relations](#argument-relations)
|
||||
//! 4. [Custom Validation](#custom-validation)
|
||||
//! 5. [Testing](#testing)
|
||||
//! 6. [Next Steps](#next-steps)
|
||||
//!
|
||||
//! See also
|
||||
//! - [FAQ: When should I use the builder vs derive APIs?][crate::_faq#when-should-i-use-the-builder-vs-derive-apis]
|
||||
//! - The [cookbook][crate::_cookbook] for more application-focused examples
|
||||
//!
|
||||
//! ## Quick Start
|
||||
//!
|
||||
//! You can create an application with several arguments using usage strings.
|
||||
//!
|
||||
//! First, ensure `clap` is available:
|
||||
//! ```console
|
||||
//! $ cargo add clap
|
||||
//! ```
|
||||
//!
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../examples/tutorial_builder/01_quick.rs")]
|
||||
//! ```
|
||||
//!
|
||||
#![doc = include_str!("../../examples/tutorial_builder/01_quick.md")]
|
||||
//!
|
||||
//! ## Configuring the Parser
|
||||
//!
|
||||
//! You use [`Command`][crate::Command] to start building a parser.
|
||||
//!
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../examples/tutorial_builder/02_apps.rs")]
|
||||
//! ```
|
||||
//!
|
||||
#![doc = include_str!("../../examples/tutorial_builder/02_apps.md")]
|
||||
//!
|
||||
//! You can use [`command!()`][crate::command!] to fill these fields in from your `Cargo.toml`
|
||||
//! file. **This requires the [`cargo` feature flag][crate::_features].**
|
||||
//!
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../examples/tutorial_builder/02_crate.rs")]
|
||||
//! ```
|
||||
#![doc = include_str!("../../examples/tutorial_builder/02_crate.md")]
|
||||
//!
|
||||
//! You can use [`Command`][crate::Command] methods to change the application level behavior of
|
||||
//! clap, like [`Command::next_line_help`].
|
||||
//!
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../examples/tutorial_builder/02_app_settings.rs")]
|
||||
//! ```
|
||||
#![doc = include_str!("../../examples/tutorial_builder/02_app_settings.md")]
|
||||
//!
|
||||
//! ## Adding Arguments
|
||||
//!
|
||||
//! ### Positionals
|
||||
//!
|
||||
//! You can have users specify values by their position on the command-line:
|
||||
//!
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../examples/tutorial_builder/03_03_positional.rs")]
|
||||
//! ```
|
||||
#![doc = include_str!("../../examples/tutorial_builder/03_03_positional.md")]
|
||||
//!
|
||||
//! Note that the default [`ArgAction`][crate::ArgAction] is [`Set`][crate::ArgAction::Set]. To
|
||||
//! accept multiple values, override the [action][Arg::action] with [`Append`][crate::ArgAction::Append]:
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../examples/tutorial_builder/03_03_positional_mult.rs")]
|
||||
//! ```
|
||||
#![doc = include_str!("../../examples/tutorial_builder/03_03_positional_mult.md")]
|
||||
//!
|
||||
//! ### Options
|
||||
//!
|
||||
//! You can name your arguments with a flag:
|
||||
//! - Order doesn't matter
|
||||
//! - They can be optional
|
||||
//! - Intent is clearer
|
||||
//!
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../examples/tutorial_builder/03_02_option.rs")]
|
||||
//! ```
|
||||
#![doc = include_str!("../../examples/tutorial_builder/03_02_option.md")]
|
||||
//!
|
||||
//! Note that the default [`ArgAction`][crate::ArgAction] is [`Set`][crate::ArgAction::Set]. To
|
||||
//! accept multiple occurrences, override the [action][Arg::action] with [`Append`][crate::ArgAction::Append]:
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../examples/tutorial_builder/03_02_option_mult.rs")]
|
||||
//! ```
|
||||
#![doc = include_str!("../../examples/tutorial_builder/03_02_option_mult.md")]
|
||||
//!
|
||||
//! ### Flags
|
||||
//!
|
||||
//! Flags can also be switches that can be on/off:
|
||||
//!
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../examples/tutorial_builder/03_01_flag_bool.rs")]
|
||||
//! ```
|
||||
#![doc = include_str!("../../examples/tutorial_builder/03_01_flag_bool.md")]
|
||||
//!
|
||||
//! To accept multiple flags, use [`Count`][crate::ArgAction::Count]:
|
||||
//!
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../examples/tutorial_builder/03_01_flag_count.rs")]
|
||||
//! ```
|
||||
#![doc = include_str!("../../examples/tutorial_builder/03_01_flag_count.md")]
|
||||
//!
|
||||
//! ### Subcommands
|
||||
//!
|
||||
//! Subcommands are defined as [`Command`][crate::Command]s that get added via
|
||||
//! [`Command::subcommand`][crate::Command::subcommand]. Each instance of a Subcommand can have its
|
||||
//! own version, author(s), Args, and even its own subcommands.
|
||||
//!
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../examples/tutorial_builder/03_04_subcommands.rs")]
|
||||
//! ```
|
||||
#![doc = include_str!("../../examples/tutorial_builder/03_04_subcommands.md")]
|
||||
//!
|
||||
//! ### Defaults
|
||||
//!
|
||||
//! We've previously showed that arguments can be [`required`][crate::Arg::required] or optional.
|
||||
//! When optional, you work with a `Option` and can `unwrap_or`. Alternatively, you can set
|
||||
//! [`Arg::default_value`][crate::Arg::default_value].
|
||||
//!
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../examples/tutorial_builder/03_05_default_values.rs")]
|
||||
//! ```
|
||||
#![doc = include_str!("../../examples/tutorial_builder/03_05_default_values.md")]
|
||||
//!
|
||||
//! ## Validation
|
||||
//!
|
||||
//! By default, arguments are assumed to be `String`s and only UTF-8 validation is performed.
|
||||
//!
|
||||
//! ### Enumerated values
|
||||
//!
|
||||
//! If you have arguments of specific values you want to test for, you can use the
|
||||
//! [`PossibleValuesParser`][crate::builder::PossibleValuesParser] or [`Arg::value_parser(["val1",
|
||||
//! ...])`][crate::Arg::value_parser] for short.
|
||||
//!
|
||||
//! This allows you specify the valid values for that argument. If the user does not use one of
|
||||
//! those specific values, they will receive a graceful exit with error message informing them
|
||||
//! of the mistake, and what the possible valid values are
|
||||
//!
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../examples/tutorial_builder/04_01_possible.rs")]
|
||||
//! ```
|
||||
#![doc = include_str!("../../examples/tutorial_builder/04_01_possible.md")]
|
||||
//!
|
||||
//! When enabling the [`derive` feature][crate::_features], you can use
|
||||
//! [`ValueEnum`][crate::ValueEnum] to take care of the boiler plate for you, giving the same
|
||||
//! results.
|
||||
//!
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../examples/tutorial_builder/04_01_enum.rs")]
|
||||
//! ```
|
||||
#![doc = include_str!("../../examples/tutorial_builder/04_01_enum.md")]
|
||||
//!
|
||||
//! ### Validated values
|
||||
//!
|
||||
//! More generally, you can validate and parse into any data type with [`Arg::value_parser`].
|
||||
//!
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../examples/tutorial_builder/04_02_parse.rs")]
|
||||
//! ```
|
||||
#![doc = include_str!("../../examples/tutorial_builder/04_02_parse.md")]
|
||||
//!
|
||||
//! A [custom parser][TypedValueParser] can be used to improve the error messages or provide additional validation:
|
||||
//!
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../examples/tutorial_builder/04_02_validate.rs")]
|
||||
//! ```
|
||||
#![doc = include_str!("../../examples/tutorial_builder/04_02_validate.md")]
|
||||
//!
|
||||
//! See [`Arg::value_parser`][crate::Arg::value_parser] for more details.
|
||||
//!
|
||||
//! ### Argument Relations
|
||||
//!
|
||||
//! You can declare dependencies or conflicts between [`Arg`][crate::Arg]s or even
|
||||
//! [`ArgGroup`][crate::ArgGroup]s.
|
||||
//!
|
||||
//! [`ArgGroup`][crate::ArgGroup]s make it easier to declare relations instead of having to list
|
||||
//! each individually, or when you want a rule to apply "any but not all" arguments.
|
||||
//!
|
||||
//! Perhaps the most common use of [`ArgGroup`][crate::ArgGroup]s is to require one and *only* one
|
||||
//! argument to be present out of a given set. Imagine that you had multiple arguments, and you
|
||||
//! want one of them to be required, but making all of them required isn't feasible because perhaps
|
||||
//! they conflict with each other.
|
||||
//!
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../examples/tutorial_builder/04_03_relations.rs")]
|
||||
//! ```
|
||||
#![doc = include_str!("../../examples/tutorial_builder/04_03_relations.md")]
|
||||
//!
|
||||
//! ### Custom Validation
|
||||
//!
|
||||
//! As a last resort, you can create custom errors with the basics of clap's formatting.
|
||||
//!
|
||||
//! ```rust
|
||||
#![doc = include_str!("../../examples/tutorial_builder/04_04_custom.rs")]
|
||||
//! ```
|
||||
#![doc = include_str!("../../examples/tutorial_builder/04_04_custom.md")]
|
||||
//!
|
||||
//! ## Testing
|
||||
//!
|
||||
//! clap reports most development errors as `debug_assert!`s. Rather than checking every
|
||||
//! subcommand, you should have a test that calls
|
||||
//! [`Command::debug_assert`][crate::Command::debug_assert]:
|
||||
//! ```rust,no_run
|
||||
#![doc = include_str!("../../examples/tutorial_builder/05_01_assert.rs")]
|
||||
//! ```
|
||||
//!
|
||||
//! ## Next Steps
|
||||
//!
|
||||
//! - [Cookbook][crate::_cookbook] for application-focused examples
|
||||
//! - Explore more features in the [API reference][super]
|
||||
//!
|
||||
//! For support, see [Discussions](https://github.com/clap-rs/clap/discussions)
|
||||
//! 1. [Quick Start][chapter_0]
|
||||
//! 2. [Configuring the Parser][chapter_1]
|
||||
//! 3. [Adding Arguments][chapter_2]
|
||||
//! 1. [Positionals][chapter_2#positionals]
|
||||
//! 2. [Options][chapter_2#options]
|
||||
//! 3. [Flags][chapter_2#flags]
|
||||
//! 4. [Subcommands][chapter_2#subcommands]
|
||||
//! 5. [Defaults][chapter_2#defaults]
|
||||
//! 4. [Validation][chapter_3]
|
||||
//! 1. [Enumerated values][chapter_3#enumerated-values]
|
||||
//! 2. [Validated values][chapter_3#validated-values]
|
||||
//! 3. [Argument Relations][chapter_3#argument-relations]
|
||||
//! 4. [Custom Validation][chapter_3#custom-validation]
|
||||
//! 5. [Testing][chapter_4]
|
||||
//! 6. [Next Steps][chapter_5]
|
||||
|
||||
#![allow(unused_imports)]
|
||||
use crate::builder::Arg;
|
||||
use crate::builder::ArgGroup;
|
||||
use crate::builder::Command;
|
||||
use crate::builder::PossibleValue;
|
||||
use crate::builder::TypedValueParser;
|
||||
use crate::builder::*;
|
||||
|
||||
pub mod chapter_0;
|
||||
pub mod chapter_1;
|
||||
pub mod chapter_2;
|
||||
pub mod chapter_3;
|
||||
pub mod chapter_4;
|
||||
pub mod chapter_5;
|
||||
|
|
|
@ -6,8 +6,8 @@
|
|||
//! > **Command Line Argument Parser for Rust**
|
||||
//!
|
||||
//! Quick Links:
|
||||
//! - Derive [tutorial][_derive::_tutorial] and [reference][_derive]
|
||||
//! - Builder [tutorial][_tutorial] and [reference](index.html)
|
||||
//! - Derive [tutorial][_derive::_tutorial::chapter_0] and [reference][_derive]
|
||||
//! - Builder [tutorial][_tutorial::chapter_0] and [reference](index.html)
|
||||
//! - [Cookbook][_cookbook]
|
||||
//! - [FAQ][_faq]
|
||||
//! - [Discussions](https://github.com/clap-rs/clap/discussions)
|
||||
|
|
Loading…
Reference in a new issue