Copperlace Configuration

The config root must be an object. Any non-object root fails compilation with InvalidConfigRoot.

Top-level keys become named rules unless the key is context and its value is an object. Path keys and nested objects can define dotted rule names.

Each top-level rule can be rendered directly by passing its key to RuleSet::render_rule. Dotted leaves can also be rendered directly, such as RuleSet::render_rule("name.first").

The selected top-level rule’s value shape also determines whether it is a text or structured render target:

See Structured output for examples and CLI mode inference.

When top-level context is an object, its entries become lazy default values used by template references. They are not inserted into the normal rule table, but they can still be rendered by name through render_rule.

If top-level context is not an object, it is treated as a normal rule named context.

Callers may also pass initial render context values to a render call through Rust APIs, wrapper render overloads, JS/WASM context methods, or CLI --set key=value. Initial context values are strings, resolve before config-defined context defaults and named rules, and do not persist after the render finishes.

Strings are parsed as templates. Each {…​} section becomes a render-time expression that appends text to the output. Each {% …​ %} section becomes a render-time statement that may update render state but appends no text. All other text remains literal.

Literal expression braces can be escaped in template text with \{ and \}. Literal statement delimiters can be escaped with \{% and %\}. In normal quoted strings, escape the backslash itself as \\{, \\}, \\{%, or %\\}. In triple-quoted strings, write \{, \}, \{%, or %\} directly.

Supported expressions:

Supported statements:

Binding statements can also use processors. {% alias:rule | uppercase %} stores the processed result under alias; {% alias:=rule | uppercase %} overwrites alias with the processed result.

Overwrite bindings are parsed before bind-if-missing bindings, so {% alias:=rule %} is distinct from {% alias:rule %}.

Supported builtin processors are:

The article processor prefixes the rendered value with a or an using English heuristics. It preserves the rendered value as-is, so use trim first when surrounding whitespace should be ignored.

The past_tense processor converts one verb token to past tense using regular spelling rules and common irregular verbs. It preserves surrounding whitespace but returns an error for blank values or multi-word phrases.

The pluralize processor converts one noun token to plural form using regular spelling rules and common irregular nouns. It preserves surrounding whitespace but returns an error for blank values or multi-word phrases.

The singularize processor converts one plural noun token to singular form using common reverse spelling rules and irregular nouns. It preserves surrounding whitespace but returns an error for blank values or multi-word phrases.

The possessive processor adds an English possessive suffix to one token. It preserves surrounding whitespace but returns an error for blank values or multi-word phrases.

The present_participle processor converts one verb token to its -ing form. It preserves surrounding whitespace but returns an error for blank values or multi-word phrases.

The ordinal processor adds an English ordinal suffix to one integer token. It preserves surrounding whitespace but returns an error for blank, multi-word, or non-integer values.

The sentence processor capitalizes the first alphabetic character in the rendered string and leaves the rest unchanged.

The quote processor wraps the rendered string in ASCII double quotes and escapes internal double quotes and backslashes.

The slug processor lowercases rendered text, trims it, converts runs of non-alphanumeric characters to hyphens, removes apostrophes, and strips leading or trailing hyphens.

Arrays are random choices. The selected element is rendered using the same value rules as a top-level config value.

Arrays may contain weighted entries. A weighted entry is an object with only value and weight fields. The value field is rendered using the same rules as any other array element, and weight must be a finite non-negative number. If any array entry is weighted, plain entries in the same array receive weight 1.0.

Individual zero weights are accepted, but a weighted choice must have at least one entry with a positive weight. Invalid weighted choices fail during RuleSet construction.

An empty array is accepted during RuleSet construction, but rendering it fails with EmptyChoice.

Inside an object-valued structured rule, arrays preserve their shape instead of acting as random choices. Top-level list structured rendering is not supported in v1; top-level list rules remain text choices.

Arrays inside object-valued structured rules are preserved for structured rendering. When a nested array looks like a malformed weighted text choice, it is still accepted as structured data; rendering that array as a dotted text rule fails with UnsupportedValue("array").

Scalar values that are not strings, arrays, or objects are converted to strings using the parsed value’s to_string behavior.

Objects can organize rules into dotted names. Path keys and nested object syntax are equivalent, so name.first = ["Mia"] and name { first = ["Mia"] } both define a rule named name.first.

Object parents are not directly renderable. Rendering name in the example above fails with UnsupportedValue("object").

Object-valued top-level rules are structured render targets. Structured rendering preserves nested objects and arrays, while string leaves still use normal templates, rule calls, processors, bindings, context defaults, and initial context values.

Objects are also supported as the special top-level context value and as weighted choice entries inside arrays. Nested context values use the same dotted name behavior.