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.

{@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}
				
					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
				
					#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
				
					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
Previous
Next