# `FormatParser.Archive`

An Archive struct and functions.

The Archive struct contains the fields format, nature, and intrinsics.

## Supported Formats

- `:zip` - ZIP archive
- `:rar` - RAR archive (1.5+)
- `:"7z"` - 7-Zip archive
- `:gz` - GZIP compressed file
- `:bz2` - BZIP2 compressed file
- `:xz` - XZ compressed file
- `:tar` - TAR archive (ustar format)
- `:iso` - ISO 9660 disc image
- `:zstd` - Zstandard compressed file

# `t`

```elixir
@type t() :: %FormatParser.Archive{
  format: atom() | nil,
  intrinsics: map(),
  nature: :archive
}
```

The Archive struct.

## Fields

- `:format` - The detected archive format (e.g., `:zip`, `:rar`, `:gz`)
- `:nature` - Always `:archive` for this struct
- `:intrinsics` - Additional format-specific metadata (currently unused)

# `parse`

```elixir
@spec parse({:error, binary()} | binary() | any()) :: any()
```

Parses an archive file and returns an Archive struct if recognized.

This function attempts to detect the archive format by examining magic bytes
at specific offsets in the binary data.

## Arguments

- `input` - Can be one of:
  - `{:error, binary}` - A tuple containing binary file data (used in parser chain)
  - `binary` - Raw binary file data
  - `any` - Any other value is returned as-is (pass-through for parser chain)

## Returns

- `%Archive{}` - If the file is a recognized archive format
- `{:error, binary}` - If the file is not recognized as an archive
- The input unchanged if it's not a binary or error tuple

## Examples

    iex> {:ok, file} = File.read("archive.zip")
    iex> FormatParser.Archive.parse(file)
    %FormatParser.Archive{format: :zip, nature: :archive, intrinsics: %{}}

    iex> FormatParser.Archive.parse({:error, zip_binary})
    %FormatParser.Archive{format: :zip, nature: :archive, intrinsics: %{}}

    iex> FormatParser.Archive.parse(%FormatParser.Image{})
    %FormatParser.Image{}

---

*Consult [api-reference.md](api-reference.md) for complete listing*