=begin rakudoc

Overview

Transformers apply molds to data.

Use this extension point when changing how transformation is performed rather than how data is walked, parsed, rendered, sourced, or stored.

To adjust transformer behavior:

• 1. Setup: decide whether the extension changes mold execution, copying, rewriting, wrappers, or validation.

• 2. Molds: preserve mold ordering and mold control behavior.

• 3. Copying: use Qwiratry's copy service for copy semantics.

• 4. Rewriting: use TreeRewrite only for intentional input mutation.

• 5. Wrappers: add cross-cutting behavior around transformer or mold execution.

• 6. Testing: test callable transformers, ordering, wrappers, copying, rewriting, and type checks.

Setup

Use transformer extensions when the extension changes transformation behavior. Do not use transformer extensions to support a new external data representation; use a format. Do not use transformer extensions to traverse a new data model; use a walker. Do not use transformer extensions to connect to a database or API; use a source/destination extension.

Molds

Mold Ordering

Molds are ordered by priority, specificity, and tie-breaker. Transformer extensions that add ordering metadata or produce molds programmatically must preserve deterministic ordering.

If ordering cannot be made deterministic, Qwiratry throws X::Qwiratry::MoldOrderingConflict. This usually means two or more molds have equal priority, specificity, and tie-breaker values. Extensions that generate molds or add ordering metadata should preserve this failure mode.

Mold Control

Qwiratry::Mold::NextMold lets a mold decline the current match and continue with the next matching mold.

Copying

Use Qwiratry::Transformer::Copy when an extension needs to clone input before rewriting or needs a standard way to copy positional and associative structures.

my $copy-service = Qwiratry::Transformer::Copy.instance;
my $clone = $copy-service.deepcopy($node);

Rewriting

TreeRewrite marks a transformer as able to mutate or replace nodes during transformation. Use this only when the extension intentionally changes the input tree or node graph.

use Qwiratry::Transformer::TreeRewrite;

transformer MyRewrite does TreeRewrite {
    mold TOP do {
        make $_;
    }
}

Wrappers

Transformer slang supports wrappers for transformer execution, mold matching, and mold actions. Use wrappers when the extension needs to add cross-cutting behavior around existing molds rather than replacing the mold system.

Testing

Add tests that prove:

• Callable transformers still work.

• Mold ordering remains deterministic.

• Wrapper behavior applies at the intended layer.

• Copy and rewrite behavior does not mutate data accidentally.

• X::Qwiratry::MoldOrderingConflict is thrown for unresolved ordering conflicts.

• X::Qwiratry::TypeCheck is thrown for result type constraint failures.

Reference Material

Main Types

• Transformer

Base class for transformer objects and the runtime behavior behind the transformer declarator.

• Qwiratry::Mold::Mold

Runtime representation of one mold rule: match logic, action logic, and ordering metadata.

• Qwiratry::Mold::NextMold

Control tool for declining the current mold and continuing with the next matching mold.

• Qwiratry::Transformer::Copy

Copy service for shallow and deep copying transformable nodes.

• Qwiratry::Transformer::TreeRewrite::TreeRewrite

Marker role for transformers that rewrite input structures in place.

• X::Qwiratry::MoldOrderingConflict

Thrown when mold order cannot be made deterministic.

• X::Qwiratry::TypeCheck

Thrown when a transformer or mold result does not match a declared return type constraint.

=end rakudoc