.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "CommonMark::Iterator 3pm"
.TH CommonMark::Iterator 3pm "2022-10-20" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
CommonMark::Iterator \- Iterate CommonMark nodes
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use CommonMark qw(:node :event);
\&
\&    my $iter = $doc\->iterator;
\&
\&    while (my ($ev_type, $node) = $iter\->next) {
\&        my $node_type = $node\->get_type;
\&
\&        if ($node_type == NODE_PARAGRAPH) {
\&            if ($ev_type == EVENT_ENTER) {
\&                print("<p>");
\&            }
\&            else {
\&                print("</p>\en");
\&            }
\&        }
\&        elsif ($node_type == NODE_TEXT) {
\&            print($node\->get_literal);
\&        }
\&    }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\f(CW\*(C`CommonMark::Iterator\*(C'\fR provides a convenient way to walk through the nodes
in a parse tree.
.SS "Construction"
.IX Subsection "Construction"
.Vb 1
\&   my $iterator = $node\->iterator;
.Ve
.PP
Creates an iterator from a node. \f(CW$node\fR is the root node of the iterator.
.SS "next"
.IX Subsection "next"
.Vb 2
\&    my $ev_type = $iterator\->next;
\&    my ($ev_type, $node) = $iterator\->next;
.Ve
.PP
The contents of the iterator are initially undefined. After the first and
each subsequent call to \f(CW\*(C`next\*(C'\fR, the iterator holds a new event type and a
new current node. In scalar context, \f(CW\*(C`next\*(C'\fR returns the new event type.
In list context, it returns a 2\-element list consisting of the new event
type and the new current node.
.PP
Event types are:
.PP
.Vb 3
\&    CommonMark::EVENT_DONE
\&    CommonMark::EVENT_ENTER
\&    CommonMark::EVENT_EXIT
.Ve
.PP
Event types can be imported from CommonMark with tag \f(CW\*(C`event\*(C'\fR.
.PP
.Vb 1
\&    use CommonMark qw(:event);
.Ve
.PP
The iterator starts by visiting the root node. Every visited node \f(CW\*(C`V\*(C'\fR
generates the following sequence of events.
.IP "\(bu" 4
Enter the node. The event type is \f(CW\*(C`CommonMark::EVENT_ENTER\*(C'\fR and the current
node is set to the entered node \f(CW\*(C`V\*(C'\fR.
.IP "\(bu" 4
Visit all children of the node \f(CW\*(C`V\*(C'\fR from first to last applying this sequence
of events recursively.
.IP "\(bu" 4
Except for leaf nodes, exit the node. The event type is
\&\f(CW\*(C`CommonMark::EVENT_EXIT\*(C'\fR and the current node is set to the original node
\&\f(CW\*(C`V\*(C'\fR.
.PP
After the root node was exited, the event type is set to
\&\f(CW\*(C`CommonMark::EVENT_DONE\*(C'\fR and the current node to \f(CW\*(C`undef\*(C'\fR. In scalar
context, \f(CW\*(C`next\*(C'\fR returns \f(CW\*(C`CommonMark::EVENT_DONE\*(C'\fR. In list context, it
returns the empty list.
.PP
For leaf nodes, no exit events are generated. Leaf nodes comprise the node
types that never have children:
.PP
.Vb 8
\&    CommonMark::NODE_HTML
\&    CommonMark::NODE_HRULE
\&    CommonMark::NODE_CODE_BLOCK
\&    CommonMark::NODE_TEXT
\&    CommonMark::NODE_SOFTBREAK
\&    CommonMark::NODE_LINEBREAK
\&    CommonMark::NODE_CODE
\&    CommonMark::NODE_INLINE_HTML
.Ve
.PP
For other node types, an exit event is generated even if the node has no
children.
.PP
It is safe to modify nodes after an exit event, or an enter event for leaf
nodes. Otherwise, changes to the tree structure can result in undefined
behavior.
.SS "Accessors"
.IX Subsection "Accessors"
.Vb 3
\&    my $node    = $iter\->get_node;
\&    my $ev_type = $iter\->get_event_type;
\&    my $node    = $iter\->get_root;
.Ve
.PP
These accessors return the current node, the current event type, and the
root node.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
This software is copyright (C) by Nick Wellnhofer.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.