0
# Expression Enhancement
1

2
Modifiers and enhancers that control repetition, optionality, lookahead/lookbehind, and token transformation. These classes wrap other parser elements to create sophisticated parsing behavior while maintaining the compositional design of pyparsing.
3

4
**Required imports for type annotations:**
5

6
```python
7
from typing import Union, Optional
8
from pyparsing import ParserElement, ParseElementEnhance, TokenConverter
9
```
10

11
## Capabilities
12

13
### Repetition and Optionality
14

15
Elements that control how many times an expression should match.
16

17
```python { .api }
18
class Optional(ParseElementEnhance):
19
    """Make an expression optional."""
20
    
21
    def __init__(self, expr: ParserElement, default: str = ""): ...
22

23
# Alias for Optional
24
Opt = Optional
25
```
26

27
```python { .api }
28
class ZeroOrMore(ParseElementEnhance):
29
    """Match zero or more repetitions of an expression."""
30
    
31
    def __init__(self, 
32
                 expr: Union[str, ParserElement], 
33
                 stop_on: Optional[Union[ParserElement, str]] = None,
34
                 *,
35
                 stopOn: Optional[Union[ParserElement, str]] = None): ...
36

37
class OneOrMore(ParseElementEnhance):
38
    """Match one or more repetitions of an expression."""
39
    
40
    def __init__(self, 
41
                 expr: Union[str, ParserElement], 
42
                 stop_on: Optional[Union[ParserElement, str]] = None,
43
                 *,
44
                 stopOn: Optional[Union[ParserElement, str]] = None): ...
45
```
46

47
**Usage examples:**
48
```python
49
# Optional element with default
50
name = Optional(Word(alphas), "Anonymous")
51

52
# Repetition patterns
53
numbers = OneOrMore(Word(nums))
54
optional_numbers = ZeroOrMore(Word(nums))
55

56
# Stop repetition on specific pattern
57
items = ZeroOrMore(Word(alphas), stopOn=Literal(";"))
58
```
59

60
### Lookahead and Lookbehind
61

62
Assertion elements that check for patterns without consuming input.
63

64
```python { .api }
65
class FollowedBy(ParseElementEnhance):
66
    """Positive lookahead assertion."""
67
    
68
    def __init__(self, expr: ParserElement): ...
69

70
class PrecededBy(ParseElementEnhance):
71
    """Positive lookbehind assertion."""
72
    
73
    def __init__(self, expr: ParserElement, retreat: int = None): ...
74

75
class NotAny(ParseElementEnhance):
76
    """Negative lookahead assertion."""
77
    
78
    def __init__(self, expr: ParserElement): ...
79
```
80

81
**Usage examples:**
82
```python
83
# Match word only if followed by punctuation
84
word_before_punct = Word(alphas) + FollowedBy(oneOf(". , ; !"))
85

86
# Match word only if preceded by whitespace
87
word_after_space = PrecededBy(White()) + Word(alphas)
88

89
# Match word only if not followed by equals sign
90
var_not_assignment = Word(alphas) + NotAny("=")
91
```
92

93
### Token Conversion
94

95
Classes that modify or transform parsed tokens.
96

97
```python { .api }
98
class TokenConverter(ParseElementEnhance):
99
    """Base class for token conversion classes."""
100
    
101
    def __init__(self, expr: ParserElement, savelist: bool = False): ...
102

103
class Combine(TokenConverter):
104
    """Combine parsed tokens into a single string."""
105
    
106
    def __init__(self, expr: ParserElement, joinString: str = "", adjacent: bool = True): ...
107

108
class Group(TokenConverter):
109
    """Group results into a list."""
110
    
111
    def __init__(self, expr: ParserElement): ...
112

113
class Dict(TokenConverter):
114
    """Convert results to dictionary."""
115
    
116
    def __init__(self, expr: ParserElement): ...
117

118
class Suppress(TokenConverter):
119
    """Suppress tokens from results."""
120
    
121
    def __init__(self, expr: ParserElement): ...
122
```
123

124
**Usage examples:**
125
```python
126
# Combine tokens into single string
127
ip_addr = Combine(Word(nums) + "." + Word(nums) + "." + Word(nums) + "." + Word(nums))
128

129
# Group related tokens
130
point = Group("(" + Word(nums) + "," + Word(nums) + ")")
131

132
# Create dictionary from key-value pairs
133
attr = Dict(Word(alphas) + "=" + QuotedString('"'))
134

135
# Suppress punctuation from results
136
expr = Word(alphas) + Suppress(",") + Word(alphas)
137
```
138

139
### Location and Context
140

141
Elements that add position information or context to results.
142

143
```python { .api }
144
class Located(TokenConverter):
145
    """Add location information to results."""
146
    
147
    def __init__(self, expr: ParserElement): ...
148

149
class Tag(TokenConverter):
150
    """Tag results with metadata."""
151
    
152
    def __init__(self, expr: ParserElement, tag_name: str): ...
153

154
class IndentedBlock(ParseElementEnhance):
155
    """Parse indented blocks of text."""
156
    
157
    def __init__(self, blockStatementExpr: ParserElement, indentStack: list = None, indent: bool = True): ...
158
```
159

160
**Usage examples:**
161
```python
162
# Add line/column info to results
163
located_word = Located(Word(alphas))
164

165
# Tag results for identification
166
tagged_expr = Tag(Word(nums), "number")
167

168
# Parse Python-style indented blocks
169
stmt = Word(alphas) + ":"
170
block = IndentedBlock(OneOrMore(Word(alphas)))
171
python_block = stmt + block
172
```
173

174
### Pattern Matching
175

176
Advanced pattern matching capabilities.
177

178
```python { .api }
179
class CloseMatch(Token):
180
    """Match strings within specified edit distance."""
181
    
182
    def __init__(self, match_string: str, maxMismatches: int = 1): ...
183
```
184

185
**Usage example:**
186
```python
187
# Match strings with up to 2 character differences
188
fuzzy_match = CloseMatch("hello", maxMismatches=2)
189
# Will match "hello", "helo", "helloo", "hallo", etc.
190
```
191

192
### Parse Actions and Conditions
193

194
Elements that enable conditional parsing and action execution.
195

196
```python { .api }
197
class OnlyOnce(object):
198
    """Wrapper to ensure parse action runs only once."""
199
    
200
    def __init__(self, methodCall: callable): ...
201
    
202
    def __call__(self, s: str, loc: int, tokens: ParseResults): ...
203
```
204

205
**Usage example:**
206
```python
207
# Ensure initialization happens only once
208
init_action = OnlyOnce(lambda: print("Initializing parser"))
209
parser = Word(alphas).set_parse_action(init_action)
210
```
211

212
### Specialized Enhancement
213

214
Specialized enhancement classes for specific parsing scenarios.
215

216
```python { .api }
217
class ParseElementEnhance(ParserElement):
218
    """Base class for elements that enhance other parsing elements."""
219
    
220
    def __init__(self, expr: ParserElement, savelist: bool = False): ...
221
    
222
    def ignore(self, other: ParserElement) -> ParserElement:
223
        """Ignore specified expression while parsing."""
224
    
225
    def suppress_first(self) -> ParserElement:
226
        """Suppress first matching element from results."""
227
    
228
    def suppress_last(self) -> ParserElement:
229
        """Suppress last matching element from results."""
230
```
231

232
### Utility Functions for Enhancement
233

234
Functions that create commonly used enhancement patterns.
235

236
```python { .api }
237
def ungroup(expr: ParserElement) -> ParserElement:
238
    """Remove grouping from expression results."""
239

240
def original_text_for(expr: ParserElement, asString: bool = True) -> ParserElement:
241
    """Return original text instead of parsed tokens."""
242
```
243

244
**Usage examples:**
245
```python
246
# Remove grouping from complex expression
247
grouped_items = Group(delimited_list(Word(alphas)))
248
ungrouped_items = ungroup(grouped_items)
249

250
# Get original text instead of parsed tokens
251
number_text = original_text_for(Word(nums) + Optional("." + Word(nums)))
252
```