uCalc API Version: 2.1.3-preview.2 Released: 6/17/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 = [uCalc]

Property

Product: 

Transformer Library

Class: 

Transformer

Gets or sets the parent uCalc instance that provides the execution context for the transformer's rules and expressions.

Remarks

Every Transformer object is intrinsically linked to a parent uCalc instance. This parent instance acts as its execution context, holding the complete set of variables, functions, and settings required to evaluate any expressions within its rules, such as those in an {@Eval} directive.

The uCalc property is a powerful feature that allows you to both retrieve and modify this context at runtime.

⚙️ Getter and Setter Behavior

  • Getter: When called without arguments, myTransformer.uCalc retrieves the uCalc instance that currently owns the transformer. This is essential for introspection and for performing other operations within the same context (e.g., defining a variable that a rule will need).

  • Setter: When called with a uCalc instance as an argument, myTransformer.uCalc = new_uc re-parents the transformer. From that point on, all its rules will be executed within the context of the new instance. This allows a single, complex transformer configuration to be applied to different data contexts.

🎯 Primary Use Cases

  • Contextual Introspection: Get a handle to the parent instance to query its state, such as its Description or defined Items.
  • Dynamic Re-scoping: Create a generic set of transformation rules and then apply them to different uCalc instances, each with its own set of variables and functions. This is ideal for multi-tenant applications or for processing data against different configuration profiles.
  • Shared Logic: A single rule can access variables or functions from its parent context, allowing for tight integration between the transformation logic and the application's state.

💡 Comparative Analysis

In many programming environments, the context for an operation is immutable or passed as a parameter during execution. uCalc's model, where the execution context is a mutable property of the transformer itself, provides a unique level of flexibility.

  • vs. Dependency Injection: While DI frameworks inject dependencies at creation time, Transformer.uCalc allows the dependency (the execution context) to be hot-swapped at any point in the object's lifecycle. This is a form of dynamic, runtime dependency injection.

  • vs. Global State: Instead of relying on a single global uCalc instance, this property promotes better encapsulation. Each transformer can have its own private context, but that context can be changed programmatically, offering the benefits of isolation with the flexibility of dynamic redirection.

Examples

Transformer.uCalc
				
					using uCalcSoftware;

var uc = new uCalc();
var t = uc.NewTransformer();
t.uCalc.DefineVariable("xyz = 123");

t.FromTo("xyz", "{@Eval: xyz * 10}");
Console.WriteLine(t.Transform("The answer is: xyz"));
				
			
The answer is: 1230
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto t = uc.NewTransformer();
   t.uCalc().DefineVariable("xyz = 123");

   t.FromTo("xyz", "{@Eval: xyz * 10}");
   cout << t.Transform("The answer is: xyz") << endl;
}
				
			
The answer is: 1230
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      t.uCalc.DefineVariable("xyz = 123")
      
      t.FromTo("xyz", "{@Eval: xyz * 10}")
      Console.WriteLine(t.Transform("The answer is: xyz"))
   End Sub
End Module
				
			
The answer is: 1230
Changing the parent uCalc object for a Transformer
				
					using uCalcSoftware;

var uc = new uCalc();
uc.DefineVariable("x = 1");
uc.DefineVariable("y = 2");
uc.DefineFunction("f(x) = x * 10");

var t = uc.NewTransformer();
var text = "Adding {x} and {y} gives: {x + y}. f(5) = {f(5)}";

var uNew = new uCalc();
uNew.DefineVariable("x = 111");
uNew.DefineVariable("y = 222");
uNew.DefineFunction("f(x) = x * 1000");

// Note: {@@Eval: txt} is equivalent of {@Eval: Eval(txt)}
// which is what's needed for to evaluate the expression
// resulting from the match that is not known ahead of time
t.FromTo("'{' {expr} '}'", "{@@Eval: expr}");
Console.WriteLine(t.Transform(text));

t.uCalc = uNew;
t.FromTo("'{' {expr} '}'", "{@@Eval: expr}");
Console.WriteLine(t.Transform(text));

				
			
Adding 1 and 2 gives: 3. f(5) = 50
Adding 111 and 222 gives: 333. f(5) = 5000
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   uc.DefineVariable("x = 1");
   uc.DefineVariable("y = 2");
   uc.DefineFunction("f(x) = x * 10");

   auto t = uc.NewTransformer();
   auto text = "Adding {x} and {y} gives: {x + y}. f(5) = {f(5)}";

   uCalc uNew;
   uNew.DefineVariable("x = 111");
   uNew.DefineVariable("y = 222");
   uNew.DefineFunction("f(x) = x * 1000");

   // Note: {@@Eval: txt} is equivalent of {@Eval: Eval(txt)}
   // which is what's needed for to evaluate the expression
   // resulting from the match that is not known ahead of time
   t.FromTo("'{' {expr} '}'", "{@@Eval: expr}");
   cout << t.Transform(text) << endl;

   t.uCalc(uNew);
   t.FromTo("'{' {expr} '}'", "{@@Eval: expr}");
   cout << t.Transform(text) << endl;

}
				
			
Adding 1 and 2 gives: 3. f(5) = 50
Adding 111 and 222 gives: 333. f(5) = 5000
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      uc.DefineVariable("x = 1")
      uc.DefineVariable("y = 2")
      uc.DefineFunction("f(x) = x * 10")
      
      Dim t = uc.NewTransformer()
      Dim text = "Adding {x} and {y} gives: {x + y}. f(5) = {f(5)}"
      
      Dim uNew As New uCalc()
      uNew.DefineVariable("x = 111")
      uNew.DefineVariable("y = 222")
      uNew.DefineFunction("f(x) = x * 1000")
      
      '// Note: {@@Eval: txt} is equivalent of {@Eval: Eval(txt)}
      '// which is what's needed for to evaluate the expression
      '// resulting from the match that is not known ahead of time
      t.FromTo("'{' {expr} '}'", "{@@Eval: expr}")
      Console.WriteLine(t.Transform(text))
      
      t.uCalc = uNew
      t.FromTo("'{' {expr} '}'", "{@@Eval: expr}")
      Console.WriteLine(t.Transform(text))
      
   End Sub
End Module
				
			
Adding 1 and 2 gives: 3. f(5) = 50
Adding 111 and 222 gives: 333. f(5) = 5000
Previous
Next