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

clap/
lib.rs
