0
# Basic Parsers
1
2
Fundamental parser constructors that form the building blocks for more complex parsers. These functions create Parser objects for matching strings, patterns, and individual characters.
3
4
## Capabilities
5
6
### String Matching
7
8
Parse exact string literals with optional case transformation.
9
10
```python { .api }
11
def string(s, transform=noop):
12
"""
13
Parse an exact string.
14
15
Args:
16
s: String to match exactly
17
transform: Optional function to transform both input and pattern for comparison
18
19
Returns:
20
Parser: Parser that succeeds if input matches string
21
"""
22
```
23
24
### Regular Expression Parsing
25
26
Parse using regular expressions with support for groups and flags.
27
28
```python { .api }
29
def regex(exp, flags=0, group=0):
30
"""
31
Parse using a regular expression.
32
33
Args:
34
exp: Regular expression string, bytes, or compiled pattern
35
flags: Regular expression flags (when exp is string/bytes)
36
group: Group number, name, or tuple of groups to extract (default 0 for whole match)
37
38
Returns:
39
Parser: Parser that matches the regex pattern
40
"""
41
```
42
43
### Character Testing
44
45
Parse individual characters or items based on predicate functions.
46
47
```python { .api }
48
def test_char(func, description):
49
"""
50
Parse a character that satisfies a predicate function.
51
52
Args:
53
func: Function that takes a character and returns boolean
54
description: Description for error messages
55
56
Returns:
57
Parser: Parser that succeeds if predicate returns True
58
"""
59
60
def test_item(func, description):
61
"""
62
Parse an item that satisfies a predicate function.
63
64
Args:
65
func: Function that takes an item and returns boolean
66
description: Description for error messages
67
68
Returns:
69
Parser: Parser that succeeds if predicate returns True
70
"""
71
```
72
73
### Exact Item Matching
74
75
Parse specific characters or items by equality comparison.
76
77
```python { .api }
78
def match_item(item, description=None):
79
"""
80
Parse a specific item by equality.
81
82
Args:
83
item: Item to match exactly
84
description: Optional description (defaults to str(item))
85
86
Returns:
87
Parser: Parser that succeeds if input equals item
88
"""
89
```
90
91
### Multiple String Options
92
93
Parse any of multiple string options, with longest match prioritization.
94
95
```python { .api }
96
def string_from(*strings, transform=noop):
97
"""
98
Parse any of the given strings (longest first).
99
100
Args:
101
*strings: Variable number of strings to match
102
transform: Optional function to transform strings for comparison
103
104
Returns:
105
Parser: Parser that matches any of the strings
106
"""
107
108
def char_from(string):
109
"""
110
Parse any character from the given string.
111
112
Args:
113
string: String containing allowed characters
114
115
Returns:
116
Parser: Parser that matches any character in string
117
"""
118
```
119
120
### Success and Failure
121
122
Create parsers that always succeed or fail with specific values.
123
124
```python { .api }
125
def success(val):
126
"""
127
Parser that always succeeds with the given value.
128
129
Args:
130
val: Value to return on success
131
132
Returns:
133
Parser: Parser that always succeeds
134
"""
135
136
def fail(expected):
137
"""
138
Parser that always fails with the given expected message.
139
140
Args:
141
expected: Expected value description for error message
142
143
Returns:
144
Parser: Parser that always fails
145
"""
146
```
147
148
### Lookahead Parsing
149
150
Parse without consuming input (lookahead).
151
152
```python { .api }
153
def peek(parser):
154
"""
155
Parse without consuming input.
156
157
Args:
158
parser: Parser to execute for lookahead
159
160
Returns:
161
Parser: Parser that succeeds without advancing position
162
"""
163
```
164
165
### Enum Parsing
166
167
Parse enum values with automatic string conversion.
168
169
```python { .api }
170
def from_enum(enum_cls, transform=noop):
171
"""
172
Parse enum values from their string representations.
173
174
Args:
175
enum_cls: Enum class to parse values from
176
transform: Optional function to transform strings for comparison
177
178
Returns:
179
Parser: Parser that matches enum values (longest first)
180
"""
181
```
182
183
## Usage Examples
184
185
```python
186
from parsy import string, regex, test_char, string_from, char_from, peek
187
188
# Basic string parsing
189
hello = string('hello')
190
result = hello.parse('hello') # Returns 'hello'
191
192
# Case-insensitive string parsing
193
insensitive = string('Hello', transform=str.lower)
194
result = insensitive.parse('HELLO') # Returns 'Hello'
195
196
# Regular expression parsing
197
number = regex(r'\d+').map(int)
198
result = number.parse('123') # Returns 123
199
200
# Regex with groups
201
quoted = regex(r'"([^"]*)"', group=1)
202
result = quoted.parse('"hello world"') # Returns 'hello world'
203
204
# Character testing
205
vowel = test_char(lambda c: c in 'aeiou', 'vowel')
206
result = vowel.parse('a') # Returns 'a'
207
208
# Multiple string options
209
operator = string_from('+', '-', '*', '/')
210
result = operator.parse('+') # Returns '+'
211
212
# Character from set
213
digit = char_from('0123456789')
214
result = digit.parse('5') # Returns '5'
215
216
# Lookahead
217
keyword_followed_by_space = string('if') << peek(test_char(str.isspace, 'whitespace'))
218
result = keyword_followed_by_space.parse('if ') # Returns 'if'
219
220
# Enum parsing (Python 3.4+)
221
from enum import Enum
222
223
class Color(Enum):
224
RED = 'red'
225
GREEN = 'green'
226
BLUE = 'blue'
227
228
color_parser = from_enum(Color)
229
result = color_parser.parse('red') # Returns Color.RED
230
```