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.

{@Whitespace}

Product: 

Class: 

Remarks

Description: A category matcher that identifies any token defined as whitespace, primarily horizontal spacing like spaces and tabs.

The {@Whitespace} directive (shorthand {@ws}) is used within a uCalc::Transformer to target non-printing characters used for spacing. Unlike many regular expression engines where \s includes newlines, uCalc typically distinguishes between horizontal whitespace ({@Whitespace}) and vertical whitespace ({@Newline}).

If you need for newline to be whitespace, you can modify it like this: Tokens["_token_newline"].TypeOfToken = TokenType::Whitespace;

Usage Context

In many parsers, whitespace is ignored or "skipped." However, when building a transformer that preserves formatting or cleans up code, {@Whitespace} allows you to precisely target and manipulate spacing without affecting the line structure.

  • Spaces and Tabs: Automatically matches standard ASCII spaces and horizontal tabs.
  • Token Boundaries: Because uCalc is token-aware, {@Whitespace} will not match characters inside a quoted string unless they have been explicitly tokenized as whitespace tokens by the engine.

Inverse Matching with !

The universal inversion operator ! can be applied to this category:

  • {@Whitespace}: Matches a space or tab.
  • {!Whitespace}: Matches any token that is not whitespace (e.g., numbers, identifiers, or punctuation).

Examples

{@Whitespace}
				
					using uCalcSoftware;

var uc = new uCalc();
var t = uc.NewTransformer();
t.FromTo("{@Whitespace}", ",");

Console.WriteLine(t.Transform("This is   a 'small test' about ' whitespace ' tokens."));
				
			
This,is,a,'small test',about,' whitespace ',tokens.
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto t = uc.NewTransformer();
   t.FromTo("{@Whitespace}", ",");

   cout << t.Transform("This is   a 'small test' about ' whitespace ' tokens.") << endl;
}
				
			
This,is,a,'small test',about,' whitespace ',tokens.
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      t.FromTo("{@Whitespace}", ",")
      
      Console.WriteLine(t.Transform("This is   a 'small test' about ' whitespace ' tokens."))
   End Sub
End Module
				
			
This,is,a,'small test',about,' whitespace ',tokens.
Matching by token type
				
					using uCalcSoftware;

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

t.FromTo("{@String:txt}", "<<InnerQuote={txt}><TxtWithQuotes={txt(0)}>>");
t.FromTo("{@Number:MyNum}", "<NumericValue={MyNum}>");
t.FromTo("{@Bracket:MyBrack}", "<Brack={MyBrack}>");
t.FromTo("{@CloseBracket:CloseBr}", "<CloseBrack={CloseBr}>");
t.FromTo("{@StatementSeparator:Sep}", "<Separator={Sep}>");
t.FromTo("{@Alphanumeric:alpha}", "<Alpha={alpha}>");
t.FromTo("{@Whitespace:ws}", "<whitespace count={@Eval: Length(ws)}>");
t.FromTo("{@Reducible:r}", "<Reducible={r}>");
t.FromTo("{@Newline}", "<New line{@Newline}>");

var s = """
This is   55.2*6 "Hello world";
'Single quote'(parenth)
""";

Console.WriteLine(t.Filter(s).Matches.Text);
				
			
<Alpha=This>
<whitespace count=1>
<Alpha=is>
<whitespace count=3>
<NumericValue=55.2>
<Reducible=*>
<NumericValue=6>
<whitespace count=1>
<<InnerQuote=Hello world><TxtWithQuotes="Hello world">>
<Separator=;>
<New line
>
<<InnerQuote=Single quote><TxtWithQuotes='Single quote'>>
<Brack=(>
<Alpha=parenth>
<CloseBrack=)>
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

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

   t.FromTo("{@String:txt}", "<<InnerQuote={txt}><TxtWithQuotes={txt(0)}>>");
   t.FromTo("{@Number:MyNum}", "<NumericValue={MyNum}>");
   t.FromTo("{@Bracket:MyBrack}", "<Brack={MyBrack}>");
   t.FromTo("{@CloseBracket:CloseBr}", "<CloseBrack={CloseBr}>");
   t.FromTo("{@StatementSeparator:Sep}", "<Separator={Sep}>");
   t.FromTo("{@Alphanumeric:alpha}", "<Alpha={alpha}>");
   t.FromTo("{@Whitespace:ws}", "<whitespace count={@Eval: Length(ws)}>");
   t.FromTo("{@Reducible:r}", "<Reducible={r}>");
   t.FromTo("{@Newline}", "<New line{@Newline}>");

   auto s = R"(This is   55.2*6 "Hello world";
'Single quote'(parenth))";

   cout << t.Filter(s).Matches().Text() << endl;
}
				
			
<Alpha=This>
<whitespace count=1>
<Alpha=is>
<whitespace count=3>
<NumericValue=55.2>
<Reducible=*>
<NumericValue=6>
<whitespace count=1>
<<InnerQuote=Hello world><TxtWithQuotes="Hello world">>
<Separator=;>
<New line
>
<<InnerQuote=Single quote><TxtWithQuotes='Single quote'>>
<Brack=(>
<Alpha=parenth>
<CloseBrack=)>
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      
      t.FromTo("{@String:txt}", "<<InnerQuote={txt}><TxtWithQuotes={txt(0)}>>")
      t.FromTo("{@Number:MyNum}", "<NumericValue={MyNum}>")
      t.FromTo("{@Bracket:MyBrack}", "<Brack={MyBrack}>")
      t.FromTo("{@CloseBracket:CloseBr}", "<CloseBrack={CloseBr}>")
      t.FromTo("{@StatementSeparator:Sep}", "<Separator={Sep}>")
      t.FromTo("{@Alphanumeric:alpha}", "<Alpha={alpha}>")
      t.FromTo("{@Whitespace:ws}", "<whitespace count={@Eval: Length(ws)}>")
      t.FromTo("{@Reducible:r}", "<Reducible={r}>")
      t.FromTo("{@Newline}", "<New line{@Newline}>")
      
      Dim s = "This is   55.2*6 ""Hello world"";
'Single quote'(parenth)"
      
      Console.WriteLine(t.Filter(s).Matches.Text)
   End Sub
End Module
				
			
<Alpha=This>
<whitespace count=1>
<Alpha=is>
<whitespace count=3>
<NumericValue=55.2>
<Reducible=*>
<NumericValue=6>
<whitespace count=1>
<<InnerQuote=Hello world><TxtWithQuotes="Hello world">>
<Separator=;>
<New line
>
<<InnerQuote=Single quote><TxtWithQuotes='Single quote'>>
<Brack=(>
<Alpha=parenth>
<CloseBrack=)>
Using {@Whitespace} and {@Exec} to Count Indentation (for Python or YAML-like text)
				
					using uCalcSoftware;

var uc = new uCalc();
// Using {@Whitespace} to Count Indentation
// A common use case for parsing structured text (like Python or YAML)
// is capturing the exact whitespace at the start of a line.

uc.DefineVariable("IndentLen");

var t = uc.NewTransformer();
t.Text = "    Item 1"; // Indented by 4 spaces

// Capture the leading whitespace into 'w' and evaluate its length
t.FromTo("{@Whitespace:w} Item {id}", "<{@Self}>{@Exec: IndentLen = Length(w)}");
t.Transform();
// We can now analyze the captured whitespace
Console.WriteLine($"Indentation length: {uc.EvalStr("IndentLen")}");
				
			
Indentation length: 4
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   // Using {@Whitespace} to Count Indentation
   // A common use case for parsing structured text (like Python or YAML)
   // is capturing the exact whitespace at the start of a line.

   uc.DefineVariable("IndentLen");

   auto t = uc.NewTransformer();
   t.Text("    Item 1"); // Indented by 4 spaces

   // Capture the leading whitespace into 'w' and evaluate its length
   t.FromTo("{@Whitespace:w} Item {id}", "<{@Self}>{@Exec: IndentLen = Length(w)}");
   t.Transform();
   // We can now analyze the captured whitespace
   cout << "Indentation length: " << uc.EvalStr("IndentLen") << endl;
}
				
			
Indentation length: 4
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      '// Using {@Whitespace} to Count Indentation
      '// A common use case for parsing structured text (like Python or YAML)
      '// is capturing the exact whitespace at the start of a line.
      
      uc.DefineVariable("IndentLen")
      
      Dim t = uc.NewTransformer()
      t.Text = "    Item 1" '// Indented by 4 spaces
      
      '// Capture the leading whitespace into 'w' and evaluate its length
      t.FromTo("{@Whitespace:w} Item {id}", "<{@Self}>{@Exec: IndentLen = Length(w)}")
      t.Transform()
      '// We can now analyze the captured whitespace
      Console.WriteLine($"Indentation length: {uc.EvalStr("IndentLen")}")
   End Sub
End Module
				
			
Indentation length: 4
Finding instances where there are two or more consecutive whitespace tokens and reducing them to a single space.
				
					using uCalcSoftware;

var uc = new uCalc();
var t = uc.NewTransformer();
// Match two whitespace tokens and replace with one space
t.FromTo("{@Whitespace}", " ");

string messy = "var    x   =  100;";
Console.WriteLine(t.Transform(messy));
				
			
var x = 100;
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto t = uc.NewTransformer();
   // Match two whitespace tokens and replace with one space
   t.FromTo("{@Whitespace}", " ");

   string messy = "var    x   =  100;";
   cout << t.Transform(messy) << endl;
}
				
			
var x = 100;
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      '// Match two whitespace tokens and replace with one space
      t.FromTo("{@Whitespace}", " ")
      
      Dim messy As String = "var    x   =  100;"
      Console.WriteLine(t.Transform(messy))
   End Sub
End Module
				
			
var x = 100;
Replacing all horizontal whitespace with a visible underscore for debugging.
				
					using uCalcSoftware;

var uc = new uCalc();
var t = new uCalc.Transformer();
t.FromTo("{@Whitespace}", "_");

Console.WriteLine(t.Transform("x = 10 + y"));
				
			
x_=_10_+_y
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   uCalc::Transformer t;
   t.FromTo("{@Whitespace}", "_");

   cout << t.Transform("x = 10 + y") << endl;
}
				
			
x_=_10_+_y
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t As New uCalc.Transformer()
      t.FromTo("{@Whitespace}", "_")
      
      Console.WriteLine(t.Transform("x = 10 + y"))
   End Sub
End Module
				
			
x_=_10_+_y
Previous
Next