include

Documentation

Overview

Package include resolves [include] directives into a single merged *parser.Model. It runs as Stage 1a in the c4drill pipeline (the FIRST pre-processing pass), before template.Expand (Phase 31) and validator.Validate.

Semantics (see .planning/phases/32-include-directive-multi-file/32-CONTEXT.md):

• INC-02: paths resolve relative to the INCLUDING file's directory.
• INC-03: transitive includes resolve recursively.
• INC-04: cycle (self or mutual) is a fatal *parser.ParseError naming the cycle.
• INC-06: once=true opts into the visited-set dedup.
• D-11: a same-file diamond (same canonical path reached via two paths) is auto-deduped silently; a cross-file unit-path collision hard-errors.
• INC-10/D-12: a missing include is an unconditional hard error.
• D-26 (Plan 35-05): include graphs may MIX .toml and .c4d files freely — dispatch is per included file's extension (.c4d -> C4D front-end, .toml -> TOML front-end) and merging happens at Model level; any other extension is a hard error naming the accepted ones (T-35-05-01).

Canonical paths (filepath.Clean + filepath.Abs) are the key for BOTH the cycle stack and the visited-set. filepath.Abs does NOT resolve symlinks (T-32-05 accepted for v1.10 — C4Drill is author-controlled local tooling).

Index

• func Resolve(entry *parser.Model, entryDir, entryFile string) (*parser.Model, error)
• func ResolveWithReader(entry *parser.Model, entryDir, entryFile string, ...) (*parser.Model, error)

Functions

func Resolve

func Resolve(entry *parser.Model, entryDir, entryFile string) (*parser.Model, error)

Resolve walks entry.Includes and merges every transitively-included file into entry, returning the merged model. entryDir is the directory of the entry file (filepath.Dir of the entry path) so [include] paths resolve relative to the including file (INC-02), independent of the CLI cwd.

entryFile is the display name of the entry file, used in error attribution for the entry's own [include] directives (so errors name the real entry path, not a placeholder). For nested directives the included file's path is used directly. If entryFile is empty, entryDir is used as the attribution name.

On success, the returned model's .Includes is drained to nil and its .Units/.UnitOrder/.Properties/.Templates/.Instantiations reflect the union of the entry and all transitively-included files per D-09/D-10/D-11/INC-08. Any failure (cycle, missing file, cross-file collision, properties conflict) is a *parser.ParseError naming the relevant file(s).

func ResolveWithReader

func ResolveWithReader(
	entry *parser.Model,
	entryDir, entryFile string,
	read func(path string) ([]byte, error),
) (*parser.Model, error)

ResolveWithReader is Resolve with an injectable file reader: read is called for every transitively-included file's bytes. nil selects os.ReadFile — byte-identical behavior to Resolve. The LSP (issue #32) passes an overlay reader that serves unsaved editor buffers by canonical path, so including documents validate against what the author SEES, not what is on disk; error messages are unaffected (reader failures produce the same include-not-found attribution as missing files).