nmbrs_workload/
lib.rs

1// Copyright 2024-2026 Jonathan Shook
2// SPDX-License-Identifier: Apache-2.0
3
4//! # nmbrs-workload
5//!
6//! Contract & axioms: [SRD 25](../../docs/SRD/25_workload_contract.md).
7//!
8//! Workload specification parsing and processing for nmbrs. Owns
9//! the YAML schema definition (op templates, bindings, phases,
10//! scenarios, tags, parameter inheritance) plus the inline
11//! `op='...'` shorthand the CLI accepts in place of a workload
12//! file.
13//!
14//! The crate's deliberately one-way: it parses YAML / inline
15//! shorthand into a [`model::Workload`] tree and exposes helpers
16//! to extract bind-points, tag-filter ops, and resolve template
17//! parameters. It does not execute anything — that's
18//! `nmbrs-runtime`'s job.
19//!
20//! ## Pieces
21//!
22//! - [`model`] — the parsed `Workload` AST. `Workload` →
23//!   `WorkloadPhase`s + ops + `ScenarioNode`s; an op carries its
24//!   field map plus parsed bindings.
25//! - [`parse`] — YAML → `Workload`, with phase-name preservation
26//!   and friendly error messages.
27//! - [`inline`] — `nmbrs run op='hello {{cycle}}'` synthesizer:
28//!   builds a one-op `Workload` from a single CLI string.
29//! - [`bindpoints`] — extracts `{name}`, `{{expr}}`, qualified
30//!   refs (`{coord:cycle}`, `{capture:foo}`) from any string.
31//! - [`tags`] — `tags=block:main,phase:read` filters during op
32//!   selection.
33//! - [`template`] — `{param}` template substitution with
34//!   default-value support.
35//!
36//! ## Quick examples
37//!
38//! Bind-point extraction:
39//!
40//! ```
41//! use nmbrs_workload::bindpoints::{extract_bind_points, BindPoint, BindQualifier};
42//!
43//! let pts = extract_bind_points("INSERT INTO t VALUES ({id}, {{hash(cycle)}})");
44//! assert_eq!(pts.len(), 2);
45//! assert!(matches!(
46//!     &pts[0],
47//!     BindPoint::Reference { name, qualifier: BindQualifier::None, .. } if name == "id",
48//! ));
49//! assert!(matches!(&pts[1], BindPoint::InlineDefinition(expr) if expr == "hash(cycle)"));
50//! ```
51//!
52//! Template substitution at workload-build time:
53//!
54//! ```
55//! use nmbrs_workload::template::expand_templates;
56//! use std::collections::HashMap;
57//!
58//! let mut params = HashMap::new();
59//! params.insert("table".into(), "users".into());
60//! let resolved = expand_templates(
61//!     "SELECT * FROM TEMPLATE(table,defaultvalue)",
62//!     &params,
63//! );
64//! assert_eq!(resolved, "SELECT * FROM users");
65//! ```
66//!
67//! ## See also
68//!
69//! - SRD 20 (`docs/SRD/20_workload_model.md`) — workload model
70//! - SRD 21 (`docs/SRD/21_parameters.md`) — parameter resolution
71//!   precedence
72//! - SRD 18 (`docs/SRD/18_control_flow.md`) — scenario-tree
73//!   constructs (`for_each`, `do_while`, `do_until`,
74//!   `for_combinations`)
75
76pub mod bindpoints;
77/// SRD-85 bundled-workload catalog (embedded workloads,
78/// tiers, exact-name lookup).
79pub mod catalog;
80pub mod construction;
81/// SRD-109 driver manifests (`driver=<name>` → adapter + library
82/// + defaults).
83pub mod drivers;
84pub mod edit;
85pub mod extends;
86pub mod implements;
87pub mod inline;
88pub mod magnitude;
89pub mod metric_format;
90pub mod model;
91pub mod op_templates;
92pub mod parse;
93pub mod polydat_matter;
94pub mod report;
95pub mod report_synth;
96pub mod spectest;
97/// SRD-85 deep workload suggestions — the shared "did you mean"
98/// set over the local file hierarchy and the bundled catalog,
99/// used by completion and the resolver not-found paths.
100pub mod suggest;
101pub mod tags;
102pub mod template;
103pub mod verify;
104pub mod vocab;
nmbrs_workload/lib.rs

nmbrs_workload/
lib.rs
