NAME

       CommonMark::Iterator - Iterate CommonMark nodes

SYNOPSIS

           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>\n");
                   }
               }
               elsif ($node_type == NODE_TEXT) {
                   print($node->get_literal);
               }
           }

DESCRIPTION

       "CommonMark::Iterator" provides a convenient way to walk through the nodes in a parse
       tree.

   Construction
          my $iterator = $node->iterator;

       Creates an iterator from a node. $node is the root node of the iterator.

   next
           my $ev_type = $iterator->next;
           my ($ev_type, $node) = $iterator->next;

       The contents of the iterator are initially undefined. After the first and each subsequent
       call to "next", the iterator holds a new event type and a new current node. In scalar
       context, "next" 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.

       Event types are:

           CommonMark::EVENT_DONE
           CommonMark::EVENT_ENTER
           CommonMark::EVENT_EXIT

       Event types can be imported from CommonMark with tag "event".

           use CommonMark qw(:event);

       The iterator starts by visiting the root node. Every visited node "V" generates the
       following sequence of events.

       •   Enter the node. The event type is "CommonMark::EVENT_ENTER" and the current node is
           set to the entered node "V".

       •   Visit all children of the node "V" from first to last applying this sequence of events
           recursively.

       •   Except for leaf nodes, exit the node. The event type is "CommonMark::EVENT_EXIT" and
           the current node is set to the original node "V".

       After the root node was exited, the event type is set to "CommonMark::EVENT_DONE" and the
       current node to "undef". In scalar context, "next" returns "CommonMark::EVENT_DONE". In
       list context, it returns the empty list.

       For leaf nodes, no exit events are generated. Leaf nodes comprise the node types that
       never have children:

           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

       For other node types, an exit event is generated even if the node has no children.

       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.

   Accessors
           my $node    = $iter->get_node;
           my $ev_type = $iter->get_event_type;
           my $node    = $iter->get_root;

       These accessors return the current node, the current event type, and the root node.

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.