Struct Overlay 

pub struct Overlay { /* private fields */ }

The text of the buffers an editor holds open, to be read in place of what is on disk.

A module’s text normally comes from its file. A language server checks what the editor holds, which differs from the disk until the user saves, so the checking entry points (check_package and check_package_with_tests) take an Overlay and every .zel file is read through it. The functions that write a build take none: no build is ever written from the text of a buffer.

An Overlay is a concrete type and not a trait, because it is the only source of text other than the disk anything wants. The functions that take it take an &Overlay where a &dyn would go, so making it one later changes a type and no call graph.

The rules, which outlive the ticket (TOOL-2) that set them:

• A path is normalised before every comparison, on both sides. insert, remove and every lookup canonicalize the deepest ancestor of the path that exists on disk and append the rest unchanged, so a path that is not on disk yet still normalises. The two sides are spelled differently otherwise: package roots are canonicalized by resolve, so a walk yields paths under the canonical root, while a caller’s path is whatever its editor reported (/tmp/.. against /private/tmp/.. on macOS). The walk follows symbolic links, so a file reached through one is matched by where it points. Normalisation is for the lookup only: a module is still named from the path the walk yielded.
• The walk adds what only the overlay holds. After the walk of a source root, every key that ends in .zel, sits under the normalised form of that root and was not matched by a walked file is loaded too, in path order, and named by its path under the normalised root. A tests/ that is not on disk does not stop that, but a src/ that is not on disk is the error it always is, whatever the overlay holds.
• It only replaces and adds. There is no way to say a file on disk is gone: an editor that deletes a module deletes the file, and the next walk does not find it.
• Only .zel sources go through it. A key that does not end in .zel is ignored, so a caller may hand over every open buffer unfiltered. The manifest is read from disk, because one being typed is malformed most of the time and its error would clear every .zel diagnostic of the package; a facade’s companion .mjs is read from disk too, by a build that writes, which takes no overlay.
• The package has to exist on disk, with its zelkova.toml and its src/, for the overlay to apply to it. A package that exists only in memory is out of scope.

Implementations

impl Overlay

pub fn new() -> Overlay

An overlay holding no buffer: every file is read from disk.

pub fn insert(&mut self, path: impl AsRef<Path>, text: String)

Hold text as the contents of the file at path, replacing any earlier text for the same file.

pub fn remove(&mut self, path: impl AsRef<Path>) -> Option<String>

Stop holding the file at path, so it is read from disk again. Returns its text if it was held.

Trait Implementations

impl Clone for Overlay

fn clone(&self) -> Overlay

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Overlay

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

Formats the value using the given formatter.

impl Default for Overlay

fn default() -> Overlay

Returns the “default value” for a type.