---
name: "Pod::Tree"
section: "3pm"
platform: "linux"
package: "libpod-tree-perl"
version: "1.31-2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Pod::Tree"
---

# Pod::Tree(3pm)

Create a static syntax tree for a POD

## 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)](/perl/1.md), `"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\> Currently maintained by Mohammad S Anwar \<mohammad.anwar@yahoo.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.