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.

Introduction

Product: 

Transformer Library

Class: 

Transformer

An overview of the uCalc.Transformer class, a token-aware engine for pattern matching, data extraction, and structural text replacement.

Remarks

🧠 uCalc.Transformer: The Smart Text Engine

The uCalc.Transformer class 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.

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 breaks the input string into a stream of meaningful tokens: words, numbers, operators, string literals, and comments. This structural awareness prevents common and dangerous bugs, such as accidentally changing text inside a string literal or a user-defined comment structure. 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, using clear, token-based patterns with anchors, variables, and token categories. This makes rules easier to write, debug, and maintain.

3. Intelligent Replacements

Replacements can include backreferences, conditional logic, and even embedded expressions using {@Eval} to perform calculations or call functions during the replacement. See the Executing Logic in Replacements tutorial.

4. Hierarchical & Multi-Pass Processing

For nested data formats, the LocalTransformer property enables hierarchical parsing. For complex, multi-stage transformations, you can define a sequence of Passes, creating a powerful processing pipeline.

Class Members Overview

▶️ Core Operation Methods

These methods execute the transformation process.

MemberDescription
FindExecutes a read-only search, populating the matches collection without modifying the text.
TransformApplies all defined rules to the text, performing find-and-replace operations.
FilterExtracts and transforms all matches, returning a new string composed only of the results.
TraceTransformCaptures each intermediate step of a cascading transformation for debugging.

✍️ Rule Definition Methods

These methods define the patterns for the transformer to find.

MemberDescription
FromToDefines a find-and-replace rule that transforms text matching a pattern.
PatternDefines a find-only search pattern that locates text without replacing it.
SkipOverDefines a pattern for text that should be ignored by all other rules.

🧐 Introspection & Results

These properties provide access to the results and state of the transformer.

MemberDescription
MatchesRetrieves the collection of all matches found by the most recent operation.
GetMatchesRetrieves the collection of matches with options to filter the result set.
TextGets or sets the primary source text string for the transformer.
WasModifiedChecks if the most recent operation resulted in any changes to the text.
DescriptionGets or sets a user-defined description for the transformer instance.

⚙️ Configuration & Settings

These properties control the transformer's behavior.

MemberDescription
TokensProvides access to the collection of token definitions for customizing lexical rules.
DefaultRuleSetGets a template rule for defining default properties for all new rules.
GlobalRuleSetGets a rule for defining global, cumulative properties across all rules in a pass.
RangeRestricts all subsequent operations to a specific character range within the source text.

🧬 Lifetime Management

These methods manage the transformer's memory and lifecycle.

MemberDescription
ConstructorCreates a new transformer instance.
CloneCreates an identical, independent copy of the transformer, including all its rules and settings.
ReleaseExplicitly frees all memory and resources associated with the transformer.
ResetClears the transformer's state for reuse without creating a new instance.
OwnedEnables RAII-style automatic memory release, primarily for C++.

⛓️ Multi-Pass & Advanced Methods

These methods enable complex, multi-stage transformations.

MemberDescription
PassCreates or retrieves a sequential transformation stage (a pass).
PassCountReturns the number of defined transformation passes.
SetupCreates a dedicated initialization pass that executes before the main transformation rules.

Examples

A simple find-and-replace transformation to replace all occurrences of a word.
				
					using uCalcSoftware;

var uc = new uCalc();
var t = new uCalc.Transformer();
// Define a simple replacement rule
t.FromTo("Hello", "Greetings");

// Execute the transformation on an input string
t.Text = "Hello World, and Hello again.";
Console.WriteLine(t.Transform());
				
			
Greetings World, and Greetings again.
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   uCalc::Transformer t;
   // Define a simple replacement rule
   t.FromTo("Hello", "Greetings");

   // Execute the transformation on an input string
   t.Text("Hello World, and Hello again.");
   cout << t.Transform() << endl;
}
				
			
Greetings World, and Greetings again.
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t As New uCalc.Transformer()
      '// Define a simple replacement rule
      t.FromTo("Hello", "Greetings")
      
      '// Execute the transformation on an input string
      t.Text = "Hello World, and Hello again."
      Console.WriteLine(t.Transform())
   End Sub
End Module
				
			
Greetings World, and Greetings again.
A succinct example showing how `SkipOver` creates 'dead zones' where other rules are not applied.
				
					using uCalcSoftware;

var uc = new uCalc();
var t = new uCalc.Transformer();
t.Text = "transform this but (not this) and this";

// A rule to replace the word 'this'
t.FromTo("this", "THAT");

// A rule to ignore any content inside parentheses
t.SkipOver("({content})");

// The 'this' inside the parentheses is protected by the SkipOver rule
Console.WriteLine(t.Transform());
				
			
transform THAT but (not this) and THAT
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   uCalc::Transformer t;
   t.Text("transform this but (not this) and this");

   // A rule to replace the word 'this'
   t.FromTo("this", "THAT");

   // A rule to ignore any content inside parentheses
   t.SkipOver("({content})");

   // The 'this' inside the parentheses is protected by the SkipOver rule
   cout << t.Transform() << endl;
}
				
			
transform THAT but (not this) and THAT
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t As New uCalc.Transformer()
      t.Text = "transform this but (not this) and this"
      
      '// A rule to replace the word 'this'
      t.FromTo("this", "THAT")
      
      '// A rule to ignore any content inside parentheses
      t.SkipOver("({content})")
      
      '// The 'this' inside the parentheses is protected by the SkipOver rule
      Console.WriteLine(t.Transform())
   End Sub
End Module
				
			
transform THAT but (not this) and THAT
Previous
Next