0
# Parsy
1
2
A comprehensive Python library for building parser combinators in pure Python. Parsy provides a declarative way to construct complex parsers by combining simple, small parsers together. It offers a monadic parser combinator library for LL(infinity) grammars, inspired by Parsec, Parsnip, and Parsimmon.
3
4
## Package Information
5
6
- **Package Name**: parsy
7
- **Language**: Python
8
- **Installation**: `pip install parsy`
9
- **Python Support**: 3.5+
10
11
## Core Imports
12
13
```python
14
import parsy
15
```
16
17
Common for working with specific parsers:
18
19
```python
20
from parsy import string, regex, generate, seq, alt
21
```
22
23
Import all core functionality:
24
25
```python
26
from parsy import *
27
```
28
29
Version information:
30
31
```python
32
from parsy import __version__
33
```
34
35
## Basic Usage
36
37
```python
38
from parsy import string, regex, generate, seq, alt
39
40
# Simple string parser
41
hello_parser = string('hello')
42
result = hello_parser.parse('hello') # Returns 'hello'
43
44
# Regex parser
45
number_parser = regex(r'\d+').map(int)
46
result = number_parser.parse('123') # Returns 123
47
48
# Combining parsers with sequences
49
greeting_parser = seq(
50
string('hello'),
51
regex(r'\s+'),
52
regex(r'\w+')
53
).combine(lambda hello, space, name: f"{hello} {name}")
54
55
result = greeting_parser.parse('hello world') # Returns 'hello world'
56
57
# Using generator syntax for complex parsing
58
@generate
59
def simple_expression():
60
left = yield number_parser
61
operator = yield regex(r'\s*[+\-*/]\s*')
62
right = yield number_parser
63
return (left, operator.strip(), right)
64
65
result = simple_expression.parse('5 + 3') # Returns (5, '+', 3)
66
```
67
68
## Architecture
69
70
Parsy follows a functional programming approach with these core concepts:
71
72
- **Parser Objects**: Immutable parser instances that can be combined and transformed
73
- **Result Objects**: Containers for parse results with success/failure status and position tracking
74
- **Combinator Functions**: Pure functions that create and combine parsers
75
- **Method Chaining**: Fluent API for parser transformations and combinations
76
77
The library uses monadic composition patterns, allowing parsers to be bound together with proper error propagation and backtracking.
78
79
## Capabilities
80
81
### Core Parser Class
82
83
The fundamental Parser class provides the foundation for all parsing operations, including execution, transformation, and combination methods.
84
85
```python { .api }
86
class Parser:
87
def parse(self, stream): ...
88
def parse_partial(self, stream): ...
89
def bind(self, bind_fn): ...
90
def map(self, map_fn): ...
91
def then(self, other): ...
92
def skip(self, other): ...
93
def many(self): ...
94
def times(self, min, max=None): ...
95
def optional(self): ...
96
```
97
98
[Core Parser Class](./core-parser.md)
99
100
### Basic Parsers
101
102
Fundamental parser constructors for strings, regular expressions, character matching, and success/failure cases.
103
104
```python { .api }
105
def string(s, transform=noop): ...
106
def regex(exp, flags=0, group=0): ...
107
def test_char(func, description): ...
108
def success(val): ...
109
def fail(expected): ...
110
```
111
112
[Basic Parsers](./basic-parsers.md)
113
114
### Parser Combinators
115
116
Functions for combining multiple parsers into more complex parsing logic, including alternatives, sequences, and generator-based composition.
117
118
```python { .api }
119
def alt(*parsers): ...
120
def seq(*parsers, **kw_parsers): ...
121
def generate(fn): ...
122
```
123
124
[Parser Combinators](./combinators.md)
125
126
### Pre-defined Parsers
127
128
Ready-to-use parser constants for common parsing tasks like whitespace, digits, letters, and end-of-input detection.
129
130
```python { .api }
131
any_char: Parser
132
whitespace: Parser
133
letter: Parser
134
digit: Parser
135
decimal_digit: Parser
136
eof: Parser
137
index: Parser
138
line_info: Parser
139
```
140
141
[Pre-defined Parsers](./predefined-parsers.md)
142
143
### Utility Functions
144
145
Helper functions for common operations and transformations.
146
147
```python { .api }
148
def line_info_at(stream, index): ...
149
noop: function
150
```
151
152
[Utility Functions](./utilities.md)
153
154
## Types
155
156
```python { .api }
157
from collections import namedtuple
158
159
class ParseError(RuntimeError):
160
expected: frozenset
161
stream: str
162
index: int
163
164
def line_info(self) -> str: ...
165
166
class Result(namedtuple('Result', 'status index value furthest expected')):
167
"""
168
Result of a parsing operation.
169
170
Attributes:
171
status: bool - True if parsing succeeded, False if failed
172
index: int - Position after successful parse (or -1 for failure)
173
value: Any - Parsed value (or None for failure)
174
furthest: int - Furthest position reached during parsing
175
expected: frozenset - Set of expected values at failure point
176
"""
177
178
@staticmethod
179
def success(index, value): ...
180
@staticmethod
181
def failure(index, expected): ...
182
183
def aggregate(self, other): ...
184
185
class forward_declaration(Parser):
186
"""
187
Forward declaration for recursive parsers.
188
189
An empty parser that can be used as a forward declaration,
190
especially for parsers that need to be defined recursively.
191
You must use .become(parser) before using.
192
"""
193
194
def __init__(self): ...
195
def become(self, other): ...
196
197
# These methods raise ValueError before become() is called:
198
def parse(self, stream): ... # Raises ValueError if become() not called
199
def parse_partial(self, stream): ... # Raises ValueError if become() not called
200
```