uCalc API Version: 5.7.0-preview.1 Released: 7/30/2026

Warning

uCalc API Preview Release Notice:This preview documentation describes the intended behavior of the API. It is not fully accurate or complete.The current preview build contains incomplete features, unoptimized performance, and is subject to breaking changes.Use of the preview version in your production code is not recommended.

{@Define}

Product: 

Class: 

Remarks

Evaluator Configuration Directive

Description: A directive used to define variables, functions, or other entities within the uCalc evaluator space during rule creation or at match-time.

The {@Define} directive allows a transformation pattern to modify the engine's internal state. It is primarily used to set up variables or logic that will be referenced by subsequent {@Eval} or {@@Eval} directives.

Required Syntax: Type Prefix

Definitions must specify the type of entity being created. Common types include Variable:, Function:, and Operator:. Failing to include a type prefix may result in the engine failing to categorize the definition properly.

  • Format: {@Define: [Type]: [Definition]}

Static vs. Dynamic Definitions

  • {@Define} (Static): Executed once when the FromTo rule is first created. The definition is fixed.
  • {@@Define} (Dynamic): Executed every time a match is found. This is significantly more powerful because the definition itself can be constructed from captured text.

While a static definition might set a global constant, a dynamic definition can "learn" from the document being parsed—for example, capturing a variable assignment in a script and making it available to the uCalc engine for the rest of the transformation.

Examples

1. Succinct (Quick Start: Static Definition)

Defining a constant PI value at the start of a transformation pass.

New(uCalc::Transformer, t)// Define a variable once during rule initializationt.FromTo("init_math", "{@Define: Variable: pi = 3.14159}Math Initialized")wl(t.Transform("init_math"))

[Expected Output]Math Initialized

2. Practical (Real World: Match-Driven Variable Definitions)

This example demonstrates the power of {@@Define} where the matched content dictates what is defined.

New(uCalc::Transformer, t)// Capture a variable name and its value to define it in the enginet.FromTo("const {@Alpha:name} = {@Number:val}", "{@@Define: Variable: {name} = {val}}Property {name} registered")// Use the newly defined variable in a later calculationt.FromTo("calc({@Alpha:name})", "{@@Eval: {name} * 1.1}")var(string, input) = "const tax = 0.15; calc(tax)"wl(t.Transform(input))

[Expected Output]Property tax registered; 0.165

3. Internal Test (Dynamic Expression Evaluation)

The real utility of {@@...} directives is when the expression itself comes from text, rather than being a hardcoded formula.

New(uCalc::Transformer, t)// Capture a math formula provided in the text and solve itt.FromTo("evaluate: {@All:expr}", "Result: {@@Eval: expr}")// In this case, 'expr' is not just a value, but the formula itselfwl(t.Transform("evaluate: 10 + 20 * 5"))

[Expected Output]Result: 110

Strategy & Critique

  • Creation-time vs Match-time: The @ vs @@ distinction is the most important concept to master. {@@Define} allows the rule to be self-modifying based on the input stream.
  • Type-Strict State: Requiring the Variable: or Function: prefix ensures that the evaluator space remains organized and prevents naming collisions.
  • Critique: Because {@@Define} can modify global state, developers should be careful when running parallel transformations on the same engine instance.
  • See Also: Refer to Topic 33 for a full list of supported definition types.

Examples

{@Define}

ID: 206

See: {@Define} 
				
					using uCalcSoftware;

var uc = new uCalc();
var t = uc.NewTransformer();

t.Pattern("{@Define: Var: xyz = 123}");
t.FromTo("abc", "{@Eval: xyz * 10}");
Console.WriteLine(t.Transform("The value is: abc"));

				
			
The value is: 1230
Explore 600+ other examples
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto t = uc.NewTransformer();

   t.Pattern("{@Define: Var: xyz = 123}");
   t.FromTo("abc", "{@Eval: xyz * 10}");
   cout << t.Transform("The value is: abc") << endl;

}
				
			
The value is: 1230
Explore 600+ other examples
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      
      t.Pattern("{@Define: Var: xyz = 123}")
      t.FromTo("abc", "{@Eval: xyz * 10}")
      Console.WriteLine(t.Transform("The value is: abc"))
      
   End Sub
End Module
				
			
The value is: 1230
Explore 600+ other examples