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);
$tree->has_pod and ...
print $tree->dump;
REQUIRES¶
Pod::Escapes
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 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.
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¶
No round-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>".
SEE ALSO¶
perl(1), "Pod::Tree::Node", "Pod::Tree::HTML"
ACKNOWLEDGMENTS¶
- •
- <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>
AUTHOR¶
Steven McDougall <swmcd@world.std.com>
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.