textfsm_rust/lib.rs
1//! # TextFSM
2//!
3//! A template-based state machine for parsing semi-formatted text.
4//!
5//! This is a Rust port of [Google's TextFSM](https://github.com/google/textfsm),
6//! commonly used for parsing CLI output from network devices.
7//!
8//! ## Quick Start
9//!
10//! ```rust
11//! use textfsm_rust::Template;
12//!
13//! let template_str = r#"Value Name (\S+)
14//! Value Age (\d+)
15//!
16//! Start
17//! ^Name: ${Name}, Age: ${Age} -> Record
18//! "#;
19//!
20//! let template = Template::parse_str(template_str).unwrap();
21//! let mut parser = template.parser();
22//!
23//! let input = "Name: Alice, Age: 30\nName: Bob, Age: 25\n";
24//! let results = parser.parse_text(input).unwrap();
25//!
26//! assert_eq!(results.len(), 2);
27//! ```
28//!
29//! ## Template Syntax
30//!
31//! Templates consist of two sections:
32//!
33//! 1. **Value definitions** at the top:
34//! ```text
35//! Value [Options] Name (regex)
36//! ```
37//! Options: `Required`, `Filldown`, `Fillup`, `Key`, `List`
38//!
39//! 2. **State definitions** below (separated by blank line):
40//! ```text
41//! StateName
42//! ^pattern -> Action NewState
43//! ```
44//! Actions: `Next`, `Continue`, `Error`, `Record`, `Clear`, `Clearall`, `NoRecord`
45//!
46//! ## Compile-Time Template Validation
47//!
48//! Use the validation macros to catch template errors at compile time:
49//!
50//! ```rust,ignore
51//! use textfsm_rust::{validate_template, validate_templates};
52//!
53//! // Validate a single template file
54//! validate_template!("templates/cisco_show_version.textfsm");
55//!
56//! // Validate all .textfsm files in a directory
57//! validate_templates!("templates/");
58//! ```
59//!
60//! ## Serde Integration
61//!
62//! Enable the `serde` feature to deserialize parsed results directly into typed structs:
63//!
64//! ```toml
65//! [dependencies]
66//! textfsm-rust = { version = "0.1", features = ["serde"] }
67//! ```
68//!
69//! ```rust,ignore
70//! use textfsm_rust::{Deserialize, Template};
71//!
72//! #[derive(Deserialize, Debug)]
73//! struct Interface {
74//! interface: String,
75//! status: String,
76//! }
77//!
78//! let template = Template::parse_str(TEMPLATE)?;
79//! let mut parser = template.parser();
80//!
81//! // Deserialize directly into typed structs
82//! let interfaces: Vec<Interface> = parser.parse_text_into(input)?;
83//! ```
84//!
85//! Field names are matched case-insensitively against template value names.
86//!
87//! ## Example Template
88//!
89//! ```text
90//! Value Required Interface (\S+)
91//! Value Filldown Status (up|down)
92//! Value IPAddress (\d+\.\d+\.\d+\.\d+)
93//!
94//! Start
95//! ^Interface: ${Interface} -> Continue
96//! ^ Status: ${Status}
97//! ^ IP: ${IPAddress} -> Record
98//! ```
99
100// Re-export everything from textfsm-core
101pub use textfsm_core::*;
102
103// Re-export macros from textfsm-macros
104pub use textfsm_macros::{validate_index, validate_template, validate_templates};
105
106// Re-export serde's Deserialize trait when serde feature is enabled
107#[cfg(feature = "serde")]
108pub use serde::Deserialize;