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: 

Tokens

Retrieves the parent uCalc instance that owns this token collection, providing access to the full execution context.

Remarks

🧭 Navigating the Hierarchy: Tokens.uCalc

Every Tokens object exists within the context of a parent uCalc instance. It either belongs directly to the uCalc instance (like ExpressionTokens) or to a Transformer which is, in turn, owned by a uCalc instance. This property provides the crucial link back to that root uCalc engine, allowing you to navigate "up" the object hierarchy.

This is essential for introspection and for writing context-aware lexical rules.

🎯 Primary Use Cases

  1. Contextual Operations: The most common use is to perform another operation within the same context as the token set. If you have a Tokens 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 Tokens collections belong to the same execution context, which is invaluable for debugging applications that manage multiple, isolated uCalc instances.

  3. Accessing Sibling Collections: Once you retrieve the parent instance, you can use it to find other Tokens collections, for example: myTokens.uCalc.ExpressionTokens.

💡 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 Tokens collection 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.

  • vs. Ad-Hoc Management: Without this built-in link, you would need to manually track which uCalc instance owns which Tokens collection, 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 lexical rules and their execution context.

Examples

Retrieves a Tokens collection's parent uCalc instance and verifies its identity by reading a description.
				
					using uCalcSoftware;

var uc = new uCalc();
var t = new uCalc.Transformer();
t.uCalc.Description = "My Parent uCalc";
var tokens = t.Tokens;

// Get the parent from the Tokens object
var parent_uc = tokens.uCalc;

// Verify we got the correct parent
Console.WriteLine(parent_uc.Description);
				
			
My Parent uCalc
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   uCalc::Transformer t;
   t.uCalc().Description("My Parent uCalc");
   auto tokens = t.Tokens();

   // Get the parent from the Tokens object
   auto parent_uc = tokens.uCalc();

   // Verify we got the correct parent
   cout << parent_uc.Description() << endl;
}
				
			
My Parent uCalc
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t As New uCalc.Transformer()
      t.uCalc.Description = "My Parent uCalc"
      Dim tokens = t.Tokens
      
      '// Get the parent from the Tokens object
      Dim parent_uc = tokens.uCalc
      
      '// Verify we got the correct parent
      Console.WriteLine(parent_uc.Description)
   End Sub
End Module
				
			
My Parent uCalc
Uses the parent uCalc context from a Tokens object to define a variable that is then used by a transformer rule.
				
					using uCalcSoftware;

var uc = new uCalc();
var t = new uCalc.Transformer();
var tokens = t.Tokens;

// Use the parent uCalc instance to define a variable
tokens.uCalc.DefineVariable("replacement = 'REPLACED'");

t.FromTo("original", "{@Eval: replacement}");

Console.WriteLine(t.Transform("Test of original value."));
				
			
Test of REPLACED value.
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   uCalc::Transformer t;
   auto tokens = t.Tokens();

   // Use the parent uCalc instance to define a variable
   tokens.uCalc().DefineVariable("replacement = 'REPLACED'");

   t.FromTo("original", "{@Eval: replacement}");

   cout << t.Transform("Test of original value.") << endl;
}
				
			
Test of REPLACED value.
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t As New uCalc.Transformer()
      Dim tokens = t.Tokens
      
      '// Use the parent uCalc instance to define a variable
      tokens.uCalc.DefineVariable("replacement = 'REPLACED'")
      
      t.FromTo("original", "{@Eval: replacement}")
      
      Console.WriteLine(t.Transform("Test of original value."))
   End Sub
End Module
				
			
Test of REPLACED value.
Internal Test: Verifies instance isolation by ensuring Tokens collections from different uCalc instances correctly resolve to their respective parents.
				
					using uCalcSoftware;

var uc = new uCalc();
var uc1 = new uCalc();
var uc2 = new uCalc();

var t1 = new uCalc.Transformer(uc1);
var t2 = new uCalc.Transformer(uc2);

var tokens1 = t1.Tokens;
var tokens2 = t2.Tokens;

var parent1 = tokens1.uCalc;
var parent2 = tokens2.uCalc;

Console.WriteLine($"tokens1 belongs to uc1: {parent1.Handle() == uc1.Handle()}");
Console.WriteLine($"tokens2 belongs to uc2: {parent2.Handle() == uc2.Handle()}");
Console.WriteLine($"tokens1 does not belong to uc2: {parent1.Handle() != uc2.Handle()}");
				
			
tokens1 belongs to uc1: True
tokens2 belongs to uc2: True
tokens1 does not belong to uc2: True
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

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

int main() {
   uCalc uc;
   uCalc uc1;
   uCalc uc2;

   uCalc::Transformer t1(uc1);
   uCalc::Transformer t2(uc2);

   auto tokens1 = t1.Tokens();
   auto tokens2 = t2.Tokens();

   auto parent1 = tokens1.uCalc();
   auto parent2 = tokens2.uCalc();

   cout << "tokens1 belongs to uc1: " << tf(parent1.Handle() == uc1.Handle()) << endl;
   cout << "tokens2 belongs to uc2: " << tf(parent2.Handle() == uc2.Handle()) << endl;
   cout << "tokens1 does not belong to uc2: " << tf(parent1.Handle() != uc2.Handle()) << endl;
}
				
			
tokens1 belongs to uc1: True
tokens2 belongs to uc2: True
tokens1 does not belong to uc2: True
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim uc1 As New uCalc()
      Dim uc2 As New uCalc()
      
      Dim t1 As New uCalc.Transformer(uc1)
      Dim t2 As New uCalc.Transformer(uc2)
      
      Dim tokens1 = t1.Tokens
      Dim tokens2 = t2.Tokens
      
      Dim parent1 = tokens1.uCalc
      Dim parent2 = tokens2.uCalc
      
      Console.WriteLine($"tokens1 belongs to uc1: {parent1.Handle() = uc1.Handle()}")
      Console.WriteLine($"tokens2 belongs to uc2: {parent2.Handle() = uc2.Handle()}")
      Console.WriteLine($"tokens1 does not belong to uc2: {parent1.Handle() <> uc2.Handle()}")
   End Sub
End Module
				
			
tokens1 belongs to uc1: True
tokens2 belongs to uc2: True
tokens1 does not belong to uc2: True
uCalc Description
				
					using uCalcSoftware;

var uc = new uCalc();
uc.Description = "This is the main uCalc object";
var t = uc.NewTransformer();
Console.WriteLine(t.Tokens.uCalc.Description);
				
			
This is the main uCalc object
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   uc.Description("This is the main uCalc object");
   auto t = uc.NewTransformer();
   cout << t.Tokens().uCalc().Description() << endl;
}
				
			
This is the main uCalc object
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      uc.Description = "This is the main uCalc object"
      Dim t = uc.NewTransformer()
      Console.WriteLine(t.Tokens.uCalc.Description)
   End Sub
End Module
				
			
This is the main uCalc object
Previous
Next