--- name: "CommonMark::Node" section: "3pm" platform: "linux" package: "libcommonmark-perl" version: "0.310100-1+b1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/CommonMark::Node" --- # CommonMark::Node(3pm) Node of the CommonMark parse tree ## 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 `"
"` 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.