pub struct Document {
pub path: PathBuf,
pub meta: Value,
pub body: String,
pub carrier: Option<MetaCarrier>,
}Expand description
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: PathBufPath this document was read from (workspace-relative or absolute — the caller decides; prov does not interpret it here).
meta: ValueParsed embedded metadata.
body: StringEverything 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§
Source§impl Document
impl Document
Sourcepub fn parse(path: impl Into<PathBuf>, text: &str) -> Result<Self>
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.
Sourcepub fn split(text: &str) -> Option<(MetaCarrier, &str, &str, &str)>
pub fn split(text: &str) -> Option<(MetaCarrier, &str, &str, &str)>
Zero-copy counterpart to parse: locate a fenced
metadata block in text without parsing it, returning the
MetaCarrier found and the three slices it borrows from text —
(meta_block, body_before, body_after). Mirrors
fig::detect/fig::Embed::extract composed into one step, the same
primitives parse builds its owned, parsed Value from.
The body comes back in two pieces because a block need not sit at an
edge. Frontmatter leaves body_before empty and endmatter leaves
body_after empty, but an HTML <script> data island below a <head>
has host text on both sides, and a single slice cannot name both — the
one-sided view this used to return dropped whichever side it could not
see. Concatenated in order they are Document::body; a caller
splicing text back together wants them separate, since only their
offsets say where the block sat.
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).
Sourcepub fn content_attr(&self) -> Option<&str>
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.
Sourcepub fn manifest_attr(&self) -> Option<&str>
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.
Sourcepub fn is_manifest_node(&self) -> bool
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.
Sourcepub fn manifest_conflicts(&self) -> bool
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.
Sourcepub fn content_path(&self, doc_path: &Path) -> Option<PathBuf>
pub fn content_path(&self, doc_path: &Path) -> Option<PathBuf>
The path of this document’s separated body file — its content target
joined onto its own directory — or None for a combined document, whose
prose is self.body.
Plain path joining, deliberately: content names a file beside the
node (§5’s placement rule), so this is the one link-ish value with no
root-absolute spelling to honour, and staying free of the workspace-root
coordinate is what lets a caller holding a real filesystem path — the
CLI reading a file it was handed — resolve it the same way a caller
holding a workspace-relative one does. Matches the resolution
attach’s reverse lookup and the mutation verbs already make.
Sourcepub fn body_path(&self, doc_path: &Path) -> PathBuf
pub fn body_path(&self, doc_path: &Path) -> PathBuf
The path of the file that actually holds this document’s prose: its
content_path when separated, and doc_path
itself when combined.
This is the path whose extension declares the body’s grammar
(ContentFormat::from_extension).
Reading that off a separated document’s own path asks a .yaml node
what grammar its prose is in, and the honest answer — “none, a config
file has no body” — is the wrong question rather than a wrong answer.
Sourcepub fn is_attachment(&self) -> bool
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.