{@Doc}

Source Document Keyword

Description: A replacement-only keyword that returns the entire source text of the document currently being transformed.

The {@Doc} keyword is used within the replacement string of a uCalc::Transformer rule. Unlike pattern-based variables that refer only to the captured segment of text, {@Doc} provides a way to reference the absolute source string in its entirety.

Usage Context

{@Doc} is primarily used when a transformation needs to wrap or re-contextualize the entire input. For example, if a rule identifies a specific document type header, it can use {@Doc} to wrap the entire file content in a new set of tags.

Comparison: {@Doc} vs {@Self}

• {@Self}: Returns only the specific portion of text that was matched by the pattern.
• {@Doc}: Returns the full original source document that was passed into the transformer.

Important Note on Evaluation

{@Doc} typically returns the document as it existed at the start of the current transformation pass. If multiple rules are firing sequentially, {@Doc} may not reflect the intermediate "dirty" state of the document until the pass is completed.

Examples

1. Succinct (Quick Start: Global Wrapper)

Wrapping the entire document in a Markdown code block whenever a specific trigger keyword is found.

New(uCalc::Transformer, t)// Match 'WRAP_ALL' and replace with the whole doc inside backtickst.FromTo("WRAP_ALL", "```\n{@Doc}\n```")wl(t.Transform("Line 1\nLine 2\nWRAP_ALL"))

[Expected Output]

Line 1Line 2WRAP_ALL

2. Practical (Real World: Signature/Footer Injection)

Using a match at the end of a file to append a signature block while preserving the entire document content.

New(uCalc::Transformer, t)// Match the word 'END' at the end of the doc and append a footert.FromTo("END{@End}", "{@Doc}\n---\nGenerated by uCalc")var(string, input) = "Document Content\nEND"wl(t.Transform(input))

[Expected Output]

Document ContentEND---Generated by uCalc

3. Internal Test (Document Integrity)

Verifying that {@Doc} captures the full source regardless of which specific token triggers the match.

New(uCalc::Transformer, t)t.FromTo("TRIGGER", "FULL_DOC_IS: [{@Doc}]")wl(t.Transform("Start TRIGGER End"))

[Expected Output]Start FULL_DOC_IS: [Start TRIGGER End] End

Strategy & Critique

• Efficiency for Large Files: Using {@Doc} in a replacement causes the engine to handle a potentially very large string. In multi-megabyte files, it is generally better to use positional anchors like {@Beginning} or {@End} rather than constantly referencing the whole document in every rule.
• Naming: The name {@Doc} is concise but might be confused with a structured "document object" (like a DOM). In this context, it is strictly the raw source string.
• Critique: If {@Doc} is used in a rule that matches multiple times, the replacement will result in the entire document being inserted multiple times. It is almost always best used in rules that are guaranteed to match only once (e.g., using {@Beginning} or {@End}).