uCalc API Version: 2.1.3-preview.2 Released: 6/17/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.

Insert

Method

Product:

Transformer Library

Class:

Tokens

Defines a new token and inserts it at a specific position in the precedence list, providing explicit control over its matching priority.

Syntax

Insert(int32, string, TokenType, string, int, RegExGrammar)

Parameters

insertionIndex

int32

The index where the new token definition will be inserted. Positive values (`0`, `1`, `2`...) specify an absolute position from the beginning (lowest precedence). Negative values (`-1`, `-2`...) specify a position relative to the end (highest precedence).

regexPattern

string

The regular expression that defines the token's pattern.

tokenType

TokenType

(Default = TokenType::Generic)

The lexical category of the token, which determines its parsing behavior.

closingBracketRegex

string

(Default = "")

An optional regex pattern for the corresponding closing bracket if this token is an opening bracket.

subMatchGroup

int

(Default = 0)

The 1-based index of a capture group within the regex. If greater than 0, the content of this group is used as the token's value instead of the entire match.

regexGrammar

RegExGrammar

(Default = RegExGrammar::Default)

The regular expression grammar to use for parsing the pattern.

Return

Item

Returns the newly created token as an Item object, which can be used to further configure its properties.

Remarks

The Insert method is a convenience overload for the Add method that emphasizes control over a token's precedence. It allows you to define a new token and specify its exact position in the token evaluation list.

⚙️ Understanding Token Precedence & `insertionIndex`

uCalc's tokenizer evaluates token patterns in a Last-In, First-Out (LIFO) order. By default, the most recently added token has the highest index and is checked first, giving it the highest precedence. The insertionIndex parameter allows you to override this default behavior with fine-grained control.

Index Type	Value	Behavior
Positive (Absolute)	`0`	Inserts at the very beginning of the list, giving the token the lowest possible precedence.
	`1`, `2`, ...	Inserts at the specified absolute index, pushing subsequent tokens to a higher index.
Negative (Relative)	`-1`	Appends to the end of the list, giving the token the highest possible precedence (same as default `Add`).
	`-2`, `-3`, ...	Inserts relative to the end of the list (`-2` is second to last), allowing for high-precedence positioning.

Why Use `Insert` vs. `Add`?

While Add also has an insertionIndex parameter, Insert makes the intent clearer when precedence is your primary concern. It is the ideal tool for implementing classic lexer design patterns, such as defining specific keywords with high precedence and a general-purpose identifier with low precedence.

💡 Comparative Analysis

In traditional compiler tools like ANTLR or Flex/Bison, token precedence is often determined by the order of rules in a static grammar file. To change a token's priority, you must edit the file and recompile.

uCalc's Insert method is part of a fully dynamic and programmatic system. You can add, remove, and reorder tokens at runtime, allowing for unparalleled flexibility in creating adaptive or user-configurable parsers. This is a significant advantage over static parsing systems.