diff --git a/src/_derive/_tutorial.rs b/src/_derive/_tutorial.rs new file mode 100644 index 00000000000..f109dfb6833 --- /dev/null +++ b/src/_derive/_tutorial.rs @@ -0,0 +1,248 @@ +// Contributing +// +// New example code: +// - Please update the corresponding section in the derive tutorial +// - Building: They must be added to `Cargo.toml` with the appropriate `required-features`. +// - Testing: Ensure there is a markdown file with [trycmd](https://docs.rs/trycmd) syntax +// +// See also the general CONTRIBUTING + +//! ## Tutorial for the Derive API +//! +//! *See the side bar for the Table of Contents* +//! +//! ## 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 +//! ``` +//! +//! Here is a preview of the type of application you can make: +//! ```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 +//! +//! ## 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(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 +//! +//! 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 +//! +//! By default, struct fields define positional arguments: +//! +//! ```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 +//! +//! 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")] +//! +//! ## 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) +#![allow(unused_imports)] +use crate::builder::*; diff --git a/src/_derive/_tutorial/chapter_0.rs b/src/_derive/_tutorial/chapter_0.rs deleted file mode 100644 index 5770a4172d6..00000000000 --- a/src/_derive/_tutorial/chapter_0.rs +++ /dev/null @@ -1,26 +0,0 @@ -//! ## 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 -//! ``` -//! -//! Here is a preview of the type of application you can make: -//! ```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::_derive::_tutorial as table_of_contents; diff --git a/src/_derive/_tutorial/chapter_1.rs b/src/_derive/_tutorial/chapter_1.rs deleted file mode 100644 index aafd7040237..00000000000 --- a/src/_derive/_tutorial/chapter_1.rs +++ /dev/null @@ -1,29 +0,0 @@ -//! ## 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(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::_derive::_tutorial as table_of_contents; diff --git a/src/_derive/_tutorial/chapter_2.rs b/src/_derive/_tutorial/chapter_2.rs deleted file mode 100644 index 4b56782de1d..00000000000 --- a/src/_derive/_tutorial/chapter_2.rs +++ /dev/null @@ -1,103 +0,0 @@ -//! ## 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 -//! -//! By default, struct fields define positional arguments: -//! -//! ```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::_derive::_tutorial as table_of_contents; diff --git a/src/_derive/_tutorial/chapter_3.rs b/src/_derive/_tutorial/chapter_3.rs deleted file mode 100644 index 15dab45c7a4..00000000000 --- a/src/_derive/_tutorial/chapter_3.rs +++ /dev/null @@ -1,78 +0,0 @@ -//! ## 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::_derive::_tutorial as table_of_contents; diff --git a/src/_derive/_tutorial/chapter_4.rs b/src/_derive/_tutorial/chapter_4.rs deleted file mode 100644 index 56ae6beda89..00000000000 --- a/src/_derive/_tutorial/chapter_4.rs +++ /dev/null @@ -1,15 +0,0 @@ -//! ## 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::_derive::_tutorial as table_of_contents; diff --git a/src/_derive/_tutorial/chapter_5.rs b/src/_derive/_tutorial/chapter_5.rs deleted file mode 100644 index 08ff984da58..00000000000 --- a/src/_derive/_tutorial/chapter_5.rs +++ /dev/null @@ -1,14 +0,0 @@ -//! ## 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::_derive::_tutorial as table_of_contents; diff --git a/src/_derive/_tutorial/mod.rs b/src/_derive/_tutorial/mod.rs deleted file mode 100644 index f48a64e8bda..00000000000 --- a/src/_derive/_tutorial/mod.rs +++ /dev/null @@ -1,36 +0,0 @@ -// Contributing -// -// New example code: -// - Please update the corresponding section in the derive tutorial -// - Building: They must be added to `Cargo.toml` with the appropriate `required-features`. -// - Testing: Ensure there is a markdown file with [trycmd](https://docs.rs/trycmd) syntax -// -// See also the general CONTRIBUTING - -//! # Documentation: Derive Tutorial -//! -//! 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::*; - -pub mod chapter_0; -pub mod chapter_1; -pub mod chapter_2; -pub mod chapter_3; -pub mod chapter_4; -pub mod chapter_5; diff --git a/src/_derive/mod.rs b/src/_derive/mod.rs index 09b7f052a20..b9091d2ad2f 100644 --- a/src/_derive/mod.rs +++ b/src/_derive/mod.rs @@ -194,8 +194,8 @@ //! [`Subcommand`][crate::Subcommand]) //! - When `Option`, the subcommand becomes optional //! -//! See [Configuring the Parser][_tutorial::chapter_1] and -//! [Subcommands][_tutorial::chapter_2#subcommands] from the tutorial. +//! See [Configuring the Parser][_tutorial#configuring-the-parser] and +//! [Subcommands][_tutorial#subcommands] from the tutorial. //! //! ### ArgGroup Attributes //! @@ -215,7 +215,7 @@ //! - For `struct`s, [`multiple = true`][crate::ArgGroup::multiple] is implied //! - `enum` support is tracked at [#2621](https://github.com/clap-rs/clap/issues/2621) //! -//! See [Argument Relations][_tutorial::chapter_3#argument-relations] from the tutorial. +//! See [Argument Relations][_tutorial#argument-relations] from the tutorial. //! //! ### Arg Attributes //! @@ -269,7 +269,7 @@ //! - Requires field arg to be of type `Vec` and `T` to implement `std::convert::Into` or `#[arg(value_enum)]` //! - `` must implement `IntoIterator` //! -//! See [Adding Arguments][_tutorial::chapter_2] and [Validation][_tutorial::chapter_3] from the +//! See [Adding Arguments][_tutorial#adding-arguments] and [Validation][_tutorial#validation] from the //! tutorial. //! //! ### ValueEnum Attributes @@ -278,7 +278,7 @@ //! - When not present: `"kebab-case"` //! - Available values: `"camelCase"`, `"kebab-case"`, `"PascalCase"`, `"SCREAMING_SNAKE_CASE"`, `"snake_case"`, `"lower"`, `"UPPER"`, `"verbatim"` //! -//! See [Enumerated values][_tutorial::chapter_3#enumerated-values] from the tutorial. +//! See [Enumerated values][_tutorial#enumerated-values] from the tutorial. //! //! ### Possible Value Attributes //! diff --git a/src/_tutorial.rs b/src/_tutorial.rs new file mode 100644 index 00000000000..877073643fe --- /dev/null +++ b/src/_tutorial.rs @@ -0,0 +1,237 @@ +// Contributing +// +// New example code: +// - Please update the corresponding section in the derive tutorial +// - Building: They must be added to `Cargo.toml` with the appropriate `required-features`. +// - Testing: Ensure there is a markdown file with [trycmd](https://docs.rs/trycmd) syntax +// +// See also the general CONTRIBUTING + +//! ## Tutorial for the Builder API +//! +//! *See the side bar for the Table of Contents* +//! +//! ## Quick Start +//! +//! You can create an application with several arguments using usage strings. +//! +//! First, ensure `clap` is available: +//! ```console +//! $ cargo add clap +//! ``` +//! +//! Here is a preview of the type of application you can make: +//! ```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 +//! +//! ## 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 +//! +//! 1. [Positionals](#positionals) +//! 2. [Options](#options) +//! 3. [Flags](#flags) +//! 4. [Subcommands](#subcommands) +//! 5. [Defaults](#defaults) +//! +//! +//! ### Positionals +//! +//! By default, an [`Arg`] defines a positional argument: +//! +//! ```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 +//! +//! 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 to 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) +#![allow(unused_imports)] +use crate::builder::*; diff --git a/src/_tutorial/chapter_0.rs b/src/_tutorial/chapter_0.rs deleted file mode 100644 index 3de5da45d87..00000000000 --- a/src/_tutorial/chapter_0.rs +++ /dev/null @@ -1,25 +0,0 @@ -//! ## Quick Start -//! -//! You can create an application with several arguments using usage strings. -//! -//! First, ensure `clap` is available: -//! ```console -//! $ cargo add clap -//! ``` -//! -//! Here is a preview of the type of application you can make: -//! ```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; diff --git a/src/_tutorial/chapter_1.rs b/src/_tutorial/chapter_1.rs deleted file mode 100644 index fbafaf722c3..00000000000 --- a/src/_tutorial/chapter_1.rs +++ /dev/null @@ -1,31 +0,0 @@ -//! ## 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; diff --git a/src/_tutorial/chapter_2.rs b/src/_tutorial/chapter_2.rs deleted file mode 100644 index 09abf95a781..00000000000 --- a/src/_tutorial/chapter_2.rs +++ /dev/null @@ -1,87 +0,0 @@ -//! ## Adding Arguments -//! -//! 1. [Positionals](#positionals) -//! 2. [Options](#options) -//! 3. [Flags](#flags) -//! 4. [Subcommands](#subcommands) -//! 5. [Defaults](#defaults) -//! -//! -//! ### Positionals -//! -//! By default, an [`Arg`] defines a positional argument: -//! -//! ```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; diff --git a/src/_tutorial/chapter_3.rs b/src/_tutorial/chapter_3.rs deleted file mode 100644 index ea69bf0a279..00000000000 --- a/src/_tutorial/chapter_3.rs +++ /dev/null @@ -1,84 +0,0 @@ -//! ## 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 to 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; diff --git a/src/_tutorial/chapter_4.rs b/src/_tutorial/chapter_4.rs deleted file mode 100644 index d778fb385ea..00000000000 --- a/src/_tutorial/chapter_4.rs +++ /dev/null @@ -1,15 +0,0 @@ -//! ## 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; diff --git a/src/_tutorial/chapter_5.rs b/src/_tutorial/chapter_5.rs deleted file mode 100644 index a34a91442d7..00000000000 --- a/src/_tutorial/chapter_5.rs +++ /dev/null @@ -1,12 +0,0 @@ -//! ## 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; diff --git a/src/_tutorial/mod.rs b/src/_tutorial/mod.rs deleted file mode 100644 index 16832302db0..00000000000 --- a/src/_tutorial/mod.rs +++ /dev/null @@ -1,36 +0,0 @@ -// Contributing -// -// New example code: -// - Please update the corresponding section in the derive tutorial -// - Building: They must be added to `Cargo.toml` with the appropriate `required-features`. -// - Testing: Ensure there is a markdown file with [trycmd](https://docs.rs/trycmd) syntax -// -// See also the general CONTRIBUTING - -//! # Documentation: Builder Tutorial -//! -//! 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::*; - -pub mod chapter_0; -pub mod chapter_1; -pub mod chapter_2; -pub mod chapter_3; -pub mod chapter_4; -pub mod chapter_5;