clap/src/lib.rs
Ed Page 7515bfeb51 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 10:50:05 -05:00

149 lines
4.5 KiB
Rust

// Copyright ⓒ 2015-2016 Kevin B. Knapp and [`clap-rs` contributors](https://github.com/clap-rs/clap/graphs/contributors).
// 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.
#![cfg_attr(docsrs, feature(doc_auto_cfg))]
#![doc(html_logo_url = "https://raw.githubusercontent.com/clap-rs/clap/master/assets/clap.png")]
#![cfg_attr(feature = "derive", doc = include_str!("../README.md"))]
//! <https://github.com/clap-rs/clap>
#![warn(
missing_docs,
missing_debug_implementations,
missing_copy_implementations,
trivial_casts,
unused_allocation,
trivial_numeric_casts,
clippy::single_char_pattern
)]
#![forbid(unsafe_code)]
// HACK https://github.com/rust-lang/rust-clippy/issues/7290
#![allow(clippy::single_component_path_imports)]
#![allow(clippy::branches_sharing_code)]
// Doesn't allow for debug statements, etc to be unique
#![allow(clippy::if_same_then_else)]
#[cfg(not(feature = "std"))]
compile_error!("`std` feature is currently required to build `clap`");
pub use crate::builder::ArgAction;
pub use crate::builder::Command;
pub use crate::builder::{Arg, ArgGroup};
pub use crate::error::Error;
pub use crate::parser::ArgMatches;
#[cfg(feature = "color")]
pub use crate::util::color::ColorChoice;
#[cfg(not(feature = "color"))]
#[allow(unused_imports)]
pub(crate) use crate::util::color::ColorChoice;
pub use crate::derive::{Args, CommandFactory, FromArgMatches, Parser, Subcommand, ValueEnum};
#[allow(deprecated)]
pub use crate::builder::App;
pub use crate::builder::{AppFlags, AppSettings, ArgFlags, ArgSettings, PossibleValue, ValueHint};
pub use crate::error::{ErrorKind, Result};
#[allow(deprecated)]
pub use crate::parser::{Indices, OsValues, ValueSource, Values};
#[cfg(feature = "yaml")]
#[doc(hidden)]
#[cfg_attr(
feature = "deprecated",
deprecated(
since = "3.0.0",
note = "Deprecated in Issue #3087, maybe clap::Parser would fit your use case?"
)
)]
#[doc(hidden)]
pub use yaml_rust::YamlLoader;
#[cfg(feature = "derive")]
#[doc(hidden)]
pub use clap_derive::{self, *};
/// Deprecated, replaced with [`CommandFactory`]
#[cfg_attr(
feature = "deprecated",
deprecated(since = "3.0.0", note = "Replaced with `CommandFactory`")
)]
pub use CommandFactory as IntoApp;
/// Deprecated, replaced with [`Parser`]
#[cfg_attr(
feature = "deprecated",
deprecated(since = "3.0.0", note = "Replaced with `Parser`")
)]
#[doc(hidden)]
pub use Parser as StructOpt;
/// Deprecated, replaced with [`ValueEnum`]
#[cfg_attr(
feature = "deprecated",
deprecated(since = "3.2.0", note = "Replaced with `ValueEnum`")
)]
pub use ValueEnum as ArgEnum;
#[cfg(any(feature = "derive", feature = "cargo"))]
#[doc(hidden)]
pub use once_cell;
#[macro_use]
#[allow(missing_docs)]
mod macros;
mod derive;
#[cfg(feature = "regex")]
pub use crate::builder::RegexRef;
pub mod builder;
pub mod error;
pub mod parser;
mod mkeymap;
mod output;
mod util;
const INTERNAL_ERROR_MSG: &str = "Fatal internal error. Please consider filing a bug \
report at https://github.com/clap-rs/clap/issues";
const INVALID_UTF8: &str = "unexpected invalid UTF-8 code point";
/// Deprecated, replaced with [`Command::new`], unless you were looking for [Subcommand]
#[cfg_attr(
feature = "deprecated",
deprecated(
since = "3.0.0",
note = "Replaced with `Command::new` unless you intended the `Subcommand` trait"
)
)]
#[doc(hidden)]
#[derive(Debug, Copy, Clone)]
pub struct SubCommand {}
#[allow(deprecated)]
impl SubCommand {
/// Deprecated, replaced with [`Command::new`].
/// Did you mean Subcommand (lower-case c)?
#[cfg_attr(
feature = "deprecated",
deprecated(since = "3.0.0", note = "Replaced with `Command::new`")
)]
#[doc(hidden)]
pub fn with_name<'help>(name: &str) -> App<'help> {
Command::new(name)
}
/// Deprecated in [Issue #3087](https://github.com/clap-rs/clap/issues/3087), maybe [`clap::Parser`][crate::Parser] would fit your use case?
#[cfg(feature = "yaml")]
#[cfg_attr(
feature = "deprecated",
deprecated(
since = "3.0.0",
note = "Deprecated in Issue #3087, maybe clap::Parser would fit your use case?"
)
)]
#[doc(hidden)]
pub fn from_yaml(yaml: &yaml_rust::Yaml) -> App {
#![allow(deprecated)]
Command::from_yaml(yaml)
}
}