NAME
Archive::Builder::Generators - Default generators, and writing your own
SYNOPSIS
# 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;
}DESCRIPTION
This documentation outlines the default generators available to you, and how to write generators of your own to extend Archive::Builder.
DEFAULT GENERATORS
A limited set of generators for the most common situation are provided for you.
The 'string' Generator
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
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
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
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 GENERATORS
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;
}Arguments
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.
Returning the Contents
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;Returning an Error
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.
USING OUR GENERATOR
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.
TO DO
Some more interesting default generators, as needed or requested.
SUPPORT
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.
AUTHOR
Adam Kennedy <adamk@cpan.org>
SEE ALSO
Archive::Builder, Archive::Builder::Archive Archive::Tar, Archive::Zip.
COPYRIGHT
Copyright 2002 - 2008 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.