0
# TextFSM
1

2
TextFSM is a Python library that implements a template-based state machine for parsing semi-structured text output into structured data. Originally developed at Google for parsing CLI command output from networking devices, it provides a powerful template language for extracting data from human-readable text formats like log files, command outputs, and configuration files.
3

4
## Package Information
5

6
- **Package Name**: textfsm
7
- **Language**: Python
8
- **Installation**: `pip install textfsm`
9
- **Repository**: https://github.com/google/textfsm
10

11
## Core Imports
12

13
```python
14
import textfsm
15
```
16

17
For CLI table functionality:
18

19
```python
20
from textfsm import clitable
21
```
22

23
For table formatting:
24

25
```python
26
from textfsm import texttable
27
```
28

29
For terminal utilities:
30

31
```python
32
from textfsm import terminal
33
```
34

35
## Basic Usage
36

37
```python
38
import io
39
import textfsm
40

41
# Basic parsing with TextFSM
42
template_text = """
43
Value INTERFACE (\S+)
44
Value IP_ADDRESS (\d+\.\d+\.\d+\.\d+)
45
Value STATUS (up|down)
46

47
Start
48
  ^Interface ${INTERFACE} is ${STATUS}, line protocol is ${STATUS}
49
  ^  Internet address is ${IP_ADDRESS}/ -> Record
50
"""
51

52
# Parse network device output
53
input_text = """
54
Interface GigabitEthernet0/0/0 is up, line protocol is up
55
  Internet address is 192.168.1.1/24
56
Interface GigabitEthernet0/0/1 is down, line protocol is down
57
  Internet address is 10.0.0.1/30
58
"""
59

60
# Create parser and parse
61
fsm = textfsm.TextFSM(io.StringIO(template_text))
62
results = fsm.ParseText(input_text)
63

64
print(results)
65
# [['GigabitEthernet0/0/0', '192.168.1.1', 'up'], 
66
#  ['GigabitEthernet0/0/1', '10.0.0.1', 'down']]
67
```
68

69
## Architecture
70

71
TextFSM uses a finite state machine approach with four main components:
72

73
- **TextFSM**: Core parsing engine that processes templates and input text
74
- **TextFSMValue**: Defines extraction variables with regex patterns and options
75
- **TextFSMRule**: Represents state transition rules and actions
76
- **TextFSMOptions**: Provides value processing options (Filldown, Required, etc.)
77

78
The library also includes CLI automation utilities (CliTable) for mapping templates to device types, tabular data structures (TextTable), and terminal formatting utilities.
79

80
## Capabilities
81

82
### Core Parser Engine
83

84
The main TextFSM parsing functionality for processing templates and extracting structured data from text input using finite state machine rules.
85

86
```python { .api }
87
class TextFSM:
88
    def __init__(self, template, options_class=None): ...
89
    def ParseText(self, text): ...
90
    def Reset(self): ...
91

92
class TextFSMValue:
93
    def __init__(self, options_class=None): ...
94
    def Parse(self, line): ...
95

96
class TextFSMRule:
97
    def __init__(self, line, line_num=0, var_map=None, options_class=None): ...
98
```
99

100
[Core Parser](./core-parser.md)
101

102
### CLI Table Management
103

104
Automated template selection and CLI data parsing with index files that map TextFSM templates to device and command combinations.
105

106
```python { .api }
107
class CliTable:
108
    def __init__(self, index_file=None, template_dir=None): ...
109
    def ParseCmd(self, cmd_input, attributes=None): ...
110
    def AddKeys(self, keys): ...
111

112
class IndexTable:
113
    def __init__(self, file_or_data=None): ...
114
    def GetRowMatch(self, **kwargs): ...
115
```
116

117
[CLI Tables](./cli-tables.md)
118

119
### Table Data Structures
120

121
Tabular data representation with formatting capabilities for displaying parsed results as structured tables.
122

123
```python { .api }
124
class TextTable:
125
    def __init__(self, header=None): ...
126
    def Append(self, row_data): ...
127
    def CsvToTable(self, csv_data): ...
128
    def LabelValueTable(self, data): ...
129

130
class Row:
131
    def __init__(self, table, row_data=None): ...
132
```
133

134
[Text Tables](./text-tables.md)
135

136
### Terminal Utilities
137

138
ANSI text formatting, terminal control, and paging functionality for enhanced command-line output display.
139

140
```python { .api }
141
def AnsiText(text, **kwargs): ...
142
def StripAnsiText(text): ...
143
class Pager:
144
    def __init__(self, command=None): ...
145
    def Page(self, text): ...
146
```
147

148
[Terminal Utils](./terminal-utils.md)
149

150
## Command Line Interface
151

152
TextFSM provides command-line tools for parsing text files:
153

154
```bash
155
# Parse text using a template file
156
textfsm template.textfsm input.txt
157

158
# Display help
159
textfsm --help
160
```
161

162
The CLI interface is available through the main parser module:
163

164
```python { .api }
165
def main(argv=None):
166
    """
167
    Command-line interface for TextFSM parsing.
168
    
169
    Args:
170
        argv (list): Command line arguments (default: sys.argv)
171
        
172
    Returns:
173
        int: Exit code (0 for success)
174
    """
175
```
176

177
## Exception Classes
178

179
```python { .api }
180
# Core Parser Exceptions
181
class Error(Exception):
182
    """Base exception class for TextFSM."""
183

184
class UsageError(Exception):
185
    """Command line execution error."""
186

187
class TextFSMError(Error):
188
    """Error in FSM state execution."""
189

190
class TextFSMTemplateError(Error):
191
    """Errors while parsing templates."""
192

193
class FSMAction(Exception):
194
    """Base class for FSM action indicators."""
195

196
class SkipRecord(FSMAction):
197
    """Indicates current record should be skipped."""
198

199
class SkipValue(FSMAction):
200
    """Indicates current value should be skipped."""
201

202
# CLI Table Exceptions
203
class IndexTableError(Error):
204
    """Index table operation error."""
205

206
class CliTableError(Error):
207
    """General CliTable error."""
208

209
# Text Table Exceptions
210
class TableError(Error):
211
    """Error in TextTable operations."""
212

213
# Terminal Exceptions
214
class TerminalError(Error):
215
    """Base exception class for terminal module."""
216

217
class TerminalUsageError(TerminalError):
218
    """Command line format error for terminal module."""
219
```
220

221
## Module Constants
222

223
```python { .api }
224
__version__ = '2.1.0'
225
```