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

FreeBSD Manual Pages


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

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

	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;

       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.

       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

       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.

       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



	=item *

	item 1

	=item *

	item 2

	=item *

	item 3


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

       Pod::Abstract is	comprised of:

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

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

       o   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

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

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

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

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

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

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

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

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

       Ben Lilburne <>

       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.

perl v5.32.1			  2010-01-03		      Pod::Abstract(3)


Want to link to this manual page? Use this URL:

home | help