/ 
Pod-Loom-0.08
River stage one • 1 direct dependent • 1 total dependent
/ Pod::Loom

NAME

Pod::Loom - Weave pseudo-POD into real POD

VERSION

This document describes version 0.08 of Pod::Loom, released March 23, 2014 as part of Pod-Loom version 0.08.

WARNING

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.

SYNOPSIS

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);

DESCRIPTION

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 =method and =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.

METHODS

new

$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).

weave

$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 $doc.

The $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.

REQUIREMENTS OF A TEMPLATE CLASS

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.

DIAGNOSTICS

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.

CONFIGURATION AND ENVIRONMENT

Pod::Loom requires no configuration files or environment variables.

DEPENDENCIES

Pod::Loom depends on Moose, Pod::Eventual, PPI, and String::RewritePrefix, which can be found on CPAN. The template class may have additional dependencies.

INCOMPATIBILITIES

None reported.

BUGS AND LIMITATIONS

No bugs have been reported.

AUTHOR

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.

COPYRIGHT AND LICENSE

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.

DISCLAIMER OF WARRANTY

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.