Initial vendor packages

Signed-off-by: Valentin Popov <valentin@popov.link>

8 files changed, 818 insertions, 0 deletions

diff --git a/vendor/clap/src/_derive/_tutorial/chapter_0.rs b/vendor/clap/src/_derive/_tutorial/chapter_0.rs
new file mode 100644
index 0000000..d680694
--- /dev/null
+++ b/vendor/clap/src/_derive/_tutorial/chapter_0.rs
@@ -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;
diff --git a/vendor/clap/src/_derive/_tutorial/chapter_1.rs b/vendor/clap/src/_derive/_tutorial/chapter_1.rs
new file mode 100644
index 0000000..b58ae6e
--- /dev/null
+++ b/vendor/clap/src/_derive/_tutorial/chapter_1.rs
@@ -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;
diff --git a/vendor/clap/src/_derive/_tutorial/chapter_2.rs b/vendor/clap/src/_derive/_tutorial/chapter_2.rs
new file mode 100644
index 0000000..95d02f8
--- /dev/null
+++ b/vendor/clap/src/_derive/_tutorial/chapter_2.rs
@@ -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;
diff --git a/vendor/clap/src/_derive/_tutorial/chapter_3.rs b/vendor/clap/src/_derive/_tutorial/chapter_3.rs
new file mode 100644
index 0000000..16004fc
--- /dev/null
+++ b/vendor/clap/src/_derive/_tutorial/chapter_3.rs
@@ -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;
diff --git a/vendor/clap/src/_derive/_tutorial/chapter_4.rs b/vendor/clap/src/_derive/_tutorial/chapter_4.rs
new file mode 100644
index 0000000..86c5368
--- /dev/null
+++ b/vendor/clap/src/_derive/_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_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;
diff --git a/vendor/clap/src/_derive/_tutorial/chapter_5.rs b/vendor/clap/src/_derive/_tutorial/chapter_5.rs
new file mode 100644
index 0000000..c586392
--- /dev/null
+++ b/vendor/clap/src/_derive/_tutorial/chapter_5.rs
@@ -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;
diff --git a/vendor/clap/src/_derive/_tutorial/mod.rs b/vendor/clap/src/_derive/_tutorial/mod.rs
new file mode 100644
index 0000000..f48a64e
--- /dev/null
+++ b/vendor/clap/src/_derive/_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: 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/vendor/clap/src/_derive/mod.rs b/vendor/clap/src/_derive/mod.rs
new file mode 100644
index 0000000..2ad242d
--- /dev/null
+++ b/vendor/clap/src/_derive/mod.rs
@@ -0,0 +1,518 @@
+//! # Documentation: Derive Reference
+//!
+//! 1. [Overview](#overview)
+//! 2. [Attributes](#attributes)
+//!     1. [Terminology](#terminology)
+//!     2. [Command Attributes](#command-attributes)
+//!     2. [ArgGroup Attributes](#arggroup-attributes)
+//!     3. [Arg Attributes](#arg-attributes)
+//!     4. [ValueEnum Attributes](#valueenum-attributes)
+//!     5. [Possible Value Attributes](#possible-value-attributes)
+//! 3. [Arg Types](#arg-types)
+//! 4. [Doc Comments](#doc-comments)
+//! 5. [Mixing Builder and Derive APIs](#mixing-builder-and-derive-apis)
+//! 6. [Tips](#tips)
+//!
+//! ## Overview
+//!
+//! To derive `clap` types, you need to enable the [`derive` feature flag][crate::_features].
+//!
+//! Example:
+//! ```rust
+#![doc = include_str!("../../examples/demo.rs")]
+//! ```
+//!
+//! Let's start by breaking down the anatomy of the derive attributes:
+//! ```rust
+//! use clap::{Parser, Args, Subcommand, ValueEnum};
+//!
+//! /// Doc comment
+//! #[derive(Parser)]
+//! #[command(CMD ATTRIBUTE)]
+//! #[group(GROUP ATTRIBUTE)]
+//! struct Cli {
+//!     /// Doc comment
+//!     #[arg(ARG ATTRIBUTE)]
+//!     field: UserType,
+//!
+//!     #[arg(value_enum, ARG ATTRIBUTE...)]
+//!     field: EnumValues,
+//!
+//!     #[command(flatten)]
+//!     delegate: Struct,
+//!
+//!     #[command(subcommand)]
+//!     command: Command,
+//! }
+//!
+//! /// Doc comment
+//! #[derive(Args)]
+//! #[command(PARENT CMD ATTRIBUTE)]
+//! #[group(GROUP ATTRIBUTE)]
+//! struct Struct {
+//!     /// Doc comment
+//!     #[command(ARG ATTRIBUTE)]
+//!     field: UserType,
+//! }
+//!
+//! /// Doc comment
+//! #[derive(Subcommand)]
+//! #[command(PARENT CMD ATTRIBUTE)]
+//! enum Command {
+//!     /// Doc comment
+//!     #[command(CMD ATTRIBUTE)]
+//!     Variant1(Struct),
+//!
+//!     /// Doc comment
+//!     #[command(CMD ATTRIBUTE)]
+//!     Variant2 {
+//!         /// Doc comment
+//!         #[arg(ARG ATTRIBUTE)]
+//!         field: UserType,
+//!     }
+//! }
+//!
+//! /// Doc comment
+//! #[derive(ValueEnum)]
+//! #[value(VALUE ENUM ATTRIBUTE)]
+//! enum EnumValues {
+//!     /// Doc comment
+//!     #[value(POSSIBLE VALUE ATTRIBUTE)]
+//!     Variant1,
+//! }
+//!
+//! fn main() {
+//!     let cli = Cli::parse();
+//! }
+//! ```
+//!
+//! Traits:
+//! - [`Parser`][crate::Parser] parses arguments into a `struct` (arguments) or `enum` (subcommands).
+//!   - [`Args`][crate::Args] allows defining a set of re-usable arguments that get merged into their parent container.
+//!   - [`Subcommand`][crate::Subcommand] defines available subcommands.
+//!   - Subcommand arguments can be defined in a struct-variant or automatically flattened with a tuple-variant.
+//! - [`ValueEnum`][crate::ValueEnum] allows parsing a value directly into an `enum`, erroring on unsupported values.
+//!   - The derive doesn't work on enums that contain non-unit variants, unless they are skipped
+//!
+//! *See also the [derive tutorial][crate::_derive::_tutorial] and [cookbook][crate::_cookbook]*
+//!
+//! ## Attributes
+//!
+//! ### Terminology
+//!
+//! **Raw attributes** are forwarded directly to the underlying [`clap` builder][crate::builder].  Any
+//! [`Command`][crate::Command], [`Arg`][crate::Arg], or [`PossibleValue`][crate::builder::PossibleValue] method can be used as an attribute.
+//!
+//! Raw attributes come in two different syntaxes:
+//! ```rust,ignore
+//! #[arg(
+//!     global = true, // name = arg form, neat for one-arg methods
+//!     required_if_eq("out", "file") // name(arg1, arg2, ...) form.
+//! )]
+//! ```
+//!
+//! - `method = arg` can only be used for methods which take only one argument.
+//! - `method(arg1, arg2)` can be used with any method.
+//!
+//! As long as `method_name` is not one of the magical methods it will be
+//! translated into a mere method call.
+//!
+//! **Magic attributes** have post-processing done to them, whether that is
+//! - Providing of defaults
+//! - Special behavior is triggered off of it
+//!
+//! Magic attributes are more constrained in the syntax they support, usually just
+//! `<attr> = <value>` though some use `<attr>(<value>)` instead.  See the specific
+//! magic attributes documentation for details.  This allows users to access the
+//! raw behavior of an attribute via `<attr>(<value>)` syntax.
+//!
+//! **NOTE:** Some attributes are inferred from [Arg Types](#arg-types) and [Doc
+//! Comments](#doc-comments).  Explicit attributes take precedence over inferred
+//! attributes.
+//!
+//! ### Command Attributes
+//!
+//! These correspond to a [`Command`][crate::Command] which is used for both top-level parsers and
+//! when defining subcommands.
+//!
+//! **Raw attributes:**  Any [`Command` method][crate::Command] can also be used as an attribute,
+//! see [Terminology](#terminology) for syntax.
+//! - e.g. `#[command(arg_required_else_help(true))]` would translate to `cmd.arg_required_else_help(true)`
+//!
+//! **Magic attributes:**
+//! - `name  = <expr>`: [`Command::name`][crate::Command::name]
+//!   - 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)
+//! - `author [= <expr>]`: [`Command::author`][crate::Command::author]
+//!   - When not present: no author set
+//!   - Without `<expr>`: defaults to [crate `authors`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-authors-field)
+//! - `about [= <expr>]`: [`Command::about`][crate::Command::about]
+//!   - When not present: [Doc comment summary](#doc-comments)
+//!   - Without `<expr>`: [crate `description`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-description-field) ([`Parser`][crate::Parser] container)
+//!     - **TIP:** When a doc comment is also present, you most likely want to add
+//!       `#[arg(long_about = None)]` to clear the doc comment so only [`about`][crate::Command::about]
+//!       gets shown with both `-h` and `--help`.
+//! - `long_about[ = <expr>]`: [`Command::long_about`][crate::Command::long_about]
+//!   - When not present: [Doc comment](#doc-comments) if there is a blank line, else nothing
+//!   - When present without a value: [Doc comment](#doc-comments)
+//! - `verbatim_doc_comment`: Minimizes pre-processing when converting doc comments to [`about`][crate::Command::about] / [`long_about`][crate::Command::long_about]
+//! - `next_display_order`: [`Command::next_display_order`][crate::Command::next_display_order]
+//! - `next_help_heading`: [`Command::next_help_heading`][crate::Command::next_help_heading]
+//!   - When `flatten`ing [`Args`][crate::Args], this is scoped to just the args in this struct and any struct `flatten`ed into it
+//! - `rename_all = <string_literal>`: Override default field / variant name case conversion for [`Command::name`][crate::Command::name] / [`Arg::id`][crate::Arg::id]
+//!   - When not present: `"kebab-case"`
+//!   - Available values: `"camelCase"`, `"kebab-case"`, `"PascalCase"`, `"SCREAMING_SNAKE_CASE"`, `"snake_case"`, `"lower"`, `"UPPER"`, `"verbatim"`
+//! - `rename_all_env = <string_literal>`: Override default field name case conversion for env variables for  [`Arg::env`][crate::Arg::env]
+//!   - When not present: `"SCREAMING_SNAKE_CASE"`
+//!   - Available values: `"camelCase"`, `"kebab-case"`, `"PascalCase"`, `"SCREAMING_SNAKE_CASE"`, `"snake_case"`, `"lower"`, `"UPPER"`, `"verbatim"`
+//!
+//! And for [`Subcommand`][crate::Subcommand] variants:
+//! - `skip`: Ignore this variant
+//! - `flatten`: Delegates to the variant for more subcommands (must implement
+//!   [`Subcommand`][crate::Subcommand])
+//! - `subcommand`: Nest subcommands under the current set of subcommands (must implement
+//!   [`Subcommand`][crate::Subcommand])
+//! - `external_subcommand`: [`Command::allow_external_subcommand(true)`][crate::Command::allow_external_subcommands]
+//!   - Variant must be either `Variant(Vec<String>)` or `Variant(Vec<OsString>)`
+//!
+//! And for [`Args`][crate::Args] fields:
+//! - `flatten`: Delegates to the field for more arguments (must implement [`Args`][crate::Args])
+//!   - Only [`next_help_heading`][crate::Command::next_help_heading] can be used with `flatten`.  See
+//!     [clap-rs/clap#3269](https://github.com/clap-rs/clap/issues/3269) for why
+//!     arg attributes are not generally supported.
+//!   - **Tip:** Though we do apply a flattened [`Args`][crate::Args]'s Parent Command Attributes, this
+//!     makes reuse harder. Generally prefer putting the cmd attributes on the
+//!     [`Parser`][crate::Parser] or on the flattened field.
+//! - `subcommand`: Delegates definition of subcommands to the field (must implement
+//!   [`Subcommand`][crate::Subcommand])
+//!   - When `Option<T>`, the subcommand becomes optional
+//!
+//! See [Configuring the Parser][_tutorial::chapter_1] and
+//! [Subcommands][_tutorial::chapter_2#subcommands] from the tutorial.
+//!
+//! ### ArgGroup Attributes
+//!
+//! These correspond to the [`ArgGroup`][crate::ArgGroup] which is implicitly created for each
+//! `Args` derive.
+//!
+//! **Raw attributes:**  Any [`ArgGroup` method][crate::ArgGroup] can also be used as an attribute, see [Terminology](#terminology) for syntax.
+//! - e.g. `#[group(required = true)]` would translate to `arg_group.required(true)`
+//!
+//! **Magic attributes**:
+//! - `id = <expr>`: [`ArgGroup::id`][crate::ArgGroup::id]
+//!   - When not present: struct's name is used
+//! - `skip [= <expr>]`: Ignore this field, filling in with `<expr>`
+//!   - Without `<expr>`: fills the field with `Default::default()`
+//!
+//! Note:
+//! - 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.
+//!
+//! ### Arg Attributes
+//!
+//! These correspond to a [`Arg`][crate::Arg].
+//!
+//! **Raw attributes:**  Any [`Arg` method][crate::Arg] can also be used as an attribute, see [Terminology](#terminology) for syntax.
+//! - e.g. `#[arg(max_values(3))]` would translate to `arg.max_values(3)`
+//!
+//! **Magic attributes**:
+//! - `id = <expr>`: [`Arg::id`][crate::Arg::id]
+//!   - When not present: field's name is used
+//! - `value_parser [= <expr>]`: [`Arg::value_parser`][crate::Arg::value_parser]
+//!   - When not present: will auto-select an implementation based on the field type using
+//!     [`value_parser!`][crate::value_parser!]
+//! - `action [= <expr>]`: [`Arg::action`][crate::Arg::action]
+//!   - When not present: will auto-select an action based on the field type
+//! - `help = <expr>`: [`Arg::help`][crate::Arg::help]
+//!   - When not present: [Doc comment summary](#doc-comments)
+//! - `long_help[ = <expr>]`: [`Arg::long_help`][crate::Arg::long_help]
+//!   - When not present: [Doc comment](#doc-comments) if there is a blank line, else nothing
+//!   - When present without a value: [Doc comment](#doc-comments)
+//! - `verbatim_doc_comment`: Minimizes pre-processing when converting doc comments to [`help`][crate::Arg::help] / [`long_help`][crate::Arg::long_help]
+//! - `short [= <char>]`: [`Arg::short`][crate::Arg::short]
+//!   - When not present: no short set
+//!   - Without `<char>`: defaults to first character in the case-converted field name
+//! - `long [= <str>]`: [`Arg::long`][crate::Arg::long]
+//!   - When not present: no long set
+//!   - Without `<str>`: defaults to the case-converted field name
+//! - `env [= <str>]`: [`Arg::env`][crate::Arg::env] (needs [`env` feature][crate::_features] enabled)
+//!   - When not present: no env set
+//!   - Without `<str>`: defaults to the case-converted field name
+//! - `from_global`: Read a [`Arg::global`][crate::Arg::global] argument (raw attribute), regardless of what subcommand you are in
+//! - `value_enum`: Parse the value using the [`ValueEnum`][crate::ValueEnum]
+//! - `skip [= <expr>]`: Ignore this field, filling in with `<expr>`
+//!   - Without `<expr>`: fills the field with `Default::default()`
+//! - `default_value = <str>`: [`Arg::default_value`][crate::Arg::default_value] and [`Arg::required(false)`][crate::Arg::required]
+//! - `default_value_t [= <expr>]`: [`Arg::default_value`][crate::Arg::default_value] and [`Arg::required(false)`][crate::Arg::required]
+//!   - Requires `std::fmt::Display` that roundtrips correctly with the
+//!     [`Arg::value_parser`][crate::Arg::value_parser] or `#[arg(value_enum)]`
+//!   - Without `<expr>`, relies on `Default::default()`
+//! - `default_values_t = <expr>`: [`Arg::default_values`][crate::Arg::default_values] and [`Arg::required(false)`][crate::Arg::required]
+//!   - Requires field arg to be of type `Vec<T>` and `T` to implement `std::fmt::Display` or `#[arg(value_enum)]`
+//!   - `<expr>` must implement `IntoIterator<T>`
+//! - `default_value_os_t [= <expr>]`: [`Arg::default_value_os`][crate::Arg::default_value_os] and [`Arg::required(false)`][crate::Arg::required]
+//!   - Requires `std::convert::Into<OsString>` or `#[arg(value_enum)]`
+//!   - Without `<expr>`, relies on `Default::default()`
+//! - `default_values_os_t = <expr>`: [`Arg::default_values_os`][crate::Arg::default_values_os] and [`Arg::required(false)`][crate::Arg::required]
+//!   - Requires field arg to be of type `Vec<T>` and `T` to implement `std::convert::Into<OsString>` or `#[arg(value_enum)]`
+//!   - `<expr>` must implement `IntoIterator<T>`
+//!
+//! See [Adding Arguments][_tutorial::chapter_2] and [Validation][_tutorial::chapter_3] from the
+//! tutorial.
+//!
+//! ### ValueEnum Attributes
+//!
+//! - `rename_all = <string_literal>`: Override default field / variant name case conversion for [`PossibleValue::new`][crate::builder::PossibleValue]
+//!   - 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.
+//!
+//! ### Possible Value Attributes
+//!
+//! These correspond to a [`PossibleValue`][crate::builder::PossibleValue].
+//!
+//! **Raw attributes:**  Any [`PossibleValue` method][crate::builder::PossibleValue] can also be used as an attribute, see [Terminology](#terminology) for syntax.
+//! - e.g. `#[value(alias("foo"))]` would translate to `pv.alias("foo")`
+//!
+//! **Magic attributes**:
+//! - `name = <expr>`: [`PossibleValue::new`][crate::builder::PossibleValue::new]
+//!   - When not present: case-converted field name is used
+//! - `help = <expr>`: [`PossibleValue::help`][crate::builder::PossibleValue::help]
+//!   - When not present: [Doc comment summary](#doc-comments)
+//! - `skip`: Ignore this variant
+//!
+//! ## Arg Types
+//!
+//! `clap` assumes some intent based on the type used:
+//!
+//! | Type                | Effect                               | Implies                                                     |
+//! |---------------------|--------------------------------------|-------------------------------------------------------------|
+//! | `()`                | user-defined                         | `.action(ArgAction::Set).required(false)`                   |
+//! | `bool`              | flag                                 | `.action(ArgAction::SetTrue)`                               |
+//! | `Option<T>`         | optional argument                    | `.action(ArgAction::Set).required(false)`                   |
+//! | `Option<Option<T>>` | optional value for optional argument | `.action(ArgAction::Set).required(false).num_args(0..=1)`   |
+//! | `T`                 | required argument                    | `.action(ArgAction::Set).required(!has_default)`            |
+//! | `Vec<T>`            | `0..` occurrences of argument        | `.action(ArgAction::Append).required(false)`  |
+//! | `Option<Vec<T>>`    | `0..` occurrences of argument        | `.action(ArgAction::Append).required(false)`  |
+//!
+//! In addition, [`.value_parser(value_parser!(T))`][crate::value_parser!] is called for each
+//! field.
+//!
+//! Notes:
+//! - For custom type behavior, you can override the implied attributes/settings and/or set additional ones
+//!   - To force any inferred type (like `Vec<T>`) to be treated as `T`, you can refer to the type
+//!     by another means, like using `std::vec::Vec` instead of `Vec`.  For improving this, see
+//!     [#4626](https://github.com/clap-rs/clap/issues/4626).
+//! - `Option<Vec<T>>` will be `None` instead of `vec![]` if no arguments are provided.
+//!   - This gives the user some flexibility in designing their argument, like with `num_args(0..)`
+//!
+//! ## Doc Comments
+//!
+//! In clap, help messages for the whole binary can be specified
+//! via [`Command::about`][crate::Command::about] and [`Command::long_about`][crate::Command::long_about] while help messages
+//! for individual arguments can be specified via [`Arg::help`][crate::Arg::help] and [`Arg::long_help`][crate::Arg::long_help].
+//!
+//! `long_*` variants are used when user calls the program with
+//! `--help` and "short" variants are used with `-h` flag.
+//!
+//! ```rust
+//! # use clap::Parser;
+//!
+//! #[derive(Parser)]
+//! #[command(about = "I am a program and I work, just pass `-h`", long_about = None)]
+//! struct Foo {
+//!     #[arg(short, help = "Pass `-h` and you'll see me!")]
+//!     bar: String,
+//! }
+//! ```
+//!
+//! For convenience, doc comments can be used instead of raw methods
+//! (this example works exactly like the one above):
+//!
+//! ```rust
+//! # use clap::Parser;
+//!
+//! #[derive(Parser)]
+//! /// I am a program and I work, just pass `-h`
+//! struct Foo {
+//!     /// Pass `-h` and you'll see me!
+//!     bar: String,
+//! }
+//! ```
+//!
+//! **NOTE:** Attributes have priority over doc comments!
+//!
+//! **Top level doc comments always generate `Command::about/long_about` calls!**
+//! If you really want to use the `Command::about/long_about` methods (you likely don't),
+//! use the `about` / `long_about` attributes to override the calls generated from
+//! the doc comment.  To clear `long_about`, you can use
+//! `#[command(long_about = None)]`.
+//!
+//! ### Pre-processing
+//!
+//! ```rust
+//! # use clap::Parser;
+//! #[derive(Parser)]
+//! /// Hi there, I'm Robo!
+//! ///
+//! /// I like beeping, stumbling, eating your electricity,
+//! /// and making records of you singing in a shower.
+//! /// Pay up, or I'll upload it to youtube!
+//! struct Robo {
+//!     /// Call my brother SkyNet.
+//!     ///
+//!     /// I am artificial superintelligence. I won't rest
+//!     /// until I'll have destroyed humanity. Enjoy your
+//!     /// pathetic existence, you mere mortals.
+//!     #[arg(long, action)]
+//!     kill_all_humans: bool,
+//! }
+//! ```
+//!
+//! A doc comment consists of three parts:
+//! - Short summary
+//! - A blank line (whitespace only)
+//! - Detailed description, all the rest
+//!
+//! The summary corresponds with `Command::about` / `Arg::help`.  When a blank line is
+//! present, the whole doc comment will be passed to `Command::long_about` /
+//! `Arg::long_help`.  Or in other words, a doc may result in just a `Command::about` /
+//! `Arg::help` or `Command::about` / `Arg::help` and `Command::long_about` /
+//! `Arg::long_help`
+//!
+//! In addition, when `verbatim_doc_comment` is not present, `clap` applies some preprocessing, including:
+//!
+//! - Strip leading and trailing whitespace from every line, if present.
+//!
+//! - Strip leading and trailing blank lines, if present.
+//!
+//! - Interpret each group of non-empty lines as a word-wrapped paragraph.
+//!
+//!   We replace newlines within paragraphs with spaces to allow the output
+//!   to be re-wrapped to the terminal width.
+//!
+//! - Strip any excess blank lines so that there is exactly one per paragraph break.
+//!
+//! - If the first paragraph ends in exactly one period,
+//!   remove the trailing period (i.e. strip trailing periods but not trailing ellipses).
+//!
+//! Sometimes you don't want this preprocessing to apply, for example the comment contains
+//! some ASCII art or markdown tables, you would need to preserve LFs along with
+//! blank lines and the leading/trailing whitespace. When you pass use the
+//! `verbatim_doc_comment` magic attribute, you  preserve
+//! them.
+//!
+//! **Note:** Keep in mind that `verbatim_doc_comment` will *still*
+//! - Remove one leading space from each line, even if this attribute is present,
+//!   to allow for a space between `///` and the content.
+//! - Remove leading and trailing blank lines
+//!
+//! ## Mixing Builder and Derive APIs
+//!
+//! The builder and derive APIs do not live in isolation. They can work together, which is
+//! especially helpful if some arguments can be specified at compile-time while others must be
+//! specified at runtime.
+//!
+//! ### Using derived arguments in a builder application
+//!
+//! When using the derive API, you can `#[command(flatten)]` a struct deriving `Args` into a struct
+//! deriving `Args` or `Parser`. This example shows how you can augment a `Command` instance
+//! created using the builder API with `Args` created using the derive API.
+//!
+//! It uses the [`Args::augment_args`][crate::Args::augment_args] method to add the arguments to
+//! the `Command` instance.
+//!
+//! Crates such as [clap-verbosity-flag](https://github.com/rust-cli/clap-verbosity-flag) provide
+//! structs that implement `Args`. Without the technique shown in this example, it would not be
+//! possible to use such crates with the builder API.
+//!
+//! For example:
+//! ```rust
+#![doc = include_str!("../../examples/derive_ref/augment_args.rs")]
+//! ```
+//!
+//! ### Using derived subcommands in a builder application
+//!
+//! When using the derive API, you can use `#[command(subcommand)]` inside the struct to add
+//! subcommands. The type of the field is usually an enum that derived `Parser`. However, you can
+//! also add the subcommands in that enum to a `Command` instance created with the builder API.
+//!
+//! It uses the [`Subcommand::augment_subcommands`][crate::Subcommand::augment_subcommands] method
+//! to add the subcommands to the `Command` instance.
+//!
+//! For example:
+//! ```rust
+#![doc = include_str!("../../examples/derive_ref/augment_subcommands.rs")]
+//! ```
+//!
+//! ### Adding hand-implemented subcommands to a derived application
+//!
+//! When using the derive API, you can use `#[command(subcommand)]` inside the struct to add
+//! subcommands. The type of the field is usually an enum that derived `Parser`. However, you can
+//! also implement the `Subcommand` trait manually on this enum (or any other type) and it can
+//! still be used inside the struct created with the derive API. The implementation of the
+//! `Subcommand` trait will use the builder API to add the subcommands to the `Command` instance
+//! created behind the scenes for you by the derive API.
+//!
+//! Notice how in the previous example we used
+//! [`augment_subcommands`][crate::Subcommand::augment_subcommands] on an enum that derived
+//! `Parser`, whereas now we implement
+//! [`augment_subcommands`][crate::Subcommand::augment_subcommands] ourselves, but the derive API
+//! calls it automatically since we used the `#[command(subcommand)]` attribute.
+//!
+//! For example:
+//! ```rust
+#![doc = include_str!("../../examples/derive_ref/hand_subcommand.rs")]
+//! ```
+//!
+//! ### Flattening hand-implemented args into a derived application
+//!
+//! When using the derive API, you can use `#[command(flatten)]` inside the struct to add arguments as
+//! if they were added directly to the containing struct. The type of the field is usually an
+//! struct that derived `Args`. However, you can also implement the `Args` trait manually on this
+//! struct (or any other type) and it can still be used inside the struct created with the derive
+//! API. The implementation of the `Args` trait will use the builder API to add the arguments to
+//! the `Command` instance created behind the scenes for you by the derive API.
+//!
+//! Notice how in the previous example we used [`augment_args`][crate::Args::augment_args] on the
+//! struct that derived `Parser`, whereas now we implement
+//! [`augment_args`][crate::Args::augment_args] ourselves, but the derive API calls it
+//! automatically since we used the `#[command(flatten)]` attribute.
+//!
+//! For example:
+//! ```rust
+#![doc = include_str!("../../examples/derive_ref/flatten_hand_args.rs")]
+//! ```
+//!
+//! ## Tips
+//!
+//! - To get access to a [`Command`][crate::Command] call
+//!   [`CommandFactory::command`][crate::CommandFactory::command] (implemented when deriving
+//!   [`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#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;