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 (or POD compatible) 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.

   WHY?
       If you've ever asked yourself "What does Pod do for me?", this module is intended to
       answer that question.

       While Pod looks like a simple format, the specification calls for a number of special
       cases to be handled, and that makes any software that works on Pod as text more complex
       than it needs to be.

       In addition to this, Pod does not lend itself to a natural structured model. This makes it
       difficult to manipulate without damaging the validity of the document.

       Pod::Abstract solves these problems by loading the document into a structured tree, and
       providing consistent traversal, searching, manpulation and re-serialisation. Pod related
       utilities are easy to write using Pod::Abstract.

       The design goal of Pod::Abstract is to do the hard work for the programmer - the library
       should work for you, and as such it should be significantly easier than string mashing
       what you want out of a Pod document.

   PROCESSING MODEL
       The intent with POD::Abstract is to provide a means to decorate a parse tree, rather than
       manipulate text, to allow other software to add features and functionality to POD based
       documenation systems.

       If you wish to write modules that interact nicely with other POD::Abstract modules, then
       you should provide a POD::Abstract -> POD::Abstract translation. Leave any document
       element that your program is not interested in directly untouched in the parse tree, and
       if you have data that could be useful to other packages, decorate the parse tree with that
       data even if you don't see any direct way to use it in the output.

       In this way, when you want one more feature for POD, 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. Simply 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 simply performed on the document tree. If your formatter does
       not use Pod::Abstract, you can simply pipe out POD and use a regular formatter. If your
       formatter supports Pod::Abstract though, then you can feed in the syntax tree directly
       without having to re-serialise and parse the document.

       In addition to this, because 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 aims to support all POD rules defined in perlpodspec (even the ones I don't
       like), except for those directly related to formatting output, or which cannot be
       implemented generically.

COMPONENTS

       Pod::Abstract is comprised of:

       •   The parser, which loads a document tree for you.

           You should access this through "Pod::Abstract", not directly

       •   The document tree, which is the root node you are given by the parser. Calling pod on
           the root node should always give you back your original document.

           See Pod::Abstract::Node

       •   Pod::Abstract::Path, the node selection expression language. This is generally called
           by doing "$node->select(PATH_EXP)". Pod::Abstract::Path is the most complex and
           powerful component of this module, and if you're not using it you should be. ;)

           This allows you to ask questions like:

           "In the first head1 that starts with "A", find me the head2 matching 'foo' with bold
           text somewhere in the preceding paragraph or heading"

            /head1[@heading=~{^A}](0)/head2[@heading=~{foo}i]<<head2 :paragraph[//:B]

           You probably don't need anything that complex, but it's there if you do.

       •   The node builder, Pod::Abstract::BuildNode

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 <bnej@mac.com>

COPYRIGHT AND LICENSE

       Copyright (C) 2009 Ben Lilburne

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