varpulis_parser/
lib.rs

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

varpulis_parser/
lib.rs
