Provided by: libpod-tree-perl_1.17-1_all bug

NAME

       Pod::Tree::Node - nodes in a Pod::Tree

SYNOPSIS

         $node = root     Pod::Tree::Node \@paragraphs;
         $node = code     Pod::Tree::Node $paragraph;
         $node = verbatim Pod::Tree::Node $paragraph;
         $node = command  Pod::Tree::Node $paragraph;
         $node = ordinary Pod::Tree::Node $paragraph;
         $node = letter   Pod::Tree::Node $token;
         $node = sequence Pod::Tree::Node $letter, \@children;
         $node = text     Pod::Tree::Node $text;
         $node = target   Pod::Tree::Node $target;
         $node = link     Pod::Tree::Node $node, $page, $section;

         is_code     $node and ...
         is_command  $node and ...
         is_for      $node and ...
         is_item     $node and ...
         is_letter   $node and ...
         is_list     $node and ...
         is_ordinary $node and ...
         is_pod      $node and ...
         is_root     $node and ...
         is_sequence $node and ...
         is_text     $node and ...
         is_verbatim $node and ...
         is_link     $node and ...

         is_c_head1  $node and ...
         is_c_head2  $node and ...
         is_c_head3  $node and ...
         is_c_head4  $node and ...
         is_c_cut    $node and ...
         is_c_pod    $node and ...
         is_c_over   $node and ...
         is_c_back   $node and ...
         is_c_item   $node and ...
         is_c_for    $node and ...
         is_c_begin  $node and ...
         is_c_end    $node and ...

         $arg       = get_arg       $node;
         $brackets  = get_brackets  $node;
         $children  = get_children  $node;
         $command   = get_command   $node;
         $domain    = get_domain    $node;
         $item_type = get_item_type $node;
         $letter    = get_letter    $node;
         $list_type = get_list_type $node;
         $page      = get_page      $node;
         $raw       = get_raw       $node;
         $raw_kids  = get_raw_kids  $node;
         $section   = get_section   $node;
         $siblings  = get_siblings  $node;
         $target    = get_target    $node;
         $text      = get_text      $node;
         $type      = get_type      $node;
         $deep_text = get_deep_text $node;

         $node->force_text($text);
         $node->force_for;
         $node->parse_begin (\@nodes);
         $node->set_children(\@children);
         $node->make_sequences;
         $node->parse_links;
         $node->unescape;
         $node->consolidate;
         $node->make_lists;

         $node->clone;
         $node->dump;

         Pod::Tree::Node->set_filename($filename);
         $filename = $node->get_filename;

REQUIRES

       Pod::Escapes

DESCRIPTION

       "Pod::Tree::Node" objects are nodes in a tree that represents a POD.  Applications walk
       the tree to recover the structure and content of the POD.

       Methods are provided for

       •   creating nodes in the tree

       •   parsing the POD into nodes

       •   returning information about nodes

       •   walking the tree

TREE STRUCTURE

   Root node
       The tree descends from a single root node; "is_root" returns true on this node and no
       other.

               $children = $root->get_children

       returns a reference to an array of nodes.  These nodes represent the POD.

   Node types
       For each node, call "get_type" to discover the type of the node

               for $child (@$children)
               {
                   $type = $child->get_type;
               }

       $type will be one of these strings:

       'root'
           The node is the root of the tree.

       'code'
           The node represents a paragraph that is not part of the POD.

       'verbatim'
           The node represents a verbatim paragraph.

       'ordinary'
           The node represents an ordinary paragraph.

       'command'
           The node represents an =command paragraph (but not an =over paragraph).

       'sequence'
           The node represents an interior sequence.

       'target'
           The node represents the target of a link (An L<> markup).

       'text'
           The node represents text that contains no interior sequences.

       'list'
           The node represents an =over list.

       'item'
           The node represents an item in an =over list.

       'for'
           The node represents a =for paragraph, or it represents the paragraphs between
           =begin/=end commands.

       Here are instructions for walking these node types.

   root node
       Call

               $children = $node->get_children

       to get a list of nodes representing the POD.

   code nodes
       A code node contains the text of a paragraph that is not part of the POD, for example, a
       paragraph that follows an "=cut" command. Call

               $text = $node->get_text

       to recover the text of the paragraph.

   verbatim nodes
       A verbatim node contains the text of a verbatim paragraph.  Call

               $text = $node->get_text

       to recover the text of the paragraph.

   ordinary nodes
       An ordinary node represents the text of an ordinary paragraph.  The text is parsed into a
       list of text and sequence nodes; these nodes are the children of the ordinary node.  Call

               $children = $node->get_children

       to get a list of the children.  Iterate over this list to recover the text of the
       paragraph.

   command nodes
       A command node represents an =command paragraph.  Call

               $command = $node->get_command;

       to recover the name of the command.  The name is returned without the equals sign.

       =over paragraphs are represented by list nodes, not command nodes; see "list nodes",
       below.

       The text of a command paragraph is parsed into a list of text and sequence nodes; these
       nodes are the children of the command node.  Call

               $children = $node->get_children;

       to get a list of the children.  Iterate over this list to recover the text of the
       paragraph.

   sequence nodes
       A sequence node represents a single interior sequence (a <> markup).  Call

               $node->get_letter

       to recover the original markup letter.  The contents of the markup are parsed into a list
       of text and sequence nodes; these nodes are the children of the sequence node.  Call

               $node->get_children

       to recover them.

       Z<> and E<> markups do not generate sequence nodes; these markups are expanded by
       "Pod::Tree" when the tree is built.

   target nodes
       If a sequence node represents a link (an "L<>" markup), then

               is_link $node

       returns true and

               $target = $node->get_target

       returns a node representing the target of the link.

       "Pod::Tree::Node" can represent targets in two domains: "POD" and "HTTP".  The "POD"
       domain represents the

               L<page/section>

       markups that are described in perlpod.  The "HTTP" domain represents "L<>" markups that
       contain a URL, e.g.

               L<http://foo.bar.com/page.html#fragment>

       Call

               $domain = $target->get_domain

       to discover the domain of the target.  For targets in the POD domain, call

               $page    = $target->get_page;
               $section = $target->get_section;

       to recover the man page and section that the link refers to.  For targets in the HTTP
       domain, call

               $url     = $target->get_page;

       to recover the URL for the link.

       $target is used only for constructing hyper-links; the text to be displayed for the link
       is recovered by walking the children of $node, as for any other interior sequence.

   text nodes
       A text node represents text that contains no interior sequences.  Call

               $text = $node->get_text

       to recover the text.

   list nodes
       A list node represents an =over list.  Call

               $list_type = $node->get_list_type;

       to discover the type of the list. This will be one of the strings

       'bullet'
       'number'
       'text'

       The type of a list is the type of the first item in the list.

       The children of a list node are item nodes; each item node represents one item in the
       list.

       You can call

               $node->get_arg;

       to recover the indent value following the =over.

   item nodes
       An item node represents one item in an =over list.  Call

               $item_type = $node->get_item_type;

       to discover the type of the item.  This will be one of the strings shown above for "list
       nodes".  Typically, all the items in a list have the same type, but "Pod::Tree::Node"
       doesn't assume this.

       The children of an item node represent the text of the =item paragraph; this is usually of
       interest only for 'text' items.  Call

               $children = $node->get_children

       to get a list of the children; these will be sequence and text nodes, as for any other
       =command paragraph.

       Each item node also has a list of nodes representing all the paragraphs following it, up
       to the next =item command, or the end of the list.  These nodes are called siblings of the
       item node.  Call

               $siblings = $node->get_siblings

       to get a list of sibling nodes.

   for nodes
       for nodes represent text that is to be passed to an external formatter.  Call

               $formatter = $node->get_arg;

       to discover the name of the formatter.  Call

               $text = $node->get_text;

       to obtain the text to be passed to the formatter.  This will either be the text of an =for
       command, or all of the text between =begin and =end commands.

   Walking the tree
       PODs have a recursive structure; therefore, any application that walks a Pod::Tree must
       also be recursive.  See skeleton for an example of the necessary code.

METHODS

   Constructors
       These methods construct "Pod::Tree::Node" objects.  They are used to build trees.  They
       aren't necessary to walk trees.

         $node = root     Pod::Tree::Node \@paragraphs;
         $node = code     Pod::Tree::Node $paragraph;
         $node = verbatim Pod::Tree::Node $paragraph;
         $node = command  Pod::Tree::Node $paragraph;
         $node = ordinary Pod::Tree::Node $paragraph;
         $node = letter   Pod::Tree::Node $token;
         $node = sequence Pod::Tree::Node $letter, \@children;
         $node = text     Pod::Tree::Node $text;
         $node = target   Pod::Tree::Node $target;
         $node = link     Pod::Tree::Node $node, $page, $section;

       $link = "Pod::Tree::Node"->"link"($node, $page, $section)
           Creates a new sequence node representing an "L<>" markup.  $node becomes the sole
           child of the new node.  The target of the node is constructed from $page and $section.

           This method isn't used to parse PODs.  It is provided for applications that want to
           create new links in an existing "Pod::Tree" structure.

   Tests
       These methods return true iff $node has the type indicated by the method name.

         is_code     $node and ...
         is_command  $node and ...
         is_for      $node and ...
         is_item     $node and ...
         is_letter   $node and ...
         is_link     $node and ...
         is_list     $node and ...
         is_ordinary $node and ...
         is_pod      $node and ...
         is_root     $node and ...
         is_sequence $node and ...
         is_text     $node and ...
         is_verbatim $node and ...

       "is_pod" returns true for all nodes except code, "=pod", and "=cut" nodes.

       These methods return true iff $node is a command node, and the command is the one
       indicated by the method name.

         is_c_head1  $node and ...
         is_c_head2  $node and ...
         is_c_head3  $node and ...
         is_c_head4  $node and ...
         is_c_cut    $node and ...
         is_c_pod    $node and ...
         is_c_over   $node and ...
         is_c_back   $node and ...
         is_c_item   $node and ...
         is_c_for    $node and ...
         is_c_begin  $node and ...
         is_c_end    $node and ...

   Accessors
       These methods return information about nodes.  Most accessors are only relevant for
       certain types of nodes.

       $arg = "get_arg" $node
           Returns the argument of $node.  This is the number following an =over command, or the
           name of an external translator for =for, =begin, and =end commands.  Only relevant for
           these four command nodes.

       $brackets = "get_brackets" $node
           Only relevant for for nodes.

           If the node represents an =for command, @$brackets is a single-element list.  The list
           element is the text of the =for command and its argument, i.e. the name of the
           external formatter.

           If the node represents a =begin/=end construct, @$brackets is a two-element list
           containing the text of the =begin and =end paragraphs.

       $children = "get_children" $node
           Returns a reference to the list of nodes that are children of $node.  May be called on
           any node.  The list may be empty.

       $command = "get_command" $node
           Returns the name of a command, without the equals sign.  Only relevant for command
           nodes.

       $domain = "get_domain" $node
           Only relevant for target nodes.  Returns the domain of the target.  This will be one
           of the strings

           'HTTP'
           'POD'
       $item_type = "get_item_type" $node
           Returns the type of an item node. The type will be one of

           'bullet'
           'number'
           'text'
       $letter = "get_letter" $node
           Returns the letter that introduces an interior sequence.  Only relevant for sequence
           nodes.

       $list_type = "get_list_type" $node
           Returns the type of a list node.  The type of a list node is the type of the first
           item node in the list.

       $page = "get_page" $node
           Only relevant for target nodes.  For targets in the "POD" domain, returns the man page
           that is the target of the link.  For targets in the "HTTP" domain, returns the URL
           that is the target of the link.

       $raw = "get_raw" $node
           Returns the original text of a paragraph.  Currently provided for command, verbatim,
           and ordinary paragraphs.

       $raw_kids = "get_raw_kids" $node
           Only provided for L<> sequence nodes.  Returns a reference to a list of nodes
           representing the entire text of the L<> sequence, including any part following a
           vertical bar (|).

           The original text of the L<> markup can be reconstructed from this list.

       $section = "get_section" $node
           Only relevant for target nodes in the "POD" domain.  Returns the section that is the
           target of a link.

       $siblings = "get_siblings" $node
           Returns the siblings of a node.  May be called on any node.  Only item nodes have
           siblings.

       $target = "get_target" $node
           Returns the target of a node.  Only relevant for sequence nodes that represent links
           ("L<>" markups).  "is_link" returns true on these nodes.

       $text = "get_text" $node
           Returns the text of a node.  $text will not contain any interior sequences.  Only
           relevant for text nodes.

       $type = "get_type" $node
           Returns the type of $node.  May be called on any node.  See "TREE STRUCTURE" for
           descriptions of the node types.

       $deep_text = "get_deep_text" $node
           Recursively walks the children of a node, catenates together the text from each node,
           and returns all that text as a single string.  All interior sequence markups are
           discarded.

           "get_deep_text" is provided as a convenience for applications that want to ignore
           markups in a POD paragraph.

   Parsing
       These methods manipulate the tree while it is being built.  They aren't necessary to walk
       the tree.

         $node->force_text($text)
         $node->force_for;
         $node->parse_begin (\@nodes);
         $node->set_children(\@children);
         $node->make_sequences;
         $node->parse_links;
         $node->unescape;
         $node->consolidate;
         $node->make_lists;

   Utility
       $node->"clone"
           Returns a deep copy of a node.  Only implemented for "text" and "sequence" nodes.

       $node->"dump"
           Returns a string containing a pretty-printed representation of the node.  Calling
           "dump" on the root node of a tree will show the entire POD.

       "Pod::Tree::Node"->"set_filename"($filename)
           Sets the file name to be reported in error messages.

       $filename = $node->"getfile_name"
           Returns the file name set by "set_file_name".

EXAMPLES

       The t/ directory in the "Pod::Tree" distribution contains examples of PODs, together with
       dumps of the trees that "Pod::Tree" constructs for them.  The tree for "t/"file".pod" is
       in "t/"file".p_exp".

       "Pod::Tree::Node::dump" is a simple example of code that walks a POD tree.

       skeleton is a skeleton application that walks a POD tree.

NOTES

       •   There is no provision in perlpod for "L<>" markups to contain URLs, but due to popular
           demand, this is now supported in "Pod::Tree::Node".

SEE ALSO

       perl(1), "Pod::Tree"

AUTHOR

       Steven McDougall, swmcd@world.std.com

COPYRIGHT

       Copyright (c) 1999-2004 by Steven McDougall. This module is free software; you can
       redistribute it and/or modify it under the same terms as Perl itself.