diff --git a/src/_derive/_tutorial.rs b/src/_derive/_tutorial.rs index 3579596d..77f35024 100644 --- a/src/_derive/_tutorial.rs +++ b/src/_derive/_tutorial.rs @@ -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 diff --git a/src/_derive/mod.rs b/src/_derive/mod.rs index 2f5f97a0..a8b53815 100644 --- a/src/_derive/mod.rs +++ b/src/_derive/mod.rs @@ -186,7 +186,6 @@ //! - `value_parser [= ]`: [`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 [= ]`: [`Arg::action`][crate::Arg::action] //! - When not present: will auto-select an action based on the field type //! - `help = `: [`Arg::help`][crate::Arg::help] @@ -254,19 +253,22 @@ //! //! `clap` assumes some intent based on the type used: //! -//! | Type | Effect | Implies | -//! |---------------------|--------------------------------------|--------------------------------------------------------------------------| -//! | `bool` | flag | `.action(ArgAction::SetTrue) | -//! | `Option` | optional argument | `.action(ArgAction::Set).required(false)` | -//! | `Option>` | 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` | `0..` occurrences of argument | `.action(ArgAction::Append).required(false).multiple_occurrences(true)` | -//! | `Option>` | `0..` occurrences of argument | `.action(ArgAction::Append).required(false).multiple_occurrences(true)` | +//! | Type | Effect | Implies | +//! |---------------------|--------------------------------------|-------------------------------------------------------------| +//! | `bool` | flag | `.action(ArgAction::SetTrue) | +//! | `Option` | optional argument | `.action(ArgAction::Set).required(false)` | +//! | `Option>` | optional value for optional argument | `.action(ArgAction::Set).required(false).num_args(0..=1)` | +//! | `T` | required argument | `.action(ArgAction::Set).required(!has_default)` | +//! | `Vec` | `0..` occurrences of argument | `.action(ArgAction::Append).required(false).num_args(1..)` | +//! | `Option>` | `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 //! - `Option>` 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 //! diff --git a/src/_tutorial.rs b/src/_tutorial.rs index cdb96ba1..67b77271 100644 --- a/src/_tutorial.rs +++ b/src/_tutorial.rs @@ -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 diff --git a/src/builder/arg.rs b/src/builder/arg.rs index dce3794b..de92d3a3 100644 --- a/src/builder/arg.rs +++ b/src/builder/arg.rs @@ -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` + /// - `[&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") diff --git a/src/builder/value_parser.rs b/src/builder/value_parser.rs index 8fa6cc4d..c5b97061 100644 --- a/src/builder/value_parser.rs +++ b/src/builder/value_parser.rs @@ -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` /// - [`EnumValueParser`] and [`PossibleValuesParser`] for static enumerated values /// - [`BoolishValueParser`] and [`FalseyValueParser`] for alternative `bool` implementations /// - [`RangedI64ValueParser`] and [`RangedU64ValueParser`] @@ -989,7 +988,8 @@ impl 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);