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.

{@Comment}

Product: 

Class: 

Remarks

Pattern Annotation Directive

Description: A non-functional structural directive used to include notes, explanations, or labels within a transformation pattern without affecting the match or the output.

The {@Comment} directive is the annotation tool of the uCalc::Transformer. It allows developers to document complex pattern logic directly within the pattern string itself.

Functional Invisibility

When the uCalc engine parses a pattern containing {@Comment}, it effectively "strips" the comment directive. It does not look for a match for the comment content, nor does it insert the comment into the replacement result.

  • In the Pattern: {@Comment: This matches a name}{@Alpha:name} is treated exactly like {@Alpha:name}.
  • In the Replacement: Hello{@Comment: friendly greeting} {name} is treated exactly like Hello {name}.

Maintenance and Clarity

In large-scale transformation projects where patterns can become quite dense, {@Comment} provides a way to:

  1. Explain the purpose of specific structural segments.
  2. Label complex capture groups.
  3. Include internal versioning or metadata within a specific rule.

Examples

1. Succinct (Quick Start: Basic Annotation)

Adding a note to a pattern that identifies a specific keyword.

New(uCalc::Transformer, t)// The comment is ignored by the enginet.FromTo("{@Comment: match the keyword} KEY", "FOUND")wl(t.Transform("KEY"))

[Expected Output]FOUND

2. Practical (Real World: Documenting Complex Logic)

Using comments to clarify a multi-part transpiler rule that converts assignment syntax.

New(uCalc::Transformer, t)t.FromTo(  "let {@Comment: identifier} {@Alpha:id} = {@Comment: value} {@Number:val}",  "set {id} = {val}")var(string, input) = "let x = 10"wl(t.Transform(input))

[Expected Output]set x = 10

3. Internal Test (Placement Versatility)

Verifying that {@Comment} can be placed anywhere, even in the replacement string, without altering the result.

New(uCalc::Transformer, t)t.FromTo("{@Alpha:a}", "Word:{@Comment: add label} {a}")wl(t.Transform("Hello"))

[Expected Output]Word: Hello

Strategy & Critique

  • Documentation "At the Source": The biggest benefit of {@Comment} is that the explanation lives inside the code it describes. This prevents documentation from becoming stale or "drifting" away from the actual logic.
  • Readability Trade-off: While useful, over-commenting short patterns can make them visually cluttered. Use {@Comment} primarily for non-obvious logic or structural anchors.
  • Critique: Unlike other directives, the @@ prefix is irrelevant for {@Comment} because there is no execution or evaluation logic to shift from rule-creation to match-time.
  • See Also: Refer to Topic 817 (Pattern Methods Introduction) for an overview of other functional directives.

Examples

{@Comment}
				
					using uCalcSoftware;

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

t.FromTo("a {@Comment: Ignore this} b c", "x{@Comment: ignore} y z");

Console.WriteLine(t.Transform("a b. a b c. abc."));
				
			
a b. x y z. abc.
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

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

   t.FromTo("a {@Comment: Ignore this} b c", "x{@Comment: ignore} y z");

   cout << t.Transform("a b. a b c. abc.") << endl;
}
				
			
a b. x y z. abc.
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      
      t.FromTo("a {@Comment: Ignore this} b c", "x{@Comment: ignore} y z")
      
      Console.WriteLine(t.Transform("a b. a b c. abc."))
   End Sub
End Module
				
			
a b. x y z. abc.
Previous
Next