Struct EntryBuilder 

pub struct EntryBuilder { /* private fields */ }

A builder for creating a NormalEntry.

This builder provides a flexible way to construct entries for PNA archives by specifying the entry type (file, directory, symbolic link, hard link), content, and metadata. It handles compression and encryption transparently according to the provided WriteOptions.

Entry Types

• Files: Created with new_file(), supports data writing via the Write trait
• Directories: Created with new_dir(), have no data payload
• Symbolic links: Created with new_symlink(), data is the link target path
• Hard links: Created with new_hard_link(), data is the link target path

Write Trait Behavior

For file entries, the Write trait is fully functional. Data written via write_all() or similar methods is automatically compressed and encrypted according to the WriteOptions provided at construction time. The original (uncompressed) file size is tracked separately.

For directory entries, the Write trait is implemented but writing data has no effect. Directories do not store data payloads in PNA archives.

For symbolic link and hard link entries, do not use the Write trait. Instead, the link target is provided to the constructor (new_symlink() or new_hard_link()).

Metadata

Metadata (timestamps, permissions, extended attributes) can be set at any time before calling build(). The order does not matter - you can set metadata before, during, or after writing data to file entries.

Compression and Encryption

When data is written to a file entry:

1. Data is compressed according to WriteOptions compression settings
2. Compressed data is encrypted according to WriteOptions encryption settings
3. Encrypted data is buffered into chunks
4. Chunks are finalized when build() is called

This happens transparently - you just write raw data and the builder handles the rest.

Important Notes

• Each builder can only be built once (build() consumes self)
• File entries with no data written will have zero size
• Compression and encryption are applied during writes, not at build time
• The build() method finalizes compression/encryption streams
• Building a directory or file without calling write methods is valid

Examples

Creating a file entry

use libpna::{EntryBuilder, WriteOptions};

let mut builder = EntryBuilder::new_file("my_file.txt".into(), WriteOptions::store())?;
builder.write_all(b"This is the file content.")?;
let entry = builder.build()?;

Creating a file entry with extended attributes

use libpna::{EntryBuilder, WriteOptions, ExtendedAttribute};

let mut builder = EntryBuilder::new_file("data.txt".into(), WriteOptions::store())?;
builder.write_all(b"file content")?;
builder.add_xattr(ExtendedAttribute::new("user.comment".into(), b"important".to_vec()));
let entry = builder.build()?;

Creating a directory entry

use libpna::EntryBuilder;

let builder = EntryBuilder::new_dir("my_dir/".into());
let entry = builder.build()?;

Creating a symbolic link entry

use libpna::EntryBuilder;

let builder = EntryBuilder::new_symlink(
    "link_name".into(),
    "target/file.txt".into()
)?;
let entry = builder.build()?;

Implementations

impl EntryBuilder

pub const fn new_dir(name: EntryName) -> EntryBuilder

Creates a new directory with the given name.

Arguments

• name - The name of the entry to create.

Returns

A new EntryBuilder.

pub fn new_file( name: EntryName, option: impl WriteOption, ) -> Result<EntryBuilder, Error>

Creates a new file with the given name and write options.

Arguments

• name - The name of the entry to create.
• option - The options for writing the entry.

Returns

A Result containing the new EntryBuilder, or an I/O error if creation fails.

Errors

Returns an error if initialization fails.

pub fn new_symlink( name: EntryName, source: EntryReference, ) -> Result<EntryBuilder, Error>

Creates a new symbolic link with the given name and link.

Arguments

• name - The name of the entry to create.
• source - The entry reference the symlink points to.

Returns

A new EntryBuilder.

Errors

Returns an error if initialization fails.

Examples

use libpna::{EntryBuilder, EntryName, EntryReference};

let builder = EntryBuilder::new_symlink(
    EntryName::try_from("path/of/target").unwrap(),
    EntryReference::try_from("path/of/source").unwrap(),
)
.unwrap();
let entry = builder.build().unwrap();

pub fn new_symbolic_link( name: EntryName, source: EntryReference, ) -> Result<EntryBuilder, Error>

👎Deprecated since 0.27.2: Use EntryBuilder::new_symlink instead

Creates a new symbolic link with the given name and link.

Deprecated

Use EntryBuilder::new_symlink instead.

Arguments

• name - The name of the entry to create.
• source - The entry reference the symlink points to.

Errors

Returns an error if initialization fails.

pub fn new_hard_link( name: EntryName, source: EntryReference, ) -> Result<EntryBuilder, Error>

Creates a new hard link with the given name and link.

Arguments

• name - The name of the entry to create.
• link - The name of the entry reference.

Returns

A new EntryBuilder.

Errors

Returns an error if initialization fails.

Examples

use libpna::{EntryBuilder, EntryName, EntryReference};

let builder = EntryBuilder::new_hard_link(
    EntryName::try_from("path/of/target").unwrap(),
    EntryReference::try_from("path/of/source").unwrap(),
)
.unwrap();
let entry = builder.build().unwrap();

pub fn created( &mut self, since_unix_epoch: impl Into<Option<Duration>>, ) -> &mut EntryBuilder

Sets the creation timestamp of the entry.

Arguments

• since_unix_epoch - The duration since the Unix epoch to set the creation timestamp to.

Returns

A mutable reference to the EntryBuilder with the creation timestamp set.

pub fn modified( &mut self, since_unix_epoch: impl Into<Option<Duration>>, ) -> &mut EntryBuilder

Sets the last modified timestamp of the entry.

Arguments

• since_unix_epoch - The duration since the Unix epoch to set the last modified timestamp to.

Returns

A mutable reference to the EntryBuilder with the last modified timestamp set.

pub fn accessed( &mut self, since_unix_epoch: impl Into<Option<Duration>>, ) -> &mut EntryBuilder

Sets the last accessed timestamp of the entry.

Arguments

• since_unix_epoch - The duration since the Unix epoch to set the last accessed timestamp to.

Returns

A mutable reference to the EntryBuilder with the last modified timestamp set.

pub fn permission( &mut self, permission: impl Into<Option<Permission>>, ) -> &mut EntryBuilder

Sets the permission of the entry to the given owner, group, and permissions.

Arguments

• permission - A Permission struct containing the owner, group, and permissions to set for the entry.

Returns

A mutable reference to the EntryBuilder with the permission set.

pub fn file_size(&mut self, store: bool) -> &mut EntryBuilder

Sets retention of raw file size data for entry.

Arguments

• store - If true retention data of raw file size for entry, otherwise not.

Returns

A mutable reference to the EntryBuilder with the store set.

pub fn add_xattr(&mut self, xattr: ExtendedAttribute) -> &mut EntryBuilder

Adds ExtendedAttribute to the entry.

Arguments

• xattr - The extended attribute.

Returns

A mutable reference to the EntryBuilder with the creation timestamp set.

pub fn add_extra_chunk<T>(&mut self, chunk: T) -> &mut EntryBuilder

where T: Into<RawChunk>,

Adds extra chunk to the entry.

Arguments

• chunk - The extra chunk.

Returns

A mutable reference to the EntryBuilder with the creation timestamp set.

pub fn build(self) -> Result<NormalEntry, Error>

Builds the entry and returns a Result containing the new NormalEntry.

Returns

A Result containing the new NormalEntry, or an I/O error if the build fails.

Errors

Returns an error if an I/O error occurs while building entry into buffer.

Trait Implementations

impl EntryBuilderExt for EntryBuilder

fn add_metadata(&mut self, metadata: &Metadata) -> &mut Self

Sets metadata from a Metadata instance.

Examples

use pna::{EntryBuilder, Metadata, WriteOptions, prelude::*};
use std::fs;

let fs_meta = fs::metadata("some_file.txt")?;
let metadata = Metadata::from_metadata(&fs_meta)?;

let mut builder = EntryBuilder::new_file("some_file.txt".try_into().unwrap(), WriteOptions::store())?;
builder.add_metadata(&metadata);

fn created_time(&mut self, time: impl Into<Option<SystemTime>>) -> &mut Self

Sets the created time using SystemTime.

Examples

use pna::{EntryBuilder, WriteOptions, prelude::*};
use std::time::SystemTime;

let mut builder = EntryBuilder::new_file("file.txt".try_into().unwrap(), WriteOptions::store())?;
builder.created_time(SystemTime::now());

fn modified_time(&mut self, time: impl Into<Option<SystemTime>>) -> &mut Self

Sets the modified time using SystemTime.

Examples

use pna::{EntryBuilder, WriteOptions, prelude::*};
use std::time::SystemTime;

let mut builder = EntryBuilder::new_file("file.txt".try_into().unwrap(), WriteOptions::store())?;
builder.modified_time(SystemTime::now());

fn accessed_time(&mut self, time: impl Into<Option<SystemTime>>) -> &mut Self

Sets the accessed time using SystemTime.

Examples

use pna::{EntryBuilder, WriteOptions, prelude::*};
use std::time::SystemTime;

let mut builder = EntryBuilder::new_file("file.txt".try_into().unwrap(), WriteOptions::store())?;
builder.accessed_time(SystemTime::now());

impl Write for EntryBuilder

fn write(&mut self, buf: &[u8]) -> Result<usize, Error>

Writes a buffer into this writer, returning how many bytes were written.

fn flush(&mut self) -> Result<(), Error>

Flushes this output stream, ensuring that all intermediately buffered contents reach their destination.

fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize, Error>

Like write, except that it writes from a slice of buffers.

fn is_write_vectored(&self) -> bool

🔬This is a nightly-only experimental API. (can_vector)

Determines if this Writer has an efficient write_vectored implementation.

fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>

Attempts to write an entire buffer into this writer.

fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>

🔬This is a nightly-only experimental API. (write_all_vectored)

Attempts to write multiple buffers into this writer.

fn write_fmt(&mut self, args: Arguments<'_>) -> Result<(), Error>

Writes a formatted string into this writer, returning any error encountered.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adapter for this instance of Write.