Crate kip 

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_c 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.

Macros

qty

Macro helper for tests and registry builder (exact integer magnitudes).

Structs

ConstraintSet

Dimension constraints accumulated over free symbols.

CustomDimId

Identifier for a user-declared base dimension (e.g. dimension Currency).

Diag

Primary error type returned by parse/eval APIs.

Diagnostic

A single diagnostic message.

Dimension

A dimension as a sorted map of base dimension → rational exponent.

EmptyResolver

Resolver that never binds symbols.

EquationProvenance

Provenance for a quantity produced by a code equation.

EquationRecord

One equation loaded from a pack (pre-parsed body, frozen contracts).

EquationRegistry

Immutable index of equations for one registry generation.

EvalOutcome

Result of checked evaluation (value + non-fatal lints).

Expr

Frozen expression tree.

ExprNode

Single AST node with span.

FmtOptions

Formatting options for quantity display.

LexOutcome

Outcome of lexing with non-fatal lints.

LintSink

Collects evaluation lints with de-duplication policy for exactness loss.

MapResolver

Simple map-backed resolver for tests and examples.

NodeId

Stable node identifier within an expression arena.

ParseOutcome

Outcome of parse-with-lints API.

Quantity

A unit-preserving engineering quantity.

Registry

Immutable frozen registry (generation N).

RegistryBuilder

Mutable registry builder; freezes into immutable Registry.

Span

Byte offset range in source text (half-open [start, end)).

SpannedToken

A token with its source span.

SymExpr

Symbolic residual expression (M5).

Symbol

A free symbol name in a partial evaluation residual.

Enums

BaseDim

Fundamental dimension in the force-based imperial system.

BinaryOp

Binary operators in expression context.

CallArg

Call argument (positional or named).

Callee

Function or code-equation callee.

CmpOp

Comparison operators (reserved v1.1).

ErrorCode

Structured error codes (grammar-spec §9 + plan §5.3 extensions).

ExprKind

Expression node kinds (grammar §5.2).

Hint

Optional structured hint for IDEs and calc sheets.

LintCode

Lint codes (non-fatal).

Mag

Magnitude of a quantity: exact rational, or float after exactness loss.

Severity

Diagnostic severity.

SymBinaryOp

Binary operators in symbolic residuals.

SymNode

Node in a symbolic expression tree.

SymUnaryOp

Unary operators in symbolic residuals.

Token

Lexer token (grammar-spec §3).

UnaryOp

Unary operators.

UnitExponent

Exponent on a unit factor (ft^2, psi^(1/2), psi^0.5).

UnitExpr

A unit expression preserving user syntax (e.g. kip·ft, lbf/ft^2).

Value

Result of evaluation: fully known or partially symbolic.

Constants

DEMO_PACK_TOML

Liberally licensed demo pack for tests and documentation.

PARALLEL_THRESHOLD

Minimum subtree node count before rayon::join splits siblings (M7).

VERSION

Crate version string (matches Cargo.toml).

Traits

Resolver

Resolve free symbols to known or symbolic values during parse/eval.

Functions

convert_quantity

Convert a quantity to another unit expression (same dimension).

eval

Evaluate a parsed expression against a frozen registry and symbol resolver.

eval_batch

Evaluate many independent expressions concurrently (M7).

eval_checked

Evaluate and collect lints (mirror of lex_checked / parse_checked).

eval_scenarios

Evaluate one expression under many resolver scenarios (M7).

format_quantity

Format a quantity per options (never mutates the input quantity).

lex

Lex source into tokens; returns error on first hard lex failure.

lex_checked

Lex source, collecting lints and continuing past non-fatal issues where possible.

load_packs

Parse TOML packs into a standalone equation registry (units must already exist).

load_packs_into

Load equation packs into a registry builder (also ingests optional [defs]).

parse

Parse source into an immutable shared AST (M3).

parse_checked

Parse with resolver-aware shadow lints (M3).

Type Aliases

LexSpan

Lexer span type (alias for crate::diag::Span).