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.
This commit is contained in:
tormol 2016-10-15 23:37:59 +02:00
parent 47ffccd251
commit cd516006e3
8 changed files with 17 additions and 28 deletions

View file

@ -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.)

View file

@ -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

View file

@ -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

View file

@ -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 =>

View file

@ -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() {}

View file

@ -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() {}

View file

@ -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

View file

@ -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)*) => {