Pod::Tree - Create a static syntax tree for a POD

       •   <crazyinsomniac@yahoo.com>

       •   <joenio@cpan.org>

       •   Paul Bettinger <paul@n8geil.de>

       •   Sean M. Burke <sburke@spinn.net>

       •   Brad Choate <brad@bradchoate.com>

       •   Havard Eidnes <he@NetBSD.org>

       •   Rudi Farkas <rudif@bluemail.ch>

       •   Paul Gibeault <pagibeault@micron.com>

       •   Jay Hannah <jhannah@omnihotels.com>

       •   Paul Hawkins <phawkins@datajunction.com>

       •   Jost Krieger <Jost.Krieger@ruhr-uni-bochum.de>

       •   Marc A. Lehmann <pcg@goof.com>

       •   Jonas Liljegren <jonas@jonas.rit.se>

       •   Thomas Linden <tom@co.daemon.de>

       •   Johan Lindstrom <johanl@bahnhof.se>

       •   Terry Luedtke <terry_luedtke@nlm.nih.gov>

       •   Rob Napier <rnapier@employees.org>

       •   Kate L Pugh <kake@earth.li>

       •   Christopher Shalah <trance@drizzle.com>

       •   Johan Vromans <JVromans@Squirrel.nl>

       Steven    McDougall    <swmcd@world.std.com>    Currently    maintained    by    Mohammad     S     Anwar
       <mohammad.anwar@yahoo.com>

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

perl v5.36.0                                       2022-11-19                                     Pod::Tree(3pm)

       "Pod::Tree" parses a POD into a static syntax tree.  Applications walk the tree to recover the structure
       and content of the POD.  See "Pod::Tree::Node" for a description of the tree.

       "load_file"($file)
           Returns null iff it can't open $file.

       Nothing

$tree = "Pod::Tree"->"new"
           Creates a new "Pod::Tree" object.  The syntax tree is initially empty.

       $ok = $tree->"load_file"($file, %options)
           Parses  a  POD  and  creates  a  syntax tree for it.  $file is the name of a file containing the POD.
           Returns null iff it can't open $file.

           See "OPTIONS" for a description of %options$tree->"load_fh"($fh, %options)
           Parses a POD and creates a syntax tree for it.  $fh is an "IO::File" object that is open  on  a  file
           containing the POD.

           See "OPTIONS" for a description of %options$tree->"load_string"($pod, %options)
           Parses a POD and creates a syntax tree for it.  $pod is a single string containing the POD.

           See "OPTIONS" for a description of %options$tree->"load_paragraphs"(\@pod, %options)
           Parses  a  POD  and creates a syntax tree for it.  \@pod is a reference to an array of strings.  Each
           string is one paragraph of the POD.

           See "OPTIONS" for a description of %options$loaded = $tree->"loaded"
           Returns true iff one of the "load_"* methods has been called on $tree.

       $node = $tree->"get_root"
           Returns the root node of the syntax tree.  See Pod::Tree::Node for a description of the syntax tree.

       $tree->"set_root"($node)
           Sets the root of the syntax tree to $node.

       $tree->"push"(@nodes)
           Pushes @nodes onto the end of the top-level list of nodes in $tree.

       $node = $tree->"pop"
           Pops $node off of the end of the top-level list of nodes in $tree.

       $tree->"walk"(\&sub)
           Walks the syntax tree, depth first.  Calls sub once for each node in the tree.  The current  node  is
           passed as the first argument to sub.

           "walk" descends to the children and siblings of $node iff sub() returns true.

       $tree->"has_pod"
           Returns true iff $tree contains POD paragraphs.

       $tree->"dump"
           Pretty prints the syntax tree.  This will show you how "Pod::Tree" interpreted your POD.

       Pod::Tree - Create a static syntax tree for a POD

Noround-tripping
       Currently, "Pod::Tree" does not provide a complete, exact representation of its input.  For  example,  it
       doesn't distingish between

           C<$foo-E<gt>bar>

       and

          C<< $foo->bar >>

       As  a  result,  it  is  not  guaranteed  that  a  file  can be exactly reconstructed from its "Pod::Tree"
       representation.

   L<>markups
       In the documentation of the

           L<"sec">    section in this manual page

       markup, "perlpod" has always claimed

               (the quotes are optional)

       However, there is no way to decide from the syntax alone whether

           L<foo>

       is a link to the foo man page or a link to the "foo" section of this man page.

       "Pod::Tree" parses "L<foo>" as a link to a section if "foo" looks like  a  section  name  (e.g.  contains
       whitespace), and as a link to a man page otherswise.

       In  practice,  this  tends  to break links to sections.  If you want your section links to work reliably,
       write them as "L<"foo">" or "L</foo>".

       These options may be passed in the %options hash to the "load_"* methods.

       "in_pod => 0"
       "in_pod => 1"
           Sets  the  initial  value of "in_pod".  When "in_pod" is false, the parser ignores all text until the
           next =command paragraph.

           The initial value of "in_pod" defaults to false for "load_file()" and "load_fh()" calls and true  for
           "load_string()"  and  "load_paragraphs()"  calls.   This  is  usually  what you want, unless you want
           consistency.  If this isn't what you want, pass different initial values in the %options hash.

       "limit" => n
           Only parse the first n paragraphs in the POD.

perl(1), "Pod::Tree::Node", "Pod::Tree::HTML"

         use Pod::Tree;

         $tree = Pod::Tree->new;
         $tree->load_file      ( $file, %options)
         $tree->load_fh        ( $fh  , %options);
         $tree->load_string    ( $pod , %options);
         $tree->load_paragraphs(\@pod , %options);

         $loaded = $tree->loaded;

         $node   = $tree->get_root;
                   $tree->set_root  ($node);
         $node =   $tree->pop;
                   $tree->push(@nodes);

                   $tree->walk(\&sub);
                   $tree->has_pod and ...
         print     $tree->dump;