/ 
Pod-Abstract-0.26
River stage two • 5 direct dependents • 14 total dependents
/ Pod::Abstract

NAME

Pod::Abstract - Abstract document tree for Perl POD documents

SYNOPSIS

use Pod::Abstract;
use Pod::Abstract::BuildNode qw(node);

# Get all the first level headings, and put them in a verbatim block
# at the start of the document
my $pa = Pod::Abstract->load_filehandle(\*STDIN);
my @headings = $pa->select('/head1@heading');
my @headings_text = map { $_->pod } @headings;
my $headings_node = node->verbatim(join "\n",@headings_text);

$pa->unshift( node->cut );
$pa->unshift( $headings_node );
$pa->unshift( node->pod );

print $pa->pod;

DESCRIPTION

Pod::Abstract provides a means to load a POD document without direct reference to it's syntax, and perform manipulations on the abstract syntax tree.

This can be used to support additional features for POD, to format output, to compile into alternative formats, etc.

POD documents are not a natural tree, but do have a logical nesting structure. Pod::Abstract makes this explicit - =head* commands create nested sections, =over and =back create nested lists, etc.

The "paf summary" command provides easy visualisation of the created tree.

USAGE

Pod::Abstract allows easy manupulation and traversal of POD or Perl files containing POD, without having to manually do any string manipulation.

It allows you to easily write formatters, filters, test scripts, etc for POD.

Pod::Abstract is based on the standard Pod::Parser module.

PROCESSING MODEL

Pod::Abstract allows documents to be loaded, decorated, and manupulated in multiple steps. It can also make generating a POD formatter very simple. You can easily add features to an existing POD formatter, since any POD abstract object can be written out as a POD document.

Rather than write or fork a whole translator, a single inline "decorator" can be added.

The paf utility provides a good starting point, which also allows you to hook in to an existing filter/transform library. Add a Pod::Abstract::Filter class to the namespace and it should start working as a paf command.

EXAMPLE

Suppose you are frustrated by the verbose list syntax used by regular POD. You might reasonably want to define a simplified list format for your own use, except POD formatters won't support it.

With Pod::Abstract you can write an inline filter to convert:

* item 1
* item 2
* item 3

into:

=over

=item *

item 1

=item *

item 2

=item *

item 3

=back

This transformation can be performed on the document tree. If your formatter does not use Pod::Abstract, you can pipe out POD and use a regular formatter. If your formatter supports Pod::Abstract, you can feed in the syntax tree without having to re-serialise and parse the document.

The source document is still valid Pod, you aren't breaking compatibility with regular perldoc just by making Pod::Abstract transformations.

POD SUPPORT

Pod::Abstract supports all POD rules defined in perlpodspec.

COMPONENTS

Pod::Abstract is comprised of:

  • The parser, which loads a document tree.

    e.g:

    my $pa = Pod::Abstract->load_filehandle(\*STDIN);

  • The document tree, returned from the parser. The root node ($pa above) represents the whole document. Calling ->pod on the root node will give you back your original document.

    Note the document includes #cut nodes, which are generally the Perl code - the parts that aren't POD. These will be included in the output of ->pod unless you remove them, so you can modify a Perl module as a POD document in POD abstract, and it will work the same afterwards.

    e.g

    my $pod_text = $pa->pod; # $pod_text is reserialized from the tree.

    See Pod::Abstract::Node

  • Pod::Abstract::Path, a node selection language. Called via $node->select(PATH_EXP). Pod paths are a powerful feature allowing declarative traversal of a document.

    For example -

    "Find all head2s under METHODS"

    /head1[@heading=~{^METHODS$}]/head2

    "Find all bold text anywhere"

    //B

  • The node builder, Pod::Abstract::BuildNode. This exports methods to allow adding content to POD documents.

    You can also combine documents -

    use Pod::Abstract::BuildNode qw(node nodes);
# ...
my @nodes = nodes->from_pod($pod);

    Where $pod is a text with POD formatting.

Using paths

The easiest way to traverse a $pa tree is to use the select method on the nodes, and paths.

select will accept and expression and return an array of Pod::Abstract::Node. These nodes also support the select method - for example:

my @headings = $pa->select('/head1'); # Get all heading 1
my @X = $headings[0]->select('//:X'); # Get all X (index) sequences inside that heading
my @indices = map { $_->text } @X; # Map out the contents of those as plain text.

You can combine path expressions with other methods, for example - children will give all the child nodes of a POD node, next, previous, parent and root allow traversal from a given node.

From any node you can then call select to make a declarative traversal from there. The above methods also have comparable expressions in Pod::Abstract::Path.

Traversing for document generation

To traverse the tree for document generation, you can follow children from the first node, then examine each node type to determine what you should generate.

The nodes will generate in a tree, so headings have nested children with subheadings and texts. In most cases the body method will give the text (or POD nodes) next to the command, while the children method will give the contained POD.

Special types are :paragraph, :text, <#cut>. Interior sequences are also started with a : for their type, like :L, :B, :I for Link, Bold, Italic.

Use the $node->ptree method to see a visualised tree of a parsed document.

METHODS

load_file

my $pa = Pod::Abstract->load_file( FILENAME );

Read the POD document in the named file. Returns the root node of the document.

load_filehandle

my $pa = Pod::Abstract->load_file( FH );

Load a POD document from the provided filehandle reference. Returns the root node of the document.

load_string

my $pa = Pod::Abstract->load_string( STRING );

Loads a POD document from a scalar string value. Returns the root node of the document.

AUTHOR

Ben Lilburne <bnej80@gmail.com>

COPYRIGHT AND LICENSE

Copyright (C) 2009-2025 Ben Lilburne

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.