class Cmark::Node
- Cmark::Node
- Reference
- Object
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:
-
Tree traversal
-
Accessors
#type
#literal
#literal=
#heading_level
#heading_level=
#list_type
#list_type=
#list_delim
#list_delim=
#list_start
#list_start=
#list_tight?
#list_tight=
#fence_info
#fence_info=
#fencing_details
#fencing_details=
#url
#url=
#title
#title=
#on_enter
#on_enter=
#on_exit
#on_exit=
#user_data
#user_data=
#start_line
#end_line
#start_column
#end_column
#autolink?
#table_string_content
#table_string_content=
#table_columns
#table_columns=
#table_alignments
#table_alignments=
#table_row_header?
#table_row_header=
#tasklist_item?
#tasklist_item=
#tasklist_item_checked?
#tasklist_item_checked=
#footnote_reference_index
#footnote_definition_count
#footnote_definition_literal
#footnote_parent_definition_literal
-
Tree manipulation
-
Rendering
-
Equality
-
Containment
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.crInstance Method Summary
-
#==(other : Node)
Returns true if both instances point to the same underlying node structure.
-
#append_child(child : Node)
Adds child to the end of the children of node; raises
TreeManipulationError
on failure. -
#autolink? : Bool
Returns true if the node is a Commonmark autolink, false otherwise.
-
#can_contain?(node_type : NodeType) : Bool
Returns true node can contain node_type, false otherwise.
-
#children : Array(Node)
Returns children nodes or an empty array if there are none.
-
#consolidate_text_nodes
Consolidates adjacent text nodes.
-
#end_column : Int32
Returns the column on which node ends.
-
#end_line : Int32
Returns the line on which node ends.
-
#fence_info : String
Returns the info string of a fenced code block.
-
#fence_info=(info : String) : String
Sets the info string of a fenced code block; on failure it raises
NodeSetterError
. -
#fencing_details : FencingDetails | Nil
Returns fencing details of a code block.
-
#fencing_details=(details : FencingDetails) : FencingDetails
Sets fencing details of a code block; on failure it raises
NodeSetterError
. -
#first_child : Node | Nil
Returns the first_child node of this node.
-
#footnote_definition_count : Int32
Returns the count the footnote definition.
-
#footnote_definition_literal : String
Returns the definition literal of the footnote.
-
#footnote_parent_definition_literal : String
Returns the definition literal of the footnote for this reference.
-
#footnote_reference_index : Int32
Returns the index of the footnote reference.
-
#grandparent : Node | Nil
Returns the grandparent node of this node.
-
#heading_level : Int32
Returns the heading level of node, or 0 if node is not a heading.
-
#heading_level=(heading_level : Int32) : Int32
Sets the heading level of node; on failure it raises
NodeSetterError
. -
#insert_after(sibling : Node)
Inserts sibling after node; raises
TreeManipulationError
on failure. -
#insert_before(sibling : Node)
Inserts sibling before node; raises
TreeManipulationError
on failure. -
#last_child : Node | Nil
Returns the last_child node of this node.
-
#list_delim : DelimType
Returns the list delimiter of node, using
DelimType::None
if node is not a list. -
#list_delim=(list_delim : DelimType) : DelimType
Sets the list delimiter of node; on failure it raises
NodeSetterError
. -
#list_start : Int
Returns starting number of node, if it is an ordered list, otherwise 0.
-
#list_start=(list_start : Int32) : Int32
Sets the list delimiter of node; on failure it raises
NodeSetterError
. -
#list_tight=(tight : Bool) : Bool
Sets the list tightness of node; on failure it raises
NodeSetterError
. -
#list_tight? : Bool
Returns true if node is a tight list, or false if loose.
-
#list_type : ListType
Returns the list type of node, using
ListType::None
if node is not a list. -
#list_type=(list_type : ListType) : ListType
Sets the list type of node; on failure it raises
NodeSetterError
. -
#literal : String
Returns the literal string contents of node, or an empty string if none is set.
-
#literal=(literal : String) : String
Sets the literal string contents of node; on failure it raises
NodeSetterError
. -
#next : Node | Nil
Returns the next node of this node.
-
#on_enter : String
Returns the literal on_enter of a custom node or an empty string if unset.
-
#on_enter=(on_enter : String) : String
Sets the literal on_enter of a custom node; on failure it raises
NodeSetterError
. -
#on_exit : String
Returns the literal on_exit of a custom node or an empty string if unset.
-
#on_exit=(on_exit : String) : String
Sets the literal on_exit of a custom node; on failure it raises
NodeSetterError
. -
#parent : Node | Nil
Returns the parent node of this node.
-
#prepend_child(child : Node)
Adds child to the beginning of the children of node; raises
TreeManipulationError
on failure. -
#previous : Node | Nil
Returns the previous node of this node.
-
#render_commonmark(options = Option::None, width = 120) : String
Renders node tree as a commonmark string, including GFM extension nodes, if present.
-
#render_html(options = Option::None, extensions = Extension::None) : String
Renders node tree as an HTML string.
-
#render_latex(options = Option::None, width = 120) : String
Renders node tree as a LaTeX string.
-
#render_man(options = Option::None, width = 80) : String
Renders node tree as a groff man page string.
-
#render_plaintext(options = Option::None, width = 120) : String
Renders node tree as a plaintext string.
-
#render_xml(options = Option::None) : String
Renders node tree an XML string.
-
#replace_with(new_node : Node)
Replaces node with new_node; raises
TreeManipulationError
on failure. -
#start_column : Int32
Returns the column on which node begins.
-
#start_line : Int32
Returns the line on which node begins.
-
#table_alignments : Array(Alignment)
Returns the alignments of columns for the table.
-
#table_alignments=(alignments : Array(Alignment)) : Array(Alignment)
Sets the alignments of columns for the table; on failure it raises
NodeSetterError
. -
#table_cell_alignment : Alignment
Returns node table alignment or
Alignment::None
if called on a node that is not a table cell. -
#table_columns : UInt16
Returns the number of columns for the table.
-
#table_columns=(n_columns : UInt16) : UInt16
Sets the number of columns for the table; on failure it raises
NodeSetterError
. -
#table_row_header=(header : Bool) : Bool
Sets a table row as table header.
-
#table_row_header? : Bool
Returns true if the the node is a header table row, false otherwise.
-
#table_string_content : String
Returns the string content of tables and table cells, otherwise an empty string.
-
#table_string_content=(content : String) : String
Sets the table string content for tables and table cells.
-
#tasklist_item=(tasklist : Bool) : Bool
Sets a list item as tasklist item; on failure it raises
NodeSetterError
. -
#tasklist_item? : Bool
Returns true is a node is a tasklist item, false otherwise.
-
#tasklist_item_checked=(checked : Bool) : Bool
Sets the checked status of tasklist item: on failure it raises
NodeSetterError
. -
#tasklist_item_checked? : Bool
Returns true is a node is a tasklist_item and is checked, false otherwise.
-
#title : String
Returns the title of a link or image node, or an empty string if no title is set.
-
#title=(title : String) : String
Sets the title of a link or image node; on failure it raises
NodeSetterError
. -
#type : NodeType
Returns the type of node.
-
#unlink
Unlinks this node from the AST.
-
#url : String
Returns the URL of a link or image node, or an empty string if no URL is set.
-
#url=(url : String) : String
Sets the URL of node; on failure it raises
NodeSetterError
. -
#user_data : Pointer(Void)
Returns the user data of node, which can then be unboxed.
-
#user_data=(user_data : Pointer(Void)) : Pointer(Void)
Sets the user data of node, which should be already boxed; on failure it raises
NodeSetterError
.
Instance Method Detail
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.
Returns true node can contain node_type, false otherwise.
Sets the info string of a fenced code block; on failure it raises NodeSetterError
.
Returns fencing details of a code block.
Returns nil if called on a node that is not a code block.
Returns the count the footnote definition.
Returns 0 if the node is not a footnote definition.
Returns the definition literal of the footnote.
Returns an empty string if the node is not a footnote definition.
Returns the definition literal of the footnote for this reference.
Returns an empty string if the node is not a footnote reference.
Returns the index of the footnote reference.
Returns 0 if the node is not a footnote reference.
Sets the heading level of node; on failure it raises NodeSetterError
.
Sets the list delimiter of node; on failure it raises NodeSetterError
.
Sets the list tightness of node; on failure it raises NodeSetterError
.
Returns the literal string contents of node, or an empty string if none is set.
Sets the literal string contents of node; on failure it raises NodeSetterError
.
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.
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.
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.
Renders node tree as a commonmark string, including GFM extension nodes, if present.
Renders node tree as an HTML string.
Renders node tree as a LaTeX string.
Renders node tree as a groff man page string.
Renders node tree as a plaintext string.
Returns the alignments of columns for the table.
Returns an empty array if called on a node that is not a table.
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]
Returns the number of columns for the table.
Returns 0 if called on a node that is not a table.
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.
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
.
Sets the table string content for tables and table cells.
Beware of setting incorrect string content.
See #table_string_content
for more information.
Sets a list item as tasklist item; on failure it raises NodeSetterError
.
It must be called only on nodes with NodeType::Item
.
Sets the checked status of tasklist item: on failure it raises NodeSetterError
.
Returns true is a node is a tasklist_item and is checked, false otherwise.
Returns the title of a link or image node, or an empty string if no title is set.
Sets the title of a link or image node; on failure it raises NodeSetterError
.
Sets the URL of node; on failure it raises NodeSetterError
.
It must be called only on link or image nodes.
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
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
.