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.

TransformerForRuleReplacements = [Transformer]

Property

Product: 

Transformer Library

Class: 

uCalc

Retrieves a meta-transformer that pre-processes the replacement strings of other transformer rules before they are defined.

Remarks

The TransformerForRuleReplacements() method provides access to a special meta-transformer. This transformer does not process normal text; instead, it processes the replacement strings (the To part) of rules you define with FromTo().

This allows you to create powerful shorthands, aliases, or macros for your replacement logic, promoting consistency and readability in complex transformation projects.

⚙️ How It Works

When you define a rule like t.FromTo(pattern, replacement), the replacement string is first passed through the meta-transformer returned by this method. The result of that transformation is what gets compiled as the final replacement rule.

### 💡 Core Use Cases*   **Creating Aliases**: Define a short alias like `~` to represent a common but verbose placeholder like `{@Self}`.*   **Building Macros**: Create complex, reusable replacement templates (e.g., for wrapping text in HTML/XML tags).*   **Enforcing Consistency**: Ensure all replacement strings follow a standard format by pre-processing them.### ⚠️ Critical Pitfall: Premature Variable EvaluationWhen defining a meta-rule, its replacement string can contain variable placeholders intended for the *final* rule (e.g., `{c}` in the example above). To prevent the meta-transformer from trying to evaluate these placeholders itself, you must wrap the replacement template in `{@Eval:'...'}`. This treats the template as a literal string, ensuring the placeholders are preserved for the final rule.*   **Incorrect**: `meta.FromTo("#b({c})", "<b>{c}</b>")` - The meta-transformer will look for a variable named `c`.*   **Correct**: `meta.FromTo("#b({c})", "{@Eval:'<b>{c}</b>'}")` - The meta-transformer inserts the literal string `<b>{c}</b>`.### Comparative Analysis*   **vs. Manual Replacement**: You could manually type `<b>{word}</b>` every time, but using a meta-transformer abstracts this logic. If you later decide to use `<strong>` tags instead of `<b>`, you only need to change the single meta-rule, and all dependent rules update automatically.*   **vs. Text Pre-processors (C/C++)**: This feature is analogous to a C pre-processor `#define` macro, but it's fully integrated into the uCalc engine, token-aware, and can be modified dynamically at runtime.This meta-transformer is not created until `TransformerForRuleReplacements()` is called for the first time, ensuring no performance overhead if the feature is unused. It is the direct counterpart to [`TransformerForRulePatterns()`](/reference/ucalc/mainclassgroup/transformerforrulepatterns), which performs the same function for pattern strings.

Examples

RulePatternTransformer

ID: 187

See: TransformerForRulePatterns = [Transformer], TransformerForRuleReplacements = [Transformer] 
				
					using uCalcSoftware;

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

var Pattern = uc.TransformerForRulePatterns;
var Replacement = uc.TransformerForRuleReplacements;

Pattern.FromTo("@sq", "{@Eval: '{@Token(_Token_String_SingleQuoted)}'}");
Replacement.FromTo("~", "{@Eval: '{@Self}'}");

t.FromTo("@sq", "<single quote txt = ~>");
// Same as t.FromTo("{@Token(_Token_QuoteChar_Single)}", "<single quote txt = {@Self}>");

Console.WriteLine(t.Transform("Test: 'some text'."));




				
			
Test: <single quote txt = 'some text'>.
Explore 600+ other examples
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto t = uc.NewTransformer();

   auto Pattern = uc.TransformerForRulePatterns();
   auto Replacement = uc.TransformerForRuleReplacements();

   Pattern.FromTo("@sq", "{@Eval: '{@Token(_Token_String_SingleQuoted)}'}");
   Replacement.FromTo("~", "{@Eval: '{@Self}'}");

   t.FromTo("@sq", "<single quote txt = ~>");
   // Same as t.FromTo("{@Token(_Token_QuoteChar_Single)}", "<single quote txt = {@Self}>");

   cout << t.Transform("Test: 'some text'.") << endl;




}
				
			
Test: <single quote txt = 'some text'>.
Explore 600+ other examples
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      
      Dim Pattern = uc.TransformerForRulePatterns
      Dim Replacement = uc.TransformerForRuleReplacements
      
      Pattern.FromTo("@sq", "{@Eval: '{@Token(_Token_String_SingleQuoted)}'}")
      Replacement.FromTo("~", "{@Eval: '{@Self}'}")
      
      t.FromTo("@sq", "<single quote txt = ~>")
      '// Same as t.FromTo("{@Token(_Token_QuoteChar_Single)}", "<single quote txt = {@Self}>"); 
      
      Console.WriteLine(t.Transform("Test: 'some text'."))
      
      
      
      
   End Sub
End Module
				
			
Test: <single quote txt = 'some text'>.
Explore 600+ other examples