Struct PackageReader

pub struct PackageReader<'c> {
    archive: Archive<CompressionDecoder<'c>>,
}

A reader for Package files.

A PackageReader can be created from a Package using the Package::into_reader or PackageReader::try_from methods.

Examples

use std::path::Path;

use alpm_package::{MetadataEntry, Package, PackageReader};
use alpm_types::MetadataFileName;

// A directory for the package file.
let temp_dir = tempfile::tempdir()?;
let path = temp_dir.path();

// Assume that the package is created
let package_path = path.join("output/example-1.0.0-1-any.pkg.tar.zst");

// Create a reader for the package.
let mut reader = package.clone().into_reader()?;

// Read all the metadata from the package archive.
let metadata = reader.metadata()?;
let pkginfo = metadata.pkginfo;
let buildinfo = metadata.buildinfo;
let mtree = metadata.mtree;

// Or you can iterate over the metadata entries:
let mut reader = package.clone().into_reader()?;
for entry in reader.metadata_entries()? {
    let entry = entry?;
    match entry {
        MetadataEntry::PackageInfo(pkginfo) => {}
        MetadataEntry::BuildInfo(buildinfo) => {}
        MetadataEntry::Mtree(mtree) => {}
        _ => {}
    }
}

// You can also read specific metadata files directly:
let mut reader = package.clone().into_reader()?;
let pkginfo = reader.read_metadata_file(MetadataFileName::PackageInfo)?;
// let buildinfo = reader.read_metadata_file(MetadataFileName::BuildInfo)?;
// let mtree = reader.read_metadata_file(MetadataFileName::Mtree)?;

// Read the install scriptlet, if present:
let mut reader = package.clone().into_reader()?;
let install_scriptlet = reader.read_install_scriptlet()?;

// Iterate over the data entries in the package archive.
let mut reader = package.clone().into_reader()?;
for data_entry in reader.data_entries()? {
    let mut data_entry = data_entry?;
    let content = data_entry.content()?;
    // Note: data_entry also implements `Read`, so you can read from it directly.
}

Notes

This API is designed with streaming and single-pass iteration in mind.

Calling Package::into_reader creates a new PackageReader each time, which consumes the underlying archive in a forward-only manner. This allows efficient access to package contents without needing to load the entire archive into memory.

If you need to perform multiple operations on a package, you can call Package::into_reader multiple times — each reader starts fresh and ensures predictable, deterministic access to the archive’s contents.

Please note that convenience methods on Package itself, such as Package::read_pkginfo, are also provided for better ergonomics and ease of use.

The lifetimes 'c is for the CompressionDecoder of the Archive

Fields

archive: Archive<CompressionDecoder<'c>>

Implementations

impl<'c> PackageReader<'c>

pub fn new(archive: Archive<CompressionDecoder<'c>>) -> Self

Creates a new PackageReader from an Archive<CompressionDecoder>.

pub fn raw_entries( &mut self, ) -> Result<Entries<'_, CompressionDecoder<'c>>, Error>

Returns an iterator over the raw entries of the package’s tar archive.

The returned Entries implements an iterator over each Entry, which provides direct data access to all entries of the package’s tar archive.

Errors

Returns an error if the Entries cannot be read from the package’s tar archive.

pub fn entries<'a>(&'a mut self) -> Result<PackageEntryIterator<'a, 'c>, Error>

Returns an iterator over the known files in the alpm-package file.

This iterator yields a set of PackageEntry variants, which may only contain data from metadata files (i.e. ALPM-MTREE, BUILDINFO or PKGINFO) or an install scriptlet (i.e. [alpm-install-scriplet]).

Note

The file names of metadata file formats (i.e. ALPM-MTREE, BUILDINFO, PKGINFO) and install scriptlets (i.e. alpm-install-scriptlet) are prefixed with a dot (.) in alpm-package files.

As alpm-package files are assumed to contain a sorted list of entries, these files are considered first. The iterator stops as soon as it encounters an entry that does not match any known metadata file or install scriptlet file name.

Errors

Returns an error if

• reading the package archive entries fails,
• reading a package archive entry fails,
• reading the contents of a package archive entry fails,
• or retrieving the path of a package archive entry fails.

pub fn metadata_entries<'a>( &'a mut self, ) -> Result<MetadataEntryIterator<'a, 'c>, Error>

Returns an iterator over the metadata entries in the package archive.

This iterator yields MetadataEntrys, which can be either PKGINFO, BUILDINFO, or ALPM-MTREE.

The iterator stops when it encounters an entry that does not match any known package files.

It is a wrapper around PackageReader::entries that filters out the install scriptlet.

Errors

Returns an error if PackageReader::entries fails to read the entries.

pub fn data_entries<'a>( &'a mut self, ) -> Result<impl Iterator<Item = Result<DataEntry<'a, 'c>, Error>>, Error>

Returns an iterator over the data files of the alpm-package archive.

This iterator yields the path and content of each data file of a package archive in the form of a DataEntry.

Notes

This iterator filters out the known metadata files PKGINFO, BUILDINFO and ALPM-MTREE. and the [alpm-install-scriplet] file.

Errors

Returns an error if

• reading the package archive entries fails,
• reading a package archive entry fails,
• reading the contents of a package archive entry fails,
• or retrieving the path of a package archive entry fails.

pub fn metadata(&mut self) -> Result<Metadata, Error>

Reads all metadata from an alpm-package file.

This method reads all the metadata entries in the package file and returns a Metadata struct containing the processed data.

Errors

Returns an error if

• reading the metadata entries fails,
• parsing a metadata entry fails,
• or if any of the required metadata files are not found in the package.

pub fn read_metadata_file( &mut self, file_name: MetadataFileName, ) -> Result<MetadataEntry, Error>

Reads the data of a specific metadata file from the alpm-package file.

This method searches for a metadata file that matches the provided MetadataFileName and returns the corresponding MetadataEntry.

Errors

Returns an error if

• PackageReader::metadata_entries fails to retrieve the metadata entries,
• or a MetadataEntry is not valid.

pub fn read_install_scriptlet(&mut self) -> Result<Option<String>, Error>

Reads the content of the [alpm-install-scriptlet] from the package archive, if it exists.

Errors

Returns an error if PackageReader::entries fails to read the entries.

pub fn read_data_entry<'a, P: AsRef<Path>>( &'a mut self, path: P, ) -> Result<Option<DataEntry<'a, 'c>>, Error>

Reads a DataEntry matching a specific path name from the package archive.

Returns None if no DataEntry is found in the package archive that matches path.

Errors

Returns an error if

• PackageReader::data_entries fails to retrieve the data entries,
• or retrieving the details of a data entry fails.

Trait Implementations

impl Debug for PackageReader<'_>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl TryFrom<&Path> for PackageReader<'_>

fn try_from(path: &Path) -> Result<Self, Self::Error>

Creates a PackageReader from a Path.

Errors

Returns an error if:

• Package::try_from fails to create a Package from path,
• or PackageReader::try_from fails to create a PackageReader from the package.

type Error = Error

The type returned in the event of a conversion error.

impl TryFrom<Package> for PackageReader<'_>

fn try_from(package: Package) -> Result<Self, Self::Error>

Creates a PackageReader from a Package.

Errors

Returns an error if:

• the package file cannot be opened,
• the package file extension cannot be determined,
• or the compression decoder cannot be created from the file and its extension.

type Error = Error

The type returned in the event of a conversion error.