Skip to main content

#
clap/_derive/
mod.rs

    1//! # Documentation: Derive Reference
    2//!
    3//! 1. [Overview](#overview)
    4//! 2. [Attributes](#attributes)
    5//!     1. [Terminology](#terminology)
    6//!     2. [Command Attributes](#command-attributes)
    7//!     2. [ArgGroup Attributes](#arggroup-attributes)
    8//!     3. [Arg Attributes](#arg-attributes)
    9//!     4. [ValueEnum Attributes](#valueenum-attributes)
    10//!     5. [Possible Value Attributes](#possible-value-attributes)
    11//! 3. [Field Types](#field-types)
    12//! 4. [Doc Comments](#doc-comments)
    13//! 5. [Mixing Builder and Derive APIs](#mixing-builder-and-derive-apis)
    14//! 6. [Tips](#tips)
    15//!
    16//! ## Overview
    17//!
    18//! To derive `clap` types, you need to enable the [`derive` feature flag][crate::_features].
    19//!
    20//! Example:
    21//! ```rust
    22#![doc = include_str!("../../examples/demo.rs")]
    23//! ```
    24//!
    25//! Let's start by breaking down the anatomy of the derive attributes:
    26//! ```rust
    27//! use clap::{Parser, Args, Subcommand, ValueEnum};
    28//!
    29//! /// Doc comment
    30//! #[derive(Parser)]
    31//! #[command(CMD ATTRIBUTE)]
    32//! #[group(GROUP ATTRIBUTE)]
    33//! struct Cli {
    34//!     /// Doc comment
    35//!     #[arg(ARG ATTRIBUTE)]
    36//!     field: UserType,
    37//!
    38//!     #[arg(value_enum, ARG ATTRIBUTE...)]
    39//!     field: EnumValues,
    40//!
    41//!     #[command(flatten)]
    42//!     delegate: Struct,
    43//!
    44//!     #[command(subcommand)]
    45//!     command: Command,
    46//! }
    47//!
    48//! /// Doc comment
    49//! #[derive(Args)]
    50//! #[command(PARENT CMD ATTRIBUTE)]
    51//! #[group(GROUP ATTRIBUTE)]
    52//! struct Struct {
    53//!     /// Doc comment
    54//!     #[command(ARG ATTRIBUTE)]
    55//!     field: UserType,
    56//! }
    57//!
    58//! /// Doc comment
    59//! #[derive(Subcommand)]
    60//! #[command(PARENT CMD ATTRIBUTE)]
    61//! enum Command {
    62//!     /// Doc comment
    63//!     #[command(CMD ATTRIBUTE)]
    64//!     Variant1(Struct),
    65//!
    66//!     /// Doc comment
    67//!     #[command(CMD ATTRIBUTE)]
    68//!     Variant2 {
    69//!         /// Doc comment
    70//!         #[arg(ARG ATTRIBUTE)]
    71//!         field: UserType,
    72//!     }
    73//! }
    74//!
    75//! /// Doc comment
    76//! #[derive(ValueEnum)]
    77//! #[value(VALUE ENUM ATTRIBUTE)]
    78//! enum EnumValues {
    79//!     /// Doc comment
    80//!     #[value(POSSIBLE VALUE ATTRIBUTE)]
    81//!     Variant1,
    82//! }
    83//!
    84//! let cli = Cli::parse();
    85//! ```
    86//!
    87//! Traits:
    88//! - [`Parser`][crate::Parser] parses arguments into a `struct` (arguments) or `enum` (subcommands).
    89//!   - [`Args`][crate::Args] allows defining a set of re-usable arguments that get merged into their parent container.
    90//!   - [`Subcommand`][crate::Subcommand] defines available subcommands.
    91//!   - Subcommand arguments can be defined in a struct-variant or automatically flattened with a tuple-variant.
    92//! - [`ValueEnum`][crate::ValueEnum] allows parsing a value directly into an `enum`, erroring on unsupported values.
    93//!   - The derive doesn't work on enums that contain non-unit variants, unless they are skipped
    94//!
    95//! *See also the [derive tutorial][crate::_derive::_tutorial] and [cookbook][crate::_cookbook]*
    96//!
    97//! ## Attributes
    98//!
    99//! ### Terminology
    100//!
    101//! **Raw attributes** are forwarded directly to the underlying [`clap` builder][crate::builder].  Any
    102//! [`Command`][crate::Command], [`Arg`][crate::Arg], or [`PossibleValue`][crate::builder::PossibleValue] method can be used as an attribute.
    103//!
    104//! Raw attributes come in two different syntaxes:
    105//! ```rust,ignore
    106//! #[arg(
    107//!     global = true, // name = arg form, neat for one-arg methods
    108//!     required_if_eq("out", "file") // name(arg1, arg2, ...) form.
    109//! )]
    110//! ```
    111//!
    112//! - `method = arg` can only be used for methods which take only one argument.
    113//! - `method(arg1, arg2)` can be used with any method.
    114//!
    115//! As long as `method_name` is not one of the magical methods it will be
    116//! translated into a mere method call.
    117//!
    118//! **Magic attributes** have post-processing done to them, whether that is
    119//! - Providing of defaults
    120//! - Special behavior is triggered off of it
    121//!
    122//! Magic attributes are more constrained in the syntax they support, usually just
    123//! `<attr> = <value>` though some use `<attr>(<value>)` instead.  See the specific
    124//! magic attributes documentation for details.  This allows users to access the
    125//! raw behavior of an attribute via `<attr>(<value>)` syntax.
    126//!
    127//! <div class="warning">
    128//!
    129//! **NOTE:** Some attributes are inferred from [Arg Types](#arg-types) and [Doc
    130//! Comments](#doc-comments).  Explicit attributes take precedence over inferred
    131//! attributes.
    132//!
    133//! </div>
    134//!
    135//! ### Command Attributes
    136//!
    137//! These correspond to a [`Command`][crate::Command] which is used for both top-level parsers and
    138//! when defining subcommands.
    139//!
    140//! **Raw attributes:**  Any [`Command` method][crate::Command] can also be used as an attribute,
    141//! see [Terminology](#terminology) for syntax.
    142//! - e.g. `#[command(arg_required_else_help(true))]` would translate to `cmd.arg_required_else_help(true)`
    143//!
    144//! **Magic attributes:**
    145//! - `name  = <expr>`: [`Command::name`][crate::Command::name]
    146//!   - 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)
    147//! - `version [= <expr>]`: [`Command::version`][crate::Command::version]
    148//!   - When not present: no version set
    149//!   - Without `<expr>`: defaults to [crate `version`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-version-field)
    150//! - `author [= <expr>]`: [`Command::author`][crate::Command::author]
    151//!   - When not present: no author set
    152//!   - Without `<expr>`: defaults to [crate `authors`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-authors-field)
    153//!   - **NOTE:** A custom [`help_template`][crate::Command::help_template] is needed for author to show up.
    154//! - `about [= <expr>]`: [`Command::about`][crate::Command::about]
    155//!   - When not present: [Doc comment summary](#doc-comments)
    156//!   - Without `<expr>`: [crate `description`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-description-field) ([`Parser`][crate::Parser] container)
    157//!     - **TIP:** When a doc comment is also present, you most likely want to add
    158//!       `#[arg(long_about = None)]` to clear the doc comment so only [`about`][crate::Command::about]
    159//!       gets shown with both `-h` and `--help`.
    160//! - `long_about[ = <expr>]`: [`Command::long_about`][crate::Command::long_about]
    161//!   - When not present: [Doc comment](#doc-comments) if there is a blank line, else nothing
    162//!   - When present without a value: [Doc comment](#doc-comments)
    163//! - `verbatim_doc_comment`: Minimizes pre-processing when converting doc comments to [`about`][crate::Command::about] / [`long_about`][crate::Command::long_about]
    164//! - `next_display_order`: [`Command::next_display_order`][crate::Command::next_display_order]
    165//! - `next_help_heading`: [`Command::next_help_heading`][crate::Command::next_help_heading]
    166//!   - When `flatten`ing [`Args`][crate::Args], this is scoped to just the args in this struct and any struct `flatten`ed into it
    167//! - `rename_all = <string_literal>`: Override default field / variant name case conversion for [`Command::name`][crate::Command::name] / [`Arg::id`][crate::Arg::id]
    168//!   - When not present: `"kebab-case"`
    169//!   - Available values: `"camelCase"`, `"kebab-case"`, `"PascalCase"`, `"SCREAMING_SNAKE_CASE"`, `"snake_case"`, `"lower"`, `"UPPER"`, `"verbatim"`
    170//! - `rename_all_env = <string_literal>`: Override default field name case conversion for env variables for  [`Arg::env`][crate::Arg::env]
    171//!   - When not present: `"SCREAMING_SNAKE_CASE"`
    172//!   - Available values: `"camelCase"`, `"kebab-case"`, `"PascalCase"`, `"SCREAMING_SNAKE_CASE"`, `"snake_case"`, `"lower"`, `"UPPER"`, `"verbatim"`
    173//!
    174//! And for [`Subcommand`][crate::Subcommand] variants:
    175//! - `skip`: Ignore this variant
    176//! - `flatten`: Delegates to the variant for more subcommands (must implement
    177//!   [`Subcommand`][crate::Subcommand])
    178//! - `subcommand`: Nest subcommands under the current set of subcommands (must implement
    179//!   [`Subcommand`][crate::Subcommand])
    180//! - `external_subcommand`: [`Command::allow_external_subcommand(true)`][crate::Command::allow_external_subcommands]
    181//!   - Variant must be either `Variant(Vec<String>)` or `Variant(Vec<OsString>)`
    182//!
    183//! And for [`Args`][crate::Args] fields:
    184//! - `flatten`: Delegates to the field for more arguments (must implement [`Args`][crate::Args])
    185//!   - Only [`next_help_heading`][crate::Command::next_help_heading] can be used with `flatten`.  See
    186//!     [clap-rs/clap#3269](https://github.com/clap-rs/clap/issues/3269) for why
    187//!     arg attributes are not generally supported.
    188//!   - **Tip:** Though we do apply a flattened [`Args`][crate::Args]'s Parent Command Attributes, this
    189//!     makes reuse harder. Generally prefer putting the cmd attributes on the
    190//!     [`Parser`][crate::Parser] or on the flattened field.
    191//! - `subcommand`: Delegates definition of subcommands to the field (must implement
    192//!   [`Subcommand`][crate::Subcommand])
    193//!   - When `Option<T>`, the subcommand becomes optional
    194//!
    195//! See [Configuring the Parser][_tutorial#configuring-the-parser] and
    196//! [Subcommands][_tutorial#subcommands] from the tutorial.
    197//!
    198//! ### ArgGroup Attributes
    199//!
    200//! These correspond to the [`ArgGroup`][crate::ArgGroup] which is implicitly created for each
    201//! `Args` derive.
    202//!
    203//! **Raw attributes:**  Any [`ArgGroup` method][crate::ArgGroup] can also be used as an attribute, see [Terminology](#terminology) for syntax.
    204//! - e.g. `#[group(required = true)]` would translate to `arg_group.required(true)`
    205//!
    206//! **Magic attributes**:
    207//! - `id = <expr>`: [`ArgGroup::id`][crate::ArgGroup::id]
    208//!   - When not present: struct's name is used
    209//! - `skip [= <expr>]`: Ignore this field, filling in with `<expr>`
    210//!   - Without `<expr>`: fills the field with `Default::default()`
    211//!
    212//! Note:
    213//! - For `struct`s, [`multiple = true`][crate::ArgGroup::multiple] is implied
    214//! - `enum` support is tracked at [#2621](https://github.com/clap-rs/clap/issues/2621)
    215//!
    216//! See [Argument Relations][_tutorial#argument-relations] from the tutorial.
    217//!
    218//! ### Arg Attributes
    219//!
    220//! These correspond to a [`Arg`][crate::Arg].
    221//! The default state for a field without attributes is to be a positional argument with [behavior
    222//! inferred from the field type](#arg-types).
    223//! `#[arg(...)]` attributes allow overriding or extending those defaults.
    224//!
    225//! **Raw attributes:**  Any [`Arg` method][crate::Arg] can also be used as an attribute, see [Terminology](#terminology) for syntax.
    226//! - e.g. `#[arg(num_args(..=3))]` would translate to `arg.num_args(..=3)`
    227//!
    228//! **Magic attributes**:
    229//! - `id = <expr>`: [`Arg::id`][crate::Arg::id]
    230//!   - When not present: field's name is used
    231//! - `value_parser [= <expr>]`: [`Arg::value_parser`][crate::Arg::value_parser]
    232//!   - When not present: will auto-select an implementation based on the field type using
    233//!     [`value_parser!`][crate::value_parser!]
    234//! - `action [= <expr>]`: [`Arg::action`][crate::Arg::action]
    235//!   - When not present: will auto-select an action based on the field type
    236//! - `help = <expr>`: [`Arg::help`][crate::Arg::help]
    237//!   - When not present: [Doc comment summary](#doc-comments)
    238//! - `long_help[ = <expr>]`: [`Arg::long_help`][crate::Arg::long_help]
    239//!   - When not present: [Doc comment](#doc-comments) if there is a blank line, else nothing
    240//!   - When present without a value: [Doc comment](#doc-comments)
    241//! - `verbatim_doc_comment`: Minimizes pre-processing when converting doc comments to [`help`][crate::Arg::help] / [`long_help`][crate::Arg::long_help]
    242//! - `short [= <char>]`: [`Arg::short`][crate::Arg::short]
    243//!   - When not present: no short set
    244//!   - Without `<char>`: defaults to first character in the case-converted field name
    245//! - `long [= <str>]`: [`Arg::long`][crate::Arg::long]
    246//!   - When not present: no long set
    247//!   - Without `<str>`: defaults to the case-converted field name
    248//! - `env [= <str>]`: [`Arg::env`][crate::Arg::env] (needs [`env` feature][crate::_features] enabled)
    249//!   - When not present: no env set
    250//!   - Without `<str>`: defaults to the case-converted field name
    251//! - `from_global`: Read a [`Arg::global`][crate::Arg::global] argument (raw attribute), regardless of what subcommand you are in
    252//! - `value_enum`: Parse the value using the [`ValueEnum`][crate::ValueEnum]
    253//! - `skip [= <expr>]`: Ignore this field, filling in with `<expr>`
    254//!   - Without `<expr>`: fills the field with `Default::default()`
    255//! - `default_value = <str>`: [`Arg::default_value`][crate::Arg::default_value] and [`Arg::required(false)`][crate::Arg::required]
    256//! - `default_value_t [= <expr>]`: [`Arg::default_value`][crate::Arg::default_value] and [`Arg::required(false)`][crate::Arg::required]
    257//!   - Requires `std::fmt::Display` that roundtrips correctly with the
    258//!     [`Arg::value_parser`][crate::Arg::value_parser] or `#[arg(value_enum)]`
    259//!   - Without `<expr>`, relies on `Default::default()`
    260//! - `default_values_t = <expr>`: [`Arg::default_values`][crate::Arg::default_values] and [`Arg::required(false)`][crate::Arg::required]
    261//!   - Requires field arg to be of type `Vec<T>` and `T` to implement `std::fmt::Display` or `#[arg(value_enum)]`
    262//!   - `<expr>` must implement `IntoIterator<T>`
    263//! - `default_value_os_t [= <expr>]`: [`Arg::default_value_os`][crate::Arg::default_value_os] and [`Arg::required(false)`][crate::Arg::required]
    264//!   - Requires `std::convert::Into<OsString>` or `#[arg(value_enum)]`
    265//!   - Without `<expr>`, relies on `Default::default()`
    266//! - `default_values_os_t = <expr>`: [`Arg::default_values_os`][crate::Arg::default_values_os] and [`Arg::required(false)`][crate::Arg::required]
    267//!   - Requires field arg to be of type `Vec<T>` and `T` to implement `std::convert::Into<OsString>` or `#[arg(value_enum)]`
    268//!   - `<expr>` must implement `IntoIterator<T>`
    269//!
    270//! See [Adding Arguments][_tutorial#adding-arguments] and [Validation][_tutorial#validation] from the
    271//! tutorial.
    272//!
    273//! ### ValueEnum Attributes
    274//!
    275//! - `rename_all = <string_literal>`: Override default field / variant name case conversion for [`PossibleValue::new`][crate::builder::PossibleValue]
    276//!   - When not present: `"kebab-case"`
    277//!   - Available values: `"camelCase"`, `"kebab-case"`, `"PascalCase"`, `"SCREAMING_SNAKE_CASE"`, `"snake_case"`, `"lower"`, `"UPPER"`, `"verbatim"`
    278//!
    279//! See [Enumerated values][_tutorial#enumerated-values] from the tutorial.
    280//!
    281//! ### Possible Value Attributes
    282//!
    283//! These correspond to a [`PossibleValue`][crate::builder::PossibleValue].
    284//!
    285//! **Raw attributes:**  Any [`PossibleValue` method][crate::builder::PossibleValue] can also be used as an attribute, see [Terminology](#terminology) for syntax.
    286//! - e.g. `#[value(alias("foo"))]` would translate to `pv.alias("foo")`
    287//!
    288//! **Magic attributes**:
    289//! - `name = <expr>`: [`PossibleValue::new`][crate::builder::PossibleValue::new]
    290//!   - When not present: case-converted field name is used
    291//! - `help = <expr>`: [`PossibleValue::help`][crate::builder::PossibleValue::help]
    292//!   - When not present: [Doc comment summary](#doc-comments)
    293//! - `skip`: Ignore this variant
    294//!
    295//! ## Field Types
    296//!
    297//! `clap` assumes some intent based on the type used.
    298//!
    299//! ### Subcommand Types
    300//!
    301//! | Type                  | Effect              | Implies                                                   |
    302//! |-----------------------|---------------------|-----------------------------------------------------------|
    303//! | `Option<T>`           | optional subcommand |                                                           |
    304//! | `T`                   | required subcommand | `.subcommand_required(true).arg_required_else_help(true)` |
    305//!
    306//! ### Arg Types
    307//!
    308//! | Type                  | Effect                                               | Implies                                                     | Notes |
    309//! |-----------------------|------------------------------------------------------|-------------------------------------------------------------|-------|
    310//! | `()`                  | user-defined                                         | `.action(ArgAction::Set).required(false)`                   |       |
    311//! | `bool`                | flag                                                 | `.action(ArgAction::SetTrue)`                               |       |
    312//! | `Option<T>`           | optional argument                                    | `.action(ArgAction::Set).required(false)`                   |       |
    313//! | `Option<Option<T>>`   | optional value for optional argument                 | `.action(ArgAction::Set).required(false).num_args(0..=1)`   |       |
    314//! | `T`                   | required argument                                    | `.action(ArgAction::Set).required(!has_default)`            |       |
    315//! | `Vec<T>`              | `0..` occurrences of argument                        | `.action(ArgAction::Append).required(false)`  |       |
    316//! | `Option<Vec<T>>`      | `0..` occurrences of argument                        | `.action(ArgAction::Append).required(false)`  |       |
    317//! | `Vec<Vec<T>>`         | `0..` occurrences of argument, grouped by occurrence | `.action(ArgAction::Append).required(false)`  | requires `unstable-v5` |
    318//! | `Option<Vec<Vec<T>>>` | `0..` occurrences of argument, grouped by occurrence | `.action(ArgAction::Append).required(false)`  | requires `unstable-v5` |
    319//!
    320//! In addition, [`.value_parser(value_parser!(T))`][crate::value_parser!] is called for each
    321//! field in the absence of a [`#[arg(value_parser)]` attribute](#arg-attributes).
    322//!
    323//! Notes:
    324//! - For custom type behavior, you can override the implied attributes/settings and/or set additional ones
    325//!   - To force any inferred type (like `Vec<T>`) to be treated as `T`, you can refer to the type
    326//!     by another means, like using `std::vec::Vec` instead of `Vec`.  For improving this, see
    327//!     [#4626](https://github.com/clap-rs/clap/issues/4626).
    328//! - `Option<Vec<T>>` and `Option<Vec<Vec<T>>` will be `None` instead of `vec![]` if no arguments are provided.
    329//!   - This gives the user some flexibility in designing their argument, like with `num_args(0..)`
    330//! - `Vec<Vec<T>>` will need [`Arg::num_args`][crate::Arg::num_args] set to be meaningful
    331//!
    332//! ## Doc Comments
    333//!
    334//! In clap, help messages for the whole binary can be specified
    335//! via [`Command::about`][crate::Command::about] and [`Command::long_about`][crate::Command::long_about] while help messages
    336//! for individual arguments can be specified via [`Arg::help`][crate::Arg::help] and [`Arg::long_help`][crate::Arg::long_help].
    337//!
    338//! `long_*` variants are used when user calls the program with
    339//! `--help` and "short" variants are used with `-h` flag.
    340//!
    341//! ```rust
    342//! # use clap::Parser;
    343//!
    344//! #[derive(Parser)]
    345//! #[command(about = "I am a program and I work, just pass `-h`", long_about = None)]
    346//! struct Foo {
    347//!     #[arg(short, help = "Pass `-h` and you'll see me!")]
    348//!     bar: String,
    349//! }
    350//! ```
    351//!
    352//! For convenience, doc comments can be used instead of raw methods
    353//! (this example works exactly like the one above):
    354//!
    355//! ```rust
    356//! # use clap::Parser;
    357//!
    358//! #[derive(Parser)]
    359//! /// I am a program and I work, just pass `-h`
    360//! struct Foo {
    361//!     /// Pass `-h` and you'll see me!
    362//!     bar: String,
    363//! }
    364//! ```
    365//!
    366//! <div class="warning">
    367//!
    368//! **NOTE:** Attributes have priority over doc comments!
    369//!
    370//! **Top level doc comments always generate `Command::about/long_about` calls!**
    371//! If you really want to use the `Command::about/long_about` methods (you likely don't),
    372//! use the `about` / `long_about` attributes to override the calls generated from
    373//! the doc comment.  To clear `long_about`, you can use
    374//! `#[command(long_about = None)]`.
    375//!
    376//! </div>
    377//!
    378//! ### Pre-processing
    379//!
    380//! ```rust
    381//! # use clap::Parser;
    382//! #[derive(Parser)]
    383//! /// Hi there, I'm Robo!
    384//! ///
    385//! /// I like beeping, stumbling, eating your electricity,
    386//! /// and making records of you singing in a shower.
    387//! /// Pay up, or I'll upload it to youtube!
    388//! struct Robo {
    389//!     /// Call my brother SkyNet.
    390//!     ///
    391//!     /// I am artificial superintelligence. I won't rest
    392//!     /// until I'll have destroyed humanity. Enjoy your
    393//!     /// pathetic existence, you mere mortals.
    394//!     #[arg(long, action)]
    395//!     kill_all_humans: bool,
    396//! }
    397//! ```
    398//!
    399//! A doc comment consists of three parts:
    400//! - Short summary
    401//! - A blank line (whitespace only)
    402//! - Detailed description, all the rest
    403//!
    404//! The summary corresponds with `Command::about` / `Arg::help`.  When a blank line is
    405//! present, the whole doc comment will be passed to `Command::long_about` /
    406//! `Arg::long_help`.  Or in other words, a doc may result in just a `Command::about` /
    407//! `Arg::help` or `Command::about` / `Arg::help` and `Command::long_about` /
    408//! `Arg::long_help`
    409//!
    410//! In addition, when `verbatim_doc_comment` is not present, `clap` applies some preprocessing, including:
    411//!
    412//! - Strip leading and trailing whitespace from every line, if present.
    413//!
    414//! - Strip leading and trailing blank lines, if present.
    415//!
    416//! - Interpret each group of non-empty lines as a word-wrapped paragraph.
    417//!
    418//!   We replace newlines within paragraphs with spaces to allow the output
    419//!   to be re-wrapped to the terminal width.
    420//!
    421//! - Strip any excess blank lines so that there is exactly one per paragraph break.
    422//!
    423//! - If the first paragraph ends in exactly one period,
    424//!   remove the trailing period (i.e. strip trailing periods but not trailing ellipses).
    425//!
    426//! Sometimes you don't want this preprocessing to apply, for example the comment contains
    427//! some ASCII art or markdown tables, you would need to preserve LFs along with
    428//! blank lines and the leading/trailing whitespace. When you pass use the
    429//! `verbatim_doc_comment` magic attribute, you  preserve
    430//! them.
    431//!
    432//! **Note:** Keep in mind that `verbatim_doc_comment` will *still*
    433//! - Remove one leading space from each line, even if this attribute is present,
    434//!   to allow for a space between `///` and the content.
    435//! - Remove leading and trailing blank lines
    436//!
    437//! ## Mixing Builder and Derive APIs
    438//!
    439//! The builder and derive APIs do not live in isolation. They can work together, which is
    440//! especially helpful if some arguments can be specified at compile-time while others must be
    441//! specified at runtime.
    442//!
    443//! ### Using derived arguments in a builder application
    444//!
    445//! When using the derive API, you can `#[command(flatten)]` a struct deriving `Args` into a struct
    446//! deriving `Args` or `Parser`. This example shows how you can augment a `Command` instance
    447//! created using the builder API with `Args` created using the derive API.
    448//!
    449//! It uses the [`Args::augment_args`][crate::Args::augment_args] method to add the arguments to
    450//! the `Command` instance.
    451//!
    452//! Crates such as [clap-verbosity-flag](https://github.com/rust-cli/clap-verbosity-flag) provide
    453//! structs that implement `Args`. Without the technique shown in this example, it would not be
    454//! possible to use such crates with the builder API.
    455//!
    456//! For example:
    457//! ```rust
    458#![doc = include_str!("../../examples/derive_ref/augment_args.rs")]
    459//! ```
    460//!
    461//! ### Using derived subcommands in a builder application
    462//!
    463//! When using the derive API, you can use `#[command(subcommand)]` inside the struct to add
    464//! subcommands. The type of the field is usually an enum that derived `Parser`. However, you can
    465//! also add the subcommands in that enum to a `Command` instance created with the builder API.
    466//!
    467//! It uses the [`Subcommand::augment_subcommands`][crate::Subcommand::augment_subcommands] method
    468//! to add the subcommands to the `Command` instance.
    469//!
    470//! For example:
    471//! ```rust
    472#![doc = include_str!("../../examples/derive_ref/augment_subcommands.rs")]
    473//! ```
    474//!
    475//! ### Adding hand-implemented subcommands to a derived application
    476//!
    477//! When using the derive API, you can use `#[command(subcommand)]` inside the struct to add
    478//! subcommands. The type of the field is usually an enum that derived `Parser`. However, you can
    479//! also implement the `Subcommand` trait manually on this enum (or any other type) and it can
    480//! still be used inside the struct created with the derive API. The implementation of the
    481//! `Subcommand` trait will use the builder API to add the subcommands to the `Command` instance
    482//! created behind the scenes for you by the derive API.
    483//!
    484//! Notice how in the previous example we used
    485//! [`augment_subcommands`][crate::Subcommand::augment_subcommands] on an enum that derived
    486//! `Parser`, whereas now we implement
    487//! [`augment_subcommands`][crate::Subcommand::augment_subcommands] ourselves, but the derive API
    488//! calls it automatically since we used the `#[command(subcommand)]` attribute.
    489//!
    490//! For example:
    491//! ```rust
    492#![doc = include_str!("../../examples/derive_ref/hand_subcommand.rs")]
    493//! ```
    494//!
    495//! ### Flattening hand-implemented args into a derived application
    496//!
    497//! When using the derive API, you can use `#[command(flatten)]` inside the struct to add arguments as
    498//! if they were added directly to the containing struct. The type of the field is usually an
    499//! struct that derived `Args`. However, you can also implement the `Args` trait manually on this
    500//! struct (or any other type) and it can still be used inside the struct created with the derive
    501//! API. The implementation of the `Args` trait will use the builder API to add the arguments to
    502//! the `Command` instance created behind the scenes for you by the derive API.
    503//!
    504//! Notice how in the previous example we used [`augment_args`][crate::Args::augment_args] on the
    505//! struct that derived `Parser`, whereas now we implement
    506//! [`augment_args`][crate::Args::augment_args] ourselves, but the derive API calls it
    507//! automatically since we used the `#[command(flatten)]` attribute.
    508//!
    509//! For example:
    510//! ```rust
    511#![doc = include_str!("../../examples/derive_ref/flatten_hand_args.rs")]
    512//! ```
    513//!
    514//! ## Tips
    515//!
    516//! - To get access to a [`Command`][crate::Command] call
    517//!   [`CommandFactory::command`][crate::CommandFactory::command] (implemented when deriving
    518//!   [`Parser`][crate::Parser])
    519//! - Proactively check for bad [`Command`][crate::Command] configurations by calling
    520//!   [`Command::debug_assert`][crate::Command::debug_assert] in a test
    521//!   ([example][_tutorial#testing])
    522//! - Always remember to [document](#doc-comments) args and commands with `#![deny(missing_docs)]`
    523//!   or `#[deny(clippy::missing_docs_in_private_items)]`
    524
    525// Point people here that search for attributes that don't exist in the derive (a subset of magic
    526// attributes)
    527#![doc(alias = "skip")]
    528#![doc(alias = "verbatim_doc_comment")]
    529#![doc(alias = "flatten")]
    530#![doc(alias = "external_subcommand")]
    531#![doc(alias = "subcommand")]
    532#![doc(alias = "rename_all")]
    533#![doc(alias = "rename_all_env")]
    534#![doc(alias = "default_value_t")]
    535#![doc(alias = "default_values_t")]
    536#![doc(alias = "default_value_os_t")]
    537#![doc(alias = "default_values_os_t")]
    538
    539pub mod _tutorial;
    540#[doc(inline)]
    541pub use crate::_cookbook;