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.

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

ID: 205

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