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.


[View source]
def append_child(child : Node) #

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


[View source]
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.


[View source]
def can_contain?(node_type : NodeType) : Bool #

Returns true node can contain node_type, false otherwise.


[View source]
def children : Array(Node) #

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


[View source]
def consolidate_text_nodes #

Consolidates adjacent text nodes.


[View source]
def end_column : Int32 #

Returns the column on which node ends.


[View source]
def end_line : Int32 #

Returns the line on which node ends.


[View source]
def fence_info : String #

Returns the info string of a fenced code block.


[View source]
def fence_info=(info : String) : String #

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


[View source]
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.


[View source]
def fencing_details=(details : FencingDetails) : FencingDetails #

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


[View source]
def first_child : Node | Nil #

Returns the first_child node of this node.


[View source]
def footnote_definition_count : Int32 #

Returns the count the footnote definition.

Returns 0 if the node is not a footnote definition.


[View source]
def footnote_definition_literal : String #

Returns the definition literal of the footnote.

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


[View source]
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.


[View source]
def footnote_reference_index : Int32 #

Returns the index of the footnote reference.

Returns 0 if the node is not a footnote reference.


[View source]
def grandparent : Node | Nil #

Returns the grandparent node of this node.


[View source]
def heading_level : Int32 #

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


[View source]
def heading_level=(heading_level : Int32) : Int32 #

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


[View source]
def insert_after(sibling : Node) #

Inserts sibling after node; raises TreeManipulationError on failure.


[View source]
def insert_before(sibling : Node) #

Inserts sibling before node; raises TreeManipulationError on failure.


[View source]
def last_child : Node | Nil #

Returns the last_child node of this node.


[View source]
def list_delim : DelimType #

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


[View source]
def list_delim=(list_delim : DelimType) : DelimType #

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


[View source]
def list_start : Int #

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


[View source]
def list_start=(list_start : Int32) : Int32 #

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


[View source]
def list_tight=(tight : Bool) : Bool #

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


[View source]
def list_tight? : Bool #

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


[View source]
def list_type : ListType #

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


[View source]
def list_type=(list_type : ListType) : ListType #

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


[View source]
def literal : String #

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


[View source]
def literal=(literal : String) : String #

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


[View source]
def next : Node | Nil #

Returns the next node of this node.


[View source]
def on_enter : String #

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


[View source]
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.


[View source]
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.


[View source]
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.


[View source]
def parent : Node | Nil #

Returns the parent node of this node.


[View source]
def prepend_child(child : Node) #

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


[View source]
def previous : Node | Nil #

Returns the previous node of this node.


[View source]
def render_commonmark(options = Option::None, width = 120) : String #

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


[View source]
def render_html(options = Option::None, extensions = Extension::None) : String #

Renders node tree as an HTML string.


[View source]
def render_latex(options = Option::None, width = 120) : String #

Renders node tree as a LaTeX string.


[View source]
def render_man(options = Option::None, width = 80) : String #

Renders node tree as a groff man page string.


[View source]
def render_plaintext(options = Option::None, width = 120) : String #

Renders node tree as a plaintext string.


[View source]
def render_xml(options = Option::None) : String #

Renders node tree an XML string.


[View source]
def replace_with(new_node : Node) #

Replaces node with new_node; raises TreeManipulationError on failure.


[View source]
def start_column : Int32 #

Returns the column on which node begins.


[View source]
def start_line : Int32 #

Returns the line on which node begins.


[View source]
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.


[View source]
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]

[View source]
def table_cell_alignment : Alignment #

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


[View source]
def table_columns : UInt16 #

Returns the number of columns for the table.

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


[View source]
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.


[View source]
def table_row_header=(header : Bool) : Bool #

Sets a table row as table header.


[View source]
def table_row_header? : Bool #

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


[View source]
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.


[View source]
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.


[View source]
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.


[View source]
def tasklist_item? : Bool #

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


[View source]
def tasklist_item_checked=(checked : Bool) : Bool #

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


[View source]
def tasklist_item_checked? : Bool #

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


[View source]
def title : String #

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


[View source]
def title=(title : String) : String #

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


[View source]
def type : NodeType #

Returns the type of node.


[View source]
def unlink #

Unlinks this node from the AST.


[View source]
def url : String #

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


[View source]
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.


[View source]
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

[View source]
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.


[View source]