Struct MdzArchive 

pub struct MdzArchive { /* private fields */ }

An opened, read-only .mdz archive.

The archive bytes are kept in memory; nothing is extracted to disk. Opening is safe for untrusted input: see MdzArchive::open.

Implementations

impl MdzArchive

pub fn open(data: impl Into<Vec<u8>>) -> Result<Self>

Open an archive from its bytes, with the default Limits.

Fails, with a stable ErrorCode, for:

• an invalid ZIP, an encrypted entry, or a compression method other than stored or DEFLATE (ErrorCode::ZipInvalid, ErrorCode::ZipEncrypted);
• entry names that are absolute, contain .., empty or . segments, reserved or control characters, or that duplicate or conflict with another entry after NFC normalization (the ERR_PATH_*, ErrorCode::DuplicatePath and ErrorCode::PathConflict codes);
• entries whose data overlaps another’s, or that exceed the limits (ErrorCode::LimitExceeded);
• an unreadable manifest, a newer major spec.version, or an unrecognized mode.

Symbolic link entries are never followed or read: they’re listed in special_files, with a warning.

pub fn open_with_limits( data: impl Into<Vec<u8>>, limits: Limits, ) -> Result<Self>

Open an archive from its bytes with custom limits.

pub fn open_path(path: impl AsRef<Path>) -> Result<Self>

Read and open the archive at path.

pub fn open_path_with_limits( path: impl AsRef<Path>, limits: Limits, ) -> Result<Self>

Read and open the archive at path with custom limits.

pub fn as_bytes(&self) -> &[u8]

The archive bytes.

pub fn into_bytes(self) -> Vec<u8>

The archive bytes, consuming the archive.

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

The file the archive was opened from, if any.

pub fn limits(&self) -> &Limits

The limits the archive was opened with.

pub fn files(&self) -> impl ExactSizeIterator<Item = &str> + '_

File entry paths, as stored, in archive order. Directory entries and symbolic links aren’t included.

pub fn directories(&self) -> impl ExactSizeIterator<Item = &str> + '_

Directory entries the archive stores, such as an empty folder (each ends in /). A folder only implied by a file path like docs/a.md isn’t listed.

pub fn special_files(&self) -> impl ExactSizeIterator<Item = &str> + '_

Symbolic link entries, as stored. Never followed or read (Section 13.1).

pub fn documents(&self) -> Vec<&str>

Markdown file entries, sorted.

pub fn find(&self, path: &str) -> Option<&str>

The stored file path matching path (NFC, case-sensitive; Section 5.4.1).

pub fn contains(&self, path: &str) -> bool

Whether a file matching path exists (Section 5.4.1).

pub fn find_directory(&self, path: &str) -> Option<&str>

The stored directory entry matching path, with or without its trailing /.

pub fn entry_info(&self, path: &str) -> Option<EntryInfo>

ZIP metadata of the file matching path.

pub fn read_bytes(&self, path: &str) -> Result<Vec<u8>>

A file’s bytes. Fails with ErrorCode::NotFound if there’s no such file, ErrorCode::ZipInvalid if its data is corrupt, and ErrorCode::LimitExceeded if it decompresses past its declared size or the limits.

pub fn read_text(&self, path: &str) -> Result<String>

A file’s text, decoded as UTF-8 (Section 7.1), with a leading BOM removed. Line endings are left as written. Fails with ErrorCode::TextInvalid if the file isn’t UTF-8.

pub fn entry_point(&self) -> Result<String>

The primary Markdown file (Section 5.5). Fails with ErrorCode::EntryPointInvalid or ErrorCode::EntryPointMissing for a bad manifest entryPoint (never a silent fallback), or ErrorCode::EntryPointUnresolved.

pub fn manifest(&self) -> Option<&Manifest>

The parsed manifest.json, with every field kept, or None.

pub fn mode(&self) -> Mode

document or project (Section 5.7).

pub fn title(&self) -> Option<&str>

The manifest title, if it’s a non-empty string.

pub fn ignored_fields(&self) -> &[&'static str]

Descriptive manifest fields with a wrong type or value, which are ignored (Section 6.4).

pub fn warnings(&self) -> &[Diagnostic]

Warnings from opening the archive: symbolic links, repeated manifest members, ignored manifest fields.

pub fn resolve_link( &self, document: &str, link: &str, use_: LinkUse, ) -> LinkTarget

Resolve link written in document of this archive (Sections 9.3–9.6).

Opened from a file, links may reach files in the archive’s own directory and below it, and into archives there. Opened from bytes, links that leave the archive are unresolved (UnresolvedReason::NoHostLocation). For other hosts, use resolve_link with a LinkHost.

pub fn validate(&self) -> Vec<Diagnostic>

Conformance findings for this archive. Never fails.

Opening already rejects what makes an archive unreadable; this adds the entry point, producer-manifest and cover checks to the warnings from opening.

impl MdzArchive

pub fn update(&self, changes: &Update) -> Result<Vec<u8>>

Apply changes and return the new archive bytes (Section 14.1). The archive itself isn’t changed.

• Entries not written or removed are copied as stored: same bytes, compression, timestamp and attributes. Each is checked (CRC-32, limits) before it’s copied.
• Directory entries, such as empty folders, are kept.
• Symbolic links are kept unless removed by name or with Update::drop_special_files; the archive then stays non-conforming and the warning still applies. Writing a file at the same path replaces the link.
• The manifest keeps every field, including unknown ones; it’s added if missing, with the entry point the archive resolved to before.
• The entry point must resolve to the same file afterwards unless Update::entry_point names a new one; otherwise ErrorCode::EntryPointChanged.

Trait Implementations

impl Clone for MdzArchive

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for MdzArchive

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

Formats the value using the given formatter.