rico/
lib.rs

1//! Rico is a high-performance Apache Thrift IDL parser and writer library.
2//!
3//! Rico provides functionality to parse Thrift IDL files into an AST (Abstract Syntax Tree)
4//! and write the AST back to Thrift IDL format. It aims to be a complete solution for
5//! working with Thrift IDL files in Rust.
6//!
7//! # Features
8//!
9//! - Fast and efficient parsing with detailed error reporting
10//! - Complete Thrift IDL support including all standard constructs
11//! - Bidirectional conversion between Thrift IDL and AST
12//! - Preservation of comments and formatting
13//! - Detailed source location tracking for debugging
14//! - Support for annotations and custom metadata
15//! - Clean and well-documented API
16//!
17//! # Modules
18//!
19//! - [`ast`]: Abstract Syntax Tree definitions and types. Provides the core data structures
20//!   that represent Thrift IDL constructs in memory.
21//!
22//! - [`lexer`]: Tokenization of Thrift IDL input. Breaks down source text into a sequence
23//!   of tokens for the parser to process.
24//!
25//! - [`parser`]: Parsing of tokens into AST. Implements recursive descent parsing with
26//!   detailed error reporting and recovery.
27//!
28//! - [`writer`]: Converting AST back to Thrift IDL text. Handles proper formatting,
29//!   indentation, and comment preservation.
30//!
31//! # Getting Started
32//!
33//! Rico can be used in two main ways:
34//!
35//! 1. Parsing Thrift IDL into AST for analysis or transformation
36//! 2. Writing AST back to Thrift IDL text
37//!
38//! ## Parsing Example
39//!
40//! ```rust
41//! use rico::Parser;
42//!
43//! fn main() {
44//!     let input = r#"
45//!         namespace rs demo
46//!
47//!         struct User {
48//!             1: string name
49//!             2: i32 age
50//!         }
51//!     "#;
52//!
53//!     let mut parser = Parser::new(input);
54//!     match parser.parse() {
55//!         Ok(ast) => println!("{}", serde_json::to_string_pretty(&ast).unwrap()),
56//!         Err(e) => eprintln!("Error: {}", e),
57//!     }
58//! }
59//! ```
60//!
61//! ## Writing Example
62//!
63//! ```rust
64//! use rico::{Parser, Writer};
65//!
66//! fn main() {
67//!     let input = r#"
68//!         struct User {
69//!             1: string name
70//!             2: i32 age
71//!         }
72//!     "#;
73//!
74//!     // Parse the input into an AST
75//!     let mut parser = Parser::new(input);
76//!     if let Ok(ast) = parser.parse() {
77//!         // Create a writer and convert AST back to Thrift IDL
78//!         let mut writer = Writer::new();
79//!         let output = writer.write(&ast);
80//!         println!("{}", output);
81//!     }
82//! }
83//! ```
84//!
85//! # Supported Thrift Features
86//!
87//! ## Types
88//! - Base types (bool, byte, i16, i32, i64, double, string, binary)
89//! - Container types (list, set, map)
90//! - User-defined types (struct, union, exception, enum)
91//!
92//! ## Definitions
93//! - Constants with complex values (numbers, strings, lists, maps)
94//! - Typedefs for type aliases and documentation
95//! - Enums with optional values and annotations
96//! - Structs with required/optional fields and defaults
97//! - Unions for variant types with field IDs
98//! - Exceptions for error handling with inheritance
99//! - Services with inheritance and function modifiers
100//!
101//! ## Other Features
102//! - Namespaces for different target languages
103//! - Include statements for modular IDL organization
104//! - Field IDs and requiredness specifiers
105//! - Default values for fields
106//! - Oneway function modifiers
107//! - Throws clauses for error handling
108//! - Single and multi-line comments
109//! - Annotations for metadata and custom attributes
110//!
111//! # Error Handling
112//!
113//! The library provides detailed error reporting for both parsing and writing operations.
114//! Errors include:
115//! - Source location information (line and column)
116//! - Descriptive error messages
117//! - Expected vs actual token information
118//! - Context about the construct being processed
119//! - Suggestions for fixing common issues
120//!
121//! # Best Practices
122//!
123//! 1. Always check for errors when parsing
124//! 2. Use the writer to maintain consistent formatting
125//! 3. Preserve comments and annotations when modifying AST
126//! 4. Handle all error cases appropriately
127//! 5. Validate AST modifications before writing
128
129pub mod ast;
130pub mod lexer;
131pub mod parser;
132pub mod writer;
133
134pub use ast::*;
135pub use parser::Parser;
136pub use writer::Writer;
rico/lib.rs

rico/
lib.rs
