Trait hoedown::renderer::Render [−] [src]

pub trait Render: Sized {
    fn render(&mut self, input: &Markdown) -> Buffer { ... }
    fn render_to(&mut self, input: &Markdown, output: &mut Buffer) { ... }
    fn render_inline(&mut self, input: &Markdown) -> Buffer { ... }
    fn render_inline_to(&mut self, input: &Markdown, output: &mut Buffer) { ... }
    unsafe fn to_hoedown(&mut self) -> hoedown_renderer { ... }
    fn code_block(
        &mut self, 
        output: &mut Buffer, 
        text: Option<&Buffer>, 
        lang: Option<&Buffer>
    ) { ... }
    fn quote_block(&mut self, output: &mut Buffer, content: Option<&Buffer>) { ... }
    fn header(
        &mut self, 
        output: &mut Buffer, 
        content: Option<&Buffer>, 
        level: i32
    ) { ... }
    fn horizontal_rule(&mut self, output: &mut Buffer) { ... }
    fn list(
        &mut self, 
        output: &mut Buffer, 
        content: Option<&Buffer>, 
        flags: List
    ) { ... }
    fn list_item(
        &mut self, 
        output: &mut Buffer, 
        content: Option<&Buffer>, 
        flags: List
    ) { ... }
    fn paragraph(&mut self, output: &mut Buffer, content: Option<&Buffer>) { ... }
    fn table(&mut self, output: &mut Buffer, content: Option<&Buffer>) { ... }
    fn table_header(&mut self, output: &mut Buffer, content: Option<&Buffer>) { ... }
    fn table_body(&mut self, output: &mut Buffer, content: Option<&Buffer>) { ... }
    fn table_row(&mut self, output: &mut Buffer, content: Option<&Buffer>) { ... }
    fn table_cell(
        &mut self, 
        output: &mut Buffer, 
        content: Option<&Buffer>, 
        flags: Table
    ) { ... }
    fn footnotes(&mut self, output: &mut Buffer, content: Option<&Buffer>) { ... }
    fn footnote_definition(
        &mut self, 
        output: &mut Buffer, 
        content: Option<&Buffer>, 
        num: u32
    ) { ... }
    fn html_block(&mut self, output: &mut Buffer, text: Option<&Buffer>) { ... }
    fn autolink(
        &mut self, 
        output: &mut Buffer, 
        link: Option<&Buffer>, 
        link_type: AutoLink
    ) -> bool { ... }
    fn code_span(&mut self, output: &mut Buffer, text: Option<&Buffer>) -> bool { ... }
    fn double_emphasis(
        &mut self, 
        output: &mut Buffer, 
        content: Option<&Buffer>
    ) -> bool { ... }
    fn emphasis(
        &mut self, 
        output: &mut Buffer, 
        content: Option<&Buffer>
    ) -> bool { ... }
    fn underline(
        &mut self, 
        output: &mut Buffer, 
        content: Option<&Buffer>
    ) -> bool { ... }
    fn highlight(
        &mut self, 
        output: &mut Buffer, 
        content: Option<&Buffer>
    ) -> bool { ... }
    fn quote_span(
        &mut self, 
        output: &mut Buffer, 
        content: Option<&Buffer>
    ) -> bool { ... }
    fn image(
        &mut self, 
        output: &mut Buffer, 
        link: Option<&Buffer>, 
        title: Option<&Buffer>, 
        alt: Option<&Buffer>
    ) -> bool { ... }
    fn line_break(&mut self, output: &mut Buffer) -> bool { ... }
    fn link(
        &mut self, 
        output: &mut Buffer, 
        content: Option<&Buffer>, 
        link: Option<&Buffer>, 
        title: Option<&Buffer>
    ) -> bool { ... }
    fn triple_emphasis(
        &mut self, 
        output: &mut Buffer, 
        content: Option<&Buffer>
    ) -> bool { ... }
    fn strikethrough(
        &mut self, 
        output: &mut Buffer, 
        content: Option<&Buffer>
    ) -> bool { ... }
    fn superscript(
        &mut self, 
        output: &mut Buffer, 
        content: Option<&Buffer>
    ) -> bool { ... }
    fn footnote_reference(&mut self, output: &mut Buffer, num: u32) -> bool { ... }
    fn math(
        &mut self, 
        output: &mut Buffer, 
        text: Option<&Buffer>, 
        displaymode: i32
    ) -> bool { ... }
    fn html_span(&mut self, output: &mut Buffer, text: Option<&Buffer>) -> bool { ... }
    fn entity(&mut self, output: &mut Buffer, text: Option<&Buffer>) { ... }
    fn normal_text(&mut self, output: &mut Buffer, text: Option<&Buffer>) { ... }
    fn before_render(&mut self, output: &mut Buffer, inline_render: bool) { ... }
    fn after_render(&mut self, output: &mut Buffer, inline_render: bool) { ... }
}

Represents render behavior

Types that implement this trait can be used to render a Buffer document.

All methods have default implementations which may be implemented by the implementing type as required, depending on which callbacks it's interested in.

The default implementations attempt to be as neutral as possible, with the exception of the block callbacks. In the underlying library, hoedown skips the block if the handler is not registered. This behavior can be confusing when creating a custom renderer, so the default implementations for block handlers is to output a message into the output buffer to make it clearer.

Type Action
block ignore the block
span pass through markdown to output
rest pass through content to output

Below is an example of a custom renderer that collects emphasis elements into a vector that can then be inspected after rendering.

struct EmphCollector {
    // html renderer to delegate to
    html: html::Html,

    // collection of emphasis elements
    emphs: Vec<String>,
}

impl EmphCollector {
    fn new() -> EmphCollector {
        EmphCollector {
            html: html::Html::new(html::Flags::empty(), ::std::i32::MAX),
            emphs: vec![],
        }
    }
}

impl Render for EmphCollector {
    // pass the content straight to the output buffer
    fn paragraph(&mut self, ob: &mut Buffer, content: Option<&Buffer>) {
        content.map(|c| ob.pipe(c));
    }

    fn emphasis(&mut self, ob: &mut Buffer, content: Option<&Buffer>) -> bool {
        // collect the emphasis element
        content
            .and_then(|c| c.to_str().ok())
            .map(|s| self.emphs.push(String::from(s)));

        // delegate rendering the emphasis element to the html renderer
        self.html.emphasis(ob, content)
    }
}

let doc = Markdown::new("this _one_ that _two_ another _three_ pass it _around_");
let mut collector = EmphCollector::new();

let output = collector.render(&doc);

assert_eq!(
    collector.emphs,
    vec![
        String::from("one"),
        String::from("two"),
        String::from("three"),
        String::from("around")]);

assert_eq!(
    "this <em>one</em> that <em>two</em> another <em>three</em> pass it <em>around</em>",
    output.to_str().unwrap());

Provided Methods

Render the document to a buffer that is returned

Render the document into the given buffer

Render the document as inline to a buffer that is returned

Render the document as inline into the given buffer

Converts the type into an underlying hoedown_renderer structure.

The default implementation of this should suffice for the majority of implementations, unless you know what you're doing.

The default implementation is unsafe because it stores a pointer to self in the underlying library. Problems could arise if that pointer is used after self has stopped existing.

This library avoids this issue by tightly controlling the the render process to ensure that the renderer outlives the document (the document is what requires to_hoedown)

Runs when a codeblock is encountered

The lang parameter will be empty if it's an indented codeblock or if no language was specified in a fenced codeblock.

The default implementation outputs an error string.

Not run if the DISABLE_INDENTED_CODE extension is enabled.

Runs when a block quote is encountered

The default implementation outputs an error string.

Runs when a header is encountered

The default implementation outputs an error string.

Runs when a horizontal rule is encountered

The default implementation outputs an error string.

Runs when a list is encountered.

The default implementation outputs an error string.

Runs when a list item is encountered.

The default implementation outputs an error string.

Runs when a paragraph is encountered.

The default implementation outputs an error string.

Runs when a table is encountered.

Only runs if the TABLES extension is enabled.

The default implementation outputs an error string.

Runs when a table header is encountered.

Only runs if the TABLES extension is enabled.

The default implementation outputs an error string.

Runs when a table body is encountered.

Only runs if the TABLES extension is enabled.

The default implementation outputs an error string.

Runs when a table row is encountered.

Only runs if the TABLES extension is enabled.

The default implementation outputs an error string.

Runs when a table cell is encountered.

Only runs if the TABLES extension is enabled.

The default implementation outputs an error string.

Runs when footnotes are encountered.

Only runs if the FOOTNOTES extension is enabled.

The default implementation outputs an error string.

Runs when a footnote definition is encountered.

Only runs if the FOOTNOTES extension is enabled.

The default implementation outputs an error string.

Runs when a raw html block is encountered.

The default implementation outputs an error string.

Runs when an autolink candidate is encountered.

Only runs if the AUTOLINK extension is enabled.

The default implementation passes the context markdown to the buffer verbatim.

Runs when a code span is encountered.

The default implementation passes the context markdown to the buffer verbatim.

Runs when double emphasis is encountered.

e.g. **double emphasis**

The default implementation passes the context markdown to the buffer verbatim.

Runs when emphasis is encountered.

The default implementation passes the context markdown to the buffer verbatim.

Runs when underline is encountered.

Only runs if the UNDERLINE extension is enabled.

The default implementation passes the context markdown to the buffer verbatim.

Runs when highlight is encountered.

Only runs if the HIGHLIGHT extension is enabled.

The default implementation passes the context markdown to the buffer verbatim.

Runs when a quote is encountered.

Only runs if the QUOTE extension is enabled.

The default implementation passes the context markdown to the buffer verbatim.

Runs when an image is encountered.

e.g. ![alt](link title)

The default implementation passes the context markdown to the buffer verbatim.

Runs when a line break is encountered.

The default implementation passes the context markdown to the buffer verbatim.

Runs when a link is encountered.

e.g. [content](link title)

The default implementation passes the context markdown to the buffer verbatim.

Runs when triple emphasis is encountered.

e.g. ***strongly emphasized***

The default implementation passes the context markdown to the buffer verbatim.

Runs when strikethrough is encountered.

Only runs if the STRIKETHROUGH extension is enabled.

The default implementation passes the context markdown to the buffer verbatim.

Runs when superscript is encountered.

Only runs if the SUPERSCRIPT extension is enabled.

The default implementation passes the context markdown to the buffer verbatim.

Runs when a footnote reference is encountered.

Only runs if the FOOTNOTES extension is enabled.

The default implementation passes the context markdown to the buffer verbatim.

Runs when math is encountered.

Only runs if the MATH extension is enabled.

The default implementation passes the context markdown to the buffer verbatim.

Runs when raw html span is encountered.

The default implementation passes the context markdown to the buffer verbatim.

Runs when an html entity is encountered.

The default implementation passes the entity to the output buffer verbatim.

Runs when plain text is encountered.

The default implementation passes the entity to the output buffer verbatim.

Runs before the document is processed.

The default implementation does nothing.

Runs after the document has been processed.

The default implementation does nothing.

Implementors