Unable to use Command::format from implementation of TypedValueParser because of mutability

[eirnym]

I have a custom enum type (doesn't really matter in this case) which is parsed and produces custom error which I'd like to print to the user.

When I use clap::Error::raw(ErrorKind::ValueValidation, err).with_cmd(cmd) and other context, no newline will be inserted on error, which is far than ideal.

So by reading the code, the preferred method should be using cmd.error(ErrorKind::ValueValidation, err), but I'm unable to because TypedValueParser provides only readonly cmd object. I can clone it to have a mutable version, but clap would be surprised to say the least. Output will be correct though.

I suggest to create a temporary trait or change it for new major version.

PS: I also suggest to add a test with implementation of custom types (e.g. enums with a value, etc) for interfaces to show how it should be implemented from a user side.

pub MyEnum {
  Valued(u8),
  AdditionalValue,
}

pub enum MyParseError {
  NotU8
}

impl FromStr for MyEnum { /*....*/ } // obvious thing to implement, but will obscure the example below
imp Display for MyParseError { /*....*/ } // obvious thing to implement, but will obscure the example below

struct MyEnumParser {} // can't be the same enum 

impl ValueParserFactory for MyEnum {
    type Parser = MyEnumParser;

    fn value_parser() -> Self::Parser {
        MyEnumParser {}
    }
}

impl TypedValueParser for MyEnumParser {
    type Value = GradleVersion;

    fn parse_ref(
        &self,
        cmd: &clap::Command,
        arg: Option<&clap::Arg>,
        value: &std::ffi::OsStr,
    ) -> Result<Self::Value, clap::Error> {
        match value.to_str() {
            Some(text) => MyEnum::from_str(text).map_err(move |err| {
                let mut clap_error = cmd.error(ErrorKind::ValueValidation, err); // This won't ever compile because of API 
                if let Some(arg) = arg {
                    clap_error.insert(
                        ContextKind::InvalidArg,
                        ContextValue::String(arg.to_string()),
                    );
                }

                clap_error
            }),
            None => Err(clap::Error::new(ErrorKind::InvalidUtf8)),
        }
    }
}

[epage]

Relevant discussions

• Error message APIs for TypedValueParser #5065
• Is it possible to print a consistent error message from a TypedValueParser? #4140

Sounds like in your case, the crux of the problem is:

When I use clap::Error::raw(ErrorKind::ValueValidation, err).with_cmd(cmd) and other context, no newline will be inserted on error, which is far than ideal.

Could you expand on that more?

Note that Command::error and Error::raw create a complete error message which overrides any context that gets inserted, see

clap/clap_builder/src/error/mod.rs

Lines 808 to 814 in 2c04acd

	fn formatted(&self) -> Cow<'_, StyledStr> {
	if let Some(message) = self.inner.message.as_ref() {
	message.formatted(&self.inner.styles)
	} else {
	let styled = F::format_error(self);
	Cow::Owned(styled)
	}

[eirnym]

Thank you for links above.

I use derive, so I don't see all mechanics beneath.

I have following notes and questions better to be addressed in official documentation.

1. I've read sparse documentation clap has for custom fields and parsers including code. I prefer to read it on site (docs + example) rather than in code. I like reverse engineering, but I prefer to read documentation if available.
2. Parser doesn't need to know anything about formatting. At all. In any place of an application or library.
3. Ideally, returning a custom message should be as easy as possible. Taking interface Error::raw(kind, message) — is an ideal for that case. Clap should do formatting later. It's still not a responsibility of a value parser.
4. I genuinely don't understand why cmd.error(...) needs cmd to be mutable. Digging further, why cmd needs to be built on the late stage, while we parsing parameters. It should be built already before.
5. I don't understand and there's no explanation (I'd better ask than dig too deep into clap history) why parser is stateful in other words, why it needs &self. In that case I can't implement it for a type I would parse. In most interfaces I've seen in Rust, Java, Python and other languages parser is stateless.
6. In most cases if a type implements FromStr or FromOsStr, a typical generic parser can be used. There's no reason to write my own.
7. Examples and documentation are crucial. (I repeating my self, but it's important).

FYI: Currently I've ended up with cloning cmd (cmd.clone().error(...)), but cloning cmd is a workaround I'd like to avoid by any cost if possible.

[epage]

Parser doesn't need to know anything about formatting. At all. In any place of an application or library.

That is reasonable for a file format like toml or for a general type inside of a library. Whats different here is that TypedValueParser is wrapping any of that to directly interface with the real world, the user. There needs to be some way to take what is provided from lower layers and decide how to show it to users.

I genuinely don't understand why cmd.error(...) needs cmd to be mutable. Digging further, why cmd needs to be built on the late stage, while we parsing parameters. It should be built already before.

It would be good to document the context for this. #6125 does so.

I don't understand and there's no explanation (I'd better ask than dig too deep into clap history) why parser is stateful in other words, why it needs &self. In that case I can't implement it for a type I would parse. In most interfaces I've seen in Rust, Java, Python and other languages parser is stateless.

This allows for general parsers that can be configured to your needs, e.g.

• PossibleValuesParser which allows specifying &["always", "auto", "never"]
• RangedI64ValueParser which allows specifying the valid range like 16..32
• TypedValueParser::try_map which you can use to extend an existing parser with more functionality

The documentation for Arg::value_parser gives two examples of stateful TypedValueParsers.

For associating a parser with a type, we offer ValueParserFactory

In most cases if a type implements FromStr or FromOsStr, a typical generic parser can be used. There's no reason to write my own.

We do support FromStr and several other traits. However, FromOsStr does not exist.

Now, how we document this could likely be improved. I'm looking around now

• In our tutorial, we say that we'll generally pick an appropriate parser/validator and point to value_parser! for more details.
• In our derive reference, we explain that in the absence of #[arg(value_parser)] we'll use determine what to use with value_parser!.
• Later in our derive reference we point to value_parser! for implicit behavior based on the type.

I made a small tweak in #6125. If you have thoughts on how to clarify the wording, I'd be open. It would reduce layers of indirection of we laid out all of these details up front but I'm trying to balance approachability with maintainability due to my limited time and we're also trying to help people understand the principles of how things operate so they can more easily reason about things and apply them in ways we don't consider how to write.

Examples and documentation are crucial. (I repeating my self, but it's important).

In terms of examples, we have

• Our tutorial showing how to write a custom parser
• A cookbook entry devoted to different type shenanigans
• Builder examples for Arg::value_parser, value_parser!, etc with the reference and the tutorial commenting about the relationship between the derive and the builder

Yes, it would be ideal if we forked all of our documentation to reduce the need for knowing the builder API when it comes to the derive. See above about our balancing of needs and #4090.

FYI: Currently I've ended up with cloning cmd (cmd.clone().error(...)), but cloning cmd is a workaround I'd like to avoid by any cost if possible.

There are likely ways around this but there seems to be a lack of context in what you are trying to accomplish for me to provide guidance on what to do. I asked for more in my previous post. If you are interested, feel free to respond to that question.

[eirnym]

Thank you for documentation links and improvement for Command and examples when TypedValueParser could have state.

I still curious in which cases cmd might have an invalid state? If it's incorrect usage, why not to return Result<> or even panic?

Could you please add a task to add a complex example with TypedValueParser implementation. I've chosen it because of another issue on complex enums and ValueEnum support and currently there's no guidance how to write it. To confirm about possible_values I had to grep code, which is less than ideal.

In my particular case I've implemented FromStr because I can test it. How would I test TypedValueParser?

How to make output the same between custom implementation and official implementation?

pure FromStr (I loose possible_values implementation) output:

error: invalid value 'test' for '--param <PARAM>': Version major part is not u8

For more information, try '--help'.

my implementation:

error: Version major part is not u8

Usage: app cmd [OPTIONS]

For more information, try '--help'.

PS: I understand how hard to document such project properly and don't spend too much time on it! I really appreciate your help with

[epage]

I still curious in which cases cmd might have an invalid state? If it's incorrect usage, why not to return Result<> or even panic?

We are ensuring the following has been run:

• clap/clap_builder/src/builder/command.rs

  Lines 4375 to 4687 in 7566762

  	/// Prepare for introspecting on all included [`Command`]s
  	///
  	/// Call this on the top-level [`Command`] when done building and before reading state for
  	/// cases like completions, custom help output, etc.
  	pub fn build(&mut self) {
  	self._build_recursive(true);
  	self._build_bin_names_internal();
  	}
  	pub(crate) fn _build_recursive(&mut self, expand_help_tree: bool) {
  	self._build_self(expand_help_tree);
  	for subcmd in self.get_subcommands_mut() {
  	subcmd._build_recursive(expand_help_tree);
  	}
  	}
  	pub(crate) fn _build_self(&mut self, expand_help_tree: bool) {
  	debug!("Command::_build: name={:?}", self.get_name());
  	if !self.settings.is_set(AppSettings::Built) {
  	if let Some(deferred) = self.deferred.take() {
  	*self = (deferred)(std::mem::take(self));
  	}
  	// Make sure all the globally set flags apply to us as well
  	self.settings = self.settings | self.g_settings;
  	if self.is_multicall_set() {
  	self.settings.set(AppSettings::SubcommandRequired);
  	self.settings.set(AppSettings::DisableHelpFlag);
  	self.settings.set(AppSettings::DisableVersionFlag);
  	}
  	if !cfg!(feature = "help") && self.get_override_help().is_none() {
  	self.settings.set(AppSettings::DisableHelpFlag);
  	self.settings.set(AppSettings::DisableHelpSubcommand);
  	}
  	if self.is_set(AppSettings::ArgsNegateSubcommands) {
  	self.settings.set(AppSettings::SubcommandsNegateReqs);
  	}
  	if self.external_value_parser.is_some() {
  	self.settings.set(AppSettings::AllowExternalSubcommands);
  	}
  	if !self.has_subcommands() {
  	self.settings.set(AppSettings::DisableHelpSubcommand);
  	}
  	self._propagate();
  	self._check_help_and_version(expand_help_tree);
  	self._propagate_global_args();
  	let mut pos_counter = 1;
  	let hide_pv = self.is_set(AppSettings::HidePossibleValues);
  	for a in self.args.args_mut() {
  	// Fill in the groups
  	for g in &a.groups {
  	if let Some(ag) = self.groups.iter_mut().find(|grp| grp.id == *g) {
  	ag.args.push(a.get_id().clone());
  	} else {
  	let mut ag = ArgGroup::new(g);
  	ag.args.push(a.get_id().clone());
  	self.groups.push(ag);
  	}
  	}
  	// Figure out implied settings
  	a._build();
  	if hide_pv && a.is_takes_value_set() {
  	a.settings.set(ArgSettings::HidePossibleValues);
  	}
  	if a.is_positional() && a.index.is_none() {
  	a.index = Some(pos_counter);
  	pos_counter += 1;
  	}
  	}
  	self.args._build();
  	#[allow(deprecated)]
  	{
  	let highest_idx = self
  	.get_keymap()
  	.keys()
  	.filter_map(|x| {
  	if let crate::mkeymap::KeyType::Position(n) = x {
  	Some(*n)
  	} else {
  	None
  	}
  	})
  	.max()
  	.unwrap_or(0);
  	let is_trailing_var_arg_set = self.is_trailing_var_arg_set();
  	let is_allow_hyphen_values_set = self.is_allow_hyphen_values_set();
  	let is_allow_negative_numbers_set = self.is_allow_negative_numbers_set();
  	for arg in self.args.args_mut() {
  	if is_allow_hyphen_values_set && arg.is_takes_value_set() {
  	arg.settings.set(ArgSettings::AllowHyphenValues);
  	}
  	if is_allow_negative_numbers_set && arg.is_takes_value_set() {
  	arg.settings.set(ArgSettings::AllowNegativeNumbers);
  	}
  	if is_trailing_var_arg_set && arg.get_index() == Some(highest_idx) {
  	arg.settings.set(ArgSettings::TrailingVarArg);
  	}
  	}
  	}
  	#[cfg(debug_assertions)]
  	assert_app(self);
  	self.settings.set(AppSettings::Built);
  	} else {
  	debug!("Command::_build: already built");
  	}
  	}
  	pub(crate) fn _build_subcommand(&mut self, name: &str) -> Option<&mut Self> {
  	use std::fmt::Write;
  	let mut mid_string = String::from(" ");
  	#[cfg(feature = "usage")]
  	if !self.is_subcommand_negates_reqs_set() && !self.is_args_conflicts_with_subcommands_set()
  	{
  	let reqs = Usage::new(self).get_required_usage_from(&[], None, true); // maybe Some(m)
  	for s in &reqs {
  	mid_string.push_str(&s.to_string());
  	mid_string.push(' ');
  	}
  	}
  	let is_multicall_set = self.is_multicall_set();
  	let sc = some!(self.subcommands.iter_mut().find(|s| s.name == name));
  	// Display subcommand name, short and long in usage
  	let mut sc_names = String::new();
  	sc_names.push_str(sc.name.as_str());
  	let mut flag_subcmd = false;
  	if let Some(l) = sc.get_long_flag() {
  	write!(sc_names, "|--{l}").unwrap();
  	flag_subcmd = true;
  	}
  	if let Some(s) = sc.get_short_flag() {
  	write!(sc_names, "|-{s}").unwrap();
  	flag_subcmd = true;
  	}
  	if flag_subcmd {
  	sc_names = format!("{{{sc_names}}}");
  	}
  	let usage_name = self
  	.bin_name
  	.as_ref()
  	.map(|bin_name| format!("{bin_name}{mid_string}{sc_names}"))
  	.unwrap_or(sc_names);
  	sc.usage_name = Some(usage_name);
  	// bin_name should be parent's bin_name + [<reqs>] + the sc's name separated by
  	// a space
  	let bin_name = format!(
  	"{}{}{}",
  	self.bin_name.as_deref().unwrap_or_default(),
  	if self.bin_name.is_some() { " " } else { "" },
  	&*sc.name
  	);
  	debug!(
  	"Command::_build_subcommand Setting bin_name of {} to {:?}",
  	sc.name, bin_name
  	);
  	sc.bin_name = Some(bin_name);
  	if sc.display_name.is_none() {
  	let self_display_name = if is_multicall_set {
  	self.display_name.as_deref().unwrap_or("")
  	} else {
  	self.display_name.as_deref().unwrap_or(&self.name)
  	};
  	let display_name = format!(
  	"{}{}{}",
  	self_display_name,
  	if !self_display_name.is_empty() {
  	"-"
  	} else {
  	""
  	},
  	&*sc.name
  	);
  	debug!(
  	"Command::_build_subcommand Setting display_name of {} to {:?}",
  	sc.name, display_name
  	);
  	sc.display_name = Some(display_name);
  	}
  	// Ensure all args are built and ready to parse
  	sc._build_self(false);
  	Some(sc)
  	}
  	fn _build_bin_names_internal(&mut self) {
  	debug!("Command::_build_bin_names");
  	if !self.is_set(AppSettings::BinNameBuilt) {
  	let mut mid_string = String::from(" ");
  	#[cfg(feature = "usage")]
  	if !self.is_subcommand_negates_reqs_set()
  	&& !self.is_args_conflicts_with_subcommands_set()
  	{
  	let reqs = Usage::new(self).get_required_usage_from(&[], None, true); // maybe Some(m)
  	for s in &reqs {
  	mid_string.push_str(&s.to_string());
  	mid_string.push(' ');
  	}
  	}
  	let is_multicall_set = self.is_multicall_set();
  	let self_bin_name = if is_multicall_set {
  	self.bin_name.as_deref().unwrap_or("")
  	} else {
  	self.bin_name.as_deref().unwrap_or(&self.name)
  	}
  	.to_owned();
  	for sc in &mut self.subcommands {
  	debug!("Command::_build_bin_names:iter: bin_name set...");
  	if sc.usage_name.is_none() {
  	use std::fmt::Write;
  	// Display subcommand name, short and long in usage
  	let mut sc_names = String::new();
  	sc_names.push_str(sc.name.as_str());
  	let mut flag_subcmd = false;
  	if let Some(l) = sc.get_long_flag() {
  	write!(sc_names, "|--{l}").unwrap();
  	flag_subcmd = true;
  	}
  	if let Some(s) = sc.get_short_flag() {
  	write!(sc_names, "|-{s}").unwrap();
  	flag_subcmd = true;
  	}
  	if flag_subcmd {
  	sc_names = format!("{{{sc_names}}}");
  	}
  	let usage_name = format!("{self_bin_name}{mid_string}{sc_names}");
  	debug!(
  	"Command::_build_bin_names:iter: Setting usage_name of {} to {:?}",
  	sc.name, usage_name
  	);
  	sc.usage_name = Some(usage_name);
  	} else {
  	debug!(
  	"Command::_build_bin_names::iter: Using existing usage_name of {} ({:?})",
  	sc.name, sc.usage_name
  	);
  	}
  	if sc.bin_name.is_none() {
  	let bin_name = format!(
  	"{}{}{}",
  	self_bin_name,
  	if !self_bin_name.is_empty() { " " } else { "" },
  	&*sc.name
  	);
  	debug!(
  	"Command::_build_bin_names:iter: Setting bin_name of {} to {:?}",
  	sc.name, bin_name
  	);
  	sc.bin_name = Some(bin_name);
  	} else {
  	debug!(
  	"Command::_build_bin_names::iter: Using existing bin_name of {} ({:?})",
  	sc.name, sc.bin_name
  	);
  	}
  	if sc.display_name.is_none() {
  	let self_display_name = if is_multicall_set {
  	self.display_name.as_deref().unwrap_or("")
  	} else {
  	self.display_name.as_deref().unwrap_or(&self.name)
  	};
  	let display_name = format!(
  	"{}{}{}",
  	self_display_name,
  	if !self_display_name.is_empty() {
  	"-"
  	} else {
  	""
  	},
  	&*sc.name
  	);
  	debug!(
  	"Command::_build_bin_names:iter: Setting display_name of {} to {:?}",
  	sc.name, display_name
  	);
  	sc.display_name = Some(display_name);
  	} else {
  	debug!(
  	"Command::_build_bin_names::iter: Using existing display_name of {} ({:?})",
  	sc.name, sc.display_name
  	);
  	}
  	sc._build_bin_names_internal();
  	}
  	self.set(AppSettings::BinNameBuilt);
  	} else {
  	debug!("Command::_build_bin_names: already built");
  	}
  	}

• clap/clap_builder/src/builder/debug_asserts.rs

  Lines 11 to 818 in 7566762

  	pub(crate) fn assert_app(cmd: &Command) {
  	debug!("Command::_debug_asserts");
  	let mut short_flags = vec![];
  	let mut long_flags = vec![];
  	// Invalid version flag settings
  	if cmd.get_version().is_none() && cmd.get_long_version().is_none() {
  	// PropagateVersion is meaningless if there is no version
  	assert!(
  	!cmd.is_propagate_version_set(),
  	"Command {}: No version information via Command::version or Command::long_version to propagate",
  	cmd.get_name(),
  	);
  	// Used `Command::mut_arg("version", ..) but did not provide any version information to display
  	let version_needed = cmd
  	.get_arguments()
  	.filter(|x| matches!(x.get_action(), ArgAction::Version))
  	.map(|x| x.get_id())
  	.collect::<Vec<_>>();
  	assert_eq!(version_needed, Vec::<&str>::new(), "Command {}: `ArgAction::Version` used without providing Command::version or Command::long_version"
  	,cmd.get_name()
  	);
  	}
  	for sc in cmd.get_subcommands() {
  	if let Some(s) = sc.get_short_flag().as_ref() {
  	short_flags.push(Flag::Command(format!("-{s}"), sc.get_name()));
  	}
  	for short_alias in sc.get_all_short_flag_aliases() {
  	short_flags.push(Flag::Command(format!("-{short_alias}"), sc.get_name()));
  	}
  	if let Some(l) = sc.get_long_flag().as_ref() {
  	assert!(!l.starts_with('-'), "Command {}: long_flag {:?} must not start with a `-`, that will be handled by the parser", sc.get_name(), l);
  	long_flags.push(Flag::Command(format!("--{l}"), sc.get_name()));
  	}
  	for long_alias in sc.get_all_long_flag_aliases() {
  	long_flags.push(Flag::Command(format!("--{long_alias}"), sc.get_name()));
  	}
  	}
  	for arg in cmd.get_arguments() {
  	assert_arg(arg);
  	assert!(
  	!cmd.is_multicall_set(),
  	"Command {}: Arguments like {} cannot be set on a multicall command",
  	cmd.get_name(),
  	arg.get_id()
  	);
  	if let Some(s) = arg.get_short() {
  	short_flags.push(Flag::Arg(format!("-{s}"), arg.get_id().as_str()));
  	}
  	for (short_alias, _) in &arg.short_aliases {
  	short_flags.push(Flag::Arg(format!("-{short_alias}"), arg.get_id().as_str()));
  	}
  	if let Some(l) = arg.get_long() {
  	assert!(!l.starts_with('-'), "Argument {}: long {:?} must not start with a `-`, that will be handled by the parser", arg.get_id(), l);
  	long_flags.push(Flag::Arg(format!("--{l}"), arg.get_id().as_str()));
  	}
  	for (long_alias, _) in &arg.aliases {
  	long_flags.push(Flag::Arg(format!("--{long_alias}"), arg.get_id().as_str()));
  	}
  	// Name conflicts
  	if let Some((first, second)) = cmd.two_args_of(|x| x.get_id() == arg.get_id()) {
  	panic!(
  	"Command {}: Argument names must be unique, but '{}' is in use by more than one argument or group{}",
  	cmd.get_name(),
  	arg.get_id(),
  	duplicate_tip(cmd, first, second),
  	);
  	}
  	// Long conflicts
  	if let Some(l) = arg.get_long() {
  	if let Some((first, second)) = cmd.two_args_of(|x| x.get_long() == Some(l)) {
  	panic!(
  	"Command {}: Long option names must be unique for each argument, \
  	but '--{}' is in use by both '{}' and '{}'{}",
  	cmd.get_name(),
  	l,
  	first.get_id(),
  	second.get_id(),
  	duplicate_tip(cmd, first, second)
  	)
  	}
  	}
  	// Short conflicts
  	if let Some(s) = arg.get_short() {
  	if let Some((first, second)) = cmd.two_args_of(|x| x.get_short() == Some(s)) {
  	panic!(
  	"Command {}: Short option names must be unique for each argument, \
  	but '-{}' is in use by both '{}' and '{}'{}",
  	cmd.get_name(),
  	s,
  	first.get_id(),
  	second.get_id(),
  	duplicate_tip(cmd, first, second),
  	)
  	}
  	}
  	// Index conflicts
  	if let Some(idx) = arg.index {
  	if let Some((first, second)) =
  	cmd.two_args_of(|x| x.is_positional() && x.get_index() == Some(idx))
  	{
  	panic!(
  	"Command {}: Argument '{}' has the same index as '{}' \
  	and they are both positional arguments\n\n\t \
  	Use `Arg::num_args(1..)` to allow one \
  	positional argument to take multiple values",
  	cmd.get_name(),
  	first.get_id(),
  	second.get_id()
  	)
  	}
  	}
  	// requires, r_if, r_unless
  	for (_predicate, req_id) in &arg.requires {
  	assert!(
  	&arg.id != req_id,
  	"Argument {} cannot require itself",
  	arg.get_id()
  	);
  	assert!(
  	cmd.id_exists(req_id),
  	"Command {}: Argument or group '{}' specified in 'requires*' for '{}' does not exist",
  	cmd.get_name(),
  	req_id,
  	arg.get_id(),
  	);
  	}
  	for req in &arg.r_ifs {
  	assert!(
  	!arg.is_required_set(),
  	"Argument {}: `required` conflicts with `required_if_eq*`",
  	arg.get_id()
  	);
  	assert!(
  	cmd.id_exists(&req.0),
  	"Command {}: Argument or group '{}' specified in 'required_if_eq*' for '{}' does not exist",
  	cmd.get_name(),
  	req.0,
  	arg.get_id()
  	);
  	}
  	for req in &arg.r_ifs_all {
  	assert!(
  	!arg.is_required_set(),
  	"Argument {}: `required` conflicts with `required_if_eq_all`",
  	arg.get_id()
  	);
  	assert!(
  	cmd.id_exists(&req.0),
  	"Command {}: Argument or group '{}' specified in 'required_if_eq_all' for '{}' does not exist",
  	cmd.get_name(),
  	req.0,
  	arg.get_id()
  	);
  	}
  	for req in &arg.r_unless {
  	assert!(
  	!arg.is_required_set(),
  	"Argument {}: `required` conflicts with `required_unless*`",
  	arg.get_id()
  	);
  	assert!(
  	cmd.id_exists(req),
  	"Command {}: Argument or group '{}' specified in 'required_unless*' for '{}' does not exist",
  	cmd.get_name(),
  	req,
  	arg.get_id(),
  	);
  	}
  	for req in &arg.r_unless_all {
  	assert!(
  	!arg.is_required_set(),
  	"Argument {}: `required` conflicts with `required_unless*`",
  	arg.get_id()
  	);
  	assert!(
  	cmd.id_exists(req),
  	"Command {}: Argument or group '{}' specified in 'required_unless*' for '{}' does not exist",
  	cmd.get_name(),
  	req,
  	arg.get_id(),
  	);
  	}
  	// blacklist
  	for req in &arg.blacklist {
  	assert!(
  	cmd.id_exists(req),
  	"Command {}: Argument or group '{}' specified in 'conflicts_with*' for '{}' does not exist",
  	cmd.get_name(),
  	req,
  	arg.get_id(),
  	);
  	}
  	// overrides
  	for req in &arg.overrides {
  	assert!(
  	cmd.id_exists(req),
  	"Command {}: Argument or group '{}' specified in 'overrides_with*' for '{}' does not exist",
  	cmd.get_name(),
  	req,
  	arg.get_id(),
  	);
  	}
  	if arg.is_last_set() {
  	assert!(
  	arg.get_long().is_none(),
  	"Command {}: Flags or Options cannot have last(true) set. '{}' has both a long and last(true) set.",
  	cmd.get_name(),
  	arg.get_id()
  	);
  	assert!(
  	arg.get_short().is_none(),
  	"Command {}: Flags or Options cannot have last(true) set. '{}' has both a short and last(true) set.",
  	cmd.get_name(),
  	arg.get_id()
  	);
  	}
  	assert!(
  	!(arg.is_required_set() && arg.is_global_set()),
  	"Command {}: Global arguments cannot be required.\n\n\t'{}' is marked as both global and required",
  	cmd.get_name(),
  	arg.get_id()
  	);
  	if arg.get_value_hint() == ValueHint::CommandWithArguments {
  	assert!(
  	arg.is_positional(),
  	"Command {}: Argument '{}' has hint CommandWithArguments and must be positional.",
  	cmd.get_name(),
  	arg.get_id()
  	);
  	assert!(
  	arg.is_trailing_var_arg_set() || arg.is_last_set(),
  	"Command {}: Positional argument '{}' has hint CommandWithArguments, so Command must have `trailing_var_arg(true)` or `last(true)` set.",
  	cmd.get_name(),
  	arg.get_id()
  	);
  	}
  	}
  	for group in cmd.get_groups() {
  	// Name conflicts
  	assert!(
  	cmd.get_groups().filter(|x| x.id == group.id).count() < 2,
  	"Command {}: Argument group name must be unique\n\n\t'{}' is already in use",
  	cmd.get_name(),
  	group.get_id(),
  	);
  	// Groups should not have naming conflicts with Args
  	assert!(
  	!cmd.get_arguments().any(|x| x.get_id() == group.get_id()),
  	"Command {}: Argument group name '{}' must not conflict with argument name",
  	cmd.get_name(),
  	group.get_id(),
  	);
  	for arg in &group.args {
  	// Args listed inside groups should exist
  	assert!(
  	cmd.get_arguments().any(|x| x.get_id() == arg),
  	"Command {}: Argument group '{}' contains non-existent argument '{}'",
  	cmd.get_name(),
  	group.get_id(),
  	arg
  	);
  	}
  	for arg in &group.requires {
  	// Args listed inside groups should exist
  	assert!(
  	cmd.id_exists(arg),
  	"Command {}: Argument group '{}' requires non-existent '{}' id",
  	cmd.get_name(),
  	group.get_id(),
  	arg
  	);
  	}
  	for arg in &group.conflicts {
  	// Args listed inside groups should exist
  	assert!(
  	cmd.id_exists(arg),
  	"Command {}: Argument group '{}' conflicts with non-existent '{}' id",
  	cmd.get_name(),
  	group.get_id(),
  	arg
  	);
  	}
  	}
  	// Conflicts between flags and subcommands
  	long_flags.sort_unstable();
  	short_flags.sort_unstable();
  	detect_duplicate_flags(&long_flags, "long");
  	detect_duplicate_flags(&short_flags, "short");
  	let mut subs = FlatSet::new();
  	for sc in cmd.get_subcommands() {
  	assert!(
  	subs.insert(sc.get_name()),
  	"Command {}: command name `{}` is duplicated",
  	cmd.get_name(),
  	sc.get_name()
  	);
  	for alias in sc.get_all_aliases() {
  	assert!(
  	subs.insert(alias),
  	"Command {}: command `{}` alias `{}` is duplicated",
  	cmd.get_name(),
  	sc.get_name(),
  	alias
  	);
  	}
  	}
  	_verify_positionals(cmd);
  	#[cfg(feature = "help")]
  	if let Some(help_template) = cmd.get_help_template() {
  	assert!(
  	!help_template.to_string().contains("{flags}"),
  	"Command {}: {}",
  	cmd.get_name(),
  	"`{flags}` template variable was removed in clap3, they are now included in `{options}`",
  	);
  	assert!(
  	!help_template.to_string().contains("{unified}"),
  	"Command {}: {}",
  	cmd.get_name(),
  	"`{unified}` template variable was removed in clap3, use `{options}` instead"
  	);
  	#[cfg(feature = "unstable-v5")]
  	assert!(
  	!help_template.to_string().contains("{bin}"),
  	"Command {}: {}",
  	cmd.get_name(),
  	"`{bin}` template variable was removed in clap5, use `{name}` instead"
  	);
  	}
  	cmd._panic_on_missing_help(cmd.is_help_expected_set());
  	assert_app_flags(cmd);
  	}
  	fn duplicate_tip(cmd: &Command, first: &Arg, second: &Arg) -> &'static str {
  	if !cmd.is_disable_help_flag_set()
  	&& (first.get_id() == Id::HELP || second.get_id() == Id::HELP)
  	{
  	" (call `cmd.disable_help_flag(true)` to remove the auto-generated `--help`)"
  	} else if !cmd.is_disable_version_flag_set()
  	&& (first.get_id() == Id::VERSION || second.get_id() == Id::VERSION)
  	{
  	" (call `cmd.disable_version_flag(true)` to remove the auto-generated `--version`)"
  	} else {
  	""
  	}
  	}
  	#[derive(Eq)]
  	enum Flag<'a> {
  	Command(String, &'a str),
  	Arg(String, &'a str),
  	}
  	impl PartialEq for Flag<'_> {
  	fn eq(&self, other: &Flag<'_>) -> bool {
  	self.cmp(other) == Ordering::Equal
  	}
  	}
  	impl PartialOrd for Flag<'_> {
  	fn partial_cmp(&self, other: &Flag<'_>) -> Option<Ordering> {
  	Some(self.cmp(other))
  	}
  	}
  	impl Ord for Flag<'_> {
  	fn cmp(&self, other: &Self) -> Ordering {
  	match (self, other) {
  	(Flag::Command(s1, _), Flag::Command(s2, _))
  	| (Flag::Arg(s1, _), Flag::Arg(s2, _))
  	| (Flag::Command(s1, _), Flag::Arg(s2, _))
  	| (Flag::Arg(s1, _), Flag::Command(s2, _)) => {
  	if s1 == s2 {
  	Ordering::Equal
  	} else {
  	s1.cmp(s2)
  	}
  	}
  	}
  	}
  	}
  	fn detect_duplicate_flags(flags: &[Flag<'_>], short_or_long: &str) {
  	for (one, two) in find_duplicates(flags) {
  	match (one, two) {
  	(Flag::Command(flag, one), Flag::Command(_, another)) if one != another => panic!(
  	"the '{flag}' {short_or_long} flag is specified for both '{one}' and '{another}' subcommands"
  	),
  	(Flag::Arg(flag, one), Flag::Arg(_, another)) if one != another => panic!(
  	"{short_or_long} option names must be unique, but '{flag}' is in use by both '{one}' and '{another}'"
  	),
  	(Flag::Arg(flag, arg), Flag::Command(_, sub)) | (Flag::Command(flag, sub), Flag::Arg(_, arg)) => panic!(
  	"the '{flag}' {short_or_long} flag for the '{arg}' argument conflicts with the short flag \
  	for '{sub}' subcommand"
  	),
  	_ => {}
  	}
  	}
  	}
  	/// Find duplicates in a sorted array.
  	///
  	/// The algorithm is simple: the array is sorted, duplicates
  	/// must be placed next to each other, we can check only adjacent elements.
  	fn find_duplicates<T: PartialEq>(slice: &[T]) -> impl Iterator<Item = (&T, &T)> {
  	slice.windows(2).filter_map(|w| {
  	if w[0] == w[1] {
  	Some((&w[0], &w[1]))
  	} else {
  	None
  	}
  	})
  	}
  	fn assert_app_flags(cmd: &Command) {
  	macro_rules! checker {
  	($a:ident conflicts $($b:ident)|+) => {
  	if cmd.$a() {
  	let mut s = String::new();
  	$(
  	if cmd.$b() {
  	use std::fmt::Write;
  	write!(&mut s, " AppSettings::{} conflicts with AppSettings::{}.\n", std::stringify!($b), std::stringify!($a)).unwrap();
  	}
  	)+
  	if !s.is_empty() {
  	panic!("{}\n{}", cmd.get_name(), s)
  	}
  	}
  	};
  	}
  	checker!(is_multicall_set conflicts is_no_binary_name_set);
  	}
  	#[cfg(debug_assertions)]
  	fn _verify_positionals(cmd: &Command) -> bool {
  	debug!("Command::_verify_positionals");
  	// Because you must wait until all arguments have been supplied, this is the first chance
  	// to make assertions on positional argument indexes
  	//
  	// First we verify that the index highest supplied index, is equal to the number of
  	// positional arguments to verify there are no gaps (i.e. supplying an index of 1 and 3
  	// but no 2)
  	let highest_idx = cmd
  	.get_keymap()
  	.keys()
  	.filter_map(|x| {
  	if let KeyType::Position(n) = x {
  	Some(*n)
  	} else {
  	None
  	}
  	})
  	.max()
  	.unwrap_or(0);
  	let num_p = cmd.get_keymap().keys().filter(|x| x.is_position()).count();
  	assert!(
  	highest_idx == num_p,
  	"Found positional argument whose index is {highest_idx} but there \
  	are only {num_p} positional arguments defined",
  	);
  	for arg in cmd.get_arguments() {
  	if arg.index.unwrap_or(0) == highest_idx {
  	assert!(
  	!arg.is_trailing_var_arg_set() || !arg.is_last_set(),
  	"{}:{}: `Arg::trailing_var_arg` and `Arg::last` cannot be used together",
  	cmd.get_name(),
  	arg.get_id()
  	);
  	if arg.is_trailing_var_arg_set() {
  	assert!(
  	arg.is_multiple(),
  	"{}:{}: `Arg::trailing_var_arg` must accept multiple values",
  	cmd.get_name(),
  	arg.get_id()
  	);
  	}
  	} else {
  	assert!(
  	!arg.is_trailing_var_arg_set(),
  	"{}:{}: `Arg::trailing_var_arg` can only apply to last positional",
  	cmd.get_name(),
  	arg.get_id()
  	);
  	}
  	}
  	// Next we verify that only the highest index has takes multiple arguments (if any)
  	let only_highest = |a: &Arg| a.is_multiple() && (a.get_index().unwrap_or(0) != highest_idx);
  	if cmd.get_positionals().any(only_highest) {
  	// First we make sure if there is a positional that allows multiple values
  	// the one before it (second to last) has one of these:
  	// * a value terminator
  	// * ArgSettings::Last
  	// * The last arg is Required
  	// We can't pass the closure (it.next()) to the macro directly because each call to
  	// find() (iterator, not macro) gets called repeatedly.
  	let last = &cmd.get_keymap()[&KeyType::Position(highest_idx)];
  	let second_to_last = &cmd.get_keymap()[&KeyType::Position(highest_idx - 1)];
  	// Either the final positional is required
  	// Or the second to last has a terminator or .last(true) set
  	let ok = last.is_required_set()
  	|| (second_to_last.terminator.is_some() || second_to_last.is_last_set())
  	|| last.is_last_set();
  	assert!(
  	ok,
  	"Positional argument `{last}` *must* have `required(true)` or `last(true)` set \
  	because a prior positional argument (`{second_to_last}`) has `num_args(1..)`"
  	);
  	// We make sure if the second to last is Multiple the last is ArgSettings::Last
  	let ok = second_to_last.is_multiple() || last.is_last_set();
  	assert!(
  	ok,
  	"Only the last positional argument, or second to last positional \
  	argument may be set to `.num_args(1..)`"
  	);
  	// Next we check how many have both Multiple and not a specific number of values set
  	let count = cmd
  	.get_positionals()
  	.filter(|p| {
  	p.is_multiple_values_set()
  	&& p.get_value_terminator().is_none()
  	&& !p.get_num_args().expect(INTERNAL_ERROR_MSG).is_fixed()
  	})
  	.count();
  	let ok = count <= 1
  	|| (last.is_last_set()
  	&& last.is_multiple()
  	&& second_to_last.is_multiple()
  	&& count == 2);
  	assert!(
  	ok,
  	"Only one positional argument with `.num_args(1..)` set is allowed per \
  	command, unless the second one also has .last(true) set"
  	);
  	}
  	let mut found = false;
  	if cmd.is_allow_missing_positional_set() {
  	// Check that if a required positional argument is found, all positions with a lower
  	// index are also required.
  	let mut foundx2 = false;
  	for p in cmd.get_positionals() {
  	if foundx2 && !p.is_required_set() {
  	assert!(
  	p.is_required_set(),
  	"Found non-required positional argument with a lower \
  	index than a required positional argument by two or more: {:?} \
  	index {:?}",
  	p.get_id(),
  	p.get_index()
  	);
  	} else if p.is_required_set() && !p.is_last_set() {
  	// Args that .last(true) don't count since they can be required and have
  	// positionals with a lower index that aren't required
  	// Imagine: prog <req1> [opt1] -- <req2>
  	// Both of these are valid invocations:
  	// $ prog r1 -- r2
  	// $ prog r1 o1 -- r2
  	if found {
  	foundx2 = true;
  	continue;
  	}
  	found = true;
  	} else {
  	found = false;
  	}
  	}
  	} else {
  	// Check that if a required positional argument is found, all positions with a lower
  	// index are also required
  	for p in (1..=num_p).rev().filter_map(|n| cmd.get_keymap().get(&n)) {
  	if found {
  	assert!(
  	p.is_required_set(),
  	"Found non-required positional argument with a lower \
  	index than a required positional argument: {:?} index {:?}",
  	p.get_id(),
  	p.get_index()
  	);
  	} else if p.is_required_set() && !p.is_last_set() {
  	// Args that .last(true) don't count since they can be required and have
  	// positionals with a lower index that aren't required
  	// Imagine: prog <req1> [opt1] -- <req2>
  	// Both of these are valid invocations:
  	// $ prog r1 -- r2
  	// $ prog r1 o1 -- r2
  	found = true;
  	}
  	}
  	}
  	assert!(
  	cmd.get_positionals().filter(|p| p.is_last_set()).count() < 2,
  	"Only one positional argument may have last(true) set. Found two."
  	);
  	if cmd
  	.get_positionals()
  	.any(|p| p.is_last_set() && p.is_required_set())
  	&& cmd.has_subcommands()
  	&& !cmd.is_subcommand_negates_reqs_set()
  	{
  	panic!(
  	"Having a required positional argument with .last(true) set *and* child \
  	subcommands without setting SubcommandsNegateReqs isn't compatible."
  	);
  	}
  	true
  	}
  	fn assert_arg(arg: &Arg) {
  	debug!("Arg::_debug_asserts:{}", arg.get_id());
  	// Self conflict
  	// TODO: this check should be recursive
  	assert!(
  	!arg.blacklist.iter().any(|x| x == arg.get_id()),
  	"Argument '{}' cannot conflict with itself",
  	arg.get_id(),
  	);
  	assert!(
  	arg.get_num_args().unwrap_or(1.into()).max_values()
  	<= arg.get_action().max_num_args().max_values(),
  	"Argument `{}`'s action {:?} is incompatible with `num_args({:?})`",
  	arg.get_id(),
  	arg.get_action(),
  	arg.get_num_args().unwrap_or(1.into())
  	);
  	if let Some(action_type_id) = arg.get_action().value_type_id() {
  	assert_eq!(
  	action_type_id,
  	arg.get_value_parser().type_id(),
  	"Argument `{}`'s selected action {:?} contradicts `value_parser` ({:?})",
  	arg.get_id(),
  	arg.get_action(),
  	arg.get_value_parser()
  	);
  	}
  	if arg.get_value_hint() != ValueHint::Unknown {
  	assert!(
  	arg.is_takes_value_set(),
  	"Argument '{}' has value hint but takes no value",
  	arg.get_id()
  	);
  	if arg.get_value_hint() == ValueHint::CommandWithArguments {
  	assert!(
  	arg.is_multiple_values_set(),
  	"Argument '{}' uses hint CommandWithArguments and must accept multiple values",
  	arg.get_id()
  	);
  	}
  	}
  	if arg.index.is_some() {
  	assert!(
  	arg.is_positional(),
  	"Argument '{}' is a positional argument and can't have short or long name versions",
  	arg.get_id()
  	);
  	assert!(
  	arg.is_takes_value_set(),
  	"Argument '{}' is positional and it must take a value but action is {:?}{}",
  	arg.get_id(),
  	arg.get_action(),
  	if arg.get_id() == Id::HELP {
  	" (`mut_arg` no longer works with implicit `--help`)"
  	} else if arg.get_id() == Id::VERSION {
  	" (`mut_arg` no longer works with implicit `--version`)"
  	} else {
  	""
  	}
  	);
  	}
  	let num_vals = arg.get_num_args().expect(INTERNAL_ERROR_MSG);
  	// This can be the cause of later asserts, so put this first
  	if num_vals != ValueRange::EMPTY {
  	// HACK: Don't check for flags to make the derive easier
  	let num_val_names = arg.get_value_names().unwrap_or(&[]).len();
  	if num_vals.max_values() < num_val_names {
  	panic!(
  	"Argument {}: Too many value names ({}) compared to `num_args` ({})",
  	arg.get_id(),
  	num_val_names,
  	num_vals
  	);
  	}
  	}
  	assert_eq!(
  	num_vals.is_multiple(),
  	arg.is_multiple_values_set(),
  	"Argument {}: mismatch between `num_args` ({}) and `multiple_values`",
  	arg.get_id(),
  	num_vals,
  	);
  	if 1 < num_vals.min_values() {
  	assert!(
  	!arg.is_require_equals_set(),
  	"Argument {}: cannot accept more than 1 arg (num_args={}) with require_equals",
  	arg.get_id(),
  	num_vals
  	);
  	}
  	if num_vals == ValueRange::SINGLE {
  	assert!(
  	!arg.is_multiple_values_set(),
  	"Argument {}: mismatch between `num_args` and `multiple_values`",
  	arg.get_id()
  	);
  	}
  	assert_arg_flags(arg);
  	}
  	fn assert_arg_flags(arg: &Arg) {
  	macro_rules! checker {
  	($a:ident requires $($b:ident)|+) => {
  	if arg.$a() {
  	let mut s = String::new();
  	$(
  	if !arg.$b() {
  	use std::fmt::Write;
  	write!(&mut s, " Arg::{} is required when Arg::{} is set.\n", std::stringify!($b), std::stringify!($a)).unwrap();
  	}
  	)+
  	if !s.is_empty() {
  	panic!("Argument {:?}\n{}", arg.get_id(), s)
  	}
  	}
  	}
  	}
  	checker!(is_hide_possible_values_set requires is_takes_value_set);
  	checker!(is_allow_hyphen_values_set requires is_takes_value_set);
  	checker!(is_allow_negative_numbers_set requires is_takes_value_set);
  	checker!(is_require_equals_set requires is_takes_value_set);
  	checker!(is_last_set requires is_takes_value_set);
  	checker!(is_hide_default_value_set requires is_takes_value_set);
  	checker!(is_multiple_values_set requires is_takes_value_set);
  	checker!(is_ignore_case_set requires is_takes_value_set);
  	}

There is a lot there for me to specifically enumerate. To give just on example, this sets up some basics for usage string generation.

Could you please add a task to add a complex example with TypedValueParser implementation.

If there are use cases we aren't covering, I'd be willing to accept them. Looking around the projects on my system, I found one use of value parsers remotely like yours. I'm adding it in #6126. Whats interesting about this case is that its not easy to provide an error that fits both cases so we prioritize one and this feels like a time to prioritize the non-possible values.

How would I test TypedValueParser?

You can put it in a Parser and call try_parse_from

How to make output the same between custom implementation and official implementation?

You can either wrap another TypedValueParser or implement it yourself, something like

format!("invalid value `{value}` for `{arg}`: `{err}`");

You could also use Error::new and manually build it up though we've not taken the time to document how to manually build these up.

[eirnym]

Thank you for your time and documentation effort. You've answered all my questions for now.