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.

Optional parts

Product: 

Class: 

Defines sections of a pattern that may or may not exist, and provides syntax for conditional replacements based on whether a match occurred.

Remarks

Optional parts allow you to define sections of a pattern that may or may not exist in the source string. These are enclosed in square brackets [...].

Syntax: Start [ Optional ] End

Behavior

  • Matching: The parser attempts to match the content inside the brackets. If the match succeeds, it consumes the tokens. If it fails (e.g., the tokens don't match or are missing), the parser ignores the optional part and continues matching the rest of the pattern.
  • Variable Capture: If you define a variable inside an optional block (e.g., [{val}]), and the block is not matched, the variable will be empty.

💎 Conditional Replacements

When a variable is defined within an optional block, you can use special syntax in the replacement string to conditionally display content.

SyntaxNameBehavior
{var: ...}Positive ConditionThe content after the colon is inserted only if {var} captured a value.
{!var: ...}Fallback ContentThe content after the colon is inserted only if {var} is empty (did not capture a value).

This provides a powerful, declarative way to handle default values and conditional formatting without needing complex callbacks.

⚠️ Syntax Warning (Escaping)

Because square brackets [ and ] are reserved for defining optional parts, if you need to match a literal square bracket in your text (e.g., a JSON array [1,2]), you must enclose the brackets in single quotes: '[' and ']'. This is a common requirement when parsing structured data formats.

Comparative Analysis: Why uCalc?

  • vs. Regex (?):

    • Block Scope: In Regex, making a whole block optional requires parentheses and a question mark: (optional part)?. uCalc's square brackets [optional part] are visually cleaner and mimic standard documentation syntax (like Backus-Naur Form).
    • Nesting: Nesting optional blocks in Regex can become a soup of punctuation ((inner)?outer)?. uCalc uses intuitive nesting [ outer [ inner ] ] that clearly delineates hierarchy.
    • Conditionals: Standard Regex replacements cannot easily say "Insert 'Label: ' only if Group 1 matched." You typically need complex code callbacks. uCalc handles this natively with {var: Label: {var}} and {!var: Default}.

  • vs. Native Code (If/Else):

    • Logic Reduction: Parsing optional data (like a middle name) manually requires multiple if checks or Split logic. uCalc handles the branching internally in a single declarative line.

Examples

A simple optional word.

ID: 790

See: Optional parts 
				
					using uCalcSoftware;

var uc = new uCalc();
var t = new uCalc.Transformer();
t.FromTo("This is a [very] important test", "MATCHED");

// Matches with the optional word
Console.WriteLine(t.Transform("This is a very important test"));

// Also matches without the optional word
Console.WriteLine(t.Transform("This is a important test"));
				
			
MATCHED
MATCHED
Explore 600+ other examples
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   uCalc::Transformer t;
   t.FromTo("This is a [very] important test", "MATCHED");

   // Matches with the optional word
   cout << t.Transform("This is a very important test") << endl;

   // Also matches without the optional word
   cout << t.Transform("This is a important test") << endl;
}
				
			
MATCHED
MATCHED
Explore 600+ other examples
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t As New uCalc.Transformer()
      t.FromTo("This is a [very] important test", "MATCHED")
      
      '// Matches with the optional word
      Console.WriteLine(t.Transform("This is a very important test"))
      
      '// Also matches without the optional word
      Console.WriteLine(t.Transform("This is a important test"))
   End Sub
End Module
				
			
MATCHED
MATCHED
Explore 600+ other examples
A practical example using a fallback content block to provide a default status for log entries.

ID: 791

See: Optional parts 
				
					using uCalcSoftware;

var uc = new uCalc();
var t = new uCalc.Transformer();
// Pattern: Match "Log:", an optional level (Warning or Error), and the message.
// Replacement: Use `{!level:OK}` to insert 'OK' if no level was captured.
t.FromTo("Log: [{level: Warning | Error}] {msg}", "Status: {!level:OK}{level} | Message: {msg}");

Console.WriteLine(t.Transform("Log: This is a standard entry"));
Console.WriteLine(t.Transform("Log: Warning A potential issue was found"));
Console.WriteLine(t.Transform("Log: Error System failure detected"));
				
			
Status: OK | Message: This is a standard entry
Status: Warning | Message: A potential issue was found
Status: Error | Message: System failure detected
Explore 600+ other examples
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   uCalc::Transformer t;
   // Pattern: Match "Log:", an optional level (Warning or Error), and the message.
   // Replacement: Use `{!level:OK}` to insert 'OK' if no level was captured.
   t.FromTo("Log: [{level: Warning | Error}] {msg}", "Status: {!level:OK}{level} | Message: {msg}");

   cout << t.Transform("Log: This is a standard entry") << endl;
   cout << t.Transform("Log: Warning A potential issue was found") << endl;
   cout << t.Transform("Log: Error System failure detected") << endl;
}
				
			
Status: OK | Message: This is a standard entry
Status: Warning | Message: A potential issue was found
Status: Error | Message: System failure detected
Explore 600+ other examples
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t As New uCalc.Transformer()
      '// Pattern: Match "Log:", an optional level (Warning or Error), and the message.
      '// Replacement: Use `{!level:OK}` to insert 'OK' if no level was captured.
      t.FromTo("Log: [{level: Warning | Error}] {msg}", "Status: {!level:OK}{level} | Message: {msg}")
      
      Console.WriteLine(t.Transform("Log: This is a standard entry"))
      Console.WriteLine(t.Transform("Log: Warning A potential issue was found"))
      Console.WriteLine(t.Transform("Log: Error System failure detected"))
   End Sub
End Module
				
			
Status: OK | Message: This is a standard entry
Status: Warning | Message: A potential issue was found
Status: Error | Message: System failure detected
Explore 600+ other examples
A practical example of parsing names with an optional middle name, using a positive conditional block.

ID: 792

See: Optional parts 
				
					using uCalcSoftware;

var uc = new uCalc();
var t = new uCalc.Transformer();
// Pattern: Capture first, optional middle, and last names.
// Replacement: The block `{middle: {middle}}` ensures a leading space is only added if a middle name exists.
t.FromTo("Name: {first:1} [{middle:1}] {last:1}",
"User: {last}, {first}{middle: {middle}}");

Console.WriteLine(t.Transform("Name: John Doe"));
Console.WriteLine(t.Transform("Name: John Quincy Adams"));
				
			
User: Doe, John
User: Adams, John Quincy
Explore 600+ other examples
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   uCalc::Transformer t;
   // Pattern: Capture first, optional middle, and last names.
   // Replacement: The block `{middle: {middle}}` ensures a leading space is only added if a middle name exists.
   t.FromTo("Name: {first:1} [{middle:1}] {last:1}",
   "User: {last}, {first}{middle: {middle}}");

   cout << t.Transform("Name: John Doe") << endl;
   cout << t.Transform("Name: John Quincy Adams") << endl;
}
				
			
User: Doe, John
User: Adams, John Quincy
Explore 600+ other examples
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t As New uCalc.Transformer()
      '// Pattern: Capture first, optional middle, and last names.
      '// Replacement: The block `{middle: {middle}}` ensures a leading space is only added if a middle name exists.
      t.FromTo("Name: {first:1} [{middle:1}] {last:1}",
      "User: {last}, {first}{middle: {middle}}")
      
      Console.WriteLine(t.Transform("Name: John Doe"))
      Console.WriteLine(t.Transform("Name: John Quincy Adams"))
   End Sub
End Module
				
			
User: Doe, John
User: Adams, John Quincy
Explore 600+ other examples
Optional part

ID: 197

See: Syntax Definitions, Optional parts 
				
					using uCalcSoftware;

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

t.FromTo("a [simple] test", "<{@Self}>");

Console.WriteLine(t.Transform("Is this a simple test, or a hard test, or just a test?"));
				
			
Is this <a simple test>, or a hard test, or just <a test>?
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 [simple] test", "<{@Self}>");

   cout << t.Transform("Is this a simple test, or a hard test, or just a test?") << endl;
}
				
			
Is this <a simple test>, or a hard test, or just <a test>?
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 [simple] test", "<{@Self}>")
      
      Console.WriteLine(t.Transform("Is this a simple test, or a hard test, or just a test?"))
   End Sub
End Module
				
			
Is this <a simple test>, or a hard test, or just <a test>?
Explore 600+ other examples
Optional part; value when optional part not used

ID: 198

See: Optional parts 
				
					using uCalcSoftware;

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

t.FromTo("This is a [{adj: simple}] test",
"Let's take the {adj}{!adj:short} test");

Console.WriteLine(t.Transform("This is a test"));
Console.WriteLine(t.Transform("This is a simple test"));
				
			
Let's take the short test
Let's take the simple test
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("This is a [{adj: simple}] test",
   "Let's take the {adj}{!adj:short} test");

   cout << t.Transform("This is a test") << endl;
   cout << t.Transform("This is a simple test") << endl;
}
				
			
Let's take the short test
Let's take the simple test
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("This is a [{adj: simple}] test",
      "Let's take the {adj}{!adj:short} test")
      
      Console.WriteLine(t.Transform("This is a test"))
      Console.WriteLine(t.Transform("This is a simple test"))
   End Sub
End Module
				
			
Let's take the short test
Let's take the simple test
Explore 600+ other examples
Named optional part

ID: 195

See: Optional parts, Replacement 
				
					using uCalcSoftware;

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

t.FromTo("a [{option: small | big }] test",
"a sample test{option: categorized as '{option}'}");

Console.WriteLine(t.Transform("This is a test."));
Console.WriteLine(t.Transform("This is a big test."));
Console.WriteLine(t.Transform("This is a small test."));
Console.WriteLine(t.Transform("This is a random test."));
				
			
This is a sample test.
This is a sample test categorized as 'big'.
This is a sample test categorized as 'small'.
This is a random test.
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 [{option: small | big }] test",
   "a sample test{option: categorized as '{option}'}");

   cout << t.Transform("This is a test.") << endl;
   cout << t.Transform("This is a big test.") << endl;
   cout << t.Transform("This is a small test.") << endl;
   cout << t.Transform("This is a random test.") << endl;
}
				
			
This is a sample test.
This is a sample test categorized as 'big'.
This is a sample test categorized as 'small'.
This is a random test.
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 [{option: small | big }] test",
      "a sample test{option: categorized as '{option}'}")
      
      Console.WriteLine(t.Transform("This is a test."))
      Console.WriteLine(t.Transform("This is a big test."))
      Console.WriteLine(t.Transform("This is a small test."))
      Console.WriteLine(t.Transform("This is a random test."))
   End Sub
End Module
				
			
This is a sample test.
This is a sample test categorized as 'big'.
This is a sample test categorized as 'small'.
This is a random test.
Explore 600+ other examples
Handling an optional trailing semicolon.

ID: 239

See: Optional parts 
				
					using uCalcSoftware;

var uc = new uCalc();
var t = uc.NewTransformer();
t.FromTo("Statement: {val} [;]", "Found: {val}");

Console.WriteLine(t.Transform("Statement: x = 1;")); // Output: Found: x = 1
Console.WriteLine(t.Transform("Statement: y = 2"));  // Output: Found: y = 2
				
			
Found: x = 1
Found: y = 2
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("Statement: {val} [;]", "Found: {val}");

   cout << t.Transform("Statement: x = 1;") << endl; // Output: Found: x = 1
   cout << t.Transform("Statement: y = 2") << endl;  // Output: Found: y = 2
}
				
			
Found: x = 1
Found: y = 2
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("Statement: {val} [;]", "Found: {val}")
      
      Console.WriteLine(t.Transform("Statement: x = 1;")) '// Output: Found: x = 1
      Console.WriteLine(t.Transform("Statement: y = 2"))  '// Output: Found: y = 2
   End Sub
End Module
				
			
Found: x = 1
Found: y = 2
Explore 600+ other examples
Parsing names with an optional middle name.

ID: 240

See: Optional parts 
				
					using uCalcSoftware;

var uc = new uCalc();
var t = uc.NewTransformer();
// Matches "First Last" OR "First Middle Last"
// Constraint Note: We use {name:1} to ensure each variable captures exactly one token.
// Replacement Note: We use {middle: {middle}} instead of just {middle} to prepend
// a space only if the middle name exists.
t.FromTo("Name: {first:1} [{middle:1}] {last:1}",
"User: {last}, {first}{middle: {middle}}");

Console.WriteLine(t.Transform("Name: John Doe"));
Console.WriteLine(t.Transform("Name: John Quincy Adams")); 
				
			
User: Doe, John
User: Adams, John Quincy
Explore 600+ other examples
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto t = uc.NewTransformer();
   // Matches "First Last" OR "First Middle Last"
   // Constraint Note: We use {name:1} to ensure each variable captures exactly one token.
   // Replacement Note: We use {middle: {middle}} instead of just {middle} to prepend
   // a space only if the middle name exists.
   t.FromTo("Name: {first:1} [{middle:1}] {last:1}",
   "User: {last}, {first}{middle: {middle}}");

   cout << t.Transform("Name: John Doe") << endl;
   cout << t.Transform("Name: John Quincy Adams") << endl;
}
				
			
User: Doe, John
User: Adams, John Quincy
Explore 600+ other examples
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      '// Matches "First Last" OR "First Middle Last"
      '// Constraint Note: We use {name:1} to ensure each variable captures exactly one token.
      '// Replacement Note: We use {middle: {middle}} instead of just {middle} to prepend
      '// a space only if the middle name exists.
      t.FromTo("Name: {first:1} [{middle:1}] {last:1}",
      "User: {last}, {first}{middle: {middle}}")
      
      Console.WriteLine(t.Transform("Name: John Doe"))
      Console.WriteLine(t.Transform("Name: John Quincy Adams"))
   End Sub
End Module
				
			
User: Doe, John
User: Adams, John Quincy
Explore 600+ other examples
Optional part in the Transformer

ID: 789

See: Optional parts 
				
					using uCalcSoftware;

var uc = new uCalc();
var t = uc.NewTransformer();
t.FromTo("a [{txt}] b", "a, {txt:{txt}, }b");
Console.WriteLine(t.Transform("a b"));
Console.WriteLine(t.Transform("a x b"));


				
			
a, b
a, x, b
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 [{txt}] b", "a, {txt:{txt}, }b");
   cout << t.Transform("a b") << endl;
   cout << t.Transform("a x b") << endl;


}
				
			
a, b
a, x, b
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 [{txt}] b", "a, {txt:{txt}, }b")
      Console.WriteLine(t.Transform("a b"))
      Console.WriteLine(t.Transform("a x b"))
      
      
   End Sub
End Module
				
			
a, b
a, x, b
Explore 600+ other examples