cel_runtime/
lib.rs

1//! cel-rs provides a stack-based runtime for developing domain specific languages, including
2//! concatenative languages to describe concurrent processes. A sequence is a list of operations
3//! (the machine instructions). Each operation is a closure that takes it's arguments from the stack
4//! and the result is pushed back onto the stack.
5//!
6//! Segments can be created in two ways.
7//!
8//! 1. Using the [`DynSegment`] struct which validates the type safety of the
9//!    operations at runtime as the segment is built.
10//! 2. Using the [`Segment`] struct, which validates the type safety of the
11//!    operations at compile time.
12//!
13//! The two types of segments can be converted to each other [not yet implemented from `Segment` to
14//! `DynSegment`].
15//!
16//! Operations are added using the form `op#[r]` where # is the arity of the operation and the
17//! optional `r` signifies that the operation returns a [`std::result::Result`] type and may fail.
18//!
19//! # Composable canonical values
20//!
21//! [`Array<T>`] owns actual contiguous `T` values. [`Array::into_vec`] and
22//! [`Array::from_vec`] transfer allocations in O(1); [`Array::as_slice`] borrows
23//! them. A nested array uses `Array<Array<T>>`: its vector view is
24//! `Vec<Array<T>>`, not `Vec<Vec<T>>`. Deep native conversion builds a new outer
25//! vector. Tuples use source-ordered [`CStackList`] values ending in [`CNil<()>`],
26//! bridged to native tuples by [`IntoCStackList`] and [`IntoRustTuple`].
27//! Source unit uses [`Nil`], not an opaque host [`Leaf<()>`].
28//!
29//! [`ValueType`] records complete recursive identity/layout and optional
30//! capabilities; [`ArrayOf`], [`Cons`], [`Nil`], [`Leaf`], and [`FnOf`] witness
31//! concrete representations. Moving storage requires no clone/equality/debug
32//! bounds. [`OwnedValue`] checks arbitrary erased external values, whereas
33//! [`DynSegment::prepare`] binds a [`PreparedSegment`] once. Repeated prepared
34//! calls borrow arguments and return independent owners without comparing
35//! descriptors or downcasting. Runtime-bound hosts can instead prepare a
36//! [`prepared_segment::PreparedRawSegment`] and uphold its unsafe pointer contract.
37//! [`Callable`] binds native or prepared bodies to the same typed interface.
38//! This is interoperability with native Rust, not a macro-compiled CEL backend.
39//!
40//! ```
41//! use cel_runtime::{ArrayOf, Cons, IntoCStackList, IntoRustTuple, Leaf, Nil, DynSegment};
42//! type Row = Cons<Leaf<i32>, Cons<Leaf<bool>, Nil>>;
43//! let mut body = DynSegment::new::<()>();
44//! body.just(7i32); body.just(true); body.make_tuple(2, 0).unwrap();
45//! body.make_array(1, 0).unwrap();
46//! let mut prepared = body.prepare::<Nil, ArrayOf<Row>>().unwrap();
47//! let row = prepared.call(&().into_c_stack_list()).unwrap().into_vec().pop().unwrap();
48//! assert_eq!(row.into_rust_tuple(), (7, true));
49//! ```
50//!
51//! # Examples
52//!
53//! ```rust
54//! use cel_runtime::*;
55//!
56//! // Create a segment that takes a u32 and &str as arguments
57//! let segment = Segment::<(u32, &str)>::new()
58//!     .op1r(|s| {
59//!         let r = s.parse::<u32>()?;
60//!         Ok(r)
61//!     })
62//!     .op2(|a, b| a + b)
63//!     .op1(|r| r.to_string());
64//! assert_eq!(segment.call((1u32, "2")).unwrap(), "3");
65//! ```
66
67/// Concrete typed ownership for homogeneous, contiguous arrays.
68pub mod array;
69/// Compile-time stack list implementation for type-safe stack operations.
70pub mod c_stack_list;
71/// Private validated canonical host-operation emission into the existing raw segment.
72mod canonical_operation;
73/// Private canonical container construction and trusted frame moves.
74mod container_execution;
75/// First-class callable CEL values with declared signatures.
76pub mod dyn_closure;
77/// Dynamic segment implementation with runtime type checking.
78pub mod dyn_segment;
79/// Checked adapters for the existing external host boundaries.
80mod host_value_bridge;
81/// Traits for working with type lists and type information.
82pub mod list_traits;
83/// Memory management and alignment utilities for the runtime.
84pub mod memory;
85/// Whole-value ownership with complete checked representation witnesses.
86pub mod owned_value;
87/// Prepared typed execution over the existing raw interpreter.
88pub mod prepared_segment;
89/// Raw segment implementation without type safety.
90pub mod raw_segment;
91/// Raw sequence implementation for operation sequences.
92pub mod raw_sequence;
93/// Raw stack implementation for low-level stack operations.
94pub mod raw_stack;
95/// Raw vector implementation for dynamic memory allocation.
96pub mod raw_vec;
97/// Type-safe segment implementation with compile-time validation.
98pub mod segment;
99/// Tuple list implementation for type-safe tuple operations.
100pub mod tuple_list;
101/// Canonical tuple-list layout support.
102mod tuple_value;
103/// Complete recursive canonical metadata and sealed concrete representation witnesses.
104pub mod value_type;
105
106pub use array::Array;
107/// Signature-typed callable facade over the canonical shared carrier.
108pub mod callable;
109pub use c_stack_list::*;
110pub use callable::Callable;
111pub use dyn_closure::{CallDynFn, DynClosure};
112pub use dyn_segment::*;
113pub use list_traits::*;
114pub use memory::*;
115pub use owned_value::OwnedValue;
116pub use prepared_segment::PreparedSegment;
117pub use raw_segment::*;
118pub use raw_sequence::*;
119pub use raw_stack::*;
120pub use raw_vec::*;
121pub use segment::*;
122pub use tuple_list::*;
123pub use value_type::{
124    ArgumentList, ArrayOf, AssociatedType, Cons, FnOf, Leaf, Nil, ValueKind, ValueRepr, ValueType,
125};
cel_runtime/lib.rs

cel_runtime/
lib.rs
