- CONFIGURATION AND ENVIRONMENT
- BUGS AND LIMITATIONS
- COPYRIGHT AND LICENSE
- DISCLAIMER OF WARRANTY
Pod::Loom::Template - Standard base class for Pod::Loom templates
This document describes version 0.07 of Pod::Loom::Template, released March 23, 2014 as part of Pod-Loom version 0.08.
Pod::Loom::Template is intended as the standard base class for Pod::Loom templates. It provides the engine that splits apart the POD and reassembles it. The subclass needs to specify how the POD is reassembled. See the "weave" method for details.
A POD document can contain special commands for the template. These commands should work with all templates based on Pod::Loom::Template. They are placed in a
=for command, and must not come in the middle of a section.
Insert (or move) one or more sections into the specified position. See "expect_sections".
Omit the specified sections from the document. See "expect_sections".
Specify the complete list of sections for the document. See "expect_sections".
If a template allows pseudo-POD commands like
=method, you can have the resulting entries sorted alphabetically. For example, to have your methods sorted, use
You can also supply a list of entries (one per line) that should come first. The list must match the corresponding entry exactly. For example:
=for Pod::Loom-sort_method new =method new
=for Pod::Loom-sort_method C<< $object = Class->new() >> =method C<< $object = Class->new() >>
If you have a lot of attributes or methods, you might want to group them into categories. You do this by appending the category (which is an arbitrary string without whitespace) to the command. For example:
says that the font attribute is in the
fmtcategory. You must have a
Pod::Loom-group_COMMANDblock for each category you use. The block begins with the category name on a line by itself. The rest of the block (which may be blank) is POD that will appear before the associated entries.
=begin Pod::Loom-group_attr fmt =head2 Formatting Attributes These attributes control formatting.
Note: Because Pod::Eventual is not a full-fledged POD parser, you do not actually need a matching
=begin, but it won't hurt if you use one. If you don't, the block ends at the next POD command in "collect_commands".
Entries that do not contain a category are placed in the special category
The categories will be listed in the order that the Pod::Loom-group_COMMAND blocks appear in the document. The order of entries within each category is controlled as usual. See "Pod::Loom-sort_COMMAND". (Just ignore the category when defining the sort order.)
Specify the template for the document. (This is actually handled by Pod::Loom, and applies to all templates, whether or not they subclass Pod::Loom::Template.)
All attributes beginning with
tmp_ are reserved and must not be defined by subclasses. In addition, attributes beginning with
sort_ are reserved for indicating whether collected entries should be sorted.
Subclasses must provide a builder for this attribute named
_build_sections. It is an arrayref of section titles in the order they should appear. The special title
* indicates where sections that appear in the document but are not in this list will be placed. (If
* is not in this list, such sections will be dropped.)
The list can include sections that the template does not provide. In that case, it simply indicates where the section should be placed if the document provides it.
This is a hashref of arrayrefs. The keys are the POD commands returned by "collect_commands", plus any format names that begin with
Pod::Loom. Each value is an arrayref of POD blocks. It is filled in by the "parse_pod" method.
This is the name of the file being processed. This is only for informational purposes; it need not represent an actual file on disk. (The "weave" method stores the filename here.)
$arrayRef = $tmp->collect_commands;
This method should be overriden in subclasses to indicate what POD commands should be collected for the template to stitch together. This should include
head1, or the template is unlikely to work properly. The default method indicates only
head1 is collected.
$section_text = $tmp->collect_sections($section_list)
This method collects the text of each section in the original document based on the $section_list (which comes from "expect_sections"). It returns a hashref keyed on section title.
Any sections that appeared in the original document but are not in
$section_list are concatenated to form the
This method calls Perl's
die builtin with the
$message after prepending the filename to it.
$section_titles = $tmp->expect_sections;
This method returns an arrayref containing the section titles in the order they should appear. By default, this is the list from "sections", but it can be overriden by the document:
If the document contains
=for Pod::Loom-sections, the sections listed there (one per line) replace the template's normal section list.
If the document contains
=for Pod::Loom-omit, the sections listed there will not appear in the final document. (Unless they appeared in the document, in which case they will be with the other
If the document contains
=for Pod::Loom-insert_before, the sections listed there will be inserted before the last section in the list (which must already be in the section list). If the sections were already in the section list, they are moved to the new location.
If the document contains
=for Pod::Loom-insert_after, the sections listed there will be inserted after the first section in the list. For example,
=for Pod::Loom-insert_after DESCRIPTION NOTES
will cause the NOTES section to appear immediately after the DESCRIPTION.
$pod = $tmp->generate_pod($section_list, $section_text)
If the section appeared in the original document, it calls
$tmp->override_section($title). If that returns false, it copies the section from the original document to the new document and proceeds to the next section. Otherwise, it continues to step 2.
$tmp->method_for_section($title)to get the method that will handle that section. If that returns no method, it proceeds to the next section.
It calls the method from step 2, passing it two parameters: the section title and the text of the section from the original document (or undef). Whatever text the method returns is appended to the new document. (The method may return the empty string, but should not return undef).
$podText = $tmp->join_entries($newcmd, \@entries);
This method is used by "joined_section", but may be useful to subclasses also. Each element of
@entries must begin with a POD command, which will be changed to
$newcmd. It returns the entries joined together, surrounded by
$podText = $tmp->joined_section($oldcmd, $newcmd, $title, $pod);
This method may be useful to subclasses that want to build sections out of collected commands.
$oldcmd must be one of the entries from "collect_commands".
$newcmd is the POD command that should be used for each entry (like
$title is the section title, and
$pod is the text of that section from the original document (if any).
Each collected entry is appended to the original section. If there was no original section, a simple
=head1 $title command is added. If
=back are added automatically.
If the document divided this section into groups (see "Pod::Loom-group_COMMAND"), that is handled automatically by this method. If
$newcmd is a
headN, and any of the category headers contains a
=headN command, then
$newcmd is automatically incremented. (E.g.,
$methodRef = $tmp->method_for_section($section_title);
This associates a section title with the template method that implements it. By default, it prepends
section_ to the title, and then converts any non-alphanumeric characters to underscores.
* section is associated with the method
$boolean = $tmp->override_section($section_title);
Normally, if a section appears in the document, it remains unchanged by the template. However, a template may want to rewrite certain sections.
override_section is called when the specified section is present in the document. If it returns true, then the normal
section_TITLE method will be called. (If it returns true but the
section_TITLE method doesn't exist, the section will be dropped.)
Parse the document, which is passed by reference. The default implementation splits up the POD using Pod::Loom::Parser, breaking it up according to "collect_commands". The resulting chunks are stored in the
This method is called after
parse_pod. The default implementation sorts the collected POD chunks if requested to by the document or the
@values = $tmp->required_attr($section_title, @attribute_names);
Returns the value of each attribute specified in
@attribute_names. If any attribute is
undef, dies with a message that
$section_title requires that attribute.
This method calls Perl's
warn builtin with the
$message. If this is the first warning, it first prints a warning with the filename.
$new_pod = $tmp->weave(\$old_pod, $filename);
This is the primary entry point, normally called by Pod::Loom's
First, it stores the filename in the
It then calls:
"parse_pod" to parse the POD.
"post_parse" to do additional processing.
"expect_sections" to get the list of section titles.
"collect_sections" to get the text of each section from the original document.
"generate_pod" to produce the new document.
The following errors are classified like Perl's built-in diagnostics (perldiag):
(S) A severe warning (F) A fatal error (trappable)
%s was grouped, but no Pod::Loom-group_%s found in %s
(F) You used categories with a command (like
=method-cat), but didn't have any Pod::Loom-group_COMMAND blocks. See "Pod::Loom-group_COMMAND".
Can't find heading in %s
(F) Pod::Loom couldn't determine the section title for the specified section. Is it formatted properly?
Can't insert before/after nonexistent section %s
(F) You can't insert sections near a section title that isn't already in the list of sections. Make sure you spelled it right.
Found Pod::Loom-group_%s in %s, but no groups were used
(S) You indicated that a command (like
=method) was going to be grouped, but didn't actually use any groups. See "Pod::Loom-group_COMMAND".
No category in Pod::Loom-group_%s
(F) A Pod::Loom-group_COMMAND block must begin with the category.
The %s section requires you to set `%s'
(F) The specified section of the template requires an attribute that you did not set.
You used =%s, but had no Pod::Loom-group_$cmd %s section
(F) You must have one Pod::Loom-group_COMMAND block for each category you use. Entries without a category are placed in the
Pod::Loom::Template 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.