forgedb_parser/
lib.rs

1//! ForgeDB Parser
2//!
3//! Parser and lexer for ForgeDB's schema definition language.
4//!
5//! # Overview
6//!
7//! This crate provides parsing capabilities for ForgeDB's schema language, converting
8//! schema files (.fdb) into an Abstract Syntax Tree (AST) that can be used for code
9//! generation, validation, and other tooling.
10//!
11//! # Architecture
12//!
13//! The parser is implemented as a traditional two-stage compiler frontend:
14//!
15//! 1. **Lexer** - Tokenizes input source code into a stream of tokens
16//! 2. **Parser** - Converts token stream into an Abstract Syntax Tree (AST)
17//!
18//! ## Supported Constructs
19//!
20//! - **Models** - Database table definitions with fields and constraints
21//! - **Structs** - Composite data types
22//! - **Fields** - Typed fields with constraints
23//! - **Constraints** - Validation rules (@unique, @email, @min, etc.)
24//! - **Relations** - Model relationships (hasMany, belongsTo)
25//! - **Components** - Reusable field groups with protocols
26//!
27//! # Examples
28//!
29//! ## Parsing a Schema File
30//!
31//! ```rust
32//! use forgedb_parser::Parser;
33//!
34//! let source = r#"
35//!     User {
36//!         id: +uuid
37//!         email: &string @email
38//!         age: i32 @min(18)
39//!     }
40//! "#;
41//!
42//! // Parser::new returns Result<Parser, String>
43//! let mut parser = Parser::new(source).expect("parse error");
44//! match parser.parse() {
45//!     Ok(schema) => {
46//!         println!("Parsed {} models", schema.models.len());
47//!         for model in &schema.models {
48//!             println!("Model: {}", model.name);
49//!         }
50//!     }
51//!     Err(error) => {
52//!         eprintln!("Parse error: {}", error);
53//!     }
54//! }
55//! ```
56//!
57//! ## Working with the AST
58//!
59//! ```rust
60//! use forgedb_parser::{Parser, Model, FieldType};
61//!
62//! let source = r#"
63//!     Post {
64//!         id: +uuid
65//!         title: string
66//!         content: string
67//!     }
68//! "#;
69//!
70//! let mut parser = Parser::new(source).expect("parse error");
71//! let schema = parser.parse().unwrap();
72//!
73//! for model in &schema.models {
74//!     println!("Model: {}", model.name);
75//!     for field in &model.fields {
76//!         println!("  Field: {} : {:?}", field.name, field.field_type);
77//!     }
78//! }
79//! ```
80//!
81//! ## Tokenization
82//!
83//! ```rust
84//! use forgedb_parser::{Lexer, Token};
85//!
86//! let source = "User { id: +uuid }";
87//! let mut lexer = Lexer::new(source);
88//!
89//! // Lexer::tokenize() collects all tokens into a Vec
90//! let tokens: Vec<Token> = lexer.tokenize().expect("lex error");
91//! println!("Tokenized into {} tokens", tokens.len());
92//! ```
93//!
94//! # Public API
95//!
96//! ## Core Types
97//!
98//! - [`Parser`] - Main parser interface
99//! - [`Lexer`] - Tokenizer for schema source code
100//! - [`Schema`] - Root AST node containing all definitions
101//!
102//! ## AST Nodes
103//!
104//! - [`Model`] - Database table definition
105//! - [`Struct`] - Composite data type
106//! - [`Field`] - Field definition with type and constraints
107//! - [`FieldType`] - Field data type (i32, string, uuid, etc.)
108//! - [`Constraint`] - Validation constraint (@unique, @email, etc.)
109//! - [`RelationType`] - Relationship type (hasMany, belongsTo)
110//!
111//! ## Component System
112//!
113//! - [`ComponentProtocol`] - Interface definition for components
114//! - [`ComponentReference`] - Reference to a component in a model
115//!
116//! # Schema Language Features
117//!
118//! ## Field Types
119//!
120//! - **Integers**: `i32`, `i64`
121//! - **Floating Point**: `f64`
122//! - **Boolean**: `bool`
123//! - **String**: `string`
124//! - **UUID**: `uuid`
125//! - **Timestamp**: `timestamp`
126//!
127//! ## Field Modifiers
128//!
129//! - `+field` - Primary key
130//! - `field?` - Optional (nullable)
131//!
132//! ## Constraints
133//!
134//! - `@unique` - Unique constraint
135//! - `@email` - Email validation
136//! - `@min(value)` - Minimum value
137//! - `@max(value)` - Maximum value
138//! - `@length(min, max)` - String length constraint
139//!
140//! ## Relations
141//!
142//! - `hasMany(Model)` - One-to-many relationship
143//! - `belongsTo(Model)` - Many-to-one relationship
144//! - `hasOne(Model)` - One-to-one relationship
145//!
146//! # Error Handling
147//!
148//! The parser returns detailed error messages with line and column information:
149//!
150//! ```text
151//! Parse error at line 5, column 12: Expected '}', found 'field'
152//! ```
153//!
154//! # Related Crates
155//!
156//! - [`forgedb-validation`](../forgedb_validation) - Schema validation
157//! - [`forgedb-types`](../forgedb_types) - Runtime type definitions
158//! - [`forgedb`](../../) - Main ForgeDB CLI using this parser
159//!
160//! # See Also
161//!
162//! - [ForgeDB Schema Language Guide](../../docs/schema-language.md)
163//! - [SPRINT1_SUMMARY.md](../../archive/sprint-summaries/SPRINT1_SUMMARY.md) - Parser implementation
164
165pub mod ast;
166pub mod lexer;
167pub mod parser;
168
169// Re-export main types for convenience
170pub use ast::{
171    ComponentProtocol, ComponentReference, Constraint, ConstraintParam, Field, FieldType, Model,
172    RelationType, Schema, Struct,
173};
174pub use lexer::{Lexer, Token};
175pub use parser::Parser;
forgedb_parser/lib.rs

forgedb_parser/
lib.rs
