class Cmark::Node

Overview

A node is a construct of the abstract syntax tree (AST) for a given markdown content.

At the very minimum every node has a NodeType —available via #type— even when invalid. However, given that each type of node has a set of required properties —which if are not set may lead to unintended behavior— all initializers of Node are protected. Nodes can be created in a safer manner either with the module NodeMaker, or with the parsing methods of the moduleCmark (which return a node with NodeType::Document).

Instance methods can be grouped into:

NOTE The Node class is a thin wrapper for the node struct of the underlying cmark-gfm C library, as such, familiarity with the GFM Spec is required for advanced node creation, processing, and rendering.

Defined in:

cmark/node.cr

Instance Method Summary

Instance Method Detail

def ==(other : Node) #

Returns true if both instances point to the same underlying node structure.


def append_child(child : Node) #

Adds child to the end of the children of node; raises TreeManipulationError on failure.


def autolink? : Bool #

Returns true if the node is a Commonmark autolink, false otherwise.

Beware that this method consolidates adjacent child text nodes if the node is a link.

NOTE When the GFM autolink extension is enabled, this method will not detect extended www autolink nor extended autolink path validation. However, extended email autolink together with simple autolinks constructed without the use of < and > as delimiters will be recognized as autolinks.


def can_contain?(node_type : NodeType) : Bool #

Returns true node can contain node_type, false otherwise.


def children : Array(Node) #

Returns children nodes or an empty array if there are none.


def consolidate_text_nodes #

Consolidates adjacent text nodes.


def end_column : Int32 #

Returns the column on which node ends.


def end_line : Int32 #

Returns the line on which node ends.


def fence_info : String #

Returns the info string of a fenced code block.


def fence_info=(info : String) : String #

Sets the info string of a fenced code block; on failure it raises NodeSetterError.


def fencing_details : FencingDetails | Nil #

Returns fencing details of a code block.

Returns nil if called on a node that is not a code block.


def fencing_details=(details : FencingDetails) : FencingDetails #

Sets fencing details of a code block; on failure it raises NodeSetterError.


def first_child : Node | Nil #

Returns the first_child node of this node.


def footnote_definition_count : Int32 #

Returns the count the footnote definition.

Returns 0 if the node is not a footnote definition.


def footnote_definition_literal : String #

Returns the definition literal of the footnote.

Returns an empty string if the node is not a footnote definition.


def footnote_parent_definition_literal : String #

Returns the definition literal of the footnote for this reference.

Returns an empty string if the node is not a footnote reference.


def footnote_reference_index : Int32 #

Returns the index of the footnote reference.

Returns 0 if the node is not a footnote reference.


def grandparent : Node | Nil #

Returns the grandparent node of this node.


def heading_level : Int32 #

Returns the heading level of node, or 0 if node is not a heading.


def heading_level=(heading_level : Int32) : Int32 #

Sets the heading level of node; on failure it raises NodeSetterError.


def insert_after(sibling : Node) #

Inserts sibling after node; raises TreeManipulationError on failure.


def insert_before(sibling : Node) #

Inserts sibling before node; raises TreeManipulationError on failure.


def last_child : Node | Nil #

Returns the last_child node of this node.


def list_delim : DelimType #

Returns the list delimiter of node, using DelimType::None if node is not a list.


def list_delim=(list_delim : DelimType) : DelimType #

Sets the list delimiter of node; on failure it raises NodeSetterError.


def list_start : Int #

Returns starting number of node, if it is an ordered list, otherwise 0.


def list_start=(list_start : Int32) : Int32 #

Sets the list delimiter of node; on failure it raises NodeSetterError.


def list_tight=(tight : Bool) : Bool #

Sets the list tightness of node; on failure it raises NodeSetterError.


def list_tight? : Bool #

Returns true if node is a tight list, or false if loose.


def list_type : ListType #

Returns the list type of node, using ListType::None if node is not a list.


def list_type=(list_type : ListType) : ListType #

Sets the list type of node; on failure it raises NodeSetterError.


def literal : String #

Returns the literal string contents of node, or an empty string if none is set.


def literal=(literal : String) : String #

Sets the literal string contents of node; on failure it raises NodeSetterError.


def next : Node | Nil #

Returns the next node of this node.


def on_enter : String #

Returns the literal on_enter of a custom node or an empty string if unset.


def on_enter=(on_enter : String) : String #

Sets the literal on_enter of a custom node; on failure it raises NodeSetterError.

Any children of the node will be rendered after this text.


def on_exit : String #

Returns the literal on_exit of a custom node or an empty string if unset.

Returns nil if called on a node that is not custom.


def on_exit=(on_exit : String) : String #

Sets the literal on_exit of a custom node; on failure it raises NodeSetterError.

Any children of the node will be rendered before this text.


def parent : Node | Nil #

Returns the parent node of this node.


def prepend_child(child : Node) #

Adds child to the beginning of the children of node; raises TreeManipulationError on failure.


def previous : Node | Nil #

Returns the previous node of this node.


def render_commonmark(options = Option::None, width = 120) : String #

Renders node tree as a commonmark string, including GFM extension nodes, if present.


def render_html(options = Option::None, extensions = Extension::None) : String #

Renders node tree as an HTML string.


def render_latex(options = Option::None, width = 120) : String #

Renders node tree as a LaTeX string.


def render_man(options = Option::None, width = 80) : String #

Renders node tree as a groff man page string.


def render_plaintext(options = Option::None, width = 120) : String #

Renders node tree as a plaintext string.


def render_xml(options = Option::None) : String #

Renders node tree an XML string.


def replace_with(new_node : Node) #

Replaces node with new_node; raises TreeManipulationError on failure.


def start_column : Int32 #

Returns the column on which node begins.


def start_line : Int32 #

Returns the line on which node begins.


def table_alignments : Array(Alignment) #

Returns the alignments of columns for the table.

Returns an empty array if called on a node that is not a table.


def table_alignments=(alignments : Array(Alignment)) : Array(Alignment) #

Sets the alignments of columns for the table; on failure it raises NodeSetterError.

It should be called only on table nodes.

Example for a table node with two columns:

node.table_alignments = [Alignment::Center, Alignment::Right]

def table_cell_alignment : Alignment #

Returns node table alignment or Alignment::None if called on a node that is not a table cell.


def table_columns : UInt16 #

Returns the number of columns for the table.

Returns 0 if called on a node that is not a table.


def table_columns=(n_columns : UInt16) : UInt16 #

Sets the number of columns for the table; on failure it raises NodeSetterError.

It must be called only on table and table row nodes that already have defined columns.


def table_row_header=(header : Bool) : Bool #

Sets a table row as table header.


def table_row_header? : Bool #

Returns true if the the node is a header table row, false otherwise.


def table_string_content : String #

Returns the string content of tables and table cells, otherwise an empty string.

With the following table

| foo | bar |
| --- | --- |
| baz | bim |

the string content of table is the header row | foo | bar |. and the string content of the cells is foo, bar, baz, and bim.


def table_string_content=(content : String) : String #

Sets the table string content for tables and table cells.

Beware of setting incorrect string content. See #table_string_content for more information.


def tasklist_item=(tasklist : Bool) : Bool #

Sets a list item as tasklist item; on failure it raises NodeSetterError.

It must be called only on nodes with NodeType::Item.


def tasklist_item? : Bool #

Returns true is a node is a tasklist item, false otherwise.


def tasklist_item_checked=(checked : Bool) : Bool #

Sets the checked status of tasklist item: on failure it raises NodeSetterError.


def tasklist_item_checked? : Bool #

Returns true is a node is a tasklist_item and is checked, false otherwise.


def title : String #

Returns the title of a link or image node, or an empty string if no title is set.


def title=(title : String) : String #

Sets the title of a link or image node; on failure it raises NodeSetterError.


def type : NodeType #

Returns the type of node.


def unlink #

Unlinks this node from the AST.


def url : String #

Returns the URL of a link or image node, or an empty string if no URL is set.


def url=(url : String) : String #

Sets the URL of node; on failure it raises NodeSetterError.

It must be called only on link or image nodes.


def user_data : Pointer(Void) #

Returns the user data of node, which can then be unboxed.

Example:

node = NodeMaker.text("Hi")
node.user_data.null? # => true
node.user_data = Box.box(:greetings)
user_data = Box(Symbol).unbox(node.user_data)
user_data # => :grettings

def user_data=(user_data : Pointer(Void)) : Pointer(Void) #

Sets the user data of node, which should be already boxed; on failure it raises NodeSetterError.

NOTE user_data must be boxed into the node struct of the C library; see #user_data.