Mirrors/clap
2
0
Fork 0
mirror of https://github.com/clap-rs/clap synced 2024-12-14 23:02:31 +00:00
Code Issues Projects Releases Packages Wiki Activity
clap/src/lib.rs

233 lines
7.8 KiB
Rust
Raw Normal View History

Update README for beta release
2020-03-02 08:52:15 +00: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 13:03:09 +00: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 18:29:31 +00: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 20:32:42 +00: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 18:29:31 +00:00
//! ```
//! *(See also [feature flag reference][_features])*
//!
//! Then in `main.rs`:
#![cfg_attr(not(feature = "derive"), doc = " ```ignore")]
#![cfg_attr(feature = "derive", doc = " ```no_run")]
#![doc = include_str!("../examples/demo.rs")]
//! ```
//!
//! Then try it out:
#![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 16:36:41 +00:00
#![cfg_attr(docsrs, feature(doc_auto_cfg))]
docs: Add back in logo
2021-12-07 22:22:14 +00: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 17:03:12 +00:00
#![warn(
style: rustfmt run
2019-04-05 19:51:22 +00: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 19:51:22 +00:00
)]
Forbid all unsafe code.
2020-08-20 22:38:40 +00: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 15:52:02 +00:00
// HACK https://github.com/rust-lang/rust-clippy/issues/7290
Fix clippy lint
2021-06-17 18:19:56 +00: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 15:06:19 +00:00
#![allow(clippy::branches_sharing_code)]
fix: Clarify short rejection in debug
2022-01-04 15:00:13 +00:00
// Doesn't allow for debug statements, etc to be unique
#![allow(clippy::if_same_then_else)]
tests: adds tests for posix compatible conflicts
2015-08-20 01:44:25 +00:00
Update lib.rs
2020-02-02 01:02:10 +00:00
#[cfg(not(feature = "std"))]
Remove _some_ of pubs
2020-03-19 07:17:52 +00:00
compile_error!("`std` feature is currently required to build `clap`");
Update lib.rs
2020-02-02 01:02:10 +00:00
fix(builder): Make it easier to discover/access ArgAction
2022-06-03 17:11:45 +00: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 10:03:26 +00:00
pub use crate::builder::Command;
fix: Soft-deprecate several items within the root
2022-05-12 10:07:54 +00:00
pub use crate::builder::{Arg, ArgGroup};
refactor(error): Prepare for splitting mod
2022-02-02 22:06:23 +00:00
pub use crate::error::Error;
fix: Soft-deprecate several items within the root
2022-05-12 10:07:54 +00: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 21:01:04 +00:00
#[cfg(feature = "color")]
pub use crate::util::color::ColorChoice;
fix(clap): Allow disabling color with debug
2022-04-22 17:19:43 +00:00
#[cfg(not(feature = "color"))]
#[allow(unused_imports)]
pub(crate) use crate::util::color::ColorChoice;
Allow replacing input on the fly
2020-02-14 16:22:01 +00: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 15:56:57 +00:00
pub use crate::derive::{Args, CommandFactory, FromArgMatches, Parser, Subcommand, ValueEnum};
Add derive traits only if derive feature is enabled
2020-08-11 14:30:02 +00:00
docs: Update App references to Command
2022-02-12 03:48:29 +00:00
#[allow(deprecated)]
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 10:03:26 +00:00
pub use crate::builder::App;
fix: Soft-deprecate several items within the root
2022-05-12 10:07:54 +00:00
pub use crate::builder::{AppFlags, AppSettings, ArgFlags, ArgSettings, PossibleValue, ValueHint};
pub use crate::error::{ErrorKind, Result};
fix(parser): Deprecate `value_of` and friends
2022-05-24 15:16:50 +00:00
#[allow(deprecated)]
fix: Soft-deprecate several items within the root
2022-05-12 10:07:54 +00:00
pub use crate::parser::{Indices, OsValues, ValueSource, Values};
docs: Update App references to Command
2022-02-12 03:48:29 +00:00
refactor(Arg): changes Arg::short to accept a char instead of &str Closes #1303
2018-07-23 19:09:42 +00:00
#[cfg(feature = "yaml")]
Remove unneeded cfg_attr
2020-09-24 11:41:37 +00:00
#[doc(hidden)]
fix: Allow people to opt-in to deprecations This adds a new `Cargo.toml` feature named `deprecated` that opts controls whether deprecation warnings show up. This is starting off as non-default though that may change (see below). Benefits - Allows a staged rollout so a smaller subset of users see new deprecations and can report their experience with them before everyone sees them. For example, this reduces the number of people who have to deal with #3822. - This allows people to defer responding to each new batch of deprecations and instead do it at once. This means we should reconsider #3616. The one risk is people who don't follow blog posts and guides having a harder time upgrading to the next breaking release without the warnings on by default. For these users, we reserve the right to make the `deprecated` feature `default`. This is most likely to happen in a minor release that is released in conjunction with the next major release (e.g. when releasing 4.0.0, we release a 3.3.0 that enables deprecations by default). By using a feature, users can still disable this if they want. Thanks @joshtriplett for the idea
2022-06-14 14:54:41 +00:00
#[cfg_attr(
feature = "deprecated",
deprecated(
since = "3.0.0",
note = "Deprecated in Issue #3087, maybe clap::Parser would fit your use case?"
)
docs: Clean up deprecations
2021-11-23 16:11:02 +00:00
)]
docs: Hide items deprecated in 3.0.0 We left them in the docs for a period of time to help people find docs for code that was still in use. Balancing that with the need for clean docs, it seems like 3.1 is an appropriate time to mark them hidden in the docs.
2022-02-12 00:42:26 +00:00
#[doc(hidden)]
refactor(Arg): changes Arg::short to accept a char instead of &str Closes #1303
2018-07-23 19:09:42 +00:00
pub use yaml_rust::YamlLoader;
Initial commit v0.0.3
2015-02-25 13:37:25 +00:00
refactor(Derives): changes the derive traits for the clap_derive crate
2018-07-13 15:36:53 +00:00
#[cfg(feature = "derive")]
Remove unneeded cfg_attr
2020-09-24 11:41:37 +00:00
#[doc(hidden)]
Default value for `default_value` (yeah, sounds awkward)
2019-12-29 15:53:12 +00:00
pub use clap_derive::{self, *};
fix: Rename IntoApp to CommandFactory This is part of the `App` rename. Previously, I was concerned about not being able to deprecate For backwards compatibility, we still expose the `IntoApp` name.
2022-02-14 22:09:38 +00:00
/// Deprecated, replaced with [`CommandFactory`]
fix: Allow people to opt-in to deprecations This adds a new `Cargo.toml` feature named `deprecated` that opts controls whether deprecation warnings show up. This is starting off as non-default though that may change (see below). Benefits - Allows a staged rollout so a smaller subset of users see new deprecations and can report their experience with them before everyone sees them. For example, this reduces the number of people who have to deal with #3822. - This allows people to defer responding to each new batch of deprecations and instead do it at once. This means we should reconsider #3616. The one risk is people who don't follow blog posts and guides having a harder time upgrading to the next breaking release without the warnings on by default. For these users, we reserve the right to make the `deprecated` feature `default`. This is most likely to happen in a minor release that is released in conjunction with the next major release (e.g. when releasing 4.0.0, we release a 3.3.0 that enables deprecations by default). By using a feature, users can still disable this if they want. Thanks @joshtriplett for the idea
2022-06-14 14:54:41 +00:00
#[cfg_attr(
feature = "deprecated",
deprecated(since = "3.0.0", note = "Replaced with `CommandFactory`")
)]
fix: Rename IntoApp to CommandFactory This is part of the `App` rename. Previously, I was concerned about not being able to deprecate For backwards compatibility, we still expose the `IntoApp` name.
2022-02-14 22:09:38 +00:00
pub use CommandFactory as IntoApp;
fix(derive): Smooth out transition for structopt Adding in a `StructOpt` derive with `structopt` attributes, with deprecation notices. Unofrtunately, not as many deprecation warnings as I would like. Apparently, you can't do them for a `use` of a derive? I also wanted to inject code that would trigger a deprecation notice for attributes but that would require enough of a refactor that I didn't consider it worth it. We are at least providing a transition window even if it means we'll have to remvoe it next major release without a deprecation warning.
2021-12-03 02:18:33 +00:00
/// Deprecated, replaced with [`Parser`]
fix: Allow people to opt-in to deprecations This adds a new `Cargo.toml` feature named `deprecated` that opts controls whether deprecation warnings show up. This is starting off as non-default though that may change (see below). Benefits - Allows a staged rollout so a smaller subset of users see new deprecations and can report their experience with them before everyone sees them. For example, this reduces the number of people who have to deal with #3822. - This allows people to defer responding to each new batch of deprecations and instead do it at once. This means we should reconsider #3616. The one risk is people who don't follow blog posts and guides having a harder time upgrading to the next breaking release without the warnings on by default. For these users, we reserve the right to make the `deprecated` feature `default`. This is most likely to happen in a minor release that is released in conjunction with the next major release (e.g. when releasing 4.0.0, we release a 3.3.0 that enables deprecations by default). By using a feature, users can still disable this if they want. Thanks @joshtriplett for the idea
2022-06-14 14:54:41 +00:00
#[cfg_attr(
feature = "deprecated",
deprecated(since = "3.0.0", note = "Replaced with `Parser`")
)]
docs: Hide items deprecated in 3.0.0 We left them in the docs for a period of time to help people find docs for code that was still in use. Balancing that with the need for clean docs, it seems like 3.1 is an appropriate time to mark them hidden in the docs.
2022-02-12 00:42:26 +00:00
#[doc(hidden)]
fix(derive): Smooth out transition for structopt Adding in a `StructOpt` derive with `structopt` attributes, with deprecation notices. Unofrtunately, not as many deprecation warnings as I would like. Apparently, you can't do them for a `use` of a derive? I also wanted to inject code that would trigger a deprecation notice for attributes but that would require enough of a refactor that I didn't consider it worth it. We are at least providing a transition window even if it means we'll have to remvoe it next major release without a deprecation warning.
2021-12-03 02:18:33 +00:00
pub use Parser as StructOpt;
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 15:56:57 +00:00
/// Deprecated, replaced with [`ValueEnum`]
fix: Allow people to opt-in to deprecations This adds a new `Cargo.toml` feature named `deprecated` that opts controls whether deprecation warnings show up. This is starting off as non-default though that may change (see below). Benefits - Allows a staged rollout so a smaller subset of users see new deprecations and can report their experience with them before everyone sees them. For example, this reduces the number of people who have to deal with #3822. - This allows people to defer responding to each new batch of deprecations and instead do it at once. This means we should reconsider #3616. The one risk is people who don't follow blog posts and guides having a harder time upgrading to the next breaking release without the warnings on by default. For these users, we reserve the right to make the `deprecated` feature `default`. This is most likely to happen in a minor release that is released in conjunction with the next major release (e.g. when releasing 4.0.0, we release a 3.3.0 that enables deprecations by default). By using a feature, users can still disable this if they want. Thanks @joshtriplett for the idea
2022-06-14 14:54:41 +00:00
#[cfg_attr(
feature = "deprecated",
deprecated(since = "3.2.0", note = "Replaced with `ValueEnum`")
)]
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 15:56:57 +00:00
pub use ValueEnum as ArgEnum;
fix(derive): Smooth out transition for structopt Adding in a `StructOpt` derive with `structopt` attributes, with deprecation notices. Unofrtunately, not as many deprecation warnings as I would like. Apparently, you can't do them for a `use` of a derive? I also wanted to inject code that would trigger a deprecation notice for attributes but that would require enough of a refactor that I didn't consider it worth it. We are at least providing a transition window even if it means we'll have to remvoe it next major release without a deprecation warning.
2021-12-03 02:18:33 +00:00
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 18:29:31 +00: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 05:21:21 +00: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-25 23:44:58 +00: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 15:36:53 +00:00
perf(usage): remove compiler warnings and dedup some code
2015-04-10 15:40:08 +00:00
#[macro_use]
fix subcommand is private bug
2020-01-01 17:57:44 +00:00
#[allow(missing_docs)]
Allow separate derives, but do not give examples
2020-05-15 07:51:36 +00:00
mod macros;
WIP
2018-07-26 15:15:47 +00:00
Allow separate derives, but do not give examples
2020-05-15 07:51:36 +00:00
mod derive;
Extract subcommands into separate trait
2020-02-08 19:36:00 +00:00
regex: Introduce convenience Cow-wrapper RegexRef As previously discussed on [GitHub], this commit introduces a Cow-like wrapper RegexRef to enable both `Regex` as well as `&Regex` as arguments. It also introduces a new module in the `build:arg` path to remove clutter from the main module. For more information see #2073. [GitHub]: https://github.com/clap-rs/clap/pull/2073#issuecomment-674442310
2020-08-26 15:49:54 +00:00
#[cfg(feature = "regex")]
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 10:03:26 +00:00
pub use crate::builder::RegexRef;
regex: Introduce convenience Cow-wrapper RegexRef As previously discussed on [GitHub], this commit introduces a Cow-like wrapper RegexRef to enable both `Regex` as well as `&Regex` as arguments. It also introduces a new module in the `build:arg` path to remove clutter from the main module. For more information see #2073. [GitHub]: https://github.com/clap-rs/clap/pull/2073#issuecomment-674442310
2020-08-26 15:49:54 +00: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 10:03:26 +00:00
pub mod builder;
refactor(error): Prepare for splitting mod
2022-02-02 22:06:23 +00: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 10:03:26 +00:00
pub mod parser;
refactor(error): Prepare for splitting mod
2022-02-02 22:06:23 +00:00
WIP changing macros into MKeyMap calls
2018-07-19 12:50:47 +00:00
mod mkeymap;
refactor(Arg): changes Arg::short to accept a char instead of &str Closes #1303
2018-07-23 19:09:42 +00:00
mod output;
refactor(Modules): moves the modules around into a more logical order to make contribution easier
2018-06-12 15:42:03 +00:00
mod util;
feat(v2): implementing the base of 2.x This commit implements the base changes for clap 2.x
2016-01-11 08:59:56 +00:00
refactor: clippy run
2018-11-14 17:12:34 +00:00
const INTERNAL_ERROR_MSG: &str = "Fatal internal error. Please consider filing a bug \
Refactor clap_generate
2020-02-05 10:04:59 +00:00
report at https://github.com/clap-rs/clap/issues";
refactor: clippy run
2018-11-14 17:12:34 +00:00
const INVALID_UTF8: &str = "unexpected invalid UTF-8 code point";
fix: Ease clap2->clap3 migration with deprecations - `App::with_defaults` was not included since that has been deprecated since 2.14 - `App::args_from_usage` does not have a close enough parallel in the new API, as far as I could tell - `ArgMatches::usage` cannot have a thin wrapper around `App::generate_usage`. - `App::write_*`: getting lazy, didn't seem like high value functions - Any `Settings` (some things need to be figured out here) This is a part of #2617
2021-08-18 15:53:05 +00:00
docs: Update App references to Command
2022-02-12 03:48:29 +00:00
/// Deprecated, replaced with [`Command::new`], unless you were looking for [Subcommand]
fix: Allow people to opt-in to deprecations This adds a new `Cargo.toml` feature named `deprecated` that opts controls whether deprecation warnings show up. This is starting off as non-default though that may change (see below). Benefits - Allows a staged rollout so a smaller subset of users see new deprecations and can report their experience with them before everyone sees them. For example, this reduces the number of people who have to deal with #3822. - This allows people to defer responding to each new batch of deprecations and instead do it at once. This means we should reconsider #3616. The one risk is people who don't follow blog posts and guides having a harder time upgrading to the next breaking release without the warnings on by default. For these users, we reserve the right to make the `deprecated` feature `default`. This is most likely to happen in a minor release that is released in conjunction with the next major release (e.g. when releasing 4.0.0, we release a 3.3.0 that enables deprecations by default). By using a feature, users can still disable this if they want. Thanks @joshtriplett for the idea
2022-06-14 14:54:41 +00:00
#[cfg_attr(
feature = "deprecated",
deprecated(
since = "3.0.0",
note = "Replaced with `Command::new` unless you intended the `Subcommand` trait"
)
docs: Clarify deprecation message for `SubCommand` Only `SubCommand` is deprecated, not `Subcommand`. This new deprecation message mentions this ambiguity. Resolves #3147.
2021-12-11 22:47:08 +00:00
)]
docs: Hide items deprecated in 3.0.0 We left them in the docs for a period of time to help people find docs for code that was still in use. Balancing that with the need for clean docs, it seems like 3.1 is an appropriate time to mark them hidden in the docs.
2022-02-12 00:42:26 +00:00
#[doc(hidden)]
fix: Ease clap2->clap3 migration with deprecations - `App::with_defaults` was not included since that has been deprecated since 2.14 - `App::args_from_usage` does not have a close enough parallel in the new API, as far as I could tell - `ArgMatches::usage` cannot have a thin wrapper around `App::generate_usage`. - `App::write_*`: getting lazy, didn't seem like high value functions - Any `Settings` (some things need to be figured out here) This is a part of #2617
2021-08-18 15:53:05 +00:00
#[derive(Debug, Copy, Clone)]
pub struct SubCommand {}
docs: Clean up deprecations
2021-11-23 16:11:02 +00:00
#[allow(deprecated)]
fix: Ease clap2->clap3 migration with deprecations - `App::with_defaults` was not included since that has been deprecated since 2.14 - `App::args_from_usage` does not have a close enough parallel in the new API, as far as I could tell - `ArgMatches::usage` cannot have a thin wrapper around `App::generate_usage`. - `App::write_*`: getting lazy, didn't seem like high value functions - Any `Settings` (some things need to be figured out here) This is a part of #2617
2021-08-18 15:53:05 +00:00
impl SubCommand {
docs: Update App references to Command
2022-02-12 03:48:29 +00:00
/// Deprecated, replaced with [`Command::new`].
docs: Clarify deprecation message for `SubCommand` Only `SubCommand` is deprecated, not `Subcommand`. This new deprecation message mentions this ambiguity. Resolves #3147.
2021-12-11 22:47:08 +00:00
/// Did you mean Subcommand (lower-case c)?
fix: Allow people to opt-in to deprecations This adds a new `Cargo.toml` feature named `deprecated` that opts controls whether deprecation warnings show up. This is starting off as non-default though that may change (see below). Benefits - Allows a staged rollout so a smaller subset of users see new deprecations and can report their experience with them before everyone sees them. For example, this reduces the number of people who have to deal with #3822. - This allows people to defer responding to each new batch of deprecations and instead do it at once. This means we should reconsider #3616. The one risk is people who don't follow blog posts and guides having a harder time upgrading to the next breaking release without the warnings on by default. For these users, we reserve the right to make the `deprecated` feature `default`. This is most likely to happen in a minor release that is released in conjunction with the next major release (e.g. when releasing 4.0.0, we release a 3.3.0 that enables deprecations by default). By using a feature, users can still disable this if they want. Thanks @joshtriplett for the idea
2022-06-14 14:54:41 +00:00
#[cfg_attr(
feature = "deprecated",
deprecated(since = "3.0.0", note = "Replaced with `Command::new`")
)]
docs: Hide items deprecated in 3.0.0 We left them in the docs for a period of time to help people find docs for code that was still in use. Balancing that with the need for clean docs, it seems like 3.1 is an appropriate time to mark them hidden in the docs.
2022-02-12 00:42:26 +00:00
#[doc(hidden)]
fix: Ease clap2->clap3 migration with deprecations - `App::with_defaults` was not included since that has been deprecated since 2.14 - `App::args_from_usage` does not have a close enough parallel in the new API, as far as I could tell - `ArgMatches::usage` cannot have a thin wrapper around `App::generate_usage`. - `App::write_*`: getting lazy, didn't seem like high value functions - Any `Settings` (some things need to be figured out here) This is a part of #2617
2021-08-18 15:53:05 +00:00
pub fn with_name<'help>(name: &str) -> App<'help> {
docs: Update App references to Command
2022-02-12 03:48:29 +00:00
Command::new(name)
fix: Ease clap2->clap3 migration with deprecations - `App::with_defaults` was not included since that has been deprecated since 2.14 - `App::args_from_usage` does not have a close enough parallel in the new API, as far as I could tell - `ArgMatches::usage` cannot have a thin wrapper around `App::generate_usage`. - `App::write_*`: getting lazy, didn't seem like high value functions - Any `Settings` (some things need to be figured out here) This is a part of #2617
2021-08-18 15:53:05 +00:00
}
docs: Clarify deprecations
2021-12-08 17:11:26 +00:00
/// Deprecated in [Issue #3087](https://github.com/clap-rs/clap/issues/3087), maybe [`clap::Parser`][crate::Parser] would fit your use case?
fix: Ease clap2->clap3 migration with deprecations - `App::with_defaults` was not included since that has been deprecated since 2.14 - `App::args_from_usage` does not have a close enough parallel in the new API, as far as I could tell - `ArgMatches::usage` cannot have a thin wrapper around `App::generate_usage`. - `App::write_*`: getting lazy, didn't seem like high value functions - Any `Settings` (some things need to be figured out here) This is a part of #2617
2021-08-18 15:53:05 +00:00
#[cfg(feature = "yaml")]
fix: Allow people to opt-in to deprecations This adds a new `Cargo.toml` feature named `deprecated` that opts controls whether deprecation warnings show up. This is starting off as non-default though that may change (see below). Benefits - Allows a staged rollout so a smaller subset of users see new deprecations and can report their experience with them before everyone sees them. For example, this reduces the number of people who have to deal with #3822. - This allows people to defer responding to each new batch of deprecations and instead do it at once. This means we should reconsider #3616. The one risk is people who don't follow blog posts and guides having a harder time upgrading to the next breaking release without the warnings on by default. For these users, we reserve the right to make the `deprecated` feature `default`. This is most likely to happen in a minor release that is released in conjunction with the next major release (e.g. when releasing 4.0.0, we release a 3.3.0 that enables deprecations by default). By using a feature, users can still disable this if they want. Thanks @joshtriplett for the idea
2022-06-14 14:54:41 +00:00
#[cfg_attr(
feature = "deprecated",
deprecated(
since = "3.0.0",
note = "Deprecated in Issue #3087, maybe clap::Parser would fit your use case?"
)
fix: Deprecate YAML API Fixes #9
2021-11-18 20:27:21 +00:00
)]
docs: Hide items deprecated in 3.0.0 We left them in the docs for a period of time to help people find docs for code that was still in use. Balancing that with the need for clean docs, it seems like 3.1 is an appropriate time to mark them hidden in the docs.
2022-02-12 00:42:26 +00:00
#[doc(hidden)]
fix: Ease clap2->clap3 migration with deprecations - `App::with_defaults` was not included since that has been deprecated since 2.14 - `App::args_from_usage` does not have a close enough parallel in the new API, as far as I could tell - `ArgMatches::usage` cannot have a thin wrapper around `App::generate_usage`. - `App::write_*`: getting lazy, didn't seem like high value functions - Any `Settings` (some things need to be figured out here) This is a part of #2617
2021-08-18 15:53:05 +00:00
pub fn from_yaml(yaml: &yaml_rust::Yaml) -> App {
fix: Deprecate YAML API Fixes #9
2021-11-18 20:27:21 +00:00
#![allow(deprecated)]
docs: Update App references to Command
2022-02-12 03:48:29 +00:00
Command::from_yaml(yaml)
fix: Ease clap2->clap3 migration with deprecations - `App::with_defaults` was not included since that has been deprecated since 2.14 - `App::args_from_usage` does not have a close enough parallel in the new API, as far as I could tell - `ArgMatches::usage` cannot have a thin wrapper around `App::generate_usage`. - `App::write_*`: getting lazy, didn't seem like high value functions - Any `Settings` (some things need to be figured out here) This is a part of #2617
2021-08-18 15:53:05 +00:00
}
}
Reference in a new issue Copy permalink