table of contents
CommonMark::Node(3pm) | User Contributed Perl Documentation | CommonMark::Node(3pm) |
NAME¶
CommonMark::Node - Node of the CommonMark parse tree
SYNOPSIS¶
my $html = $node->render(format => 'html'); my $header = $doc->first_child; my $level = $header->get_header_level; my $paragraph = $header->next; my $link = CommonMark::Node->new(CommonMark::NODE_LINK); $link->set_url('http://example.com/'); my $text = CommonMark::Node->new(CommonMark::NODE_TEXT); $text->set_literal('link text'); $link->append_child($link_text); $paragraph->append_child($link); $doc->render_html;
DESCRIPTION¶
"CommonMark::Node" represents a node of the parse tree.
new¶
my $node = CommonMark::Node->new($type);
Creates a new node of type $type. See "Node types" for a list of types. Note that the node creation functions provide a more powerful interface.
Rendering¶
"render"
my $result = $node->render( format => $string, sourcepos => $bool, # Optional hardbreaks => $bool, # Optional nobreaks => $bool, # Optional unsafe => $bool, # Optional width => $int, # Optional );
Convenience function to render documents. Supported "format"s are 'html', 'xml', 'man', 'commonmark', and 'latex'.
The "width" specifies the number of characters at which lines are broken, and is passed to renderers that support it. A value of 0 disables line wrapping. The default is 0.
The remaining options enable the respective render options:
- "sourcepos"
- "hardbreaks"
- "unsafe"
- "nobreaks"
- "safe" (no-op as of libcmark 0.29)
"render_*"
my $html = $node->render_html( [$options] ) my $xml = $node->render_xml( [$options] ) my $man = $node->render_man( [$options], [$width] ) my $md = $node->render_commonmark( [$options], [$width] ) my $latex = $node->render_latex( [$options], [$width] )
These methods render the contents of the node in the respective format.
$options is a bit field created by ORing render options. It may be omitted and defaults to "OPT_DEFAULT".
$width specifies the number of characters at which lines are broken. A value of 0 disables line wrapping. The default is 0.
Render options¶
Render options can be imported from CommonMark with tag "opt".
use CommonMark qw(:opt);
- "OPT_SOURCEPOS"
- Adds information about line numbers in the source file to the XML and HTML formats.
- "OPT_HARDBREAKS"
- Translates "softbreak" nodes (typically corresponding to newlines in the input) to hard line breaks. This is only supported by some renderers. The HTML renderer, for example, generates a "<br />" instead of a newline character.
- "OPT_NOBREAKS"
- Translates "softbreak" nodes to spaces. Requires libcmark 0.26 or higher.
- "OPT_UNSAFE"
- Only affects the HTML renderer. It allows raw HTML blocks and some dangerous links.
- "OPT_OPT_SAFE"
- Replaces raw HTML with a placeholder HTML comment. This option has no effect with libcmark 0.29 or higher, where "Safe" mode is the default.
See the documentation of libcmark for a more detailed explanation of the render options.
Accessors¶
# Integer values my $int = $node->get_type; my $int = $node->get_header_level; my $int = $node->get_list_type; my $int = $node->get_list_delim; my $int = $node->get_list_start; my $int = $node->get_list_tight; my $int = $node->get_start_line; my $int = $node->get_start_column; my $int = $node->get_end_line; my $int = $node->get_end_column; $node->set_header_level($int); $node->set_list_type($int); $node->set_list_delim($int); $node->set_list_start($int); $node->set_list_tight($int); # String values my $string = $node->get_type_string; my $string = $node->get_literal; my $string = $node->get_title; my $string = $node->get_url; my $string = $node->get_fence_info; my $string = $node->get_on_enter; my $string = $node->get_on_exit; $node->set_literal($string); $node->set_title($string); $node->set_url($string); $node->set_fence_info($string); $node->set_on_enter($string); $node->set_on_exit($string);
Various accessors to get and set integer and string values of a node. Not all values are supported by every type of node. Getters return 0 or "undef" for unsupported values. Setters die on failure.
See "Constants" for a list of constants used for node types, list types, and list delimiters.
Tree traversal¶
my $iterator = $node->iterator;
Creates a new CommonMark::Iterator to walk through the descendants of the node.
my $next = $node->next; my $prev = $node->previous; my $parent = $node->parent; my $child = $node->first_child; my $child = $node->last_child;
These methods return the respective node in the tree structure.
Tree manipulation¶
$node->unlink; $node->replace($other); $node->insert_before($other); $node->insert_after($other); $node->prepend_child($other); $node->append_child($other);
"unlink" removes a node and all its descendants from the tree.
"replace" replaces $node with $other, unlinking $node.
"insert_before" and "insert_after" insert the $other node before or after $node. "append_child" and "prepend_child" append or prepend $other to the children of $node. $other is unlinked before it is moved to its new position.
These methods may die on failure, for example if the document structure is violated.
Constants¶
Node types
CommonMark::NODE_NONE => 0 CommonMark::NODE_DOCUMENT CommonMark::NODE_BLOCK_QUOTE CommonMark::NODE_LIST CommonMark::NODE_ITEM CommonMark::NODE_CODE_BLOCK CommonMark::NODE_HTML_BLOCK CommonMark::NODE_CUSTOM_BLOCK CommonMark::NODE_PARAGRAPH CommonMark::NODE_HEADING CommonMark::NODE_THEMATIC_BREAK CommonMark::NODE_TEXT CommonMark::NODE_SOFTBREAK CommonMark::NODE_LINEBREAK CommonMark::NODE_CODE CommonMark::NODE_HTML_INLINE CommonMark::NODE_CUSTOM_INLINE CommonMark::NODE_EMPH CommonMark::NODE_STRONG CommonMark::NODE_LINK CommonMark::NODE_IMAGE
Node types can be imported from CommonMark with tag "node".
use CommonMark qw(:node);
List types
CommonMark::NO_LIST => 0 CommonMark::BULLET_LIST CommonMark::ORDERED_LIST
List types can be imported from CommonMark with tag "list".
use CommonMark qw(:list);
Delimiter types for ordered lists
CommonMark::NO_DELIM => 0 CommonMark::PERIOD_DELIM CommonMark::PAREN_DELIM
Delimiter types can be imported from CommonMark with tag "delim".
use CommonMark qw(:delim);
COPYRIGHT¶
This software is copyright (C) by Nick Wellnhofer.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
2024-08-17 | perl v5.38.2 |