Struct Card

Source

pub struct Card { /* private fields */ }

Expand description

A single card-yaml block (root or composable). body is "" when no content follows the closing fence; check card.body().is_empty().

Implementations§

Source §

impl Card

Source

pub fn new(kind: impl Into<String>) -> Result<Self, EditError>

Create a composable card with the given kind, no fields, and an empty body.

Source

pub fn set_field( &mut self, name: &str, value: QuillValue, ) -> Result<(), EditError>

Set a payload field, clearing any !must_fill marker on that key.

Returns EditError::InvalidFieldName when name does not match [A-Za-z_][A-Za-z0-9_]*.

Source

pub fn set_fill( &mut self, name: &str, value: QuillValue, ) -> Result<(), EditError>

Set a payload field and mark it as a !must_fill placeholder. Null emits as key: !must_fill; scalars/sequences as key: !must_fill <value>. Same validation as Card::set_field.

Source

pub fn remove_field( &mut self, name: &str, ) -> Result<Option<QuillValue>, EditError>

Remove a payload field; returns Ok(None) if the name is absent. Same validation as Card::set_field.

Source

pub fn set_ext(&mut self, value: Map<String, Value>) -> Result<(), EditError>

Replace the card’s opaque $ext map wholesale, inserting it at the canonical position (after $quill/$kind/$id, before user fields) when none existed. Passing an empty map records an explicit $ext: {}.

$ext carries out-of-band consumer state (editor renames, agent annotations, …) and is stripped from Document::to_plate_json, so a write here can never affect a render. Any nested comments attached to a replaced $ext are dropped. Returns EditError::ValueTooDeep when the map nests past the §8 depth limit — $ext never reaches the plate JSON, but it does flow through the recursive emit and DTO paths, so it carries the same depth bound as user fields.

Source

pub fn remove_ext(&mut self) -> Option<Map<String, Value>>

Remove the card’s $ext map entirely, returning the previous map if present. This is a blunt escape hatch — it discards every namespace ($ext.editor, $ext.agent, …) at once. To clear consumer state, prefer Card::remove_ext_namespace, which drops only your own slot and leaves sibling consumers’ state intact.

Source

pub fn set_ext_namespace( &mut self, namespace: impl Into<String>, value: Value, ) -> Result<(), EditError>

Merge value into the card’s $ext map under namespace, creating the map when absent and replacing any existing value at that key.

This is the recommended way to write $ext: it preserves sibling namespaces, so independent consumers keying on their own slot ($ext.editor, $ext.agent, …) don’t clobber each other. Returns EditError::ValueTooDeep when the merged map nests past the §8 depth limit (see Card::set_ext); the card’s $ext is unchanged on error.

Source

pub fn remove_ext_namespace(&mut self, namespace: &str) -> Option<Value>

Remove namespace from the card’s $ext map, returning the value that was stored there (or None when the map or the key was absent).

This is the recommended way to clear $ext state: it is the namespace-scoped inverse of Card::set_ext_namespace and preserves sibling namespaces, where Card::remove_ext would wipe them all. When removing the last namespace empties the map, the $ext entry is dropped entirely (not left as $ext: {}), so set_ext_namespace(ns, v) followed by remove_ext_namespace(ns) restores a card that had no $ext to its original state.

Source

pub fn seed(&self) -> Option<&Map<String, Value>>

The raw $seed map (keyed by card-kind), or None. For a parsed, per-kind overlay, index this map by kind and pass the entry to crate::SeedOverlay::from_json. Only the main card carries $seed.

Source

pub fn set_seed_namespace( &mut self, card_kind: impl Into<String>, value: Value, ) -> Result<(), EditError>

Merge a card-kind’s seed overlay value into the card’s $seed map under card_kind, creating the map when absent and replacing any existing overlay for that kind. Sibling kinds are preserved — this is the per-kind-safe writer, the seed analogue of Card::set_ext_namespace. card_kind must be a valid, non-reserved composable kind (EditError::InvalidKindName / EditError::ReservedKind otherwise) — $seed is keyed by composable card-kind, unlike the free-form namespaces of $ext. Returns EditError::ValueTooDeep when the merged map nests past the §8 depth limit; the card is unchanged on error.

Source

pub fn remove_seed_namespace(&mut self, card_kind: &str) -> Option<Value>

Remove card_kind from the card’s $seed map, returning the overlay stored there (or None). When removing the last kind empties the map, the $seed entry is dropped entirely (not left as $seed: {}). The seed analogue of Card::remove_ext_namespace.

Source

pub fn replace_body(&mut self, body: impl Into<String>)

Source §

impl Card

Source

pub fn from_parts(payload: Payload, body: String) -> Self

Create a Card from its parts without validation. For user-facing construction of composable cards use Card::new.

Source

pub fn ext(&self) -> Option<&Map<String, Value>>

Opaque $ext map for out-of-band extension data (UI editor state, agent annotations, …). Carried through Markdown and storage DTO round-trips; never emitted into the plate JSON consumed by backends.

Source