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.

uCalc = [uCalc]

Property

Product: 

Transformer Library

Class: 

Rule

Retrieves the parent uCalc instance that owns the rule, providing access to its full execution context.

Remarks

🧭 Navigating the Hierarchy: Rule.uCalc

Every Rule object exists within the context of a parent Transformer, which in turn is owned by a specific uCalc instance. This property provides the crucial link back to the root uCalc engine, allowing you to navigate "up" the object hierarchy from a specific rule to its ultimate execution context.

This is essential for introspection and for writing context-aware transformation logic.

🎯 Primary Use Cases

  1. Contextual Operations: The most common use is to perform another operation within the same context as the item. If you have a Rule object but not a direct reference to its parent uCalc instance, you can use this property to retrieve it and call methods like Eval() or DefineVariable().

  2. Instance Introspection: It allows you to determine if two different rules belong to the same execution context, which is invaluable for debugging applications that manage multiple, isolated uCalc instances.

  3. Accessing Sibling Items: Once you retrieve the parent instance, you can use it to find other items within the same sandbox, for example: myRule.@uCalc().ItemOf("SomeOtherVar").

💡 Why uCalc? (Comparative Analysis)

This parent-child relationship is a common design pattern for creating navigable object trees.

  • vs. DOM (Document Object Model): The relationship between a Rule and its parent uCalc instance is analogous to an HTML element and its ownerDocument property in the DOM. It provides a structured, predictable way to traverse the hierarchy of your parsing logic. Just as you might walk up the DOM tree from a specific <div> to find its container, you can walk up from a Rule to its owning uCalc engine.

  • vs. Ad-Hoc Rule Management: Without this built-in link, you would need to manually track which Transformer (and which uCalc instance) owns which Rule, likely using external dictionaries or wrapper classes. This is complex and error-prone. By making uCalc() a first-class property, uCalc provides a clean, reliable, and integrated solution for managing the relationship between rules and their execution context.

Examples

A succinct example demonstrating how to retrieve a rule's parent uCalc instance and verify its identity.
				
					using uCalcSoftware;

var uc = new uCalc();
var t = uc.NewTransformer();
var myRule = t.FromTo("A", "B");

// Get the parent uCalc from the rule
var parent_uc = myRule.uCalc;

// Verify they are the same instance using their MemoryIndex
Console.WriteLine(parent_uc.MemoryIndex == uc.MemoryIndex);
				
			
True
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

#define tf(IsTrue) ((IsTrue) ? "True" : "False")

int main() {
   uCalc uc;
   auto t = uc.NewTransformer();
   auto myRule = t.FromTo("A", "B");

   // Get the parent uCalc from the rule
   auto parent_uc = myRule.uCalc();

   // Verify they are the same instance using their MemoryIndex
   cout << tf(parent_uc.MemoryIndex() == uc.MemoryIndex()) << endl;
}
				
			
True
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      Dim myRule = t.FromTo("A", "B")
      
      '// Get the parent uCalc from the rule
      Dim parent_uc = myRule.uCalc
      
      '// Verify they are the same instance using their MemoryIndex
      Console.WriteLine(parent_uc.MemoryIndex = uc.MemoryIndex)
   End Sub
End Module
				
			
True
A practical example that uses a rule's parent context to define and evaluate an expression.
				
					using uCalcSoftware;

var uc = new uCalc();
// The transformer 't' belongs to the main 'uc' instance.
var t = new uCalc.Transformer(uc);

// Define a variable in the transformer's parent context.
t.uCalc.DefineVariable("VarX = 123");

// This rule is created within 't' and will need to access VarX.
var myRule = t.FromTo("x", "{@Eval: VarX}");

// Get the rule's parent uCalc instance...
var parent_uc = myRule.uCalc;

// ...and use it to evaluate an expression to prove we have the right context.
Console.WriteLine($"Value of VarX in parent context: {parent_uc.Eval("VarX")}");

// Now, run the transformation. The {@Eval} in the rule
// correctly finds 'VarX' in its parent uCalc context.
Console.WriteLine(t.Transform("The value is: x"));
				
			
Value of VarX in parent context: 123
The value is: 123
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   // The transformer 't' belongs to the main 'uc' instance.
   uCalc::Transformer t(uc);

   // Define a variable in the transformer's parent context.
   t.uCalc().DefineVariable("VarX = 123");

   // This rule is created within 't' and will need to access VarX.
   auto myRule = t.FromTo("x", "{@Eval: VarX}");

   // Get the rule's parent uCalc instance...
   auto parent_uc = myRule.uCalc();

   // ...and use it to evaluate an expression to prove we have the right context.
   cout << "Value of VarX in parent context: " << parent_uc.Eval("VarX") << endl;

   // Now, run the transformation. The {@Eval} in the rule
   // correctly finds 'VarX' in its parent uCalc context.
   cout << t.Transform("The value is: x") << endl;
}
				
			
Value of VarX in parent context: 123
The value is: 123
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      '// The transformer 't' belongs to the main 'uc' instance.
      Dim t As New uCalc.Transformer(uc)
      
      '// Define a variable in the transformer's parent context.
      t.uCalc.DefineVariable("VarX = 123")
      
      '// This rule is created within 't' and will need to access VarX.
      Dim myRule = t.FromTo("x", "{@Eval: VarX}")
      
      '// Get the rule's parent uCalc instance...
      Dim parent_uc = myRule.uCalc
      
      '// ...and use it to evaluate an expression to prove we have the right context.
      Console.WriteLine($"Value of VarX in parent context: {parent_uc.Eval("VarX")}")
      
      '// Now, run the transformation. The {@Eval} in the rule
      '// correctly finds 'VarX' in its parent uCalc context.
      Console.WriteLine(t.Transform("The value is: x"))
   End Sub
End Module
				
			
Value of VarX in parent context: 123
The value is: 123
Internal Test: Verifies that a rule defined in a nested LocalTransformer correctly resolves its parent to the root uCalc instance.
				
					using uCalcSoftware;

var uc = new uCalc();
var root_uc = new uCalc();
root_uc.Description = "Root uCalc Instance";

var main_t = new uCalc.Transformer(root_uc);

// Create a rule in the main transformer
var outerRule = main_t.Pattern("OUTER({body})");

// Get a local transformer for the outer rule
var local_t = outerRule.LocalTransformer;
local_t.Description = "Local Transformer";

// Create an inner rule inside the local transformer
var innerRule = local_t.FromTo("INNER", "inner_match");

// Verify both rules resolve to the same root uCalc instance
var outerParent = outerRule.uCalc;
var innerParent = innerRule.uCalc;

Console.WriteLine($"Outer rule's parent: {outerParent.Description}");
Console.WriteLine($"Inner rule's parent: {innerParent.Description}");
Console.WriteLine($"Both rules share the same root uCalc instance: {outerParent.Handle() == innerParent.Handle()}");
				
			
Outer rule's parent: Root uCalc Instance
Inner rule's parent: Root uCalc Instance
Both rules share the same root uCalc instance: True
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

#define tf(IsTrue) ((IsTrue) ? "True" : "False")

int main() {
   uCalc uc;
   uCalc root_uc;
   root_uc.Description("Root uCalc Instance");

   uCalc::Transformer main_t(root_uc);

   // Create a rule in the main transformer
   auto outerRule = main_t.Pattern("OUTER({body})");

   // Get a local transformer for the outer rule
   auto local_t = outerRule.LocalTransformer();
   local_t.Description("Local Transformer");

   // Create an inner rule inside the local transformer
   auto innerRule = local_t.FromTo("INNER", "inner_match");

   // Verify both rules resolve to the same root uCalc instance
   auto outerParent = outerRule.uCalc();
   auto innerParent = innerRule.uCalc();

   cout << "Outer rule's parent: " << outerParent.Description() << endl;
   cout << "Inner rule's parent: " << innerParent.Description() << endl;
   cout << "Both rules share the same root uCalc instance: " << tf(outerParent.Handle() == innerParent.Handle()) << endl;
}
				
			
Outer rule's parent: Root uCalc Instance
Inner rule's parent: Root uCalc Instance
Both rules share the same root uCalc instance: True
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim root_uc As New uCalc()
      root_uc.Description = "Root uCalc Instance"
      
      Dim main_t As New uCalc.Transformer(root_uc)
      
      '// Create a rule in the main transformer
      Dim outerRule = main_t.Pattern("OUTER({body})")
      
      '// Get a local transformer for the outer rule
      Dim local_t = outerRule.LocalTransformer
      local_t.Description = "Local Transformer"
      
      '// Create an inner rule inside the local transformer
      Dim innerRule = local_t.FromTo("INNER", "inner_match")
      
      '// Verify both rules resolve to the same root uCalc instance
      Dim outerParent = outerRule.uCalc
      Dim innerParent = innerRule.uCalc
      
      Console.WriteLine($"Outer rule's parent: {outerParent.Description}")
      Console.WriteLine($"Inner rule's parent: {innerParent.Description}")
      Console.WriteLine($"Both rules share the same root uCalc instance: {outerParent.Handle() = innerParent.Handle()}")
   End Sub
End Module
				
			
Outer rule's parent: Root uCalc Instance
Inner rule's parent: Root uCalc Instance
Both rules share the same root uCalc instance: True
Rule uCalc
				
					using uCalcSoftware;

var uc = new uCalc();
var t = uc.NewTransformer();
t.Text = "The value is: x";

uc.DefineVariable("VarX");
t.FromTo("x", "{@Eval: VarX}").uCalc.Eval("VarX = 123");

t.Transform();
Console.WriteLine(t.Text);
				
			
The value is: 123
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto t = uc.NewTransformer();
   t.Text("The value is: x");

   uc.DefineVariable("VarX");
   t.FromTo("x", "{@Eval: VarX}").uCalc().Eval("VarX = 123");

   t.Transform();
   cout << t.Text() << endl;
}
				
			
The value is: 123
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      t.Text = "The value is: x"
      
      uc.DefineVariable("VarX")
      t.FromTo("x", "{@Eval: VarX}").uCalc.Eval("VarX = 123")
      
      t.Transform()
      Console.WriteLine(t.Text)
   End Sub
End Module
				
			
The value is: 123
Previous
Next