SYNOPSIS

  use Pod::Tree;

  $tree = new Pod::Tree;
  $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;

REQUIRES

Pod::Escapes

EXPORTS

Nothing

DESCRIPTION

\*(C`Pod::Tree\*(C' parses a \s-1POD\s0 into a static syntax tree. Applications walk the tree to recover the structure and content of the \s-1POD\s0. See \*(C`Pod::Tree::Node\*(C' for a description of the tree.

METHODS

Creates a new \*(C`Pod::Tree\*(C' object. The syntax tree is initially empty. Parses a \s-1POD\s0 and creates a syntax tree for it. $file is the name of a file containing the \s-1POD\s0. Returns null iff it can't open $file. See \*(L"\s-1OPTIONS\s0\*(R" for a description of %options Parses a \s-1POD\s0 and creates a syntax tree for it. $fh is an \*(C`IO::File\*(C' object that is open on a file containing the \s-1POD\s0. See \*(L"\s-1OPTIONS\s0\*(R" for a description of %options Parses a \s-1POD\s0 and creates a syntax tree for it. $pod is a single string containing the \s-1POD\s0. See \*(L"\s-1OPTIONS\s0\*(R" for a description of %options Parses a \s-1POD\s0 and creates a syntax tree for it. \@pod is a reference to an array of strings. Each string is one paragraph of the \s-1POD\s0. See \*(L"\s-1OPTIONS\s0\*(R" for a description of %options Returns true iff one of the \*(C`load_\*(C'* methods has been called on $tree. Returns the root node of the syntax tree. See Pod::Tree::Node for a description of the syntax tree. Sets the root of the syntax tree to $node. Pushes @nodes onto the end of the top-level list of nodes in $tree. Pops $node off of the end of the top-level list of nodes in $tree. 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. \*(C`walk\*(C' descends to the children and siblings of $node iff sub() returns true. Returns true iff $tree contains \s-1POD\s0 paragraphs. Pretty prints the syntax tree. This will show you how \*(C`Pod::Tree\*(C' interpreted your \s-1POD\s0.

OPTIONS

These options may be passed in the %options hash to the \*(C`load_\*(C'* methods. Sets the initial value of \*(C`in_pod\*(C'. When \*(C`in_pod\*(C' is false, the parser ignores all text until the next =command paragraph. The initial value of \*(C`in_pod\*(C' defaults to false for \*(C`load_file()\*(C' and \*(C`load_fh()\*(C' calls and true for \*(C`load_string()\*(C' and \*(C`load_paragraphs()\*(C' 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. Only parse the first n paragraphs in the \s-1POD\s0.

DIAGNOSTICS

Returns null iff it can't open $file.

NOTES

No round-tripping

Currently, \*(C`Pod::Tree\*(C' 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 \*(C`Pod::Tree\*(C' representation.

L<> markups

In the documentation of the

L<"sec"> section in this manual page

markup, \*(C`perlpod\*(C' 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 \*(C`foo\*(C' section of this man page.

\*(C`Pod::Tree\*(C' parses \*(C`L<foo>\*(C' as a link to a section if \*(C`foo\*(C' 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 \*(C`L<"foo">\*(C' or \*(C`L</foo>\*(C'.

RELATED TO Pod::Tree…

perl\|(1), \*(C`Pod::Tree::Node\*(C', \*(C`Pod::Tree::HTML\*(C'

ACKNOWLEDGMENTS

AUTHOR

Steven McDougall <[email protected]>

COPYRIGHT

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.