sim_citizen/
lib.rs

1//! Citizen support outside the SIM kernel.
2//!
3//! A citizen is a public SIM-facing runtime value with a class-backed read
4//! constructor, constructor encoding, conformance fixture, and census row.
5//! Domain values usually opt in with `#[derive(Citizen)]`; hard cases may
6//! register hand-written citizens, and live handles carry inline
7//! `#[non_citizen(reason = "...", kind = "...", descriptor = "...")]`
8//! exemptions that name their descriptor strategy.
9//!
10//! This crate owns only the shared support layer: registry rows, runtime
11//! installation helpers, fixture checks, generated census rendering, and the
12//! semantic equality helpers used by the strict citizen gate. Read-construct
13//! remains capability-gated by the codec/runtime path, not by this crate.
14//!
15//! # Surface
16//!
17//! Conformance fixtures check a citizen's read-construct round trip; the field
18//! and equality traits encode citizen fields and back the strict semantic
19//! equality gate; the registry and runtime helpers install citizens into a
20//! library and a context; the card and census helpers render browse and census
21//! output for both citizens and explicit non-citizen exemptions; and a
22//! reference citizen value is provided as an example.
23//!
24//! # Explicit registration
25//!
26//! Inventory-backed discovery is convenient for normal host binaries. Strict
27//! release, LTO, and wasm checks can instead build a [`CitizenRegistry`] by
28//! calling [`CitizenRegistry::register`] for each expected citizen type, load
29//! that registry as a kernel library, and call
30//! [`run_registry_conformance_expecting`]. The expected-symbol guard reports a
31//! missing row instead of letting a shorter registry pass.
32
33#![forbid(unsafe_code)]
34#![deny(missing_docs)]
35
36extern crate self as sim_citizen;
37
38mod card;
39mod census;
40mod conformance;
41mod eq;
42mod field;
43mod read_construct;
44mod registry;
45mod runtime;
46mod symbol;
47
48pub use ::inventory;
49pub use card::{citizen_card, non_citizen_card};
50pub use census::{
51    citizen_census_markdown, citizen_registry_census_markdown, non_citizen_census_markdown,
52    render_citizen_census, render_non_citizen_census,
53};
54pub use conformance::{
55    check_default_fixture, check_fixture, check_value_fixture,
56    check_value_fixture_with_wrong_version, run_registered_conformance,
57    run_registered_conformance_expecting, run_registry_conformance,
58    run_registry_conformance_expecting,
59};
60pub use eq::{CitizenEq, expr_citizen_eq, values_citizen_eq};
61pub use field::{
62    CitizenField, arity_error, decode_version, field_error, value_from_expr, value_to_expr,
63};
64pub use read_construct::text_read_construct_expr;
65pub use registry::{
66    CitizenInfo, CitizenLib, CitizenRegistry, InstallFn, NonCitizenInfo, install_all,
67    install_namespace, registered_citizens, registered_non_citizens,
68};
69pub use runtime::{Citizen, CitizenRuntime, constructor_expr, install_derived};
70pub use symbol::parse_symbol;
71
72#[cfg(test)]
73mod example;
74
75#[cfg(test)]
76mod tests;
sim_citizen/lib.rs

sim_citizen/
lib.rs
