mirror of
https://github.com/clap-rs/clap
synced 2024-09-21 06:41:54 +00:00
chore: fixes doc and style mistakes
This commit is contained in:
Kevin K
parent
bf8cd8f446
commit
90542747ac
7 changed files with 49 additions and 286 deletions
|
|
@ -35,7 +35,7 @@ fn main() {
|
|||
|
||||
// Two arguments, one "Option" argument (i.e. one that takes a value) such
|
||||
// as "-c some", and one positional argument (i.e. "myapp some_file")
|
||||
.args( &[
|
||||
.args(&[
|
||||
Arg::with_name("config")
|
||||
.help("sets the config file to use")
|
||||
.takes_value(true)
|
||||
|
|
|
|||
|
|
@ -369,7 +369,7 @@ pub enum AppSettings {
|
|||
///
|
||||
/// assert!(r.is_ok());
|
||||
/// let m = r.unwrap();
|
||||
/// assert_eq!(m.os_value_of("arg").unwrap().as_bytes(), &[0xe9]);
|
||||
/// assert_eq!(m.value_of_os("arg").unwrap().as_bytes(), &[0xe9]);
|
||||
/// ```
|
||||
AllowInvalidUtf8,
|
||||
/// Specifies that leading hyphens are allowed in argument values, such as `-10`
|
||||
|
|
|
|||
|
|
@ -116,7 +116,7 @@ impl<'a> ArgMatches<'a> {
|
|||
/// invalid points will be replaced with `\u{FFFD}`
|
||||
///
|
||||
/// *NOTE:* If getting a value for an option or positional argument that allows multiples,
|
||||
/// prefer `lossy_values_of()` as `lossy_value_of()` will only return the *first* value.
|
||||
/// prefer `values_of_lossy()` as `value_of_lossy()` will only return the *first* value.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
|
|
@ -130,9 +130,9 @@ impl<'a> ArgMatches<'a> {
|
|||
/// .get_matches_from(vec![OsString::from("myprog"),
|
||||
/// // "Hi {0xe9}!"
|
||||
/// OsString::from_vec(vec![b'H', b'i', b' ', 0xe9, b'!'])]);
|
||||
/// assert_eq!(&*m.lossy_value_of("arg").unwrap(), "Hi \u{FFFD}!");
|
||||
/// assert_eq!(&*m.value_of_lossy("arg").unwrap(), "Hi \u{FFFD}!");
|
||||
/// ```
|
||||
pub fn lossy_value_of<S: AsRef<str>>(&'a self, name: S) -> Option<Cow<'a, str>> {
|
||||
pub fn value_of_lossy<S: AsRef<str>>(&'a self, name: S) -> Option<Cow<'a, str>> {
|
||||
if let Some(arg) = self.args.get(name.as_ref()) {
|
||||
if let Some(v) = arg.vals.values().nth(0) {
|
||||
return Some(v.to_string_lossy());
|
||||
|
|
@ -144,11 +144,11 @@ impl<'a> ArgMatches<'a> {
|
|||
/// Gets the OS version of a string value of a specific argument. If the option wasn't present
|
||||
/// at runtime it returns `None`. An OS value on Unix-like systems is any series of bytes,
|
||||
/// regardless of whether or not they contain valid UTF-8 code points. Since `String`s in Rust
|
||||
/// are garunteed to be valid UTF-8, a valid filename on a Unix system as an argument value may
|
||||
/// are guaranteed to be valid UTF-8, a valid filename on a Unix system as an argument value may
|
||||
/// contain invalid UTF-8 code points.
|
||||
///
|
||||
/// *NOTE:* If getting a value for an option or positional argument that allows multiples,
|
||||
/// prefer `os_values_of()` as `os_value_of()` will only return the *first* value.
|
||||
/// prefer `values_of_os()` as `value_of_os()` will only return the *first* value.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
|
|
@ -162,9 +162,9 @@ impl<'a> ArgMatches<'a> {
|
|||
/// .get_matches_from(vec![OsString::from("myprog"),
|
||||
/// // "Hi {0xe9}!"
|
||||
/// OsString::from_vec(vec![b'H', b'i', b' ', 0xe9, b'!'])]);
|
||||
/// assert_eq!(&*m.os_value_of("arg").unwrap().as_bytes(), [b'H', b'i', b' ', 0xe9, b'!']);
|
||||
/// assert_eq!(&*m.value_of_os("arg").unwrap().as_bytes(), [b'H', b'i', b' ', 0xe9, b'!']);
|
||||
/// ```
|
||||
pub fn os_value_of<S: AsRef<str>>(&self, name: S) -> Option<&OsStr> {
|
||||
pub fn value_of_os<S: AsRef<str>>(&self, name: S) -> Option<&OsStr> {
|
||||
self.args.get(name.as_ref()).map_or(None, |arg| arg.vals.values().nth(0).map(|v| v.as_os_str()))
|
||||
}
|
||||
|
||||
|
|
@ -215,12 +215,12 @@ impl<'a> ArgMatches<'a> {
|
|||
/// .get_matches_from(vec![OsString::from("myprog"),
|
||||
/// // "Hi {0xe9}!"
|
||||
/// OsString::from_vec(vec![b'H', b'i', b' ', 0xe9, b'!'])]);
|
||||
/// let itr = m.lossy_values_of("arg").unwrap();
|
||||
/// let itr = m.values_of_lossy("arg").unwrap();
|
||||
/// assert_eq!(&*itr.next().unwrap(), "Hi");
|
||||
/// assert_eq!(&*itr.next().unwrap(), "\u{FFFD}!");
|
||||
/// assert_eq!(itr.next(), None);
|
||||
/// ```
|
||||
pub fn lossy_values_of<S: AsRef<str>>(&'a self, name: S) -> Option<Vec<String>> {
|
||||
pub fn values_of_lossy<S: AsRef<str>>(&'a self, name: S) -> Option<Vec<String>> {
|
||||
if let Some(ref arg) = self.args.get(name.as_ref()) {
|
||||
return Some(arg.vals.values()
|
||||
.map(|v| v.to_string_lossy().into_owned())
|
||||
|
|
@ -232,7 +232,7 @@ impl<'a> ArgMatches<'a> {
|
|||
/// Gets the OS version of a string value of a specific argument If the option wasn't present
|
||||
/// at runtime it returns `None`. An OS value on Unix-like systems is any series of bytes,
|
||||
/// regardless of whether or not they contain valid UTF-8 code points. Since `String`s in Rust
|
||||
/// are garunteed to be valid UTF-8, a valid filename as an argument value on Linux (for
|
||||
/// are guaranteed to be valid UTF-8, a valid filename as an argument value on Linux (for
|
||||
/// example) may contain invalid UTF-8 code points.
|
||||
///
|
||||
/// # Examples
|
||||
|
|
@ -250,12 +250,12 @@ impl<'a> ArgMatches<'a> {
|
|||
/// // "{0xe9}!"
|
||||
/// OsString::from_vec(vec![0xe9, b'!'])]);
|
||||
///
|
||||
/// let itr = m.os_values_of("arg").unwrap();
|
||||
/// let itr = m.values_of_os("arg").unwrap();
|
||||
/// assert_eq!(itr.next(), Some(&*OsString::from("Hi")));
|
||||
/// assert_eq!(itr.next(), Some(&*OsString::from_vec(vec![0xe9, b'!'])));
|
||||
/// assert_eq!(itr.next(), None);
|
||||
/// ```
|
||||
pub fn os_values_of<S: AsRef<str>>(&'a self, name: S) -> Option<OsValues<'a>> {
|
||||
pub fn values_of_os<S: AsRef<str>>(&'a self, name: S) -> Option<OsValues<'a>> {
|
||||
fn to_str_slice(o: &OsString) -> &OsStr { &*o }
|
||||
let to_str_slice: fn(&'a OsString) -> &'a OsStr = to_str_slice; // coerce to fn pointer
|
||||
if let Some(ref arg) = self.args.get(name.as_ref()) {
|
||||
|
|
@ -359,7 +359,10 @@ impl<'a> ArgMatches<'a> {
|
|||
/// }
|
||||
/// ```
|
||||
pub fn subcommand_matches<S: AsRef<str>>(&self, name: S) -> Option<&ArgMatches<'a>> {
|
||||
self.subcommand.as_ref().map(|s| if s.name == name.as_ref() { Some(&s.matches) } else { None } ).unwrap()
|
||||
if let Some(ref s) = self.subcommand {
|
||||
if s.name == name.as_ref() { return Some(&s.matches) }
|
||||
}
|
||||
None
|
||||
}
|
||||
|
||||
/// Because subcommands are essentially "sub-apps" they have their own `ArgMatches` as well.
|
||||
|
|
@ -466,7 +469,7 @@ impl<'a> ArgMatches<'a> {
|
|||
/// }
|
||||
/// ```
|
||||
pub fn subcommand(&self) -> (&str, Option<&ArgMatches<'a>>) {
|
||||
self.subcommand.as_ref().map_or(("",None), |sc| (&sc.name[..], Some(&sc.matches)))
|
||||
self.subcommand.as_ref().map_or(("", None), |sc| (&sc.name[..], Some(&sc.matches)))
|
||||
}
|
||||
|
||||
/// Returns a string slice of the usage statement for the `App` (or `SubCommand`)
|
||||
|
|
|
|||
|
|
@ -32,7 +32,7 @@ pub enum ErrorKind {
|
|||
/// assert_eq!(result.unwrap_err().kind, ErrorKind::InvalidValue);
|
||||
/// ```
|
||||
InvalidValue,
|
||||
/// Occurs when a user provides a flag, option, or argument which wasn't defined
|
||||
/// Occurs when a user provides a flag, option, or argument which wasn't defined.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
|
|
@ -47,7 +47,7 @@ pub enum ErrorKind {
|
|||
UnknownArgument,
|
||||
/// Occurs when the user provids an unrecognized subcommand which meets the threshold for being
|
||||
/// similar enough to an existing subcommand so as to not cause the more general
|
||||
/// `UnknownArgument` error
|
||||
/// `UnknownArgument` error.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
|
|
@ -64,7 +64,8 @@ pub enum ErrorKind {
|
|||
/// assert_eq!(result.unwrap_err().kind, ErrorKind::InvalidSubcommand);
|
||||
/// ```
|
||||
InvalidSubcommand,
|
||||
/// Occurs when the user provides an empty value for an option that does not allow empty values
|
||||
/// Occurs when the user provides an empty value for an option that does not allow empty
|
||||
/// values.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
|
|
@ -102,7 +103,7 @@ pub enum ErrorKind {
|
|||
/// ```
|
||||
ValueValidation,
|
||||
/// Occurs when a user provides more values for an argument than were defined by setting
|
||||
/// `Arg::max_values`
|
||||
/// `Arg::max_values`.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
|
|
@ -118,7 +119,7 @@ pub enum ErrorKind {
|
|||
/// ```
|
||||
TooManyValues,
|
||||
/// Occurs when the user provides fewer values for an argument than were defined by setting
|
||||
/// `Arg::min_values`
|
||||
/// `Arg::min_values`.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
|
|
@ -135,7 +136,7 @@ pub enum ErrorKind {
|
|||
TooFewValues,
|
||||
/// Occurs when the user provides a different number of values for an argument than what's
|
||||
/// been defined by setting `Arg::number_of_values` or than was implicitly set by
|
||||
/// `Arg::value_names`
|
||||
/// `Arg::value_names`.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
|
|
@ -169,7 +170,7 @@ pub enum ErrorKind {
|
|||
/// assert_eq!(result.unwrap_err().kind, ErrorKind::ArgumentConflict);
|
||||
/// ```
|
||||
ArgumentConflict,
|
||||
/// Occurs when the user does not provide one or more required arguments
|
||||
/// Occurs when the user does not provide one or more required arguments.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
|
|
@ -184,7 +185,7 @@ pub enum ErrorKind {
|
|||
/// ```
|
||||
MissingRequiredArgument,
|
||||
/// Occurs when a subcommand is required (as defined by `AppSettings::SubcommandRequired`), but
|
||||
/// the user does not provide one
|
||||
/// the user does not provide one.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
|
|
@ -202,7 +203,7 @@ pub enum ErrorKind {
|
|||
/// ```
|
||||
MissingSubcommand,
|
||||
/// Occurs when either an argument or subcommand is required, as defined by
|
||||
/// `AppSettings::ArgRequiredElseHelp` but the user did not provide one
|
||||
/// `AppSettings::ArgRequiredElseHelp` but the user did not provide one.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
|
|
@ -264,7 +265,7 @@ pub enum ErrorKind {
|
|||
/// to `stdout`.
|
||||
///
|
||||
/// **Note**: If the help is displayed due to an error (such as missing subcommands) it will
|
||||
/// be sent to `stderr` instead of `stdout`
|
||||
/// be sent to `stderr` instead of `stdout`.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
|
|
@ -277,7 +278,7 @@ pub enum ErrorKind {
|
|||
/// ```
|
||||
HelpDisplayed,
|
||||
/// Not a true "error" as it means `--version` or similar was used. The message will be sent
|
||||
/// to `stdout`
|
||||
/// to `stdout`.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
|
|
@ -293,13 +294,13 @@ pub enum ErrorKind {
|
|||
/// type `T`, but the argument you requested wasn't used. I.e. you asked for an argument with
|
||||
/// name `config` to be converted, but `config` wasn't used by the user.
|
||||
ArgumentNotFound,
|
||||
/// Represents an I/O error, typically while writing to `stderr` or `stdout`
|
||||
/// Represents an I/O error, typically while writing to `stderr` or `stdout`.
|
||||
Io,
|
||||
/// Represents an Rust Display Format error, typically white writing to `stderr` or `stdout`
|
||||
/// Represents an Rust Display Format error, typically white writing to `stderr` or `stdout`.
|
||||
Format,
|
||||
}
|
||||
|
||||
/// Command Line Argumetn Parser Error
|
||||
/// Command Line Argument Parser Error
|
||||
#[derive(Debug)]
|
||||
pub struct Error {
|
||||
/// Formated error message
|
||||
|
|
@ -634,12 +635,6 @@ impl StdError for Error {
|
|||
fn description(&self) -> &str {
|
||||
&*self.message
|
||||
}
|
||||
|
||||
fn cause(&self) -> Option<&StdError> {
|
||||
match self.kind {
|
||||
_ => None,
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
impl Display for Error {
|
||||
|
|
|
|||
239
src/lib.rs
239
src/lib.rs
|
|
@ -1,108 +1,4 @@
|
|||
//! # clap
|
||||
//!
|
||||
//! [](https://crates.io/crates/clap) [](https://crates.io/crates/clap) [](https://github.com/kbknapp/clap-rs/blob/master/LICENSE-MIT) [](https://coveralls.io/github/kbknapp/clap-rs?branch=master) [](https://gitter.im/kbknapp/clap-rs?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
|
||||
//!
|
||||
//! Linux: [](https://travis-ci.org/kbknapp/clap-rs)
|
||||
//! Windows: [](https://ci.appveyor.com/project/kbknapp/clap-rs/branch/master)
|
||||
//!
|
||||
//! Command Line Argument Parser for Rust
|
||||
//!
|
||||
//! It is a simple to use, efficient, and full featured library for parsing command line arguments and subcommands when writing console, or terminal applications.
|
||||
//!
|
||||
//! Table of Contents
|
||||
//! =================
|
||||
//!
|
||||
//! * [What's New](#whats-new)
|
||||
//! * [About](#about)
|
||||
//! * [FAQ](#faq)
|
||||
//! * [Features](#features)
|
||||
//! * [Quick Example](#quick-example)
|
||||
//! * [Try it!](#try-it)
|
||||
//! * [Pre-Built Test](#pre-built-test)
|
||||
//! * [BYOB (Build Your Own Binary)](#byob-build-your-own-binary)
|
||||
//! * [Usage](#usage)
|
||||
//! * [Optional Dependencies / Features](#optional-dependencies--features)
|
||||
//! * [Dependencies Tree](#dependencies-tree)
|
||||
//! * [More Information](#more-information)
|
||||
//! * [Video Tutorials](#video-tutorials)
|
||||
//! * [How to Contribute](#how-to-contribute)
|
||||
//! * [Running the tests](#running-the-tests)
|
||||
//! * [Goals](#goals)
|
||||
//! * [License](#license)
|
||||
//! * [Recent Breaking Changes](#recent-breaking-changes)
|
||||
//! * [Deprecations](#deprecations)
|
||||
//!
|
||||
//! Created by [gh-md-toc](https://github.com/ekalinin/github-markdown-toc)
|
||||
//!
|
||||
//! ## What's New
|
||||
//!
|
||||
//! v**2.0** has been released! This means fixing some pain points, new features, better documentation, improved ergonomics, and also some minor breaking changes if you're used to v1.x
|
||||
//!
|
||||
//! #### New Features
|
||||
//!
|
||||
//! Here are some key points about the 2.x release
|
||||
//!
|
||||
//! * Support for arguments with invalid UTF-8 values!: Helps with POSIX and Unix like OSs
|
||||
//! * Even better performance boost!
|
||||
//! * Far better documentation
|
||||
//! * Support for delimited values
|
||||
//! * Support for custom delimiter in values
|
||||
//! * Support for external subcommands
|
||||
//! * Support for options that act as flags (i.e. ones which optionally have no value)
|
||||
//! * Support for negative numbers as arguments (i.e. `-10`, etc.)
|
||||
//! * Better Errors and error handling
|
||||
//! * Improved "from usage" strings
|
||||
//! * Better support for generics, instead of being locked in to `Vec` at key points
|
||||
//! * Improved macros
|
||||
//! * Better regression testing
|
||||
//! * Vastly improved ergonomics
|
||||
//! * Numerous bug fixes
|
||||
//!
|
||||
//! 
|
||||
//!
|
||||
//! #### Breaking Changes
|
||||
//!
|
||||
//! Below is a list of breaking changes between 1.x and 2.x and how you can change your code to update.
|
||||
//!
|
||||
//! * **Fewer liftimes! Yay!**
|
||||
//! * `App<'a, 'b, 'c, 'd, 'e, 'f>` => `App<'a, 'b>`
|
||||
//! * `Arg<'a, 'b, 'c, 'd, 'e, 'f>` => `Arg<'a, 'b>`
|
||||
//! * `ArgMatches<'a, 'b>` => `ArgMatches<'a>`
|
||||
//! * **Simply Renamed**
|
||||
//! * `App::arg_group` => `App::group`
|
||||
//! * `App::arg_groups` => `App::groups`
|
||||
//! * `ArgGroup::add` => `ArgGroup::arg`
|
||||
//! * `ArgGroup::add_all` => `ArgGroup::args`
|
||||
//! * `ClapError` => `Error`
|
||||
//! * `ClapResult` => `Result`
|
||||
//! * `ClapErrorType` => `ErrorKind`
|
||||
//! * struct field `ClapError::error_type` => `Error::kind`
|
||||
//! * **Removed Deprecated Functions and Methods**
|
||||
//! * `App::subcommands_negate_reqs`
|
||||
//! * `App::subcommand_required`
|
||||
//! * `App::arg_required_else_help`
|
||||
//! * `App::global_version(bool)`
|
||||
//! * `App::versionless_subcommands`
|
||||
//! * `App::unified_help_messages`
|
||||
//! * `App::wait_on_error`
|
||||
//! * `App::subcommand_required_else_help`
|
||||
//! * `SubCommand::new`
|
||||
//! * `App::error_on_no_subcommand`
|
||||
//! * `Arg::new`
|
||||
//! * `Arg::mutually_excludes`
|
||||
//! * `Arg::mutually_excludes_all`
|
||||
//! * `Arg::mutually_overrides_with`
|
||||
//! * `simple_enum!`
|
||||
//! * **Renamed Errors Variants**
|
||||
//! * `InvalidUnicode` => `InvalidUtf8`
|
||||
//! * `InvalidArgument` => `UnknownArgument`
|
||||
//! * **Usage Parser**
|
||||
//! * Value names can now be specified inline, i.e. `-o, --option <FILE> <FILE2> 'some option which takes two files'`
|
||||
//! * **There is now a priority of order to determine the name** - This is perhaps the biggest breaking change. See the documentation for full details. Prior to this change, the value name took precedence. **Ensure your args are using the proper names (i.e. typically the long or short and NOT the value name) throughout the code**
|
||||
//! * `ArgMatches::values_of` returns an `Values` now which implements `Iterator` (should not break any code)
|
||||
//! * `crate_version!` returns `&'static str` instead of `String`
|
||||
//!
|
||||
//! For full details, see [CHANGELOG.md](https://github.com/kbknapp/clap-rs/blob/master/CHANGELOG.md)
|
||||
//! A simple to use, efficient, and full featured library for parsing command line arguments and subcommands when writing console, or terminal applications.
|
||||
//!
|
||||
//! ## About
|
||||
//!
|
||||
|
|
@ -140,54 +36,6 @@
|
|||
//!
|
||||
//! `clap` is as fast, and as lightweight as possible while still giving all the features you'd expect from a modern argument parser. In fact, for the amount and type of features `clap` offers it remains about as fast as `getopts`. If you use `clap` when just need some simple arguments parsed, you'll find its a walk in the park. `clap` also makes it possible to represent extremely complex, and advanced requirements, without too much thought. `clap` aims to be intuitive, easy to use, and fully capable for wide variety use cases and needs.
|
||||
//!
|
||||
//! ## Features
|
||||
//!
|
||||
//! Below are a few of the features which `clap` supports, full descriptions and usage can be found in the [documentation](http://kbknapp.github.io/clap-rs/clap/index.html) and [examples/](examples) directory
|
||||
//!
|
||||
//! * **Auto-generated Help, Version, and Usage information**
|
||||
//! - Can optionally be fully, or partially overridden if you want a custom help, version, or usage
|
||||
//! * **Flags / Switches** (i.e. bool fields)
|
||||
//! - Both short and long versions supported (i.e. `-f` and `--flag` respectively)
|
||||
//! - Supports combining short versions (i.e. `-fBgoZ` is the same as `-f -B -g -o -Z`)
|
||||
//! - Supports multiple occurrences (i.e. `-vvv` or `-v -v -v`)
|
||||
//! * **Positional Arguments** (i.e. those which are based off an index from the program name)
|
||||
//! - Supports multiple values (i.e. `myprog <file>...` such as `myprog file1.txt file2.txt` being two values for the same "file" argument)
|
||||
//! - Supports Specific Value Sets (See below)
|
||||
//! - Can set value parameters (such as the minimum number of values, the maximum number of values, or the exact number of values)
|
||||
//! - Can set custom validations on values to extend the argument parsing capability to truly custom domains
|
||||
//! * **Option Arguments** (i.e. those that take values)
|
||||
//! - Both short and long versions supported (i.e. `-o value`, `-ovalue`, `-o=value` and `--option value` or `--option=value` respectively)
|
||||
//! - Supports multiple values (i.e. `-o <val1> -o <val2>` or `-o <val1> <val2>`)
|
||||
//! - Supports delimited values (i.e. `-o=val1,val2,val3`, can also change the delimiter)
|
||||
//! - Supports Specific Value Sets (See below)
|
||||
//! - Supports named values so that the usage/help info appears as `-o <FILE> <INTERFACE>` etc. for when you require specific multiple values
|
||||
//! - Can set value parameters (such as the minimum number of values, the maximum number of values, or the exact number of values)
|
||||
//! - Can set custom validations on values to extend the argument parsing capability to truly custom domains
|
||||
//! * **Sub-Commands** (i.e. `git add <file>` where `add` is a sub-command of `git`)
|
||||
//! - Support their own sub-arguments, and sub-sub-commands independent of the parent
|
||||
//! - Get their own auto-generated Help, Version, and Usage independent of parent
|
||||
//! * **Support for building CLIs from YAML** - This keeps your Rust source nice and tidy and makes supporting localized translation very simple!
|
||||
//! * **Requirement Rules**: Arguments can define the following types of requirement rules
|
||||
//! - Can be required by default
|
||||
//! - Can be required only if certain arguments are present
|
||||
//! - Can require other arguments to be present
|
||||
//! * **Confliction Rules**: Arguments can optionally define the following types of exclusion rules
|
||||
//! - Can be disallowed when certain arguments are present
|
||||
//! - Can disallow use of other arguments when present
|
||||
//! * **POSIX Override Rules**: Arguments can define rules to support POSIX overriding
|
||||
//! * **Groups**: Arguments can be made part of a group
|
||||
//! - Fully compatible with other relational rules (requirements, conflicts, and overrides) which allows things like requiring the use of any arg in a group, or denying the use of an entire group conditionally
|
||||
//! * **Specific Value Sets**: Positional or Option Arguments can define a specific set of allowed values (i.e. imagine a `--mode` option which may *only* have one of two values `fast` or `slow` such as `--mode fast` or `--mode slow`)
|
||||
//! * **Default Values**: Although not specifically provided by `clap` you can achieve this exact functionality from Rust's `Option<&str>.unwrap_or("some default")` method (or `Result<T,String>.unwrap_or(T)` when using typed values)
|
||||
//! * **Automatic Version from Cargo.toml**: `clap` is fully compatible with Rust's `env!()` macro for automatically setting the version of your application to the version in your Cargo.toml. See [09_auto_version example](examples/09_auto_version.rs) for how to do this (Thanks to [jhelwig](https://github.com/jhelwig) for pointing this out)
|
||||
//! * **Typed Values**: You can use several convenience macros provided by `clap` to get typed values (i.e. `i32`, `u8`, etc.) from positional or option arguments so long as the type you request implements `std::str::FromStr` See the [12_typed_values example](examples/12_typed_values.rs). You can also use `clap`s `arg_enum!` macro to create an enum with variants that automatically implement `std::str::FromStr`. See [13a_enum_values_automatic example](examples/13a_enum_values_automatic.rs) for details
|
||||
//! * **Suggestions**: Suggests corrections when the user enters a typo. For example, if you defined a `--myoption` argument, and the user mistakenly typed `--moyption` (notice `y` and `o` transposed), they would receive a `Did you mean '--myoption' ?` error and exit gracefully. This also works for subcommands and flags. (Thanks to [Byron](https://github.com/Byron) for the implementation) (This feature can optionally be disabled, see 'Optional Dependencies / Features')
|
||||
//! * **Colorized Errors (Non Windows OS only)**: Error message are printed in in colored text (this feature can optionally be disabled, see 'Optional Dependencies / Features').
|
||||
//! * **Global Arguments**: Arguments can optionally be defined once, and be available to all child subcommands.
|
||||
//! * **Custom Validations**: You can define a function to use as a validator of argument values. Imagine defining a function to validate IP addresses, or fail parsing upon error. This means your application logic can be solely focused on *using* values.
|
||||
//! * **POSIX Compatible Conflicts** - In POSIX args can be conflicting, but not fail parsing because whichever arg comes *last* "wins" to to speak. This allows things such as aliases (i.e. `alias ls='ls -l'` but then using `ls -C` in your terminal which ends up passing `ls -l -C` as the final arguments. Since `-l` and `-C` aren't compatible, this effectively runs `ls -C` in `clap` if you choose...`clap` also supports hard conflicts that fail parsing). (Thanks to [Vinatorul](https://github.com/Vinatorul)!)
|
||||
//! * Supports the unix `--` meaning, only positional arguments follow
|
||||
//!
|
||||
//! ## Quick Example
|
||||
//!
|
||||
//! The following examples show a quick example of some of the very basic functionality of `clap`. For more advanced usage, such as requirements, conflicts, groups, multiple values and occurrences see the [documentation](http://kbknapp.github.io/clap-rs/clap/index.html), [examples/](examples) directory of this repository or the [video tutorials](https://www.youtube.com/playlist?list=PLza5oFLQGTl0Bc_EU_pBNcX-rhVqDTRxv) (which are quite outdated by now).
|
||||
|
|
@ -496,15 +344,6 @@
|
|||
//! * **"yaml"**: This is **not** included by default. Enables building CLIs from YAML documents.
|
||||
//! * **"unstable"**: This is **not** included by default. Enables unstable features, unstable refers to whether or not they may change, not performance stability.
|
||||
//!
|
||||
//! ### Dependencies Tree
|
||||
//!
|
||||
//! The following graphic depicts `clap`s dependency graph (generated using [cargo-graph](https://github.com/kbknapp/cargo-graph)).
|
||||
//!
|
||||
//! * **Dashed** Line: Optional dependency
|
||||
//! * **Red** Color: **NOT** included by default (must use cargo `features` to enable)
|
||||
//!
|
||||
//! 
|
||||
//!
|
||||
//! ### More Information
|
||||
//!
|
||||
//! You can find complete documentation on the [github-pages site](http://kbknapp.github.io/clap-rs/clap/index.html) for this project.
|
||||
|
|
@ -519,14 +358,6 @@
|
|||
//!
|
||||
//! *Note*: Apologies for the resolution of the first video, it will be updated to a better resolution soon. The other videos have a proper resolution.
|
||||
//!
|
||||
//! ## How to Contribute
|
||||
//!
|
||||
//! Contributions are always welcome! And there is a multitude of ways in which you can help depending on what you like to do, or are good at. Anything from documentation, code cleanup, issue completion, new features, you name it, even filing issues is contributing and greatly appreciated!
|
||||
//!
|
||||
//! Another really great way to help is if you find an interesting, or helpful way in which to use `clap`. You can either add it to the [examples/](examples) directory, or file an issue and tell me. I'm all about giving credit where credit is due :)
|
||||
//!
|
||||
//! Please read [CONTRIBUTING.md](CONTRIBUTING.md) before you start contributing.
|
||||
//!
|
||||
//! ### Running the tests
|
||||
//!
|
||||
//! If contributing, you can run the tests as follows (assuming you're in the `clap-rs` directory)
|
||||
|
|
@ -539,75 +370,9 @@
|
|||
//! $ cargo build --features lints
|
||||
//! ```
|
||||
//!
|
||||
//! ### Goals
|
||||
//!
|
||||
//! There are a few goals of `clap` that I'd like to maintain throughout contributions. If your proposed changes break, or go against any of these goals we'll discuss the changes further before merging (but will *not* be ignored, all contributes are welcome!). These are by no means hard-and-fast rules, as I'm no expert and break them myself from time to time (even if by mistake or ignorance :P).
|
||||
//!
|
||||
//! * Remain backwards compatible when possible
|
||||
//! - If backwards compatibility *must* be broken, use deprecation warnings if at all possible before removing legacy code
|
||||
//! - This does not apply for security concerns
|
||||
//! * Parse arguments quickly
|
||||
//! - Parsing of arguments shouldn't slow down usage of the main program
|
||||
//! - This is also true of generating help and usage information (although *slightly* less stringent, as the program is about to exit)
|
||||
//! * Try to be cognizant of memory usage
|
||||
//! - Once parsing is complete, the memory footprint of `clap` should be low since the main program is the star of the show
|
||||
//! * `panic!` on *developer* error, exit gracefully on *end-user* error
|
||||
//!
|
||||
//! ## License
|
||||
//!
|
||||
//! `clap` is licensed under the MIT license. Please read the [LICENSE-MIT](LICENSE-MIT) file in this repository for more information.
|
||||
//!
|
||||
//! ## Recent Breaking Changes
|
||||
//!
|
||||
//! `clap` follows semantic versioning, so breaking changes should only happen upon major version bumps. The only exception to this rule is breaking changes that happen due to implementation that was deemed to be a bug, security concerns, or it can be reasonably proved to affect no code. For the full details, see [CHANGELOG.md](./CHANGELOG.md).
|
||||
//!
|
||||
//! As of 2.0.0 (From 1.x)
|
||||
//!
|
||||
//! * **Fewer liftimes! Yay!**
|
||||
//! * `App<'a, 'b, 'c, 'd, 'e, 'f>` => `App<'a, 'b>`
|
||||
//! * `Arg<'a, 'b, 'c, 'd, 'e, 'f>` => `Arg<'a, 'b>`
|
||||
//! * `ArgMatches<'a, 'b>` => `ArgMatches<'a>`
|
||||
//! * **Simply Renamed**
|
||||
//! * `App::arg_group` => `App::group`
|
||||
//! * `App::arg_groups` => `App::groups`
|
||||
//! * `ArgGroup::add` => `ArgGroup::arg`
|
||||
//! * `ArgGroup::add_all` => `ArgGroup::args`
|
||||
//! * `ClapError` => `Error`
|
||||
//! * struct field `ClapError::error_type` => `Error::kind`
|
||||
//! * `ClapResult` => `Result`
|
||||
//! * `ClapErrorType` => `ErrorKind`
|
||||
//! * **Removed Deprecated Functions and Methods**
|
||||
//! * `App::subcommands_negate_reqs`
|
||||
//! * `App::subcommand_required`
|
||||
//! * `App::arg_required_else_help`
|
||||
//! * `App::global_version(bool)`
|
||||
//! * `App::versionless_subcommands`
|
||||
//! * `App::unified_help_messages`
|
||||
//! * `App::wait_on_error`
|
||||
//! * `App::subcommand_required_else_help`
|
||||
//! * `SubCommand::new`
|
||||
//! * `App::error_on_no_subcommand`
|
||||
//! * `Arg::new`
|
||||
//! * `Arg::mutually_excludes`
|
||||
//! * `Arg::mutually_excludes_all`
|
||||
//! * `Arg::mutually_overrides_with`
|
||||
//! * `simple_enum!`
|
||||
//! * **Renamed Error Variants**
|
||||
//! * `InvalidUnicode` => `InvalidUtf8`
|
||||
//! * `InvalidArgument` => `UnknownArgument`
|
||||
//! * **Usage Parser**
|
||||
//! * Value names can now be specified inline, i.e. `-o, --option <FILE> <FILE2> 'some option which takes two files'`
|
||||
//! * **There is now a priority of order to determine the name** - This is perhaps the biggest breaking change. See the documentation for full details. Prior to this change, the value name took precedence. **Ensure your args are using the proper names (i.e. typically the long or short and NOT the value name) throughout the code**
|
||||
//! * `ArgMatches::values_of` returns an `Values` now which implements `Iterator` (should not break any code)
|
||||
//! * `crate_version!` returns `&'static str` instead of `String`
|
||||
//!
|
||||
//! ### Deprecations
|
||||
//!
|
||||
//! Old method names will be left around for several minor version bumps, or one major version bump.
|
||||
//!
|
||||
//! As of 2.0.0:
|
||||
//!
|
||||
//! * None!
|
||||
|
||||
#![crate_type= "lib"]
|
||||
#![cfg_attr(feature = "nightly", feature(plugin))]
|
||||
|
|
@ -625,7 +390,7 @@
|
|||
// clippy false positives, or ones we're ok with...
|
||||
#![cfg_attr(feature = "lints", allow(cyclomatic_complexity))]
|
||||
// Only while bitflats uses "_first" inside it's macros
|
||||
#![cfg_attr(feature = "lints", allow(used_underscore_binding))]
|
||||
#![cfg_attr(feature = "lints", allow(used_underscore_binding))]
|
||||
|
||||
#[cfg(feature = "suggestions")]
|
||||
extern crate strsim;
|
||||
|
|
|
|||
|
|
@ -214,7 +214,7 @@ macro_rules! values_t_or_exit {
|
|||
|
||||
/// Convenience macro to generate more complete enums with variants to be used as a type when
|
||||
/// parsing arguments. This enum also provides a `variants()` function which can be used to
|
||||
/// retrieve a `Vec<&'static str>` of the variant names. As well as implementing `FromStr` and
|
||||
/// retrieve a `Vec<&'static str>` of the variant names, as well as implementing `FromStr` and
|
||||
/// `Display` automatically.
|
||||
///
|
||||
/// **NOTE:** Case insensitivity is supported for ASCII characters only
|
||||
|
|
|
|||
|
|
@ -83,7 +83,7 @@ fn invalid_utf8_lossy_positional() {
|
|||
assert!(r.is_ok());
|
||||
let m = r.unwrap();
|
||||
assert!(m.is_present("arg"));
|
||||
assert_eq!(&*m.lossy_value_of("arg").unwrap(), "\u{FFFD}");
|
||||
assert_eq!(&*m.value_of_lossy("arg").unwrap(), "\u{FFFD}");
|
||||
}
|
||||
|
||||
#[test]
|
||||
|
|
@ -96,7 +96,7 @@ fn invalid_utf8_lossy_option_short_space() {
|
|||
assert!(r.is_ok());
|
||||
let m = r.unwrap();
|
||||
assert!(m.is_present("arg"));
|
||||
assert_eq!(&*m.lossy_value_of("arg").unwrap(), "\u{FFFD}");
|
||||
assert_eq!(&*m.value_of_lossy("arg").unwrap(), "\u{FFFD}");
|
||||
}
|
||||
|
||||
#[test]
|
||||
|
|
@ -108,7 +108,7 @@ fn invalid_utf8_lossy_option_short_equals() {
|
|||
assert!(r.is_ok());
|
||||
let m = r.unwrap();
|
||||
assert!(m.is_present("arg"));
|
||||
assert_eq!(&*m.lossy_value_of("arg").unwrap(), "\u{FFFD}");
|
||||
assert_eq!(&*m.value_of_lossy("arg").unwrap(), "\u{FFFD}");
|
||||
}
|
||||
|
||||
#[test]
|
||||
|
|
@ -120,7 +120,7 @@ fn invalid_utf8_lossy_option_short_no_space() {
|
|||
assert!(r.is_ok());
|
||||
let m = r.unwrap();
|
||||
assert!(m.is_present("arg"));
|
||||
assert_eq!(&*m.lossy_value_of("arg").unwrap(), "\u{FFFD}");
|
||||
assert_eq!(&*m.value_of_lossy("arg").unwrap(), "\u{FFFD}");
|
||||
}
|
||||
|
||||
#[test]
|
||||
|
|
@ -133,7 +133,7 @@ fn invalid_utf8_lossy_option_long_space() {
|
|||
assert!(r.is_ok());
|
||||
let m = r.unwrap();
|
||||
assert!(m.is_present("arg"));
|
||||
assert_eq!(&*m.lossy_value_of("arg").unwrap(), "\u{FFFD}");
|
||||
assert_eq!(&*m.value_of_lossy("arg").unwrap(), "\u{FFFD}");
|
||||
}
|
||||
|
||||
#[test]
|
||||
|
|
@ -145,7 +145,7 @@ fn invalid_utf8_lossy_option_long_equals() {
|
|||
assert!(r.is_ok());
|
||||
let m = r.unwrap();
|
||||
assert!(m.is_present("arg"));
|
||||
assert_eq!(&*m.lossy_value_of("arg").unwrap(), "\u{FFFD}");
|
||||
assert_eq!(&*m.value_of_lossy("arg").unwrap(), "\u{FFFD}");
|
||||
}
|
||||
|
||||
#[test]
|
||||
|
|
@ -157,7 +157,7 @@ fn invalid_utf8_positional() {
|
|||
assert!(r.is_ok());
|
||||
let m = r.unwrap();
|
||||
assert!(m.is_present("arg"));
|
||||
assert_eq!(&*m.os_value_of("arg").unwrap(), &*OsString::from_vec(vec![0xe9]));
|
||||
assert_eq!(&*m.value_of_os("arg").unwrap(), &*OsString::from_vec(vec![0xe9]));
|
||||
}
|
||||
|
||||
#[test]
|
||||
|
|
@ -170,7 +170,7 @@ fn invalid_utf8_option_short_space() {
|
|||
assert!(r.is_ok());
|
||||
let m = r.unwrap();
|
||||
assert!(m.is_present("arg"));
|
||||
assert_eq!(&*m.os_value_of("arg").unwrap(), &*OsString::from_vec(vec![0xe9]));
|
||||
assert_eq!(&*m.value_of_os("arg").unwrap(), &*OsString::from_vec(vec![0xe9]));
|
||||
}
|
||||
|
||||
#[test]
|
||||
|
|
@ -182,7 +182,7 @@ fn invalid_utf8_option_short_equals() {
|
|||
assert!(r.is_ok());
|
||||
let m = r.unwrap();
|
||||
assert!(m.is_present("arg"));
|
||||
assert_eq!(&*m.os_value_of("arg").unwrap(), &*OsString::from_vec(vec![0xe9]));
|
||||
assert_eq!(&*m.value_of_os("arg").unwrap(), &*OsString::from_vec(vec![0xe9]));
|
||||
}
|
||||
|
||||
#[test]
|
||||
|
|
@ -194,7 +194,7 @@ fn invalid_utf8_option_short_no_space() {
|
|||
assert!(r.is_ok());
|
||||
let m = r.unwrap();
|
||||
assert!(m.is_present("arg"));
|
||||
assert_eq!(&*m.os_value_of("arg").unwrap(), &*OsString::from_vec(vec![0xe9]));
|
||||
assert_eq!(&*m.value_of_os("arg").unwrap(), &*OsString::from_vec(vec![0xe9]));
|
||||
}
|
||||
|
||||
#[test]
|
||||
|
|
@ -207,7 +207,7 @@ fn invalid_utf8_option_long_space() {
|
|||
assert!(r.is_ok());
|
||||
let m = r.unwrap();
|
||||
assert!(m.is_present("arg"));
|
||||
assert_eq!(&*m.os_value_of("arg").unwrap(), &*OsString::from_vec(vec![0xe9]));
|
||||
assert_eq!(&*m.value_of_os("arg").unwrap(), &*OsString::from_vec(vec![0xe9]));
|
||||
}
|
||||
|
||||
#[test]
|
||||
|
|
@ -219,5 +219,5 @@ fn invalid_utf8_option_long_equals() {
|
|||
assert!(r.is_ok());
|
||||
let m = r.unwrap();
|
||||
assert!(m.is_present("arg"));
|
||||
assert_eq!(&*m.os_value_of("arg").unwrap(), &*OsString::from_vec(vec![0xe9]));
|
||||
assert_eq!(&*m.value_of_os("arg").unwrap(), &*OsString::from_vec(vec![0xe9]));
|
||||
}
|
||||
|
|
|
|||
Loading…
Reference in a new issue