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.

TransformerForRulePatterns = [Transformer]

Property

Product: 

Transformer Library

Class: 

uCalcBase

Retrieves a singleton transformer that pre-processes pattern definition strings before they are compiled into rules.

Remarks

The TransformerForRulePatterns() method retrieves a special, singleton Transformer instance that pre-processes the pattern part of a rule before it is compiled. This "meta-transformer" allows you to create aliases, macros, or syntactic sugar for your pattern definitions, effectively enabling you to build a custom, higher-level pattern language.

⚙️ How It Works

When you define a rule using methods like FromTo() or Pattern(), the pattern string goes through this pipeline:

  1. The raw pattern string is passed to the TransformerForRulePatterns instance.
  2. Any matching rules defined on this meta-transformer are applied.
  3. The resulting, transformed string is then compiled into the final pattern rule.

This process is transparent. By default, this transformer has no rules and does nothing. It is lazily instantiated only when this method is called for the first time, ensuring no performance overhead for users who don't need it.

🎯 Primary Use Cases

  • Creating Shortcuts & Aliases: Simplify complex or frequently used pattern segments. Instead of writing {@StringSQ} repeatedly, you can define a rule to transform a simple alias like @sqs into the full token name.
  • Abstracting Complexity: Hide complex regex or structural logic behind a simple, readable keyword. A custom pattern like IPV4_ADDRESS could be expanded into {@Number}.{@Number}.{@Number}.{@Number}.
  • Building a Mini-DSL: Design a simpler syntax for end-users, which the meta-transformer then transpiles into valid uCalc patterns behind the scenes.

🆚 Comparative Analysis

MethodTransformerForRulePatterns()ExpressionTransformer()NewTransformer()
PurposeTransforms pattern definition strings before they become rules.Transforms user expressions before they are parsed (e.g., EvalStr).A general-purpose tool for transforming any user data string.
ScopeAffects how FromTo() and Pattern() rules are created.Affects the uCalc expression parser.Standalone; does not affect any internal process.

Using this meta-transformer is similar to using C/C++ preprocessor macros (#define) to create aliases for complex code, but with the full, token-aware power of a uCalc Transformer.

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