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.

TransformerForRuleReplacements = [Transformer]

Property

Product: 

Transformer Library

Class: 

uCalcBase

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.

// 1. Get the meta-transformervar meta = uc.TransformerForRuleReplacements();// 2. Define a meta-rule: "#b({c})" will become "<b>{c}</b>"//    Note: {@Eval:'...'} is used to pass the replacement as a literal template.meta.FromTo("#b({c})", "{@Eval:'<b>{c}</b>'}");// 3. Create a standard transformervar t = new uCalc.Transformer();// 4. Use the shorthand in a normal rule definition.//    The meta-transformer will expand "#b({word})" before this rule is compiled.t.FromTo("{@Alpha:word}", "#b({word})");// 5. The rule effectively becomes: t.FromTo("{@Alpha:word}", "<b>{word}</b>");Console.WriteLine(t.Transform("make this bold"));// Output: make this <b>bold</b>

💡 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 Evaluation

When 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(), which performs the same function for pattern strings.

Examples

RulePatternTransformer
				
					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'>.
				
					#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'>.
				
					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'>.
Previous
Next