Copperlace

Errors and API Behavior

This page documents the current Rust renderer entry points and error behavior. The Rust API is exported from rust-core/src/lib.rs; the CLI, C ABI, Python wrapper, and Java wrapper are thin layers around that library. See Packaging and language wrappers for wrapper packaging and runtime loading details.

Entry Points

Copperlace::from_str(config) / Copperlace::from_file(path)

Parse and compile configuration input once into a reusable renderer for repeated calls to Copperlace::render.

Copperlace::render(&self, rule_name: &str) → Result<String, RenderError>

Starts a fresh render for rule_name using the previously loaded config.

Copperlace::render_with_context(&self, rule_name, context)

Starts a fresh render with initial context values.

Copperlace::render_inferred(&self, rule_name)

Starts a fresh render and returns text for string-valued or list-valued rules, or formatted JSON for object-valued rules.

Copperlace::render_inferred_with_context(&self, rule_name, context)

Starts an inferred render with initial context values.

Copperlace::render_structured(&self, rule_name)

Starts a fresh structured render for an object-valued rule and returns a CopperlaceValue.

Copperlace::render_structured_with_context(&self, rule_name, context)

Starts a fresh structured render with initial context values.

RuleSet::from_config(config) → Result<RuleSet, RenderError>

Compiles a parsed root value into named render rules and context defaults. The root must be an object.

RuleSet::render_rule(&self, rule_name: &str) → Result<String, RenderError>

Starts a fresh render for rule_name. Each call gets a new render context and a new thread-local random number generator.

RuleSet::render_rule_with_context(&self, rule_name, context)

Starts a fresh render with initial context values.

RuleSet::render_rule_inferred(&self, rule_name)

Starts a fresh render and returns text for string-valued or list-valued rules, or formatted JSON for object-valued rules.

RuleSet::render_rule_inferred_with_context(&self, rule_name, context)

Starts an inferred render with initial context values.

RuleSet::render_rule_structured(&self, rule_name)

Starts a fresh structured render for an object-valued rule and returns a CopperlaceValue.

RuleSet::render_rule_structured_with_context(&self, rule_name, context)

Starts a fresh structured render with initial context values.

render_config_rule(config, rule_name) → Result<String, RenderError>

Convenience function that compiles the config and renders one rule.

render_config_rule_structured(config, rule_name) → Result<CopperlaceValue, RenderError>

Convenience function that compiles the config and renders one object-valued rule as a structured value.

ruleset_from_str / ruleset_from_file

Parse configuration input and compile it into a RuleSet.

render_str / render_file

Parse configuration input and render one rule in a single call.

render_str_inferred / render_file_inferred

Parse configuration input and render one rule in a single call, returning text or formatted JSON based on the selected rule shape.

RuleSet::from_config_with_processors(config, processors)

Compiles a config with the builtin processor registry plus Rust-provided custom processors. Custom processor names override builtin names when they collide.

Wrapper processor constructors

The C ABI, Python, Java, and JS/WASM wrappers also expose construction-time custom processor registration. Callback failures are reported as ProcessorError.

CLI

The package builds a copperlace binary:

copperlace render --config <path>
copperlace render --config -
copperlace render -c <path> -r <name> --count <n> --set name=Mia
copperlace render -c <path> -r <object-rule> --compact-json
copperlace check --config -

The CLI renders origin when --rule is omitted. Passing - as the render or check config path reads configuration from standard input. It writes rendered output, help, version text, and successful check output to stdout. Parse, render, check, and argument errors are written to stderr and return a nonzero exit code.

For render commands, the CLI infers text versus structured JSON output from the selected rule shape. Object-valued rules render as formatted JSON with tab indentation by default. --compact-json selects compact JSON and is valid only for object-valued structured rules.

C ABI

The dynamic library exposes an opaque ruleset handle API:

  • copperlace_ruleset_from_file

  • copperlace_ruleset_from_file_with_processors

  • copperlace_ruleset_from_string

  • copperlace_ruleset_from_string_with_processors

  • copperlace_ruleset_render

  • copperlace_ruleset_render_with_context

  • copperlace_ruleset_render_inferred

  • copperlace_ruleset_render_inferred_with_context

  • copperlace_ruleset_render_structured_json

  • copperlace_ruleset_render_structured_json_with_context

  • copperlace_processor_result_set_output

  • copperlace_processor_result_set_error

  • copperlace_ruleset_free

  • copperlace_string_free

Returned strings are allocated by Copperlace and must be released with copperlace_string_free. Ruleset handles must be released with copperlace_ruleset_free.

Custom processor callbacks are owned by the caller and must remain valid until the ruleset handle is freed.

Render Context

Each render has an isolated context. Bindings created by {% alias:rule %} and lazy values created from top-level context defaults live only for the current render_rule call.

Callers may provide initial context values for a render through Rust, copperlace_ruleset_render_with_context, Python and Java render overloads, JS/WASM context methods, or CLI --set key=value. Initial context values resolve before top-level context defaults and named rules. They are scoped to one render call and do not persist on the ruleset.

Bind-if-missing statements are idempotent within a render. If {% alias:rule %} runs after alias already exists, it leaves the existing value unchanged and does not render rule. Overwrite statements with {% alias:=rule %} always render rule and replace the value.

The renderer does not currently expose seeded randomness or deterministic replay.

Error Cases

UnknownRule(String)

Returned when a template reference or requested render rule cannot be resolved from the current render context, top-level context defaults, or named rules.

UnknownProcessor(String)

Returned when a template pipeline references a processor that is not registered.

ProcessorError { processor, message }

Returned when a registered processor rejects a rendered value.

InvalidExpression(String)

Returned when a template expression or statement is malformed, such as {name | }, { | uppercase}, or {% name %}, or when template text contains an unmatched raw {, }, {%, or %}.

EmptyChoice

Returned when rendering an array value with no elements.

InvalidWeightedChoice(String)

Returned during RuleSet construction when a weighted choice entry is malformed, has a missing or invalid weight, or has no positive-weight entries.

CircularRuleReference(Vec<String>)

Returned when rule expansion re-enters a rule already on the call stack. The vector contains the detected path, including the repeated final rule name.

UnsupportedValue(String)

Returned when rendering a value type that compiled to an unsupported node. The current unsupported value types are "object" for object parents such as name when only dotted leaves such as name.first are renderable, and "array" for nested arrays that are valid structured data but not valid dotted text-choice rules.

UnsupportedStructuredTarget(String)

Returned when structured rendering is requested for a target that is not an object-valued rule.

JsonSerialization(String)

Returned when a structured value cannot be serialized to JSON.

InvalidConfigRoot

Returned by RuleSet::from_config when the provided value root is not an object.

Current Non-Goals

The current implementation does not define these as supported behavior:

  • Seeded or deterministic random output.

  • Rendering object parents directly.