view release on metacpan or  search on metacpan

lib/Archive/Builder.pm  view on Meta::CPAN

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

The C<archive> method only returns a C<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.

=head1 Archive::Builder::Section

=head2 new name

Creates a new C<Archive::Builder::Section> object of a given name. Although
meant to be used in an C<Archive::Builder> object, they can still be used
effectively standalone, as they have both C<save> and C<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.

=head2 name

Returns the name of the Section.

=head2 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.

=head2 Builder

If the Section has been added to a Builder, the C<Builder> method will return
it.

Returns a C<Archive::Builder> object if added, or C<undef> if not.

=head2 add_file $Archive::Builder::File

Adds an existing C<Archive::Builder::File> object to the section.

Returns true on success. Returns C<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.

=head2 new_file $path, $generator [, @arguments ]

Creates a new file, using the arguments provided, and immediately adds it
to the current section. See the C<new> method for Archive::Builder::File
below for more details on the arguments.

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

=head2 file $path

Finds the C<Archive::Builder::File> object with the given path and returns
it. Returns undef if no such file exists.

=head2 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.

=head2 file_list

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

=head2 remove_file $path

Removes the file object with the given path from the section. Returns C<undef>
if no such path exists within the section.

=head2 file_count

Returns the number of files contained in the section

=head2 save $directory

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

Returns C<undef> if an error during generation or saving occurs.

=head2 delete

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

The C<delete> method always returns true.

=head2 reset

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

The C<reset> method always returns true.