Any::Renderer::Template - render data structure using a template

  use Any::Renderer;

  my %options = ( 'Template'  => 'path/to/template.tmpl' );

  my $format = "HTML::Template";
  my $r = new Any::Renderer ( $format, \%options );

  my $data_structure = [...]; # arbitrary structure code
  my $string = $r->render ( $data_structure );

  my $list_ref = Any::Renderer::Template::available_formats ();

  my $bool = Any::Renderer::Template::requires_template ( $format );

  perl -MAny::Renderer::Template -e "print join(qq{\n}, sort @{Any::Renderer::Template::available_formats()})"

package Any::Renderer::Template;

# $Id: Template.pm,v 1.21 2006/09/04 12:15:53 johna Exp $

use vars qw($VERSION %Formats $Cache $CacheMaxItems $CacheMaxAtime $CachePurgeInterval $CacheLastPurged);

use Any::Template;
use Cache::AgainstFile;
use strict;

use constant MUST_COMPILE => $ENV{ANY_RENDERER_AT_SAFE};

$VERSION = sprintf"%d.%03d", q$Revision: 1.21 $ =~ /: (\d+)\.(\d+)/;

#Package-level cache and settings
$Cache = undef; #Generated on first use
$CacheMaxItems = 1000;
$CacheMaxAtime = 6 * 60 * 60; # seconds (6 hours)
$CachePurgeInterval = 60 * 60 ; # seconds (1 hour)
$CacheLastPurged = undef;

sub new
{
  my ( $class, $format, $options ) = @_;
  die("You must specify a format in the Any::Renderer::Template constructor") unless(defined $format && length $format);

  unless($Formats{$format}) {
    _scan_available_formats(); #Discover if it's appeared recently
    die("The format '$format' doesn't appear to be supported by Any::Template") unless($Formats{$format});
  }

  #Separate options for this module from options passed through to backend
  $options ||= {};
  my $backend_options = $options->{TemplateOptions} || {
    map {$_ => $options->{$_}} 
    grep {$_ !~ /^(Template|TemplateFilename|TemplateString|NoCache)$/} 
    keys %$options
  };

  $Cache ||= _init_cache ();

  my $self = {
    'format'  => $format,
    'template_file' => $options->{'Template'} || $options->{'TemplateFilename'},
    'template_string' => $options->{'TemplateString'},
    'options' => $backend_options,
    'cache' => $options->{'NoCache'}? undef: $Cache,
  };

  die("You must specify either a template filename or string containing a template") unless($self->{template_file} || defined $self->{template_string});

  bless $self, $class;  
  return $self;
}

# load the template via Any::Template or Cache::AgainstFile
sub render
{
  my ( $self, $data ) = @_;

  my $template;
  my $template_file = $self->{template_file};
  my $template_string = $self->{template_string};
  if ( $template_file )
  {
    if( $self->{cache} )
    {
      TRACE ( "Loading template '" . $template_file . "' via Cache" );
      $template = $self->{cache}->get($template_file, $self->{ 'format' }, $self->{ 'options' });
      _purge_cache($self->{cache}) if(time - $CacheLastPurged > $CachePurgeInterval);
    }
    else
    {
      TRACE ( "No cache found, loading template via _template_from_file" );
      $template = _template_from_file ( $template_file, $self->{'format'}, $self->{'options'}  );
    }
  }
  elsif ( $template_string )
  {
    TRACE ( "Using in-memory template and new Any::Template" );
    $template = _template_from_string($template_string, $self->{'format'}, $self->{'options'});
  }
  else
  {
    die ( "No template provided!" );
  }

  return $template->process ( $data );
}

# returns whether or not this format requires a template
sub requires_template
{
  return 1; #True in all cases
}

# return a list reference of the formats that we handle
sub available_formats
{
  _scan_available_formats();
  return [ sort keys %Formats ];  
}

#
# Private routines
#

# a sub-routine for loading of templates
sub _template_from_file
{
  my ( $filename, $format, $options ) = @_;

  TRACE ( "_template_from_file : loading '$filename' as '$format'" );
  DUMP ( "options", $options );

  my %ops = (
    'Options'   => $options,
    'Filename'  => $filename,
  );
  $ops{'Backend'} = $format unless($format eq 'Any::Template');

  return new Any::Template ( \%ops );
}

sub _template_from_string
{
  my($string, $format, $options) = @_;	
  my %ops = (
    'Options'   => $options,
    'String'    => $string,
  );
  $ops{'Backend'} = $format unless($format eq 'Any::Template');

  return new Any::Template ( \%ops );
}

sub _scan_available_formats
{
  my $formats = Any::Template::available_backends();
  if (MUST_COMPILE) {
    @$formats = grep {
       eval {new Any::Template({Backend => $_, String => ""})} , !$@
    } @$formats;
  }
  %Formats = map {$_ => 1} (@$formats, 'Any::Template');
}

#
# Cache management
#

sub _init_cache
{
  $CacheLastPurged = time();
  return new Cache::AgainstFile ( \&_template_from_file, {
    'Method'    => 'Memory',
    'Grace'     => 0, # seconds
    'MaxATime'  => $CacheMaxAtime,
    'MaxItems'  => $CacheMaxItems,
  } );
}

sub _purge_cache
{
  my $cache = shift;
  return unless defined $cache;
  $cache->purge();
  $CacheLastPurged = time();
}


sub TRACE {}
sub DUMP {}

1;