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 !fill marker on that key.

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

Source

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

Set a payload field and mark it as a !fill placeholder. Null emits as key: !fill; scalars/sequences as key: !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>)

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.

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.presentation, $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)

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.presentation, $ext.agent, …) don’t clobber each other.

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 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