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.

Nesting Override ^

Product: 

Class: 

Remarks

Nesting Override

Shortcut: ^Associated Method: uCalc.Rule.NestingAware(bool)

Description: A postfix modifier that instructs a pattern variable to ignore balanced nesting levels (brackets, parentheses, etc.) and stop at the literal next terminal token.

By default, uCalc is "Nesting Aware." This means if a variable is tasked with capturing content inside a bracketed structure, it will intelligently track open and close markers (like ( and )) to ensure it doesn't stop matching prematurely.

The Nesting Override (^) is used to break this structural integrity for specific, surgical transformations.

Default vs. Override Behavior

  • Default (Nesting Aware): A pattern like func({x}) matched against func((1+1)) will capture (1+1) into {x}. The engine sees the first ) but knows it belongs to an internal group, so it continues until the "balanced" closing bracket is found.
  • Override ({x^}): Appending the ^ symbol tells the engine to stop at the very first occurrence of the terminal token, regardless of whether brackets are balanced or not. In the example above, {x^} would capture ((1+1).

The NestingAware() Method

While the ^ symbol provides per-variable control, you can toggle this behavior globally using the NestingAware() method on the uCalc object.

  • uc.NestingAware(true): (Default) All variables respect bracket levels.
  • uc.NestingAware(false): All variables behave as if they have the ^ postfix unless otherwise specified.

Examples

1. Succinct (Nesting Awareness Example)

Demonstrating how the engine normally handles nested parentheses versus the override.

New(uCalc::Transformer, t)// Default: captures everything balancedt.FromTo("calc({v})", "RESULT({v})")// Override: stops at the first ')' it seest.FromTo("raw({v^})", "RAW({v})")wl(t.Transform("calc((1+1))")) // Output: RESULT((1+1))wl(t.Transform("raw((1+1))"))  // Output: RAW((1+1)

2. Practical (Surgical Extraction)

In some complex document formats, you may need to stop at the first delimiter even if it appears "inside" a bracketed segment.

New(uCalc::Transformer, t)// We want to capture the function name and the first part of the args// but stop immediately at a comma, even if that comma is inside a nested call.t.FromTo("{@Alpha:f}({args^}, {@All:rest})", "FUNC:{f} ARG1:{args}")wl(t.Transform("process(format(x, y), z)"))

[Expected Output]FUNC:process ARG1:format(x

3. Internal Test (Global vs Local)

Verifying that the global NestingAware setting can be overridden or complemented by the postfix.

// Turn off nesting awareness globallyuc.NestingAware(false)New(uCalc::Transformer, t)// Now, this variable will stop at the first ')' by defaultt.FromTo("test({v})", "GOT:{v}")wl(t.Transform("test((a))"))

[Expected Output]GOT:(a

Strategy & Critique

  • Structural Safety: Nesting awareness is one of uCalc's most powerful features, preventing the "leaky capture" issues common in Regular Expressions. The ^ override should be used sparingly.
  • Logical Use Case: Use ^ when you are dealing with poorly formatted text or when a bracket character is being used as a literal delimiter rather than a structural container.
  • Naming: Renaming the associated method to NestingAware() aligns perfectly with the "Nesting Override" terminology, making the API much more self-documenting.
  • See Also: Refer to Topic 786 for Quote Overrides and Topic 780 for Statement Boundary Overrides.

Examples

Ignore bracket directive ^
				
					using uCalcSoftware;

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

t.FromTo("begin {body} end",   "bracket not ignored: <{@Self}>");
t.FromTo("begin_ {body^} end", "bracket ignored:     <{@Self}>");

Console.WriteLine(t.Transform("begin (a b c end) end"));
Console.WriteLine(t.Transform("begin_ (a b c end) end"));
				
			
bracket not ignored: <begin (a b c end) end>
bracket ignored:     <begin_ (a b c end>) end
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

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

   t.FromTo("begin {body} end",   "bracket not ignored: <{@Self}>");
   t.FromTo("begin_ {body^} end", "bracket ignored:     <{@Self}>");

   cout << t.Transform("begin (a b c end) end") << endl;
   cout << t.Transform("begin_ (a b c end) end") << endl;
}
				
			
bracket not ignored: <begin (a b c end) end>
bracket ignored:     <begin_ (a b c end>) end
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      
      t.FromTo("begin {body} end",   "bracket not ignored: <{@Self}>")
      t.FromTo("begin_ {body^} end", "bracket ignored:     <{@Self}>")
      
      Console.WriteLine(t.Transform("begin (a b c end) end"))
      Console.WriteLine(t.Transform("begin_ (a b c end) end"))
   End Sub
End Module
				
			
bracket not ignored: <begin (a b c end) end>
bracket ignored:     <begin_ (a b c end>) end
Previous
Next