rtlola_frontend/
lib.rs

1//! The front-end of the RTLola Monitoring Framework
2//!
3//! This crate offers functionality to transform a textual representation of an RTLola specification into one of three tree-shaped representation and perform a variety of checks.
4//!
5//! # Specification Representations
6//! * [RtLolaAst]: The Ast represents the abstract syntax of the specification.  It is obtained by first parsing the specification into a homogenous tree
7//!   and then remove concrete syntax fragments irrelevant for the logics of the specification.  Apart from that, the Ast does not provide much functionality.
8//!   The only checks performed when creating the Ast concern the correct syntax.  See also: [rtlola_parser], [RtLolaAst], and [parse_to_ast].
9//! * [RtLolaHir]: The Hir represents a high-level intermediate representation optimized for analyzability.  It contains more convenient methods than the Ast, enables different
10//!   analysis steps and provides their reports.  The Hir traverses several modes representing the level to which it was analyzed and refined.
11//!   Its base mode is `RtLolaHir<BaseMode>` and its fully analyzed version is `RtLolaHir<CompleteMode>`.  See also: [rtlola_hir], [rtlola_hir::RtLolaHir], [parse_to_base_hir], and [parse_to_base_hir].
12//! * [RtLolaMir]: The Mir represents a mid-level intermediate representation optimized for external use such as interpretation and compilation.  It contains several interconnections
13//!   enabling easy accesses and additional annotation such as memory bounds for each stream. See also: [RtLolaMir], [parse].
14//!
15//! As a rule of thumb, if you want to analyze and/or enrich a specification, use the [RtLolaHir].  If you only need a convenient representation of the specification for some devious
16//! activity such as compiling it into something else, the [RtLolaMir] is the way to go.
17//!
18//! # Modules
19//! * [mir] Contains anything related to the [RtLolaMir].
20
21#![forbid(unused_must_use)]
22#![warn(
23    missing_docs,
24    missing_debug_implementations,
25    missing_copy_implementations,
26    trivial_casts,
27    trivial_numeric_casts,
28    unsafe_code,
29    unstable_features,
30    unused_import_braces,
31    unused_qualifications
32)]
33
34pub mod hash;
35mod lowering;
36pub mod mir;
37pub mod tag_parser;
38
39use mir::Mir;
40use rtlola_hir::hir::FeatureSelector;
41use rtlola_hir::{BaseMode, CompleteMode};
42use rtlola_parser::RtLolaAst;
43
44#[cfg(test)]
45mod tests;
46
47pub use rtlola_hir::config::{FrontendConfig, MemoryBoundMode, ParserConfigExt};
48pub(crate) use rtlola_hir::hir::RtLolaHir;
49pub use rtlola_parser::ParserConfig;
50pub use rtlola_reporting::{Diagnostic, Handler, RawDiagnostic, RtLolaError, Span};
51
52pub use crate::mir::RtLolaMir;
53
54/// Attempts to parse a textual specification into an [RtLolaMir].
55///
56/// The specification is wrapped into a [ParserConfig] and can either be a string or a path to a specification file.
57///
58/// # Fail
59/// Fails if either the parsing was unsuccessful due to parsing errors such as incorrect syntax or an analysis failed
60/// due to a semantic error such as inconsistent types or unknown identifiers.
61pub fn parse<'a>(config: impl Into<FrontendConfig<'a>>) -> Result<RtLolaMir, RtLolaError> {
62    let hir = parse_to_final_hir(config)?;
63    Ok(Mir::from_hir(hir))
64}
65
66/// Attempts to parse a textual specification into an [RtLolaHir].
67/// Returns an [FeatureSelector] allowing to check for language features that are not supported by the backend.
68///
69/// The specification is wrapped into a [ParserConfig] and can either be a string or a path to a specification file.
70///
71/// # Fail
72/// Fails if either the parsing was unsuccessful due to parsing errors such as incorrect syntax or an analysis failed
73/// due to a semantic error such as inconsistent types or unknown identifiers.
74pub fn parse_with_features<'a>(
75    config: impl Into<FrontendConfig<'a>>,
76) -> Result<FeatureSelector, RtLolaError> {
77    let hir = parse_to_final_hir(config)?;
78    Ok(FeatureSelector::new(hir))
79}
80
81/// Attempts to parse a textual specification into a fully analyzed `RtLolaHir<CompleteMode>`.
82///
83/// The specification is wrapped into a [ParserConfig] and can either be a string or a path to a specification file.
84///
85/// # Fail
86/// Fails if either the parsing was unsuccessful due to parsing errors such as incorrect syntax or an analysis failed
87/// due to a semantic error such as inconsistent types or unknown identifiers.
88pub fn parse_to_final_hir<'a>(
89    cfg: impl Into<FrontendConfig<'a>>,
90) -> Result<RtLolaHir<CompleteMode>, RtLolaError> {
91    let config: FrontendConfig = cfg.into();
92    let spec = rtlola_parser::parse(config.parser_config())?;
93    rtlola_hir::fully_analyzed(spec, &config)
94}
95
96/// Attempts to parse a textual specification into an `RtLolaHir<BaseMode>`.
97///
98/// The specification is wrapped into a [ParserConfig] and can either be a string or a path to a specification file.
99///
100/// # Fail
101/// Fails if either the parsing was unsuccessful due to parsing errors such as incorrect syntax or the initial analysis failed
102/// due occurrences of unknown identifiers.
103pub fn parse_to_base_hir(cfg: &ParserConfig) -> Result<RtLolaHir<BaseMode>, RtLolaError> {
104    let spec = rtlola_parser::parse(cfg)?;
105    rtlola_hir::from_ast(spec)
106}
107
108/// Attempts to parse a textual specification into an [RtLolaAst].
109///
110/// The specification is wrapped into a [ParserConfig] and can either be a string or a path to a specification file.
111///
112/// # Fail
113/// Fails if the parsing was unsuccessful due to parsing errors such as incorrect syntax.
114pub fn parse_to_ast(cfg: &ParserConfig) -> Result<RtLolaAst, RtLolaError> {
115    rtlola_parser::parse(cfg)
116}
rtlola_frontend/lib.rs

rtlola_frontend/
lib.rs
