Printing the line "For more information ..." from TypedValueParser

[mamekoro]

I was trying to print an error message from my custom TypedValueParser and noticed that it prints the error message, but the line "For more information, try '--help'" is not printed at the end of output.

If I use Fn(&str) -> Result<T, E> instead of TypedValueParser, the "For more info" line is printed at the end as I wanted.

I want to print the line "For more information, try '--help'" from TypedValueParser. How can I do this?

Steps to reproduce

To reproduce, please copy the following main.rs and dependencies into your new testing project, and follow these steps:

1. Run cargo run and check its output.
2. Comment out the line test_typed_value_parser();.
3. Uncomment the line test_function();.
4. Run cargo run and check its output.

main.rs

use clap::{
    builder::{TypedValueParser, ValueParserFactory},
    error::ErrorKind,
    Parser,
};

#[derive(Copy, Clone, Debug)]
pub struct Color(u32);

#[derive(Copy, Clone, Debug)]
pub struct ColorParser;

impl TypedValueParser for ColorParser {
    type Value = Color;

    fn parse_ref(
        &self,
        cmd: &clap::Command,
        arg: Option<&clap::Arg>,
        value: &std::ffi::OsStr,
    ) -> Result<Self::Value, clap::Error> {
        Err(clap::Error::raw(ErrorKind::InvalidValue, "Error from ColorParser").with_cmd(cmd))
    }
}

impl ValueParserFactory for Color {
    type Parser = ColorParser;

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

fn parse_color(s: &str) -> Result<Color, clap::Error> {
    Err(clap::Error::raw(
        ErrorKind::InvalidValue,
        "Error from parse_color()",
    ))
}

#[derive(Copy, Clone, Debug, Parser)]
struct ArgsByTypedValueParser {
    #[arg(value_parser = ColorParser)]
    color: Color,
}

#[derive(Copy, Clone, Debug, Parser)]
struct ArgsByFunction {
    #[arg(value_parser = parse_color)]
    color: Color,
}

fn main() {
    // 1. Run `cargo run` and check the error message.
    // 2. Comment out the line `test_typed_value_parser();`.
    // 3. Uncomment the line `test_function();`.
    // 4. Run `cargo run` and check the error message.

    test_typed_value_parser();
    // test_function();
}

fn test_typed_value_parser() {
    let args = ArgsByTypedValueParser::parse_from(vec!["", "test"].iter());
    println!("{args:?}");
}

fn test_function() {
    let args = ArgsByFunction::parse_from(vec!["", "test"].iter());
    println!("{args:?}");
}

[dependencies] in Cargo.toml

[dependencies]
clap = { version = "4.2.4", features = ["derive"] }

The output from TypedValueParser

error: Error from ColorParser

The output from Fn(&str) -> Result<T, E>

error: invalid value 'test' for '<COLOR>': error: Error from parse_color()

For more information, try '--help'.

[epage]

When implementing a TypedValueParser, you are creating the error message directly, rather than supplying a small section of the error message.

Take RangedI64ValueParser as an example, it delegates error creation to value validation but then finalizes it with Error::with_cmd. These same things can be done in your TypedValueParser.

Alternatively, you could reuse one of the existing TypedValueParsers. Most cases I hear of people wanting to write a TypedValueParser can instead be built up out of the existing pieces, making the code much simpler.

[mamekoro]

I'm facing a new problem.

I created a custom ErrorFormatter and tried to use it in TypedValueParser. However, it cannot be compiled due to a signature mismatch in TypedValueParser::parse_ref.

#[derive(Copy, Clone, Debug)]
struct MyFormatter;

impl ErrorFormatter for MyFormatter {
    fn format_error(error: &clap::error::Error<Self>) -> StyledStr {
        todo!();
    }
}

impl TypedValueParser for ColorParserWithMyFormatter {
    type Value = Color;

    fn parse_ref(
        &self,
        cmd: &clap::Command,
        arg: Option<&clap::Arg>,
        value: &std::ffi::OsStr,
    // Compilation error:
    // The return type must be `Result<Self::Value, clap::error::Error<DefaultFormatter>>`.
    ) -> Result<Self::Value, clap::error::Error<MyFormatter>> {
        todo!();
    }
}

error[E0053]: method `parse_ref` has an incompatible type for trait
  --> src/main.rs:89:10
   |
89 |     ) -> Result<Self::Value, clap::error::Error<MyFormatter>> {
   |          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   |          |
   |          expected `DefaultFormatter`, found `MyFormatter`
   |          help: change the output type to match the trait: `Result<Color, clap::error::Error>`
   |
   = note: expected signature `fn(&ColorParserWithMyFormatter, &clap::Command, Option<&Arg>, &std::ffi::OsStr) -> Result<_, clap::error::Error<DefaultFormatter>>`
              found signature `fn(&ColorParserWithMyFormatter, &clap::Command, Option<&Arg>, &std::ffi::OsStr) -> Result<_, clap::error::Error<MyFormatter>>`

Would you consider allowing the return value of the TypedValueParser::parse_ref function to specify a ErrorFormatter other than DefaultFormatter?

[epage]

The error formatter is meant to be applied on the return type from Command::try_get_matches or similar functions.

Could you provide more details on how you are wanting to customize the error message? Already, creating a TypedValueParser is less common route; creating a custom formatter to customize a single error feels like this is getting off into the weeds.

[mamekoro]

My actual project is a commandline tool that can print or search a color from a color palette in various format such as HTML color (e.g. #RRGGBB, #RGB), shader-like format (e.g. vec4(1.0, 1.0, 1.0, 1.0), or user-defined format specified via commandline arguments, etc.

And I created custom TypedValueParsers because I need to parse and validate arguments in a user-defined format.

My goal is to make commandline errors easier to understand for users by displaying specific error messages in the console, and if possible, I want the errors to be formatted like clap's default formatter for visual consistency.

For example, suppose the user specified a color and a color palette via command line, but the palette did not have that color.

In this case, an expected output is as follows.

error: Color "test" does not exist in Palette "test_palette". Available colors are ["color1", "color2", "color3"] (case insensitive).

For more information, try '--help'.

• The string error: in the above output should be displayed in red as in clap's default formatter.
• The Color "test" does not ... part is my custom error message.
• The error: and For more info... parts are the same as clap's default formatter.

And the related error is as follows.

#[derive(Clone, Debug)]
pub struct NoSuchColorError {
    pub color_name: String,
    pub palette_name: String,
}

impl fmt::Display for NoSuchColorError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        let available_colors: Vec<String> = Palette::from_name(&self.palette_name)
            .unwrap()
            .iter()
            .map(|color| color.name())
            .collect();
        write!(
            f,
            "Color {color:?} does not exist in Palette {palette:?}. \
            Available colors are {available_colors:?} (case-insensitive).",
            color = self.color_name,
            palette = self.palette_name,
        )
    }
}

And I faced problems:

• The error messages provided by the existing TypedValueParser is too generic, and I would like to make them specific to my tool.
• Useful functions such as set_source(err) or value_validation(...) are pub(crate) in clap.
• Context::Custom is not handled by the default formatter.
• It's difficult to use custom formatters because TypeValueParser::parse_ref requires DefaultFormatter.

So I opened this discussion and here we are.

In short, things what I want are public APIs for configuring custom error messages which are formatted/colored like clap's default formatter.

[epage]

In that case, I would most likely just construct the full error message directly, passing styled text to Error::new. Other APIs supported styled text as of 4.2 but I overlooked Error::new during 4.0 so it would be a breaking change now (#4862) but it should work anyways.

[mamekoro]

Thank you so much for your replies and the great crate!

[tlylt-autodesk]

Hi @epage, may I ask on the flip side, is there an easy way to prevent the printing of "For more information ..." when I used the value_parser ?

In my below code, although I have overridden the error message, the "For more information..." is still printed at the end of the message

#[derive(clap::Parser, Default, Debug)]
#[command()]
struct Args {
    #[arg(value_parser = parse_version)]
    version: Version,
}

fn parse_version(s: &str) -> Result<Version, String> {
    Version::from_str(s).map_err(|_| {
        format!(
            "Failed to parse VERSION: '{}'!",
            s
        )
    })
}

[epage]

The error message is setup by impl TypedValueParser for F. If you manually implement TypedValueParser, you can return whatever error message you want.