clap_i18n_richformatter/

lib.rs

use std::error::Error;

use clap::ArgMatches;
use clap::builder::StyledStr;
use clap::builder::Styles;
use clap::builder::styling::Style;
use clap::error::ContextKind;
use clap::error::ContextValue;
use clap::error::ErrorFormatter;
use clap::error::ErrorKind;
use i18n_embed::DefaultLocalizer;
use i18n_embed::DesktopLanguageRequester;
use i18n_embed::Localizer;

use crate::lang::CLAP_I18N_LANGUAGE_LOADER;
pub use crate::lang::ClapI18nLocalizations;
use crate::lang::fl;

mod lang;

// Re-export the derive macro
#[cfg(feature = "derive")]
pub use clap_i18n_derive::clap_i18n;

// Hidden module for internal use by derive macro (not shown in code completion)
#[doc(hidden)]
pub mod __private {
    pub use crate::lang::get_translation;
}

const TAB: &str = "  ";

pub fn init_clap_rich_formatter_localizer() {
    let localizer = DefaultLocalizer::new(&*CLAP_I18N_LANGUAGE_LOADER, &ClapI18nLocalizations);
    let requested_languages = DesktopLanguageRequester::requested_languages();

    if let Err(error) = localizer.select(&requested_languages) {
        eprintln!("Error while loading languages for library_fluent {error}");
    }

    // Windows Terminal doesn't support bidirectional (BiDi) text, and renders the isolate characters incorrectly.
    // This is a temporary workaround for https://github.com/microsoft/terminal/issues/16574
    // TODO: this might break BiDi text, though we don't support any writing system depends on that.
    CLAP_I18N_LANGUAGE_LOADER.set_use_isolating(false);
}

pub trait CommandI18nExt {
    fn try_get_matches_i18n(self) -> Result<ArgMatches, clap::error::Error<ClapI18nRichFormatter>>;
    fn get_matches_i18n(self) -> ArgMatches;
}

impl CommandI18nExt for clap::Command {
    /// `clap::Command::try_get_matches` i18n version
    fn try_get_matches_i18n(self) -> Result<ArgMatches, clap::error::Error<ClapI18nRichFormatter>> {
        init_clap_rich_formatter_localizer();
        self.try_get_matches()
            .map_err(|e| e.apply::<ClapI18nRichFormatter>())
    }

    /// `clap::Command::get_matches` i18n version
    fn get_matches_i18n(self) -> ArgMatches {
        self.try_get_matches_i18n().map_err(|e| e.exit()).unwrap()
    }
}

/// Richly formatted error context
///
/// This follows the [rustc diagnostic style guide](https://rustc-dev-guide.rust-lang.org/diagnostics.html#suggestion-style-guide).
#[non_exhaustive]
pub struct ClapI18nRichFormatter;

impl ErrorFormatter for ClapI18nRichFormatter {
    fn format_error(error: &clap::error::Error<Self>) -> StyledStr {
        use std::fmt::Write as _;
        let styles = &Styles::default();
        let valid = &styles.get_valid();

        let mut styled = StyledStr::new();
        start_error(&mut styled, styles);

        if !write_dynamic_context(error, &mut styled, styles) {
            if error.kind().as_str().is_some() {
                styled.push_str(&translation_errorkind(error));
            } else if let Some(source) = error.source() {
                let _ = write!(styled, "{source}");
            } else {
                styled.push_str("unknown cause");
            }
        }

        let mut suggested = false;
        if let Some(valid) = error.get(ContextKind::SuggestedSubcommand) {
            styled.push_str("\n");
            if !suggested {
                styled.push_str("\n");
                suggested = true;
            }
            did_you_mean(&mut styled, styles, &fl!("clap-subcommand-context"), valid);
        }
        if let Some(valid) = error.get(ContextKind::SuggestedArg) {
            styled.push_str("\n");
            if !suggested {
                styled.push_str("\n");
                suggested = true;
            }
            did_you_mean(&mut styled, styles, &fl!("clap-argument-context"), valid);
        }
        if let Some(valid) = error.get(ContextKind::SuggestedValue) {
            styled.push_str("\n");
            if !suggested {
                styled.push_str("\n");
                suggested = true;
            }
            did_you_mean(&mut styled, styles, &fl!("clap-value-context"), valid);
        }
        let suggestions = error.get(ContextKind::Suggested);
        if let Some(ContextValue::StyledStrs(suggestions)) = suggestions {
            if !suggested {
                styled.push_str("\n");
            }
            for suggestion in suggestions {
                let _ = write!(
                    styled,
                    "\n{TAB}{valid}{}:{valid:#} ",
                    fl!("clap-tip-heading")
                );
                styled.push_str(&suggestion.ansi().to_string());
            }
        }

        let usage = error.get(ContextKind::Usage);
        if let Some(ContextValue::StyledStr(usage)) = usage {
            put_usage(&mut styled, usage);
        }

        try_help(&mut styled, styles, Some("--help"));

        styled
    }
}

fn translation_errorkind(error: &clap::error::Error<ClapI18nRichFormatter>) -> String {
    match error.kind() {
        ErrorKind::InvalidValue => fl!("clap-errorkind-invalidvalue"),
        ErrorKind::UnknownArgument => fl!("clap-errorkind-unknown-arg"),
        ErrorKind::InvalidSubcommand => fl!("clap-errorkind-invalid-subcmd"),
        ErrorKind::NoEquals => fl!("clap-errorkind-noeq"),
        ErrorKind::ValueValidation => fl!("clap-errorkind-value-validation"),
        ErrorKind::TooManyValues => fl!("clap-errorkind-too-many-values"),
        ErrorKind::TooFewValues => fl!("clap-errorkind-too-few-values"),
        ErrorKind::WrongNumberOfValues => fl!("clap-errorkind-wrong-number-of-values"),
        ErrorKind::ArgumentConflict => fl!("clap-errorkind-arg-conflict"),
        ErrorKind::MissingRequiredArgument => {
            fl!("clap-errorkind-missing-required-arg")
        }
        ErrorKind::MissingSubcommand => fl!("clap-errorkind-missing-subcmd"),
        ErrorKind::InvalidUtf8 => fl!("clap-errorkind-invalid-utf8"),
        _ => unreachable!(),
    }
}

fn start_error(styled: &mut StyledStr, styles: &Styles) {
    use std::fmt::Write as _;
    let error = &styles.get_error();
    let _ = write!(styled, "{error}{}:{error:#} ", fl!("clap-error-heading"));
}

#[must_use]
fn write_dynamic_context(
    error: &clap::error::Error<ClapI18nRichFormatter>,
    styled: &mut StyledStr,
    styles: &Styles,
) -> bool {
    use std::fmt::Write as _;
    let valid = styles.get_valid();
    let invalid = styles.get_invalid();
    let literal = styles.get_literal();

    match error.kind() {
        ErrorKind::ArgumentConflict => {
            let mut prior_arg = error.get(ContextKind::PriorArg);
            let mut arg_conflict = false;
            let mut subcommand_conflict = false;
            let mut arg = "".to_string();
            if let Some(ContextValue::String(invalid_arg)) = error.get(ContextKind::InvalidArg) {
                arg = format!("{invalid}{invalid_arg}{invalid:#}");
                if Some(&ContextValue::String(invalid_arg.clone())) == prior_arg {
                    prior_arg = None;
                    let _ = write!(
                        styled,
                        "{}",
                        fl!("clap-dyn-errorkind-multipletimes", arg = arg.clone()),
                    );
                } else {
                    arg_conflict = true;
                }
            } else if let Some(ContextValue::String(invalid_arg)) =
                error.get(ContextKind::InvalidSubcommand)
            {
                arg = format!("{invalid}{invalid_arg}{invalid:#}");
                subcommand_conflict = true;
            } else {
                styled.push_str(&translation_errorkind(error));
            }

            if let Some(prior_arg) = prior_arg {
                match prior_arg {
                    ContextValue::Strings(values) => {
                        styled.push_str(":");
                        for v in values {
                            let _ = write!(styled, "\n{TAB}{invalid}{v}{invalid:#}",);
                        }
                    }
                    ContextValue::String(value) => {
                        let value = format!("{invalid}{value}{invalid:#}");

                        if arg_conflict {
                            let _ = write!(
                                styled,
                                "{}",
                                fl!("clap-dyn-errorkind-argconflict", arg = arg, arg2 = value)
                            );
                        } else if subcommand_conflict {
                            let _ = write!(
                                styled,
                                "{}",
                                fl!(
                                    "clap-dyn-errorkind-subcmd-conflict",
                                    arg = arg,
                                    subcmd = value
                                )
                            );
                        }
                    }
                    _ => {
                        let _ = write!(styled, "{}", fl!("clap-dyn-errorkind-conflict-other"));
                    }
                }
            }

            true
        }
        ErrorKind::NoEquals => {
            let invalid_arg = error.get(ContextKind::InvalidArg);
            if let Some(ContextValue::String(invalid_arg)) = invalid_arg {
                let arg = format!("{invalid}{invalid_arg}{invalid:#}'");
                let _ = write!(styled, "{}", fl!("clap-dyn-errorkind-no-eq", arg = arg));
                true
            } else {
                false
            }
        }
        ErrorKind::InvalidValue => {
            let invalid_arg = error.get(ContextKind::InvalidArg);
            let invalid_value = error.get(ContextKind::InvalidValue);
            if let (
                Some(ContextValue::String(invalid_arg)),
                Some(ContextValue::String(invalid_value)),
            ) = (invalid_arg, invalid_value)
            {
                let arg = format!("{invalid}{invalid_arg}{invalid:#}");
                if invalid_value.is_empty() {
                    let _ = write!(
                        styled,
                        "{}",
                        fl!("clap-dyn-errorkind-required-arg-but-none", arg = arg),
                    );
                } else {
                    let value = format!("{invalid}{invalid_value}{invalid:#}");
                    let _ = write!(
                        styled,
                        "{}",
                        fl!(
                            "clap-dyn-errorkind-value-validation",
                            invalid_value = value,
                            invalid_arg = arg
                        ),
                    );
                }

                let values = error.get(ContextKind::ValidValue);
                write_values_list(
                    &fl!("clap-possible-value-context", multi = true.to_string()),
                    styled,
                    valid,
                    values,
                );

                true
            } else {
                false
            }
        }
        ErrorKind::InvalidSubcommand => {
            let invalid_sub = error.get(ContextKind::InvalidSubcommand);
            if let Some(ContextValue::String(invalid_sub)) = invalid_sub {
                let sub = format!("{invalid}{invalid_sub}{invalid:#}");
                let _ = write!(
                    styled,
                    "{}",
                    fl!("clap-dyn-errorkind-unrecognized-subcmd", sub = sub),
                );
                true
            } else {
                false
            }
        }
        ErrorKind::MissingRequiredArgument => {
            let invalid_arg = error.get(ContextKind::InvalidArg);
            if let Some(ContextValue::Strings(invalid_arg)) = invalid_arg {
                let _ = write!(styled, "{}", fl!("clap-dyn-errorkind-not-provided"));
                for v in invalid_arg {
                    let _ = write!(styled, "\n{TAB}{valid}{v}{valid:#}",);
                }
                true
            } else {
                false
            }
        }
        ErrorKind::MissingSubcommand => {
            let invalid_sub = error.get(ContextKind::InvalidSubcommand);
            if let Some(ContextValue::String(invalid_sub)) = invalid_sub {
                let sub = format!("{invalid}{invalid_sub}{invalid:#}");
                let _ = write!(
                    styled,
                    "{}",
                    fl!("clap-dyn-errorkind-subcmd-not-provided", sub = sub),
                );
                let values = error.get(ContextKind::ValidSubcommand);
                write_values_list(
                    &fl!("clap-subcommand-context", multi = true.to_string()),
                    styled,
                    valid,
                    values,
                );

                true
            } else {
                false
            }
        }
        ErrorKind::InvalidUtf8 => false,
        ErrorKind::TooManyValues => {
            let invalid_arg = error.get(ContextKind::InvalidArg);
            let invalid_value = error.get(ContextKind::InvalidValue);
            if let (
                Some(ContextValue::String(invalid_arg)),
                Some(ContextValue::String(invalid_value)),
            ) = (invalid_arg, invalid_value)
            {
                let value = format!("{invalid}{invalid_value}{invalid:#}");
                let arg = format!("{literal}{invalid_arg}{literal:#}");
                let _ = write!(
                    styled,
                    "{}",
                    fl!(
                        "clap-dyn-errorkind-too-many-values-no-more-expected",
                        value = value,
                        arg = arg
                    )
                );
                true
            } else {
                false
            }
        }
        ErrorKind::TooFewValues => {
            let invalid_arg = error.get(ContextKind::InvalidArg);
            let actual_num_values = error.get(ContextKind::ActualNumValues);
            let min_values = error.get(ContextKind::MinValues);
            if let (
                Some(ContextValue::String(invalid_arg)),
                Some(ContextValue::Number(actual_num_values)),
                Some(ContextValue::Number(min_values)),
            ) = (invalid_arg, actual_num_values, min_values)
            {
                let min_values = format!("{valid}{min_values}{valid:#}");
                let invalid_arg = format!("{literal}{invalid_arg}{literal:#}");
                let actual_num_values_str = format!("{invalid}{actual_num_values}{invalid:#}");
                let _ = write!(
                    styled,
                    "{}",
                    fl!(
                        "clap-dyn-errorkind-too-few-values",
                        min_values = min_values,
                        invalid_arg = invalid_arg,
                        actual_num_values = actual_num_values_str,
                        n = actual_num_values
                    )
                );
                true
            } else {
                false
            }
        }
        ErrorKind::ValueValidation => {
            let invalid_arg = error.get(ContextKind::InvalidArg);
            let invalid_value = error.get(ContextKind::InvalidValue);
            if let (
                Some(ContextValue::String(invalid_arg)),
                Some(ContextValue::String(invalid_value)),
            ) = (invalid_arg, invalid_value)
            {
                let invalid_value = format!("{invalid}{invalid_value}{invalid:#}");
                let invalid_arg = format!("{literal}{invalid_arg}{literal:#}");
                let _ = write!(
                    styled,
                    "{}",
                    fl!(
                        "clap-dyn-errorkind-value-validation",
                        invalid_value = invalid_value,
                        invalid_arg = invalid_arg
                    )
                );
                if let Some(source) = error.source() {
                    let _ = write!(styled, ": {source}");
                }
                true
            } else {
                false
            }
        }
        ErrorKind::WrongNumberOfValues => {
            let invalid_arg = error.get(ContextKind::InvalidArg);
            let actual_num_values = error.get(ContextKind::ActualNumValues);
            let num_values = error.get(ContextKind::ExpectedNumValues);
            if let (
                Some(ContextValue::String(invalid_arg)),
                Some(ContextValue::Number(actual_num_values)),
                Some(ContextValue::Number(num_values)),
            ) = (invalid_arg, actual_num_values, num_values)
            {
                let num_values = format!("{valid}{num_values}{valid:#}");
                let invalid_arg = format!("{literal}{invalid_arg}{literal:#}");
                let actual_num_values_str = format!("{invalid}{actual_num_values}{invalid:#}");

                let _ = write!(
                    styled,
                    "{}",
                    fl!(
                        "clap-dyn-errorkind-wrong-number-of-values",
                        num_values = num_values,
                        invalid_arg = invalid_arg,
                        actual_num_values = actual_num_values_str,
                        n = actual_num_values
                    )
                );
                true
            } else {
                false
            }
        }
        ErrorKind::UnknownArgument => {
            let invalid_arg = error.get(ContextKind::InvalidArg);
            if let Some(ContextValue::String(invalid_arg)) = invalid_arg {
                let arg = format!("{invalid}{invalid_arg}{invalid:#}");
                let _ = write!(
                    styled,
                    "{}",
                    fl!("clap-dyn-errorkind-unexpected-arg", arg = arg),
                );
                true
            } else {
                false
            }
        }
        ErrorKind::DisplayHelp
        | ErrorKind::DisplayHelpOnMissingArgumentOrSubcommand
        | ErrorKind::DisplayVersion
        | ErrorKind::Io
        | ErrorKind::Format => false,
        _ => false,
    }
}

fn write_values_list(
    list_name: &str,
    styled: &mut StyledStr,
    valid: &Style,
    possible_values: Option<&ContextValue>,
) {
    use std::fmt::Write as _;
    if let Some(ContextValue::Strings(possible_values)) = possible_values
        && !possible_values.is_empty()
    {
        let _ = write!(styled, "\n{TAB}[{list_name}: ");

        for (idx, val) in possible_values.iter().enumerate() {
            if idx > 0 {
                styled.push_str(", ");
            }
            let _ = write!(styled, "{valid}{}{valid:#}", Escape(val));
        }

        styled.push_str("]");
    }
}

fn put_usage(styled: &mut StyledStr, usage: &StyledStr) {
    styled.push_str("\n\n");
    styled.push_str(
        &usage
            .ansi()
            .to_string()
            .replacen("Usage:", &fl!("clap-usage-heading"), 1),
    );
}

fn try_help(styled: &mut StyledStr, styles: &Styles, help: Option<&str>) {
    if let Some(help) = help {
        use std::fmt::Write as _;
        let literal = &styles.get_literal();
        let help = format!("{literal}{help}{literal:#}");
        let _ = write!(styled, "\n\n{}\n", fl!("clap-help-tips", help = help));
    } else {
        styled.push_str("\n");
    }
}

fn did_you_mean(styled: &mut StyledStr, styles: &Styles, context: &str, possibles: &ContextValue) {
    use std::fmt::Write as _;

    let valid = &styles.get_valid();
    let _ = write!(styled, "{TAB}{valid}{}:{valid:#}", fl!("clap-tip-heading"));
    if let ContextValue::String(possible) = possibles {
        let possible = format!("{valid}{possible}{valid:#}");
        let _ = write!(
            styled,
            " {}",
            fl!(
                "clap-similar-exists-single",
                possible = possible,
                context = context
            )
        );
    } else if let ContextValue::Strings(possibles) = possibles {
        if possibles.len() == 1 {
            let possible = format!("{valid}{}{valid:#}", &possibles[0]);
            let _ = write!(
                styled,
                " {}",
                fl!(
                    "clap-similar-exists-single",
                    possible = possible,
                    context = context
                )
            );
        } else {
            let _ = write!(
                styled,
                " {} ",
                fl!("clap-similar-exists-multi", context = context)
            );

            for (i, possible) in possibles.iter().enumerate() {
                if i != 0 {
                    styled.push_str(", ");
                }
                let _ = write!(styled, "'{valid}{possible}{valid:#}'",);
            }
        }
    }
}

struct Escape<'s>(&'s str);

impl std::fmt::Display for Escape<'_> {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        if self.0.contains(char::is_whitespace) {
            std::fmt::Debug::fmt(self.0, f)
        } else {
            self.0.fmt(f)
        }
    }
}