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: &Buffer, lang: &Buffer) { ... }
    fn quote_block(&mut self, output: &mut Buffer, content: &Buffer) { ... }
    fn header(&mut self, output: &mut Buffer, content: &Buffer, level: i32) { ... }
    fn horizontal_rule(&mut self, output: &mut Buffer) { ... }
    fn list(&mut self, output: &mut Buffer, content: &Buffer, flags: List) { ... }
    fn list_item(&mut self, output: &mut Buffer, content: &Buffer, flags: List) { ... }
    fn paragraph(&mut self, output: &mut Buffer, content: &Buffer) { ... }
    fn table(&mut self, output: &mut Buffer, content: &Buffer) { ... }
    fn table_header(&mut self, output: &mut Buffer, content: &Buffer) { ... }
    fn table_body(&mut self, output: &mut Buffer, content: &Buffer) { ... }
    fn table_row(&mut self, output: &mut Buffer, content: &Buffer) { ... }
    fn table_cell(&mut self, output: &mut Buffer, content: &Buffer, flags: Table) { ... }
    fn footnotes(&mut self, output: &mut Buffer, content: &Buffer) { ... }
    fn footnote_definition(&mut self, output: &mut Buffer, content: &Buffer, num: u32) { ... }
    fn html_block(&mut self, output: &mut Buffer, text: &Buffer) { ... }
    fn autolink(&mut self, output: &mut Buffer, link: &Buffer, link_type: AutoLink) -> bool { ... }
    fn code_span(&mut self, output: &mut Buffer, text: &Buffer) -> bool { ... }
    fn double_emphasis(&mut self, output: &mut Buffer, content: &Buffer) -> bool { ... }
    fn emphasis(&mut self, output: &mut Buffer, content: &Buffer) -> bool { ... }
    fn underline(&mut self, output: &mut Buffer, content: &Buffer) -> bool { ... }
    fn highlight(&mut self, output: &mut Buffer, content: &Buffer) -> bool { ... }
    fn quote_span(&mut self, output: &mut Buffer, content: &Buffer) -> bool { ... }
    fn image(&mut self, output: &mut Buffer, link: &Buffer, title: &Buffer, alt: &Buffer) -> bool { ... }
    fn line_break(&mut self, output: &mut Buffer) -> bool { ... }
    fn link(&mut self, output: &mut Buffer, content: &Buffer, link: &Buffer, title: &Buffer) -> bool { ... }
    fn triple_emphasis(&mut self, output: &mut Buffer, content: &Buffer) -> bool { ... }
    fn strikethrough(&mut self, output: &mut Buffer, content: &Buffer) -> bool { ... }
    fn superscript(&mut self, output: &mut Buffer, content: &Buffer) -> bool { ... }
    fn footnote_reference(&mut self, output: &mut Buffer, num: u32) -> bool { ... }
    fn math(&mut self, output: &mut Buffer, text: &Buffer, displaymode: i32) -> bool { ... }
    fn html_span(&mut self, output: &mut Buffer, text: &Buffer) -> bool { ... }
    fn entity(&mut self, output: &mut Buffer, text: &Buffer) { ... }
    fn normal_text(&mut self, output: &mut Buffer, text: &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: &Buffer) {
        ob.pipe(content);
    }

    fn emphasis(&mut self, ob: &mut Buffer, content: &Buffer) -> bool {
        // collect the emphasis element
        self.emphs.push(String::from(content.to_str().unwrap()));

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

`fn render(&mut self, input: &Markdown) -> Buffer`

Render the document to a buffer that is returned

`fn render_to(&mut self, input: &Markdown, output: &mut Buffer)`

Render the document into the given buffer

`fn render_inline(&mut self, input: &Markdown) -> Buffer`

Render the document as inline to a buffer that is returned

`fn render_inline_to(&mut self, input: &Markdown, output: &mut Buffer)`

Render the document as inline into the given buffer

`unsafe fn to_hoedown(&mut self) -> hoedown_renderer`

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)

`fn code_block(&mut self, output: &mut Buffer, text: &Buffer, lang: &Buffer)`

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.

`fn quote_block(&mut self, output: &mut Buffer, content: &Buffer)`

Runs when a block quote is encountered

The default implementation outputs an error string.

`fn header(&mut self, output: &mut Buffer, content: &Buffer, level: i32)`

Runs when a header is encountered

The default implementation outputs an error string.

`fn horizontal_rule(&mut self, output: &mut Buffer)`

Runs when a horizontal rule is encountered

The default implementation outputs an error string.

`fn list(&mut self, output: &mut Buffer, content: &Buffer, flags: List)`

Runs when a list is encountered.

The default implementation outputs an error string.

`fn list_item(&mut self, output: &mut Buffer, content: &Buffer, flags: List)`

Runs when a list item is encountered.

The default implementation outputs an error string.

`fn paragraph(&mut self, output: &mut Buffer, content: &Buffer)`

Runs when a paragraph is encountered.

The default implementation outputs an error string.

`fn table(&mut self, output: &mut Buffer, content: &Buffer)`

Runs when a table is encountered.

Only runs if the TABLES extension is enabled.

The default implementation outputs an error string.

`fn table_header(&mut self, output: &mut Buffer, content: &Buffer)`

Runs when a table header is encountered.

Only runs if the TABLES extension is enabled.

The default implementation outputs an error string.

`fn table_body(&mut self, output: &mut Buffer, content: &Buffer)`

Runs when a table body is encountered.

Only runs if the TABLES extension is enabled.

The default implementation outputs an error string.

`fn table_row(&mut self, output: &mut Buffer, content: &Buffer)`

Runs when a table row is encountered.

Only runs if the TABLES extension is enabled.

The default implementation outputs an error string.

`fn table_cell(&mut self, output: &mut Buffer, content: &Buffer, flags: Table)`

Runs when a table cell is encountered.

Only runs if the TABLES extension is enabled.

The default implementation outputs an error string.

`fn footnotes(&mut self, output: &mut Buffer, content: &Buffer)`

Runs when footnotes are encountered.

Only runs if the FOOTNOTES extension is enabled.

The default implementation outputs an error string.

`fn footnote_definition(&mut self, output: &mut Buffer, content: &Buffer, num: u32)`

Runs when a footnote definition is encountered.

Only runs if the FOOTNOTES extension is enabled.

The default implementation outputs an error string.

`fn html_block(&mut self, output: &mut Buffer, text: &Buffer)`

Runs when a raw html block is encountered.

The default implementation outputs an error string.