Struct Source 

pub struct Source { /* private fields */ }

Source::open on a file retains the primary bytes and permits constrained acquisition of referenced files beneath the file’s canonical containing directory; Source::with_acquisition_root widens that root at construction, and never from a parser. Source::from_bytes grants no filesystem access; referenced content reaches an in-memory source only through Source::with_named_buffer.

Implementations

impl Source

pub fn open(path: impl Into<PathBuf>) -> Result<Self, Error>

Acquire a file eagerly or a directory lazily.

pub fn from_bytes( name: impl Into<String>, bytes: impl Into<Arc<[u8]>>, ) -> Result<Self, Error>

Retain a caller-owned binary or text buffer. An Arc<[u8]> argument is retained without copying; a Vec<u8> is copied once into the shared buffer, since Arc<[u8]> needs its own allocation.

pub fn with_named_buffer( self, name: impl Into<String>, bytes: impl Into<Arc<[u8]>>, ) -> Result<Self, Error>

Supply one referenced buffer to an in-memory source under the relative name a format uses to refer to it. This is the only way referenced content reaches a source built by Source::from_bytes; such a source never touches the filesystem.

pub fn with_acquisition_root( self, root: impl Into<PathBuf>, ) -> Result<Self, Error>

Widen the acquisition root of a file source to a directory that contains the file, selected while constructing the source. A parser can never widen the root.

pub fn with_format(self, format: FormatId) -> Self

Select one parser explicitly while retaining the same source owner.

pub fn name(&self) -> &str

pub const fn format(&self) -> Option<&FormatId>

pub fn is_directory(&self) -> bool

pub fn primary_buffer(&self) -> Result<SourceBuffer, Error>

Borrow the sole primary buffer of a file or memory source.

pub fn buffer(&self, name: &ArtifactPath) -> Result<SourceBuffer, Error>

Acquire and retain one file of a directory source by its root relative name.

pub fn root_buffer(&self, name: &str) -> Result<SourceBuffer, Error>

Acquire and retain one file beneath the acquisition root by its root relative name, for a parser that resolves referenced names itself and hands over the resolved result. An in-memory source consults the buffers the caller supplied.

pub fn selected_acquisition_root(&self) -> Option<&Path>

The canonical root selected with Source::with_acquisition_root, None when the root defaulted to the containing directory or the source is not file backed. Read-only context for a parser’s own resolution and refusal wording; acquisition itself always goes through this source.

pub fn referenced_buffer( &self, referrer: &SourceBuffer, name: &str, ) -> Result<SourceBuffer, Error>

Acquire and retain one file referenced by referrer, resolved against the referring file’s directory and confined beneath the acquisition root. An in-memory source resolves the same name against the buffers the caller supplied and never touches the filesystem.

pub fn entry_names(&self) -> Result<Vec<ArtifactPath>, Error>

The root relative file names of a directory source, in sorted order, so a directory format can report files outside its profile without touching the filesystem itself. Symbolic links are listed by name and refused if acquired. The listing is bounded by the referenced file budget; a directory holding more entries is refused.

pub fn acquired_buffers(&self) -> Vec<SourceBuffer>

Buffers already retained by this source, in deterministic name order.

Trait Implementations

impl Clone for Source

fn clone(&self) -> Source

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Source

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

Formats the value using the given formatter.