pub struct Source { /* private fields */ }Expand description
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_memory grants no
filesystem access; referenced content reaches an in-memory source only
through Source::with_named_buffer.
Implementations§
Source§impl Source
impl Source
Sourcepub fn open(path: impl Into<PathBuf>) -> Result<Self, Error>
pub fn open(path: impl Into<PathBuf>) -> Result<Self, Error>
Acquire a file eagerly or a directory lazily.
Primary files are limited to 1 GiB unless POWERIO_MAX_PRIMARY_BYTES
supplies a positive decimal byte count. The limit is checked before
allocation. Referenced files have a separate cumulative budget.
POWERIO_MAX_REFERENCED_BYTES overrides that budget (1 GiB by default).
Both variables are read and validated once, before the path is opened,
for file and directory sources alike; the budget is shared by every
clone of the source.
Sourcepub fn from_memory(
name: impl Into<String>,
bytes: impl Into<Arc<[u8]>>,
) -> Result<Self, Error>
pub fn from_memory( 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.
Sourcepub fn from_memory_tree(
name: impl Into<String>,
files: impl IntoIterator<Item = (ArtifactPath, Arc<[u8]>)>,
primary: Option<ArtifactPath>,
) -> Result<Self, Error>
pub fn from_memory_tree( name: impl Into<String>, files: impl IntoIterator<Item = (ArtifactPath, Arc<[u8]>)>, primary: Option<ArtifactPath>, ) -> Result<Self, Error>
Retain a tree of caller-owned files without filesystem access.
A primary path selects a file and resolves its references relative to its containing directory. Without a primary path, the source is a directory. Paths must be unique and portable; the tree shares the referenced-file count, depth, and byte limits of filesystem sources.
Sourcepub fn with_named_buffer(
self,
name: impl Into<String>,
bytes: impl Into<Arc<[u8]>>,
) -> Result<Self, Error>
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_memory; such a source
never touches the filesystem.
Sourcepub fn with_acquisition_root(
self,
root: impl Into<PathBuf>,
) -> Result<Self, Error>
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.
Sourcepub fn with_format(self, format: FormatId) -> Self
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
Sourcepub fn acquisition_byte_limit(&self) -> Result<u64, Error>
pub fn acquisition_byte_limit(&self) -> Result<u64, Error>
Byte limit for cumulative acquisition and expanded archive contents.
Filesystem sources capture POWERIO_MAX_REFERENCED_BYTES when opened;
memory sources read it when a parser requests expansion. Defaults to 1 GiB.
Sourcepub fn primary_buffer(&self) -> Result<SourceBuffer, Error>
pub fn primary_buffer(&self) -> Result<SourceBuffer, Error>
Borrow the sole primary buffer of a file or memory source.
Sourcepub fn buffer(&self, name: &ArtifactPath) -> Result<SourceBuffer, Error>
pub fn buffer(&self, name: &ArtifactPath) -> Result<SourceBuffer, Error>
Acquire and retain one file of a directory source by its root relative name.
Sourcepub fn root_buffer(&self, name: &str) -> Result<SourceBuffer, Error>
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.
Sourcepub fn selected_acquisition_root(&self) -> Option<&Path>
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.
Sourcepub fn referenced_buffer(
&self,
referrer: &SourceBuffer,
name: &str,
) -> Result<SourceBuffer, Error>
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.
Sourcepub fn entry_names(&self) -> Result<Vec<ArtifactPath>, Error>
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.
Sourcepub fn acquired_buffers(&self) -> Vec<SourceBuffer>
pub fn acquired_buffers(&self) -> Vec<SourceBuffer>
Buffers already retained by this source, in deterministic name order.