ifc_validate/express.rs
1//! EXPRESS rule evaluation: WHERE rules, type rules, global rules and the
2//! FUNCTIONs they call, read from the release's own schema text.
3//!
4//! ```no_run
5//! # fn demo(model: &ifc_model::Model, exp: &str) -> Result<(), Box<dyn std::error::Error>> {
6//! use ifc_validate::{express::ExpressRules, validate_with_options, ValidateOptions};
7//!
8//! let schema = ifc_schema::ifc4();
9//! // `exp` is the text of IFC4.exp, which the caller supplies.
10//! let rules = ExpressRules::parse(exp, schema)?;
11//! let report = validate_with_options(model, schema, &ValidateOptions::new().express(&rules));
12//! # Ok(()) }
13//! ```
14//!
15//! # Why the rule text is supplied, not bundled
16//!
17//! The IFC schemas are CC BY-ND 4.0. The bundled tables keep their
18//! structure and rule labels, never rule text, and generated code
19//! transcribing the rules would be a derivative of it. So the evaluator is
20//! an interpreter: [`ExpressRules::parse`] reads the `.exp` file the caller
21//! has (`scripts/fetch-ifc-schemas.sh` fetches and checksums all five
22//! releases), and nothing derived from it is written anywhere.
23//!
24//! # Semantics
25//!
26//! ISO 10303-11, with three-valued logic: a rule is violated when it
27//! evaluates to FALSE, and an UNKNOWN or `?` result is reported as
28//! indeterminate, never as a pass or a violation. `TYPEOF` answers the
29//! SELECT types a value belongs to as well as its own types. One schema
30//! defect is worked around: rule strings naming a type in mixed case
31//! (`'IFC4X3_ADD2.IfcMappedItem'`) are read upper-cased, as `resolve.rs`
32//! explains.
33//!
34//! # Internal split
35//!
36//! - `lexer.rs`, `parse.rs`, `parse_expr.rs`, `parse_stmt.rs`: reading the
37//! text into `ast.rs`.
38//! - `resolve.rs`: binding names to slots, functions, entities and
39//! enumeration items.
40//! - `tables.rs`: attribute layout, cross-checked against the bundled
41//! tables, and `TYPEOF` names.
42//! - `value.rs`, `machine.rs`, `eval.rs`, `ops.rs`, `builtins.rs`,
43//! `exec.rs`, `access.rs`: the interpreter.
44//! - `run.rs`: applying every rule to a model and reporting.
45//! - `rules.rs`, `options.rs`, `coverage.rs`, `error.rs`: the public
46//! surface.
47
48mod access;
49mod ast;
50mod builtins;
51mod coverage;
52mod error;
53mod eval;
54mod exec;
55mod lexer;
56mod machine;
57mod ops;
58mod options;
59mod parse;
60mod parse_expr;
61mod parse_stmt;
62mod resolve;
63mod rules;
64mod run;
65mod tables;
66mod value;
67
68pub use coverage::{Coverage, RuleCount};
69pub use error::ExpressError;
70pub use options::{BudgetExceeded, EvalLimits};
71pub use rules::ExpressRules;
72
73pub(crate) use run::evaluate;