view release on metacpan or  search on metacpan

README  view on Meta::CPAN

      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.

  Builder
    If the Section has been added to a Builder, the "Builder" method will
    return it.

    Returns a "Archive::Builder" object if added, or "undef" if not.

  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.

  delete
    The "delete" method deletes a Section, removing it from its parent
    Builder if applicable, and removing all child Files from the Section.

    The "delete" method always returns true.

  reset
    If the contents of any of the files in the Section has been generated (
    and thus cached ), the "reset" method will remove any cached content
    from the files, forcing them to be generated again.

    The "reset" method always returns true.

  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