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