Documentation
¶
Overview ¶
Package include expands `&include("path")` in txcl source: the named file's contents, written in as a txcl string literal.
Expansion runs on the CLI side, when ops are read from an OPS/ tree (cli/bundle's walker), so everything that deploys, compares or checks ops sees the expanded text and the admin API never sees the directive, exactly like `op://NAME`. It is textual and happens before parsing, so `&include("x")` works anywhere a string literal does, including inside `[...]` and on the right of a WHEN, where a real &function cannot go.
The rules:
- one plain "…" argument: a path relative to the .txcl's directory; `../` is fine as long as the file stays inside its stack directory (OPS/<stack>/), which is what a package carries;
- a regular file, no symlinks anywhere below the stack directory;
- UTF-8 text without NUL, at most MaxBytes; a leading BOM is dropped, everything else is kept byte for byte;
- included text is data, never scanned for further includes.
The literal is written on one line (newlines as \n), so line numbers in the .txcl stay what the author sees.
Index ¶
Constants ¶
const MaxBytes = 1 << 20
MaxBytes caps one included file (the same cap as txco://read-file).
Variables ¶
This section is empty.
Functions ¶
func Expand ¶
Expand replaces each `&include("path")` in src, the .txcl at txclPath, with the file's contents as a string literal. Paths are fsys paths; stackDir is the op's stack directory (e.g. "OPS/ingest"), which every included file must stay inside. deps lists the files read, once each. Errors read `<txclPath>:<line>: &include("<path>"): <reason>`.
func Has ¶
Has reports whether src still contains an &include directive: the admin API's guard against an op uploaded without expansion. Token-based, so text that merely mentions `&include(` inside a string (an expanded include, say) does not count.
func Quote ¶
Quote writes s as a txcl string literal that lexes back to exactly s. Hand-rolled on purpose: txcl knows only \" \\ \n \r \t, and keeps any other backslash sequence (strconv.Quote's \x01, json's \u003c) as literal text. Newlines are escaped so the literal stays on one line. s must not contain NUL, which the lexer reads as end of input.
Types ¶
type Ref ¶
type Ref struct {
Start, End int // byte span of the whole call, `&include` through `)`
Path string // the argument as written
Line int // 1-based line of the `&`
}
Ref is one `&include("path")` in a txcl source.
type SyntaxError ¶
SyntaxError is a malformed directive, or source that does not lex.
func (*SyntaxError) Error ¶
func (e *SyntaxError) Error() string
Source Files