NAME

Contentment::Generator - Provides the contract and factory for generators

SYNOPSIS

  my $generator = Contentment::Generator->generator('Plain', {
      source     => sub {
          print "Hello World!\n";
      },
      kind       => 'text/plain',
      properties => {
          title       => 'Generic Generator',
          description => 'This is a very simple example.',
      },
  });

  $generator->generate( foo => 1, bar => 2 );

DESCRIPTION

At the center of each response is the generator. A generator is responsible for sending a response to the user and must implement a few methods. This class provides a generic way for constructing generators.

GENERATOR INTERFACE

This is the list of methods that a generator class must implement and the expected parameters, output, and return values.

my $generator->new(\%args)

Users should not call generator constructors directly. Rather, $generator objects should be constructed via the factory method, generator, provided by Contentment::Generator (this class).

The arguments can be anything appropriate to the generator class. However, here a few recommendations:

source

Many generators take some source text and use that as the basis for executing some code, finding properties, etc. The source should be accepted as a scalar. You may also wish to accept other forms like file handles.

properties

Many generators will take a list of properties to associate with the generator. If your generator creates properties from the source, it is recommended that the properties associated with this option be used as default values. Any properties found in the file should append to or override the properties stated here.

my $value = $generator->get_property($key)

This method must exist and returns whatever information is appropriate. For generators based on files, it might return information for keys naming values returned from the stat operator. This is anything you want.

This should, in general, include the following properties for each generator:

kind

This is the kind of data the generate() method will output.

title

This is the title of the document generated by this generator.

description

This is a short one line description of the document generated by this generator.

$result = $generator->generate(%args)

This method should print to STDOUT the output of the generator. It may return whatever result seems appropriate (it will be ignored if it's run as the top-level response).

FACTORY

$generator = Contentment::Generator->generator($class, \%args)

This factory method will create the requested generator. If the given class name, $class, does not contain "::", it will be considered a short name and will have the string "Contentment::Generator::" prepended to it to find the generator class.

The arguments should be those necessary to initialize the generator.

$content = Contentment::Generator->content_of($generator, \%args)

This is a helper to stringify the generation of a generator in case you need to just capture the string output instead of printing that output immediately. This is very useful for calling generators from the Template Toolkit generator:

  [% USE Generator %]
  [% Generator.content_of(arg.gen, foo = 1 bar = 2) %]

AUTHOR

Andrew Sterling Hanenkamp, <hanenkamp@cpan.org>

COPYRIGHT AND LICENSE

Copyright 2005 Andrew Sterling Hanenkamp. All Rights Reserved.

Contentment is licensed and distributed under the same terms as Perl itself.