textfsm-rs

A robust, performant, and safe Rust implementation of TextFSM. This library is designed to parse semi-structured text—specifically output from networking device CLI commands—into structured programmatic data (JSON, YAML, or Rust HashMaps).

Why textfsm-rs?

• Blazing Fast: Optimized for high-throughput parsing with minimal memory allocations.
• Safe by Design: Written in 100% safe Rust, replacing Python's runtime errors with compile-time checks and graceful Result handling.
• NTC-Templates Compatible: Designed to work out-of-the-box with the massive library of templates from ntc-templates.
• Modern Tooling: Seamless integration with serde for serialization and pest for reliable template parsing.

Features

• Full TextFSM Specification: Support for Value definitions (Filldown, Key, Required, List, Fillup), States, Rules, and Transitions.
• Advanced Regex: Uses fancy-regex to support Python-style features like lookahead and lookbehind.
• Automatic Template Selection: Built-in CliTable logic to automatically select the right template based on device platform and command.
• Zero-Panic: Library code avoids unwrap() and panic!, ensuring your automation tools stay up.

Installation

Add this to your Cargo.toml:

[dependencies]
textfsm-rs = "0.3.5" # Check crates.io for the latest version

Quick Start

use textfsm_rs::{TextFSM, DataRecordConversion};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Initialize the FSM with a template
    let mut fsm = TextFSM::from_file("templates/cisco_ios_show_version.textfsm")?;

    // 2. Parse your CLI output
    let records = fsm.parse_file("data/show_version.txt", Some(DataRecordConversion::LowercaseKeys))?;
    
    // 3. Use the structured data
    for record in records {
        if let Some(version) = record.fields.get("Version") {
            println!("Device Version: {}", version);
        }
    }

    Ok(())
}

CLI Usage

You can use textfsm-rs as a standalone command-line tool.

Installation

cargo install textfsm-rs

Commands

Parse a single file:

textfsm parse --template templates/cisco_ios_show_version.textfsm --input data/show_version.txt --format json

Auto-detect template (using ntc-templates index):

textfsm auto --index ntc_templates/templates/index --platform cisco_ios --command "show version" --input data/show_version.txt

Advanced: Automated Template Mapping

Using the ntc-templates index style:

use textfsm_rs::CliTable;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let index = CliTable::from_file("ntc_templates/templates/index")?;
    
    // Automatically find the template for a Cisco command
    if let Some((dir, row)) = index.get_template_for_command("cisco_ios", "sh version") {
        println!("Match found! Template: {}/{}", dir, row.templates[0]);
    }
    
    Ok(())
}

Documentation

• API Documentation - Official crate documentation on docs.rs.
• Usage Guide - Detailed examples and API usage.
• Creating Templates - Syntax guide for writing .textfsm files.
• Advanced Examples - Patterns for complex parsing scenarios.
• Common Capture Groups - Reference for standard variable names.
• Architecture - Deep dive into internal implementation and optimizations.

Contributing

Contributions are welcome! Please ensure all tests pass:

cargo test

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.