{@File} lets you insert the contents of a file into a pattern definition or replacement text. Let's say you have a file called Dictionary.txt, which consists of:

a | all | the | words | in | the | dictionary | z

You can define a pattern such as: The word {userword: {@File:'c:\text\Dictionary.txt'} }

The definition will be transformed to: The word {userword: a | all | the | words | in | the | dictionary | z }

In the above example we used a literal file name within quotes. But {@File} can take any string that when evaluated with uCalc.EvalStr would return a file name. So you could have {@File:'c:\text' + '\Dictionary.txt'} or {@File:MyFileName} where MyFileName is a string variable defined in the parent uCalc object, which contains the file name.

{@File}: File Injection Directive

Description: A directive used to load the contents of an external file and insert it into a pattern definition or a transformation replacement string.

Remarks

The {@File} directive allows the uCalc::Transformer to reference external text resources. This is particularly useful for separating logic from content, such as storing large templates, configuration blocks, or documentation footers in separate files.

Timing: Static (@) vs. Dynamic (@@)

Like other directives, the behavior of {@File} depends on the prefix used in the replacement:

• {@File: filename} (Static): The file is loaded once at the moment the rule is created. The contents are "baked" into the rule definition as literal text.
• {@@File: filename} (Dynamic): The file is loaded for every match found during transformation. This allows the filename itself to be captured from the source document.

Path Resolution

The filename parameter should follow the standard path rules of the environment where uCalc is running. If the file cannot be found, the engine will typically insert an empty string or a descriptive error depending on the current error-handling configuration.

Content Treatment

Unlike {@Eval}, which parses the content as an expression, {@File} simply inserts the raw text of the file. If you wish to evaluate the contents of a file as a uCalc expression, you should combine it with {@Eval}, for example: {@Eval: {@File: math_rules.txt}}.

Examples

1. Succinct (Quick Start: Template Injection)

Inserting a standard copyright notice from a file into a document header.

New(uCalc::Transformer, t)// Load the license once during rule setupt.FromTo("{@Beginning} COPYRIGHT", "{@File: license.txt}")wl(t.Transform("COPYRIGHT\nSource Code..."))

[Expected Output]

(Contents of license.txt)Source Code...

2. Practical (Real World: Match-Driven File Inclusion)

Capturing a "module" name from the source text and dynamically loading the corresponding documentation file.

New(uCalc::Transformer, t)// Capture 'mod' and use it to find the filename dynamicallyt.FromTo("import_doc {@Alpha:mod}", "DOC_START\n{@@File: mod + '.txt'}\nDOC_END")wl(t.Transform("import_doc engine"))

[Expected Output]

DOC_START(Contents of engine.txt)DOC_END

3. Internal Test (Literal Integrity)

Verifying that {@File} inserts content literally without performing mathematical evaluation on the file's contents.

New(uCalc::Transformer, t)// If 'data.txt' contains "1+1", the output will be "1+1", not "2"t.FromTo("DATA", "{@File: data.txt}")wl(t.Transform("DATA"))

[Expected Output]1+1

Strategy & Critique

• Separation of Concerns: {@File} is the primary way to keep transformation rules clean. By moving boilerplate text out of the code and into external files, you make the transformer easier to maintain.
• Performance Consideration: Use static {@File} (single @) whenever possible. Dynamic {@@File} (double @@) requires a disk read for every match, which can significantly slow down transformations on large documents.
• Security: Be cautious when using {@@File} with user-provided text, as it could potentially lead to unauthorized file access if the input is not strictly validated.
• See Also: Refer to Topic 771 ({@Eval}) if you need to execute the contents of a file as code.