Struct Archive 

pub struct Archive<T> { /* private fields */ }

An object providing access to a PNA file. An instance of an Archive can be read and/or written.

The Archive struct provides two main modes of operation:

• Read mode: Allows reading entries from an existing PNA file
• Write mode: Enables creating new entries and writing data to the archive

The archive supports various features including:

• Multiple compression algorithms
• Encryption options
• Solid and non-solid modes
• Chunk-based storage

Examples

Creates a new PNA file and adds an entry to it.

let file = File::create("foo.pna")?;
let mut archive = Archive::write_header(file)?;
let mut entry_builder =
    EntryBuilder::new_file("bar.txt".into(), WriteOptions::builder().build())?;
entry_builder.write_all(b"content")?;
let entry = entry_builder.build()?;
archive.add_entry(entry)?;
archive.finalize()?;

Reads the entries of a PNA file.

let file = File::open("foo.pna")?;
let mut archive = Archive::read_header(file)?;
for entry in archive.entries().skip_solid() {
    let entry = entry?;
    let mut file = File::create(entry.header().path().as_path())?;
    let mut reader = entry.reader(ReadOptions::builder().build())?;
    copy(&mut reader, &mut file)?;
}

Implementations

impl<'d> Archive<&'d [u8]>

pub fn read_header_from_slice(bytes: &'d [u8]) -> Result<Self>

Reads the archive header from the provided bytes and returns a new Archive.

Arguments

• bytes - The [&[u8]] slice to read the header from.

Returns

A new [io::Result<Archive<&[u8]>>].

Errors

Returns an error if an I/O error occurs while reading the header from the bytes.

pub const fn entries_slice<'a>(&'a mut self) -> Entries<'a, 'd>

Returns an iterator over the entries in the archive.

Returns

An iterator over the entries in the archive.

Examples

use libpna::{Archive, ReadEntry};
use std::fs;

let file = fs::read("foo.pna")?;
let mut archive = Archive::read_header_from_slice(&file[..])?;
for entry in archive.entries_slice() {
    match entry? {
        ReadEntry::Solid(solid_entry) => {
            // handle solid entry
        }
        ReadEntry::Normal(entry) => {
            // handle normal entry
        }
    }
}

pub fn raw_entries_slice<'s>( &'s mut self, ) -> impl Iterator<Item = Result<impl Entry + Sized + 'd>> + 's

Returns an iterator over raw entries in the archive.

Returns

An iterator over raw entries in the archive.

Examples

use libpna::Archive;
use std::fs;

let bytes = fs::read("foo.pna")?;
let mut src = Archive::read_header_from_slice(&bytes[..])?;
let mut dist = Archive::write_header(Vec::new())?;
for entry in src.raw_entries_slice() {
    dist.add_entry(entry?)?;
}
dist.finalize()?;

pub fn read_next_archive_from_slice( self, bytes: &[u8], ) -> Result<Archive<&[u8]>>

Reads the next archive from the provided reader and returns a new Archive.

Arguments

• bytes - The [&[u8]] to read from.

Returns

A new Archive.

Errors

Returns an error if an I/O error occurs while reading from the reader.

impl<R: Read> Archive<R>

pub fn read_header(reader: R) -> Result<Self>

Reads the archive header from the provided reader and returns a new Archive.

Arguments

• reader - The Read object to read the header from.

Returns

A new io::Result<Archive<R>>.

Errors

Returns an error if an I/O error occurs while reading the header from the reader.

pub fn raw_entries( &mut self, ) -> impl Iterator<Item = Result<impl Entry + Sized>> + '_

Returns an iterator over raw entries in the archive.

Returns

An iterator over raw entries in the archive.

Examples

use libpna::Archive;
use std::fs::File;

let mut src = Archive::read_header(File::open("foo.pna")?)?;
let mut dist = Archive::write_header(File::create("bar.pna")?)?;
for entry in src.raw_entries() {
    dist.add_entry(entry?)?;
}
dist.finalize()?;

pub fn entries_skip_solid( &mut self, ) -> impl Iterator<Item = Result<NormalEntry>> + '_

👎Deprecated since 0.28.1: Use Archive::entries().skip_solid() chain instead

Returns an iterator over the entries in the archive, excluding entries in solid mode.

Deprecated

Use Archive::entries() followed by skip_solid() instead.

Returns

An iterator over the entries in the archive.

pub fn entries_with_password<'a>( &'a mut self, password: Option<&'a [u8]>, ) -> impl Iterator<Item = Result<NormalEntry>> + 'a

Returns an iterator over the entries in the archive, including entries in solid mode.

Arguments

• password - a password for solid mode entry.

Returns

An iterator over the entries in the archive.

pub fn read_next_archive<OR: Read>(self, reader: OR) -> Result<Archive<OR>>

Reads the next archive from the provided reader and returns a new Archive.

Arguments

• reader - The reader to read from.

Returns

A new Archive.

Errors

Returns an error if an I/O error occurs while reading from the reader.

impl<R> Archive<R>

pub const fn entries(&mut self) -> Entries<'_, R>

Returns an iterator over the entries in the archive.

Returns

An iterator over the entries in the archive.

Examples

use libpna::{Archive, ReadEntry};
use std::fs;

let file = fs::File::open("foo.pna")?;
let mut archive = Archive::read_header(file)?;
for entry in archive.entries() {
    match entry? {
        ReadEntry::Solid(_solid_entry) => {
            // handle solid entry
        }
        ReadEntry::Normal(_entry) => {
            // handle normal entry
        }
    }
}

impl<R: Read + Seek> Archive<R>

pub fn seek_to_end(&mut self) -> Result<()>

Seek the cursor to the end of the archive marker.

Errors

Returns an error if this function failed to seek or contains a broken chunk.

Examples

For appending entry to the existing archive.

let file = File::open("foo.pna")?;
let mut archive = Archive::read_header(file)?;
archive.seek_to_end()?;
archive.add_entry({
    let entry = EntryBuilder::new_dir("dir_entry".into());
    entry.build()?
})?;
archive.finalize()?;

impl<W: Write> Archive<W>

pub fn write_header(write: W) -> Result<Self>

Writes the archive header to the given Write object and return a new Archive.

Arguments

• write - The Write object to write the header to.

Returns

A new io::Result<Archive<W>>

Examples

use libpna::Archive;
use std::fs;

let file = fs::File::create("example.pna")?;
let mut archive = Archive::write_header(file)?;
archive.finalize()?;

Errors

Returns an error if an I/O error occurs while writing header to the writer.

pub fn write_file<F>( &mut self, name: EntryName, metadata: Metadata, option: impl WriteOption, f: F, ) -> Result<()>

where F: FnMut(&mut EntryDataWriter<&mut W>) -> Result<()>,

Writes a regular file as a normal entry into the archive.

Examples

use libpna::{Archive, Metadata, WriteOptions};
use std::fs;
use std::io::{self, prelude::*};

let file = fs::File::create("foo.pna")?;
let mut archive = Archive::write_header(file)?;
archive.write_file(
    "bar.txt".into(),
    Metadata::new(),
    WriteOptions::builder().build(),
    |writer| writer.write_all(b"text"),
)?;
archive.finalize()?;

Errors

Returns an error if an I/O error occurs while writing the entry, or if the closure returns an error.

pub fn add_entry(&mut self, entry: impl Entry) -> Result<usize>

Adds a new entry to the archive.

Arguments

• entry - The entry to add to the archive.

Examples

use libpna::{Archive, EntryBuilder, WriteOptions};
use std::fs;

let file = fs::File::create("example.pna")?;
let mut archive = Archive::write_header(file)?;
archive.add_entry(
    EntryBuilder::new_file("example.txt".into(), WriteOptions::builder().build())?.build()?,
)?;
archive.finalize()?;

Errors

Returns an error if an I/O error occurs while writing a given entry.

pub fn add_entry_part<T>(&mut self, entry_part: EntryPart<T>) -> Result<usize>

where RawChunk<T>: Chunk,

Adds a part of an entry to the archive.

Arguments

• entry_part - The part of an entry to add to the archive.

Examples

let part1_file = File::create("example.part1.pna")?;
let mut archive_part1 = Archive::write_header(part1_file)?;
let entry =
    EntryBuilder::new_file("example.txt".into(), WriteOptions::builder().build())?.build()?;
archive_part1.add_entry_part(EntryPart::from(entry))?;

let part2_file = File::create("example.part2.pna")?;
let archive_part2 = archive_part1.split_to_next_archive(part2_file)?;
archive_part2.finalize()?;

Errors

Returns an error if an I/O error occurs while writing the entry part.

pub fn split_to_next_archive<OW: Write>(self, writer: OW) -> Result<Archive<OW>>

Split to the next archive.

Examples

let part1_file = File::create("example.part1.pna")?;
let mut archive_part1 = Archive::write_header(part1_file)?;
let entry =
    EntryBuilder::new_file("example.txt".into(), WriteOptions::builder().build())?.build()?;
archive_part1.add_entry_part(EntryPart::from(entry))?;

let part2_file = File::create("example.part2.pna")?;
let archive_part2 = archive_part1.split_to_next_archive(part2_file)?;
archive_part2.finalize()?;

Errors

Returns an error if an I/O error occurs while splitting to the next archive.

pub fn finalize(self) -> Result<W>

Writes the end-of-archive marker and finalizes the archive.

Marks that the PNA archive contains no more entries. Normally, a PNA archive reader will continue reading entries in the hope that the entry exists until it encounters this end marker. This end marker should always be recorded at the end of the file unless there is a special reason to do so.

Examples

Creates an empty archive.

let file = File::create("foo.pna")?;
let mut archive = Archive::write_header(file)?;
archive.finalize()?;

Errors

Returns an error if writing the end-of-archive marker fails.

impl<W: Write> Archive<W>

pub fn write_solid_header( write: W, option: impl WriteOption, ) -> Result<SolidArchive<W>>

Writes the archive header to the given Write object and return a new SolidArchive.

Arguments

• write - The Write object to write the header to.
• option - The WriteOptions object of a solid mode option.

Returns

A new io::Result<SolidArchive<W>>

Examples

use libpna::{Archive, WriteOptions};
use std::fs::File;

let option = WriteOptions::builder().build();
let file = File::create("example.pna")?;
let mut archive = Archive::write_solid_header(file, option)?;
archive.finalize()?;

Errors

Returns an error if an I/O error occurs while writing header to the writer.

impl<T> Archive<T>

pub const fn has_next_archive(&self) -> bool

Returns true if an ANXT chunk has appeared before calling this method.

Returns

true if the next archive in the series is available, otherwise false.