uCalc API Version: 2.1.3-preview.2 Released: 6/17/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.

Verbatim Capture ~

Product: 

Class: 

Remarks

Verbatim Capture

Shortcut: ~Associated Method: NestedMatchAware(bool)

Description: A postfix modifier that allows a variable to ignore other pattern boundaries during capture, treating the text as a verbatim block.

By default, uCalc is "Nested Match Aware." As a variable moves through text to satisfy a capture, it remains aware of all other active patterns in the transformer. If it encounters text that matches another rule, it treats that entire match as an unbreakable unit (a boundary). It will complete that other match before continuing its own capture, ensuring that it never "crosses" or partially consumes another potential anchor match.

The Verbatim Capture (~) postfix is used to disable this boundary awareness for a specific variable.

Boundary Logic

  • Default (Nested Match Aware): The variable respects the boundaries of other patterns. If it's capturing "everything until X" and hits the start of another pattern, it waits for that pattern to finish and includes it as a block.
  • Verbatim Capture (~): The variable ignores all other patterns. It acts as a "bulldozer," capturing every character/token purely based on its own termination criteria, regardless of whether it is splitting another rule's potential match in half.

Purpose: Verbatim Preservation

This is used when you need to capture a section of text exactly as it is, without allowing other rules to "claim" parts of the content while the capture is in progress. This ensures the resulting variable contains the literal source text without any structural interference from other patterns.

This is essential when transforming documents that contain "literal" sections—such as code blocks, raw data strings, or pre-formatted text—where internal content must remain untouched by global search-and-replace rules.

The NestedMatchAware() Method

You can toggle this behavior globally using the NestedMatchAware() method on the uCalc object.

  • uc.NestedMatchAware(true): (Default) Variables respect the boundaries of other patterns during capture.
  • uc.NestedMatchAware(false): All variables behave as if they have the ~ postfix, ignoring other pattern boundaries.

Strategy & Critique

  • Structural Safety: The default awareness is what makes uCalc more stable than regex for complex grammars. It prevents rules from "fighting" over the same characters in a way that leads to unpredictable results.
  • Verbatim Intent: Use ~ when the captured text is meant to be stored or moved without any modification or structural analysis.
  • Naming: NestedMatchAware() is appropriate because it describes the engine's ability to "see" and respect other potential matches while it is busy fulfilling the current one.
  • See Also: Refer to Topic 779 (Immediate Transform) for the reverse behavior (forcing transformation during capture).

Examples

Pattern directive to skip nested pattern matching
				
					using uCalcSoftware;

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

t.FromTo("start {etc} end", "<{@Self}>");
t.FromTo("start2 {etc~} end", "<{@Self}>");

Console.WriteLine(t.Transform("start start2 a b c end end"));
Console.WriteLine(t.Transform("start2 start a b c end end"));
				
			
<start start2 a b c end end>
<start2 start 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("start {etc} end", "<{@Self}>");
   t.FromTo("start2 {etc~} end", "<{@Self}>");

   cout << t.Transform("start start2 a b c end end") << endl;
   cout << t.Transform("start2 start a b c end end") << endl;
}
				
			
<start start2 a b c end end>
<start2 start 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("start {etc} end", "<{@Self}>")
      t.FromTo("start2 {etc~} end", "<{@Self}>")
      
      Console.WriteLine(t.Transform("start start2 a b c end end"))
      Console.WriteLine(t.Transform("start2 start a b c end end"))
   End Sub
End Module
				
			
<start start2 a b c end end>
<start2 start a b c end> end
Previous
Next