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](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.64.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 #![cfg_attr(not(feature = "derive"), doc = " ```ignore")] 45 #![cfg_attr(feature = "derive", doc = " ```no_run")] 46 #![doc = include_str!("../examples/demo.rs")] 47 //! ``` 48 //! 49 //! And try it out: 50 #![doc = include_str!("../examples/demo.md")] 51 //! 52 //! See also the derive [tutorial][_derive::_tutorial] and [reference][_derive] 53 //! 54 //! ### Related Projects 55 //! 56 //! Augment clap: 57 //! - [wild](https://crates.io/crates/wild) for supporting wildcards (`*`) on Windows like you do Linux 58 //! - [argfile](https://crates.io/crates/argfile) for loading additional arguments from a file (aka response files) 59 //! - [shadow-rs](https://crates.io/crates/shadow-rs) for generating `Command::long_version` 60 //! - [clap_mangen](https://crates.io/crates/clap_mangen) for generating man page source (roff) 61 //! - [clap_complete](https://crates.io/crates/clap_complete) for shell completion support 62 //! 63 //! CLI Helpers 64 //! - [clap-verbosity-flag](https://crates.io/crates/clap-verbosity-flag) 65 //! - [clap-cargo](https://crates.io/crates/clap-cargo) 66 //! - [concolor-clap](https://crates.io/crates/concolor-clap) 67 //! 68 //! Testing 69 //! - [`trycmd`](https://crates.io/crates/trycmd): Bulk snapshot testing 70 //! - [`snapbox`](https://crates.io/crates/snapbox): Specialized snapshot testing 71 //! - [`assert_cmd`](https://crates.io/crates/assert_cmd) and [`assert_fs`](https://crates.io/crates/assert_fs): Customized testing 72 //! 73 //! Documentation: 74 //! - [Command-line Apps for Rust](https://rust-cli.github.io/book/index.html) book 75 //! 76 77 #![cfg_attr(docsrs, feature(doc_auto_cfg))] 78 #![doc(html_logo_url = "https://raw.githubusercontent.com/clap-rs/clap/master/assets/clap.png")] 79 #![warn( 80 missing_docs, 81 missing_debug_implementations, 82 missing_copy_implementations, 83 trivial_casts, 84 unused_allocation, 85 trivial_numeric_casts, 86 clippy::single_char_pattern 87 )] 88 #![forbid(unsafe_code)] 89 // HACK https://github.com/rust-lang/rust-clippy/issues/7290 90 #![allow(clippy::single_component_path_imports)] 91 #![allow(clippy::branches_sharing_code)] 92 // Doesn't allow for debug statements, etc to be unique 93 #![allow(clippy::if_same_then_else)] 94 // Breaks up parallelism that clarifies intent 95 #![allow(clippy::collapsible_else_if)] 96 97 #[cfg(not(feature = "std"))] 98 compile_error!("`std` feature is currently required to build `clap`"); 99 100 pub use crate::builder::ArgAction; 101 pub use crate::builder::Command; 102 pub use crate::builder::ValueHint; 103 pub use crate::builder::{Arg, ArgGroup}; 104 pub use crate::parser::ArgMatches; 105 pub use crate::util::color::ColorChoice; 106 pub use crate::util::Id; 107 108 /// Command Line Argument Parser Error 109 /// 110 /// See [`Command::error`] to create an error. 111 /// 112 /// [`Command::error`]: crate::Command::error 113 pub type Error = crate::error::Error<crate::error::DefaultFormatter>; 114 115 pub use crate::derive::{Args, CommandFactory, FromArgMatches, Parser, Subcommand, ValueEnum}; 116 117 #[cfg(feature = "derive")] 118 #[doc(hidden)] 119 pub use clap_derive::{self, *}; 120 121 #[cfg(feature = "unstable-doc")] 122 pub mod _cookbook; 123 #[cfg(feature = "unstable-doc")] 124 pub mod _derive; 125 #[cfg(feature = "unstable-doc")] 126 pub mod _faq; 127 #[cfg(feature = "unstable-doc")] 128 pub mod _features; 129 #[cfg(feature = "unstable-doc")] 130 pub mod _tutorial; 131 132 #[doc(hidden)] 133 pub mod __macro_refs { 134 #[cfg(any(feature = "derive", feature = "cargo"))] 135 #[doc(hidden)] 136 pub use once_cell; 137 } 138 139 #[macro_use] 140 #[allow(missing_docs)] 141 mod macros; 142 143 mod derive; 144 145 pub mod builder; 146 pub mod error; 147 pub mod parser; 148 149 mod mkeymap; 150 mod output; 151 mod util; 152 153 const INTERNAL_ERROR_MSG: &str = "Fatal internal error. Please consider filing a bug \ 154 report at https://github.com/clap-rs/clap/issues"; 155
