Archive::Builder::Generators - Default generators, and writing your own

  # Our own useless generator
  sub generator {
      my $File = isa( $_[0], 'Archive::Builder::File' )
          ? shift : return undef;

      # Create the file contents
      my $contents = 'Something trivial';

      return \$contents;
  }

This documentation outlines the default generators available to you, and how to write generators of your own to extend Archive::Builder.

A limited set of generators for the most common situation are provided for you.

The 'string' default generator is a simple pass-through for when you already have the contents of the file, generated by another method. The generator takes one argument, which can be either a scalar containing the file contents, or a reference to a scalar containing the file contents

The 'file' generator takes as an argument of a file name, and slurps in the file as the contents. It should be used when the builder file already exists on disk, and just needs to be used directly. Most commonly used for binary files like images and such, that might need to be included, but not modified.

The 'handle' generator takes as argument a single object of an IO::Handle object. It allows you use something the can only easily be accessed as an IO handle easily.

The generator will read from the handle until an EOF is reached and then returns the results.

The 'template' generator hooks in to the power of Template Toolkit. It takes three arguments.

The first is a valid Template object. You would be expected to use the same Template object for multiple files, and can do so without ill effect. The generator does not modify the Template object.

The second and third arguments are the path of the template file to process and a reference to a hash containing the values to provide to the template, using the same values as you would for the normal Template process method.

And error will be caught and passed on, and becomes available from $Archive::Builder::errstr or one of the errstr methods.

Writing a generator is fairly simple. It consist of a single function, residing in a module. It takes some arguments, builds the contents of a file in a single scalar, and then returns a reference to that scalar.

A typical function will look something like this ( you may cut and paste ).

  sub generator {
      # Get the file argument
      my $File = UNIVERSAL::isa( $_[0], 'Archive::Builder::File' )
          ? shift : return undef;

      # Get and check any other arguments
      my $argument = shift;
      return $File->_error( 'Bad argument' ) unless defined $argument;

      # Build the contents
      my $contents = "Something: $argument";

      # Returns the contents
      return \$contents;
  }

The function takes as its first argument the Archive::Builder::File object it is part of. The first few lines of the function should look Any remaining arguments are passed as recieved from the File object constructor. You should do your own checking on the validity of the arguments.

The contents of the file MUST be returned as a reference to a scalar. For example.

  my $contents = "This\n";
  $content .= "That\n";
  return \$content;

The Archive::Builder::File argument we recieve gives us the ability to set an error that can be retrieved later from the $Archive::Builder::errstr variable, or through one of the errstr methods.

The method _error( message ) sets the error string to the value of message, and returns a value of undef. Thus, an easy way to say "Return this error" is simply to write.

  return $File->_error( 'This is an error' );

The _error method will return undef, which will be returned to our caller, signalling an error.

To use our new generator, assuming it's in package Our::New, simply pass its fullyt referenced name as a string.

  $Section->new_file( 'file/path', 'Our::New::generator', $argument );

If the Our::New package is loaded already, the generator will be called normally. If the Our::New package is NOT loaded, Archive::Builder will attempt to load the package Our::New before calling the generator function.

Some more interesting default generators, as needed or requested.

Bugs should always be submitted via the CPAN bug tracker.

http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Archive-Builder

For other issues, contact the maintainer.

Adam Kennedy <adamk@cpan.org>

Archive::Builder, Archive::Builder::Archive Archive::Tar, Archive::Zip.

Copyright 2002 - 2011 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.