Struct Payload 

pub struct Payload { /* private fields */ }

Ordered, comment-preserving payload of a card-yaml block.

Contains the block’s $ entries, user fields, and comments interleaved in source order. See the module docs for the full design.

Implementations

impl Payload

pub fn new() -> Self

Create an empty Payload.

pub fn from_index_map(map: IndexMap<String, QuillValue>) -> Self

Build from an IndexMap of user fields. No $ entries, no comments, no fill markers.

pub fn from_items(items: Vec<PayloadItem>) -> Self

Build from a pre-computed item list (parser and DTO entry point).

pub fn items(&self) -> &[PayloadItem]

Ordered iterator over raw items ($ entries, fields, comments).

pub fn items_mut(&mut self) -> &mut [PayloadItem]

Mutable access to the raw item list. Callers must preserve the invariants (at most one Quill/Kind/Id/Ext, no duplicate field keys, every field name matches [A-Za-z_][A-Za-z0-9_]*) — use the typed mutators when in doubt.

pub fn quill(&self) -> Option<&QuillReference>

The $quill reference, if declared.

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

The $kind value, if declared.

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

The $id value, if declared.

pub fn ext(&self) -> Option<&JsonMap<String, JsonValue>>

The $ext map, if declared. The map is opaque — Quillmark does not interpret its contents and never emits them into the plate JSON.

pub fn seed(&self) -> Option<&JsonMap<String, JsonValue>>

The raw $seed map (keyed by card-kind), if declared. The seeding layer interprets it; it never reaches the plate JSON. For a parsed, per-kind overlay, index this map by kind and pass the entry to crate::SeedOverlay::from_json.

pub fn set_quill(&mut self, reference: QuillReference)

Set or replace the $quill entry. Inserts at canonical position (before any $kind / $id / $ext) when adding. Comments are untouched.

pub fn set_kind(&mut self, kind: impl Into<String>)

Set or replace the $kind entry. Same insertion rules as set_quill.

pub fn set_id(&mut self, id: impl Into<String>)

Set or replace the $id entry. Same insertion rules as set_quill.

pub fn set_ext(&mut self, value: JsonMap<String, JsonValue>)

Set or replace the $ext entry. Same insertion rules as set_quill; the canonical position is after $quill / $kind / $id and before any user field.

Any nested comments previously attached to a replaced $ext entry are dropped (the new value tree may not contain matching positions).

pub fn set_seed(&mut self, value: JsonMap<String, JsonValue>)

Set or replace the $seed entry. Inserted at the canonical position (after $quill / $kind / $id / $ext, before any user field). Nested comments on a replaced $seed are dropped, like set_ext.

pub fn take_ext(&mut self) -> Option<JsonMap<String, JsonValue>>

Remove the $ext entry, returning the previous map if any. Any nested comments attached to the entry are dropped.

pub fn take_seed(&mut self) -> Option<JsonMap<String, JsonValue>>

Remove the $seed entry, returning the previous map if any. Any nested comments attached to the entry are dropped.

pub fn iter(&self) -> impl Iterator<Item = (&String, &QuillValue)> + '_

Iterator over user (key, &value) pairs. Excludes $ entries and comments; preserves source order.

pub fn keys(&self) -> impl Iterator<Item = &String> + '_

Iterator over user field keys.

pub fn len(&self) -> usize

Number of user-field items ($ entries and comments excluded).

pub fn is_empty(&self) -> bool

true when there are no user-field items.

pub fn get(&self, key: &str) -> Option<&QuillValue>

Look up a user-field value by key. $ entries are not visible via this accessor — use quill / kind / id.

pub fn contains_key(&self, key: &str) -> bool

true if a user field with this key is present.

pub fn is_fill(&self, key: &str) -> bool

true if a user field with this key is marked !must_fill.

pub fn insert( &mut self, key: impl Into<String>, value: QuillValue, ) -> Option<QuillValue>

Insert or update a user field. Always clears the fill marker (field is no longer a placeholder). Preserves position for existing keys; appends new keys at the end. $ entries and comments are untouched. Replacing an existing field discards its nested_comments because the new value tree may not contain matching positions.

pub fn insert_fill( &mut self, key: impl Into<String>, value: QuillValue, ) -> Option<QuillValue>

Insert or update a user field and mark it as a !must_fill placeholder. Preserves position for existing keys; appends new keys at the end. Replacing an existing field discards its nested_comments.

pub fn remove(&mut self, key: &str) -> Option<QuillValue>

Remove a user field by key, returning its value. Comments and $ entries are untouched.

pub fn to_index_map(&self) -> IndexMap<String, QuillValue>

Project the user-field portion into an IndexMap<String, QuillValue>. Comments, fill markers, and $ entries are dropped. Preserves order.

Trait Implementations

impl Clone for Payload

fn clone(&self) -> Payload

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Payload

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

Formats the value using the given formatter.

impl Default for Payload

fn default() -> Payload

Returns the “default value” for a type.

impl From<&Payload> for PayloadV0_92_0

fn from(payload: &Payload) -> Self

Converts to this type from the input type.

impl<'a> IntoIterator for &'a Payload

type Item = (&'a String, &'a QuillValue)

The type of the elements being iterated over.

type IntoIter = FilterMap<Iter<'a, PayloadItem>, fn(&'a PayloadItem) -> Option<(&'a String, &'a QuillValue)>>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl PartialEq for Payload

fn eq(&self, other: &Payload) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl StructuralPartialEq for Payload

impl TryFrom<PayloadV0_92_0> for Payload

type Error = StorageError

The type returned in the event of a conversion error.

fn try_from(p: PayloadV0_92_0) -> Result<Self, Self::Error>

Performs the conversion.