promql_parser/lib.rs
1// Copyright 2023 Greptime Team
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7// http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15//! # PromQL Lexer and Parser
16//!
17//! The goal of this project is to build a PromQL lexer and parser capable of
18//! parsing PromQL that conforms with [Prometheus Query][querying-prometheus].
19//!
20//! ## Example
21//!
22//! The parser entry point is [`parser::parse()`], which takes a string slice of Promql
23//! and returns the parse result, either an AST ([`parser::Expr`]) or an error message.
24//! Other query parameters like time range and step are included in [`parser::EvalStmt`].
25//!
26//! ``` rust
27//! use promql_parser::parser;
28//!
29//! let promql = r#"http_requests_total{environment=~"staging|testing|development",method!="GET"} offset 5m"#;
30//!
31//! match parser::parse(promql) {
32//! Ok(expr) => {
33//! println!("Prettify:\n{}\n", expr.prettify());
34//! println!("AST:\n{expr:?}");
35//! }
36//! Err(info) => println!("Err: {info:?}"),
37//! }
38//! ```
39//!
40//! or you can directly run examples under this repo:
41//!
42//! ``` shell
43//! cargo run --example parser
44//! ```
45//!
46//! This outputs:
47//!
48//! ```rust, ignore
49//! Prettify:
50//! http_requests_total{environment=~"staging|testing|development",method!="GET"} offset 5m
51//!
52//! AST:
53//! VectorSelector(VectorSelector { name: Some("http_requests_total"), matchers: Matchers { matchers: [Matcher { op: Re(staging|testing|development), name: "environment", value: "staging|testing|development" }, Matcher { op: NotEqual, name: "method", value: "GET" }] }, offset: Some(Pos(300s)), at: None })
54//! ```
55//! ## PromQL compliance
56//!
57//! This crate declares compatible with [prometheus v2.45.0][prom-v2.45.0], which is
58//! released at 2023-06-23. Any revision on PromQL after this commit is not guaranteed.
59//!
60//! [prom-v2.45.0]: https://github.com/prometheus/prometheus/tree/v2.45.0
61//! [querying-prometheus]: https://prometheus.io/docs/prometheus/latest/querying/basics/
62
63#![allow(clippy::let_unit_value)]
64lrpar::lrpar_mod!("parser/promql.y");
65
66pub mod label;
67pub mod parser;
68pub mod util;