Documentation
¶
Overview ¶
Package sourceload provides file-finding and load-stack tracking for locating source files across virtual filesystems.
The package is focused on file-path traversal, file loading, and load-stack management — isolated from Scheme evaluation concerns.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrNotFound = werr.NewStaticError("sourceload: file not found")
ErrNotFound is returned when no matching file can be located across all provided search directories.
Functions ¶
func Walk ¶
func Walk(fsys fs.FS, searchDirs []string, accept func(name string) bool, fn func(relPath string)) error
Walk traverses fsys under each search directory, calling fn for every file where accept returns true. Hidden directories (name starting with ".") are skipped. Non-existent directories are silently skipped. Other root-level errors (permission, I/O) are propagated.
accept receives the filename (not the full path). fn receives the slash-separated path relative to the search directory.
No "." fallback — only walks directories explicitly provided. No deduplication — caller handles domain-specific identity. Per-directory errors are accumulated via errors.Join and returned alongside partial results. Individual file-level errors within a directory are skipped (best-effort enumeration).
Types ¶
type Finder ¶
type Finder struct {
// contains filtered or unexported fields
}
Finder locates files within an fs.FS by searching an ordered list of directories. It supports an optional LoadStack for current-directory-relative resolution and an optional canonicalize function applied to resolved paths.
func NewFinder ¶
func NewFinder(fsys fs.FS, searchDirs []string, opts ...FinderOption) *Finder
NewFinder constructs a Finder that searches fsys in the given directories. It panics if fsys is nil.
func (*Finder) Open ¶
Open searches for the named path and returns an open file, the resolved path, and nil on success. It returns ErrNotFound when no match is found.
Search order:
- stack.CurrentDir() — if stack is non-nil, CurrentDir is non-empty, and is not "."
- Each searchDir provided to NewFinder, in order
- FS root "."
The returned path goes through canonicalize (if set) before being returned. Returns ErrNotFound immediately for an empty path argument.
type FinderOption ¶
type FinderOption func(*Finder)
FinderOption is a functional option for Finder.
func WithCanonicalize ¶
func WithCanonicalize(fn func(string) string) FinderOption
WithCanonicalize sets a path transformation applied to every resolved path before it is returned from Open. It does not affect which file is opened — only the returned path string.
func WithStack ¶
func WithStack(s *LoadStack) FinderOption
WithStack attaches a LoadStack to the Finder. When set, the directory of the currently-loading file is searched first (before explicit searchDirs).
type LoadStack ¶
type LoadStack struct {
// contains filtered or unexported fields
}
LoadStack tracks the chain of source files currently being loaded. Each Push records the path of a file being processed; Pop removes it when loading is complete. The stack enables directory-relative resolution of include paths — the current file's directory is the base for includes.
All methods are safe for concurrent use.
func NewLoadStack ¶
func NewLoadStack() *LoadStack
NewLoadStack returns an empty LoadStack with pre-allocated capacity.
func (*LoadStack) Current ¶
Current returns the path at the top of the stack, or "" if the stack is empty.
func (*LoadStack) CurrentDir ¶
CurrentDir returns the directory component of the top path using slash-separated semantics (path.Dir, not filepath.Dir). Returns "" if the stack is empty.
Source Files