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.

{@Exec}

Product: 

Class: 

Remarks

Execution Directive

Description: A directive used to execute mathematical expressions or logic commands without inserting a return value into the output. It is primarily used for side effects.

The {@Exec} directive is functionally identical to {@Eval}, but with one key difference: it is "void." It performs the requested calculation or command within the uCalc evaluator space, but the result is discarded rather than being pasted into the pattern or replacement string.

Purpose: Pure Side Effects

Use {@Exec} when you need to update internal state without altering the text being transformed. Common use cases include:

  • Logging: Triggering a print statement or log update.
  • Counter/State Management: Incrementing a match counter or toggling a boolean flag.
  • Initialization: Setting up evaluator variables during rule creation.

Timing: Rule Creation (@) vs. Match Time (@@)

  • {@Exec: expression} (Static): Executed once when the rule is defined.
  • {@@Exec: expression} (Dynamic): Executed for every match found in the source text.

Variable Access

Like {@Eval}, {@Exec} has full access to variables captured in the pattern. These variables are referenced by name without curly braces.

  • Example: {@@Exec: match_count = match_count + 1}.

Examples

1. Succinct (Quick Start: Initialization Log)

Triggering a console message when a specific rule is initialized by the transformer.

New(uCalc::Transformer, t)// 'print' is executed at rule creation; nothing is added to the patternt.FromTo("{@Exec: print('Rule initialized')}TRIGGER", "MATCH")wl(t.Transform("TRIGGER"))

[Expected Output]MATCH(Console: Rule initialized)

2. Practical (Real World: Match Counter)

Incrementing a variable in the background for every match without changing the source text itself.

New(uCalc::Transformer, t)// Initialize the counter staticallyt.FromTo("{@Beginning}", "{@Define: Variable: cnt = 0}")// Increment the counter dynamically for every word foundt.FromTo("{@Alpha}", "{@@Exec: cnt = cnt + 1}{@Self}")// At the end, display the resultt.FromTo("{@End}", " [Total Words: {@@Eval: cnt}]")wl(t.Transform("One two three"))

[Expected Output]One two three [Total Words: 3]

3. Internal Test (Void Behavior)

Verifying that {@Exec} produces absolutely no output characters in the resulting string.

New(uCalc::Transformer, t)// Despite the math result being 100, nothing is inserted heret.FromTo("TEST", "Result:{@Exec: 50 + 50}!")wl(t.Transform("TEST"))

[Expected Output]Result:!

Strategy & Critique

  • Structural Integrity: {@Exec} is invaluable when you need to perform logic at a specific token location but do not want to disturb the spacing or content of that location.
  • Performance: Since {@Exec} doesn't need to format or return a string to the transformer, it is slightly more efficient than {@Eval} for pure state updates.
  • Critique: Because it is invisible, debugging {@Exec} logic can be difficult. It is recommended to use print() statements inside the expression during development to verify that the side effects are occurring as expected.
  • See Also: Refer to Topic 771 ({@Eval}) for the version of this directive that returns values.

Examples

{@Exec}
				
					using uCalcSoftware;

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

t.Pattern("{@Define: Var: Count_a = 0}");
t.Pattern("{@Define: Var: Count_an = 0}");

t.FromTo("a", "{@Self}{@Exec: Count_a++}");
t.FromTo("an", "{@Self}{@Exec: Count_an++}");
t.FromTo(".", """
{@nl}'a' occurs {@Eval: Count_a} times
'an' occurs {@Eval: Count_an} times
""");

// Note: it is counting "a" as a token, not as a character.
Console.WriteLine(t.Transform("An apple, an eagle, a cat, an orange, a tree."));
				
			
An apple, an eagle, a cat, an orange, a tree
'a' occurs 2 times
'an' occurs 3 times
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

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

   t.Pattern("{@Define: Var: Count_a = 0}");
   t.Pattern("{@Define: Var: Count_an = 0}");

   t.FromTo("a", "{@Self}{@Exec: Count_a++}");
   t.FromTo("an", "{@Self}{@Exec: Count_an++}");
   t.FromTo(".", R"({@nl}'a' occurs {@Eval: Count_a} times
'an' occurs {@Eval: Count_an} times)");

   // Note: it is counting "a" as a token, not as a character.
   cout << t.Transform("An apple, an eagle, a cat, an orange, a tree.") << endl;
}
				
			
An apple, an eagle, a cat, an orange, a tree
'a' occurs 2 times
'an' occurs 3 times
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      
      t.Pattern("{@Define: Var: Count_a = 0}")
      t.Pattern("{@Define: Var: Count_an = 0}")
      
      t.FromTo("a", "{@Self}{@Exec: Count_a++}")
      t.FromTo("an", "{@Self}{@Exec: Count_an++}")
      t.FromTo(".", "{@nl}'a' occurs {@Eval: Count_a} times
'an' occurs {@Eval: Count_an} times")
      
      '// Note: it is counting "a" as a token, not as a character.
      Console.WriteLine(t.Transform("An apple, an eagle, a cat, an orange, a tree."))
   End Sub
End Module
				
			
An apple, an eagle, a cat, an orange, a tree
'a' occurs 2 times
'an' occurs 3 times
Previous
Next