Archive::Libarchive::ArchiveWrite(3)

NAME
Archive::Libarchive::ArchiveWrite - Libarchive write archive class

VERSION
version 0.09

SYNOPSIS
 use 5.020;
 use Archive::Libarchive;
 use Path::Tiny qw( path );

 my $w = Archive::Libarchive::ArchiveWrite->new;
 $w->set_format_pax_restricted;
 $w->open_filename("outarchive.tar");

 path('.')->visit(sub ($path, $) {
   my $path = shift;

   return if $path->is_dir;

   my $e = Archive::Libarchive::Entry->new;
   $e->set_pathname("$path");
   $e->set_size(-s $path);
   $e->set_filetype('reg');
   $e->set_perm( oct('0644') );
   $w->write_header($e);
   $w->write_data(\$path->slurp_raw);

 }, { recurse => 1 });

 $w->close;

DESCRIPTION
This class represents an archive instance for writing to archives.

CONSTRUCTOR

  new
 # archive_write_new
 my $w = Archive::Libarchive::ArchiveWrite->new;

Create a new archive write object.

METHODS
This is a subset of total list of methods available to all archive classes. For the full list see "Archive::Libarchive::ArchiveWrite" in Archive::Libarchive::API.

  open
 # archive_write_open
 $w->open(%callbacks);

This is a basic open method, which relies on callbacks for its implementation. The only callback that is required is the "write" callback. The "open" and "close" callbacks are made available mostly for the benefit of the caller. All callbacks should return a normal status code, which is "ARCHIVE_OK" on success.

Unlike the "libarchive" C-API, this interface doesn't provide a facility for passing in "client" data. In Perl this is implemented using a closure, which should allow you to pass in arbitrary variables via proper scoping.

open
     $w->open(open => sub ($w) {
       ...
     });

    Called immediately when the archive is "opened";

write
     $w->open(write => sub ($w, $ref) {
       ... = $$ref;
       return $size;
     });

    This callback is called when data needs to be written to the archive. It is passed in as a reference to a scalar that contains the raw data. On success you should return the actual size of the data written in bytes, and on failure return a normal status code.

close
     $w->open(open => sub ($w) {
       ...
     });

    This is called when the archive instance is closed.

  open_FILE
 # archive_write_open_FILE
 $w->open_FILE($file_pointer);

This takes either a FFI::C::File, or an opaque pointer to a libc file pointer.

  open_memory
 # archive_write_open_memory
 $w->open_memory(\$buffer);

This takes a reference to scalar and stores the archive in memory there.

  open_perlfile
 $w->open_perlfile(*FILE);

This takes a perl file handle and stores the archive there.

  write_data
 # archive_write_data
 my $size_or_code = $w->write_data(\$buffer);

Write the entry content data to the archive. This takes a reference to the buffer. Returns the number of bytes written on success, and a normal status code on error.

  add_filter
 # archive_write_add_filter
 my $int = $w->add_filter($code);

Add filter to be applied when writing the archive. This will accept either a string representation of the filter code, or the constant. The constant prefix is "ARCHIVE_FILTER_". So for a gzipped file this would be either 'gzip' or "ARCHIVE_FILTER_GZIP". For the full list see "CONSTANTS" in Archive::Libarchive::API.

  set_format
 # archive_write_set_format
 my $int = $w->set_format($code);

Set the output format. This will accept either a string representation of the format, or the constant. The constant prefix is "ARCHIVE_FORMAT_". So for a tar file this would be either 'tar' or "ARCHIVE_FORMAT_TAR".

  set_passphrase_callback
 # archive_write_set_passphrase_callback
 my $int = $w->set_passphrase_callback(sub ($w) {
   ...
   return $passphrase;
 });

Set a callback that will be called when a passphrase is required, for example with a .zip file with encrypted entries.

SEE ALSO

Archive::Libarchive::Peek
    Provides an interface for listing and retrieving entries from an archive without extracting them to the local filesystem.

Archive::Libarchive::Extract
    Provides an interface for extracting arbitrary archives of any format/filter supported by "libarchive".

Archive::Libarchive::Unwrap
    Decompresses / unwraps files that have been compressed or wrapped in any of the filter formats supported by "libarchive"

Archive::Libarchive
    This is the main top-level module for using "libarchive" from Perl. It is the best place to start reading the documentation. It pulls in the other classes and "libarchive" constants so that you only need one "use" statement to effectively use "libarchive".

Archive::Libarchive::API
    This contains the full and complete API for all of the Archive::Libarchive classes. Because "libarchive" has hundreds of methods, the main documentation pages elsewhere only contain enough to be useful, and not to overwhelm.

Archive::Libarchive::Archive
    The base class of all archive classes. This includes some common error reporting functionality among other things.

Archive::Libarchive::ArchiveRead
    This class is used for reading from archives.

Archive::Libarchive::DiskRead
    This class is for reading Archive::Libarchive::Entry objects from disk so that they can be written to Archive::Libarchive::ArchiveWrite objects.

Archive::Libarchive::DiskWrite
    This class is for writing Archive::Libarchive::Entry objects to disk that have been written from Archive::Libarchive::ArchiveRead objects.

Archive::Libarchive::Entry
    This class represents a file in an archive, or on disk.

Archive::Libarchive::EntryLinkResolver
    This class exposes the "libarchive" link resolver API.

Archive::Libarchive::Match
    This class exposes the "libarchive" match API.

Dist::Zilla::Plugin::Libarchive
    Build Dist::Zilla based dist tarballs with libarchive instead of the built in Archive::Tar.

Alien::Libarchive3
    If a suitable system "libarchive" can't be found, then this Alien will be installed to provide it.

libarchive.org <http://libarchive.org/>
    The "libarchive" project home page.

<https://github.com/libarchive/libarchive/wiki>
    The "libarchive" project wiki.

<https://github.com/libarchive/libarchive/wiki/ManualPages>
    Some of the "libarchive" man pages are listed here.

AUTHOR
Graham Ollis <plicease@cpan.org>

COPYRIGHT AND LICENSE
This software is copyright (c) 2021,2022 by Graham Ollis.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.