-
-
Notifications
You must be signed in to change notification settings - Fork 1k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
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?
- Loading branch information
Showing
15 changed files
with
565 additions
and
473 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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; |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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; |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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; |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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; |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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; |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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; |
Oops, something went wrong.