droll 0.1.0

Dice notation parser and interpeter library
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136

use std::{
    iter::{self, Peekable},
    str::Chars,
};

#[derive(Debug, Clone, Copy, PartialEq)]
/// Represents the different types of tokens that can be parsed from the input.
pub enum Token {
    /// Represents a numeric value.
    Number(usize),
    /// Represents the addition operator.
    Plus,
    /// Represents the subtraction operator.
    Minus,
    /// Represents a die token in dice notation.
    Die,
}

/// Performs lexical analysis of the provided string, transforming it into a vector of [`Token`]s.
///
/// Lexical analysis, often referred to as tokenization, is the process of breaking down a string
/// into meaningful units called tokens. In this context:
///
/// - A [`Token`] represents a type of dice notation unit parsed from the input string.
///
/// - The function returns a [`Result`] to handle potential errors:
///   - `Err(String)`: Signifies that unexpected or invalid characters were encountered during
///     tokenization.
///   - `Ok(Vec<Token>)`: Indicates a successful tokenization process, producing a vector
///     containing the identified dice notation tokens.
///
/// # Example
///
/// Basic Usage:
///
/// ```
/// use droll::lexer::{Token,lex};
///
/// let dice_notation = "1d20+10";
/// let tokens = lex(dice_notation).unwrap();
///
/// assert_eq!(vec![Token::Number(1), Token::Die, Token::Number(20), Token::Plus, Token::Number(10)], tokens);
/// ```
pub fn lex(input: &str) -> Result<Vec<Token>, String> {
    let mut chars = input.chars().peekable();

    let mut tokens: Vec<Token> = Vec::new();

    while let Some(&char) = chars.to_owned().peek() {
        tokens.push(parse_token(char, &mut chars)?);
    }

    Ok(tokens)
}

/// Converts a [`char`] into an operator token.
fn operator_token(char: char, chars: &mut Peekable<Chars>) -> Result<Token, String> {
    chars.next();
    match char {
        '+' => Ok(Token::Plus),
        '-' => Ok(Token::Minus),
        'd' => Ok(Token::Die),
        c => error_unexpected_character(c),
    }
}

/// Converts consecutive characters into a number token, extending as long as the following
/// characters are ASCII digits.
fn number_token(chars: &mut Peekable<Chars>) -> Result<Token, String> {
    match iter::from_fn(|| chars.next_if(|c| c.is_ascii_digit()))
        .collect::<String>()
        .parse::<usize>()
    {
        Ok(number) => Ok(Token::Number(number)),
        parse_err => Err(parse_err.unwrap_err().to_string()),
    }
}

/// Converts a [`char`] into a [`Token`].
fn parse_token(char: char, chars: &mut Peekable<Chars>) -> Result<Token, String> {
    match char {
        '1'..='9' => number_token(chars),
        '+' | '-' | 'd' => operator_token(char, chars),
        c => error_unexpected_character(c),
    }
}

fn error_unexpected_character<T>(c: char) -> Result<T, String> {
    Err(format!("Unexpected character: {}", c))
}

#[test]
fn test_lex_valid() {
    let tests = [
        (
            "+-1234567890d",
            vec![
                Token::Plus,
                Token::Minus,
                Token::Number(1234567890),
                Token::Die,
            ],
        ),
        ("d20", vec![Token::Die, Token::Number(20)]),
        (
            "2d20",
            vec![Token::Number(2), Token::Die, Token::Number(20)],
        ),
        (
            "2d20+1d8",
            vec![
                Token::Number(2),
                Token::Die,
                Token::Number(20),
                Token::Plus,
                Token::Number(1),
                Token::Die,
                Token::Number(8),
            ],
        ),
        (
            "d20-10",
            vec![
                Token::Die,
                Token::Number(20),
                Token::Minus,
                Token::Number(10),
            ],
        ),
    ];

    tests.iter().for_each(|(input, expected)| {
        let actual = lex(input).unwrap();
        assert_eq!(actual, *expected, "for input `{:#?}`", input);
    })
}