sim_codec/lib.rs
1//! Core decoder/encoder and output-position contracts for the SIM codec layer.
2//!
3//! sim-codec is the foundation crate of the sim-codec-* family. The SIM kernel
4//! defines the `Expr` graph and the codec contract types; this crate provides
5//! the concrete runtime that every other codec crate implements against: the
6//! `Decoder`/`Encoder` traits, their located and tree-shaped variants, the
7//! `DecodePosition`/`DecodeTarget` output-position model (eval, quote, data,
8//! pattern), and the `CodecRuntime` glue that registers a codec as a
9//! runtime object. On top of those contracts it carries the shared
10//! `Expr`<->tree encode machinery, domain-codec scaffolding, decode resource
11//! limits, portable encode/decode, string-literal coding, and tree validation.
12//!
13//! A decoder turns tokens or text into a checked `Expr` form; an encoder knows
14//! its output position and renders an `Expr` back to text or bytes. Downstream
15//! crates (general-purpose and domain codecs) build on these primitives rather
16//! than re-implementing them.
17//!
18//! Module map (these modules are private; their public items are re-exported at
19//! the crate root, so they are listed here in plain text rather than linked):
20//!
21//! - implementation: implementation root that aggregates the submodules below
22//! and re-exports their public surface.
23//! - runtime: the `Decoder`/`Encoder` runtime contracts, the
24//! `DecodePosition`/`DecodeTarget` output positions, `Input`/`Output`, and
25//! the `CodecRuntime` registration glue.
26//! - domain: builder scaffolding for domain codec libs (`DomainCodecLib`) and
27//! the shared UTF-8 input helper.
28//! - domain_form: a generic `#(...)` domain-form parser and formatter.
29//! - limits: decode resource ceilings (`DecodeLimits`), running budgets
30//! (`DecodeBudget`), and the `ReadCx` decode context.
31//! - list_encode: the shared list/`Expr` value-to-expr encode machinery.
32//! - lowering: structure-preserving operator-node lowering.
33//! - portable: codec-neutral, lossless portable encode/decode for the data
34//! subset of `Expr`.
35//! - strings: string-literal encode/decode helpers.
36//! - tree: structural validation of a `LocatedExprTree`.
37//! - runtime_api: the eval-facing surface that drives codecs through the kernel
38//! (`DecodedForm`, codec lookup, and decode/encode entry points).
39
40#![forbid(unsafe_code)]
41#![deny(missing_docs)]
42
43mod implementation;
44mod prism;
45mod runtime_api;
46
47pub use implementation::*;
48pub use prism::*;
49pub use runtime_api::*;
50
51/// Cookbook recipes for this codec, embedded at build time.
52pub static RECIPES: sim_cookbook::EmbeddedDir =
53 include!(concat!(env!("OUT_DIR"), "/cookbook_recipes.rs"));