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.

{@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}

ID: 216

See: {@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
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: 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
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: 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
Explore 600+ other examples