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.

Variables and Anchors

Product: 

Class: 

Remarks

uCalc patterns are constructed using two fundamental building blocks: Anchors and Variables. While effective patterns often combine both to define structure and capture data, a valid pattern may consist of only anchors, only variables, or a mixture of both.

  • Anchors (Literals): Text that must appear in the source string.
    • Example: In the pattern Code: {val}, the text Code: serves as the anchor. A pattern like Error consists solely of an anchor.
    • Tokenization Note: Because uCalc is token-based, a sequence like Code: actually represents two distinct anchors: Code and :. Unless WhitespaceSensitive is explicitly enabled, Code: will match both Code: and Code : equally.
  • Variables (Captures): Named placeholders enclosed in curly braces {...}.
    • Example: In the pattern Code: {val}, the variable {val} captures the dynamic content immediately following the anchors.
    • Pure Variable Patterns: Patterns can be purely dynamic. For instance, {mytoken:1} captures exactly one token of any kind, while {groupA:2}{groupB:3} captures 2 tokens followed by 3 tokens.
    • Stop Condition: An unconstrained variable captures content until:
      1. The Next Anchor defined in the pattern is found.
      2. The End of the String is reached.
      3. A Statement Separator is encountered (e.g., a newline or semicolon).
      • Note: For the default list of statement separators, see the topic Matching by token category -> Introduction.
      • Customizing Separators: If you need newlines to be treated as whitespace rather than separators, you can modify the token definitions. (See the Whitespace topic for details on releasing tokens like _token_newline or redefining them).

Escaping Characters:Because { and } are reserved for variable definitions, if you need to match them as literal anchors, you must enclose them in single quotes.

  • Correct: func '{' {body} '}' (Matches func { ... })
  • Incorrect: func { {body} } (This does not generate a syntax error, but it fails to capture literal braces. Instead, it interprets the inner structure as a variable definition or nested expression, leading to unexpected matching behavior.)

Comparative Analysis: Why uCalc?

  • vs. Regex (Named Groups):
    • Simplicity: In Regex, defining a named capture and an anchor requires complex syntax escaping: Code:\s*(?<val>.*). In uCalc, it is simply Code: {val}.
    • Implicit Boundaries: Regex is greedy by default. uCalc variables are "smart-lazy"—they automatically stop at the next anchor or statement separator without requiring complex look-ahead assertions.
  • vs. String.Split (Native Code):
    • Structure: Using Split(':') relies on array indices (parts[1]). uCalc Variables preserve context and allow you to access data by Name (e.g., referencing {val} in replacements or callbacks) rather than fragile numeric indices.

Examples

Variables and anchors
				
					using uCalcSoftware;

var uc = new uCalc();
var t = uc.NewTransformer();
t.FromTo("is {etc} see", "({@Self})");
Console.WriteLine(t.Transform("This is a test to see how anchors/variables work"));
				
			
This (is a test to see) how anchors/variables work
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto t = uc.NewTransformer();
   t.FromTo("is {etc} see", "({@Self})");
   cout << t.Transform("This is a test to see how anchors/variables work") << endl;
}
				
			
This (is a test to see) how anchors/variables work
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      t.FromTo("is {etc} see", "({@Self})")
      Console.WriteLine(t.Transform("This is a test to see how anchors/variables work"))
   End Sub
End Module
				
			
This (is a test to see) how anchors/variables work
More on variables and anchors
				
					using uCalcSoftware;

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

// Variables are {etc} and {ch}
// Anchors are "This", either "a small" or "an easy", and "Test"

t.FromTo("This {etc} {ch: a small | an easy } Test", "<{etc}> ({ch}) experiment");
Console.WriteLine(t.Transform("This is such an easy test."));
				
			
<is such> (an easy) experiment.
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

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

   // Variables are {etc} and {ch}
   // Anchors are "This", either "a small" or "an easy", and "Test"

   t.FromTo("This {etc} {ch: a small | an easy } Test", "<{etc}> ({ch}) experiment");
   cout << t.Transform("This is such an easy test.") << endl;
}
				
			
<is such> (an easy) experiment.
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      
      '// Variables are {etc} and {ch}
      '// Anchors are "This", either "a small" or "an easy", and "Test"
      
      t.FromTo("This {etc} {ch: a small | an easy } Test", "<{etc}> ({ch}) experiment")
      Console.WriteLine(t.Transform("This is such an easy test."))
   End Sub
End Module
				
			
<is such> (an easy) experiment.
Using the same pattern variable multiple times in a pattern
				
					using uCalcSoftware;

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

// When a variable is used multiple times in a pattern,
// such as {tag} in this case, the matching text must be the same

t.FromTo("<{tag}> {words:2} {more} </{tag}>",
"tag={tag}, 2 words={words}, text={more}");

Console.WriteLine(t.Transform("<div>abc xyz more words<b>bold</b></div>").Text);
				
			
tag=div, 2 words=abc xyz, text=more words<b>bold</b>
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

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

   // When a variable is used multiple times in a pattern,
   // such as {tag} in this case, the matching text must be the same

   t.FromTo("<{tag}> {words:2} {more} </{tag}>",
   "tag={tag}, 2 words={words}, text={more}");

   cout << t.Transform("<div>abc xyz more words<b>bold</b></div>").Text() << endl;
}
				
			
tag=div, 2 words=abc xyz, text=more words<b>bold</b>
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      
      '// When a variable is used multiple times in a pattern,
      '// such as {tag} in this case, the matching text must be the same
      
      t.FromTo("<{tag}> {words:2} {more} </{tag}>",
      "tag={tag}, 2 words={words}, text={more}")
      
      Console.WriteLine(t.Transform("<div>abc xyz more words<b>bold</b></div>").Text)
   End Sub
End Module
				
			
tag=div, 2 words=abc xyz, text=more words<b>bold</b>
Basic Key-Value extraction using a colon as an anchor.
				
					using uCalcSoftware;

var uc = new uCalc();
var t = uc.NewTransformer();
// "ID" and ":" are Anchors. "{id}" is the Variable.
t.FromTo("ID: {id}", "Found ID: {id}");
Console.WriteLine(t.Transform("ID: 12345").Text); 
				
			
Found ID: 12345
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto t = uc.NewTransformer();
   // "ID" and ":" are Anchors. "{id}" is the Variable.
   t.FromTo("ID: {id}", "Found ID: {id}");
   cout << t.Transform("ID: 12345").Text() << endl;
}
				
			
Found ID: 12345
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      '// "ID" and ":" are Anchors. "{id}" is the Variable.
      t.FromTo("ID: {id}", "Found ID: {id}")
      Console.WriteLine(t.Transform("ID: 12345").Text)
   End Sub
End Module
				
			
Found ID: 12345
Parsing a standard connection string. Note how the semicolon acts as both an anchor and a natural statement separator.
				
					using uCalcSoftware;

var uc = new uCalc();
var t = uc.NewTransformer();
// Anchors: "Server", "=", ";", "Database"
// Variables: {srv}, {db}
t.FromTo("Server={srv};Database={db};",
"Connecting to database '{db}' on server '{srv}'...");

var connStr = "Server = LocalHost; Database = MyData;";
Console.WriteLine(t.Transform(connStr).Text);
// Note: Spaces around '=' handled automatically by default tokenization.
				
			
Connecting to database 'MyData' on server 'LocalHost'...
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto t = uc.NewTransformer();
   // Anchors: "Server", "=", ";", "Database"
   // Variables: {srv}, {db}
   t.FromTo("Server={srv};Database={db};",
   "Connecting to database '{db}' on server '{srv}'...");

   auto connStr = "Server = LocalHost; Database = MyData;";
   cout << t.Transform(connStr).Text() << endl;
   // Note: Spaces around '=' handled automatically by default tokenization.
}
				
			
Connecting to database 'MyData' on server 'LocalHost'...
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      '// Anchors: "Server", "=", ";", "Database"
      '// Variables: {srv}, {db}
      t.FromTo("Server={srv};Database={db};",
      "Connecting to database '{db}' on server '{srv}'...")
      
      Dim connStr = "Server = LocalHost; Database = MyData;"
      Console.WriteLine(t.Transform(connStr).Text)
      '// Note: Spaces around '=' handled automatically by default tokenization.
   End Sub
End Module
				
			
Connecting to database 'MyData' on server 'LocalHost'...
Previous
Next