🎣 Capturing Text with Variables

At the heart of any parsing task is the need to find known text in order to extract unknown text. In uCalc's Transformer, this is done using two simple concepts: Anchors and Variables.

• Anchors are the literal, static text in your pattern that must exist in the source string. They act as guideposts for the parser. In the pattern User: {name}, the text User: is the anchor.
• Variables are named placeholders enclosed in curly braces {...} that capture the dynamic, unknown text. In User: {name}, the variable {name} captures whatever text follows the anchor.

How a Capture Works

By default, a variable like {data} is "smart lazy." It captures all text until it encounters one of three things:

1. The next anchor defined in your pattern.
2. A statement separator token (like a newline or semicolon).
3. The end of the string.

This behavior is incredibly powerful because it automatically respects the natural structure of your text without requiring complex lookaheads or non-greedy specifiers common in Regex.

Using Captured Variables

Once a variable captures text, you can re-insert it in the replacement string using the same {variableName} syntax. This allows you to reformat, wrap, or reorder the extracted data.

using uCalcSoftware;

var uc = new uCalc();

var t = new uCalc.Transformer();
t.FromTo("Log: {message}", "[LOG] - {message}");
Console.WriteLine(t.Transform("Log: System ready."));
// Output: [LOG] - System ready.

Backreferences: Enforcing Equality

One of the most powerful features is backreferencing. If you use the same variable name multiple times within the pattern string, uCalc enforces that the captured text for each instance must be identical. This is the key to matching balanced structures.

For example, the pattern <{tag}>{content}</{tag}> will correctly match <b>text</b> because the {tag} variable captures b in both places. It will not match <b>text</i>, preventing a common parsing error.

💡 Why uCalc? (Comparative Analysis)

vs. Regular Expressions

Regex uses capture groups (...) and backreferences like $1 or \1. uCalc's approach is superior for several reasons:

• Readability: Named variables like {user} are far more readable and maintainable than numeric indices like $1.
• Token Awareness: A uCalc variable like {word} automatically respects word boundaries. In Regex, you must manually add boundaries (\bword\b) to prevent partial matches inside other words.
• Safe Backreferences: As shown above, matching balanced tags is simple and intuitive in uCalc, while it is often complex and fragile in Regex.

vs. Native String Splitting

Using native functions like string.Split() is common but brittle.

• Positional Fragility: Split() gives you an array of results that you must access by a numeric index (e.g., parts[1]). If the input format changes slightly, your indices may be wrong, leading to runtime errors.
• Named Access: uCalc variables allow you to access captured data by a meaningful name, making your code more robust and self-documenting.