Mirrors/clap
2
0
Fork 0
mirror of https://github.com/clap-rs/clap synced 2025-03-05 07:47:40 +00:00
Code Issues Projects Releases Packages Wiki Activity
clap/src/lib.rs

158 lines
5.7 KiB
Rust
Raw Normal View History

Update README for beta release
2020-03-02 09:52:15 +01:00
// Copyright ⓒ 2015-2016 Kevin B. Knapp and [`clap-rs` contributors](https://github.com/clap-rs/clap/graphs/contributors).
imp(arg_enum): enum declared with arg_enum returns [&'static str; #] instead of Vec
2016-01-31 08:03:09 -05:00
// Licensed under the MIT license
// (see LICENSE or <http://opensource.org/licenses/MIT>) All files in the project carrying such
// notice may not be copied, modified, or distributed except according to those terms.
docs: Move everything to docs.rs A couple of things happened when preparing to release 3.0 - We needed derive documentation - I had liked how serde handled theres - I had bad experiences finding things in structopt's documentation - The examples were broken and we needed tests - The examples seemed to follow a pattern of having tutorial content and cookbook content - We had been getting bug reports from people looking at master and thinking they were looking at what is currently released - We had gotten feedback to keep down the number of places that documentation was located From this, we went with a mix of docs.rs and github - We kept the number of content locations at 2 rather than 3 by not having an external site like serde - We rewrote the examples into explicit tutorials and cookbooks to align with the 4 styles of documentation - We could test our examples by running `console` code blocks with trycmd - Documentation was versioned and the README pointed to the last release This had downsides - The tutorials didn't have the code inlined - Users still had a hard time finding and navigating between the different forms of documentation - In practice, we were less likely to cross-link between the different types of documentation Moving to docs.rs would offer a lot of benefits, even if it is only designed for Rust-reference documentation and isn't good for Rust derive reference documentation, tutorials, cookbooks, etc. The big problem was keeping the examples tested to keep maintenance costs down. Maybe its just me but its easy to overlook - You can pull documentation from a file using `#[doc = "path"]` - Repeated doc attributes get concatenated rather than first or last writer winning Remember these when specifically thinking about Rust documentation made me realize that we could get everything into docs.rs. When doing this - Tutorial code got brought in as was one of the aims - We needed to split the lib documentation and the README to have all of the linking work. This allowed us to specialize them according to their rule (user vs contributor) - We needed to avoid users getting caught up in making a decision between Derive and Builder APIs so we put the focus on the derive API with links to the FAQ to help users decide when to use one or the other. - Improved cross-referencing between different parts of the documentation - Limited inline comments were added to example code - Introductory example code intentionally does not have teaching comments in it as its meant to give a flavor or sense of things and not meant to teach on its own. This is a first attempt. There will be a lot of room for further improvement. Current know downsides: - Content source is more split up for the tutorials This hopefully addresses #3189
2022-07-19 13:29:31 -05:00
//! > **Command Line Argument Parser for Rust**
//!
//! Quick Links:
//! - Derive [tutorial][_derive::_tutorial] and [reference][_derive]
//! - Builder [tutorial][_tutorial] and [reference](index.html)
//! - [Cookbook][_cookbook]
//! - [FAQ][_faq]
//! - [Discussions](https://github.com/clap-rs/clap/discussions)
//!
//! ## Aspirations
//!
//! - Out of the box, users get a polished CLI experience
//! - 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
//! - Flexible enough to port your existing CLI interface
//! - However, we won't necessarily streamline support for each use case
//! - Reasonable parse performance
//! - Resilient maintainership, including
//! - Willing to break compatibility rather than batching up breaking changes in large releases
//! - Leverage feature flags to keep to one active branch
//! - Being under [WG-CLI](https://github.com/rust-cli/team/) to increase the bus factor
//! - We follow semver and will wait about 6-9 months between major breaking changes
//! - We will support the last two minor Rust releases (MSRV, currently 1.56.1)
//!
//! While these aspirations can be at odds with fast build times and low binary
//! size, we will still strive to keep these reasonable for the flexibility you
//! get. Check out the
//! [argparse-benchmarks](https://github.com/rust-cli/argparse-benchmarks-rs) for
//! CLI parsers optimized for other use cases.
//!
//! ## Example
//!
//! Run
//! ```console
docs: reduce the need to guess
2022-07-19 22:32:42 +02:00
//! $ cargo add clap --features derive
docs: Move everything to docs.rs A couple of things happened when preparing to release 3.0 - We needed derive documentation - I had liked how serde handled theres - I had bad experiences finding things in structopt's documentation - The examples were broken and we needed tests - The examples seemed to follow a pattern of having tutorial content and cookbook content - We had been getting bug reports from people looking at master and thinking they were looking at what is currently released - We had gotten feedback to keep down the number of places that documentation was located From this, we went with a mix of docs.rs and github - We kept the number of content locations at 2 rather than 3 by not having an external site like serde - We rewrote the examples into explicit tutorials and cookbooks to align with the 4 styles of documentation - We could test our examples by running `console` code blocks with trycmd - Documentation was versioned and the README pointed to the last release This had downsides - The tutorials didn't have the code inlined - Users still had a hard time finding and navigating between the different forms of documentation - In practice, we were less likely to cross-link between the different types of documentation Moving to docs.rs would offer a lot of benefits, even if it is only designed for Rust-reference documentation and isn't good for Rust derive reference documentation, tutorials, cookbooks, etc. The big problem was keeping the examples tested to keep maintenance costs down. Maybe its just me but its easy to overlook - You can pull documentation from a file using `#[doc = "path"]` - Repeated doc attributes get concatenated rather than first or last writer winning Remember these when specifically thinking about Rust documentation made me realize that we could get everything into docs.rs. When doing this - Tutorial code got brought in as was one of the aims - We needed to split the lib documentation and the README to have all of the linking work. This allowed us to specialize them according to their rule (user vs contributor) - We needed to avoid users getting caught up in making a decision between Derive and Builder APIs so we put the focus on the derive API with links to the FAQ to help users decide when to use one or the other. - Improved cross-referencing between different parts of the documentation - Limited inline comments were added to example code - Introductory example code intentionally does not have teaching comments in it as its meant to give a flavor or sense of things and not meant to teach on its own. This is a first attempt. There will be a lot of room for further improvement. Current know downsides: - Content source is more split up for the tutorials This hopefully addresses #3189
2022-07-19 13:29:31 -05:00
//! ```
//! *(See also [feature flag reference][_features])*
//!
docs: Small tweak to lib docs
2022-07-19 15:54:01 -05:00
//! Then define your CLI in `main.rs`:
docs: Move everything to docs.rs A couple of things happened when preparing to release 3.0 - We needed derive documentation - I had liked how serde handled theres - I had bad experiences finding things in structopt's documentation - The examples were broken and we needed tests - The examples seemed to follow a pattern of having tutorial content and cookbook content - We had been getting bug reports from people looking at master and thinking they were looking at what is currently released - We had gotten feedback to keep down the number of places that documentation was located From this, we went with a mix of docs.rs and github - We kept the number of content locations at 2 rather than 3 by not having an external site like serde - We rewrote the examples into explicit tutorials and cookbooks to align with the 4 styles of documentation - We could test our examples by running `console` code blocks with trycmd - Documentation was versioned and the README pointed to the last release This had downsides - The tutorials didn't have the code inlined - Users still had a hard time finding and navigating between the different forms of documentation - In practice, we were less likely to cross-link between the different types of documentation Moving to docs.rs would offer a lot of benefits, even if it is only designed for Rust-reference documentation and isn't good for Rust derive reference documentation, tutorials, cookbooks, etc. The big problem was keeping the examples tested to keep maintenance costs down. Maybe its just me but its easy to overlook - You can pull documentation from a file using `#[doc = "path"]` - Repeated doc attributes get concatenated rather than first or last writer winning Remember these when specifically thinking about Rust documentation made me realize that we could get everything into docs.rs. When doing this - Tutorial code got brought in as was one of the aims - We needed to split the lib documentation and the README to have all of the linking work. This allowed us to specialize them according to their rule (user vs contributor) - We needed to avoid users getting caught up in making a decision between Derive and Builder APIs so we put the focus on the derive API with links to the FAQ to help users decide when to use one or the other. - Improved cross-referencing between different parts of the documentation - Limited inline comments were added to example code - Introductory example code intentionally does not have teaching comments in it as its meant to give a flavor or sense of things and not meant to teach on its own. This is a first attempt. There will be a lot of room for further improvement. Current know downsides: - Content source is more split up for the tutorials This hopefully addresses #3189
2022-07-19 13:29:31 -05:00
#![cfg_attr(not(feature = "derive"), doc = " ```ignore")]
#![cfg_attr(feature = "derive", doc = " ```no_run")]
#![doc = include_str!("../examples/demo.rs")]
//! ```
//!
docs: Small tweak to lib docs
2022-07-19 15:54:01 -05:00
//! And try it out:
docs: Move everything to docs.rs A couple of things happened when preparing to release 3.0 - We needed derive documentation - I had liked how serde handled theres - I had bad experiences finding things in structopt's documentation - The examples were broken and we needed tests - The examples seemed to follow a pattern of having tutorial content and cookbook content - We had been getting bug reports from people looking at master and thinking they were looking at what is currently released - We had gotten feedback to keep down the number of places that documentation was located From this, we went with a mix of docs.rs and github - We kept the number of content locations at 2 rather than 3 by not having an external site like serde - We rewrote the examples into explicit tutorials and cookbooks to align with the 4 styles of documentation - We could test our examples by running `console` code blocks with trycmd - Documentation was versioned and the README pointed to the last release This had downsides - The tutorials didn't have the code inlined - Users still had a hard time finding and navigating between the different forms of documentation - In practice, we were less likely to cross-link between the different types of documentation Moving to docs.rs would offer a lot of benefits, even if it is only designed for Rust-reference documentation and isn't good for Rust derive reference documentation, tutorials, cookbooks, etc. The big problem was keeping the examples tested to keep maintenance costs down. Maybe its just me but its easy to overlook - You can pull documentation from a file using `#[doc = "path"]` - Repeated doc attributes get concatenated rather than first or last writer winning Remember these when specifically thinking about Rust documentation made me realize that we could get everything into docs.rs. When doing this - Tutorial code got brought in as was one of the aims - We needed to split the lib documentation and the README to have all of the linking work. This allowed us to specialize them according to their rule (user vs contributor) - We needed to avoid users getting caught up in making a decision between Derive and Builder APIs so we put the focus on the derive API with links to the FAQ to help users decide when to use one or the other. - Improved cross-referencing between different parts of the documentation - Limited inline comments were added to example code - Introductory example code intentionally does not have teaching comments in it as its meant to give a flavor or sense of things and not meant to teach on its own. This is a first attempt. There will be a lot of room for further improvement. Current know downsides: - Content source is more split up for the tutorials This hopefully addresses #3189
2022-07-19 13:29:31 -05:00
#![doc = include_str!("../examples/demo.md")]
//!
//! See also the derive [tutorial][_derive::_tutorial] and [reference][_derive]
//!
//! ### Related Projects
//!
//! Augment clap:
//! - [wild](https://crates.io/crates/wild) for supporting wildcards (`*`) on Windows like you do Linux
//! - [argfile](https://crates.io/crates/argfile) for loading additional arguments from a file (aka response files)
//! - [shadow-rs](https://crates.io/crates/shadow-rs) for generating `Command::long_version`
//! - [clap_mangen](https://crates.io/crates/clap_mangen) for generating man page source (roff)
//! - [clap_complete](https://crates.io/crates/clap_complete) for shell completion support
//!
//! CLI Helpers
//! - [clap-verbosity-flag](https://crates.io/crates/clap-verbosity-flag)
//! - [clap-cargo](https://crates.io/crates/clap-cargo)
//! - [concolor-clap](https://crates.io/crates/concolor-clap)
//!
//! Testing
//! - [`trycmd`](https://crates.io/crates/trycmd): Bulk snapshot testing
//! - [`snapbox`](https://crates.io/crates/snapbox): Specialized snapshot testing
//! - [`assert_cmd`](https://crates.io/crates/assert_cmd) and [`assert_fs`](https://crates.io/crates/assert_fs): Customized testing
//!
//! Documentation:
//! - [Command-line Apps for Rust](https://rust-cli.github.io/book/index.html) book
//!
docs: Show features in docs.rs Confirmed this works with [`argfile`](https://docs.rs/argfile/latest/argfile/) And then running in clap ``` $ RUSTDOCFLAGS="--cfg docsrs" cargo +nightly doc --all-features ``` They now show up!
2021-12-16 10:36:41 -06:00
#![cfg_attr(docsrs, feature(doc_auto_cfg))]
docs: Add back in logo
2021-12-07 16:22:14 -06:00
#![doc(html_logo_url = "https://raw.githubusercontent.com/clap-rs/clap/master/assets/clap.png")]
chore: Only error for warnings in CI This makes it easier for developers to iterate, not having to stop to write docs just to get things building.
2021-12-06 11:03:12 -06:00
#![warn(
style: rustfmt run
2019-04-05 15:51:22 -04:00
missing_docs,
missing_debug_implementations,
missing_copy_implementations,
trivial_casts,
unused_allocation,
style: prefer 'char' to 'str' for single character patterns
2022-01-04 07:20:03 +00:00
trivial_numeric_casts,
clippy::single_char_pattern
style: rustfmt run
2019-04-05 15:51:22 -04:00
)]
Forbid all unsafe code.
2020-08-20 18:38:40 -04:00
#![forbid(unsafe_code)]
chore: Remove the TODO chaff The intent is to make stand out more the important technical debt hidden in comments.
2021-12-22 09:52:02 -06:00
// HACK https://github.com/rust-lang/rust-clippy/issues/7290
Fix clippy lint
2021-06-17 19:19:56 +01:00
#![allow(clippy::single_component_path_imports)]
chore: Silence bad clippy lint While in some cases "branches-sharing-code" might catch bugs, it overall encourages a form of DRY that leads to bad code. In this specific case, it is relying on the implementation detail of the formatting of each branch being the same. If the `'` wasn't part of it, I could see it being about a shared `?` to go with the shared start of the question.
2021-10-23 10:06:19 -05:00
#![allow(clippy::branches_sharing_code)]
fix: Clarify short rejection in debug
2022-01-04 09:00:13 -06:00
// Doesn't allow for debug statements, etc to be unique
#![allow(clippy::if_same_then_else)]
style: Make clippy happy
2022-07-28 15:11:28 -05:00
// Breaks up parallelism that clarifies intent
#![allow(clippy::collapsible_else_if)]
tests: adds tests for posix compatible conflicts
2015-08-19 21:44:25 -04:00
Update lib.rs
2020-02-02 02:02:10 +01:00
#[cfg(not(feature = "std"))]
Remove _some_ of pubs
2020-03-19 10:17:52 +03:00
compile_error!("`std` feature is currently required to build `clap`");
Update lib.rs
2020-02-02 02:02:10 +01:00
fix(builder): Make it easier to discover/access ArgAction
2022-06-03 12:11:45 -05:00
pub use crate::builder::ArgAction;
feat: Expose builder/parser modules The top-level API for clap is getting a bit bloated. By exposing these modules, we'll be able to continue to add new, less commonly used types while keeping the main API focused.
2022-05-12 05:03:26 -05:00
pub use crate::builder::Command;
fix: Soft-deprecate several items within the root
2022-05-12 05:07:54 -05:00
pub use crate::builder::{Arg, ArgGroup};
refactor(error): Prepare for splitting mod
2022-02-02 16:06:23 -06:00
pub use crate::error::Error;
fix: Soft-deprecate several items within the root
2022-05-12 05:07:54 -05:00
pub use crate::parser::ArgMatches;
Add DisableColoredHelp setting to improve flexibility (clap-rs/clap#2956) Until we have a modular help generator that can be configured and/or authored by the users themselves as part of #2914, we will provide the flexibility of turning off colored help messages but still wanting colored error messages. This flexibility was available before #2845 and @dbrgn immediately noticed it and requested it back to which I agree. This was also suggested by Josh in [here](https://github.com/clap-rs/clap/issues/2806#issuecomment-933877438)
2021-10-27 22:01:04 +01:00
#[cfg(feature = "color")]
pub use crate::util::color::ColorChoice;
fix(clap): Allow disabling color with debug
2022-04-22 12:19:43 -05:00
#[cfg(not(feature = "color"))]
#[allow(unused_imports)]
pub(crate) use crate::util::color::ColorChoice;
Allow replacing input on the fly
2020-02-14 17:22:01 +01:00
fix(derive): Clarify ArgEnum as ValueEnum We aren't enumerating arguments but values for an argument, so the name should reflect that. This will be important as part of #1807 when we have more specific attribute names.
2022-06-08 10:56:57 -05:00
pub use crate::derive::{Args, CommandFactory, FromArgMatches, Parser, Subcommand, ValueEnum};
Add derive traits only if derive feature is enabled
2020-08-11 16:30:02 +02:00
docs: Update App references to Command
2022-02-11 21:48:29 -06:00
#[allow(deprecated)]
fix!: Pull AppSettings out of API Part of #3021
2022-07-22 15:50:13 -05:00
pub use crate::builder::{PossibleValue, ValueHint};
fix: Soft-deprecate several items within the root
2022-05-12 05:07:54 -05:00
pub use crate::error::{ErrorKind, Result};
fix(parser): Deprecate `value_of` and friends
2022-05-24 10:16:50 -05:00
#[allow(deprecated)]
fix!: Remove ArgMatches::*value* functions
2022-07-21 13:47:06 -05:00
pub use crate::parser::{Indices, ValueSource};
docs: Update App references to Command
2022-02-11 21:48:29 -06:00
refactor(Derives): changes the derive traits for the clap_derive crate
2018-07-13 11:36:53 -04:00
#[cfg(feature = "derive")]
Remove unneeded cfg_attr
2020-09-24 13:41:37 +02:00
#[doc(hidden)]
Default value for `default_value` (yeah, sounds awkward)
2019-12-29 18:53:12 +03:00
pub use clap_derive::{self, *};
docs: Move everything to docs.rs A couple of things happened when preparing to release 3.0 - We needed derive documentation - I had liked how serde handled theres - I had bad experiences finding things in structopt's documentation - The examples were broken and we needed tests - The examples seemed to follow a pattern of having tutorial content and cookbook content - We had been getting bug reports from people looking at master and thinking they were looking at what is currently released - We had gotten feedback to keep down the number of places that documentation was located From this, we went with a mix of docs.rs and github - We kept the number of content locations at 2 rather than 3 by not having an external site like serde - We rewrote the examples into explicit tutorials and cookbooks to align with the 4 styles of documentation - We could test our examples by running `console` code blocks with trycmd - Documentation was versioned and the README pointed to the last release This had downsides - The tutorials didn't have the code inlined - Users still had a hard time finding and navigating between the different forms of documentation - In practice, we were less likely to cross-link between the different types of documentation Moving to docs.rs would offer a lot of benefits, even if it is only designed for Rust-reference documentation and isn't good for Rust derive reference documentation, tutorials, cookbooks, etc. The big problem was keeping the examples tested to keep maintenance costs down. Maybe its just me but its easy to overlook - You can pull documentation from a file using `#[doc = "path"]` - Repeated doc attributes get concatenated rather than first or last writer winning Remember these when specifically thinking about Rust documentation made me realize that we could get everything into docs.rs. When doing this - Tutorial code got brought in as was one of the aims - We needed to split the lib documentation and the README to have all of the linking work. This allowed us to specialize them according to their rule (user vs contributor) - We needed to avoid users getting caught up in making a decision between Derive and Builder APIs so we put the focus on the derive API with links to the FAQ to help users decide when to use one or the other. - Improved cross-referencing between different parts of the documentation - Limited inline comments were added to example code - Introductory example code intentionally does not have teaching comments in it as its meant to give a flavor or sense of things and not meant to teach on its own. This is a first attempt. There will be a lot of room for further improvement. Current know downsides: - Content source is more split up for the tutorials This hopefully addresses #3189
2022-07-19 13:29:31 -05:00
#[cfg(feature = "unstable-doc")]
pub mod _cookbook;
#[cfg(feature = "unstable-doc")]
pub mod _derive;
#[cfg(feature = "unstable-doc")]
pub mod _faq;
#[cfg(feature = "unstable-doc")]
pub mod _features;
#[cfg(feature = "unstable-doc")]
pub mod _tutorial;
Make caching in crate_authors! actually work
2020-08-21 08:21:21 +03:00
#[doc(hidden)]
refactor: Put once_cell reexport into __macro_refs When upgrading our company projects from clap 3.1 to clap 3.2 I had to fix several references to `clap::lazy_init`. People are not supposed to do that, but that's hard to enforce. Hope placing `once_cell` reexport into `__macro_refs` prevent at least some of the such issues in the future.
2022-06-26 00:44:58 +01:00
pub mod __macro_refs {
#[cfg(any(feature = "derive", feature = "cargo"))]
#[doc(hidden)]
pub use once_cell;
}
refactor(Derives): changes the derive traits for the clap_derive crate
2018-07-13 11:36:53 -04:00
perf(usage): remove compiler warnings and dedup some code
2015-04-10 11:40:08 -04:00
#[macro_use]
fix subcommand is private bug
2020-01-01 23:27:44 +05:30
#[allow(missing_docs)]
Allow separate derives, but do not give examples
2020-05-15 09:51:36 +02:00
mod macros;
WIP
2018-07-26 20:15:47 +05:00
Allow separate derives, but do not give examples
2020-05-15 09:51:36 +02:00
mod derive;
Extract subcommands into separate trait
2020-02-08 22:36:00 +03:00
feat: Expose builder/parser modules The top-level API for clap is getting a bit bloated. By exposing these modules, we'll be able to continue to add new, less commonly used types while keeping the main API focused.
2022-05-12 05:03:26 -05:00
pub mod builder;
refactor(error): Prepare for splitting mod
2022-02-02 16:06:23 -06:00
pub mod error;
feat: Expose builder/parser modules The top-level API for clap is getting a bit bloated. By exposing these modules, we'll be able to continue to add new, less commonly used types while keeping the main API focused.
2022-05-12 05:03:26 -05:00
pub mod parser;
refactor(error): Prepare for splitting mod
2022-02-02 16:06:23 -06:00
WIP changing macros into MKeyMap calls
2018-07-19 15:50:47 +03:00
mod mkeymap;
refactor(Arg): changes Arg::short to accept a char instead of &str Closes #1303
2018-07-23 15:09:42 -04:00
mod output;
refactor(Modules): moves the modules around into a more logical order to make contribution easier
2018-06-12 11:42:03 -04:00
mod util;
feat(v2): implementing the base of 2.x This commit implements the base changes for clap 2.x
2016-01-11 03:59:56 -05:00
refactor: clippy run
2018-11-14 12:12:34 -05:00
const INTERNAL_ERROR_MSG: &str = "Fatal internal error. Please consider filing a bug \
Refactor clap_generate
2020-02-05 11:04:59 +01:00
report at https://github.com/clap-rs/clap/issues";
refactor: clippy run
2018-11-14 12:12:34 -05:00
const INVALID_UTF8: &str = "unexpected invalid UTF-8 code point";
Reference in a new issue Copy permalink