NAME

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

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);
  print     $tree->dump;

REQUIRES

Perl 5.004, Exporter, IO::File, Pod::Tree::Node

EXPORTS

Nothing

DESCRIPTION

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.

METHODS

$tree = new Pod::Tree

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 to 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->dump

Pretty prints the syntax tree. This will show you how Pod::Tree interpreted your POD.

OPTIONS

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.

DIAGNOSTICS

load_file($file)

Returns null iff it can't open $file.

NOTES

Blank lines

PODs are defined in terms of paragraphs, and paragraphs are defined as text delimited by two or more consecutive newlines.

load_file() and load_fh() parse paragraphs by setting $/ to '' and calling getline(). This reads paragraphs as desired; however, the strings returned by getline() always have two newlines at the end, no matter now many actually appear in the input. I reported this as a bug against Perl, but was told that it is a feature.

To fix this, I would have to abandon $/ and count newlines in Pod::Tree. From a coding standpoint, this isn't difficult, but I hate to do it: $/ ought to be good for something.

Instead, load_file() and load_fh() go ahead and chomp the line endings. pod2* translators can add back "\n\n" if they like, but there is no way to recover the actual number of newlines in the input. For consistency, load_string() splits on m(\n{2,}) and discards the delimiters. In contrast, load_paragraphs() doesn't mung newlines. By definition, text passed to load_paragraphs() has already been divided into paragraphs, so any trailing newlines are taken to be part of the paragraph in which they appear.

None of this should be an issue for ordinary POD paragraphs. However, it could be a problem for =begin/=end blocks, if they pass text to a formatter for which blank lines are significant.

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>.

SEE ALSO

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

AUTHOR

Steven McDougall, swmcd@world.std.com

COPYRIGHT

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

cpanm Pod::Tree

perl -MCPAN -e shell
install Pod::Tree