Pod::Loom - Weave pseudo-POD into real POD
This document describes version 0.08 of Pod::Loom, released March 23, 2014 as part of Pod-Loom version 0.08.
This code is still in flux. Use it at your own risk, and be prepared to adapt to changes. The POD syntax should be fairly stable, but if you 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 a copy of the code with the reformatted POD at the end.
A template may convert non-standard POD commands like
=attr into standard POD, reorder sections, and generally do whatever it likes to the POD.
The document being reformatted can specify the template to use with a line 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 that namespace, 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; it defaults 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 a reference to a string containing Perl code mixed with POD. (This string is not modified.) It returns a new string containing the reformatted POD moved to the end of the code.
$doc should contain raw bytes (i.e. UTF8 flag off). If
$doc is encoded in something other than Latin-1, it must contain an
=encoding directive specifying the encoding.
$new_doc will likewise contain raw bytes in the same encoding as
$filename is used for error messages. It does not need to actually exist on disk.
$data is passed as the only argument to the template class's constructor (which must be named
new). Pod::Loom does not inspect it, but for consistency and compatibility between templates it should be a hashref.
A template class must have a constructor named
new and a method named
weave that matches the one in Pod::Loom::Template. It should be in the
Pod::Loom::Template:: namespace (to make it easy to specify the template name), but it does not need to be a subclass of Pod::Loom::Template.
Pod::Loom may generate the following error messages, in addition to whatever 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 on your program would change its behavior. Move the POD outside the string, or quote any equals sign at the beginning of a line so it no longer 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.
Pod::Loom requires no configuration files or environment variables.
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 https://github.com/madsen/pod-loom.
This software is copyright (c) 2014 by Christopher J. Madsen.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENSE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.