view release on metacpan or  search on metacpan

lib/Dist/Man/Plugin/Template.pm  view on Meta::CPAN

package Dist::Man::Plugin::Template;
# vi:et:sw=4 ts=4

use warnings;
use strict;
use Carp qw( confess );

=head1 NAME

Dist::Man::Plugin::Template - dist manager with templates

=head1 VERSION

Version 0.0.6

=cut

our $VERSION = '0.0.8';

=head1 SYNOPSIS

 use Dist::Man qw(
   Dist::Man::Simple
   Dist::Man::Plugin::Template
 );

 Dist::Man->create_distro(%args);

=head1 DESCRIPTION

This plugin is designed to be added to a Dist::Man::Simple-compatible
Dist::Man class.  It adds stub methods for template retrieval and
rendering, and it replaces all of Simple's _guts methods with methods that will
retrieve and render the apropriate templates.

=head1 CLASS METHODS

=head2 C<< new(%args) >>

This plugin calls the C<new> supermethod and then initializes the template
store and renderer.  (See C<templates> and C<renderer> below.)

=cut

sub new {
    my $class = shift;
    my $self  = $class->SUPER::new(@_);
    $self->{templates} = { $self->templates };
    $self->{renderer} = $self->renderer;
    return bless $self => $class;
}

=head1 OBJECT METHODS

=head2 C<< templates() >>

This method is used to initialize the template store on the Dist::Man
object.  It returns a hash of templates; each key is a filename and each value
is the body of the template.  The filename F<Module.pm> is used for the module
template.

=cut

sub templates {
    confess 'attempted to use abstract base templates method';
}

=head2 C<< renderer() >>

This method is used to initialize the template renderer.  Its result is stored
in the object's C<renderer> entry.  The implementation will determine its use.

=cut

sub renderer {
    confess 'attempted to use abstract base renderer method';
}

=head2 C<< render($template, \%options) >>

The C<render> method will render the template passed to it, using the
data in the Dist::Man object and in the hash of passed parameters.

=cut

sub render {
    my $self = shift;
    my $template = shift;
    my $options = shift;

    confess 'attempted to use abstract base render method';
}

=head2 _guts methods

All of the C<FILE_guts> methods from Dist::Man::Simple are subclassed to
look something like this:

    sub file_guts {
        my $self = shift;
        my %options;
        @options{qw(first second third)} = @_;

        my $template = $self->{templates}{filename};
        $self->render($template, \%options);
    }

These methods will need to be rewritten when (as is likely)
Dist::Man::Simple's _guts methods are refactored into a registry.