Skip to main content

#
clap/
lib.rs

    1// Copyright ⓒ 2015-2016 Kevin B. Knapp and [`clap-rs` contributors](https://github.com/clap-rs/clap/graphs/contributors).
    2// Licensed under the MIT license
    3// (see LICENSE or <http://opensource.org/licenses/MIT>) All files in the project carrying such
    4// notice may not be copied, modified, or distributed except according to those terms.
    5
    6//! > **Command Line Argument Parser for Rust**
    7//!
    8//! Quick Links:
    9//! - Derive [tutorial][_derive::_tutorial] and [reference][_derive]
    10//! - Builder [tutorial][_tutorial] and [reference][Command]
    11//! - [Cookbook][_cookbook]
    12//! - [CLI Concepts][_concepts]
    13//! - [FAQ][_faq]
    14//! - [Discussions](https://github.com/clap-rs/clap/discussions)
    15//! - [CHANGELOG](https://github.com/clap-rs/clap/blob/v4.6.5/CHANGELOG.md) (includes major version migration
    16//!   guides)
    17//!
    18//! ## Aspirations
    19//!
    20//! - Out of the box, users get a polished CLI experience
    21//!   - Including common argument behavior, help generation, suggested fixes for users, colored output, [shell completions](https://github.com/clap-rs/clap/tree/master/clap_complete), etc
    22//! - Flexible enough to port your existing CLI interface
    23//!   - However, we won't necessarily streamline support for each use case
    24//! - Reasonable parse performance
    25//! - Resilient maintainership, including
    26//!   - Willing to break compatibility rather than batching up breaking changes in large releases
    27//!   - Leverage feature flags to keep to one active branch
    28//!   - Being under [WG-CLI](https://github.com/rust-cli/team/) to increase the bus factor
    29//! - We follow semver and will wait about 6-9 months between major breaking changes
    30//! - We will support the last two minor Rust releases (MSRV, currently 1.74)
    31//!
    32//! While these aspirations can be at odds with fast build times and low binary
    33//! size, we will still strive to keep these reasonable for the flexibility you
    34//! get.  Check out the
    35//! [argparse-benchmarks](https://github.com/rust-cli/argparse-benchmarks-rs) for
    36//! CLI parsers optimized for other use cases.
    37//!
    38//! ## Example
    39//!
    40//! Run
    41//! ```console
    42//! $ cargo add clap --features derive
    43//! ```
    44//! *(See also [feature flag reference][_features])*
    45//!
    46//! Then define your CLI in `main.rs`:
    47//! ```rust
    48//! # #[cfg(feature = "derive")] {
    49#![doc = include_str!("../examples/demo.rs")]
    50//! # }
    51//! ```
    52//!
    53//! And try it out:
    54#![doc = include_str!("../examples/demo.md")]
    55//!
    56//! See also the derive [tutorial][_derive::_tutorial] and [reference][_derive]
    57//!
    58//! ### Related Projects
    59//!
    60//! Augment clap:
    61//! - [wild](https://crates.io/crates/wild) for supporting wildcards (`*`) on Windows like you do Linux
    62//! - [argfile](https://crates.io/crates/argfile) for loading additional arguments from a file (aka response files)
    63//! - [shadow-rs](https://crates.io/crates/shadow-rs) for generating `Command::long_version`
    64//! - [clap_mangen](https://crates.io/crates/clap_mangen) for generating man page source (roff)
    65//! - [clap_complete](https://crates.io/crates/clap_complete) for shell completion support
    66//! - [clap-i18n-richformatter](https://crates.io/crates/clap-i18n-richformatter) for i18n support with `clap::error::RichFormatter`
    67//!
    68//! CLI Helpers
    69//! - [clio](https://crates.io/crates/clio) for reading/writing to files specified as arguments
    70//! - [clap-verbosity-flag](https://crates.io/crates/clap-verbosity-flag)
    71//! - [clap-cargo](https://crates.io/crates/clap-cargo)
    72//! - [colorchoice-clap](https://crates.io/crates/colorchoice-clap)
    73//!
    74//! Testing
    75//! - [`trycmd`](https://crates.io/crates/trycmd):  Bulk snapshot testing
    76//! - [`snapbox`](https://crates.io/crates/snapbox):  Specialized snapshot testing
    77//! - [`assert_cmd`](https://crates.io/crates/assert_cmd) and [`assert_fs`](https://crates.io/crates/assert_fs): Customized testing
    78//!
    79//! Documentation:
    80//! - [Command-line Apps for Rust](https://rust-cli.github.io/book/index.html) book
    81//!
    82
    83#![doc(html_logo_url = "https://raw.githubusercontent.com/clap-rs/clap/master/assets/clap.png")]
    84#![cfg_attr(docsrs, feature(doc_cfg))]
    85#![forbid(unsafe_code)]
    86#![warn(missing_docs)]
    87#![warn(clippy::print_stderr)]
    88#![warn(clippy::print_stdout)]
    89
    90pub use clap_builder::*;
    91#[cfg(feature = "derive")]
    92#[doc(hidden)]
    93pub use clap_derive::{self, Args, Parser, Subcommand, ValueEnum};
    94
    95#[cfg(feature = "unstable-doc")]
    96pub mod _concepts;
    97#[cfg(feature = "unstable-doc")]
    98pub mod _cookbook;
    99#[cfg(feature = "unstable-doc")]
    100pub mod _derive;
    101#[cfg(feature = "unstable-doc")]
    102pub mod _faq;
    103#[cfg(feature = "unstable-doc")]
    104pub mod _features;
    105#[cfg(feature = "unstable-doc")]
    106pub mod _tutorial;
    107
    108#[doc = include_str!("../README.md")]
    109#[cfg(doctest)]
    110pub struct ReadmeDoctests;