0
# Core Parser Engine
1
2
The TextFSM core parser provides the fundamental template-based state machine functionality for extracting structured data from semi-formatted text. This is the primary interface for creating parsers and processing text input.
3
4
## Core Imports
5
6
```python
7
import textfsm
8
from textfsm.parser import TextFSM, TextFSMValue, TextFSMRule
9
from textfsm.parser import TextFSMError, TextFSMTemplateError
10
```
11
12
## Capabilities
13
14
### TextFSM Parser
15
16
The main parser class that processes TextFSM templates and applies them to text input to extract structured records.
17
18
```python { .api }
19
class TextFSM:
20
def __init__(self, template, options_class=None):
21
"""
22
Initialize TextFSM parser with template.
23
24
Args:
25
template: File-like object containing TextFSM template
26
options_class: Custom options class (default: TextFSMOptions)
27
"""
28
29
def ParseText(self, text, eof=True):
30
"""
31
Parse input text using the template.
32
33
Args:
34
text (str): Input text to parse
35
eof (bool): Whether to process end-of-file transitions (default: True)
36
37
Returns:
38
list: List of records, each record is a list of extracted values
39
"""
40
41
def ParseTextToDicts(self, text, eof=True):
42
"""
43
Parse input text using the template, returning dictionary records.
44
45
Args:
46
text (str): Input text to parse
47
eof (bool): Whether to process end-of-file transitions (default: True)
48
49
Returns:
50
list: List of records, each record is a dict with column names as keys
51
"""
52
53
def Reset(self):
54
"""Reset parser state to initial conditions."""
55
56
def GetValuesByAttrib(self, attribute):
57
"""
58
Get values that have a specific attribute.
59
60
Args:
61
attribute (str): Attribute name to search for
62
63
Returns:
64
list: List of value names with the attribute
65
"""
66
67
@property
68
def header(self):
69
"""List of column headers from Value definitions."""
70
71
@property
72
def values(self):
73
"""List of TextFSMValue objects."""
74
75
@property
76
def states(self):
77
"""Dict of FSM states and their rules."""
78
79
@property
80
def value_map(self):
81
"""Dict mapping value names to TextFSMValue objects."""
82
83
@property
84
def state_list(self):
85
"""List of state names in order."""
86
```
87
88
### TextFSM Value Definitions
89
90
Represents template value definitions with regex patterns and processing options.
91
92
```python { .api }
93
class TextFSMValue:
94
def __init__(self, fsm=None, max_name_len=48, options_class=None):
95
"""
96
Initialize value definition.
97
98
Args:
99
fsm: Parent TextFSM object
100
max_name_len (int): Maximum allowed name length (default: 48)
101
options_class: Custom options class for value processing
102
"""
103
104
def Parse(self, value):
105
"""
106
Parse a Value line from template.
107
108
Args:
109
value (str): Value definition line from template
110
"""
111
112
def AssignVar(self, value):
113
"""
114
Assign a value to this variable.
115
116
Args:
117
value: Value to assign
118
"""
119
120
def ClearVar(self):
121
"""
122
Clear this variable's value.
123
"""
124
125
def ClearAllVar(self):
126
"""
127
Clear this variable's value (part of ClearAll operation).
128
"""
129
130
def Header(self):
131
"""
132
Get header name for this value.
133
134
Returns:
135
str: Header name string
136
"""
137
138
def OnCreateOptions(self):
139
"""Called after all options have been parsed."""
140
141
def OnClearVar(self):
142
"""Called when value is cleared."""
143
144
def OnClearAllVar(self):
145
"""Called when value is cleared with ClearAll."""
146
147
def OnSaveRecord(self):
148
"""Called when record is saved."""
149
150
def OptionNames(self):
151
"""
152
Get list of option names for this value.
153
154
Returns:
155
list: List of option name strings
156
"""
157
158
@property
159
def name(self):
160
"""Value name string."""
161
162
@property
163
def regex(self):
164
"""Original regex pattern."""
165
166
@property
167
def template(self):
168
"""Compiled regex template with named groups."""
169
170
@property
171
def value(self):
172
"""Current extracted value."""
173
174
@property
175
def options(self):
176
"""List of option objects."""
177
178
@property
179
def compiled_regex(self):
180
"""Compiled regex object for matching."""
181
182
@property
183
def max_name_len(self):
184
"""Maximum allowed name length."""
185
```
186
187
### TextFSM Rule Processing
188
189
Represents parsing rules that define state transitions and actions within the FSM.
190
191
```python { .api }
192
class TextFSMRule:
193
def __init__(self, line, line_num=0, var_map=None, options_class=None):
194
"""
195
Initialize parsing rule.
196
197
Args:
198
line (str): Rule line from template
199
line_num (int): Line number in template (default: 0)
200
var_map (dict): Variable name to regex mapping
201
options_class: Options class for processing
202
"""
203
204
205
@property
206
def match(self):
207
"""Regex match pattern for this rule."""
208
209
@property
210
def line_op(self):
211
"""Line operation (Continue, Next, Error, etc.)."""
212
213
@property
214
def new_state(self):
215
"""Next state to transition to."""
216
217
@property
218
def record_op(self):
219
"""Record operation (NoRecord, Record, Clear, etc.)."""
220
221
@property
222
def regex(self):
223
"""Original regex pattern string."""
224
225
@property
226
def regex_obj(self):
227
"""Compiled regex object."""
228
229
@property
230
def line_num(self):
231
"""Line number in template."""
232
```
233
234
### Value Options System
235
236
Container and base classes for TextFSM value processing options like Filldown and Required.
237
238
```python { .api }
239
class TextFSMOptions:
240
"""Container for all valid TextFSMValue options."""
241
242
@classmethod
243
def ValidOptions(cls):
244
"""
245
Get list of valid option names.
246
247
Returns:
248
list: List of valid option name strings
249
"""
250
251
@classmethod
252
def GetOption(cls, name):
253
"""
254
Get option class by name.
255
256
Args:
257
name (str): Option name
258
259
Returns:
260
class: Option class
261
"""
262
263
class OptionBase:
264
def __init__(self, value):
265
"""
266
Base class for value options.
267
268
Args:
269
value: Parent TextFSMValue instance
270
"""
271
272
def OnCreateOptions(self):
273
"""Called after all options have been parsed."""
274
275
def OnClearVar(self):
276
"""Called when value has been cleared."""
277
278
def OnClearAllVar(self):
279
"""Called when value has been cleared with ClearAll."""
280
281
def OnAssignVar(self, value):
282
"""
283
Called when value is assigned.
284
285
Args:
286
value: Assigned value
287
"""
288
289
def OnGetValue(self):
290
"""
291
Called when value is retrieved.
292
293
Returns:
294
Value to return
295
"""
296
297
def OnSaveRecord(self):
298
"""Called when record is saved."""
299
300
@property
301
def name(self):
302
"""Option name without 'option' prefix."""
303
304
class optionFilldown(OptionBase):
305
"""Maintains value across records until explicitly changed."""
306
307
class optionFillup(OptionBase):
308
"""Fills empty values from subsequent records."""
309
310
class optionRequired(OptionBase):
311
"""Requires value to be set before record can be saved."""
312
313
class optionList(OptionBase):
314
"""Collects multiple values into a list."""
315
316
class optionKey(OptionBase):
317
"""Marks value as a key field for record identification."""
318
```
319
320
### Helper Classes
321
322
```python { .api }
323
class CopyableRegexObject:
324
def __init__(self, pattern):
325
"""
326
Wrapper for regex objects to enable deep copying.
327
328
Args:
329
pattern: Regular expression pattern or compiled regex
330
"""
331
332
def search(self, *args, **kwargs):
333
"""Search for pattern in text."""
334
335
def match(self, *args, **kwargs):
336
"""Match pattern at start of text."""
337
338
def sub(self, *args, **kwargs):
339
"""Substitute pattern matches in text."""
340
341
def __copy__(self):
342
"""Create shallow copy."""
343
344
def __deepcopy__(self, unused_memo):
345
"""Create deep copy."""
346
```
347
348
### Module Functions
349
350
```python { .api }
351
def main(argv=None):
352
"""
353
Command-line interface for TextFSM parsing.
354
355
Args:
356
argv (list): Command line arguments (default: sys.argv)
357
358
Returns:
359
int: Exit code (0 for success)
360
"""
361
```
362
363
### Core Exceptions
364
365
```python { .api }
366
class Error(Exception):
367
"""Base exception class for TextFSM."""
368
369
class UsageError(Exception):
370
"""Command line execution error."""
371
372
class TextFSMTemplateError(Error):
373
"""Error in template parsing or validation."""
374
375
class FSMAction(Exception):
376
"""Base class for FSM action indicators."""
377
378
class SkipRecord(FSMAction):
379
"""Indicates current record should be skipped."""
380
381
class SkipValue(FSMAction):
382
"""Indicates current value should be skipped."""
383
```
384
385
## Usage Examples
386
387
### Basic Template Processing
388
389
```python
390
import io
391
import textfsm
392
393
# Define template
394
template = """
395
Value HOSTNAME (\S+)
396
Value UPTIME (.+)
397
Value VERSION (\S+)
398
399
Start
400
^${HOSTNAME} uptime is ${UPTIME}
401
^Software version ${VERSION} -> Record
402
"""
403
404
# Parse text
405
text = """
406
router1 uptime is 5 days, 14 hours, 23 minutes
407
Software version 15.1(4)M5
408
router2 uptime is 2 days, 8 hours, 15 minutes
409
Software version 15.2(2)T1
410
"""
411
412
fsm = textfsm.TextFSM(io.StringIO(template))
413
results = fsm.ParseText(text)
414
# [['router1', '5 days, 14 hours, 23 minutes', '15.1(4)M5'],
415
# ['router2', '2 days, 8 hours, 15 minutes', '15.2(2)T1']]
416
```
417
418
### Using Value Options
419
420
```python
421
template_with_options = """
422
Value Required INTERFACE (\S+)
423
Value Filldown DEVICE (\S+)
424
Value List IP_ADDR (\d+\.\d+\.\d+\.\d+)
425
426
Start
427
^Device: ${DEVICE}
428
^Interface ${INTERFACE}
429
^ IP: ${IP_ADDR} -> Record
430
"""
431
432
text = """
433
Device: switch1
434
Interface GigE0/1
435
IP: 192.168.1.1
436
IP: 10.0.0.1
437
Interface GigE0/2
438
IP: 172.16.1.1
439
"""
440
441
fsm = textfsm.TextFSM(io.StringIO(template_with_options))
442
results = fsm.ParseText(text)
443
# [['GigE0/1', 'switch1', ['192.168.1.1', '10.0.0.1']],
444
# ['GigE0/2', 'switch1', ['172.16.1.1']]]
445
```