🔀 Matching Alternatives (OR Logic)

In many text processing tasks, you need to find a pattern that could be one of several possibilities. For example, a status could be "OK", "Error", or "Pending". uCalc's Transformer handles this with the alternation operator: the vertical bar |.

This tutorial will guide you through using the | operator to create flexible, conditional patterns.

1. The Basics of Alternation

The core syntax is simple: enclose your choices within curly braces {}, separated by the | operator. The engine will match the first choice that allows the entire pattern to succeed.

using uCalcSoftware;

var uc = new uCalc();

// This pattern will match 'Status: OK', 'Status: Error', or 'Status: Pending'
"Status: { OK | Error | Pending }"

This is far more readable and maintainable than writing three separate rules.

2. Capturing the Choice

To make alternation useful, you often need to know which of the alternatives was matched. You can do this by assigning a variable name to the group.

using uCalcSoftware;

var uc = new uCalc();

// Captures 'OK', 'Error', or 'Pending' into the variable {status_val}
"Status: {status_val: OK | Error | Pending }"

You can then use {status_val} in your replacement string to reference the specific text that was matched.

3. 💎 Conditional Replacements

This is where alternation becomes truly powerful. You can create different outputs based on which variable was captured within an alternation. This is done using special replacement syntax:

• {var: ...}: The content after the colon is inserted only if {var} captured a value.
• {!var: ...}: The content after the colon is inserted only if {var} is empty (did not capture a value).

This is perfect for normalizing data from different formats into a single, consistent output, as shown in the practical example below.

4. ⚠️ Ordering Matters: The Precedence Pitfall

The engine evaluates alternatives from left to right and stops at the first successful match that allows the rest of the pattern to succeed. This can create a common trap if your alternatives overlap.

Consider matching "Apple Pie" and "Apple".

• Wrong Order: { Apple | Apple Pie }. When given the text "An Apple Pie", the engine will match "Apple" first and stop, because it's a valid match. It will never get a chance to test for "Apple Pie".
• Correct Order: { Apple Pie | Apple }. You must always place the longest and most specific alternatives first. This ensures they are tested before any shorter, partial matches.

See the internal test example for a clear demonstration of this pitfall.

5. Why uCalc? (Comparative Analysis)

• vs. Regex ((A|B|C)):
  • Readability: uCalc's syntax { Red | Blue } is cleaner and doesn't require the often-confusing parentheses-grouping of Regex (Red|Blue).
  • Token Awareness: A Regex alternation like (in|to) can match inside words like "bin" or "top" unless you explicitly add word boundaries (\b). uCalc defaults to whole-token matching, preventing these common false positives automatically.