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
77/// Parse error types with source location information.
78pub mod error;
79/// Compile-time expansion of top-level `for` loops in VPL source.
80pub mod expand;
81/// Helper functions for parsing literal values (durations, timestamps).
82pub mod helpers;
83/// Indentation preprocessor that converts Python-style blocks to explicit markers.
84pub mod indent;
85/// Logos-based lexer producing spanned tokens for VPL source.
86pub mod lexer;
87/// AST-level constant folding optimization pass.
88pub mod optimize;
89/// Rule-based logical plan optimizer (filter pushdown, window merge, etc.).
90pub mod optimizer;
91/// Pest PEG parser that transforms VPL source into an AST.
92///
93/// The `Rule` enum inside this module is auto-generated by `pest_derive`
94/// and cannot carry doc comments.
95#[allow(missing_docs)]
96pub mod pest_parser;
97
98pub use error::{ParseError, RichParseError};
99pub use lexer::Token;
100pub use optimizer::optimize_plan;
101pub use pest_parser::parse;
varpulis_parser/lib.rs

varpulis_parser/
lib.rs
