uCalc API Version: 2.1.3-preview.2 Released: 6/16/2026

Warning

uCalc API Preview Release Notice:The documentation describes the intended behavior of the API. The current preview build contains incomplete features, unoptimized performance, and is subject to breaking changes.

Alternation

Product: 

Class: 

Defines multiple acceptable token sequences for a single position in a pattern using the '|' (OR) operator.

Remarks

Alternation allows you to define a set of choices for a single position in your pattern. The parser will attempt to match each choice in order until one succeeds. It uses the vertical bar | as the "OR" operator.

Syntax: { Option1 | Option2 | Option3 }

Key Concepts

  • Left-to-Right Precedence: The parser is "greedy" and evaluates alternatives from left to right. It stops at the first successful match that allows the rest of the pattern to also match. If you have overlapping alternatives (e.g., Apple and Apple Pie), you must list the longest and most specific one first to ensure it gets matched correctly. See the internal test example for a demonstration of this common pitfall.

  • Grouping and Scope: The curly braces {...} define the scope of the alternation. Any anchors outside the braces apply to the entire group. For example, in Set { On | Off }, the Set anchor is required, followed by either On or Off.

  • Tokens vs. Sub-Patterns: Alternatives can be single tokens (e.g., { Red | Blue }) or more complex sequences of tokens, which can themselves contain groups (e.g., { Color | {Size {Big | Small}} }).

  • Alternation with "Nothing": To create a choice that includes an empty option (e.g., "match A or B or nothing"), combine alternation with an Optional parts block: [{ A | B }].

💎 Conditional Replacements with Alternation

When an alternation contains multiple branches that capture different variables, only the variables in the branch that successfully matches will contain a value. The variables from all other branches will be empty. This allows you to use conditional replacement blocks to create a dynamic output based on which alternative was matched.

SyntaxNameBehavior
{var: ...}Positive ConditionThe content after the colon is inserted only if {var} captured a value.
{!var: ...}Fallback ContentThe content after the colon is inserted only if {var} is empty (did not capture a value).

This is extremely powerful for normalizing different input formats into a single, consistent output format.

Comparative Analysis: Why uCalc?

  • 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.

  • vs. C# Switch/Case:

    • Conciseness: Handling multiple string alternatives in native C# code often requires a switch statement or a List.Contains() check after parsing. uCalc handles the branching logic directly within the pattern string, making the code more declarative.

Examples

A succinct example matching one of several status keywords.
				
					using uCalcSoftware;

var uc = new uCalc();
var t = new uCalc.Transformer();
t.FromTo("Status: { OK | Error | Pending }", "Found Valid Status");

Console.WriteLine(t.Transform("Status: OK"));
Console.WriteLine(t.Transform("Status: Error"));
Console.WriteLine(t.Transform("Status: Fail"));
				
			
Found Valid Status
Found Valid Status
Status: Fail
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   uCalc::Transformer t;
   t.FromTo("Status: { OK | Error | Pending }", "Found Valid Status");

   cout << t.Transform("Status: OK") << endl;
   cout << t.Transform("Status: Error") << endl;
   cout << t.Transform("Status: Fail") << endl;
}
				
			
Found Valid Status
Found Valid Status
Status: Fail
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t As New uCalc.Transformer()
      t.FromTo("Status: { OK | Error | Pending }", "Found Valid Status")
      
      Console.WriteLine(t.Transform("Status: OK"))
      Console.WriteLine(t.Transform("Status: Error"))
      Console.WriteLine(t.Transform("Status: Fail"))
   End Sub
End Module
				
			
Found Valid Status
Found Valid Status
Status: Fail
A practical example normalizing various boolean representations to a standard format.
				
					using uCalcSoftware;

var uc = new uCalc();
var t = new uCalc.Transformer();
// Normalize 'true-like' and 'false-like' values
t.FromTo("{ True | Yes | On }", "TRUE");
t.FromTo("{ False | No | Off }", "FALSE");

Console.WriteLine(t.Transform("System is On and Power is False"));
Console.WriteLine(t.Transform("Access: Yes, Admin: No"));
				
			
System is TRUE and Power is FALSE
Access: TRUE, Admin: FALSE
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   uCalc::Transformer t;
   // Normalize 'true-like' and 'false-like' values
   t.FromTo("{ True | Yes | On }", "TRUE");
   t.FromTo("{ False | No | Off }", "FALSE");

   cout << t.Transform("System is On and Power is False") << endl;
   cout << t.Transform("Access: Yes, Admin: No") << endl;
}
				
			
System is TRUE and Power is FALSE
Access: TRUE, Admin: FALSE
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t As New uCalc.Transformer()
      '// Normalize 'true-like' and 'false-like' values
      t.FromTo("{ True | Yes | On }", "TRUE")
      t.FromTo("{ False | No | Off }", "FALSE")
      
      Console.WriteLine(t.Transform("System is On and Power is False"))
      Console.WriteLine(t.Transform("Access: Yes, Admin: No"))
   End Sub
End Module
				
			
System is TRUE and Power is FALSE
Access: TRUE, Admin: FALSE
Alternative parts
				
					using uCalcSoftware;

var uc = new uCalc();
var t = uc.NewTransformer();

t.FromTo("This is a {adjective: simple | small | nice } test",
"The adjective in '{@Self}' is: {adjective}.");

Console.WriteLine(t.Transform("This is a test"));
Console.WriteLine(t.Transform("This is a simple test"));
Console.WriteLine(t.Transform("This is a small test"));
Console.WriteLine(t.Transform("This is a nice test"));
Console.WriteLine(t.Transform("This is a random test"));

				
			
This is a test
The adjective in 'This is a simple test' is: simple.
The adjective in 'This is a small test' is: small.
The adjective in 'This is a nice test' is: nice.
This is a random test
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto t = uc.NewTransformer();

   t.FromTo("This is a {adjective: simple | small | nice } test",
   "The adjective in '{@Self}' is: {adjective}.");

   cout << t.Transform("This is a test") << endl;
   cout << t.Transform("This is a simple test") << endl;
   cout << t.Transform("This is a small test") << endl;
   cout << t.Transform("This is a nice test") << endl;
   cout << t.Transform("This is a random test") << endl;

}
				
			
This is a test
The adjective in 'This is a simple test' is: simple.
The adjective in 'This is a small test' is: small.
The adjective in 'This is a nice test' is: nice.
This is a random test
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      
      t.FromTo("This is a {adjective: simple | small | nice } test",
      "The adjective in '{@Self}' is: {adjective}.")
      
      Console.WriteLine(t.Transform("This is a test"))
      Console.WriteLine(t.Transform("This is a simple test"))
      Console.WriteLine(t.Transform("This is a small test"))
      Console.WriteLine(t.Transform("This is a nice test"))
      Console.WriteLine(t.Transform("This is a random test"))
      
   End Sub
End Module
				
			
This is a test
The adjective in 'This is a simple test' is: simple.
The adjective in 'This is a small test' is: small.
The adjective in 'This is a nice test' is: nice.
This is a random test
Matching one of several keywords.
				
					using uCalcSoftware;

var uc = new uCalc();
var t = uc.NewTransformer();
t.FromTo("Status: { OK | Error | Pending }", "Found Status");

Console.WriteLine(t.Transform("Status: OK"));    // Output: Found Status
Console.WriteLine(t.Transform("Status: Error")); // Output: Found Status
Console.WriteLine(t.Transform("Status: Fail"));  // No Match (Output unchanged)
				
			
Found Status
Found Status
Status: Fail
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto t = uc.NewTransformer();
   t.FromTo("Status: { OK | Error | Pending }", "Found Status");

   cout << t.Transform("Status: OK") << endl;    // Output: Found Status
   cout << t.Transform("Status: Error") << endl; // Output: Found Status
   cout << t.Transform("Status: Fail") << endl;  // No Match (Output unchanged)
}
				
			
Found Status
Found Status
Status: Fail
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      t.FromTo("Status: { OK | Error | Pending }", "Found Status")
      
      Console.WriteLine(t.Transform("Status: OK"))    '// Output: Found Status
      Console.WriteLine(t.Transform("Status: Error")) '// Output: Found Status
      Console.WriteLine(t.Transform("Status: Fail"))  '// No Match (Output unchanged)
   End Sub
End Module
				
			
Found Status
Found Status
Status: Fail
Parsing boolean values that might be represented differently.
				
					using uCalcSoftware;

var uc = new uCalc();
var t = uc.NewTransformer();
// Normalize "True/Yes/On" to "TRUE" and "False/No/Off" to "FALSE"
t.FromTo("{ True | Yes | On }", "TRUE");
t.FromTo("{ False | No | Off }", "FALSE");

Console.WriteLine(t.Transform("System is On"));    // Output: System is TRUE
Console.WriteLine(t.Transform("Power is False"));  // Output: Power is FALSE
				
			
System is TRUE
Power is FALSE
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto t = uc.NewTransformer();
   // Normalize "True/Yes/On" to "TRUE" and "False/No/Off" to "FALSE"
   t.FromTo("{ True | Yes | On }", "TRUE");
   t.FromTo("{ False | No | Off }", "FALSE");

   cout << t.Transform("System is On") << endl;    // Output: System is TRUE
   cout << t.Transform("Power is False") << endl;  // Output: Power is FALSE
}
				
			
System is TRUE
Power is FALSE
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      '// Normalize "True/Yes/On" to "TRUE" and "False/No/Off" to "FALSE"
      t.FromTo("{ True | Yes | On }", "TRUE")
      t.FromTo("{ False | No | Off }", "FALSE")
      
      Console.WriteLine(t.Transform("System is On"))    '// Output: System is TRUE
      Console.WriteLine(t.Transform("Power is False"))  '// Output: Power is FALSE
   End Sub
End Module
				
			
System is TRUE
Power is FALSE
Previous
Next