module Cmark::NodeMaker

Overview

A convenience class to safely create Node instances with a predefined NodeType.

NOTE The methods herein only create the given node(s) per se, it is the responsibility of the module user to create and assign the necessary parent and child nodes of the respective created nodes.

Defined in:

cmark/node_maker.cr

Class Method Summary

Class Method Detail

def self.block_quote : Node #

Makes a node with NodeType::BlockQuote.


def self.code(literal : String) : Node #

Makes a node with NodeType::Code.


def self.code_block(contents : String, fence_info : String = "") #

def self.custom_block(on_enter : String = "", on_exit : String = "") #

Mades a node with NodeType::CUSTOM_BLOCK.


def self.custom_inline(on_enter : String = "", on_exit : String = "") #

Mades a node with NodeType::CUSTOM_INLINE.


def self.document : Node #

Makes a node with NodeType::Document.


def self.emph : Node #

Makes a node with NodeType::Emph.


def self.heading(level : Int32 = 1) : Node #

def self.html_block(literal : String) : Node #

Makes a node with NodeType::HTMLBlock.


def self.html_inline(literal : String) : Node #

Makes a node with NodeType::HTMLInline.


def self.image(url : String, title = "") : Node #

Makes a node with NodeType::Image.


def self.item : Node #

Makes a node with NodeType::Item.


def self.linebreak : Node #

Makes a node with NodeType::Linebreak.


def self.link(url : String, title = "") : Node #

Makes a node with NodeType::Link.


def self.list_as_bullet(tight : Bool = true) #

Makes a node with NodeType::List with ListType::Bullet.


def self.list_as_ordered(tight : Bool = true, start = 1, delim = DelimType::Period) #

Makes a node with NodeType::List with ListType::Ordered.


def self.paragraph(parent : Node, append = true) : Node #

Makes a node with NodeType::Paragraph as child of the given parent.

If append is true the new paragraph will be appended as child of parent, otherwise it will be prepended as child.

It raises Cmark::TreeManipulationError if cannot be inserted as child of parent.

NOTE a paragraph node could theoretically be created without a parent. However, the HTML renderer of the underlying C library assumes that a paragraph node will always have a parent. Given that most users will render use such HTML rendering anyways, it is better to be safe than to have an invalid memory access.


def self.softbreak : Node #

Makes a node with NodeType::Softbreak.


def self.strikethrough : Node #

Makes a node with NodeType::Strikethrough.


def self.strong : Node #

Makes a node with NodeType::Strong.


def self.table(contents : Array(Array(Node))) : Node #

Makes a node with NodeType::Table using a bidimensional array of Node for contents, with the first array of nodes being its headers.

Non-header arrays of nodes can be of different size with respect to the the header array of nodes. If the non-header array's size is greater than the header's size, the nodes in excess will be discarded. If, on the contrary, the non-header array's size is less than the header's size, the table row will be padded with empty cells.

It raises Cmark::Error if the headers or contents arrays are empty.

It raises Cmark::TreeManipulationError if any node in contents cannot be appended to its respective table cell.

This example

include NodeMaker
contents = [] of Array(Node)
contents.push [text("foo"), text("bar")]
contents.push [text("fiz"), text("baz")]
node = table(contents)
node.render_html

renders the following HTML (formatted for better reading):

<table>
  <thead>
    <tr>
      <th>foo</th>
      <th>bar</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>fiz</td>
       <td>baz</td>
    </tr>
  </tbody>
</table>

def self.table_row(table : Node, contents : Array(Node), previous_table_row : Node | Nil = nil) : Node #

Makes a node with NodeType::Table using contents to populate its cells; if previous_table_row is not nil then the new row is inserted after it, otherwise it is appended as a child of table.

NOTE If creating a table from scratch is better to use .table.

If contents size is greater than the number of columns in table, the nodes in excess will be discarded. If, on the contrary, contents size is less than number of columns, the table row will be padded with empty cells.

It raises Cmark::Error if contents is empty, if table is not a node with NodeType::Table, or if previous_table_row is set but is not a child of table.

It raises Cmark::TreeManipulationError if any node in contents cannot be appended to its respective table cell.

This example

include NodeMaker
table_contents = [] of Array(Node)
table_contents.push [text("foo"), text("bar")]
table_contents.push [text("fee"), text("ber")]
table_node = table(table_contents)
previous_table_row = table_node.first_child.not_nil!
contents = [text("fiz"), text("baz")]
table_row_node = table_row(table, contents, previous_table_row)
table_node.render_html

renders the following HTML (formatted for better reading):

<table>
  <thead>
    <tr>
      <th>foo</th>
      <th>bar</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>fiz</td>
       <td>baz</td>
    </tr>
    <tr>
      <td>fee</td>
       <td>ber</td>
    </tr>
  </tbody>
</table>

def self.tasklist_item(checked : Bool = false) #

Makes a tasklist extension node with NodeType::Item, which is checked or not.

To check if a given node is a tasklist item use Node#tasklist_item?.


def self.text(literal : String) : Node #

Makes a node with NodeType::Text.


def self.thematic_break : Node #

Makes a node with NodeType::ThematicBreak.