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§
- Cached
Files - One read of each file per run — the layer every other layer’s text comes from.
- Disk
Files - The real filesystem.
- FileId
- A file’s identity within one analysis.
- Memory
Files - Files held in memory.
- Overlay
Files - One provider in front of another: open documents first, then the disk.
- Path
Interner - Mints a
FileIdper distinct path, and remembers which path that was.
Traits§
- File
Provider - 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.