Struct BlockMetadata 

#[non_exhaustive]
pub struct BlockMetadata<'a> {
    pub caption: Option<Caption<'a>>,
    pub attributes: ElementAttributes<'a>,
    pub roles: Vec<Role<'a>>,
    pub options: Vec<&'a str>,
    pub style: Option<&'a str>,
    pub id: Option<Anchor<'a>>,
    pub anchors: Vec<Anchor<'a>>,
    pub substitutions: Option<SubstitutionSpec>,
    pub attribution: Option<Attribution<'a>>,
    pub citetitle: Option<CiteTitle<'a>>,
    pub location: Option<Location>,
    /* private fields */
}

A BlockMetadata represents the metadata of a block in a document.

Equality includes the values and empty slots from Self::positional_attributes, but not their source locations. The block’s own Self::location still participates.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

caption: Option<Caption<'a>>

Caption behavior resolved from the document attributes in effect at this block’s source position, and the ordinal assigned to it. None means caller-built metadata or a block that takes no caption.

attributes: ElementAttributes<'a>

roles: Vec<Role<'a>>

options: Vec<&'a str>

style: Option<&'a str>

id: Option<Anchor<'a>>

anchors: Vec<Anchor<'a>>

substitutions: Option<SubstitutionSpec>

Substitutions to apply to block content. Only present when the pre-spec-subs feature is enabled; the draft AsciiDoc spec is dropping the substitution model in favour of an inline parsing grammar, so this field is feature-gated to reflect that.

• None: Use block-type defaults (VERBATIM for listing/literal, NORMAL for paragraphs)
• Some(Source(entries)): Preserve authored entries; resolve against block defaults as needed
• Some(Explicit([])): No substitutions (equivalent to subs=none)
• Some(Explicit(list)): Use the explicit list of substitutions
• Some(Modifiers(ops)): Apply modifier operations to block-type defaults

attribution: Option<Attribution<'a>>

citetitle: Option<CiteTitle<'a>>

location: Option<Location>

Implementations

impl<'a> BlockMetadata<'a>

pub fn new() -> Self

Create a new block metadata with default values.

pub fn uses_substitution( &self, substitution: &Substitution, defaults: &[Substitution], ) -> bool

Whether a substitution is enabled after applying this block’s subs setting.

defaults contains individual substitutions, such as crate::VERBATIM for source blocks. Without pre-spec-subs, only these defaults apply.

pub fn with_attributes(self, attributes: ElementAttributes<'a>) -> Self

Set the attributes.

pub fn with_options(self, options: Vec<&'a str>) -> Self

Set the options.

pub fn with_roles(self, roles: Vec<Role<'a>>) -> Self

Set the roles.

pub fn with_style(self, style: Option<&'a str>) -> Self

Set the style.

pub fn with_id(self, id: Option<Anchor<'a>>) -> Self

Set the ID.

pub fn positional_attribute(&self, index: usize) -> Option<&'a str>

Return a non-empty retained positional attribute by its zero-based slot.

Returns None when the slot is empty or absent. See Self::positional_attributes for ordering, substitution, and merge behavior.

pub fn positional_attributes( &self, ) -> impl ExactSizeIterator<Item = Option<&'a str>> + '_

Iterate over retained positional slots after the first attribute-list entry.

The first entry is usually a block style, or alt text or a poster in a media macro. It is excluded even when parsing consumes or clears Self::style.

For block attribute lists, surrounding quotes are removed and document-attribute references are expanded; inline markup remains literal. Empty strings (quoted or unquoted) and gaps before later positional values yield None. For example, [tikz,target=x,svg] yields [None, Some("svg")]; trailing named attributes do not extend the iterator. Consecutive lists merge by slot: later slots replace earlier ones, including empty slots, while earlier trailing slots remain.

Values remain available after context-specific routing. This positional view is not added to JSON. Markdown fence languages do not add positional slots.

This is a snapshot of the parsed, merged slots. Changing Self::attributes or Self::style afterward does not update it. For example, after parsing [source,rust], setting the named language attribute to python leaves positional slot 0 as Some("rust"). Metadata created with Self::new or Self::default has no positional slots; setting attributes does not add them.

pub fn is_default(&self) -> bool

Whether this metadata serializes to nothing.

This gates skip_serializing_if on every block’s metadata field, so it covers only the serialized fields. caption is deliberately excluded: it carries #[serde(skip)], so counting it would make a block emit an empty metadata object.

Trait Implementations

impl<'a> Clone for BlockMetadata<'a>

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<'a> Debug for BlockMetadata<'a>

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

Formats the value using the given formatter.

impl<'a> Default for BlockMetadata<'a>

fn default() -> Self

Returns the “default value” for a type.

impl PartialEq for BlockMetadata<'_>

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

Equality operator ==.

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

Inequality operator !=.

impl<'a> Serialize for BlockMetadata<'a>

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.