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

$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_* functions 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->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. in_pod controls whether the parser is cutting: the parser is cutting iff in_pod is false. When the parser is cutting, it 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.

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.

SEE ALSO

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

AUTHOR

Steven McDougall, swmcd@world.std.com

COPYRIGHT

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