Skip to main content

Module paths

Module paths 

Source
Expand description

Paths, file identities, and reading files — behind a trait so that all of it is testable.

§Why a trait and not std::fs

Every interesting property of include resolution is about which of several candidate paths is found first: a quoted include preferring the including file’s own directory, a project directory shadowing a system one, an include guard stopping a second visit. A test for any of those needs a specific tree of files, and building one on disk is slow, needs cleanup, and makes the test depend on the filesystem’s case and separator rules rather than on the rules under test.

So reading is a trait, with MemoryFiles for tests and DiskFiles for real use. The resolution logic is then ordinary code with ordinary tests, and the part that touches the disk is small enough to read in one sitting.

§Why a FileId and not a PathBuf

Two spellings of one file have to compare equal. ./a.h, a.h, inc/../a.h and A.H on Windows are one file, and a graph keyed by path would hold four nodes for it — four times the analysis, and a reverse-dependency query that finds one of the four. A FileId is a number that the path table mints once per distinct file, and everything downstream compares numbers.

Structs§

CachedFiles
One read of each file per run — the layer every other layer’s text comes from.
DiskFiles
The real filesystem.
FileId
A file’s identity within one analysis.
MemoryFiles
Files held in memory.
OverlayFiles
One provider in front of another: open documents first, then the disk.
PathInterner
Mints a FileId per distinct path, and remembers which path that was.

Traits§

FileProvider
Reads files. The only thing in this layer that touches a filesystem.

Functions§

join_normalized
Join a directory and a relative path, then normalize.
normalize_path
Normalize a path for comparison: separators unified, . and .. resolved, case folded if asked.
parent_normalized
The directory a path lives in, normalized, or an empty path when there is none.