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.

uCalc Transformer

Product: 

Transformer Library

Class: 

An overview of uCalc's token-aware text transformation engine, which uses declarative patterns to find, replace, and restructure text.

Remarks

🧠 The uCalc Transformer

The uCalc Transformer is a powerful, token-aware engine for finding, replacing, and restructuring text. It serves as a more intelligent and safer alternative to traditional tools like Regular Expressions (Regex), especially when working with structured data such as source code, configuration files, or markup languages.

While the uCalc.String class is ideal for simple, fluent, "one-liner" manipulations, the Transformer is the tool of choice for building robust, rule-based systems. It is the engine that powers static analysis, code refactoring, transpilation, and complex data extraction tasks in uCalc.

Core Concepts: Beyond Simple String Replacement

The Transformer's power comes from a few fundamental concepts that set it apart from character-based tools.

1. Token-Awareness: The Key to Safety

This is the most critical difference between the Transformer and Regex. Before any matching occurs, the Transformer's tokenizer (or lexer) breaks the input string into a stream of meaningful tokens: words, numbers, operators, string literals, and comments.

  • Regex sees a flat stream of characters.
  • The Transformer sees a structured stream of tokens.

This structural awareness prevents the most common and dangerous bugs associated with using Regex for code manipulation, such as accidentally changing text inside a string literal or a comment. For a detailed comparison, see the Structural Awareness (Tokens vs. Regex) topic.

2. Declarative, Readable Patterns

Transformer rules are defined using a declarative pattern syntax that is designed to be human-readable. Instead of cryptic regex like (?<=\s)\w+(?=\s), you use clear, token-based patterns.

  • Anchors: Literal text like ID:.
  • Variables: Capture dynamic content with {name}.
  • Token Categories: Match types of content, such as {@Number} or {@String}.

This approach makes rules easier to write, debug, and maintain.

3. Intelligent Replacements

Replacements are not limited to static text. The replacement string can include:

  • Backreferences to captured variables (e.g., {name}).
  • Conditional logic to include text only if an optional variable was matched.
  • Embedded expressions using {@Eval} to perform calculations or call functions during the replacement. See the Executing Logic in Replacements tutorial.

4. Hierarchical Parsing

For nested data formats like HTML or XML, the Transformer supports hierarchical parsing via the LocalTransformer property. This allows you to define rules that apply only within the scope of a parent match, enabling you to parse nested structures with ease. See the Hierarchical Parsing (LocalTransformer) topic.

Ready to get started? Head over to the Your First Transformation tutorial.

Examples

A simple word replacement to demonstrate the basic find-and-replace capability.

ID: 1263

See: uCalc Transformer 
				
					using uCalcSoftware;

var uc = new uCalc();
using (var t = new uCalc.Transformer()) {
   t.FromTo("red", "blue");
   Console.WriteLine(t.Transform("The red car and the red house."));
};
				
			
The blue car and the blue house.
Explore 600+ other examples
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   {
      uCalc::Transformer t;
      t.Owned(); // Causes t to be released when it goes out of scope
      t.FromTo("red", "blue");
      cout << t.Transform("The red car and the red house.") << endl;
   };
}
				
			
The blue car and the blue house.
Explore 600+ other examples
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Using t As New uCalc.Transformer()
         t.FromTo("red", "blue")
         Console.WriteLine(t.Transform("The red car and the red house."))
      End Using
   End Sub
End Module
				
			
The blue car and the blue house.
Explore 600+ other examples
Demonstrates the Transformer's token-aware safety by correctly renaming a variable without corrupting a string literal or comment.

ID: 1264

See: uCalc Transformer 
				
					using uCalcSoftware;

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

// Turn single-line comments into whitespace tokens (to be ignored)
t.Tokens.Add("//.*", TokenType.Whitespace);

// Define a rule to replace the alphanumeric token 'x' with 'value'
t.FromTo("x", "value");

var code = "x = 10; print('The max value is x.'); // x is 10 here";

// The Transformer correctly identifies that only the first 'x' is
// a token on its own. Imbedded occurrences of 'x' are left alone.
Console.WriteLine(t.Transform(code));
				
			
value = 10; print('The max value is x.'); // x is 10 here
Explore 600+ other examples
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   uCalc::Transformer t;

   // Turn single-line comments into whitespace tokens (to be ignored)
   t.Tokens().Add("//.*", TokenType::Whitespace);

   // Define a rule to replace the alphanumeric token 'x' with 'value'
   t.FromTo("x", "value");

   auto code = "x = 10; print('The max value is x.'); // x is 10 here";

   // The Transformer correctly identifies that only the first 'x' is
   // a token on its own. Imbedded occurrences of 'x' are left alone.
   cout << t.Transform(code) << endl;
}
				
			
value = 10; print('The max value is x.'); // x is 10 here
Explore 600+ other examples
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t As New uCalc.Transformer()
      
      '// Turn single-line comments into whitespace tokens (to be ignored)
      t.Tokens.Add("//.*", TokenType.Whitespace)
      
      '// Define a rule to replace the alphanumeric token 'x' with 'value'
      t.FromTo("x", "value")
      
      Dim code = "x = 10; print('The max value is x.'); // x is 10 here"
      
      '// The Transformer correctly identifies that only the first 'x' is
      '// a token on its own. Imbedded occurrences of 'x' are left alone.
      Console.WriteLine(t.Transform(code))
   End Sub
End Module
				
			
value = 10; print('The max value is x.'); // x is 10 here
Explore 600+ other examples
LIFO (Last-In, First-Out) precedence of rules with overlapping anchors.

ID: 1265

See: uCalc Transformer 
				
					using uCalcSoftware;

var uc = new uCalc();
using (var t = new uCalc.Transformer()) {
   var text = "An apple, an apple pie, and an apple cider.";

   // Rule 1 (Lowest precedence for this anchor)
   t.FromTo("an apple", "[FRUIT]");

   // Rule 2 (Higher precedence)
   t.FromTo("an apple pie", "[DESSERT]");

   // The transformer will match "an apple pie" first because it was defined last.
   // For the remaining "an apple" occurrences, it will fall back to the first rule.
   Console.WriteLine(t.Transform(text));
};
				
			
[FRUIT], [DESSERT], and [FRUIT] cider.
Explore 600+ other examples
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   {
      uCalc::Transformer t;
      t.Owned(); // Causes t to be released when it goes out of scope
      auto text = "An apple, an apple pie, and an apple cider.";

      // Rule 1 (Lowest precedence for this anchor)
      t.FromTo("an apple", "[FRUIT]");

      // Rule 2 (Higher precedence)
      t.FromTo("an apple pie", "[DESSERT]");

      // The transformer will match "an apple pie" first because it was defined last.
      // For the remaining "an apple" occurrences, it will fall back to the first rule.
      cout << t.Transform(text) << endl;
   };
}
				
			
[FRUIT], [DESSERT], and [FRUIT] cider.
Explore 600+ other examples
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Using t As New uCalc.Transformer()
         Dim text = "An apple, an apple pie, and an apple cider."
         
         '// Rule 1 (Lowest precedence for this anchor)
         t.FromTo("an apple", "[FRUIT]")
         
         '// Rule 2 (Higher precedence)
         t.FromTo("an apple pie", "[DESSERT]")
         
         '// The transformer will match "an apple pie" first because it was defined last.
         '// For the remaining "an apple" occurrences, it will fall back to the first rule.
         Console.WriteLine(t.Transform(text))
      End Using
   End Sub
End Module
				
			
[FRUIT], [DESSERT], and [FRUIT] cider.
Explore 600+ other examples