Skip to main content

#
clap/
_tutorial.rs

    1// Contributing
    2//
    3// New example code:
    4// - Please update the corresponding section in the derive tutorial
    5// - Building: They must be added to `Cargo.toml` with the appropriate `required-features`.
    6// - Testing: Ensure there is a markdown file with [trycmd](https://docs.rs/trycmd) syntax
    7//
    8// See also the general CONTRIBUTING
    9
    10//! ## Tutorial for the Builder API
    11//!
    12//! *See the side bar for the Table of Contents*
    13//!
    14//! ## Quick Start
    15//!
    16//! You can create an application with several arguments using usage strings.
    17//!
    18//! First, ensure `clap` is available:
    19//! ```console
    20//! $ cargo add clap
    21//! ```
    22//!
    23//! Here is a preview of the type of application you can make:
    24//! ```rust
    25#![doc = include_str!("../examples/tutorial_builder/01_quick.rs")]
    26//! ```
    27//!
    28#![doc = include_str!("../examples/tutorial_builder/01_quick.md")]
    29//!
    30//! See also
    31//! - [FAQ: When should I use the builder vs derive APIs?][crate::_faq#when-should-i-use-the-builder-vs-derive-apis]
    32//! - The [cookbook][crate::_cookbook] for more application-focused examples
    33//!
    34//! ## Configuring the Parser
    35//!
    36//! You use [`Command`][crate::Command] to start building a parser.
    37//!
    38//! ```rust
    39#![doc = include_str!("../examples/tutorial_builder/02_apps.rs")]
    40//! ```
    41//!
    42#![doc = include_str!("../examples/tutorial_builder/02_apps.md")]
    43//!
    44//! You can use [`command!()`][crate::command!] to fill these fields in from your `Cargo.toml`
    45//! file.  **This requires the [`cargo` feature flag][crate::_features].**
    46//!
    47//! ```rust
    48#![doc = include_str!("../examples/tutorial_builder/02_crate.rs")]
    49//! ```
    50#![doc = include_str!("../examples/tutorial_builder/02_crate.md")]
    51//!
    52//! You can use [`Command`][crate::Command] methods to change the application level behavior of
    53//! clap, like [`Command::next_line_help`].
    54//!
    55//! ```rust
    56#![doc = include_str!("../examples/tutorial_builder/02_app_settings.rs")]
    57//! ```
    58#![doc = include_str!("../examples/tutorial_builder/02_app_settings.md")]
    59//!
    60//! ## Adding Arguments
    61//!
    62//! 1. [Positionals](#positionals)
    63//! 2. [Options](#options)
    64//! 3. [Flags](#flags)
    65//! 4. [Required](#required)
    66//! 5. [Defaults](#defaults)
    67//! 6. [Subcommands](#subcommands)
    68//!
    69//!
    70//! ### Positionals
    71//!
    72//! By default, an [`Arg`] defines a positional argument:
    73//!
    74//! ```rust
    75#![doc = include_str!("../examples/tutorial_builder/03_03_positional.rs")]
    76//! ```
    77#![doc = include_str!("../examples/tutorial_builder/03_03_positional.md")]
    78//!
    79//! Note that the default [`ArgAction`][crate::ArgAction] is [`Set`][crate::ArgAction::Set].  To
    80//! accept multiple values, override the [action][Arg::action] with [`Append`][crate::ArgAction::Append]:
    81//! ```rust
    82#![doc = include_str!("../examples/tutorial_builder/03_03_positional_mult.rs")]
    83//! ```
    84#![doc = include_str!("../examples/tutorial_builder/03_03_positional_mult.md")]
    85//!
    86//! ### Options
    87//!
    88//! You can name your arguments with a flag:
    89//! - Intent of the value is clearer
    90//! - Order doesn't matter
    91//!
    92//! ```rust
    93#![doc = include_str!("../examples/tutorial_builder/03_02_option.rs")]
    94//! ```
    95#![doc = include_str!("../examples/tutorial_builder/03_02_option.md")]
    96//!
    97//! Note that the default [`ArgAction`][crate::ArgAction] is [`Set`][crate::ArgAction::Set].  To
    98//! accept multiple occurrences, override the [action][Arg::action] with [`Append`][crate::ArgAction::Append]:
    99//! ```rust
    100#![doc = include_str!("../examples/tutorial_builder/03_02_option_mult.rs")]
    101//! ```
    102#![doc = include_str!("../examples/tutorial_builder/03_02_option_mult.md")]
    103//!
    104//! ### Flags
    105//!
    106//! Flags can also be switches that can be on/off:
    107//!
    108//! ```rust
    109#![doc = include_str!("../examples/tutorial_builder/03_01_flag_bool.rs")]
    110//! ```
    111#![doc = include_str!("../examples/tutorial_builder/03_01_flag_bool.md")]
    112//!
    113//! To accept multiple flags, use [`Count`][crate::ArgAction::Count]:
    114//!
    115//! ```rust
    116#![doc = include_str!("../examples/tutorial_builder/03_01_flag_count.rs")]
    117//! ```
    118#![doc = include_str!("../examples/tutorial_builder/03_01_flag_count.md")]
    119//!
    120//! ### Required
    121//!
    122//! By default, an [`Arg`] is optional which can be changed with
    123//! [`required`][crate::Arg::required].
    124//! ```rust
    125#![doc = include_str!("../examples/tutorial_builder/03_06_required.rs")]
    126//! ```
    127#![doc = include_str!("../examples/tutorial_builder/03_06_required.md")]
    128//!
    129//! ### Defaults
    130//!
    131//! We've previously showed that arguments can be [`required`][crate::Arg::required] or optional.
    132//! When optional, you work with a `Option` and can `unwrap_or`.  Alternatively, you can set
    133//! [`Arg::default_value`][crate::Arg::default_value].
    134//!
    135//! ```rust
    136#![doc = include_str!("../examples/tutorial_builder/03_05_default_values.rs")]
    137//! ```
    138#![doc = include_str!("../examples/tutorial_builder/03_05_default_values.md")]
    139//!
    140//! ### Subcommands
    141//!
    142//! Subcommands are defined as [`Command`][crate::Command]s that get added via
    143//! [`Command::subcommand`][crate::Command::subcommand]. Each instance of a Subcommand can have its
    144//! own version, author(s), Args, and even its own subcommands.
    145//!
    146//! ```rust
    147#![doc = include_str!("../examples/tutorial_builder/03_04_subcommands.rs")]
    148//! ```
    149#![doc = include_str!("../examples/tutorial_builder/03_04_subcommands.md")]
    150//!
    151//! ## Validation
    152//!
    153//! 1. [Enumerated values](#enumerated-values)
    154//! 2. [Validated values](#validated-values)
    155//! 3. [Argument Relations](#argument-relations)
    156//! 4. [Custom Validation](#custom-validation)
    157//!
    158//! An appropriate default parser/validator will be selected for the field's type.  See
    159//! [`value_parser!`][crate::value_parser!] for more details.
    160//!
    161//! ### Enumerated values
    162//!
    163//! If you have arguments of specific values you want to test for, you can use the
    164//! [`PossibleValuesParser`] or [`Arg::value_parser(["val1",
    165//! ...])`][crate::Arg::value_parser] for short.
    166//!
    167//! This allows you to specify the valid values for that argument. If the user does not use one of
    168//! those specific values, they will receive a graceful exit with error message informing them
    169//! of the mistake, and what the possible valid values are
    170//!
    171//! ```rust
    172#![doc = include_str!("../examples/tutorial_builder/04_01_possible.rs")]
    173//! ```
    174#![doc = include_str!("../examples/tutorial_builder/04_01_possible.md")]
    175//!
    176//! When enabling the [`derive` feature][crate::_features], you can use
    177//! [`ValueEnum`][crate::ValueEnum] to take care of the boiler plate for you, giving the same
    178//! results.
    179//!
    180//! ```rust
    181#![doc = include_str!("../examples/tutorial_builder/04_01_enum.rs")]
    182//! ```
    183#![doc = include_str!("../examples/tutorial_builder/04_01_enum.md")]
    184//!
    185//! ### Validated values
    186//!
    187//! More generally, you can validate and parse into any data type with [`Arg::value_parser`].
    188//!
    189//! ```rust
    190#![doc = include_str!("../examples/tutorial_builder/04_02_parse.rs")]
    191//! ```
    192#![doc = include_str!("../examples/tutorial_builder/04_02_parse.md")]
    193//!
    194//! A [custom parser][TypedValueParser] can be used to improve the error messages or provide additional validation:
    195//!
    196//! ```rust
    197#![doc = include_str!("../examples/tutorial_builder/04_02_validate.rs")]
    198//! ```
    199#![doc = include_str!("../examples/tutorial_builder/04_02_validate.md")]
    200//!
    201//! See [`Arg::value_parser`][crate::Arg::value_parser] for more details.
    202//!
    203//! ### Argument Relations
    204//!
    205//! You can declare dependencies or conflicts between [`Arg`][crate::Arg]s or even
    206//! [`ArgGroup`][crate::ArgGroup]s.
    207//!
    208//! [`ArgGroup`][crate::ArgGroup]s  make it easier to declare relations instead of having to list
    209//! each individually, or when you want a rule to apply "any but not all" arguments.
    210//!
    211//! Perhaps the most common use of [`ArgGroup`][crate::ArgGroup]s is to require one and *only* one
    212//! argument to be present out of a given set. Imagine that you had multiple arguments, and you
    213//! want one of them to be required, but making all of them required isn't feasible because perhaps
    214//! they conflict with each other.
    215//!
    216//! ```rust
    217#![doc = include_str!("../examples/tutorial_builder/04_03_relations.rs")]
    218//! ```
    219#![doc = include_str!("../examples/tutorial_builder/04_03_relations.md")]
    220//!
    221//! ### Custom Validation
    222//!
    223//! As a last resort, you can create custom errors with the basics of clap's formatting.
    224//!
    225//! ```rust
    226#![doc = include_str!("../examples/tutorial_builder/04_04_custom.rs")]
    227//! ```
    228#![doc = include_str!("../examples/tutorial_builder/04_04_custom.md")]
    229//!
    230//! ## Testing
    231//!
    232//! clap reports most development errors as `debug_assert!`s.  Rather than checking every
    233//! subcommand, you should have a test that calls
    234//! [`Command::debug_assert`][crate::Command::debug_assert]:
    235//! ```rust,no_run
    236#![doc = include_str!("../examples/tutorial_builder/05_01_assert.rs")]
    237//! ```
    238//!
    239//! ## Next Steps
    240//!
    241//! - [Cookbook][crate::_cookbook] for application-focused examples
    242//! - Explore more features in the [API reference][super]
    243//!
    244//! For support, see [Discussions](https://github.com/clap-rs/clap/discussions)
    245#![allow(unused_imports)]
    246use crate::builder::*;