trivet 3.1.0

// Trivet
// Copyright (c) 2025 by Stacy Prowell.  All rights reserved.
// https://gitlab.com/binary-tools/trivet

//! Provide parsing for "keywords."  These are typically sequences of letters, digits,
//! and underscores, often required to start with a letter or underscore to separate
//! them from numbers.

use crate::{
    errors::{syntax_error, ParseResult},
    ParserCore,
};

/// Parse a keyword.
///
///
pub struct KeywordParser {
    /// Whether digits are permitted in the keyword.  If this is true, the first character
    /// of the keyword cannot be a digit, but subsequent characters can be.
    ///
    /// Enabled by default.
    pub permit_digits: bool,

    /// Whether underscores are permitted in the keyword.  If this is true, the first
    /// character of a keyword is also permitted to be an underscore.
    ///
    /// Enabled by default.
    pub permit_underscores: bool,

    /// If true, permit hyphens and transclude them as underscores.  That is, the string
    /// `my-keyword-here` is parsed and returned as `my_keyword_here`.  Note that this
    /// is only meaningful if `permit_underscores` is `true`.  Leading hyphens are
    /// also transcluded, so `--fred--` becomes `__fred__`.
    ///
    /// Disabled by default.
    pub transclude_hyphens: bool,

    /// A closure that defines what characters are permitted in a keyword.  This is
    /// not used unless `use_permit` is set to true.
    ///
    /// The argument is the current state, specified by a `u32`, and a character to test.
    ///
    /// The output is a Boolean that determines if the character is permitted, and a
    /// new state value.  Your implementation must accept the state zero as the initial
    /// state, and may generate any negative number to indicate an error state.  If the
    /// method returns `false` with any positive state, then the keyword is assumed to
    /// be fully parsed and accepted.
    ///
    /// The default implementation of this method accepts ASCII alphabetic characters
    /// only.
    ///
    /// ```
    /// use trivet::parse_from_string;
    /// use trivet::parsers::keyword::KeywordParser;
    /// let mut kwp = KeywordParser::new();
    /// kwp.permit = Box::new(|state, ch| {
    ///     (ch.is_alphabetic(), 0)
    /// });
    /// kwp.use_permit = true;
    /// let mut parser = parse_from_string("keyword key");
    /// assert_eq!(kwp.parse(parser.borrow_core()).unwrap(), "keyword");
    /// parser.consume_ws();
    /// assert_eq!(kwp.parse(parser.borrow_core()).unwrap(), "key");
    /// ```
    ///
    /// The following accepts keywords that start with an underscore or letter and that
    /// may contain letters, digits, and underscores.
    ///
    /// ```
    /// use trivet::parse_from_string;
    /// use trivet::parsers::keyword::KeywordParser;
    /// let mut kwp = KeywordParser::new();
    /// kwp.permit = Box::new(|state, ch| {
    ///     match state {
    ///         0 => (ch == '_' || ch.is_alphabetic(), 1),
    ///         _ => (ch == '_' || ch.is_alphanumeric(), 1),
    ///     }
    /// });
    /// kwp.use_permit = true;
    /// let mut parser = parse_from_string("key1_rd __12key");
    /// assert_eq!(kwp.parse(parser.borrow_core()).unwrap(), "key1_rd");
    /// parser.consume_ws();
    /// assert_eq!(kwp.parse(parser.borrow_core()).unwrap(), "__12key");
    /// ```
    pub permit: Box<dyn Fn(i32, char) -> (bool, i32)>,

    /// A closure that defines how characters are transformed as they are read.  This
    /// transformation is performed before checking for inclusion with, say, `permit`.
    ///
    /// For example, the following permits colons in a keyword by transforming them
    /// into underscores.
    ///
    /// ```
    /// use trivet::parse_from_string;
    /// use trivet::parsers::keyword::KeywordParser;
    /// let mut kwp = KeywordParser::new();
    /// kwp.permit_underscores = true;
    /// kwp.use_transform = true;
    /// kwp.transform = Box::new(|ch| -> char {
    ///     if ch == ':' { '_' } else { ch }
    /// });
    /// let mut parser = parse_from_string("k::d __12:key");
    /// assert_eq!(kwp.parse(parser.borrow_core()).unwrap(), "k__d");
    /// parser.consume_ws();
    /// assert_eq!(kwp.parse(parser.borrow_core()).unwrap(), "__12_key");
    /// ```
    pub transform: Box<dyn Fn(char) -> char>,

    /// If `true`, use the `permit` closure to test characters.  If `false`, do not.  If
    /// this is `true`, then other permit flags are ignored.
    ///
    /// Disabled by default.
    pub use_permit: bool,

    /// If `true`, use the `transform` closure to test characters.  If `false`, do not.
    /// If this is `true`, then other transform flags are ignored.
    ///
    /// Disabled by default.
    pub use_transform: bool,
}

impl KeywordParser {
    /// Make a new keyword parser with the default settings.
    pub fn new() -> Self {
        Self {
            permit: Box::new(|_, ch: char| (ch.is_alphabetic(), 0)),
            transform: Box::new(|ch| ch),
            use_permit: false,
            use_transform: false,
            permit_digits: true,
            permit_underscores: true,
            transclude_hyphens: false,
        }
    }

    /// Parse the next keyword using the provided parser core and the current settings.
    pub fn parse(&self, parser: &mut ParserCore) -> ParseResult<String> {
        if self.use_permit {
            self.parse_with_permit(parser)
        } else if self.permit_underscores && self.permit_digits {
            self.parse_keyword(
                parser,
                |ch| ch == '_' || ch.is_alphabetic(),
                |ch| ch == '_' || ch.is_alphanumeric(),
            )
        } else if self.permit_underscores {
            self.parse_keyword(
                parser,
                |ch| ch == '_' || ch.is_alphabetic(),
                |ch| ch == '_' || ch.is_alphabetic(),
            )
        } else if self.permit_digits {
            self.parse_keyword(parser, |ch| ch.is_alphabetic(), |ch| ch.is_alphanumeric())
        } else {
            self.parse_keyword(parser, |ch| ch.is_alphabetic(), |ch| ch.is_alphabetic())
        }
    }

    /// Parse a keyword.
    ///
    /// This method uses two provided closures.  The `first` closure must be true for
    /// the first character of the keyword or an error is generated.  Then characters
    /// are accumulated so long as the `next` closure is true.
    fn parse_keyword(
        &self,
        parser: &mut ParserCore,
        first: impl Fn(char) -> bool,
        next: impl Fn(char) -> bool,
    ) -> ParseResult<String> {
        let mut kw = String::new();
        let ch = if self.use_transform {
            (self.transform)(parser.peek())
        } else {
            let ch = parser.peek();
            if self.transclude_hyphens && ch == '-' {
                '_'
            } else {
                ch
            }
        };
        if !first(ch) {
            return Err(syntax_error(
                parser.loc(),
                &format!("Expected keyword but found '{}'", ch),
            ));
        }
        kw.push(ch);
        parser.consume();
        loop {
            let ch = if self.use_transform {
                (self.transform)(parser.peek())
            } else {
                let ch = parser.peek();
                if self.transclude_hyphens && ch == '-' {
                    '_'
                } else {
                    ch
                }
            };
            if next(ch) {
                kw.push(ch);
                parser.consume();
            } else {
                break;
            }
        }
        Ok(kw)
    }

    /// Parse using the permit closure.
    fn parse_with_permit(&self, parser: &mut ParserCore) -> ParseResult<String> {
        let mut state = 0;
        let mut result = String::new();
        loop {
            if parser.is_at_eof() {
                return Ok(result);
            }
            let mut ch = parser.peek();
            if self.use_transform {
                ch = (self.transform)(ch)
            }
            let (accept, newstate) = (self.permit)(state, ch);
            if newstate < 0 {
                return Err(syntax_error(parser.loc(), "Error parsing keyword"));
            }
            if accept {
                parser.consume();
                state = newstate;
                result.push(ch)
            } else {
                return Ok(result);
            }
        }
    }
}

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

#[cfg(test)]
mod test {
    use crate::{errors::ParseResult, parse_from_string};

    use super::KeywordParser;

    fn parse(kwp: &KeywordParser, value: &str) -> ParseResult<String> {
        let mut parser = parse_from_string(value);
        kwp.parse(parser.borrow_core())
    }

    #[test]
    fn primitive_keyword_test() {
        let next = |ch: char| ch.is_alphabetic();
        let first = |ch: char| ch == '&';
        let kwp = KeywordParser::new();
        let mut parser = parse_from_string("&wyvern");
        assert_eq!(
            kwp.parse_keyword(parser.borrow_core(), first, next)
                .unwrap(),
            "&wyvern"
        );
        let mut parser = parse_from_string("&");
        assert_eq!(
            kwp.parse_keyword(parser.borrow_core(), first, next)
                .unwrap(),
            "&"
        );
        let mut parser = parse_from_string("wyvern");
        assert!(kwp
            .parse_keyword(parser.borrow_core(), first, next)
            .is_err());
    }

    #[test]
    fn default_keyword_test() {
        let samples = &[
            ("source", "source"),
            ("_fred", "_fred"),
            ("fred_", "fred_"),
            ("fred12", "fred12"),
            ("f12red", "f12red"),
            ("_fred12", "_fred12"),
            ("_12fred", "_12fred"),
            ("___12___", "___12___"),
            ("fred--12", "fred"),
            ("-fred", ""),
            ("12", ""),
            ("", ""),
            ("16_fred", ""),
            ("&f", ""),
        ];
        let kwp = KeywordParser::default();
        for (in_str, out_str) in samples {
            println!("Testing sample {}", in_str);
            if out_str.is_empty() {
                assert!(parse(&kwp, in_str).is_err())
            } else {
                assert_eq!(&parse(&kwp, in_str).unwrap(), out_str)
            }
        }
    }

    #[test]
    fn no_digits_test() {
        let samples = &[
            ("source", "source"),
            ("_fred", "_fred"),
            ("fred_", "fred_"),
            ("fred12", "fred"),
            ("f12red", "f"),
            ("_fred12", "_fred"),
            ("_12fred", "_"),
            ("___12___", "___"),
            ("fred--12", "fred"),
            ("-fred", ""),
            ("12", ""),
            ("", ""),
            ("16_fred", ""),
        ];
        let kwp = KeywordParser {
            permit_digits: false,
            ..Default::default()
        };
        for (in_str, out_str) in samples {
            println!("Testing sample {}", in_str);
            if out_str.is_empty() {
                assert!(parse(&kwp, in_str).is_err())
            } else {
                assert_eq!(&parse(&kwp, in_str).unwrap(), out_str)
            }
        }
    }

    #[test]
    fn no_underscores_test() {
        let samples = &[
            ("source", "source"),
            ("_fred", ""),
            ("fred_", "fred"),
            ("fred12", "fred12"),
            ("f12red", "f12red"),
            ("_fred12", ""),
            ("_12fred", ""),
            ("___12___", ""),
            ("fred--12", "fred"),
            ("-fred", ""),
            ("12", ""),
            ("", ""),
            ("16_fred", ""),
        ];
        let kwp = KeywordParser {
            permit_underscores: false,
            ..Default::default()
        };
        for (in_str, out_str) in samples {
            println!("Testing sample {}", in_str);
            if out_str.is_empty() {
                assert!(parse(&kwp, in_str).is_err())
            } else {
                assert_eq!(&parse(&kwp, in_str).unwrap(), out_str)
            }
        }
    }

    #[test]
    fn no_underscores_or_digits_test() {
        let samples = &[
            ("source", "source"),
            ("_fred", ""),
            ("fred_", "fred"),
            ("fred12", "fred"),
            ("f12red", "f"),
            ("_fred12", ""),
            ("_12fred", ""),
            ("___12___", ""),
            ("fred__12", "fred"),
            ("_fred", ""),
            ("12", ""),
            ("", ""),
            ("16_fred", ""),
        ];
        let kwp = KeywordParser {
            permit_digits: false,
            permit_underscores: false,
            ..Default::default()
        };
        for (in_str, out_str) in samples {
            println!("Testing sample {}", in_str);
            if out_str.is_empty() {
                assert!(parse(&kwp, in_str).is_err())
            } else {
                assert_eq!(&parse(&kwp, in_str).unwrap(), out_str)
            }
        }
    }

    #[test]
    fn hyphens_test() {
        let samples = &[
            ("source", "source"),
            ("_fred", "_fred"),
            ("fred_", "fred_"),
            ("fred12--", "fred12__"),
            ("f-12-red", "f_12_red"),
            ("-fred12", "_fred12"),
            ("-_-12fred", "___12fred"),
            ("___12___", "___12___"),
            ("fred--12", "fred__12"),
            ("-fred", "_fred"),
            ("-12", "_12"),
            ("12", ""),
            ("", ""),
            ("16_fred", ""),
        ];
        let kwp = KeywordParser {
            transclude_hyphens: true,
            ..Default::default()
        };
        for (in_str, out_str) in samples {
            println!("Testing sample {}", in_str);
            if out_str.is_empty() {
                assert!(parse(&kwp, in_str).is_err())
            } else {
                assert_eq!(&parse(&kwp, in_str).unwrap(), out_str)
            }
        }
    }

    #[test]
    fn transform_test() {
        let samples = &[
            ("source", "source"),
            ("_fred", "_fred"),
            ("fred_", "fred_"),
            ("fred12::", "fred12__"),
            ("f:12:red", "f_12_red"),
            (":fred12", "_fred12"),
            (":_:12fred", "___12fred"),
            ("___12___", "___12___"),
            ("fred::12", "fred__12"),
            (":fred", "_fred"),
            (":12", "_12"),
            ("12", ""),
            ("", ""),
            ("16_fred", ""),
        ];
        let kwp = KeywordParser {
            use_transform: true,
            transform: Box::new(|ch| if ch == ':' { '_' } else { ch }),
            ..Default::default()
        };
        for (in_str, out_str) in samples {
            println!("Testing sample {}", in_str);
            if out_str.is_empty() {
                assert!(parse(&kwp, in_str).is_err())
            } else {
                assert_eq!(&parse(&kwp, in_str).unwrap(), out_str)
            }
        }
    }

    #[test]
    fn permit_test() {
        let samples = &[
            ("$source", "$source"),
            ("$fred", "$fred"),
            ("$fred.", "$fred."),
            ("$fred.12", ""),
            ("$f12.$red", "$f12.$red"),
            ("$fred.$12", "$fred.$12"),
            ("$12.fred", ""),
            ("$12", "$12"),
            ("$fred.$12", "$fred.$12"),
            ("fred", ""),
            ("$$12", "$"),
            ("$.$12", "$.$12"),
            ("$", "$"),
            ("$16fred", "$16fred"),
        ];
        let kwp = KeywordParser {
            use_transform: true,
            use_permit: true,
            permit: Box::new(|state, ch| match state {
                0 if ch == '$' => (true, 1),
                0 => (false, -1),
                1 if ch.is_alphanumeric() => (true, 1),
                1 if ch == '.' => (true, 0),
                _ => (false, 1),
            }),
            ..Default::default()
        };
        for (in_str, out_str) in samples {
            println!("Testing sample {}", in_str);
            if out_str.is_empty() {
                assert!(parse(&kwp, in_str).is_err())
            } else {
                assert_eq!(&parse(&kwp, in_str).unwrap(), out_str)
            }
        }
    }
}