From cd516006e35c37b005f329338560a0a53d1f3e00 Mon Sep 17 00:00:00 2001 From: tormol Date: Sat, 15 Oct 2016 23:37:59 +0200 Subject: [PATCH] imp: Stabilize clap_app! It was de-stabilized in 2.0.0 but hasn't been changed since. This commit also updates docs to reflect that the "unstable" feature does nothing now. --- .github/CONTRIBUTING.md | 2 +- Cargo.toml | 2 +- README.md | 10 +++++----- benches/03_complex.rs | 3 +-- examples/01c_quick_example.rs | 4 ---- examples/18_builder_macro.rs | 4 ---- src/lib.rs | 14 ++++++-------- src/macros.rs | 6 +++--- 8 files changed, 17 insertions(+), 28 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 7a122363..f961afcf 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -21,7 +21,7 @@ Contributions are always welcome! Please use the following guidelines when contr - `chore` - Catch all or things that have to do with the build system, etc - `examples` - Changes to existing example, or a new example * The `COMPONENT` is optional, and may be a single file, directory, or logical component. Can be omitted if commit applies globally -5. Run the tests (`cargo test --no-std-features && cargo test --features="yaml unstable"`) +5. Run the tests (`cargo test --no-std-features && cargo test --features yaml`) 6. `git rebase` into concise commits and remove `--fixup`s (`git rebase -i HEAD~NUM` where `NUM` is number of commits back) 7. Push your changes back to your fork (`git push origin $your-branch`) 8. Create a pull request! (You can also create the pull request first, and we'll merge when ready. This a good way to discuss proposed changes.) diff --git a/Cargo.toml b/Cargo.toml index d3f17bb2..3abe65ce 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -35,7 +35,7 @@ suggestions = ["strsim"] color = ["ansi_term", "libc"] wrap_help = ["libc", "term_size"] yaml = ["yaml-rust"] -unstable = [] # for building with unstable clap features (doesn't require nightly Rust) +unstable = [] # for building with unstable clap features (doesn't require nightly Rust) (currently none) nightly = [] # for building with unstable Rust features (currently none) lints = ["clippy"] # Requires nightly Rust debug = [] # Enables debug messages diff --git a/README.md b/README.md index 7c649189..9b1db05b 100644 --- a/README.md +++ b/README.md @@ -493,7 +493,10 @@ subcommands: help: print debug information ``` -Now we create our `main.rs` file just like we would have with the previous two examples: +Since this feature is not compiled in by default we need to enable a feature flag in Cargo.toml: +Simply change your `clap = "2"` to `clap = {version = "2", features = ["yaml"]}`. + +At last we create our `main.rs` file just like we would have with the previous two examples: ```rust // (Full example with detailed comments in examples/17_yaml.rs) @@ -513,8 +516,6 @@ fn main() { } ``` -**NOTE**: The YAML and macro builder options require adding a special `features` flag when compiling `clap` because they are not compiled by default. Simply change your `clap = "2"` to `clap = {version = "2", features = ["yaml"]}` for YAML, or `features = ["unstable"]` for the macro builder, in your `Cargo.toml`. - If you were to compile any of the above programs and run them with the flag `--help` or `-h` (or `help` subcommand, since we defined `test` as a subcommand) the following would be output ```sh @@ -632,7 +633,6 @@ features = [ "suggestions", "color" ] #### Opt-in features * **"yaml"**: Enables building CLIs from YAML documents. (builds dependency `yaml-rust`) -* **"unstable"**: Enables clap features whoose API might change without a major version bump, but doesn't require nightly Rust. Currently `clap_app!`. ### Dependencies Tree @@ -667,7 +667,7 @@ To test with all features both enabled and disabled, you can run theese commands ```sh $ cargo test --no-default-features -$ cargo test --features "yaml unstable" +$ cargo test --features yaml ``` If you have a nightly compiler you can append `--features lints` to both commands diff --git a/benches/03_complex.rs b/benches/03_complex.rs index 2c97da95..a803cfeb 100644 --- a/benches/03_complex.rs +++ b/benches/03_complex.rs @@ -134,8 +134,7 @@ fn create_app_builder(b: &mut Bencher) { }); } -#[cfg(feature = "unstable")] -#[cfg_attr(feature = "unstable", bench)] +#[bench] fn create_app_macros(b: &mut Bencher) { b.iter(|| { clap_app!(claptests => diff --git a/examples/01c_quick_example.rs b/examples/01c_quick_example.rs index 24c1b892..071bdc0a 100644 --- a/examples/01c_quick_example.rs +++ b/examples/01c_quick_example.rs @@ -1,7 +1,6 @@ #[macro_use] extern crate clap; -#[cfg(feature = "unstable")] fn main() { // This example shows how to create an application with several arguments using macro builder. // It combines the simplicity of the from_usage methods and the performance of the Builder Pattern. @@ -74,6 +73,3 @@ fn main() { // more program logic goes here... } - -#[cfg(not(feature = "unstable"))] -fn main() {} diff --git a/examples/18_builder_macro.rs b/examples/18_builder_macro.rs index d139e771..594c3865 100644 --- a/examples/18_builder_macro.rs +++ b/examples/18_builder_macro.rs @@ -4,7 +4,6 @@ extern crate clap; // Note, there isn't a need for "use clap::{ ... };" Because the clap_app! macro uses // $crate:: internally -#[cfg(feature = "unstable")] fn main() { // Validation example testing that a file exists @@ -82,6 +81,3 @@ fn main() { // Continued program logic goes here... } - -#[cfg(not(feature = "unstable"))] -fn main() {} diff --git a/src/lib.rs b/src/lib.rs index 637481e3..e63f23f0 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -151,10 +151,8 @@ //! //! The following combines the previous two examples by using the less verbose `from_usage` methods and the performance of the Builder Pattern. //! -#![cfg_attr(not(feature="unstable"), doc=" ```ignore")] -#![cfg_attr( feature="unstable" , doc=" ```no_run")] +//! ```no_run //! // (Full example with detailed comments in examples/01c_quick_example.rs) -//! // Must be compiled with `--features unstable` (which doesn't require nightly Rust). //! // //! // This example demonstrates clap's "usage strings" method of creating arguments //! // which is less less verbose @@ -214,7 +212,10 @@ //! help: print debug information //! ``` //! -//! Now we create our `main.rs` file just like we would have with the previous two examples: +//! Because this feature is not compiled in by default we need to enable a feature flag in Cargo.toml: +//! Simply change your `clap = "2"` to `clap = {version = "2", features = ["yaml"]}`. +//! +//! At last we create our `main.rs` file just like we would have with the previous two examples: //! //! ```ignore //! // (Full example with detailed comments in examples/17_yaml.rs) @@ -234,8 +235,6 @@ //! } //! ``` //! -//! **NOTE**: The YAML and macro builder options require adding a special `features` flag when compiling `clap` because they are not compiled by default. Simply change your `clap = "2"` to `clap = {version = "2", features = ["yaml"]}` for YAML, or `features = ["unstable"]` for the macro builder, in your `Cargo.toml`. -//! //! If you were to compile any of the above programs and run them with the flag `--help` or `-h` (or `help` subcommand, since we defined `test` as a subcommand) the following would be output //! //! ```text @@ -353,7 +352,6 @@ //! #### Opt-in features //! //! * **"yaml"**: Enables building CLIs from YAML documents. -//! * **"unstable"**: Enables clap features whoose API might change without a major version bump. Doesn't require nightly Rust. Currently `clap_app!`. //! //! ### More Information //! @@ -375,7 +373,7 @@ //! //! ```sh //! $ cargo test --no-default-features -//! $ cargo test --features "yaml unstable" +//! $ cargo test --features yaml //! ``` //! //! If you have a nightly compiler you can append `--features lints` to both commands diff --git a/src/macros.rs b/src/macros.rs index 6836a229..8df6a081 100644 --- a/src/macros.rs +++ b/src/macros.rs @@ -416,9 +416,9 @@ macro_rules! crate_authors { }; } -/// App, Arg, SubCommand and Group builder macro (Usage-string like input) must be compiled with -/// the `unstable` feature in order to use. -#[cfg_attr(feature = "unstable", macro_export)] +/// Build `App`, `Arg`s, `SubCommand`s and `Group`s with Usage-string like input +/// but without the parsing. +#[macro_export] macro_rules! clap_app { (@app ($builder:expr)) => { $builder }; (@app ($builder:expr) (@arg $name:ident: $($tail:tt)*) $($tt:tt)*) => {