rusty_promql_parser/
lib.rs

1//! # Rusty PromQL Parser
2//!
3//! A Rust parser for the Prometheus Query Language (PromQL) using the
4//! [nom](https://github.com/rust-bakery/nom) parser combinator library.
5//!
6//! This crate provides a complete parser for PromQL expressions, producing an
7//! Abstract Syntax Tree (AST) that can be used for analysis, transformation,
8//! or evaluation.
9//!
10//! ## Quick Start
11//!
12//! The main entry point is the [`expr()`] function, which parses a PromQL expression
13//! and returns the remaining input along with the parsed AST:
14//!
15//! ```rust
16//! use rusty_promql_parser::expr;
17//!
18//! let input = r#"http_requests_total{job="api"}"#;
19//! let (rest, ast) = expr(input).expect("failed to parse");
20//! assert!(rest.is_empty());
21//! println!("{:#?}", ast);
22//! ```
23//!
24//! ## Examples
25//!
26//! ### Parsing a metric with label filtering
27//!
28//! ```rust
29//! use rusty_promql_parser::expr;
30//!
31//! let input = r#"go_gc_duration_seconds{instance="localhost:9090", job="alertmanager"}"#;
32//! let (rest, ast) = expr(input).expect("failed to parse");
33//! assert!(rest.is_empty());
34//! ```
35//!
36//! ### Parsing aggregation operators
37//!
38//! ```rust
39//! use rusty_promql_parser::expr;
40//!
41//! let input = r#"sum by (app, proc) (
42//!   instance_memory_limit_bytes - instance_memory_usage_bytes
43//! ) / 1024 / 1024"#;
44//! let (rest, ast) = expr(input).expect("failed to parse");
45//! assert!(rest.is_empty());
46//! ```
47//!
48//! ### Parsing rate queries
49//!
50//! ```rust
51//! use rusty_promql_parser::expr;
52//!
53//! let input = "rate(http_requests_total[5m])";
54//! let (rest, ast) = expr(input).expect("failed to parse");
55//! assert!(rest.is_empty());
56//! ```
57//!
58//! ## AST Types
59//!
60//! The parser produces an [`Expr`] enum which can be one of:
61//!
62//! - [`Expr::Number`] - Numeric literals (`42`, `3.14`, `Inf`, `NaN`)
63//! - [`Expr::String`] - String literals (`"hello"`, `'world'`)
64//! - [`Expr::VectorSelector`] - Instant vector selectors (`metric{label="value"}`)
65//! - [`Expr::MatrixSelector`] - Range vector selectors (`metric[5m]`)
66//! - [`Expr::Call`] - Function calls (`rate(...)`, `histogram_quantile(...)`)
67//! - [`Expr::Aggregation`] - Aggregation expressions (`sum by (job) (...)`)
68//! - [`Expr::Binary`] - Binary operations (`a + b`, `foo and bar`)
69//! - [`Expr::Unary`] - Unary operations (`-metric`)
70//! - [`Expr::Paren`] - Parenthesized expressions (`(a + b)`)
71//! - [`Expr::Subquery`] - Subqueries (`metric[5m:1m]`)
72//!
73//! ## Modules
74//!
75//! - [`ast`] - Abstract Syntax Tree type definitions
76//! - [`lexer`] - Low-level token parsers (numbers, strings, durations, identifiers)
77//! - [`parser`] - Expression and statement parsers
78//!
79//! ## Display
80//!
81//! All AST types implement [`std::fmt::Display`], allowing you to convert parsed
82//! expressions back to PromQL strings:
83//!
84//! ```rust
85//! use rusty_promql_parser::expr;
86//!
87//! let (_, ast) = expr("1 + 2 * 3").unwrap();
88//! assert_eq!(ast.to_string(), "1 + 2 * 3");
89//! ```
90
91pub mod ast;
92pub mod lexer;
93pub mod parser;
94
95// Re-export commonly used types and parsers
96pub use ast::{
97    Aggregation, BinaryExpr, BinaryModifier, BinaryOp, Call, Expr, GroupModifier, GroupSide,
98    SubqueryExpr, UnaryExpr, UnaryOp, VectorMatching, VectorMatchingOp,
99};
100pub use lexer::number;
101pub use parser::aggregation::{Grouping, GroupingAction};
102pub use parser::expr;
103pub use parser::selector::{LabelMatchOp, LabelMatcher, MatrixSelector, VectorSelector};
rusty_promql_parser/lib.rs

rusty_promql_parser/
lib.rs
