Archive (Archive v0.4.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 theArchive.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
, and Archive.Entry
provide custom implementations for the Inspect
protocol.
When inspecting Archive
, the following custom options can be supplied to the custom_options
option of inspect:
:depth
- Depth of directories to display. Defaults to 3.:breadth
- Breadth of items to display. Defaults to 2.
Examples
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.
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
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.
index(archive, stream)
new()
Create a new Archive
struct
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.
reader!(path, opts \\ [])
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
.
stream!(opts \\ [])
update_entries(archive, stream)
update_info(archive, stream)
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.