Struct TemplateBuilder

Source

pub struct TemplateBuilder { /* private fields */ }

Expand description

Owns declarations and validates all local references before accepting them.

Private included names do not enter this builder’s declaration namespace.

§Examples

See the module example.

Implementations§

Source §

impl TemplateBuilder

Source

pub fn new() -> Self

Creates an empty recipe with its own local handle namespace.

§Examples

let template = TemplateBuilder::new().finish()?;
assert!(template.is_relationship_only());

Source

pub fn parameter<T: 'static>( &mut self, name: &str, ) -> Result<CellSlot, TemplateError>

Declares a typed formal that allocates and writes no destination cell.

§Errors

Returns TemplateError::DuplicateParameter for a repeated declaration name, or TemplateError::Capacity when storage cannot be reserved.

Complexity: Amortized O(n) time and space for a name of length n.

§Examples

See the module example.

Source

pub fn cell<T, F>( &mut self, name: &str, initial: F, ) -> Result<CellSlot, TemplateError>
where T: Any + PartialEq + 'static, F: Fn() -> Result<T> + 'static,

Declares a private cell initialized afresh for every live instance.

The initializer owns its captures and runs only during instantiation.

§Errors

Returns TemplateError::DuplicateParameter for a repeated declaration name, or TemplateError::Capacity when storage cannot be reserved.

Complexity: Amortized O(n) time and space for a name of length n.

§Examples

let mut builder = TemplateBuilder::new();
builder.cell("count", || Ok(3i32))?;
let mut sheet = Sheet::new();
let instance = builder.finish()?.instantiate(&mut sheet, &[])?;
assert_eq!(*sheet.read::<i32>(instance.cells()[0])?, 3);

Source

pub fn source<T, F>( &mut self, name: &str, initial: F, ) -> Result<CellSlot, TemplateError>
where T: Any + PartialEq + 'static, F: Fn() -> Result<T> + 'static,

Declares a private source initialized afresh for every live instance.

Specialization removes every whole method that writes a source.

§Errors

Returns TemplateError::DuplicateParameter for a repeated declaration name, or TemplateError::Capacity when storage cannot be reserved.

Complexity: Amortized O(n) time and space for a name of length n.

§Examples

let mut builder = TemplateBuilder::new();
builder.source("constant", || Ok(7i32))?;
let mut sheet = Sheet::new();
let instance = builder.finish()?.instantiate(&mut sheet, &[])?;
assert_eq!(sheet.cell_kind(instance.cells()[0]), Some(CellKind::Source));

Source

pub fn relationship( &mut self, methods: Vec<MethodRecipe>, ) -> Result<RelationshipSlot, TemplateError>

Appends a relationship after validating owners and native edge-set rules.

Methods must reference the same cell set and have distinct, non-nested output sets. Source-writing methods remain authored until specialization.

§Errors

Returns TemplateError::EmptyRelationship, TemplateError::ForeignHandle, TemplateError::InvalidDefinition, or TemplateError::Capacity.

Complexity: O(m² × e) time and O(m × e) space for m methods of at most e edges.

§Examples

See the module example.

Source

pub fn out( &mut self, writer: MethodRecipe, ) -> Result<RelationshipSlot, TemplateError>

Promotes a private ordinary cell through its sole, single-output writer.

Formal parameters cannot become outputs. Requirements attach separately, in declaration order, through Self::require.

§Errors

Returns TemplateError::InvalidDefinition for a non-private, non-ordinary, multiply-written, or non-single output; also returns relationship validation errors.

Complexity: O(i + r) time and O(i) space for inputs i and prior output summaries r.

§Examples

let mut b = TemplateBuilder::new();
let input = b.parameter::<i32>("input")?;
let output = b.cell("output", || Ok(0i32))?;
b.out(MethodRecipe::new(&[input], &[output], |i, o| {
    Ok(Method::from_fn_1_1(i[0], o[0], |x: &i32| Ok(*x)))
})?)?;

Source

pub fn filter<F>( &mut self, cell: &CellSlot, inputs: &[CellSlot], make: F, ) -> Result<(), TemplateError>
where F: Fn(CellId, &[CellId]) -> Result<Filter> + 'static,

Attaches one freshly constructed filter to a private cell.

The factory receives the live target and positional dynamic arguments. Its filter must declare those exact arguments and their concrete types.

§Errors

Returns ownership, capacity, or TemplateError::InvalidDefinition errors for a formal target, duplicate filter, or self-dependent filter.

Complexity: O(i) time and space for i inputs.

§Examples

let mut b = TemplateBuilder::new();
let x = b.cell("x", || Ok(0i32))?;
b.filter(&x, &[], |_, _| Ok(Filter::from_fn_0(|x: &i32| Ok((*x).max(0)))))?;

Source

pub fn require<F>( &mut self, cell: &CellSlot, inputs: &[CellSlot], make: F, ) -> Result<(), TemplateError>
where F: Fn(&[CellId]) -> Result<Requirement> + 'static,

Attaches a freshly constructed requirement to a private cell.

The factory must declare exactly the supplied positional inputs and types. Native attachment evaluates ordinary/source requirements immediately; output requirements wait until propagation.

§Errors

Returns ownership, capacity, or TemplateError::InvalidDefinition errors for a formal target. Factory and native errors occur during instantiation.

Complexity: O(i) time and space for i inputs.

§Examples

let mut b = TemplateBuilder::new();
let x = b.cell("x", || Ok(1i32))?;
b.require(&x, &[x.clone()], |i| Ok(Requirement::from_fn_1(i[0], |x: &i32| Ok(*x > 0))))?;

Source

pub fn conditional<T, F>( &mut self, inputs: &[CellSlot], make: F, branches: Vec<(Vec<T>, Vec<RelationshipSlot>)>, default: Vec<RelationshipSlot>, ) -> Result<(), TemplateError>
where T: Clone + Any + PartialEq + 'static, F: Fn(&[CellId]) -> Result<MatchExpr> + 'static,

Registers native conditional branches over direct relationships or included groups.

Included groups must be transitively relationship-only before specialization. Each constituent remains a distinct native relationship; no extra activation layer is introduced. Keys follow native first-match semantics.

§Errors

Returns TemplateError::ConditionalComponent for stateful groups, or TemplateError::InvalidDefinition for foreign, reused, or duplicate groups or empty branch keys. Input ownership and capacity errors are also reported.

Complexity: O(i + g + k) time and space for inputs i, groups g, and keys k.

§Examples

let mut b = TemplateBuilder::new();
let guard = b.parameter::<bool>("guard")?;
b.conditional(&[guard], |i| Ok(MatchExpr::cell(i[0])), vec![(vec![true], vec![])], vec![])?;

Source

pub fn conditional_factory<T, F, K>( &mut self, inputs: &[CellSlot], make: F, keys: K, branches: Vec<Vec<RelationshipSlot>>, default: Vec<RelationshipSlot>, ) -> Result<(), TemplateError>
where T: Any + PartialEq + 'static, F: Fn(&[CellId]) -> Result<MatchExpr> + 'static, K: Fn() -> Result<Vec<Vec<T>>> + 'static,

Registers conditional groups with fresh keys constructed once per instance.

Neither factory executes during preparation. Group ownership, uniqueness and relationship-only eligibility are checked before mutation. Keys follow native first-match semantics and must have one nonempty vector per declared branch.

§Errors

Reports invalid inputs/groups before mutation; reports failed factories, invalid key counts, empty keys or native conditional errors during construction.

Complexity: O(i + b + g) preparation for inputs i, branches b and groups g; construction adds factory costs and O(i + b + k + g + r) for keys k and expanded relationship members r.

§Examples

let mut b = adam_rs::TemplateBuilder::new();
let flag = b.parameter::<bool>("flag")?;
b.conditional_factory::<bool, _, _>(&[flag],
    |ids| Ok(adam_rs::MatchExpr::cell(ids[0])),
    || Ok(vec![vec![true]]), vec![vec![]], vec![])?;

Source

pub fn include( &mut self, child: Rc<SheetTemplate>, bindings: &[(&str, CellSlot)], ) -> Result<TemplateInclusion, TemplateError>

Appends a compact child-DAG edge with checked named bindings.

Binding and structural failures leave the builder unchanged. Immutable factories are shared, but every live instantiation creates fresh native methods. The returned single group slot represents all transitive relationships; only instantiation enumerates its distinct live members in inline order.

§Errors

Returns binding errors for unknown, missing, duplicate, aliased, foreign, or wrongly typed arguments; returns TemplateError::InvalidDefinition for a private out argument, or TemplateError::Capacity on reservation failure.

Complexity: Expected O(c + b) time and space for the child’s own local cells c and bindings b, independent of transitive expansion size.

§Examples

let child = Rc::new(TemplateBuilder::new().finish()?);
let mut parent = TemplateBuilder::new();
let included = parent.include(child, &[])?;
assert_eq!(included.relationships().len(), 1);

Source