Skip to main content

#
clap/
_faq.rs

    1//! # Documentation: FAQ
    2//!
    3//! 1. [Comparisons](#comparisons)
    4//!    1. [How does `clap` compare to structopt?](#how-does-clap-compare-to-structopt)
    5//!    2. [What are some reasons to use `clap`? (The Pitch)](#what-are-some-reasons-to-use-clap-the-pitch)
    6//!    3. [What are some reasons *not* to use `clap`? (The Anti Pitch)](#what-are-some-reasons-not-to-use-clap-the-anti-pitch)
    7//!    4. [Reasons to use `clap`](#reasons-to-use-clap)
    8//! 2. [How many approaches are there to create a parser?](#how-many-approaches-are-there-to-create-a-parser)
    9//! 3. [When should I use the builder vs derive APIs?](#when-should-i-use-the-builder-vs-derive-apis)
    10//! 4. [Why is there a default subcommand of help?](#why-is-there-a-default-subcommand-of-help)
    11//!
    12//! ### Comparisons
    13//!
    14//! First, let me say that these comparisons are highly subjective, and not meant
    15//! in a critical or harsh manner. All the argument parsing libraries out there (to
    16//! include `clap`) have their own strengths and weaknesses. Sometimes it just
    17//! comes down to personal taste when all other factors are equal. When in doubt,
    18//! try them all and pick one that you enjoy :). There's plenty of room in the Rust
    19//! community for multiple implementations!
    20//!
    21//! For less detailed but more broad comparisons, see
    22//! [argparse-benchmarks](https://github.com/rust-cli/argparse-benchmarks-rs).
    23//!
    24//! #### How does `clap` compare to [structopt](https://github.com/TeXitoi/structopt)?
    25//!
    26//! Simple! `clap` *is* `structopt`.  `structopt` started as a derive API built on
    27//! top of clap v2.  With clap v3, we've forked structopt and integrated it
    28//! directly into clap.  structopt is in
    29//! [maintenance mode](https://github.com/TeXitoi/structopt/issues/516#issuecomment-989566094)
    30//! with the release of `clap_derive`.
    31//!
    32//! The benefits of integrating `structopt` and `clap` are:
    33//! - Easier cross-linking in documentation
    34//! - Documentation parity
    35//! - Tighter design feedback loop, ensuring all new features are designed with
    36//!   derives in mind and easier to change `clap` in response to `structopt` bugs.
    37//! - Clearer endorsement of `structopt`
    38//!
    39//! See also
    40//! - [`clap` v3 CHANGELOG](https://github.com/clap-rs/clap/blob/v3-master/CHANGELOG.md#300---2021-12-31)
    41//! - [`structopt` migration guide](https://github.com/clap-rs/clap/blob/v3-master/CHANGELOG.md#migrate-structopt)
    42//!
    43//! #### What are some reasons to use `clap`? (The Pitch)
    44//!
    45//! `clap` is as fast, and as lightweight as possible while still giving all the features you'd expect from a modern argument parser. In fact, for the amount and type of features `clap` offers it remains about as fast as `getopts`. If you use `clap`, when you just need some simple arguments parsed, you'll find it's a walk in the park. `clap` also makes it possible to represent extremely complex and advanced requirements without too much thought. `clap` aims to be intuitive, easy to use, and fully capable for wide variety use cases and needs.
    46//!
    47//! #### What are some reasons *not* to use `clap`? (The Anti Pitch)
    48//!
    49//! Depending on the style in which you choose to define the valid arguments, `clap` can be very verbose. `clap` also offers so many finetuning knobs and dials, that learning everything can seem overwhelming. I strive to keep the simple cases simple, but when turning all those custom dials it can get complex. `clap` is also opinionated about parsing. Even though so much can be tweaked and tuned with `clap` (and I'm adding more all the time), there are still certain features which `clap` implements in specific ways that may be contrary to some users' use-cases.
    50//!
    51//! #### Reasons to use `clap`
    52//!
    53//!  * You want all the nice CLI features your users may expect, yet you don't want to implement them all yourself. You'd like to focus on your application, not argument parsing.
    54//!  * In addition to the point above, you don't want to sacrifice performance to get all those nice features.
    55//!  * You have complex requirements/conflicts between your various valid args.
    56//!  * You want to use subcommands (although other libraries also support subcommands, they are not nearly as feature rich as those provided by `clap`).
    57//!  * You want some sort of custom validation built into the argument parsing process, instead of as part of your application (which allows for earlier failures, better error messages, more cohesive experience, etc.).
    58//!
    59//! ### How many approaches are there to create a parser?
    60//!
    61//! The following APIs are supported:
    62//! - [Derive][crate::_derive::_tutorial]
    63//! - [Builder][crate::_tutorial]
    64//!
    65//! Previously, we supported:
    66//! - [YAML](https://github.com/clap-rs/clap/issues/3087)
    67//! - [docopt](http://docopt.org/)-inspired [usage parser](https://github.com/clap-rs/clap/issues/3086)
    68//! - [`clap_app!`](https://github.com/clap-rs/clap/issues/2835)
    69//!
    70//! There are also experiments with other APIs:
    71//! - [fncmd](https://github.com/yuhr/fncmd): function attribute
    72//! - [clap-serde](https://github.com/aobatact/clap-serde): create a `Command` from a deserializer
    73//!
    74//! ### When should I use the builder vs derive APIs?
    75//!
    76//! Our default answer is to use the [Derive API][crate::_derive::_tutorial]:
    77//! - Easier to read, write, and modify
    78//! - Easier to keep the argument declaration and reading of argument in sync
    79//! - Easier to reuse, e.g. [clap-verbosity-flag](https://crates.io/crates/clap-verbosity-flag)
    80//!
    81//! The [Builder API][crate::_tutorial] is a lower-level API that someone might want to use for
    82//! - Faster compile times if you aren't already using other procedural macros
    83//! - More flexibility, e.g. you can look up the [argument's values][crate::ArgMatches::get_many],
    84//!   their [ordering with other arguments][crate::ArgMatches::indices_of], and [what set
    85//!   them][crate::ArgMatches::value_source].  The Derive API can only report values and not
    86//!   indices of or other data.
    87//!
    88//! You can [interop between Derive and Builder APIs][crate::_derive#mixing-builder-and-derive-apis].
    89//!
    90//! ### Why is there a default subcommand of help?
    91//!
    92//! There is only a default subcommand of `help` when other subcommands have been defined manually. So it's opt-in(ish), being that you only get a `help` subcommand if you're actually using subcommands.
    93//!
    94//! Also, if the user defined a `help` subcommand themselves, the auto-generated one wouldn't be added (meaning it's only generated if the user hasn't defined one themselves).
    95//!