lucre 0.8.0

//! Reading of [`Money`] values from text.

use std::str::FromStr;

use rust_decimal::Decimal;
use thiserror::Error;

use crate::{Currency, Money};

/// A reusable recipe for reading monetary amounts from text.
///
/// Start from [`Parser::new`] (or [`Parser::default`]) and refine it with the
/// builder methods; construction cannot fail. [`Money`]'s [`FromStr`] impl
/// applies the starting recipe, so common shapes need no `Parser` at all.
///
/// The vocabulary mirrors [`Format`](crate::Format): any rendering a `Format`
/// produces can be read back by a `Parser` that shares its separators and,
/// where the rendering carries no ISO code, assumes the right currency.
///
/// ## Example
///
/// ```
/// # use std::error::Error;
/// #
/// # fn main() -> Result<(), Box<dyn Error>> {
/// use lucre::{Currency, Money, Parser};
///
/// let parser = Parser::new();
/// let expected = Money::from_minor(-150000, &Currency::USD);
///
/// // The starting recipe reads an ISO code on either side of the digits,
/// // commas grouping them, a dot decimal mark, and negatives marked by a
/// // minus sign or by parentheses.
/// assert_eq!(parser.parse("-1,500.00 usd")?, expected);
/// assert_eq!(parser.parse("(USD 1,500.00)")?, expected);
/// #
/// #     Ok(())
/// # }
/// ```
#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
pub struct Parser {
    assumed: Option<Currency>,
    group_separator: char,
    decimal_separator: char,
}

impl Parser {
    /// The starting recipe: comma-grouped digits, a dot decimal mark, and no
    /// assumed currency, so the text must carry an ISO code.
    ///
    /// ## Example
    ///
    /// ```
    /// # use std::error::Error;
    /// #
    /// # fn main() -> Result<(), Box<dyn Error>> {
    /// use lucre::{Currency, Money, Parser};
    ///
    /// let parser = Parser::new();
    ///
    /// assert_eq!(
    ///     parser.parse("1,500.00 USD")?,
    ///     Money::from_minor(150000, &Currency::USD)
    /// );
    /// assert!(parser.parse("1,500.00").is_err());
    /// #
    /// #     Ok(())
    /// # }
    /// ```
    #[must_use]
    pub const fn new() -> Self {
        Self {
            assumed: None,
            group_separator: ',',
            decimal_separator: '.',
        }
    }

    /// The characters expected to separate digit groups and mark the start
    /// of the fraction.
    ///
    /// ## Example
    ///
    /// ```
    /// # use std::error::Error;
    /// #
    /// # fn main() -> Result<(), Box<dyn Error>> {
    /// use lucre::{Currency, Money, Parser};
    ///
    /// let parser = Parser::new().separators('.', ',');
    ///
    /// assert_eq!(
    ///     parser.parse("1.500,00 EUR")?,
    ///     Money::from_minor(150000, &Currency::EUR)
    /// );
    /// #
    /// #     Ok(())
    /// # }
    /// ```
    #[must_use]
    pub const fn separators(mut self, group: char, decimal: char) -> Self {
        self.group_separator = group;
        self.decimal_separator = decimal;
        self
    }

    /// The currency to use when the text names none.
    ///
    /// ## Example
    ///
    /// ```
    /// # use std::error::Error;
    /// #
    /// # fn main() -> Result<(), Box<dyn Error>> {
    /// use lucre::{Currency, Money, Parser};
    ///
    /// let parser = Parser::new().assume_currency(&Currency::USD);
    ///
    /// assert_eq!(parser.parse("1.50")?, Money::from_minor(150, &Currency::USD));
    ///
    /// // The assumption also lets the text identify the currency by its symbol.
    /// assert_eq!(parser.parse("$1.50")?, Money::from_minor(150, &Currency::USD));
    ///
    /// // An ISO code in the text still wins over the assumption.
    /// assert_eq!(parser.parse("1.50 EUR")?, Money::from_minor(150, &Currency::EUR));
    /// #
    /// #     Ok(())
    /// # }
    /// ```
    #[must_use]
    pub const fn assume_currency(mut self, currency: &Currency) -> Self {
        self.assumed = Some(*currency);
        self
    }

    /// Reads one monetary amount from `text`, ignoring surrounding
    /// whitespace.
    ///
    /// The digits are kept verbatim, as by [`Money::from_decimal`]: nothing
    /// is rounded or scaled to the currency's minor digits.
    ///
    /// ## Example
    ///
    /// ```
    /// # use std::error::Error;
    /// #
    /// # fn main() -> Result<(), Box<dyn Error>> {
    /// use lucre::{Currency, Money, Parser};
    ///
    /// let parser = Parser::new().assume_currency(&Currency::USD);
    /// let expected = Money::from_minor(150, &Currency::USD);
    ///
    /// // The currency may be named on either side of the digits — by ISO
    /// // code (case-insensitive) or by the applicable currency's symbol —
    /// // or on both sides when they agree; text naming neither falls back
    /// // to the assumed currency.
    /// assert_eq!(parser.parse("1.50 usd")?, expected);
    /// assert_eq!(parser.parse("USD 1.50")?, expected);
    /// assert_eq!(parser.parse("$1.50 USD")?, expected);
    /// assert_eq!(parser.parse("1.50")?, expected);
    ///
    /// // Negative amounts are marked by enclosing parentheses or by one
    /// // minus sign, either leading or directly before the digits.
    /// let negative = Money::from_minor(-150, &Currency::USD);
    /// assert_eq!(parser.parse("(1.50)")?, negative);
    /// assert_eq!(parser.parse("$-1.50")?, negative);
    ///
    /// // Group separators may appear anywhere left of the decimal mark;
    /// // their spacing is not checked.
    /// assert_eq!(
    ///     parser.parse("1,00,0.50")?,
    ///     Money::from_decimal("1000.50".parse()?, &Currency::USD)
    /// );
    /// #
    /// #     Ok(())
    /// # }
    /// ```
    ///
    /// ## Errors
    ///
    /// Returns [`ParseMoneyError::MissingCurrency`] if the text names no currency and none is assumed.
    /// Returns [`ParseMoneyError::UnknownCurrency`] if a named currency matches no ISO code and no applicable symbol.
    /// Returns [`ParseMoneyError::ConflictingCurrencies`] if the text names two different currencies.
    /// Returns [`ParseMoneyError::InvalidAmount`] if the digits are absent, malformed, or beyond [`Decimal`]'s range.
    pub fn parse(&self, text: &str) -> Result<Money, ParseMoneyError> {
        let mut s = text.trim();
        let mut negative = false;

        if let Some(inner) = s.strip_prefix('(').and_then(|r| r.strip_suffix(')')) {
            negative = true;
            s = inner.trim();
        }
        if let Some(rest) = s.strip_prefix('-') {
            if negative {
                return Err(ParseMoneyError::InvalidAmount);
            }
            negative = true;
            s = rest.trim_start();
        }

        let first = s
            .find(|c: char| c.is_ascii_digit())
            .ok_or(ParseMoneyError::InvalidAmount)?;
        let last = s
            .rfind(|c: char| c.is_ascii_digit())
            .ok_or(ParseMoneyError::InvalidAmount)?;

        let mut prefix = s[..first].trim_end();
        let suffix = s[last + 1..].trim_start();

        // A minus written between a prefixed identifier and the digits, as
        // in `$-1.50`, lands on the prefix token; claim it as the sign.
        if let Some(stripped) = prefix.strip_suffix('-') {
            if negative {
                return Err(ParseMoneyError::InvalidAmount);
            }
            negative = true;
            prefix = stripped.trim_end();
        }

        let currency = self.identify(prefix, suffix)?;
        let amount = self.read_amount(&s[first..=last], negative)?;
        Ok(Money::from_decimal(amount, &currency))
    }

    /// Resolves the identifier tokens found around the digits into one
    /// currency, giving ISO codes priority so a symbol on the other side is
    /// checked against the coded currency rather than the assumed one.
    fn identify(&self, prefix: &str, suffix: &str) -> Result<Currency, ParseMoneyError> {
        let mut currency = None;
        let mut symbols = [None, None];
        for (slot, token) in symbols.iter_mut().zip([prefix, suffix]) {
            if token.is_empty() {
                continue;
            }
            match Currency::from_alphabetic_code(&token.to_ascii_uppercase()) {
                Some(coded) => {
                    if currency.is_some_and(|c| c != coded) {
                        return Err(ParseMoneyError::ConflictingCurrencies);
                    }
                    currency = Some(coded);
                }
                None => *slot = Some(token),
            }
        }
        for token in symbols.into_iter().flatten() {
            let claimed = currency
                .or(self.assumed)
                .filter(|c| c.symbol() == token)
                .ok_or_else(|| ParseMoneyError::UnknownCurrency(token.to_string()))?;
            currency = Some(claimed);
        }
        currency
            .or(self.assumed)
            .ok_or(ParseMoneyError::MissingCurrency)
    }

    /// Turns the span between the first and last digit into a `Decimal`,
    /// dropping group separators and normalizing the decimal mark.
    fn read_amount(&self, span: &str, negative: bool) -> Result<Decimal, ParseMoneyError> {
        let mut normalized = String::with_capacity(span.len() + 1);
        if negative {
            normalized.push('-');
        }
        let mut in_fraction = false;
        for c in span.chars() {
            if c.is_ascii_digit() {
                normalized.push(c);
            } else if c == self.decimal_separator && !in_fraction {
                in_fraction = true;
                normalized.push('.');
            } else if c == self.group_separator && !in_fraction {
                // Group marks carry no value and are simply dropped.
            } else {
                return Err(ParseMoneyError::InvalidAmount);
            }
        }
        Decimal::from_str(&normalized).map_err(|_| ParseMoneyError::InvalidAmount)
    }
}

impl Default for Parser {
    fn default() -> Self {
        Self::new()
    }
}

/// Parses as [`Parser::new`]'s recipe expects.
///
/// ## Example
///
/// ```
/// # use std::error::Error;
/// #
/// # fn main() -> Result<(), Box<dyn Error>> {
/// use lucre::{Currency, Money};
///
/// let expected = Money::from_minor(150000, &Currency::USD);
///
/// assert_eq!("1,500.00 USD".parse::<Money>()?, expected);
/// assert_eq!("USD 1,500.00".parse::<Money>()?, expected);
/// #
/// #     Ok(())
/// # }
/// ```
impl FromStr for Money {
    type Err = ParseMoneyError;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        Parser::new().parse(s)
    }
}

/// An error from reading a monetary amount out of text.
#[derive(Clone, Debug, Error, Eq, PartialEq)]
#[non_exhaustive]
pub enum ParseMoneyError {
    /// The text named no currency, and the [`Parser`] assumes none.
    #[error("no currency named and none assumed")]
    MissingCurrency,

    /// The text named a currency matching no ISO code, and no symbol of the
    /// currency that would otherwise apply. Carries the offending token.
    #[error("unrecognized currency {0:?}")]
    UnknownCurrency(String),

    /// The text named two different currencies.
    #[error("more than one currency named")]
    ConflictingCurrencies,

    /// The digits are absent, malformed, or beyond [`Decimal`]'s range.
    #[error("malformed or unrepresentable amount")]
    InvalidAmount,
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::Format;
    use rust_decimal::prelude::*;

    #[test]
    fn code_suffix_test() {
        let money: Money = "1,500.00 USD".parse().unwrap();

        assert_eq!(money, Money::from_minor(150000, &Currency::USD));
    }

    #[test]
    fn code_prefix_test() {
        let money: Money = "USD 1,500.00".parse().unwrap();

        assert_eq!(money, Money::from_minor(150000, &Currency::USD));
    }

    #[test]
    fn code_without_space_test() {
        assert_eq!(
            "1.50USD".parse::<Money>().unwrap(),
            Money::from_minor(150, &Currency::USD)
        );
        assert_eq!(
            "USD1.50".parse::<Money>().unwrap(),
            Money::from_minor(150, &Currency::USD)
        );
    }

    #[test]
    fn code_is_case_insensitive_test() {
        assert_eq!(
            "1.50 usd".parse::<Money>().unwrap(),
            Money::from_minor(150, &Currency::USD)
        );
    }

    #[test]
    fn surrounding_whitespace_test() {
        assert_eq!(
            "  1.50 USD  ".parse::<Money>().unwrap(),
            Money::from_minor(150, &Currency::USD)
        );
    }

    #[test]
    fn negative_minus_placements_test() {
        let expected = Money::from_minor(-150, &Currency::USD);

        assert_eq!("-1.50 USD".parse::<Money>().unwrap(), expected);
        assert_eq!("-USD 1.50".parse::<Money>().unwrap(), expected);
        assert_eq!("USD -1.50".parse::<Money>().unwrap(), expected);
    }

    #[test]
    fn negative_parentheses_test() {
        assert_eq!(
            "(1,500.00 USD)".parse::<Money>().unwrap(),
            Money::from_minor(-150000, &Currency::USD)
        );
    }

    #[test]
    fn doubled_sign_is_invalid_test() {
        assert_eq!(
            "--1.50 USD".parse::<Money>(),
            Err(ParseMoneyError::InvalidAmount)
        );
        assert_eq!(
            "(-1.50 USD)".parse::<Money>(),
            Err(ParseMoneyError::InvalidAmount)
        );
    }

    #[test]
    fn missing_currency_test() {
        assert_eq!(
            "1.50".parse::<Money>(),
            Err(ParseMoneyError::MissingCurrency)
        );
    }

    #[test]
    fn unknown_currency_test() {
        assert_eq!(
            "1.50 ZZZ".parse::<Money>(),
            Err(ParseMoneyError::UnknownCurrency("ZZZ".to_string()))
        );
    }

    #[test]
    fn conflicting_currencies_test() {
        assert_eq!(
            "EUR 1.50 USD".parse::<Money>(),
            Err(ParseMoneyError::ConflictingCurrencies)
        );
    }

    #[test]
    fn symbol_agreeing_with_code_test() {
        assert_eq!(
            "$1.50 USD".parse::<Money>().unwrap(),
            Money::from_minor(150, &Currency::USD)
        );
        assert_eq!(
            "€1.50 USD".parse::<Money>(),
            Err(ParseMoneyError::UnknownCurrency("€".to_string()))
        );
    }

    #[test]
    fn symbol_without_assumption_is_unknown_test() {
        assert_eq!(
            "$1.50".parse::<Money>(),
            Err(ParseMoneyError::UnknownCurrency("$".to_string()))
        );
    }

    #[test]
    fn assumed_currency_test() {
        let parser = Parser::new().assume_currency(&Currency::USD);

        assert_eq!(
            parser.parse("1.50").unwrap(),
            Money::from_minor(150, &Currency::USD)
        );
        assert_eq!(
            parser.parse("$1.50").unwrap(),
            Money::from_minor(150, &Currency::USD)
        );
        assert_eq!(
            parser.parse("$-1.50").unwrap(),
            Money::from_minor(-150, &Currency::USD)
        );
    }

    #[test]
    fn code_overrides_assumed_currency_test() {
        let parser = Parser::new().assume_currency(&Currency::USD);

        assert_eq!(
            parser.parse("1.50 EUR").unwrap(),
            Money::from_minor(150, &Currency::EUR)
        );
    }

    #[test]
    fn wrong_symbol_for_assumed_currency_test() {
        let parser = Parser::new().assume_currency(&Currency::EUR);

        assert_eq!(
            parser.parse("$1.50"),
            Err(ParseMoneyError::UnknownCurrency("$".to_string()))
        );
    }

    #[test]
    fn separators_test() {
        let parser = Parser::new().separators('.', ',');

        assert_eq!(
            parser.parse("1.500,00 EUR").unwrap(),
            Money::from_minor(150000, &Currency::EUR)
        );
    }

    #[test]
    fn grouping_spacing_is_not_checked_test() {
        assert_eq!(
            "1,00,0.50 USD".parse::<Money>().unwrap(),
            Money::from_decimal(dec!(1000.50), &Currency::USD)
        );
    }

    #[test]
    fn group_separator_in_fraction_is_invalid_test() {
        assert_eq!(
            "1.5,0 USD".parse::<Money>(),
            Err(ParseMoneyError::InvalidAmount)
        );
    }

    #[test]
    fn second_decimal_mark_is_invalid_test() {
        assert_eq!(
            "1.5.0 USD".parse::<Money>(),
            Err(ParseMoneyError::InvalidAmount)
        );
    }

    #[test]
    fn no_digits_is_invalid_test() {
        assert_eq!("USD".parse::<Money>(), Err(ParseMoneyError::InvalidAmount));
        assert_eq!("".parse::<Money>(), Err(ParseMoneyError::InvalidAmount));
    }

    #[test]
    fn amount_beyond_decimal_range_is_invalid_test() {
        assert_eq!(
            "99999999999999999999999999999999999999 USD".parse::<Money>(),
            Err(ParseMoneyError::InvalidAmount)
        );
    }

    #[test]
    fn digits_are_kept_verbatim_test() {
        let money: Money = "1.2345 USD".parse().unwrap();

        assert_eq!(money.amount(), dec!(1.2345));
    }

    #[test]
    fn zero_minor_digit_currency_test() {
        assert_eq!(
            "5 JPY".parse::<Money>().unwrap(),
            Money::from_major(5, &Currency::JPY)
        );
    }

    #[test]
    fn round_trips_format_renderings_test() {
        let money = Money::from_minor(-1234567, &Currency::USD);
        let parser = Parser::new().assume_currency(&Currency::USD);

        for format in [
            Format::new(),
            Format::new().symbol(),
            Format::new().amount_only(),
            Format::new().prefix().no_space(),
            Format::new().symbol().parentheses(),
            Format::new().no_grouping(),
            Format::new().grouping(&[3, 2]),
        ] {
            let rendered = money.format_with(&format).to_string();

            assert_eq!(
                parser.parse(&rendered).unwrap(),
                money,
                "rendering {rendered:?}"
            );
        }
    }
}