gramma 0.2.24

Generate a scannerless parser by declaring types.
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
137
138
139
140
141
142
143
144
145
146

Define AST rules by declaring `struct`s and `enum`s.

# Basic Example
```rust
// Define Ident, LParen, RParen, Whitespace here:
gramma::define_token! {
    /* ... */
#    #[pattern(matcher = word_boundary() + !precedes(ascii_digit()) + word().repeat(1..).simple() )]
#    struct Ident;
#    #[pattern(exact = "(")]
#    struct LParen;
#    #[pattern(exact = ")")]
#    struct RParen;
#    #[pattern(matcher = whitespace().repeat(..).simple())]
#    struct Whitespace;
}
gramma::define_rule! {
 struct Group {
     l_paren: LParen,
     exprs: Vec<Expr>,
     r_paren: RParen,
 }
 // Enum rules may only have struct-like variants:
 #[transform(ignore_around<Whitespace>)]
 enum Expr {
     Group { group: Group },
     Ident { ident: Ident },
 }
}

let src = "
(list
    (add a b)
    (mul (sub c d) e)
)
";

let expr: Expr = gramma::parse_tree::<_, 1>(src).unwrap();

let display = format!("{:#}", gramma::display_tree(src, &expr));
assert_eq!(display, r#"Group -> {
    "(",
    [
        <Ident "list">,
        Group -> {
            "(",
            [
                <Ident "add">,
                <Ident "a">,
                <Ident "b">,
            ],
            ")",
        },
        Group -> {
            "(",
            [
                <Ident "mul">,
                Group -> {
                    "(",
                    [
                        <Ident "sub">,
                        <Ident "c">,
                        <Ident "d">,
                    ],
                    ")",
                },
                <Ident "e">,
            ],
            ")",
        },
    ],
    ")",
}"#);
```
# Transformations
In the example above, `Expr` was given the attribute
`#[transform(ignore_around<Whitespace>)]`.
Transformations, denoted by the `#[transform(...)]` attribute,
modify the way a rule is parsed.
All built-in transformations are declared as types in the
[ast::transform](crate::ast::transform) module.
Some of the more common transformations are:
<table>
<thead><tr><th>Transformation</th><th>Description</th></tr></thead>
<tr><td>

[`ignore_before<S>`](ignore_before)
</td><td>

Parse an _optional_ `S` before the target rule and discard the result if found.
Useful for ignoring optional whitespace before the target rule.
</td></tr><tr><td>

[`ignore_after<S>`](ignore_after)
</td><td>


Parse an _optional_ `S` after the target rule and discard the result if found.
Useful for ignoring optional whitespace after the target rule.
</td></tr><tr><td>

[`ignore_around<S1, S2 = S1>`](ignore_around)
</td><td>


Parse an _optional_ `S1` before and `S2` after the target rule and discard the results if found.
Useful for ignoring optional whitespace around the target rule.
</td></tr><tr><td>

[`discard_before<S>`](discard_before)
</td><td>

Parse a _required_ `S` before the target rule and discard the result.
Useful for matching punctuation before the target rule.
</td></tr><tr><td>

[`discard_after<S>`](discard_after)
</td><td>

Parse a _required_ `S` after the target rule and discard the result.
Useful for matching punctuation after the target rule.
</td></tr><tr><td>

[`discard_around<S1, S2 = S1>`](discard_around)
</td><td>

Parse a _required_ `S1` before and `S2` after the target rule and discard the results.
Useful for matching punctuation around the target rule.
</td></tr><tr><td>

[`not<Invalid>`](not)
</td><td>

Rejects if the section matched by the target rule starts with `Invalid`.
</td></tr><tr><td>

[`for_each<X>`](for_each)
</td><td>

Apply the transformation `X` to each item in the target rule.
Useful when matching a `Vec` of rules.
</td></tr>
</table>

A `#[transform(...)]` can be applied to the entirety of a `struct` or `enum` rule,
an `enum` variant, or an individual field.