Struct FileAccess 

pub struct FileAccess { /* private fields */ }

Tracked, confined access to the project’s files.

Implementations

impl FileAccess

pub fn new(root: &Path) -> Self

Anchor reads at a project root, canonicalizing it.

Every containment check compares against the root, so it has to be canonical or a symlinked checkout would fail every check. Callers that already hold a canonical root should use FileAccess::rooted instead — this is one syscall, and the engine builds an access per file.

pub fn rooted(root: PathBuf) -> Self

Anchor reads at an already-canonical root.

Cheap enough to call per file, which is what the engine does: a fresh access per file makes it structurally impossible for one file’s reads to be recorded against another’s, rather than making it depend on a reset being called in the right place.

pub fn root(&self) -> &Path

The project root reads are confined to.

pub fn read(&self, path: &str) -> Result<Option<String>, ReadError>

Read a file’s text, or None if nothing is there.

Errors

ReadError if the path escapes the root, is absolute, or holds something that is not text. Absence is not an error — a rule asking whether a config is present should not have to catch to find out.

pub fn hash_of(&self, path: &str) -> Result<Option<ContentHash>, ReadError>

The hash of a file’s bytes, or None if nothing readable is there.

Goes through the same resolution every other read does, so it is confined the same way and recorded as a dependency exactly as Self::read would be — a caller that asked only for the hash still depended on the file, and an entry that did not list it would validate after the file changed.

What it saves is the text: a caller holding a parse of these bytes wants to know whether the parse is still the right one, and that is a comparison against a digest the memo already computed. Returning the String for it would clone a whole declaration file per importer to answer a question about thirty-two bytes.

None covers absence and a file that is there but is not text. A binary file is hashed — the dependency it becomes carries that digest — but it cannot be parsed, and this method answers a caller asking whether it holds the current parse of these bytes. For a file no parse can be made of, the answer is no however the bytes hash.

Errors

ReadError if the path escapes the root or is absolute — the same refusals Self::read makes, for the same reasons.

pub fn exists(&self, path: &str) -> Result<bool, ReadError>

Whether a file is there.

A file that exists but is not text still exists — this answers the question asked, where returning false would claim something untrue about the filesystem.

Errors

ReadError if the path escapes the root or is absolute.

pub fn dependencies(&self) -> Vec<TrackedRead>

Everything read so far, in path order.

pub fn clear(&self)

Forget everything, for an embedder reusing one access across several files.

The engine does not use this — it builds an access per file, so there is nothing to forget. Kept because reuse is a reasonable thing for an embedder to want, and a half-populated access is not.

Trait Implementations

impl Debug for FileAccess

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.