Section: User Contributed Perl Documentation (3)
Pod::Loom - Weave pseudo-POD into real POD
This document describes version 0.03 ofPod::Loom, released March 6, 2010as part of Pod-Loom version 0.03.
This code is still in flux. Use it at your own risk, and be preparedto adapt to changes. The POD
syntax should be fairly stable, but ifyou write your own templates, they might need to change.
use Pod::Loom; my $document = ...; # Text of Perl program including POD my $filename = "filename/of/document.pm"; # For messages my %data = ...; # Configuration required by template my $loom = Pod::Loom->new(template => 'Custom'); my $new_doc = $loom->weave(\$document, $filename, \%data);
Pod::Loom extracts all the POD
sections from Perl code, passes the POD
to a template that may reformat it in various ways, and then returns acopy of the code with the reformatted POD
at the end.
A template may convert non-standard POD commands like "=method" and"=attr" into standard POD, reorder sections, and generally dowhatever it likes to the POD.
The document being reformatted can specify the template to use with aline like this:
=for Pod::Loom-template TEMPLATE_NAME
Otherwise, you can specify the template in the Pod::Loom constructor:
$loom = Pod::Loom->new(template => TEMPLATE_NAME);
TEMPLATE_NAME is automatically prefixed with "Pod::Loom::Template::"to form a class name. If you want to use a template outside thatnamespace, prefix the class name with "=" to indicate that.
$loom = Pod::Loom->new(template => TEMPLATE_NAME);
Constructs a new Pod::Loom. The "template" parameter is optional; itdefaults to "Default" (meaning Pod::Loom::Template::Default).
$new_doc = $loom->weave(\$doc, $filename, $data);
This method does all the work (see ``DESCRIPTION''). You pass it areference to a string containing Perl code mixed with POD. (Thisstring is not modified.) It returns a new string containing thereformatted POD moved to the end of the code.
The $filename is used for error messages. It does not need toactually exist on disk.
$data is passed as the only argument to the template class'sconstructor (which must be named "new"). Pod::Loom does not inspectit, but for consistency and compatibility between templates it shouldbe a hashref.
REQUIREMENTS OF A TEMPLATE CLASS
A template class must have a constructor named "new"
and a methodnamed "weave"
that matches the one in Pod::Loom::Template. Itshould be in the "Pod::Loom::Template::"
namespace (to make it easyto specify the template name), but it does not need to be a subclassof Pod::Loom::Template.
Pod::Loom may generate the following error messages, in addition towhatever errors the template class generates.
- Can't use Pod::Loom on %s: there is POD inside string literals
- You have POD commands inside a string literal (probably a here doc).Since Pod::Loom moves all POD to the end of the file, running it onyour program would change its behavior. Move the POD outside thestring, or quote any equals sign at the beginning of a line so it nolonger looks like POD.
- Invalid class name %s
- A template name may only contain ASCII alphanumerics and underscore.
- Unable to load %s: %s
- Pod::Loom got an error when it tried to "require" your template class.
CONFIGURATION AND ENVIRONMENT
Pod::Loom requires no configuration files or environment variables.
Pod::Loom depends on Moose, Pod::Eventual, PPI
, andString::RewritePrefix, which can be found on CPAN
. The templateclass may have additional dependencies.
BUGS AND LIMITATIONS
No bugs have been reported.
Christopher J. Madsen "<perl AT cjmweb.net>"
Please report any bugs or feature requests to"<bug-Pod-Loom AT rt.cpan.org>",or through the web interface at<http://rt.cpan.org/Public/Bug/Report.html?Queue=Pod-Loom>
You can follow or contribute to Pod-Loom's development at<http://github.com/madsen/pod-loom>.
COPYRIGHT AND LICENSE
This software is copyright (c) 2010 by Christopher J. Madsen.
This is free software; you can redistribute it and/or modify it underthe same terms as the Perl 5 programming language system itself.
DISCLAIMER OF WARRANTYBECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE
, THERE IS NO WARRANTYFOR THE SOFTWARE
, TO THE EXTENT PERMITTED BY APPLICABLE LAW
. EXCEPT WHENOTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIESPROVIDE THE SOFTWARE
'' WITHOUT WARRANTY OF ANY KIND
, EITHEREXPRESSED OR IMPLIED
, BUT NOT LIMITED TO
, THE IMPLIEDWARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE
. THEENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITHYOU
. SHOULD THE SOFTWARE PROVE DEFECTIVE
, YOU ASSUME THE COST OF ALLNECESSARY SERVICING
, OR CORRECTION
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITINGWILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/ORREDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENSE, BELIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL,OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USETHE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEINGRENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR AFAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IFSUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OFSUCH DAMAGES.
- REQUIREMENTS OF A TEMPLATE CLASS
- CONFIGURATION AND ENVIRONMENT
- BUGS AND LIMITATIONS
- COPYRIGHT AND LICENSE
- DISCLAIMER OF WARRANTY
This document was created byman2html,using the manual pages.