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.0/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 //! - [cio](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 #![cfg_attr(docsrs, feature(doc_auto_cfg))]
82 #![doc(html_logo_url = "https://raw.githubusercontent.com/clap-rs/clap/master/assets/clap.png")]
83 #![warn(
84     missing_docs,
85     missing_debug_implementations,
86     missing_copy_implementations,
87     trivial_casts,
88     unused_allocation,
89     trivial_numeric_casts,
90     clippy::single_char_pattern
91 )]
92 #![forbid(unsafe_code)]
93 // HACK https://github.com/rust-lang/rust-clippy/issues/7290
94 #![allow(clippy::single_component_path_imports)]
95 #![allow(clippy::branches_sharing_code)]
96 // Doesn't allow for debug statements, etc to be unique
97 #![allow(clippy::if_same_then_else)]
98 // Breaks up parallelism that clarifies intent
99 #![allow(clippy::collapsible_else_if)]
100 
101 pub use clap_builder::*;
102 #[cfg(feature = "derive")]
103 #[doc(hidden)]
104 pub use clap_derive::{self, *};
105 
106 #[cfg(feature = "unstable-doc")]
107 pub mod _cookbook;
108 #[cfg(feature = "unstable-doc")]
109 pub mod _derive;
110 #[cfg(feature = "unstable-doc")]
111 pub mod _faq;
112 #[cfg(feature = "unstable-doc")]
113 pub mod _features;
114 #[cfg(feature = "unstable-doc")]
115 pub mod _tutorial;
116