kip 0.1.1

Pure thread-safe engineering expression evaluator for US imperial units
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98

//! # kip — engineering expression evaluator (US imperial)
//!
//! kip is a pure, thread-safe evaluator for engineering expressions with exact
//! rational arithmetic, partial (symbolic) evaluation, and a user-extensible unit
//! registry anchored to **inch, lbf, second, Rankine** (plus angle and custom
//! base dimensions).
//!
//! ## Force-based (gravitational) system
//!
//! kip uses a **force-based** dimensional system common in structural engineering:
//! **Force** is a base dimension (anchor: `lbf`), and **mass** is derived
//! (`slug = lbf·s²/ft`). There is no hidden *g*<sub>c</sub> constant in user-visible
//! math. SI-trained users: do not expect mass to be fundamental here.
//!
//! ## Typical workflow
//!
//! 1. Build or load a [`Registry`] (`RegistryBuilder::from_seed`, [`RegistryBuilder::parse_defs`],
//!    [`RegistryBuilder::load_packs`]).
//! 2. [`parse`] an expression against that registry (optional [`Resolver`] for symbols).
//! 3. [`eval`] to a [`Value`] — fully [`Quantity`] or [`eval::value::SymExpr`] residual.
//! 4. Format with [`Quantity::display`] and [`FmtOptions`], or bind further with [`Value::bind`].
//!
//! ## Concurrency (P1)
//!
//! ASTs ([`Expr`]), registries ([`Registry`]), and evaluation are immutable and
//! `Send + Sync`. Evaluation is a pure function — no globals, no locks.
//! With the `parallel` feature: [`eval_batch`], [`eval_scenarios`], and intra-expression
//! `rayon` splits above [`PARALLEL_THRESHOLD`] nodes.
//!
//! ## Code equations (P2)
//!
//! Namespaced calls such as `ACI.fr(fc: 4000 psi, lambda: 1.0)` require named arguments.
//! Load pack TOML via [`RegistryBuilder::load_packs`] or [`load_packs`]; results carry
//! [`EquationProvenance`] on [`Quantity`].
//!
//! ## Version 0.1.0
//!
//! Full grammar conformance (lexer → packs → parallel/fmt). See `CHANGELOG.md` and
//! `VERSIONING.md` for release policy.

#![warn(clippy::mod_module_files)]
#![warn(missing_docs)]

mod dim;
mod diag;
mod eval;
mod fmt;
mod lexer;
mod packs;
mod parser;
mod quantity;
mod registry;
mod resolver;

pub use diag::{Diag, Diagnostic, ErrorCode, Hint, LintCode, Severity, Span};
pub use dim::{BaseDim, CustomDimId, Dimension};
pub use eval::{eval, eval_checked, EvalOutcome, LintSink, Mag, Value};
pub use eval::units::convert_quantity;
pub use eval::value::{ConstraintSet, EquationProvenance, Quantity, SymBinaryOp, SymExpr, SymNode, SymUnaryOp, Symbol};
pub use fmt::{format_quantity, FmtOptions};
pub use lexer::{lex, lex_checked, LexOutcome, LexSpan, SpannedToken, Token};
pub use parser::{parse, parse_checked, BinaryOp, Callee, CallArg, CmpOp, Expr, ExprKind, ExprNode, NodeId, ParseOutcome, UnaryOp};
pub use quantity::{UnitExpr, UnitExponent};
pub use registry::{Registry, RegistryBuilder};
pub use resolver::{EmptyResolver, MapResolver, Resolver};
pub use packs::equation::{EquationRecord, EquationRegistry};
#[cfg(feature = "packs")]
pub use packs::{load_packs, load_packs_into, DEMO_PACK_TOML};

#[cfg(feature = "parallel")]
pub use eval::{eval_batch, eval_scenarios, PARALLEL_THRESHOLD};

/// Crate version string (matches `Cargo.toml`).
pub const VERSION: &str = env!("CARGO_PKG_VERSION");

#[cfg(test)]
mod send_sync {
    use super::*;
    use std::sync::Arc;

    const fn assert_send_sync<T: Send + Sync + ?Sized>() {}

    #[test]
    fn public_types_are_send_sync() {
        assert_send_sync::<Dimension>();
        assert_send_sync::<Quantity>();
        assert_send_sync::<Value>();
        assert_send_sync::<Diag>();
        assert_send_sync::<Diagnostic>();
        assert_send_sync::<Registry>();
        assert_send_sync::<Expr>();
        assert_send_sync::<Arc<Registry>>();
        assert_send_sync::<Arc<Expr>>();
        assert_send_sync::<SpannedToken>();
        assert_send_sync::<Token>();
        assert_send_sync::<dyn Resolver>();
    }
}