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 formats 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.

cpanm CommonMark

perl -MCPAN -e shell
install CommonMark