NAME
Markdown::Perl::InlineTree
SYNOPSIS
A tree structure meant to represent the inline elements of a Markdown paragraph.
This package is internal to the implementation of Markdown::Perl and its documentation should be useful only if you are trying to modify the library.
Otherwise please refer to the Markdown::Perl and pmarkdown documentation.
DESCRIPTION
new
my $tree = Markdown::Perl::InlineTree->new();The constructor currently does not support any options.
new_text, new_code, new_link, new_literal
my $text_node = new_text('text content');
my $code_node = new_code('code content');
my $link_node = new_link('text content', type=> 'type', target => 'the target'[, title => 'the title']);
my $link_node = new_link($subtree_content, type=> 'type', target => 'the target'[, title => 'the title']);
my $html_node = new_html('<raw html content>');
my $style_node = new_literal($subtree_content, 'html_tag');
my $literal_node = new_literal('literal content');These methods return a text node that can be inserted in an InlineTree.
is_node, is_tree
These two methods returns whether a given object is a node that can be inserted in an InlineTree and whether it’s an InlineTree object.
push
$tree->push(@nodes_or_trees);Push a list of nodes at the end of the top-level nodes of the current tree.
If passed InlineTree objects, then the nodes of these trees are pushed (not the tree itself).
replace
$tree->replace($index, @nodes);Remove the existing node at the given index and replace it by the given list of nodes (or, if passed InlineTree objects, their own nodes).
insert
$tree->insert($index, @new_nodes);Inserts the given nodes (or, if passed InlineTree objects, their own nodes) at the given index. After the operation, the first inserted node will have that index.
extract
$tree->extract($start_child, $start_offset, $end_child, $end_offset);Extract the content of the given tree, starting at the child with the given index (which must be a text node) and at the given offset in the child’s text, and ending at the given node and offset (which must also be a text node).
That content is removed from the input tree and returned as a new InlineTree object. Returns a pair with the new tree and the index of the first child after the removed content in the input tree. Usually it will be $start_child + 1, but it can be $start_child if $start_offset was 0.
In scalar context, returns only the extracted tree.
map_shallow
$tree->map_shallow($sub);Apply the given sub to each direct child of the tree. The sub can return a node or a tree and that returned content is concatenated to form a new tree.
Only the top-level nodes of the tree are visited.
In void context, update the tree in-place. Otherwise, the new tree is returned.
In all cases, $sub must return new nodes or trees, it can’t modify the input object. The argument to $sub are passed in the usual way in @_, not in $_.
map
$tree->map($sub);Same as map_shallow, but the tree is visited recursively. The subtree of individual nodes are visited and their content replaced before the node itself are visited.
apply
$tree->apply($sub);Apply the given $sub to all nodes of the tree. The sub receives the current node in $_ and can modify it. The return value of the sub is ignored.
clone
my $new_tree = $tree->clone([$child_start, $child_end]);Clone (deep copy) the entire tree or a portion of it.
fold
$tree->fold($sub, $init);Iterates over the top-level nodes of the tree, calling $sub for each of them. It receives two arguments, the current node and the result of the previous call. The first call receives $init as its second argument.
Returns the result of the last call of $sub.
find_in_text
$tree->find_in_text($regex, $start_child, $start_offset, [$end_child, $end_offset]);Find the first match of the given regex in the tree, starting at the given offset in the node. This only considers top-level nodes of the tree and skip over non text node (including the first one).
If $end_child and $end_offset are given, then does not look for anything starting at or after that bound.
Does not match the regex across multiple nodes.
Returns $child_number, $match_start_offset, $match_end_offset (or just a true value in scalar context) or undef.
find_balanced_in_text
$tree->find_balanced_in_text(
$open_re, $close_re, $start_child, $start_offset, $child_bound, $text_bound);Same as find_in_text except that this method searches for both $open_re and $close_re and, each time $open_re is found, it needs to find $close_re one more time before we it returns. The method assumes that $open_re has already been seen once before the given $start_child and $start_offset.
find_in_text_with_balanced_content
$tree->find_in_text_with_balanced_content(
$open_re, $close_re, $end_re, $start_child, $start_offset,
$child_bound, $text_bound);Similar to find_balanced_in_text except that this method ends when $end_re is seen, after the $open_re and $close_re regex have been seen a balanced number of time. If the closing one is seen more than the opening one, the search succeeds too. The method does not assumes that $open_re has already been seen before the given $start_child and $start_offset (as opposed to find_balanced_in_text).
render_html
$tree->render_html();Returns the HTML representation of that InlineTree.
to_text
$tree->to_text();Returns the text content of this InlineTree discarding all HTML formatting. This is used mainly to produce the alt text of image nodes (which can contain any Markdown construct in the source).
to_source_text
$tree->to_source_text($unescape_literal);Returns the original Markdown source corresponding to this InlineTree. This is used to produce the reference label, target and title of link elements and so can support only node types that have a higher priority than links (nodes that may have been built already when this is called).
The source is returned as-is, the HTML entities are neither decoded nor escaped.
If $unescape_literal is true, then literal values that were escaped in the source are unescaped (e.g. \; will appear again as \;). Otherwise they will just appear as their literal value (e.g. ;).
As a readability facility, the UNESCAPE_LITERAL symbol can be used to pass this option (with a value of 1).
span_to_source_text
$tree->span_to_source_text($child_start, $text_start, $child_end, $text_end[, $unescape_literal]);Same as to_source_text() but only renders the specified span of the InlineTree.