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.

{@Newline}

Product: 

Class: 

Remarks

Description: A structural category matcher that identifies any token defined as a line break or newline character sequence.

The {@Newline} directive (shorthand {@nl}) is used within a uCalc::Transformer to detect boundaries between lines. Because uCalc operates on tokens, {@Newline} is platform-agnostic; it will match whichever line-ending sequence (LF, CRLF, or custom separators) the engine is currently configured to recognize as a line break.

Structural Significance

In many grammars, a newline acts as an implicit statement terminator. {@Newline} allows you to:

  • Enforce formatting: Normalize varied line endings to a single standard.
  • Control Scope: Prevent a match from spanning across multiple lines.
  • Remove Clutter: Clean up unnecessary empty lines in data or code.

Dual Role in Transformation

  • In the Pattern (Match): When used in the first argument of FromTo(), it matches an existing newline token in the input stream.
  • In the Replacement (Insert): When used in the second argument of FromTo(), it inserts the actual line-break character sequence defined in the engine's _newline variable.

Inverse Matching with !

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

  • {@Newline}: Matches a line break.
  • {!Newline}: Matches any token that is not a line break.

This is particularly effective when combined with {@Line} to create precise "horizontal" search patterns that strictly stay within the bounds of a single line.

Examples

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=)>
Replacing all platform-specific newlines with a generic visible tag.
				
					using uCalcSoftware;

var uc = new uCalc();
var t = new uCalc.Transformer();
t.FromTo("{@Newline}", "[BR]");

string input = "Line 1\nLine 2\r\nLine 3";

Console.WriteLine(t.Transform(input));
				
			
Line 1[BR]Line 2[BR]Line 3
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   uCalc::Transformer t;
   t.FromTo("{@Newline}", "[BR]");

   string input = "Line 1\nLine 2\r\nLine 3";

   cout << t.Transform(input) << endl;
}
				
			
Line 1[BR]Line 2[BR]Line 3
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t As New uCalc.Transformer()
      t.FromTo("{@Newline}", "[BR]")
      
      
      Dim input = $"Line 1{vbLf}Line 2{vbCrLf}Line 3"
      Console.WriteLine(t.Transform(input))
   End Sub
End Module
				
			
Line 1[BR]Line 2[BR]Line 3
Identifying and removing redundant empty lines (consecutive newlines).
				
					using uCalcSoftware;

var uc = new uCalc();
var t = new uCalc.Transformer();
// Match two newlines in a row and replace with one
t.FromTo("{@nl} {@nl}", "{@nl}");

string text = "First\n\nSecond\n\nThird";

Console.WriteLine(t.Transform(text));
				
			
First
Second
Third
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   uCalc::Transformer t;
   // Match two newlines in a row and replace with one
   t.FromTo("{@nl} {@nl}", "{@nl}");

   string text = "First\n\nSecond\n\nThird";

   cout << t.Transform(text) << endl;
}
				
			
First
Second
Third
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t As New uCalc.Transformer()
      '// Match two newlines in a row and replace with one
      t.FromTo("{@nl} {@nl}", "{@nl}")
      
      
      Dim text = $"First{vbLf}{vbLf}Second{vbLf}{vbLf}Third"
      Console.WriteLine(t.Transform(text))
   End Sub
End Module
				
			
First
Second
Third
Previous
Next