alkale 2.0.0

//! This module implements many helpful "built-in" methods to [`SourceCodeScanner`].
//!
//! This module and submodules are fairly barren, generally only containing helper
//! types and errors for various new methods.

use core::str;

use crate::{
    span::{Span, Spannable, Spanned},
    SourceCodeScanner,
};

pub mod identifier;
pub mod numeric;
pub mod string;
pub mod structure;

impl<'src> SourceCodeScanner<'src> {
    /// Executes the input predicate and then returns a spanned [`prim@str`]
    /// over the entire region of source code that was consumed.
    ///
    /// # Examples
    /// ```rust
    /// # use alkale::SourceCodeScanner;
    /// # use alkale::span::Span;
    /// let scanner = SourceCodeScanner::new("abcdef");
    ///
    /// let capture = scanner.capture_str(|| {
    ///     scanner.skip();
    ///     scanner.skip();
    ///     scanner.skip();
    /// });
    ///
    /// # unsafe {
    /// assert_eq!(capture, Span::new(0, 3).wrap("abc"));
    /// # }
    ///
    /// ```
    ///
    /// # See Also
    /// Use [`capture_span`][Self::capture_span] if only the [`Span`][crate::span::Span]
    /// is desired.
    #[inline]
    pub fn capture_str<F: FnOnce()>(&self, predicate: F) -> Spanned<&'src str> {
        let start_pos = self.span();

        let range = self.consume_range(predicate);

        let end_pos = self.span();

        range.spanned(start_pos.up_to(&end_pos))
    }

    /// Repeatedly skip characters until EOF or until a character is found
    /// that matches the input predicate.
    ///
    /// # Examples
    /// ```rust
    /// # use alkale::SourceCodeScanner;
    /// # use alkale::span::Span;
    /// fn recovery(c: char) -> bool {
    ///     c == ';' || c == ','
    /// }
    ///
    /// let scanner = SourceCodeScanner::new("blabla broken code, also broken; working yahoo");
    ///
    /// assert_eq!(scanner.next(), Some('b'));
    ///
    /// scanner.skip_until_match(recovery);
    /// assert_eq!(scanner.next(), Some(','));
    ///
    /// scanner.skip_until_match(recovery);
    /// assert_eq!(scanner.next(), Some(';'));
    ///
    /// scanner.skip_until_match(recovery);
    /// assert_eq!(scanner.next(), None);
    /// ```
    ///
    /// # See Also
    /// A more efficient version for individual characters: [`skip_until`][SourceCodeScanner::skip_until].
    #[inline]
    pub fn skip_until_match<F: Fn(char) -> bool>(&self, predicate: F) {
        while let Some(char) = self.peek() {
            if predicate(char) {
                break;
            } else {
                self.skip();
            }
        }
    }

    /// Repeatedly skip characters until EOF or until the argument character is found.
    ///
    /// # Examples
    /// ```rust
    /// # use alkale::SourceCodeScanner;
    /// # use alkale::span::Span;
    /// let scanner = SourceCodeScanner::new("abcd;efghi;jklmn");
    ///
    /// assert_eq!(scanner.next(), Some('a'));
    ///
    /// scanner.skip_until(';');
    /// scanner.skip();
    /// assert_eq!(scanner.next(), Some('e'));
    ///
    /// scanner.skip_until(';');
    /// scanner.skip();
    /// assert_eq!(scanner.next(), Some('j'));
    ///
    /// scanner.skip_until(';');
    /// assert_eq!(scanner.next(), None);
    /// ```
    #[inline]
    pub fn skip_until(&self, match_character: char) {
        while let Some(char) = self.peek() {
            if char == match_character {
                break;
            } else {
                self.skip();
            }
        }
    }

    /// Executes the input predicate and then returns a [`Span`][crate::span::Span]
    /// over the entire region of source code that was consumed.
    ///
    /// # Examples
    /// ```rust
    /// # use alkale::SourceCodeScanner;
    /// # use alkale::span::Span;
    /// let scanner = SourceCodeScanner::new("abcdef");
    ///
    /// let capture = scanner.capture_span(|| {
    ///     scanner.skip();
    ///     scanner.skip();
    ///     scanner.skip();
    /// });
    ///
    /// # unsafe {
    /// assert_eq!(capture, Span::new(0, 3));
    /// # }
    /// ```
    ///
    /// # See Also
    /// Use [`capture_str`][Self::capture_str] if the consumed region needs to be
    /// analyzed afterwards.
    #[inline]
    pub fn capture_span<F: FnOnce()>(&self, predicate: F) -> Span {
        let start_position = self.span();

        predicate();

        start_position.up_to(&self.span())
    }

    /// The same as [`next`](Self::next) but includes the [`Span`] of the
    /// character in the returned value.
    ///
    /// # Examples
    /// ```rust
    /// # use alkale::SourceCodeScanner;
    /// # use alkale::span::Span;
    /// let scanner = SourceCodeScanner::new("ABC");
    ///
    /// # unsafe {
    /// assert_eq!(scanner.next_span(), Some(Span::new(0, 1).wrap('A')));
    /// assert_eq!(scanner.next_span(), Some(Span::new(1, 1).wrap('B')));
    /// assert_eq!(scanner.next_span(), Some(Span::new(2, 1).wrap('C')));
    /// assert_eq!(scanner.next_span(), None);
    /// # }
    /// ```
    #[inline]
    pub fn next_span(&self) -> Option<Spanned<char>> {
        let span = self.span();

        self.next().map(|char| span.wrap(char))
    }

    /// Returns true if the next character is equal to the argument character.
    /// Returns false on EOF.
    /// Does not modify the underlying iterator.
    ///
    /// # Examples
    /// ```rust
    /// # use alkale::SourceCodeScanner;
    /// # use alkale::span::Span;
    /// let scanner = SourceCodeScanner::new("ABC");
    ///
    /// assert!(scanner.peek_is('A'));
    ///
    /// scanner.skip();
    /// scanner.skip();
    ///
    /// assert!(scanner.peek_is('C'));
    ///
    /// scanner.skip();
    ///
    /// assert!(!scanner.peek_is('D'));
    /// ```
    #[inline]
    pub fn peek_is(&self, char: char) -> bool {
        self.peek() == Some(char)
    }

    /// Returns true if the next character matches the predicate.
    /// Returns false on EOF.
    /// Does not modify the underlying iterator.
    ///
    /// # Examples
    /// ```rust
    /// # use alkale::SourceCodeScanner;
    /// # use alkale::span::Span;
    /// let scanner = SourceCodeScanner::new("AB#");
    ///
    /// assert!(scanner.peek_is_map(|c| c.is_ascii_alphabetic()));
    ///
    /// scanner.skip();
    /// scanner.skip();
    ///
    /// assert!(!scanner.peek_is_map(|c| c.is_ascii_alphabetic()));
    ///
    /// scanner.skip();
    ///
    /// assert!(!scanner.peek_is_map(|c| c.is_ascii_alphabetic()));
    /// ```
    #[inline]
    pub fn peek_is_map<F: FnOnce(char) -> bool>(&self, predicate: F) -> bool {
        self.peek().map_or(false, predicate)
    }

    /// Returns true if the next character isn't equal to the argument character.
    /// Returns true on EOF.
    /// Does not modify the underlying iterator.
    ///
    /// # Examples
    /// ```rust
    /// # use alkale::SourceCodeScanner;
    /// # use alkale::span::Span;
    /// let scanner = SourceCodeScanner::new("ABC");
    ///
    /// assert!(scanner.peek_is_not('C'));
    ///
    /// scanner.skip();
    /// scanner.skip();
    ///
    /// assert!(!scanner.peek_is_not('C'));
    ///
    /// scanner.skip();
    ///
    /// assert!(scanner.peek_is_not('C'));
    /// ```
    #[inline]
    pub fn peek_is_not(&self, char: char) -> bool {
        self.peek() != Some(char)
    }
}

/// Used to map very simple, single-char patterns into tokens and automatically append them to a [`LexerResult`][crate::LexerResult].
///
/// Takes a [`SourceCodeScanner`], a mutable reference [`LexerResult`][crate::LexerResult], and 0 or more
/// "patterns." Each pattern maps a single character to a token type.
///
/// If any pattern matches the next character, that character will be consumed, and the relevant token will be
/// pushed to the result with the correct [`Span`][crate::span::Span]. If no patterns matched, this is a no-op.
///
/// # Example
/// ```rust
/// # use alkale::SourceCodeScanner;
/// # use alkale::LexerResult;
/// # use alkale::map_single_char_token;
/// # use alkale::span::Span;
/// # use alkale::token::Token;
///
/// #[derive(Debug, PartialEq, Eq)]
/// enum Data {
///     Plus,
///     Minus,
///     Asterisk,
///     Slash,
/// }
///
/// let context = SourceCodeScanner::new("++-*/-");
/// let mut result = LexerResult::<_, ()>::new();
///
/// while context.has_next() {
///     map_single_char_token!(&context, &mut result,
///         '+' => Data::Plus,
///         '-' => Data::Minus,
///         '*' => Data::Asterisk,
///         '/' => Data::Slash,
///     );
///
///     // This macro calls "continue" if it matches a character and correctly
///     // pushes a token; this should never panic.
///     panic!("Unknown character");
/// }
///
/// # unsafe {
/// assert_eq!(result.finalize().tokens().unwrap(), &vec![
///     Token::new(Data::Plus, Span::new_single(0)),
///     Token::new(Data::Plus, Span::new_single(1)),
///     Token::new(Data::Minus, Span::new_single(2)),
///     Token::new(Data::Asterisk, Span::new_single(3)),
///     Token::new(Data::Slash, Span::new_single(4)),
///     Token::new(Data::Minus, Span::new_single(5)),
/// ])
/// # }
///
///
/// ```
#[macro_export]
macro_rules! map_single_char_token {
    ($e:expr, $r:expr, $($pat:pat => $value:expr),* $(,)?) => {
        match $crate::SourceCodeScanner::peek($e) {
            $(core::option::Option::Some($pat) => {
                let span = $crate::SourceCodeScanner::span($e);
                $crate::SourceCodeScanner::skip($e);
                $crate::LexerResult::push_token($r, $crate::token::Token::new($value, span));
                continue;
            },)*
            _ => {},
        };
    }
}

/// Used to map one-to-two-char patterns into tokens and automatically append them to a [`LexerResult`][crate::LexerResult].
///
/// The first character of a set of tokens will always be consumed.
/// i.e. if parsing out `+`, `+=`, and `++`, this macro will *always* consume `+` characters.
///
/// This macro takes in a mutable reference to [`SourceCodeScanner`] and then 0 or more patterns that map a character
/// to a "match body." Each match body contains 1 or more sub-patterns which map a character to token data. The final
/// pattern of each "match body" must be a catch-all `_ => ...`.
///
/// When this macro is reached during lexing, the next character in the source code will be checked. If it matches
/// *any* branch within this macro, then it will be consumed. Afterwards, the *next* character in the source code will
/// be checked against the first character's "match body," and consumed if it does.
///
/// After one or two characters have been consumed, a token will be generated based on the matched characters and automatically
/// pushed to the context with the correct [`Span`][crate::span::Span]. Afterwards, `continue;` is called.
///
/// This macro is a no-op if the next character in the source code doesn't match any pattern.
///
/// # Example
/// ```rust
/// # use alkale::SourceCodeScanner;
/// # use alkale::LexerResult;
/// # use alkale::map_double_char_tokens;
/// # use alkale::span::Span;
/// # use alkale::token::Token;
///
/// #[derive(Debug, PartialEq, Eq)]
/// enum Data {
///     Plus,
///     DoublePlus,
///     PlusEquals,
///     Minus,
///     DoubleMinus,
///     MinusEquals,
/// }
///
/// let context = SourceCodeScanner::new("+ += -- ++ - -=");
/// let mut result = LexerResult::<_, ()>::new();
///
/// while context.has_next() {
///     context.skip_whitespace();
///
///     map_double_char_tokens!(&context, &mut result,
///         '+' => {
///             '+' => Data::DoublePlus,
///             '=' => Data::PlusEquals,
///             _ => Data::Plus,
///         },
///         '-' => {
///             '-' => Data::DoubleMinus,
///             '=' => Data::MinusEquals,
///             _ => Data::Minus,
///         },
///     );
///
///     // This macro calls "continue" if it matches a character and correctly
///     // pushes a token; this should never panic.
///     panic!("Unknown character");
/// }
///
/// # unsafe {
/// assert_eq!(result.finalize().tokens().unwrap(), &vec![
///     Token::new(Data::Plus, Span::new(0, 1)),
///     Token::new(Data::PlusEquals, Span::new(2, 2)),
///     Token::new(Data::DoubleMinus, Span::new(5, 2)),
///     Token::new(Data::DoublePlus, Span::new(8, 2)),
///     Token::new(Data::Minus, Span::new(11, 1)),
///     Token::new(Data::MinusEquals, Span::new(13, 2)),
/// ])
/// # }
///
///
/// ```
#[macro_export]
macro_rules! map_double_char_tokens {
    ($e:expr, $r:expr, $($char:literal => { $($pat:literal => $value:expr,)* _ => $final_value:expr $(,)? }),* $(,)?) => {
        match $crate::SourceCodeScanner::peek($e) {
            $(
                core::option::Option::Some($char) => {
                    let initial_span = $crate::SourceCodeScanner::span($e);
                    $crate::SourceCodeScanner::skip($e);

                    let data = match $crate::SourceCodeScanner::peek($e) {
                        $(
                            core::option::Option::Some($pat) => {
                                $crate::SourceCodeScanner::skip($e);
                                $value
                            },
                        )*
                        _ => {
                            $final_value
                        }
                    };

                    let span = $crate::SourceCodeScanner::span($e);

                    $crate::LexerResult::push_token(
                        $r,
                        $crate::token::Token::new(data, $crate::span::Span::up_to(&initial_span, &span))
                    );

                    continue;

                },
            )*
            _ => {

            }
        }
    }
}

#[cfg(test)]
mod tests {
    use crate::{
        span::{Span, Spannable},
        SourceCodeScanner,
    };

    fn ctx(code: &str) -> SourceCodeScanner {
        SourceCodeScanner::new(code)
    }

    #[test]
    fn recover_with() {
        let code = ctx("1 blabla whatever 2 yea yea 3 ... 4");

        // SAFETY: Spans are all valid.
        unsafe {
            code.skip_until_match(|x| x.is_numeric());
            assert_eq!(code.next_span(), Some('1'.spanned(Span::new(0, 1))));

            code.skip_until_match(|x| x.is_numeric());
            assert_eq!(code.next_span(), Some('2'.spanned(Span::new(18, 1))));

            code.skip_until_match(|x| x.is_numeric());
            assert_eq!(code.next_span(), Some('3'.spanned(Span::new(28, 1))));

            code.skip_until_match(|x| x.is_numeric());
            assert_eq!(code.next_span(), Some('4'.spanned(Span::new(34, 1))));

            assert!(!code.has_next());

            code.skip_until_match(|x| x.is_numeric());

            assert!(!code.has_next());
        }
    }

    #[test]
    fn skip_until() {
        let code = ctx("|1 blabla whatever |2 yea yea |3 ... |");

        // SAFETY: Spans are all valid.
        unsafe {
            code.skip_until('|');
            assert_eq!(code.next_span(), Some('|'.spanned(Span::new(0, 1))));

            code.skip_until('|');
            assert_eq!(code.next_span(), Some('|'.spanned(Span::new(19, 1))));

            code.skip_until('|');
            assert_eq!(code.next_span(), Some('|'.spanned(Span::new(30, 1))));

            code.skip_until('|');
            assert_eq!(code.next_span(), Some('|'.spanned(Span::new(37, 1))));

            assert!(!code.has_next());

            code.skip_until('|');

            assert!(!code.has_next());
        }
    }

    #[test]
    fn capture_span() {
        let code = ctx("ABCDEFGHIJKLMNOPQRSTUVWXYZ");

        code.skip();
        code.skip();

        let mut out = String::new();

        let span = code.capture_span(|| {
            out.push(code.next().unwrap());
            out.push(code.next().unwrap());
            out.push(code.next().unwrap());
            out.push(code.next().unwrap());
        });

        // SAFETY: Span is valid.
        unsafe {
            assert_eq!(span, Span::new(2, 4));
        }

        assert_eq!(out, "CDEF");
    }

    #[test]
    fn capture_str() {
        let code = ctx("this is one string|this is another|and another!");
        let mut collected = vec![];

        while code.has_next() {
            let res = code.capture_str(|| {
                while code.has_next() {
                    if code.peek_is('|') {
                        break;
                    }

                    code.skip();
                }
            });

            code.skip();

            collected.push(res);
        }

        assert_eq!(
            collected,
            // SAFETY: Spans are valid.
            unsafe {
                vec![
                    (Span::new(0, 18).wrap("this is one string")),
                    (Span::new(19, 15).wrap("this is another")),
                    (Span::new(35, 12).wrap("and another!")),
                ]
            }
        );

        assert!(!code.has_next());
    }
}