Mirrors/clap
2
0
Fork 0
mirror of https://github.com/clap-rs/clap synced 2024-12-14 06:42:33 +00:00
Code Issues Projects Releases Packages Wiki Activity

Merge pull request #4244 from epage/docs

Browse source 
docs: Clarify value parser
This commit is contained in:
Ed Page 2022-09-21 11:34:38 -05:00 committed by GitHub
commit 32637d4d09
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
8 changed files with 44 additions and 109 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

5
Cargo.toml
View file

@ -350,11 +350,6 @@ path = "examples/tutorial_derive/05_01_assert.rs"
required-features = ["derive"]
test = true
[[example]]
name = "custom-bool"
path = "examples/derive_ref/custom-bool.rs"
required-features = ["derive"]
[[example]]
name = "interop_augment_args"
path = "examples/derive_ref/augment_args.rs"

44
examples/derive_ref/custom-bool.md
View file

@ -1,44 +0,0 @@
*Jump to [source](custom-bool.rs)*
Example of overriding the magic `bool` behavior
```console
$ custom-bool --help
A simple to use, efficient, and full-featured Command Line Argument Parser
Usage: custom-bool[EXE] [OPTIONS] --foo <FOO> <BOOM>
Arguments:
<BOOM> [possible values: true, false]
Options:
--foo <FOO> [possible values: true, false]
--bar <BAR> [default: false]
-h, --help Print help information
-V, --version Print version information
$ custom-bool
? failed
error: The following required arguments were not provided:
--foo <FOO>
<BOOM>
Usage: custom-bool[EXE] --foo <FOO> <BOOM>
For more information try '--help'
$ custom-bool --foo true false
[examples/derive_ref/custom-bool.rs:31] opt = Opt {
foo: true,
bar: false,
boom: false,
}
$ custom-bool --foo true --bar true false
[examples/derive_ref/custom-bool.rs:31] opt = Opt {
foo: true,
bar: true,
boom: false,
}
```

32
examples/derive_ref/custom-bool.rs
View file

@ -1,32 +0,0 @@
use clap::Parser;
#[derive(Parser, Debug, PartialEq)]
#[command(author, version, about, long_about = None)]
struct Opt {
// Default parser for `Set` is FromStr::from_str.
// `impl FromStr for bool` parses `true` or `false` so this
// works as expected.
#[arg(long, action = clap::ArgAction::Set)]
foo: bool,
// Of course, this could be done with an explicit parser function.
#[arg(long, action = clap::ArgAction::Set, value_parser = true_or_false, default_value_t)]
bar: bool,
// `bool` can be positional only with explicit `action` annotation
#[arg(action = clap::ArgAction::Set)]
boom: bool,
}
fn true_or_false(s: &str) -> Result<bool, &'static str> {
match s {
"true" => Ok(true),
"false" => Ok(false),
_ => Err("expected `true` or `false`"),
}
}
fn main() {
let opt = Opt::parse();
dbg!(opt);
}

7
src/_derive/_tutorial.rs
View file

@ -154,9 +154,12 @@
//!
//! ## Validation
//!
//! An appropriate default parser/validator will be selected for the field's type. See
//! [`value_parser!][crate::value_parser!] for more details.
//!
//! ### Enumerated values
//!
//! If you have arguments of specific values you want to test for, you can derive
//! For example, if you have arguments of specific values you want to test for, you can derive
//! [`ValueEnum`][crate::ValueEnum].
//!
//! This allows you specify the valid values for that argument. If the user does not use one of
@ -184,6 +187,8 @@
//! ```
#![doc = include_str!("../../examples/tutorial_derive/04_02_validate.md")]
//!
//! See [`Arg::value_parser`][crate::Arg::value_parser] for more details.
//!
//! ### Argument Relations
//!
//! You can declare dependencies or conflicts between [`Arg`][crate::Arg]s or even

23
src/_derive/mod.rs
View file

@ -186,7 +186,6 @@
//! - `value_parser [= <expr>]`: [`Arg::value_parser`][crate::Arg::value_parser]
//! - When not present: will auto-select an implementation based on the field type using
//! [`value_parser!`][crate::value_parser!]
//! - To register a custom type's [`ValueParser`][crate::builder::ValueParser], implement [`ValueParserFactory`][crate::builder::ValueParserFactory]
//! - `action [= <expr>]`: [`Arg::action`][crate::Arg::action]
//! - When not present: will auto-select an action based on the field type
//! - `help = <expr>`: [`Arg::help`][crate::Arg::help]
@ -254,20 +253,22 @@
//!
//! `clap` assumes some intent based on the type used:
//!
//! | Type | Effect | Implies |
//! |---------------------|--------------------------------------|--------------------------------------------------------------------------|
//! | `bool` | flag | `.action(ArgAction::SetTrue) |
//! | `Option<T>` | optional argument | `.action(ArgAction::Set).required(false)` |
//! | `Option<Option<T>>` | optional value for optional argument | `.action(ArgAction::Set).required(false).min_values(0).max_values(1)` |
//! | `T` | required argument | `.action(ArgAction::Set).required(!has_default)` |
//! | `Vec<T>` | `0..` occurrences of argument | `.action(ArgAction::Append).required(false).multiple_occurrences(true)` |
//! | `Option<Vec<T>>` | `0..` occurrences of argument | `.action(ArgAction::Append).required(false).multiple_occurrences(true)` |
//! | Type | Effect | Implies |
//! |---------------------|--------------------------------------|-------------------------------------------------------------|
//! | `bool` | flag | `.action(ArgAction::SetTrue) |
//! | `Option<T>` | optional argument | `.action(ArgAction::Set).required(false)` |
//! | `Option<Option<T>>` | optional value for optional argument | `.action(ArgAction::Set).required(false).num_args(0..=1)` |
//! | `T` | required argument | `.action(ArgAction::Set).required(!has_default)` |
//! | `Vec<T>` | `0..` occurrences of argument | `.action(ArgAction::Append).required(false).num_args(1..)` |
//! | `Option<Vec<T>>` | `0..` occurrences of argument | `.action(ArgAction::Append).required(false).num_args(1..)` |
//!
//! In addition, [`.value_parser(value_parser!(T))`][crate::value_parser!] is called for each
//! field.
//!
//! Notes:
//! - For custom type behavior, you can override the implied attributes/settings and/or set additional ones
//! - For example, see [custom-bool](./custom-bool.md)
//! - `Option<Vec<T>>` will be `None` instead of `vec![]` if no arguments are provided.
//! - This gives the user some flexibility in designing their argument, like with `min_values(0)`
//! - This gives the user some flexibility in designing their argument, like with `num_args(0..)`
//!
//! ## Doc Comments
//!

4
src/_tutorial.rs
View file

@ -143,6 +143,8 @@
//!
//! ## Validation
//!
//! By default, arguments are assumed to be `String`s and only UTF-8 validation is performed.
//!
//! ### Enumerated values
//!
//! If you have arguments of specific values you want to test for, you can use the
@ -183,6 +185,8 @@
//! ```
#![doc = include_str!("../examples/tutorial_builder/04_02_validate.md")]
//!
//! See [`Arg::value_parser`][crate::Arg::value_parser] for more details.
//!
//! ### Argument Relations
//!
//! You can declare dependencies or conflicts between [`Arg`][crate::Arg]s or even

21
src/builder/arg.rs
View file

@ -867,21 +867,22 @@ impl Arg {
self
}
/// Specify the type of the argument.
/// Specify the typed behavior of the argument.
///
/// This allows parsing and validating a value before storing it into
/// [`ArgMatches`][crate::ArgMatches].
/// [`ArgMatches`][crate::ArgMatches] as the given type.
///
/// Possible value parsers include:
/// - [`value_parser!(T)`][crate::value_parser!] for auto-selecting a value parser for a given type
/// - Or [range expressions like `0..=1`][std::ops::RangeBounds] as a shorthand for [`RangedI64ValueParser`][crate::builder::RangedI64ValueParser]
/// - `Fn(&str) -> Result<T, E>`
/// - `[&str]` and [`PossibleValuesParser`][crate::builder::PossibleValuesParser] for static enumerated values
/// - [`BoolishValueParser`][crate::builder::BoolishValueParser], and [`FalseyValueParser`][crate::builder::FalseyValueParser] for alternative `bool` implementations
/// - [`NonEmptyStringValueParser`][crate::builder::NonEmptyStringValueParser] for basic validation for strings
/// - or any other [`TypedValueParser`][crate::builder::TypedValueParser] implementation
///
/// The default value is [`ValueParser::string`][crate::builder::ValueParser::string].
///
/// See also
/// - [`value_parser!`][crate::value_parser!] for auto-selecting a value parser for a given type
/// - [`BoolishValueParser`][crate::builder::BoolishValueParser], and [`FalseyValueParser`][crate::builder::FalseyValueParser] for alternative `bool` implementations
/// - [`NonEmptyStringValueParser`][crate::builder::NonEmptyStringValueParser] for basic validation for strings
/// - [`RangedI64ValueParser`][crate::builder::RangedI64ValueParser] and [`RangedU64ValueParser`][crate::builder::RangedU64ValueParser] for numeric ranges
/// - [`EnumValueParser`][crate::builder::EnumValueParser] and [`PossibleValuesParser`][crate::builder::PossibleValuesParser] for static enumerated values
/// - or any other [`TypedValueParser`][crate::builder::TypedValueParser] implementation
///
/// ```rust
/// # use clap::ArgAction;
/// let mut cmd = clap::Command::new("raw")

17
src/builder/value_parser.rs
View file

@ -73,9 +73,8 @@ enum ValueParserInner {
impl ValueParser {
/// Custom parser for argument values
///
/// To create a custom parser, see [`TypedValueParser`]
///
/// Pre-existing implementations include:
/// Pre-existing [`TypedValueParser`] implementations include:
/// - `Fn(&str) -> Result<T, E>`
/// - [`EnumValueParser`] and [`PossibleValuesParser`] for static enumerated values
/// - [`BoolishValueParser`] and [`FalseyValueParser`] for alternative `bool` implementations
/// - [`RangedI64ValueParser`] and [`RangedU64ValueParser`]
@ -989,7 +988,8 @@ impl<E: crate::ValueEnum + Clone + Send + Sync + 'static> Default for EnumValueP
/// Verify the value is from an enumerated set of [`PossibleValue`][crate::builder::PossibleValue].
///
/// See also:
/// - [`EnumValueParser`]
/// - [`EnumValueParser`] for directly supporting `enum`s
/// - [`TypedValueParser::map`] for adapting values to a more specialized type
///
/// # Example
///
@ -2083,7 +2083,12 @@ pub mod via_prelude {
/// Select a [`ValueParser`] implementation from the intended type
///
/// To register a custom type with this macro, implement [`ValueParserFactory`].
/// Supported types
/// - [`ValueParserFactory` types][ValueParserFactory], including
/// - [Native types][ValueParser]: `bool`, `String`, `OsString`, `PathBuf`
/// - [Ranged numeric types][RangedI64ValueParser]: `u8`, `i8`, `u16`, `i16, `u32`, `i32`, `u64`, `i64`
/// - [`ValueEnum` types][crate::ValueEnum]
/// - [`FromStr` types][std::str::FromStr], including usize, isize
///
/// # Example
///
@ -2104,7 +2109,7 @@ pub mod via_prelude {
/// assert_eq!(port, Path::new("file.txt"));
/// ```
///
/// Supported types:
/// Example mappings:
/// ```rust
/// // Built-in types
/// let parser = clap::value_parser!(String);