diff options
Diffstat (limited to 'vendor/clap/src/_tutorial')
| -rw-r--r-- | vendor/clap/src/_tutorial/chapter_0.rs | 24 | ||||
| -rw-r--r-- | vendor/clap/src/_tutorial/chapter_1.rs | 31 | ||||
| -rw-r--r-- | vendor/clap/src/_tutorial/chapter_2.rs | 87 | ||||
| -rw-r--r-- | vendor/clap/src/_tutorial/chapter_3.rs | 84 | ||||
| -rw-r--r-- | vendor/clap/src/_tutorial/chapter_4.rs | 15 | ||||
| -rw-r--r-- | vendor/clap/src/_tutorial/chapter_5.rs | 12 | ||||
| -rw-r--r-- | vendor/clap/src/_tutorial/mod.rs | 36 |
7 files changed, 289 insertions, 0 deletions
diff --git a/vendor/clap/src/_tutorial/chapter_0.rs b/vendor/clap/src/_tutorial/chapter_0.rs new file mode 100644 index 000000000..6999f08b7 --- /dev/null +++ b/vendor/clap/src/_tutorial/chapter_0.rs @@ -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; diff --git a/vendor/clap/src/_tutorial/chapter_1.rs b/vendor/clap/src/_tutorial/chapter_1.rs new file mode 100644 index 000000000..fbafaf722 --- /dev/null +++ b/vendor/clap/src/_tutorial/chapter_1.rs @@ -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; diff --git a/vendor/clap/src/_tutorial/chapter_2.rs b/vendor/clap/src/_tutorial/chapter_2.rs new file mode 100644 index 000000000..607b4e4e6 --- /dev/null +++ b/vendor/clap/src/_tutorial/chapter_2.rs @@ -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; diff --git a/vendor/clap/src/_tutorial/chapter_3.rs b/vendor/clap/src/_tutorial/chapter_3.rs new file mode 100644 index 000000000..6dc7db2db --- /dev/null +++ b/vendor/clap/src/_tutorial/chapter_3.rs @@ -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; diff --git a/vendor/clap/src/_tutorial/chapter_4.rs b/vendor/clap/src/_tutorial/chapter_4.rs new file mode 100644 index 000000000..d778fb385 --- /dev/null +++ b/vendor/clap/src/_tutorial/chapter_4.rs @@ -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; diff --git a/vendor/clap/src/_tutorial/chapter_5.rs b/vendor/clap/src/_tutorial/chapter_5.rs new file mode 100644 index 000000000..a34a91442 --- /dev/null +++ b/vendor/clap/src/_tutorial/chapter_5.rs @@ -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; diff --git a/vendor/clap/src/_tutorial/mod.rs b/vendor/clap/src/_tutorial/mod.rs new file mode 100644 index 000000000..16832302d --- /dev/null +++ b/vendor/clap/src/_tutorial/mod.rs @@ -0,0 +1,36 @@ +// 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; |