Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Pod::Tree(3)	      User Contributed Perl Documentation	  Pod::Tree(3)

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

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

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

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
       o   <crazyinsomniac@yahoo.com>

       o   <joenio@cpan.org>

       o   Paul	Bettinger <paul@n8geil.de>

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

       o   Brad	Choate <brad@bradchoate.com>

       o   Havard Eidnes <he@NetBSD.org>

       o   Rudi	Farkas <rudif@bluemail.ch>

       o   Paul	Gibeault <pagibeault@micron.com>

       o   Jay Hannah <jhannah@omnihotels.com>

       o   Paul	Hawkins	<phawkins@datajunction.com>

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

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

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

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

       o   Johan Lindstrom <johanl@bahnhof.se>

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

       o   Rob Napier <rnapier@employees.org>

       o   Kate	L Pugh <kake@earth.li>

       o   Christopher Shalah <trance@drizzle.com>

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

perl v5.24.1			  2015-05-25			  Pod::Tree(3)

NAME | SYNOPSIS | EXPORTS | DESCRIPTION | METHODS | OPTIONS | DIAGNOSTICS | NOTES | SEE ALSO | ACKNOWLEDGMENTS | AUTHOR | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Pod::Tree&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help