uCalc API Version: 2.1.3-preview.2 Released: 6/17/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.

Matching by Token Category

Product: 

Class: 

Explains how to use token category matchers like {@Number} and {@String} to create powerful, readable, and context-aware patterns.

Remarks

🎯 Matching by Token Category

While matching literal text (like "Hello") is useful, the real power of the Transformer comes from matching by token category. Instead of looking for a specific value, you can create a pattern that looks for a type of content, such as "any number," "any string," or "any word."

This is the key feature that makes the Transformer structurally aware and significantly more powerful than regular expressions for parsing code and structured data.

💡 Why Match by Category? (The Advantage over Regex)

  1. Readability: A pattern to find a number is simply {@Number}. The equivalent regex can be long and cryptic, like [-+]?[0-9]*\.?[0-9]+([eE][-+]?[0-9]+)?.

  2. Safety & Context-Awareness: The uCalc tokenizer runs first, breaking text into meaningful units. It knows that "123" is a single string token. A rule to find {@Number} will not match the 123 inside the string, preventing the accidental corruption of string literals—a common and dangerous pitfall of using regex for code transformation.

  3. Maintainability: Token definitions are centralized. If you decide to add support for a new number format (like hexadecimal 0x...), you only need to update the number token definition once using Tokens.Add(). All existing {@Number} patterns across your entire application will automatically support the new format without any changes.

Syntax

The syntax uses an @ symbol inside curly braces {}.

  • Match Only: {@Category} matches any token of that category but does not capture it.
  • Match & Capture: {@Category:variableName} matches and captures the token's text into a variable for use in a replacement string.
  • Negation: {!Category:var} captures any token that is not in the specified category.

Category names are case-insensitive, so {@Number} and {@number} are equivalent.

Common Categories

CategoryDescription
{@Alphanumeric}Matches words and identifiers (e.g., Result, x1). Shortcut: {@Alpha}.
{@Number}Matches integers or decimals (e.g., 42, 3.14).
{@String}Matches text inside quotes (e.g., "Hello"). Shortcut: {@s}.
{@Literal}Matches any data value (a Number OR a String).
{@Whitespace}Matches horizontal space or tab characters. Shortcut: {@ws}.
{@Newline}Matches line break characters. Shortcut: {@nl}.
{@Bracket}Matches an opening bracket like (, [, or {.

Examples

A simple example demonstrating how to find and wrap all numeric values in a string.
				
					using uCalcSoftware;

var uc = new uCalc();
var t = new uCalc.Transformer();
// Define a rule to find any number and wrap it in 'Num(...)'
t.FromTo("{@Number:n}", "Num({n})");

Console.WriteLine(t.Transform("var x = 10.5; var y = 20;"));
				
			
var x = Num(10.5); var y = Num(20);
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   uCalc::Transformer t;
   // Define a rule to find any number and wrap it in 'Num(...)'
   t.FromTo("{@Number:n}", "Num({n})");

   cout << t.Transform("var x = 10.5; var y = 20;") << endl;
}
				
			
var x = Num(10.5); var y = Num(20);
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t As New uCalc.Transformer()
      '// Define a rule to find any number and wrap it in 'Num(...)'
      t.FromTo("{@Number:n}", "Num({n})")
      
      Console.WriteLine(t.Transform("var x = 10.5; var y = 20;"))
   End Sub
End Module
				
			
var x = Num(10.5); var y = Num(20);
Previous
Next