diff options
Diffstat (limited to 'vendor/clap/src')
| -rw-r--r-- | vendor/clap/src/_derive/_tutorial.rs | 59 | ||||
| -rw-r--r-- | vendor/clap/src/_derive/mod.rs | 18 | ||||
| -rw-r--r-- | vendor/clap/src/_features.rs | 2 | ||||
| -rw-r--r-- | vendor/clap/src/_tutorial.rs | 30 | ||||
| -rw-r--r-- | vendor/clap/src/lib.rs | 1 |
5 files changed, 83 insertions, 27 deletions
diff --git a/vendor/clap/src/_derive/_tutorial.rs b/vendor/clap/src/_derive/_tutorial.rs index 8d00b03ec..2a9145fa2 100644 --- a/vendor/clap/src/_derive/_tutorial.rs +++ b/vendor/clap/src/_derive/_tutorial.rs @@ -23,6 +23,7 @@ //! 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] @@ -31,7 +32,12 @@ //! ## Quick Start //! //! You can create an application declaratively with a `struct` and some -//! attributes. **This requires enabling the [`derive` feature flag][crate::_features].** +//! 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")] @@ -49,14 +55,14 @@ //! #![doc = include_str!("../../examples/tutorial_derive/02_apps.md")] //! -//! You can use `#[command(author, version, about)]` attribute defaults to fill these fields in from your `Cargo.toml` file. +//! You can use [`#[command(author, version, about)]` attribute defaults][super#command-attributes] 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 attributes to change the application level behavior of clap. Any [`Command`][crate::Command] builder function can be used as an attribute. +//! You can use attributes 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")] @@ -74,8 +80,8 @@ //! ``` #![doc = include_str!("../../examples/tutorial_derive/03_03_positional.md")] //! -//! Note that the default [`ArgAction`][crate::ArgAction] is [`Set`][crate::ArgAction::Set]. To -//! accept multiple values, use [`Append`][crate::ArgAction::Append] via `Vec`: +//! 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")] //! ``` @@ -88,17 +94,17 @@ //! - They can be optional //! - Intent is clearer //! -//! The `#[arg(short = 'n')]` and `#[arg(long = "name")]` attributes that define +//! The [`#[arg(short = 'n')]`][Arg::short] and [`#[arg(long = "name")]`][Arg::long] attributes that define //! the flags are [`Arg`][crate::Args] methods that are derived from the field name when no value -//! is specified (`#[arg(short)]` and `#[arg(long)]`). +//! is specified ([`#[arg(short)]` and `#[arg(long)]`][super#arg-attributes]). //! //! ```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`][crate::ArgAction] is [`Set`][crate::ArgAction::Set]. To -//! accept multiple occurrences, use [`Append`][crate::ArgAction::Append] via `Vec`: +//! 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")] //! ``` @@ -106,17 +112,15 @@ //! //! ### Flags //! -//! Flags can also be switches that can be on/off. This is enabled via the -//! `#[arg(action = ArgAction::SetTrue)]` attribute though this is implied when the field is a -//! `bool`. +//! 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`][crate::ArgAction] for a `bool` field is -//! [`SetTrue`][crate::ArgAction::SetTrue]. To accept multiple flags, use +//! 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 @@ -126,7 +130,7 @@ //! //! ### Subcommands //! -//! Subcommands are derived with `#[derive(Subcommand)]` and be added via `#[command(subcommand)]` attribute. Each +//! Subcommands are derived with `#[derive(Subcommand)]` and be added via [`#[command(subcommand)]` attribute][super#command-attributes]. Each //! instance of a [Subcommand][crate::Subcommand] can have its own version, author(s), Args, and even its own //! subcommands. //! @@ -145,7 +149,7 @@ //! //! 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)]`. +//! set [`#[arg(default_value_t)]`][super#arg-attributes]. //! //! ```rust #![doc = include_str!("../../examples/tutorial_derive/03_05_default_values.rs")] @@ -160,7 +164,8 @@ //! ### Enumerated values //! //! For example, if you have arguments of specific values you want to test for, you can derive -//! [`ValueEnum`][crate::ValueEnum]. +//! [`ValueEnum`][super#valueenum-attributes] +//! (any [`PossibleValue`] builder function can be used as variant attributes). //! //! 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 @@ -173,14 +178,14 @@ //! //! ### Validated values //! -//! More generally, you can validate and parse into any data type. +//! 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 can be used to improve the error messages or provide additional validation: +//! 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")] @@ -227,3 +232,19 @@ //! ```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::Arg; +use crate::builder::ArgGroup; +use crate::builder::Command; +use crate::builder::PossibleValue; +use crate::builder::TypedValueParser; diff --git a/vendor/clap/src/_derive/mod.rs b/vendor/clap/src/_derive/mod.rs index 2e4a4902d..0c479a236 100644 --- a/vendor/clap/src/_derive/mod.rs +++ b/vendor/clap/src/_derive/mod.rs @@ -141,7 +141,7 @@ //! //! **Magic attributes:** //! - `name = <expr>`: [`Command::name`][crate::Command::name] -//! - When not present: [crate `name`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-name-field) (if on [`Parser`][crate::Parser] container), variant name (if on [`Subcommand`][crate::Subcommand] variant) +//! - When not present: [package `name`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-name-field) (if on [`Parser`][crate::Parser] container), variant name (if on [`Subcommand`][crate::Subcommand] variant) //! - `version [= <expr>]`: [`Command::version`][crate::Command::version] //! - When not present: no version set //! - Without `<expr>`: defaults to [crate `version`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-version-field) @@ -482,9 +482,23 @@ //! [`Parser`][crate::Parser]) //! - Proactively check for bad [`Command`][crate::Command] configurations by calling //! [`Command::debug_assert`][crate::Command::debug_assert] in a test -//! ([example](../tutorial_derive/05_01_assert.rs)) +//! ([example][_tutorial#testing]) //! - Always remember to [document](#doc-comments) args and commands with `#![deny(missing_docs)]` +// Point people here that search for attributes that don't exist in the derive (a subset of magic +// attributes) +#![doc(alias = "skip")] +#![doc(alias = "verbatim_doc_comment")] +#![doc(alias = "flatten")] +#![doc(alias = "external_subcommand")] +#![doc(alias = "subcommand")] +#![doc(alias = "rename_all")] +#![doc(alias = "rename_all_env")] +#![doc(alias = "default_value_t")] +#![doc(alias = "default_values_t")] +#![doc(alias = "default_value_os_t")] +#![doc(alias = "default_values_os_t")] + pub mod _tutorial; #[doc(inline)] pub use crate::_cookbook; diff --git a/vendor/clap/src/_features.rs b/vendor/clap/src/_features.rs index 27b567c98..2be4a608f 100644 --- a/vendor/clap/src/_features.rs +++ b/vendor/clap/src/_features.rs @@ -26,4 +26,4 @@ //! **Warning:** These may contain breaking changes between minor releases. //! //! * **unstable-v5**: Preview features which will be stable on the v5.0 release -//! * **unstable-unstable-styles**: Custom theming support for clap +//! * **unstable-styles**: Custom theming support for clap diff --git a/vendor/clap/src/_tutorial.rs b/vendor/clap/src/_tutorial.rs index 4605ec9a1..58e527cbc 100644 --- a/vendor/clap/src/_tutorial.rs +++ b/vendor/clap/src/_tutorial.rs @@ -23,6 +23,7 @@ //! 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] @@ -32,6 +33,11 @@ //! //! 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")] //! ``` @@ -57,7 +63,7 @@ #![doc = include_str!("../examples/tutorial_builder/02_crate.md")] //! //! You can use [`Command`][crate::Command] methods to change the application level behavior of -//! clap. +//! clap, like [`Command::next_line_help`]. //! //! ```rust #![doc = include_str!("../examples/tutorial_builder/02_app_settings.rs")] @@ -76,7 +82,7 @@ #![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, use [`Append`][crate::ArgAction::Append]: +//! 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")] //! ``` @@ -95,7 +101,7 @@ #![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, use [`Append`][crate::ArgAction::Append]: +//! 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")] //! ``` @@ -169,14 +175,14 @@ //! //! ### Validated values //! -//! More generally, you can validate and parse into any data type. +//! 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 can be used to improve the error messages or provide additional validation: +//! 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")] @@ -220,3 +226,17 @@ //! ```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::Arg; +use crate::builder::ArgGroup; +use crate::builder::Command; +use crate::builder::PossibleValue; +use crate::builder::TypedValueParser; diff --git a/vendor/clap/src/lib.rs b/vendor/clap/src/lib.rs index 8e6d1fd6e..2c861dc5c 100644 --- a/vendor/clap/src/lib.rs +++ b/vendor/clap/src/lib.rs @@ -62,6 +62,7 @@ //! - [clap_complete](https://crates.io/crates/clap_complete) for shell completion support //! //! CLI Helpers +//! - [cio](https://crates.io/crates/clio) for reading/writing to files specified as arguments //! - [clap-verbosity-flag](https://crates.io/crates/clap-verbosity-flag) //! - [clap-cargo](https://crates.io/crates/clap-cargo) //! - [concolor-clap](https://crates.io/crates/concolor-clap) |