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.

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 succinct example demonstrating a simple optional word.
				
					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
				
					#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
				
					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
A practical example using a fallback content block to provide a default status for log entries.
				
					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
				
					#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
				
					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
A practical example of parsing names with an optional middle name, using a positive conditional block.
				
					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
				
					#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
				
					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
Optional part
				
					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>?
				
					#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>?
				
					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>?
Optional part; value when optional part not used
				
					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
				
					#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
				
					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
Named optional part
				
					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.
				
					#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.
				
					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.
Handling an optional trailing semicolon.
				
					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
				
					#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
				
					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
Parsing names with an optional middle name.
				
					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
				
					#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
				
					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
				
					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
				
					#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
				
					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
Previous
Next