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.

uCalc Transformer

Product: 

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.
				
					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.
				
					#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.
				
					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.
Demonstrates the Transformer's token-aware safety by correctly renaming a variable without corrupting a string literal.
				
					using uCalcSoftware;

var uc = new uCalc();
using (var t = new uCalc.Transformer()) {
   // 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.");
""";

   // The Transformer correctly identifies that the first 'x' is a variable token
   // and the second 'x' is part of a string literal token.
   // The replacement is only applied to the variable.
   Console.WriteLine(t.Transform(code));
};
				
			
value = 10; print("The max value is x.");
				
					#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
      // Define a rule to replace the alphanumeric token 'x' with 'value'
      t.FromTo("x", "value");

      auto code = R"(x = 10; print("The max value is x.");)";

      // The Transformer correctly identifies that the first 'x' is a variable token
      // and the second 'x' is part of a string literal token.
      // The replacement is only applied to the variable.
      cout << t.Transform(code) << endl;
   };
}
				
			
value = 10; print("The max value is x.");
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Using t As New uCalc.Transformer()
         '// 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."");"
         
         '// The Transformer correctly identifies that the first 'x' is a variable token
         '// and the second 'x' is part of a string literal token.
         '// The replacement is only applied to the variable.
         Console.WriteLine(t.Transform(code))
      End Using
   End Sub
End Module
				
			
value = 10; print("The max value is x.");
LIFO (Last-In, First-Out) precedence of rules with overlapping anchors.
				
					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.
				
					#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.
				
					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.
Previous
Next