Struct Document 

pub struct Document {
    pub path: PathBuf,
    pub meta: Value,
    pub body: String,
    pub carrier: Option<MetaCarrier>,
}

A parsed document: its path, its embedded metadata, and its body text.

Metadata is stored as a dynamic Value (a mapping, or Value::Null when the document has no frontmatter) because link fields are configurable and therefore accessed dynamically.

Fields

path: PathBuf

Path this document was read from (workspace-relative or absolute — the caller decides; prov does not interpret it here).

meta: Value

Parsed embedded metadata.

body: String

Everything outside the metadata block (the host prose). Empty for a config document.

carrier: Option<MetaCarrier>

Where the metadata was found, or None when the document has no (well-formed) metadata. Preserved on write.

Implementations

impl Document

pub fn parse(path: impl Into<PathBuf>, text: &str) -> Result<Self>

Parse a document from its full text.

If path has a config extension (.yaml, .yml, .json, .fig, .figl), the entire text is the metadata and the body is empty. Otherwise the embedded metadata block is auto-detected via fig::detect — any archetype fig knows (--- YAML, ;;; JSON, ```fig, ```endmatter) — and parsed in that archetype’s inner format. If there is no (well-formed) block, meta is Value::Null and the whole text is the body. An unterminated opening fence is treated as no metadata — we do not guess where it ends.

pub fn split(text: &str) -> Option<(MetaCarrier, &str, &str)>

Zero-copy counterpart to parse: locate a fenced metadata block in text without parsing it, returning the MetaCarrier found and the two slices it borrows from text — (meta_block, body). Mirrors fig::detect/fig::split composed into one step, the same primitives parse builds its owned, parsed Value from.

Only recognizes a fenced carrier — a whole-file (config) document has no split to offer, since its entire text already is the metadata; a caller steering by path extension (as parse does via whole_file_format) should check that first. Returns None when text opens no known archetype, or its opening fence has no matching close (an unterminated fence degrades to “no metadata”, matching parse).

The caller who wants the parsed Value should use parse instead; this exists for one who wants to defer parsing to their own deserializer, or just needs the raw borrowed text (e.g. to detect which archetype a document uses without allocating).

pub fn path(&self) -> &Path

The document’s path.

pub fn has_meta(&self) -> bool

true if the document declares any embedded metadata mapping.

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

The raw content attribute — the relative path to a separated document’s body file — or None for an ordinary (combined) document whose body is self.body. A separated document is a whole-file metadata document (.yaml/.json/.figl) that points at its prose body in a sibling file, keeping both halves plain text and linked.

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

The raw manifest attribute — the relative path to the manifest document listing the files this node stands for — or None for a node that stands for itself.

The bulk counterpart of content_attr and mutually exclusive with it: a node covers one payload or a set of them, never both. See manifest for the record shape.

pub fn is_manifest_node(&self) -> bool

true when this document is a manifest node: it declares a manifest pointer, so the files it stands for are listed there rather than being a single content payload.

pub fn manifest_conflicts(&self) -> bool

true when this document declares both content and manifest — a node claiming to be a single payload’s sidecar and a whole directory’s at once. Neither reading is safe to pick, so the pair is reported rather than resolved.

pub fn is_attachment(&self) -> bool

true when this document is an attachment sidecar: a whole-file metadata document whose content points at an opaque payload rather than a prose body. Recognized two ways, so a hand-written sidecar need not be verbose: an explicit attachment: true flag (what prov’s Workspace::attach writes), or a content target whose extension prov cannot read as text.

A separated prose document (content → a .md/.dj/.html body) is deliberately not an attachment: its body is a prov document in its own right, scanned for links and titles; an attachment’s payload is bytes prov never opens.

Trait Implementations

impl Clone for Document

fn clone(&self) -> Document

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Document

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

Formats the value using the given formatter.