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:

Strict unique calls can use processors and binding statements:

Repeated {rule!} calls share one used-entry set per rule name for the current render operation. The set resets for the next render. Exhaustion fails with ExhaustedUniqueChoice(rule), and using ! with a non-choice rule fails with UnsupportedUniqueChoice(rule). Uniqueness is by array entry index, not by the rendered text. Weighted unique choices sample only among unused entries using their original weights; if the remaining unused entries have no positive total weight, rendering fails.

The ! marker does not propagate through lazy context defaults. If {hero!} resolves context.hero = "{name}", the default is rendered and cached normally. Use context.hero = "{name!}" when the nested name draw should be unique.

Recursive rule references are disabled by default. If rule expansion re-enters a rule already on the current call stack, rendering fails with CircularRuleReference.

Callers may opt in to limited recursion with the render-time max_recursion_depth option, or CLI --max-recursion-depth <n>. A value of 0 keeps recursion disabled. Values greater than zero allow that many recursive re-entries for each rule name. When another recursive call would exceed the limit, that call returns an empty string.

Rendering origin with max_recursion_depth = 1 produces xx: the first recursive re-entry is rendered, and the next recursive call is cut off.

The limit applies to named rules and lazy context defaults. Initial context values and values bound earlier in the render still resolve before rules and do not consume recursion depth.

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.

{% for item in items %}…​{% endfor %} iterates an array in source order and concatenates the text rendered by the loop body. An empty array renders no text. Top-level arrays, dotted config paths, arrays from the special context object, and array fields of an enclosing loop element can be sources.

Scalar elements render through the loop variable, such as {member}. Object fields use dotted paths such as {group.name}. Array and object values are not renderable directly as text, but their fields and nested arrays can be used. Templates in an element or field are rendered on every reference, so repeated references may make different random choices.

Each iteration exposes an immutable loop object:

Nested loops temporarily shadow loop and restore the outer metadata when the inner loop finishes. The name loop cannot be used as the element variable. Loop elements and metadata cannot be overwritten.

Bindings created by {% alias:rule %} or {% alias:=rule %} inside the body are local to that iteration. They are visible to nested loops and the remainder of the current iteration, then discarded. Values from outer scopes remain visible and are restored afterward.

Name lookup is lexical. A visible string binding shadows a config array with the same name, so attempting to iterate it returns UnsupportedIterationSource. Weighted array entries are exposed exactly as authored: { value = red, weight = 2 } is an object addressed with {item.value} and {item.weight}. Iteration never applies weights.

Loops inside quoted text templates produce text only. In an object-valued structured rule, an unquoted loop block can instead occupy one array-entry position. Its body must contain one HOCON value, which is rendered once per source element and appended to that array. The emitted value may be a scalar, object, or nested array. Nested structured loops are allowed.

The block is recognized only outside quoted strings and comments. Text loops inside a string continue to concatenate their rendered body as before.

A HOCON substitution such as ${shared} in a structured loop body resolves against the fully merged configuration when it is loaded, retaining its value type. A Copperlace binding such as {item.name} renders for each iteration. The example emits value = 3 for both entries while name changes. The two forms can be used in nested loop bodies and included .conf files. The rest of the configuration follows normal HOCON substitution rules, including required and optional substitutions.

A structured array produced by a loop is output data; loop sources continue to be authored config arrays, context arrays, dotted paths, and arrays on outer loop elements. File-loaded .conf fragments can also contain structured loops, including fragments imported through include classpath(…​), include file(…​), or bare include "…​". Nested imports use the same behavior.

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.

Strict unique calls such as {mood!} select without replacement from the top-level array-backed mood rule for one render operation. Empty arrays still fail 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.