NAME

Pod::Loom::Template - Standard base class for Pod::Loom templates

VERSION

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

DESCRIPTION

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.

Controlling the template

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.

Pod::Loom-insert_after

Pod::Loom-insert_before

Insert (or move) one or more sections into the specified position. See "expect_sections".

Pod::Loom-omit

Omit the specified sections from the document. See "expect_sections".

Pod::Loom-sections

Specify the complete list of sections for the document. See "expect_sections".

Pod::Loom-sort_COMMAND

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

  =for Pod::Loom-sort_method

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

or

  =for Pod::Loom-sort_method
  C<< $object = Class->new() >>

  =method C<< $object = Class->new() >>

Pod::Loom-group_COMMAND

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:

  =attr-fmt font

says that the font attribute is in the fmt category. You must have a Pod::Loom-group_COMMAND block 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 =end after the =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.)

Pod::Loom-template

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

ATTRIBUTES

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.

sections

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.

tmp_collected

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.

tmp_filename

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

tmp_groups

This is a hashref of hashrefs. The keys are the POD commands returned by "collect_commands", Each value is an hashref of group codes. It is filled in by the "parse_pod" method.

METHODS

collect_commands

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

collect_sections

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

error

  $tmp->error($message);

This method calls Perl's die builtin with the $message after prepending the filename to it.

expect_sections

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

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.

generate_pod

  $pod = $tmp->generate_pod($section_list, $section_text)

This method is passed a list of section titles (from "expect_sections") and a hash containing the original text of each section (from "collect_sections". It then considers each section in order:

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

2. It calls $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.

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

join_entries

  $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 =over and =back if $newcmd is item.

joined_section

  $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 head2 or item). $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 $newcmd is item, then =over and =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., head2 becomes head3).

method_for_section

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

The special * section is associated with the method other_sections.

override_section

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

  $tmp->parse_pod(\$pod);

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 tmp_collected attribute.

post_parse

  $tmp->post_parse()

This method is called after parse_pod. The default implementation sorts the collected POD chunks if requested to by the document or the sort_ attributes.

required_attr

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

warning

  $tmp->warning($message);

This method calls Perl's warn builtin with the $message. If this is the first warning, it first prints a warning with the filename.

weave

  $new_pod = $tmp->weave(\$old_pod, $filename);

This is the primary entry point, normally called by Pod::Loom's weave method.

First, it stores the filename in the tmp_filename attribute.

It then calls:

1. "parse_pod" to parse the POD.

2. "post_parse" to do additional processing.

3. "expect_sections" to get the list of section titles.

4. "collect_sections" to get the text of each section from the original document.

5. "generate_pod" to produce the new document.

DIAGNOSTICS

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 * category.

CONFIGURATION AND ENVIRONMENT

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

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

cpanm Pod::Loom

perl -MCPAN -e shell
install Pod::Loom