0
# Core Parsing Functions
1

2
The primary interface for compiling EBNF grammars and parsing input text using TatSu. These functions provide both one-step parsing for simple use cases and separate compilation for parser reuse and performance optimization.
3

4
## Capabilities
5

6
### Grammar Compilation
7

8
Compile EBNF grammar definitions into reusable parser models with memoization and optimization support.
9

10
```python { .api }
11
def compile(grammar, name=None, semantics=None, asmodel=False, config=None, **settings):
12
    """
13
    Compile an EBNF grammar into a parser model.
14
    
15
    Parameters:
16
    - grammar (str): EBNF grammar definition string
17
    - name (str, optional): Name for the parser (defaults to grammar filename base)
18
    - semantics (object, optional): Semantic actions object with rule methods
19
    - asmodel (bool): If True, use ModelBuilderSemantics automatically
20
    - config (ParserConfig, optional): Parser configuration object
21
    - **settings: Additional parser settings (trace, colorize, left_recursion, etc.)
22
    
23
    Returns:
24
    Model: Compiled parser model that can parse input text
25
    
26
    Raises:
27
    GrammarError: If grammar contains syntax or semantic errors
28
    """
29
```
30

31
Usage example:
32

33
```python
34
import tatsu
35

36
grammar = '''
37
    start = expr;
38
    expr = term ("+" term)*;
39
    term = factor ("*" factor)*;
40
    factor = "(" expr ")" | number;
41
    number = /\d+/;
42
'''
43

44
# Basic compilation
45
model = tatsu.compile(grammar)
46

47
# Compilation with options
48
model = tatsu.compile(
49
    grammar, 
50
    name="Calculator",
51
    trace=True,
52
    left_recursion=True
53
)
54

55
# Use the compiled model multiple times
56
result1 = model.parse("2 + 3")
57
result2 = model.parse("4 * 5")
58
```
59

60
### Direct Parsing
61

62
Parse input text using a grammar in a single function call, combining compilation and parsing for convenience.
63

64
```python { .api }
65
def parse(grammar, input, start=None, name=None, semantics=None, asmodel=False, config=None, **settings):
66
    """
67
    Parse input text using the provided grammar.
68
    
69
    Parameters:
70
    - grammar (str): EBNF grammar definition string
71
    - input (str): Text to parse
72
    - start (str, optional): Start rule name (defaults to first rule in grammar)
73
    - name (str, optional): Parser name for error reporting
74
    - semantics (object, optional): Semantic actions object
75
    - asmodel (bool): If True, use ModelBuilderSemantics automatically  
76
    - config (ParserConfig, optional): Parser configuration object
77
    - **settings: Additional parser settings
78
    
79
    Returns:
80
    Any: Parsed AST or result of semantic actions
81
    
82
    Raises:
83
    ParseException: If input cannot be parsed according to grammar
84
    FailedParse: Specific parse failure with position information
85
    """
86
```
87

88
Usage example:
89

90
```python
91
import tatsu
92

93
grammar = '''
94
    expr = number ("+" number)*;
95
    number = /\d+/;
96
'''
97

98
# Direct parsing
99
result = tatsu.parse(grammar, "1 + 2 + 3")
100
print(result)  # ['1', ['+', '2'], ['+', '3']]
101

102
# Parsing with semantic actions
103
class CalcSemantics:
104
    def number(self, ast):
105
        return int(ast)
106
    
107
    def expr(self, ast):
108
        result = ast[0]
109
        for op, num in ast[1]:
110
            result += num
111
        return result
112

113
result = tatsu.parse(grammar, "1 + 2 + 3", semantics=CalcSemantics())
114
print(result)  # 6
115
```
116

117
### Parser Model Interface
118

119
The compiled Model object provides methods for parsing input and accessing grammar information.
120

121
```python { .api }
122
class Model:
123
    """Compiled grammar model that can parse input text."""
124
    
125
    def parse(self, input, start=None, semantics=None, config=None, **settings):
126
        """
127
        Parse input text using this compiled grammar.
128
        
129
        Parameters:
130
        - input (str): Text to parse
131
        - start (str, optional): Start rule name
132
        - semantics (object, optional): Semantic actions object
133
        - config (ParserConfig, optional): Parser configuration
134
        - **settings: Additional parsing settings
135
        
136
        Returns:
137
        Any: Parsed AST or semantic action result
138
        """
139
    
140
    def pretty(self):
141
        """
142
        Return a pretty-printed version of the grammar.
143
        
144
        Returns:
145
        str: Formatted grammar text
146
        """
147
    
148
    def pretty_lean(self):
149
        """
150
        Return a lean pretty-printed version without annotations.
151
        
152
        Returns:
153
        str: Formatted grammar text without name: or ::Parameter annotations
154
        """
155
    
156
    @property
157
    def rules(self):
158
        """Get the grammar rules dictionary."""
159
    
160
    def nodecount(self):
161
        """
162
        Count the total number of nodes in the grammar AST.
163
        
164
        Returns:
165
        int: Total node count
166
        """
167
```
168

169
Usage example:
170

171
```python
172
model = tatsu.compile(grammar)
173

174
# Parse with the model
175
ast = model.parse("1 + 2 * 3")
176

177
# Get grammar information
178
print(f"Grammar has {len(model.rules)} rules")
179
print(f"Total nodes: {model.nodecount()}")
180

181
# Pretty print the grammar
182
print(model.pretty())
183
```
184

185
### Configuration Options
186

187
Common parser settings that can be passed to `compile()` and `parse()` functions:
188

189
```python { .api }
190
# Parser behavior settings
191
trace: bool = False          # Enable verbose parsing trace output
192
colorize: bool = False       # Use colored output in traces (requires colorama)
193
left_recursion: bool = True  # Enable left-recursion support
194
nameguard: bool = None       # Prevent tokens that are prefixes of others
195
whitespace: str = None       # Characters to skip during parsing
196

197
# Grammar processing settings  
198
filename: str = None         # Source filename for error reporting
199
ignorecase: bool = False     # Case-insensitive parsing
200
```
201

202
## Error Handling
203

204
Core parsing functions raise specific exceptions for different types of failures:
205

206
```python { .api }
207
# Grammar compilation errors
208
GrammarError         # Invalid grammar syntax or semantics
209
SemanticError        # Semantic action processing errors
210

211
# Parse failures
212
ParseException       # Base parsing exception
213
FailedParse         # Parse failure with position info
214
FailedToken         # Expected token not found
215
FailedPattern       # Regex pattern didn't match
216
FailedChoice        # No choice alternative matched
217
FailedKeyword       # Keyword match failed
218
```
219

220
Example error handling:
221

222
```python
223
import tatsu
224
from tatsu.exceptions import ParseException, GrammarError
225

226
try:
227
    # This will raise GrammarError - invalid grammar
228
    model = tatsu.compile("invalid grammar syntax")
229
except GrammarError as e:
230
    print(f"Grammar error: {e}")
231

232
try:
233
    # This will raise FailedParse - parse failure
234
    result = tatsu.parse("expr = 'hello';", "goodbye")
235
except ParseException as e:
236
    print(f"Parse failed: {e}")
237
    print(f"Position: line {e.line}, column {e.col}")
238
```