Crate textfsm_rust 

TextFSM

A template-based state machine for parsing semi-formatted text.

This is a Rust port of Google’s TextFSM, commonly used for parsing CLI output from network devices.

Quick Start

use textfsm_rust::Template;

let template_str = r#"
Value Name (\S+)
Value Age (\d+)

Start
  ^Name: ${Name}, Age: ${Age} -> Record
"#;

let template = Template::parse_str(template_str).unwrap();
let mut parser = template.parser();

let input = "Name: Alice, Age: 30\nName: Bob, Age: 25\n";
let results = parser.parse_text(input).unwrap();

assert_eq!(results.len(), 2);

Template Syntax

Templates consist of two sections:

1. Value definitions at the top:

   Value [Options] Name (regex)

   Options: Required, Filldown, Fillup, Key, List

2. State definitions below (separated by blank line):

   StateName
     ^pattern -> Action NewState

   Actions: Next, Continue, Error, Record, Clear, Clearall, NoRecord

Compile-Time Template Validation

Use the validation macros to catch template errors at compile time:

use textfsm_rust::{validate_template, validate_templates};

// Validate a single template file
validate_template!("templates/cisco_show_version.textfsm");

// Validate all .textfsm files in a directory
validate_templates!("templates/");

Serde Integration

Enable the serde feature to deserialize parsed results directly into typed structs:

[dependencies]
textfsm-rust = { version = "0.1", features = ["serde"] }

use textfsm_rust::{Deserialize, Template};

#[derive(Deserialize, Debug)]
struct Interface {
    interface: String,
    status: String,
}

let template = Template::parse_str(TEMPLATE)?;
let mut parser = template.parser();

// Deserialize directly into typed structs
let interfaces: Vec<Interface> = parser.parse_text_into(input)?;

Field names are matched case-insensitively against template value names.

Example Template

Value Required Interface (\S+)
Value Filldown Status (up|down)
Value IPAddress (\d+\.\d+\.\d+\.\d+)

Start
  ^Interface: ${Interface} -> Continue
  ^  Status: ${Status}
  ^  IP: ${IPAddress} -> Record

Modules

clitable

CliTable - Index-based template selection for parsing CLI output.

Macros

validate_index

Validates an index file and all templates it references at compile time.

validate_template

Validates a single TextFSM template file at compile time.

validate_templates

Validates all TextFSM template files in a directory at compile time.

Structs

CliTable

Index-based template selection and parsing for CLI output.

Index

Parsed index file.

IndexEntry

A single row in the index file.

Parser

Parser for processing text with a compiled template.

Row

A single row in a TextTable.

Rule

A rule within a state.

State

A state containing rules.

Template

Compiled template - immutable, can be shared across threads.

TextTable

Table of parsed CLI output with named columns.

ValueDef

A Value definition from the template header.

ValueState

Runtime state for a single value.

Enums

CliTableError

Errors that occur during CliTable operations.

LineOp

Line operators control input line processing.

ListItem

A single item in a List value.

ParseError

Errors that occur during text parsing (runtime).

RecordOp

Record operators control output record handling.

TemplateError

Errors that occur when parsing a template file.

TextFsmError

Combined error type for public API.

Transition

State transition target.

Value

Runtime value during parsing.

ValueOption

Available options for Value definitions.

Type Aliases

Result

Result type alias using TextFsmError.

ValueOptions

Set of options for a value.