copperlace 0.4.2

Procedural text renderer for generative grammar configuration
Documentation

= Copperlace

Copperlace turns generative grammars into varied text.

Write the pieces once, then ask Copperlace to render a named rule. It can pick random options, remember a picked value for the rest of one result, fill in default values, and clean up text with processors such as article, possessive, pluralize, and sentence.

Use it for story snippets, game item descriptions, product blurbs, release notes, quest logs, or any place where hand-written text needs controlled variation.

== What It Does

Here is a tiny Copperlace configuration:

[source]

name = ["Mia", "Lina"] animal = ["owl", "raven"] mood = ["quiet", "restless"]

story = "{hero} traveled with {pet | article}. {hero} stayed {mood}." origin = "{% hero:name %}{% pet:animal %}{story}"

Rendering origin might produce:

[source,text]

Mia traveled with an owl. Mia stayed quiet.

Another render might produce:

[source,text]

Lina traveled with a raven. Lina stayed restless.

The important detail is consistency inside one result: {% hero:name %} chooses a name once, and later {hero} references reuse that same name.

When you need different entries from the same choice rule, add ! to draw without replacement for the current render:

[source]

name = ["Mia", "Lina"] duel = "{name!} faces {name!}"

Template expressions also support processor pipelines:

[source]

item = ["ancient key", "owl feather", "brass compass"] slug = "{item | slug}" description = "You found {item | article}."

This can render text like:

[source,text]

You found an ancient key.

The article processor chooses a or an, and slug turns text into a URL-friendly value such as ancient-key.

Arrays can also be traversed deterministically with a for block. Ordinary {item} calls still make random choices; iteration visits every authored entry in source order:

[source]

items = ["ancient key", "owl feather", "brass compass"] inventory = """{% for item in items %}{loop.index}. {item} {% endfor %}"""

Loops support nested arrays and object fields. See link:docs/configuration.adoc#_iteration[Iteration] for scoping, metadata, and weighted-entry behavior.

== License

Copyright 2026 Bruno Mahé.

Copperlace is licensed under the Apache License, Version 2.0. See link:LICENSE[LICENSE] for details.

== Packages

== Quick Start

If you have Rust installed, install the released CLI from crates.io:

[source,sh]

cargo install copperlace

If you do not want to build from source, download the prebuilt CLI archive for your platform from the latest link:https://github.com/bmahe/Copperlace/releases[GitHub Release]. The archive includes the copperlace executable, the native library, the README, and the license.

On Linux and macOS, extract the archive and run the executable:

[source,sh]

tar -xzf copperlace---cli.tar.gz cd copperlace---cli ./copperlace --help

On Windows, extract copperlace-<version>-windows-x86_64-cli.zip and run copperlace.exe.

Render a small configuration from standard input:

[source,sh]

cat <<'EOF' | copperlace render -c - name = ["Mia"] pet = ["owl"] origin = "{name} travels with {pet | article}." EOF

Output:

[source,text]

Mia travels with an owl.

From a repository checkout, run the bundled example:

[source,sh]

copperlace render -c examples/character_scene.conf

Example output:

[source,text]

Darcy's scholar found a brass compass in a moonlit bridge while running. The quiet discovery changed everything.

Your exact result may differ because the example contains random choices.

Using the same example file, render three results from one loaded configuration:

[source,sh]

copperlace render -c examples/character_scene.conf -n 3

Example output:

[source,text]

Mia's ranger found an hourglass in a forgotten observatory while searching. The quiet discovery changed everything. Azra's ranger found a brass compass in a moonlit bridge while searching. The restless discovery changed everything. Lina's scholar found an owl feather in a moonlit bridge while watching. The restless discovery changed everything.

Provide a starting value with --set. Here the hero is fixed to Mia, while the other values can still vary:

[source,sh]

copperlace render -c examples/character_scene.conf --set hero=Mia

Example output:

[source,text]

Mia's pilot found a brass compass in a forgotten observatory while running. The quiet discovery changed everything.

Check a configuration without rendering it:

[source,sh]

copperlace check -c examples/character_scene.conf

Output:

[source,text]

OK

Use - as the config path to read configuration from standard input:

[source,sh]

cat examples/character_scene.conf | copperlace render -c - cat examples/character_scene.conf | copperlace check -c -

More runnable examples live in link:examples/README.adoc[examples/], covering story text, game item cards, gendered pronouns, JSON item data, structured item data, product copy, release notes, and quest logs.

Object-valued rules render as structured JSON. The CLI formats structured JSON with tabs by default:

[source,sh]

copperlace render -c examples/structured_item.conf

Example output:

[source,json]

{ "description": "A moonstone compass once saved a lost caravan. It still releases 3 sparks when its bearer is searching in the dark.", "id": "rare-moonstone-compass-2nd", "level": "2", "name": "Rare Moonstone Compass", "properties": { "charges": "3", "effect": "spark", "material": "moonstone" }, "rarity": "rare", "tags": [ "rare", "compass", "spark" ], "type": "compass" }

Use --compact-json when one-line JSON is more convenient.

For development checks, run:

[source,sh]

make check

== Load Once, Render Many Times

For repeated renders, load the configuration once and call render multiple times. This avoids recompiling the rule set for each render.

Copperlace is available as a command-line tool and as libraries for Rust, Python, Java, browser JavaScript/WebAssembly, and Elixir.

=== Rust

Add Copperlace to a Rust project:

[source,sh]

cargo add copperlace

Or add it to Cargo.toml:

[source,toml]

copperlace = "0.4.2"

[source,rust]

use copperlace::Copperlace;

let copperlace = Copperlace::from_file("examples/character_scene.conf")?; let first = copperlace.render("origin")?; let second = copperlace.render("origin")?; let seeded = copperlace.render_with_context( "origin", [("hero".to_string(), "Mia".to_string())].into(), )?;

One-shot helpers are also available when repeated rendering is not needed.

=== Python

Install the Python package:

[source,sh]

pip install copperlace

[source,python]

from copperlace import Copperlace

with Copperlace.from_file("examples/character_scene.conf") as copperlace: first = copperlace.render("origin") second = copperlace.render("origin") seeded = copperlace.render("origin", {"hero": "Mia"})

with Copperlace.from_string( 'name = ["Mia"]\norigin = "{name | shout}"', {"shout": lambda value: value.upper()}, ) as copperlace: shouted = copperlace.render("origin")

Python also exposes RuleSet and one-shot render helpers. Wrapper errors are raised as CopperlaceError.

=== Java

Use the all-platform Maven Central dependency:

[source,xml]

Gradle Kotlin DSL:

[source,kotlin]

implementation("dev.mahe.copperlace:copperlace:0.4.2")

[source,java]

import dev.mahe.copperlace.Copperlace; import java.util.Map;

try (final Copperlace copperlace = Copperlace.fromFile("examples/character_scene.conf")) { final String first = copperlace.render("origin"); final String second = copperlace.render("origin"); final String seeded = copperlace.render("origin", Map.of("hero", "Mia")); }

try (final Copperlace copperlace = Copperlace.fromStringWithProcessors( "name = ["Mia"]\norigin = "{name | shout}"", Map.of("shout", value -> value.toUpperCase()))) { final String shouted = copperlace.render("origin"); }

Java also exposes RuleSet and one-shot render helpers. Copperlace and RuleSet implement AutoCloseable.

=== JS/TS

Install the npm package:

[source,sh]

npm install copperlace

[source,ts]

import { Copperlace } from "copperlace";

const response = await fetch("/config.conf"); const config = await response.text(); const copperlace = new Copperlace(config); const output = copperlace.render("origin"); const seeded = copperlace.renderWithContext("origin", { hero: "Mia" }); const custom = Copperlace.withProcessors(config, { shout: (value) => value.toUpperCase(), }).render("origin");

The published JS/TS package is generated with wasm-pack. Bundler output can be imported directly; direct browser ES module output must call the generated init function before using Copperlace. Browser code should load config text, then pass the string to new Copperlace(config). File-path APIs are not exported to WebAssembly.

=== Elixir

Add copperlace to your mix.exs dependencies:

[source,elixir]

defp deps do [{:copperlace, "~> 0.3"}] end

[source,elixir]

{:ok, copperlace} = Copperlace.from_string(~s(name = ["Mia"]\norigin = "Hello {name}")) {:ok, "Hello Mia"} = Copperlace.render(copperlace, "origin") {:ok, _} = Copperlace.render(copperlace, "origin", %{"name" => "Darcy"})

The NIF resolves the Copperlace native library from COPPERLACE_LIBRARY_PATH, the packaged priv/native/ directory, or the local rust-core build output. For source-tree development, run make rust-build first. The bang variants render!/4, render_inferred!/4, and render_structured!/4 raise Copperlace.Error on failure. The native handle is a NIF resource released automatically by the BEAM garbage collector; there is no explicit close/1. This release uses the builtin processor registry only.

== Documentation

The detailed behavior and configuration contract lives in docs/:

  • link:docs/index.adoc[Documentation index]
  • link:docs/getting-started.adoc[Getting started]
  • link:docs/cli.adoc[Command-line guide]
  • link:docs/capabilities.adoc[Capabilities]
  • link:docs/configuration.adoc[Configuration]
  • link:docs/processors.adoc[Processor reference]
  • link:docs/structured-output.adoc[Structured output]
  • link:docs/troubleshooting.adoc[Troubleshooting]
  • link:docs/errors.adoc[Errors and API behavior]
  • link:docs/packaging.adoc[Packaging and language wrappers]

== Project Layout

  • rust-core/ contains the renderer library, C ABI, and CLI.
  • python/ contains the Python wheel wrapper and ctypes bindings.
  • java/ contains the Java FFM wrapper and Maven packaging.
  • elixir/ contains the Elixir NIF wrapper and Hex packaging.
  • js/ contains JS/TS WebAssembly package documentation.
  • docs/ contains the behavior and configuration specification.
  • examples/ contains runnable rule examples.

== Development Commands

Use the root Makefile for normal workflows:

[source,sh]

make help # list available targets make check # Rust fmt check plus Rust, Python, Java, and Elixir tests make test # Rust, Python, Java, and Elixir tests make package # Python wheel, JS/TS wasm package, Java JARs, and Elixir Hex package make clean # remove generated Rust, Python, JS/TS, Java, and Elixir build outputs

Common targeted commands:

[source,sh]

make rust-build make rust-test make rust-cli make python-test make python-wheel make js-package make js-web make java-test make java-package make elixir-test make elixir-package

== Packaging Notes

Python wheels and Java native JARs are platform-specific because they include the Rust dynamic library. Python source distributions include the Rust sources needed to build that native library locally. JS/TS packages are generated from the same Rust renderer as WebAssembly and require wasm-pack. The Elixir Hex package ships a NIF shim that resolves the Rust dynamic library at runtime from COPPERLACE_LIBRARY_PATH, the packaged priv/native/ directory, or the local rust-core build output.

The simplest Java dependency is dev.mahe.copperlace:copperlace, which brings in the Java API plus all supported native platform artifacts. Users who only want one runtime platform can depend on a platform artifact such as dev.mahe.copperlace:copperlace-linux-x86_64, and advanced users can depend on dev.mahe.copperlace:copperlace-api directly. At runtime, the Java wrapper loads the native library from COPPERLACE_LIBRARY_PATH first, then from packaged native resources, then from local Rust build output for source-tree development.