dream_archive 1.1.0

Pure-Rust Bethesda BA2 and BSA archive reader, extractor, and writer
Documentation
+++
title = "Archive facade"
description = "The crate root: Archive, Entry, Entries, FileFormat, BsaFormat, guess_format, detect_path, Copied, CompressionOverride, the builder aliases and the re-exports."
weight = 10

[extra]
kind = "api"
+++

Everything here is at the crate root, `dream_archive::`. [Reading archives](@/docs/reading.md)
shows it in use.

## Archive

{{ api_signature(value="enum Archive { BA2(ba2::Archive), Tes3Bsa(bsa::tes3::Archive), Tes4Bsa(bsa::tes4::Archive) }") }}

An opened archive of any family. Each variant exists with its family's feature. Match on it to
reach the format type's own API. `Clone`, `Debug`; cloning shares the archive's bytes and copies
its index.

### Opening

{{ api_signature(value="fn open_path(path: impl AsRef<Path>) -> Result<Archive>") }}

Detects the family from the file's first four bytes, then opens it with that family's
`open_path`, which memory-maps the file. `Error::Io` if the file cannot be opened or has fewer
than four bytes, `Error::UnknownFormat` if the family is unknown or its feature is off, and the
family's parse error inside `Error::Ba2` or `Error::Bsa` if the archive is malformed.

{{ api_signature(value="fn from_slice(bytes: &[u8]) -> Result<Archive>") }}

{{ api_signature(value="fn from_vec(bytes: Vec<u8>) -> Result<Archive>") }}

The same, from bytes in memory. `from_slice` copies them; `from_vec` takes ownership.

### Reading

{{ api_signature(value="fn format(&self) -> FileFormat") }}

{{ api_signature(value="fn len(&self) -> usize") }}

{{ api_signature(value="fn is_empty(&self) -> bool") }}

The family, the number of entries, and whether there are none.

{{ api_signature(value="fn entries(&self) -> Entries<'_>") }}

Every entry, in archive order, without allocating.

{{ api_signature(value="fn read_file(&self, path: impl AsRef<[u8]>) -> Result<Option<Vec<u8>>>") }}

{{ api_signature(value="fn read_file_required(&self, path: impl AsRef<[u8]>) -> Result<Vec<u8>>") }}

A member, decompressed into a new `Vec`. `read_file` returns `Ok(None)` when no entry matches
`path`; `read_file_required` returns `Error::FileNotFound` with the path as given.
[Archive paths](@/docs/paths.md#lookups) says how `path` is matched.

{{ api_signature(value="fn extract_file(&self, path: impl AsRef<[u8]>, out: impl Write) -> Result<Option<u64>>") }}

{{ api_signature(value="fn extract_file_required(&self, path: impl AsRef<[u8]>, out: impl Write) -> Result<u64>") }}

A member, decompressed into `out`; returns the number of bytes written. Compressed data is
decoded before it is written.

{{ api_signature(value="fn open_file(&self, path: impl AsRef<[u8]>) -> Result<Option<Box<dyn Read + '_>>>") }}

{{ api_signature(value="fn open_file_required(&self, path: impl AsRef<[u8]>) -> Result<Box<dyn Read + '_>>") }}

A member as a reader that borrows the archive. A stored member is read straight from the
archive's bytes; a compressed one is decoded when the reader is made, so decoding errors come
from this call and not from `read`.

{{ api_signature(value="fn extract_to(&self, target_dir: impl AsRef<Path>) -> Result<u64>") }}

Every entry, written below `target_dir` at its archive path, each file atomically; returns the
bytes written. [Extracting](@/docs/extracting.md) has the rules and what is refused.

## Entry

{{ api_signature(value="enum Entry<'a> { BA2(&'a ba2::Entry), Tes3Bsa(&'a bsa::tes3::Entry), Tes4Bsa(&'a bsa::tes4::Entry) }") }}

One entry, borrowed from an `Archive`. `Clone`, `Copy`, `Debug`.

{{ api_signature(value="fn path(self) -> Option<&'a BStr>") }}

The path the archive stores, as bytes. `None` for a TES4 entry without names and for a BA2 entry
without a string table; a BA2 entry's empty name counts as no name.

{{ api_signature(value="fn format(self) -> FileFormat") }}

The family of the archive it came from.

## Entries

{{ api_signature(value="enum Entries<'a> { BA2(slice::Iter<'a, ba2::Entry>), Tes3Bsa(slice::Iter<'a, bsa::tes3::Entry>), Tes4Bsa(slice::Iter<'a, bsa::tes4::Entry>) }") }}

The iterator `Archive::entries` returns. `Iterator<Item = Entry<'a>>`, `ExactSizeIterator`,
`FusedIterator`, `Clone`, `Debug`.

## Detecting a family

{{ api_signature(value="enum FileFormat { BA2, BSA(BsaFormat) }") }}

{{ api_signature(value="enum BsaFormat { TES3, TES4 }") }}

An archive family. Both are `Clone`, `Copy`, `Debug`, `Eq`, `PartialEq`.

{{ api_signature(value="fn guess_format(input: &mut impl Read) -> io::Result<Option<FileFormat>>") }}

Reads exactly four bytes from `input` and names the family they begin: `BTDX` is BA2, `BSA\0` is
TES4, and `00 01 00 00` is TES3. `Ok(None)` for anything else, or for a family whose feature is
off. An error if four bytes cannot be read. It checks nothing past the magic, and the four bytes
are consumed.

{{ api_signature(value="fn detect_path(path: impl AsRef<Path>) -> io::Result<Option<FileFormat>>") }}

`guess_format` on the start of a file.

## Copied

{{ api_signature(value="struct Copied<'copy>(pub &'copy [u8])") }}

Marks bytes to be copied. `ba2::Archive`, `bsa::tes3::Archive` and `bsa::tes4::Archive` each
implement `TryFrom<Copied<'_>>` as their `from_slice`.

## CompressionOverride

{{ api_signature(value="enum CompressionOverride { Inherit, Store, Compress }") }}

A member's compression in a builder's `_with_compression` calls: `Inherit`, the default, follows
the builder; `Store` never compresses; `Compress` always does. `Clone`, `Copy`, `Debug`,
`Default`, `Eq`, `PartialEq`. [Compression](@/docs/building.md#compression) says what each builder
does with it.

## Builder aliases

{{ api_signature(value="type Ba2Builder = ba2::Builder") }}

{{ api_signature(value="type Ba2Dx10Builder = ba2::Dx10Builder") }}

{{ api_signature(value="type Tes3BsaBuilder = bsa::tes3::Builder") }}

{{ api_signature(value="type Tes4BsaBuilder = bsa::tes4::Builder") }}

The four builders, named at the root. [BA2 builders](@/docs/api/ba2-builders.md),
[bsa::tes3](@/docs/api/tes3.md#builder) and [TES4 builder](@/docs/api/tes4-builder.md).

## Re-exports

{{ api_signature(value="pub use dream_path") }}

[dream-path](https://DreamWeave-MP.github.io/dream_path/), whose normalization every lookup
uses. Depend on it through this re-export and the versions cannot drift apart.

{{ api_signature(value="pub use flate2") }}

The zlib crate whose `Compression` the builders' `set_zlib_level` takes, with the `ba2` or
`bsa-tes4` feature. `dream_archive::flate2::Compression::best()` names a level without a `flate2`
dependency of your own.

{{ api_signature(value="pub use dream_path::bstr") }}

{{ api_signature(value="pub use dream_path::bstr::{BStr, BString, ByteSlice, ByteVec}") }}

The [`bstr`](https://crates.io/crates/bstr) crate and its byte-string types, which entry paths
and several errors use.

`Result` and `Error` are on [Errors](@/docs/api/errors.md).