{@Beginning}

Start-of-String Anchor

Description: A structural anchor directive that restricts a pattern match to the very beginning of the source text.

The {@Beginning} directive is used within a uCalc::Transformer to ensure that a specific pattern only triggers if it is found at the absolute start of the input string. It is a zero-width anchor, meaning it does not "consume" any tokens itself; it simply validates that the parser's current position is at index zero.

Positional Logic

In many transformation tasks, the first few tokens of a file contain metadata, headers, or unique identifiers (like a "shebang" in scripts). {@Beginning} allows you to target these elements safely without accidentally matching similar patterns elsewhere in the document.

• Comparison to Regex: {@Beginning} is functionally equivalent to the ^ anchor in standard Regular Expressions when used at the start of a pattern.
• Token Awareness: Even if your input starts with whitespace or comments, {@Beginning} refers to the start of the entire source string, unless the engine is configured to skip those tokens during the initial anchor check.

Examples

1. Succinct (Quick Start: Header Identification)

Replacing a specific keyword only if it appears at the very start of the document.

New(uCalc::Transformer, t)// Match 'ID' only if it's the first thing in the stringt.FromTo("{@Beginning} ID", "IDENTIFIER:")wl(t.Transform("ID 12345"))wl(t.Transform("User ID 123"))

[Expected Output]IDENTIFIER: 12345User ID 123 (No change, since 'ID' was not at the beginning)

2. Practical (Real World: Script Shebang Transpiler)

Using {@Beginning} to find a script indicator and convert it to a standardized header, while ignoring similar text in the body.

New(uCalc::Transformer, t)// Match a '#' followed by a word only at the startt.FromTo("{@Beginning} # {@Alpha:lang}", "--- Language: {lang} ---")var(string, script) = "#uCalc\nprint \"Hello\"; #Note: comments"wl(t.Transform(script))

[Expected Output]--- Language: uCalc ---print "Hello"; #Note: comments

3. Internal Test (Whitespace Sensitivity)

Verifying that {@Beginning} respects the absolute start, even when adjacent to other tokens.

New(uCalc::Transformer, t)t.FromTo("{@Beginning}", "[START]")// Note: If the engine doesn't auto-skip leading spaces, // this will insert [START] at the very front.wl(t.Transform("Data"))

[Expected Output][START]Data

Strategy & Critique

• Performance Optimization: Positional anchors are incredibly efficient. When the transformer sees {@Beginning}, it can immediately skip the rule if the current match attempt is not at the start of the string, saving significant processing time in large documents.
• Naming: The name is clear, though some developers might expect {@Start}. Using {@Beginning} aligns with a more descriptive, semantic approach to structural anchors.
• Critique: If used in a multi-line document where "Beginning" should apply to every line, this directive might be too restrictive. In those cases, use line-based logic instead.
• See Also: Refer to Topic 792 ({@End}) for anchoring to the conclusion of the source string.