varpulis_parser/lib.rs
1//! # VPL Parser
2//!
3//! Lexing and parsing for the VPL streaming analytics language.
4//!
5//! This crate transforms VPL source code into an Abstract Syntax Tree (AST)
6//! that can be executed by the runtime engine.
7//!
8//! ## Features
9//!
10//! - Complete VPL grammar support
11//! - Detailed error messages with line/column information
12//! - Syntax hints for common mistakes
13//! - PEG-based parsing via Pest
14//!
15//! ## Modules
16//!
17//! - [`pest_parser`]: Main parser implementation using Pest PEG grammar
18//! - [`lexer`]: Token definitions (used for syntax highlighting)
19//! - [`error`]: Parse error types with location information
20//! - [`helpers`]: Parsing utility functions
21//! - [`indent`]: Indentation handling
22//!
23//! ## Quick Start
24//!
25//! ```rust
26//! use varpulis_parser::parse;
27//!
28//! let source = r#"
29//! stream Readings = SensorReading
30//! .where(temperature > 100)
31//! .emit(alert("HighTemp", "Temperature exceeded threshold"))
32//! "#;
33//!
34//! match parse(source) {
35//! Ok(program) => {
36//! println!("Parsed {} statements", program.statements.len());
37//! }
38//! Err(e) => {
39//! eprintln!("Parse error: {}", e);
40//! }
41//! }
42//! ```
43//!
44//! ## Error Handling
45//!
46//! Parse errors include detailed location information:
47//!
48//! ```rust
49//! use varpulis_parser::{parse, ParseError};
50//!
51//! let result = parse("stream X form Y"); // Typo: "form" instead of "from"
52//! if let Err(ParseError::Located { line, column, message, hint, .. }) = result {
53//! println!("Error at {}:{}: {}", line, column, message);
54//! if let Some(h) = hint {
55//! println!("Hint: {}", h);
56//! }
57//! }
58//! ```
59//!
60//! ## Grammar
61//!
62//! The VPL grammar is defined in `varpulis.pest` and supports:
63//!
64//! - Stream declarations with filtering, selection, windowing, and aggregation
65//! - Event type definitions
66//! - SASE+ pattern declarations (sequences, Kleene closures, negation)
67//! - User-defined functions
68//! - Configuration blocks
69//! - Control flow (if/elif/else, for, while)
70//! - Expressions with operators and function calls
71//!
72//! ## See Also
73//!
74//! - [`varpulis_core`](../varpulis_core): AST types produced by the parser
75//! - [`varpulis_runtime`](../varpulis_runtime): Executing parsed programs
76
77pub mod error;
78pub mod expand;
79pub mod helpers;
80pub mod indent;
81pub mod lexer;
82pub mod optimize;
83pub mod pest_parser;
84
85pub use error::ParseError;
86pub use lexer::Token;
87pub use pest_parser::parse;