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

Macros

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

Parser

Parser for processing text with a compiled template.

Rule

A rule within a state.

State

A state containing rules.

Template

Compiled template - immutable, can be shared across threads.

ValueDef

A Value definition from the template header.

ValueState

Runtime state for a single value.

Enums

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.