SEARCH
NEW RPMS
DIRECTORIES
ABOUT
FAQ
VARIOUS
BLOG
DONATE


YUM REPOSITORY

 
 

Pod::Loom

Section: User Contributed Perl Documentation (3)
Updated: 2010-03-07
Index 

NAME

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

VERSION

This document describes version 0.03 ofPod::Loom, released March 6, 2010as part of Pod-Loom version 0.03. 

WARNING

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. 

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

METHODS

 

new

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

weave

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

DIAGNOSTICS

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. 

DEPENDENCIES

Pod::Loom depends on Moose, Pod::Eventual, PPI, andString::RewritePrefix, which can be found on CPAN. The templateclass 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<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 WARRANTY

BECAUSE 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 ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHEREXPRESSED OR IMPLIED, INCLUDING, 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, REPAIR, 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.


 

Index

NAME
VERSION
WARNING
SYNOPSIS
DESCRIPTION
METHODS
new
weave
REQUIREMENTS OF A TEMPLATE CLASS
DIAGNOSTICS
CONFIGURATION AND ENVIRONMENT
DEPENDENCIES
INCOMPATIBILITIES
BUGS AND LIMITATIONS
AUTHOR
COPYRIGHT AND LICENSE
DISCLAIMER OF WARRANTY

This document was created byman2html,using the manual pages.