view release on metacpan or  search on metacpan

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

Returns a new Archive::Ar object.  Without an argument, it returns
an empty object.  If passed a filename or an open filehandle, it will
read the referenced archive into memory.  If the read fails for any
reason, returns undef.

=head2 set_opt

  $ar->set_opt($name, $val)

Assign option $name value $val.  Possible options are:

=over 4

=item * warn

Warning level.  Levels are zero for no warnings, 1 for brief warnings,
and 2 for warnings with a stack trace.  Default is zero.

=item * chmod

Change the file permissions of files created when extracting.  Default
is true (non-zero).

=item * same_perms

When setting file permissions, use the values in the archive unchanged.
If false, removes setuid bits and applies the user's umask.  Default is
true for the root user, false otherwise.

=item * chown

Change the owners of extracted files, if possible.  Default is true.

=item * type

Archive type.  May be GNU, BSD or COMMON, or undef if no archive has
been read.  Defaults to the type of the archive read, or undef.

=item * symbols

Provide a filename for the symbol table, if present.  If set, the symbol
table is treated as a file that can be read from or written to an archive.
It is an error if the filename provided matches the name of a file in the
archive.  If undefined, the symbol table is ignored.  Defaults to undef.

=back

=head2 get_opt

  $val = $ar->get_opt($name)

Returns the value of option $name.

=head2 type

  $type = $ar->type()

Returns the type of the ar archive.  The type is undefined until an
archive is loaded.  If the archive displays characteristics of a gnu-style
archive, GNU is returned.  If it looks like a bsd-style archive, BSD
is returned.  Otherwise, COMMON is returned.  Note that unless filenames
exceed 16 characters in length, bsd archives look like the common format.

=head2 clear

  $ar->clear()

Clears the current in-memory archive.

=head2 read

  $len = $ar->read($filename)
  $len = $ar->read($filehandle)

This reads a new file into the object, removing any ar archive already
represented in the object.  The argument may be a filename, filehandle
or IO::Handle object.  Returns the size of the file contents or undef
if it fails.

=head2 read_memory

  $len = $ar->read_memory($data)

Parses the string argument as an archive, reading it into memory.  Replaces
any previously loaded archive.  Returns the number of bytes read, or undef
if it fails.

=head2 contains_file

  $bool = $ar->contains_file($filename)

Returns true if the archive contains a file with $filename.  Returns
undef otherwise.

=head2 extract

  $ar->extract()
  $ar->extract_file($filename)

Extracts files from the archive.  The first form extracts all files, the
latter extracts just the named file.  Extracted files are assigned the
permissions and modification time stored in the archive, and, if possible,
the user and group ownership.  Returns non-zero upon success, or undef if
failure.

=head2 rename

  $ar->rename($filename, $newname)

Changes the name of a file in the in-memory archive.

=head2 chmod

  $ar->chmod($filename, $mode);

Change the mode of the member to C<$mode>.

=head2 chown

  $ar->chown($filename, $uid, $gid);