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.

Syntax Definitions

Product: 

Class: 

Defines the recognition rules -- using literals, variable types, or complex syntax -- that the parser uses to identify and process input tokens.

Remarks

uCalc Patterns provide a high-level, token-based syntax for defining search criteria and text transformations. Unlike traditional string searches that match exact characters, or Regular Expressions (Regex) that rely on complex character-level syntax, uCalc patterns operate primarily on Tokens (words, numbers, symbols). This approach allows for more readable definitions that naturally respect word boundaries and structure.

A pattern string is the fundamental argument passed to methods such as Transformer.Pattern() and Transformer.FromTo(). These patterns define the criteria for Transformer.Find() and Transformer.Transform() operations.

Key Concepts & Syntax

Syntax ElementDescriptionExample
AnchorsLiteral text that must exist in the source string.Error Code:
VariablesNamed placeholders enclosed in curly braces. Captures variable content.{ErrorCode}
AlternativesVertical bars inside curly braces denote "OR" logic.{ High | Medium | Low }
OptionalsSquare brackets denote text that may or may not exist.[Detailed] Report
BackreferencesReusing a variable name enforces equality.<{tag}>...</{tag}>
Token ConstraintsColon followed by a number limits the capture length. Can be named or anonymous.{word:4} (named)
{4} (anonymous) captures exactly 4 tokens
Quoted TextCaptures an entire block of quoted text as a single unit using {@String} or {@s}.Test {@String} matches Test 'foo' or Test "bar"
RegEx EmbeddingSingle quotes inside curly braces allow raw Regex. Can be named or anonymous.{MyRegex:'[0-9]+'} (named)
{'[0-9]+'} (anonymous)

Crucial Syntax Rules

  1. Variable Naming & Spacing:To assign a variable name to a group, the name must immediately follow the opening curly brace without spaces.

    • Correct: {Type: Error | Warning} captures Error or Warning into the variable Type.
    • Incorrect: { Type: Error | Warning} matches the literal text Type: Error OR Warning. It does not create a variable named Type.

  2. Escaping Special Characters:Characters like [ and { have special meaning. To match them literally, enclose them in quotes.

    • Example: ['['{timestamp}']'] defines an optional section (outer brackets) containing a literal opening bracket (quoted '['), a variable, and a literal closing bracket.

Handling Quoted Text ({@String})

By default, uCalc is QuoteSensitive, meaning it treats a block of text enclosed in quotes (e.g., 'hello world' or "hello world") as a single token. The {@String} method (or shortcut {@s}) allows you to explicitly capture these blocks.

  • Syntax: {@String} or {@s} (string and s are case-insensitive).
  • Variable Assignment: Add a colon followed by the name (no spaces). E.g., {@s:MyText}.
  • Replacement Access:
    • {MyText} or {MyText(1)}: Returns the content inside the quotes.
    • {MyText(0)}: Returns the content including the surrounding quotes.

Why uCalc? (Comparative Analysis)

  • vs. Regular Expressions (Regex):
    • Readability: Regex is often described as "write-once, read-never" due to its dense, cryptic syntax (e.g., (?<=\s)\d+(?=\s)). uCalc patterns use human-readable tokens or methods (e.g., {@Number}).
    • Tokenization: Regex requires explicit boundaries (e.g., \bword\b). uCalc variables like {x} automatically respect token boundaries, preventing partial matches within words.
    • Backreferences: Matching an opening tag to a closing tag in Regex (e.g., <(\w+)>.*<\/\1>) is fragile and complex. In uCalc, simply reusing the variable name <{tag}>...<{/tag}> handles the logic automatically.
  • vs. Native Code (C#/C++):
    • Dynamic: uCalc patterns can be defined and modified at runtime, whereas native parsing logic is often hard-coded and requires recompilation.
  • vs. AI (LLMs):
    • Deterministic: uCalc patterns provide 100% deterministic matching. An LLM might hallucinate a match or miss a pattern based on probability; uCalc will always find exactly what is defined.

Examples

				
					using uCalcSoftware;

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

// Define the pattern first
t.FromTo("Temperature: {temp} C", "temperature: {@Eval: Double(temp) * 1.8 + 32} F");

// Perform the Transform() operation
Console.WriteLine(t.Transform("Here is the temperature: 22.5 C"));
				
			
Here is the temperature: 72.5 F
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

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

   // Define the pattern first
   t.FromTo("Temperature: {temp} C", "temperature: {@Eval: Double(temp) * 1.8 + 32} F");

   // Perform the Transform() operation
   cout << t.Transform("Here is the temperature: 22.5 C") << endl;
}
				
			
Here is the temperature: 72.5 F
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      
      '// Define the pattern first
      t.FromTo("Temperature: {temp} C", "temperature: {@Eval: Double(temp) * 1.8 + 32} F")
      
      '// Perform the Transform() operation
      Console.WriteLine(t.Transform("Here is the temperature: 22.5 C"))
   End Sub
End Module
				
			
Here is the temperature: 72.5 F
Using the same pattern variable multiple times in a pattern
				
					using uCalcSoftware;

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

// When a variable is used multiple times in a pattern,
// such as {tag} in this case, the matching text must be the same

t.FromTo("<{tag}> {words:2} {more} </{tag}>",
"tag={tag}, 2 words={words}, text={more}");

Console.WriteLine(t.Transform("<div>abc xyz more words<b>bold</b></div>").Text);
				
			
tag=div, 2 words=abc xyz, text=more words<b>bold</b>
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

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

   // When a variable is used multiple times in a pattern,
   // such as {tag} in this case, the matching text must be the same

   t.FromTo("<{tag}> {words:2} {more} </{tag}>",
   "tag={tag}, 2 words={words}, text={more}");

   cout << t.Transform("<div>abc xyz more words<b>bold</b></div>").Text() << endl;
}
				
			
tag=div, 2 words=abc xyz, text=more words<b>bold</b>
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      
      '// When a variable is used multiple times in a pattern,
      '// such as {tag} in this case, the matching text must be the same
      
      t.FromTo("<{tag}> {words:2} {more} </{tag}>",
      "tag={tag}, 2 words={words}, text={more}")
      
      Console.WriteLine(t.Transform("<div>abc xyz more words<b>bold</b></div>").Text)
   End Sub
End Module
				
			
tag=div, 2 words=abc xyz, text=more words<b>bold</b>
Optional part
				
					using uCalcSoftware;

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

t.FromTo("a [simple] test", "<{@Self}>");

Console.WriteLine(t.Transform("Is this a simple test, or a hard test, or just a test?"));
				
			
Is this <a simple test>, or a hard test, or just <a test>?
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

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

   t.FromTo("a [simple] test", "<{@Self}>");

   cout << t.Transform("Is this a simple test, or a hard test, or just a test?") << endl;
}
				
			
Is this <a simple test>, or a hard test, or just <a test>?
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      
      t.FromTo("a [simple] test", "<{@Self}>")
      
      Console.WriteLine(t.Transform("Is this a simple test, or a hard test, or just a test?"))
   End Sub
End Module
				
			
Is this <a simple test>, or a hard test, or just <a test>?
A simple "Hello World" transformation demonstrating variable capture.
				
					using uCalcSoftware;

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

// Define a rule to swap the name into a greeting
t.FromTo("Hello {name}", "Greetings, {name}!");
Console.WriteLine(t.Transform("Hello World"));
				
			
Greetings, World!
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

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

   // Define a rule to swap the name into a greeting
   t.FromTo("Hello {name}", "Greetings, {name}!");
   cout << t.Transform("Hello World") << endl;
}
				
			
Greetings, World!
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      
      '// Define a rule to swap the name into a greeting
      t.FromTo("Hello {name}", "Greetings, {name}!")
      Console.WriteLine(t.Transform("Hello World"))
   End Sub
End Module
				
			
Greetings, World!
Previous
Next