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