Trait IsBlock

pub trait IsBlock<'src>:
    HasSpan<'src>
    + Clone
    + Debug
    + Eq
    + PartialEq {
    // Required methods
    fn content_model(&self) -> ContentModel;
    fn raw_context(&self) -> CowStr<'src>;
    fn title(&'src self) -> Option<Span<'src>>;
    fn anchor(&'src self) -> Option<Span<'src>>;
    fn attrlist(&'src self) -> Option<&'src Attrlist<'src>>;

    // Provided methods
    fn resolved_context(&'src self) -> CowStr<'src> { ... }
    fn declared_style(&'src self) -> Option<Span<'src>> { ... }
    fn nested_blocks(&'src self) -> Iter<'src, Block<'src>> { ... }
    fn id(&'src self) -> Option<Span<'src>> { ... }
    fn roles(&'src self) -> Vec<Span<'src>> { ... }
    fn options(&'src self) -> Vec<Span<'src>> { ... }
}

Block elements form the main structure of an AsciiDoc document, starting with the document itself.

A block element (aka block) is a discrete, line-oriented chunk of content in an AsciiDoc document. Once parsed, that chunk of content becomes a block element in the parsed document model. Certain blocks may contain other blocks, so we say that blocks can be nested. The converter visits each block in turn, in document order, converting it to a corresponding chunk of output.

This trait implements many of the same core methods as the Block enum but provides a mechanism for third-party code to extend the behavior of blocks.

Required Methods

fn content_model(&self) -> ContentModel

Returns the ContentModel for this block.

fn raw_context(&self) -> CowStr<'src>

Returns the raw (uninterpreted) context for this block.

A block’s context is also sometimes referred to as a name, such as an example block, a sidebar block, an admonition block, or a section.

Every block has a context. The context is often implied by the syntax, but can be declared explicitly in certain cases. The context is what distinguishes one kind of block from another. You can think of the context as the block’s type.

For that reason, the context is not defined as an enumeration, but rather as a string type that is optimized for the case where predefined constants are viable.

A block’s context can be replaced by a block style that matches a built-in context. That transformation is only performed by resolved_context(), not this function.

fn title(&'src self) -> Option<Span<'src>>

Returns the title for this block, if present.

fn anchor(&'src self) -> Option<Span<'src>>

Returns the anchor for this bloc, if present.

fn attrlist(&'src self) -> Option<&'src Attrlist<'src>>

Returns the attribute list for this block, if present.

Provided Methods

fn resolved_context(&'src self) -> CowStr<'src>

Returns the resolved context for this block.

A block’s context is also sometimes referred to as a name, such as an example block, a sidebar block, an admonition block, or a section.

Every block has a context. The context is often implied by the syntax, but can be declared explicitly in certain cases. The context is what distinguishes one kind of block from another. You can think of the context as the block’s type.

For that reason, the context is not defined as an enumeration, but rather as a string type that is optimized for the case where predefined constants are viable.

A block’s context can be replaced by a block style that matches a built-in context. Unlike raw_context(), that transformation is performed by this function.

fn declared_style(&'src self) -> Option<Span<'src>>

Returns the declared (uninterpreted) style for this block.

Above some blocks, you may notice a name at the start of the block attribute list (e.g., [source] or [verse]). The first positional (unnamed) attribute in the block attribute list is used to declare the block style.

The declared block style is the value the author supplies.

That value is then interpreted and resolved. That interpretation is not performed by this function.

fn nested_blocks(&'src self) -> Iter<'src, Block<'src>>

Returns an iterator over the nested blocks contained within this block.

Many block types do not have nested blocks so the default implementation returns an empty iterator.

fn id(&'src self) -> Option<Span<'src>>

Returns the ID for this block, if present.

You can assign an ID to a block using the shorthand syntax, the longhand syntax, or a legacy block anchor.

In the shorthand syntax, you prefix the name with a hash (#) in the first position attribute:

[#goals]
* Goal 1
* Goal 2

In the longhand syntax, you use a standard named attribute:

[id=goals]
* Goal 1
* Goal 2

In the legacy block anchor syntax, you surround the name with double square brackets:

[[goals]]
* Goal 1
* Goal 2

fn roles(&'src self) -> Vec<Span<'src>>

Returns any role attributes that were found.

You can assign one or more roles to blocks and most inline elements using the role attribute. The role attribute is a named attribute. Even though the attribute name is singular, it may contain multiple (space-separated) roles. Roles may also be defined using a shorthand (dot-prefixed) syntax.

A role:

1. adds additional semantics to an element
2. can be used to apply additional styling to a group of elements (e.g., via a CSS class selector)
3. may activate additional behavior if recognized by the converter

TIP: The role attribute in AsciiDoc always get mapped to the class attribute in the HTML output. In other words, role names are synonymous with HTML class names, thus allowing output elements to be identified and styled in CSS using class selectors (e.g., sidebarblock.role1).

fn options(&'src self) -> Vec<Span<'src>>

Returns any option attributes that were found.

The options attribute (often abbreviated as opts) is a versatile named attribute that can be assigned one or more values. It can be defined globally as document attribute as well as a block attribute on an individual block.

There is no strict schema for options. Any options which are not recognized are ignored.

You can assign one or more options to a block using the shorthand or formal syntax for the options attribute.

Shorthand options syntax for blocks

To assign an option to a block, prefix the value with a percent sign (%) in an attribute list. The percent sign implicitly sets the options attribute.

Example 1: Sidebar block with an option assigned using the shorthand dot

[%option]
****
This is a sidebar with an option assigned to it, named option.
****

You can assign multiple options to a block by prest fixing each value with a percent sign (%).

Example 2: Sidebar with two options assigned using the shorthand dot

[%option1%option2]
****
This is a sidebar with two options assigned to it, named option1 and option2.
****

Formal options syntax for blocks

Explicitly set options or opts, followed by the equals sign (=), and then the value in an attribute list.

Example 3. Sidebar block with an option assigned using the formal syntax

[opts=option]
****
This is a sidebar with an option assigned to it, named option.
****

Separate multiple option values with commas (,).

Example 4. Sidebar with three options assigned using the formal syntax

[opts="option1,option2"]
****
This is a sidebar with two options assigned to it, option1 and option2.
****

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl<'src> IsBlock<'src> for Block<'src>

impl<'src> IsBlock<'src> for Document<'src>

impl<'src> IsBlock<'src> for CompoundDelimitedBlock<'src>

impl<'src> IsBlock<'src> for MacroBlock<'src>

impl<'src> IsBlock<'src> for RawDelimitedBlock<'src>

impl<'src> IsBlock<'src> for SectionBlock<'src>

impl<'src> IsBlock<'src> for SimpleBlock<'src>