serde_saphyr/de/

localizer.rs

//! Localization / wording customization.
//!
//! The [`Localizer`] trait is the central hook for customizing *crate-authored wording*.
//! It is intentionally designed to be low-boilerplate:
//!
//! - Every method has a reasonable English default.
//! - You can override only the pieces you care about, while inheriting all other defaults.
//!
//! This crate may also show *external* message text coming from dependencies (for example
//! `granit-parser` scan errors, or validator messages). Where such texts are used, the
//! rendering pipeline should provide a best-effort opportunity to override them via
//! [`Localizer::override_external_message`].
//!
//! ## Example: override a single phrase
//!
//! ```rust
//! use serde_saphyr::{Error, Location};
//! use serde_saphyr::localizer::{Localizer, DEFAULT_ENGLISH_LOCALIZER};
//! use std::borrow::Cow;
//!
//! /// A wrapper that overrides only location suffix wording, delegating everything else.
//! struct Pirate<'a> {
//!     base: &'a dyn Localizer,
//! }
//!
//! impl Localizer for Pirate<'_> {
//!     fn attach_location<'b>(&self, base: Cow<'b, str>, loc: Location) -> Cow<'b, str> {
//!         if loc == Location::UNKNOWN {
//!             return base;
//!         }
//!         // Note: you can also delegate to `self.base.attach_location(...)` if you want.
//!         Cow::Owned(format!(
//!             "{base}. Bug lurks on line {}, then {} runes in",
//!             loc.line(),
//!             loc.column()
//!         ))
//!     }
//! }
//!
//! // This snippet shows the customization building blocks; the crate's rendering APIs
//! // obtain a `Localizer` via the `MessageFormatter`.
//! # let _ = (Error::InvalidUtf8Input, &DEFAULT_ENGLISH_LOCALIZER);
//! ```

use crate::Location;
use granit_parser::ScanError;
use std::borrow::Cow;

/// Where an “external” message comes from.
///
/// External messages are those primarily produced by dependencies (parser / validators).
#[non_exhaustive]
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ExternalMessageSource {
    /// Text produced by the immediate YAML parser, with its structured error.
    Parser(ScanError),
    /// Text produced by `garde` validation rules.
    Garde,
    /// Text produced by `validator` validation rules.
    Validator,
}

/// A best-effort description of an external message.
///
/// The crate should pass as much stable metadata as it has (e.g. `code` and `params` for
/// `validator`) so the localizer can override *specific* messages without string matching.
#[non_exhaustive]
#[derive(Debug, Clone)]
pub struct ExternalMessage<'a> {
    pub source: ExternalMessageSource,
    /// The original text as provided by the external library.
    pub original: &'a str,
    /// Stable-ish identifier when available (e.g. validator error code).
    pub code: Option<&'a str>,
    /// Optional structured parameters when available.
    pub params: &'a [(String, String)],
}

impl<'a> ExternalMessage<'a> {
    /// Construct an external message with no code or structured parameters.
    #[must_use]
    pub fn new(source: ExternalMessageSource, original: &'a str) -> Self {
        Self {
            source,
            original,
            code: None,
            params: &[],
        }
    }

    /// Attach a dependency-provided message code.
    #[must_use]
    pub fn with_code(mut self, code: &'a str) -> Self {
        self.code = Some(code);
        self
    }

    /// Attach structured dependency-provided message parameters.
    #[must_use]
    pub fn with_params(mut self, params: &'a [(String, String)]) -> Self {
        self.params = params;
        self
    }
}

/// All crate-authored wording customization points.
///
/// Implementors should typically override *only a few* methods.
/// Everything else should default to English (via the default method bodies).
///
/// [`Error::render`](crate::Error::render) and the other rendering entrypoints neutralize
/// control characters in returned message and label text. Calling these low-level hooks
/// directly bypasses that boundary; sanitize their output (for example with
/// [`str::escape_debug`]) before writing it to a terminal or log.
pub trait Localizer {
    // ---------------- Common tiny building blocks ----------------

    /// Attach an ordinary error-location suffix to `base`.
    ///
    /// Renderers must use this instead of hard-coding English wording like
    /// `" at line X, column Y"`.
    /// Plain alias use and definition locations have separate hooks:
    /// [`Localizer::alias_used_at`] and [`Localizer::alias_defined_at`].
    ///
    /// Default:
    /// - If `loc == Location::UNKNOWN`: returns `base` unchanged.
    /// - Otherwise: returns `"{base} at line {line}, column {column}"`.
    fn attach_location<'a>(&self, base: Cow<'a, str>, loc: Location) -> Cow<'a, str> {
        if loc == Location::UNKNOWN {
            base
        } else {
            Cow::Owned(format!(
                "{base} at line {}, column {}",
                loc.line, loc.column
            ))
        }
    }

    /// Label used when a path has no leaf.
    ///
    /// Default `<root>`
    fn root_path_label(&self) -> Cow<'static, str> {
        Cow::Borrowed("<root>")
    }

    /// Suffix for alias-related errors when a distinct defined-location is available.
    ///
    /// Default wording matches the crate's historical English output:
    /// `" (defined at line X, column Y)"`.
    ///
    /// Default: `format!(" (defined at line {line}, column {column})", ...)`.
    fn alias_defined_at(&self, defined: Location) -> String {
        format!(
            " (defined at line {}, column {})",
            defined.line, defined.column
        )
    }

    /// Suffix identifying where an aliased value is used in a plain-text diagnostic.
    ///
    /// Default: `" (used at line X, column Y)"`, or an empty string for an unknown location.
    /// This replaces the generic [`Localizer::attach_location`] call for a known alias use.
    /// Override this hook as well when customizing or suppressing alias-use coordinates;
    /// return an empty string to omit the suffix.
    fn alias_used_at(&self, used: Location) -> String {
        if used == Location::UNKNOWN {
            String::new()
        } else {
            format!(" (used at line {}, column {})", used.line, used.column)
        }
    }

    // ---------------- Validation (plain text) glue ----------------

    /// Render one validation issue line.
    ///
    /// The crate provides `resolved_path`, `entry` and the chosen `loc`.
    ///
    /// Default:
    /// - Base text: `"validation error at {resolved_path}: {entry}"`.
    /// - If `loc` is `Some` and not `Location::UNKNOWN`, appends a location suffix via
    ///   [`Localizer::attach_location`].
    fn validation_issue_line(
        &self,
        resolved_path: &str,
        entry: &str,
        loc: Option<Location>,
    ) -> String {
        let base = format!("validation error at {resolved_path}: {entry}");
        match loc {
            Some(l) if l != Location::UNKNOWN => {
                self.attach_location(Cow::Owned(base), l).into_owned()
            }
            _ => base,
        }
    }

    /// Join multiple validation issues into one message.
    ///
    /// Default: joins `lines` with a single newline (`"\n"`).
    fn join_validation_issues(&self, lines: &[String]) -> String {
        lines.join("\n")
    }

    /// Summary for a validation report whose issues are shown as related miette diagnostics.
    ///
    /// Default: `"validation failed"` for one issue, otherwise
    /// `"validation failed (multiple errors)"`.
    fn validation_failed(&self, issue_count: usize) -> Cow<'static, str> {
        if issue_count == 1 {
            Cow::Borrowed("validation failed")
        } else {
            Cow::Borrowed("validation failed (multiple errors)")
        }
    }

    /// Summary for validation failures spanning multiple YAML documents.
    ///
    /// Default: `"validation failed for {document_count} document(s)"`.
    fn validation_failed_documents(&self, document_count: usize) -> String {
        format!("validation failed for {document_count} document(s)")
    }

    // ---------------- Validation snippets / diagnostic labels ----------------

    /// Legacy label for a snippet window at the “definition” site.
    ///
    /// Retained for compatibility. Built-in validation snippets now use the actual source
    /// name in their headers and do not call this hook.
    ///
    /// Default: `"(defined)"`.
    fn defined(&self) -> Cow<'static, str> {
        Cow::Borrowed("(defined)")
    }

    /// Legacy label for a snippet window with only a “defined here” location.
    ///
    /// Retained for compatibility. Built-in validation snippets now use the actual source
    /// name in their headers and do not call this hook.
    ///
    /// Default: `"(defined here)"`.
    fn defined_here(&self) -> Cow<'static, str> {
        Cow::Borrowed("(defined here)")
    }

    /// Label used for the primary snippet window when an aliased/anchored value is used
    /// at a different location than where it was defined, and for use sites in miette.
    ///
    /// Default: `"the value is used here"`.
    fn value_used_here(&self) -> Cow<'static, str> {
        Cow::Borrowed("the value is used here")
    }

    /// Label used for the secondary snippet window that points at the anchor definition.
    /// Also used for validation definitions and definition-only locations in miette.
    ///
    /// For the separate anchor-definition label in miette alias diagnostics, also override
    /// [`Localizer::anchor_defined_here`], which defaults to `"anchor defined here"`
    /// independently of this method.
    ///
    /// Default: `"defined here"`.
    fn defined_window(&self) -> Cow<'static, str> {
        Cow::Borrowed("defined here")
    }

    /// Label for an alias's anchor definition in miette diagnostics.
    ///
    /// Default: `"anchor defined here"`.
    fn anchor_defined_here(&self) -> Cow<'static, str> {
        Cow::Borrowed("anchor defined here")
    }

    /// Message identifying an include site in a diagnostic.
    ///
    /// Used by miette related diagnostics and plain snippet headings. The plain snippet
    /// renderer adds a trailing colon.
    ///
    /// Default: `"included from here"` (without a trailing colon).
    fn included_from_here(&self) -> Cow<'static, str> {
        Cow::Borrowed("included from here")
    }

    /// Label for the failing value when it differs from the alias definition and use.
    ///
    /// Default: `"the error occurred here"`.
    fn error_here(&self) -> Cow<'static, str> {
        Cow::Borrowed("the error occurred here")
    }

    /// Compose the base validation message used in snippets and miette diagnostics.
    ///
    /// Default: `"validation error: {entry} for `{`resolved_path`}`"`.
    fn validation_base_message(&self, entry: &str, resolved_path: &str) -> String {
        format!("validation error: {entry} for `{resolved_path}`")
    }

    /// Compose the “invalid here” prefix for the primary snippet message.
    ///
    /// Default: `"invalid here, {base}"`.
    fn invalid_here(&self, base: &str) -> String {
        format!("invalid here, {base}")
    }

    /// Intro line printed between the primary and secondary snippet windows for
    /// anchor/alias (“indirect value”) cases.
    ///
    /// Default:
    /// `"  | This value comes indirectly from the anchor at line {line} column {column}:"`.
    fn value_comes_from_the_anchor(&self, def: Location) -> String {
        format!(
            "  | This value comes indirectly from the anchor at line {} column {}:",
            def.line, def.column
        )
    }

    // ---------------- External overrides ----------------

    /// Optional hook to override the location prefix used for snippet titles
    ///
    /// Default:
    /// - If `loc == Location::UNKNOWN`: returns an empty string.
    /// - Otherwise: returns `"line {line} column {column}"`.
    fn snippet_location_prefix(&self, loc: Location) -> String {
        if loc == Location::UNKNOWN {
            String::new()
        } else {
            format!("line {} column {}", loc.line(), loc.column())
        }
    }

    /// Best-effort hook to override/translate dependency-provided message text.
    ///
    /// Default: returns `None` (keep the external message as-is).
    fn override_external_message<'a>(&self, _msg: ExternalMessage<'a>) -> Option<Cow<'a, str>> {
        None
    }
}

/// Default English localizer used by the crate.
#[derive(Debug, Default, Clone, Copy)]
pub struct DefaultEnglishLocalizer;

impl Localizer for DefaultEnglishLocalizer {}

/// A single shared instance of the default English localizer.
///
/// This avoids repeated instantiation and provides a convenient reference for wrappers.
pub static DEFAULT_ENGLISH_LOCALIZER: DefaultEnglishLocalizer = DefaultEnglishLocalizer;