[Templates-cvs] cvs commit: TT3/lib/Template/TT3 Utils.pm

[cvs@template-toolkit.org]

cvs         03/12/04 12:21:43

  Added:       lib/Template/TT3 Utils.pm
  Log:
  * added Template::TT3::Utils and t/utils.t test script
  
  Revision  Changes    Path
  1.1                  TT3/lib/Template/TT3/Utils.pm
  
  Index: Utils.pm
  ===================================================================
  #============================================================= -*-perl-*-
  #
  # Template::TT3::Utils
  #
  # DESCRIPTION
  #   Module implementing various utility functions.
  #
  # AUTHOR
  #   Andy Wardley  <abw@wardley.org>
  #
  # COPYRIGHT
  #   Copyright (C) 1996-2003 Andy Wardley.  All Rights Reserved.
  #   Copyright (C) 1998-2002 Canon Research Centre Europe Ltd.
  #
  #   This module is free software; you can redistribute it and/or
  #   modify it under the same terms as Perl itself.
  #
  # REVISION
  #   $Id: Utils.pm,v 1.1 2003/12/04 12:21:42 abw Exp $
  #
  #========================================================================
  
  package Template::TT3::Utils;
  
  use strict;
  use warnings;
  use File::Basename qw() ;
  use Template::TT3::Base;
  use vars qw( $VERSION $DEBUG $ERROR $WARNING );
  use base qw( Template::TT3::Base );
  
  $VERSION = sprintf("%d.%02d", q$Revision: 1.1 $ =~ /(\d+)\.(\d+)/);
  $DEBUG   = 0 unless defined $DEBUG;
  $ERROR   = '';
  
  
  #------------------------------------------------------------------------
  # load_module($name)
  #
  # Load a Perl module.
  #------------------------------------------------------------------------
  
  sub load_module {
      my ($class, $module) = @_;
      $module  =~ s[::][/]g;
      $module .= '.pm';
      eval { require $module };
      return $@ ? $class->error("failed to load $module: $@") : 1;
  }
  
  
  #------------------------------------------------------------------------
  # load_file($filename)
  #
  # Load the contents of a file.
  #------------------------------------------------------------------------
  
  sub load_file {
      my ($class, $filename) = @_;
      local $/ = undef;
      local *FH;
  
      open(FH, "<$filename") || return $class->error("$filename: $!");
      my $output = <FH>;
      close(FH);
      
      return $output;
  }
  
  
  #------------------------------------------------------------------------
  # save_file($filename, $output)
  #
  # Write output to the file denoted by $filename.  $output can be a text
  # string or a reference to one.
  #------------------------------------------------------------------------
  
  sub save_file {
      my ($class, $filename, $output) = @_;
      my $error;
      local *FP;
  
      # make destination directory if it doesn't exist
      my $dir = File::Basename::dirname($filename);
      eval { mkpath($dir) unless -d $dir; };
      if ($@) {
          # strip file name and line number from error raised by die()
          ($error = $@) =~ s/ at \S+ line \d+\n?$//;
          return $class->error($error);
      }
  
      open(FP, ">$filename") || return $class->error("$filename: $!");
      print FP ref $output ? $$output : $output;
      close FP;
  
      return 1;
  }
  
  
  1;
  __END__
  
  =head1 NAME
  
  Template::TT3::Utils - utility functions for the Template Toolkit
  
  =head1 SYNOPSIS
  
      use Template::TT3::Utils
  
      # supports class methods...
  
      # load a Perl module
      Template::TT3::Utils->load_module('Template::TT3::Compiler')
          || die Template::TT3::Utils->error();  
  
      # load a file
      my $text = Template::TT3::Utils->load_file('/tmp/foo')
          || die Template::TT3::Utils->error();  
  
      # save a file
      Template::TT3::Utils->save_file('/tmp/bar', $text)
          || die Template::TT3::Utils->error();  
  
  
      # ...and also object methods
  
      my $utils = Template::TT3::Utils->new();
  
      # load a Perl module
      $utils->load_module('Template::TT3::Compiler')
          || die $utils->error();  
  
      # load a file
      my $text = $utils->load_file('/tmp/foo')
          || die $utils->error();  
  
      # save a file
      $utils->save_file('/tmp/bar', $text)
          || die $utils->error();  
  
      
  =head1 DESCRIPTION
  
  This module implements a number of useful utility methods.  They can
  be called as class methods:
  
      use Template::TT3::Utils;
  
      # load a Perl module
      Template::TT3::Utils->load_module('Template::TT3::Compiler')
          || die Template::TT3::Utils->error();  
  
  Or as object methods:
  
      my $utils = Template::TT3::Utils->new();
  
      # load a Perl module
      $utils->load_module('Template::TT3::Compiler')
          || die $utils->error();  
  
  =head1 METHODS
  
  =head2 new()
  
  This constructor method creates a new Template::TT3::Utils object.
  
      my $utils = Template::TT3::Utils->new();
  
  =head2 load_module($modname)
  
  This method loads the Perl module named by the first argument.  Any
  occurrences of C<::> in the name will be converted to C</> and C<.pm>
  will be appended to it to determine the correct file name.  
  
      $utils->load_module('Template::TT3::Compiler')
          || die $utils->error();  
  
  In the example above, the module loaded (using Perl's C<require>
  function) is C<Template/TT3/Compiler.pm>.
  
  =head2 load_file($filename)
  
  This method reads the content of the file named by the first argument
  and returns it as a single string.
  
      my $text = $utils->load_file('/tmp/foo')
          || die $utils->error();  
  
  =head2 save_file($filename, $text)
  
  This method writes the text passed as the second argument to the 
  file named by the first.  The text can be passed as a scalar value
  or as a reference to a scalar value.
  
      # pass text
      $utils->save_file('/tmp/bar', $text)
          || die $utils->error();  
  
      # pass reference to text
      $utils->save_file('/tmp/bar', \$text)
          || die $utils->error();  
  
  
  =head1 AUTHOR
  
  Andy Wardley  E<lt>abw@wardley.orgE<gt>
  
  =head1 VERSION
  
  $Revision: 1.1 $
  
  =head1 COPYRIGHT
  
    Copyright (C) 1996-2003 Andy Wardley.  All Rights Reserved.
    Copyright (C) 1998-2002 Canon Research Centre Europe Ltd.
  
  This module is free software; you can redistribute it and/or
  modify it under the same terms as Perl itself.
  
  =cut
  
  # Local Variables:
  # mode: perl
  # perl-indent-level: 4
  # indent-tabs-mode: nil
  # End:
  #
  # vim: expandtab shiftwidth=4: