uCalc API Version: 5.7.0-preview.1 Released: 7/30/2026

Warning

uCalc API Preview Release Notice:This preview documentation describes the intended behavior of the API. It is not fully accurate or complete.The current preview build contains incomplete features, unoptimized performance, and is subject to breaking changes.Use of the preview version in your production code is not recommended.

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

Converting from Celsius to Fahrenheit with the Transformer

ID: 174

See: {@Eval}, Syntax Definitions 
				
					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
Explore 600+ other examples
				
					#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
Explore 600+ other examples
				
					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
Explore 600+ other examples
Using the same pattern variable multiple times in a pattern

ID: 199

See: Syntax Definitions, Replacement, Variables and Anchors 
				
					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>
Explore 600+ other examples
				
					#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>
Explore 600+ other examples
				
					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>
Explore 600+ other examples
Optional part

ID: 197

See: Syntax Definitions, Optional parts 
				
					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>?
Explore 600+ other examples
				
					#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>?
Explore 600+ other examples
				
					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>?
Explore 600+ other examples
A simple "Hello World" transformation demonstrating variable capture.

ID: 224

See: Syntax Definitions 
				
					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!
Explore 600+ other examples
				
					#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!
Explore 600+ other examples
				
					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!
Explore 600+ other examples