Archive (Archive v0.3.0)

Archive provides Elixir bindings to libarchive through the power of the wonderful Zigler library.

Archive provides a high-level API for interacting with archive files.

Intro to Archive's APIs

High-Level API

The Archive API is the highest-level API offered by Archive, and mostly consists of convenience functions for common use cases with archives. It involves using the Archive struct as a container for archive information extracted from archives using the Archive.Stream API.

It also implements the Inspect protocol specially for providing information about the archive in a succinct manner.

Streaming API

Archive implements archive traversal, reading, and writing as streams. It does this in the Archive.Stream module.

Archive.Stream implements both the Enumerable and Collectable protocol, modeled after File.Stream from the standard library. This allows you to read from an archive, perform transformations, and redirect to a new archive, all lazily.

All implementations in the high-level API are built off of the streaming API.

Low-Level API

Caution

The low-level API is a nearly one-to-one mapping to the libarchive C API. All of the low-level API lives in the Archive.Nif module, and it is highly recommended to not use this API directly.

If you choose to use this API, you will need to carefully consider resource management and proper error checking.

Realistically, you will likely mix the High-Level API and the Streaming API, since the Streaming API is required to traverse the archive.

Concepts

Like libarchive, Archive treats all files as streams first and foremost, but provides many convenient high-level APIs to make it more natural to work with archive.

There are four major operations that Archive performs:

Reading Archives

As streams, archives are not conducive to random-access reads or seeks. Once archives are opened and read, they must be closed and reopened to read again. It is often a two-stage process to read an archive, where you read a list of the contents first, then selectively filter which items you want suring a second pass.

Archive takes care of all resource allocations, initializations, and cleanup for you. Using the high-level API, you only need to provide a mapping function to determine what to do with each entry as it is streamed.

The mapping function will accept an Archive.Entry struct, which will contain metadata (such as path and size) information about the entry. You can use that information to determine what to do in your function.

You can also use function from the Archive.Entry module to perform different operations with the entry (most commonly Archive.Entry.load/2).

Writing Archives

TODO

Writing to Disk

TODO

Extracting to Disk

TODO

Inspect

Archive,Archive.Stream, andArchive.Entryprovide custom implementations for theInspectprotocol. When inspectingArchive, the following custom options can be supplied to thecustom_optionsoption of inspect: *:depth- Depth of directories to display. Defaults to 3. *:breadth` - Breadth of items to display. Defaults to 2. ### Examples elixir IO.inspect(%Archive{} = a, custom_options: [depth: 3, breadth: 2]) #Archive[zip]< 147 entries (40 loaded), 506.0 KB ─────────────── .editorconfig (166 B) .github/ (1 items, 338 B) workflows/ (1 items, 338 B) deploy-theme.yml (338 B) ... and 21 more >

Summary

Functions

Extracts the archive from the reader stream, extracting the archive to disk.

Create a new Archive struct

Creates a new Archive.Stream that is capable of reading an archive.

Creates a new Archive.Stream that is capable of reading and writing an archive.

Creates a new Archive.Stream that is capable of writing an archive.

Functions

Link to this function

extract(stream, opts \\ [])

Extracts the archive from the reader stream, extracting the archive to disk.

As opposed to the other write operations, which write a new archive, extract extracts the archive to disk at the target location.

Options

  • :flags - Controls optional behavior when extracting archive entries to disk. Pass all flags you want to enable as a list. The available flags and their default behavior is as follows:

    • :owner - Do not try to set owner/group.
    • :perm - Do obey umask, do not restore SUID/SGID/SVTX bits.
    • :time - Do not restore mtime/atime.
    • :no_overwrite - Replace existing files.
    • :unlink - Try create first, unlink only if create fails with EEXIST.
    • :acl - Do not restore ACLs.
    • :fflags - Do not restore fflags.
    • :xattr - Do not restore xattrs.
    • :secure_symlinks - Do not try to guard against extracts redirected by symlinks. Note: With ARCHIVE_EXTRACT_UNLINK, will remove any intermediate symlink.
    • :secure_nodotdot - Do not reject entries with '..' as path elements.
    • :no_autodir - Create parent directories as needed.
    • :no_overwrite_newer - Overwrite files, even if one on disk is newer.
    • :sparse - Detect blocks of 0 and write holes instead.
    • :mac_metadata - Do not restore Mac extended metadata. This has no effect except on Mac OS.
    • :no_hfs_compression - Use HFS+ compression if it was compressed. This has no effect except on Mac OS v10.6 or later.
    • :hfs_compression_forced - Do not use HFS+ compression if it was not compressed. This has no effect except on Mac OS v10.6 or later.
    • :secure_noabsolutepaths - Do not reject entries with absolute paths
    • :clear_nochange_fflags - Do not clear no-change flags when unlinking object
    • :safe_writes - Do not extract atomically (using rename) The default value is [].
  • :to (String.t/0) - Directory to extract to. Will create any intermediate directories as necessary. Defaults to the current working directory.

  • :prefix (String.t/0) - A prefix to apply to each archive entry.

Link to this function

index(archive, stream)

Create a new Archive struct

Link to this function

reader(path_or_data, opts \\ [])

Creates a new Archive.Stream that is capable of reading an archive.

Attempts to infer whether the passed binary is a filename or in-memory data to be read.

Options

See Reader Options for a list of the full options.

Link to this function

reader!(path, opts \\ [])

Link to this function

stream(opts \\ [])

Creates a new Archive.Stream that is capable of reading and writing an archive.

Options

  • :writer - The default value is [format: :tar, filters: :none].

  • :reader - The default value is [formats: [:cpio, :tar, :iso9660, :iso9660_rockridge, :zip, :empty, :ar, :ar_gnu, :ar_bsd, :mtree, :raw, :xar, :lha, :cab, :rar, :sevenz, :warc, :rar_v5], filters: [:none, :gzip, :bzip2, :compress, :lzma, :xz, :uu, :lzip, :lrzip, :lzop, :grzip, :lz4, :zstd, :rpm]].

Writer Options

Configures the writer. If true, uses default options. If a keyword list, uses the following options:

  • :format - The format to use when writing the archive. Must be one of these supported write formats: [:cpio, :cpio_posix, :cpio_bin_le, :cpio_bin_be, :cpio_svr4_nocrc, :cpio_svr4_crc, :cpio_afio_large, :cpio_pwb, :shar, :shar_base, :shar_dump, :tar, :tar_ustar, :tar_pax_interchange, :tar_pax_restricted, :tar_gnutar, :iso9660, :zip, :mtree, :raw, :xar, :sevenz, :warc]. The default value is :tar.

  • :filters - The filters to apply when writing. Can be :all, a single filter, or a list of such filters. Available write filters are [:none, :gzip, :bzip2, :compress, :lzma, :xz, :uu, :lzip, :lrzip, :lzop, :grzip, :lz4, :zstd]. The default value is :none.

  • :file (String.t/0) - Required. The path or name of the file to write the archive to.

Reader Options

Configures the reader. If false, disables reading. If a keyword list, uses the following options:

  • :formats - Specifies the archive formats to support when reading. Can be a single format, a list of such formats, or a keyword list with either :only or :except keys containing lists of formats. Available reader formats are [:cpio, :tar, :iso9660, :iso9660_rockridge, :zip, :empty, :ar, :ar_gnu, :ar_bsd, :mtree, :raw, :xar, :lha, :cab, :rar, :sevenz, :warc, :rar_v5]. The default value is :all.

  • :filters - Specifies the filters to support when reading. Can be a single filter, a list of such filters, or a keyword list with either :only or :except keys containing lists of filters. Available reader filters are [:none, :gzip, :bzip2, :compress, :lzma, :xz, :uu, :lzip, :lrzip, :lzop, :grzip, :lz4, :zstd, :rpm] The default value is [:none, :gzip, :bzip2, :compress, :lzma, :xz, :uu, :lzip, :lrzip, :lzop, :grzip, :lz4, :zstd, :rpm].

  • :open (String.t/0) - Required. The path or name of the archive to open.

  • :as - Specifies how to treat the opened archive. Available options are [:file, :data, :auto] The default value is :auto.

Link to this function

stream!(opts \\ [])

Link to this function

update_entries(archive, stream)

Link to this function

update_info(archive, stream)

Link to this function

writer(path, opts \\ [])

Creates a new Archive.Stream that is capable of writing an archive.

Opens the writer at the given filepath.

Options

See Writer Options for a list of the full options.

Link to this function

writer!(path, opts \\ [])