Note: This feature is currently in the design phase and is not yet implemented in the production engine.

⚙️ Creating a Setup Pass for State Management

The Setup() method creates a dedicated, high-priority initialization pass (Pass 0) for a Transformer. This pass executes a given expression once at the very beginning of each Transform() operation, making it the ideal mechanism for resetting stateful variables before the main transformation rules are applied.

How It Works: The {@All} and {@Exec} Shortcut

Setup() is a convenient shortcut for a common multi-pass pattern. A call like:t.Setup("counter = 0; total = 0;");

is equivalent to creating a new pass and defining a special rule:t.Pass().FromTo("{@All}", "{@Self}{@Exec: counter = 0; total = 0;}");

This works because:

1. Pass(): Creates a new pass. If it's the first one, it becomes Pass 0.
2. {@All}: Matches the entire input text as a single, efficient block. It doesn't perform a costly token-by-token search, making it a very fast way to trigger a one-time action.
3. {@Self}: Re-inserts the original text unmodified.
4. {@Exec}: Executes the setup expression for its side effects (e.g., setting variables) without inserting any text into the output.

After using Setup(), subsequent rules should be added to a new pass (created with Pass()) to ensure they run after the setup pass.

Primary Use Case: Resetting State Between Transform() Calls

Setup() is essential when you use the same transformer instance to process multiple, independent text blocks. Without a setup pass, state from one transformation (like an incremented counter) would leak into the next.

💡 Why uCalc? (Comparative Analysis)

In a typical programming workflow, you would manage state manually in your host application code.

Manual Approach (C#):

var t = uc.NewTransformer();uc.DefineVariable("counter = 0");t.FromTo("item", "{@Eval: counter++}");foreach (var textBlock in myTextBlocks){    uc.Eval("counter = 0"); // Manual reset before each transform    var result = t.Transform(textBlock);    // ...}

This approach mixes the state management logic with the application's control flow.

The uCalc Setup() Advantage:uCalc's Setup() method is declarative. It moves the state initialization logic into the transformer's definition.

var t = uc.NewTransformer();t.Setup("counter = 0"); // State reset is now part of the transformervar mainPass = t.Pass();mainPass.FromTo("item", "{@Eval: counter++}");foreach(var textBlock in myTextBlocks) {{    var result = t.Transform(textBlock); // Reset happens automatically    // ...}

This creates a self-contained, stateful component that is cleaner, more reusable, and less prone to errors, as the responsibility for resetting state is handled automatically by the transformer itself.