NAME
    Archive::Builder - File generation and archiving framework

SYNOPSIS
      # Make a builder with one section, and some files
      my $Builder = Archive::Builder->new();
      my $Section = $Builder->new_section( 'html' );
      $Section->add_file( 'one.html', 'string', qq~<html><body>
            Hello World!
            </body></html>~ );
      $Section->add_file( 'two.html', 'file', './source/file.html' );
      $Section->add_file( 'three.html', 'Custom::function', @args );

      # Generate and save to disk
      $Builder->save( './somewhere' );

      # Create an zip file from it and save it.
      my $Archive = $Builder->archive( 'zip' ).
      $Archive->save( 'foo.zip' );

      # Create a tar.gz file of just one section
      my $Tar = $Section->archive( 'tar.gz' );

DESCRIPTION
    Perl is often used for applications that generate large numbers of
    files, and Archive::Builder is designed to assist in these sorts of
    tasks.

    It provides a framework for defining a set of files, and how they will
    be generated, and a series of methods for turning them into an Archive
    of varying types, or saving directly to disk.

  Structure
    Each "Archive::Builder" object consists of one or more
    "Archive::Builder::Section"s, which contain one or more
    "Archive::Builder::File"s. Each of these files know their location
    within the section, and are given a generation function, with a set of
    arguments specific to each generator. Some simple generators are
    provided built-in, or you can provide an function name as the generator.

  Generating Archives
    Once a Archive::Builder is fully defined, you can "save" it to disk, or
    get an "archive", containing the generated files, in one of several
    formats. You can also "save" and get the "archive" any of the individual
    sections within the builder.

    During the generation process for an entire "Archive::Builder" a
    subdirectory is created for each section matching the name of the
    section. So, for a builder with a Section name 'one', containing a
    single file 'two.txt', and a section 'three', containing files
    'four.html' and 'five.dat', the following file structure would result

      one/two.txt
      three/four.html
      three/five.dat

  Caching
    Caching is dont of the generated files on a per-file basis. Two calls to
    the "content()" method of an "Archive::Builder::File" object will only
    result in the file being generated once, and the same contents returned
    twice.

  Generation on Demand Caveats
    During an output action, such as a "save()" or "archive()" method call,
    the contents of each file are generated only as needed. This means that
    if the generation of a file fails, an action may have already been taken
    ( especially in the case of "save()", where you may end up with only
    part of the files written to disk.

    Some procedures to address these limitations will be added as the module
    evolves.

METHODS
    The methods for the three main classes involved in generation trees,
    "Archive::Builder", "Archive::Builder::Section" and
    "Archive::Builder::File" are documented below. For the archive handlers
    the builders generate, see Archive::Builder::Archive. For information on
    the built-in generators, and how to write your own generators, see
    Archive::Builder::Generators.

  Common Error Handlers
    Errors from any object of any type below Archive::Builder are set in the
    global $Archive::Builder::errstr variable. They can also be retrieved
    from the "errstr()" method called on any object.

Archive::Builder
  new()
    The "new()" constructor takes no arguments, and returns a new
    "Archive::Builder" object.

  add_section( Archive::Builder::Section )
    The "add_section" method takes as an argument an
    "Archive::Builder::Section" object, and adds it to the builder.

    Returns true if the section is added successfully. Returns undef on
    error, for example if another Section with the same name has already
    been added.

  new_section( name )
    Creates a new "Archive::Builder::Section" object with the name provided,
    and immediately adds it to the builder.

    Returns the new Section object on success. Returns undef on error.

  section( name )
    Finds and returns a "Archive::Builder::Section" object with the provided
    name within the builder and returns it. Returns undef if passed name
    does not exist.

  sections()
    Returns a hash containing all the sections, indexed by name. Returns 0
    if no sections have been created in the builder.

  section_list()
    Returns all the sections in the builder as a list, sorted by section
    name. Returns a null list "()" if no sections are defined in the
    builder.

  remove_section( name )
    Removes a section of a given name from the builder, if it exists.
    Returns "undef" if no such section exists.

  file_count()
    Returns the total number of files in ass sections in the builder

  save( directory )
    Generates the file tree for the entire builder and attempts to save it
    below a given directory. The passed directory does not have to exist, it
    will be created on demand.

    Returns true if all files were generated and saved successfully. Returns
    "undef" if an error occurs, or the directory is bad.

  archive( type )
    Creates a handle to an archive of a specified type related to the
    builder. Types can only be used if the modules that support them are
    installed. The following types are supported, and their prerequisites
    are listed.

      zip    - Archive::Zip
      tar    - Archive::Tar
      tar.gz - Archive::Tar
      tgz    - Archive::Tar

    The tar.gz and tgz are aliases that produce the same thing with a
    different file extension.

    The "archive" method only returns a "Archive::Builder::Archive" handle
    to the object, not the object itself. Also, the files are not generated
    at the time that the archive is created, so generation errors cannot be
    guarenteed to have occurred by this time.

    To save or otherwise act on the archive, see the
    Archive::Builder::Archive section below.

Archive::Builder::Section
  new( name )
    Creates a new "Archive::Builder::Section" object of a given name.
    Although meant to be used in an "Archive::Builder" object, they can
    still be used effectively standalone, as they have both "save" and
    "archive" methods.

    Returns undef is an invalid section name is given. A section name must
    contain only word ( \w ) characters and be 1 to 31 characters long.

    As a side note, the reason that Sections exist at all is so that
    Builders can be defined containing multiple sections, where the sections
    will be saved to different locations, but should still be passed around
    as a single entity.

  name()
    Returns the name of the Section.

  path( [ path ] )
    When used within the context of a Builder object, and set to the same
    value as the section's name by default, this method returns the path
    below the Builder root that will be used, or if passed a relative path,
    will set the path to a new value. You are not likely to need this, as in
    general, the same value will suffice for both the name and path.

  add_file( Archive::Builder::File )
    Adds an existing "Archive::Builder::File" object to the section.

    Returns true on success. Returns "undef" on error, or if the path of the
    file clashes with an existing file in the Section.

    This could happen if you try to add a file with the same name, of if
    your path contains a directory that is already in the Section as a file.
    For example, the two files could not exist in the same Section.

      first/second
      first/second/third

    Creation of the directory first/second would be blocked by the existing
    file first/second ( or vica versa ). This issue is caught for you now,
    rather than wait until we are halfway through writing the files to disk
    to find out.

  new_file( path, generator [, arguments ] )
    Creates a new file, using the arguments provided, and immediately adds
    it to the current section. See the "new" method for
    Archive::Builder::File below for more details on the arguments.

    Returns true if the file is created and added successfuly. Returns
    "undef" if an error occurs during either the creation or addition of the
    file.

  file( path )
    Finds the "Archive::Builder::File" object with the given path and
    returns it. Returns undef if no such file exists.

  files()
    Returns a reference to a hash containing all of the files objects, keyed
    by their paths. Returns 0 if no files exist within the section.

  file_list()
    Returns a list of all the file objects, sorted by path. Returns a null
    array "()" if no files exist within the section.

  remove_file( path )
    Removes the file object with the given path from the section. Returns
    "undef" if no such path exists within the section.

  file_count()
    Returns the number of files contained in the section

  save( directory )
    The "save()" method works the same as the "Archive::Builder" "save"
    method, generating the files and saving them below the directory
    provided. Again, the directory is created on demand.

    Returns "undef" if an error during generation or saving occurs.

  archive( type )
    As for the "Archive::Builder" "acrhive" method, creates an archive
    handle of the given type. Returns a "Archive::Builder::Archive" object
    on success. Returns "undef" on error.

Archive::Builder::File
  new( path, generator [, arguments ] )
    Creates a new "Archive::Builder::File" object and returns it. This
    method is not normally used directly, with the
    "Archive::Builder::Section" method "new_file()" being more typically
    used.

    The path argument should be a valid looking relative path. That is, it
    cannot start with /. For safety, the use of escaping slashes and
    relative '..' paths are restricted for safety.

    The generator should be a string containing the name of the function to
    be used to generate the file contents. A check will be done to ensure
    that the module containing the function is installed, although the
    existance of the function itself will not be tested. For example, for
    the generator function "Foo::Bar::makeme", a test to make sure
    "Foo::Bar" is installed will be done.

    To specify a function in the the main package ( say in a script ), the
    format "main::function" MUST be used. A generator value that does not
    contain a package seperator will be assumed to be one of the default
    generators. The list of default generators, and instructions on how to
    write your own generators, are in the Archive::Builder::Generators
    documentation.

    Anything passed after the generator are assumed to be arguments to the
    generator function, and will be stored and passed as needed. Note that
    the arguments are not copied or cloned, so any objects passed as
    arguments and later modified, will be generated using the modified
    values. This is considered a feature. If you need to freeze a copy of
    the object for the generation, you are recommended to Clone it before
    passing.

  path()
    Returns the path for the file. This cannot be changed after creation.

  generator()
    Returns the generator for the file. This cannot be changed after
    creation

  arguments()
    Returns a reference to an array containing the arguments to be passed to
    the generator, or 0 if there are no arguments. The list of arguments
    cannot be changed after creation ( although of course objects passed can
    be changed outside the scope of this API ).

  binary()
    This method will analyse the file contents ( generating if needed ) to
    determine if the file is a binary file. While not 100% accurate, it
    should be good enough for most situations.

  executable()
    Calling this method will add a hint to the file that it should be
    considered as an executable file, should the need arise. This is most
    likely used in situations where permissions need to be set after
    generation.

  contents()
    Generates and returns the contents of the file as a scalar reference.
    Returns "undef" if a generation error occurs.

  save( filename )
    Bypassing the normal generation process and path name, the "save" method
    allows you to generate a single file object and save it to a specific
    filename. Any directories need to write the file will be created on
    demand. Returns "undef" if a generation permissions error occurs.

TODO
    Better control over caching, more archive types, pre-generation testing.

SUPPORT
    Contact the author

AUTHOR
            Adam Kennedy ( maintainer )
            cpan@ali.as
            http://ali.as/
        
SEE ALSO
    Archive::Builder::Archive, Archive::Builder::Generators, Archive::Tar,
    Archive::Zip.

COPYRIGHT
    Copyright (c) 2002 Adam Kennedy. All rights reserved. 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.

