Skip to main content

PBO

Struct PBO 

Source
pub struct PBO { /* private fields */ }
Expand description

PBO file

§Examples

let pbo = PBO::from_directory(Path::new("src"), &PackOptions::pack(), None, &mut Warnings::new()).expect("Failed to create PBO");

assert!(pbo.entry_names().any(|name| name == "lib.rs"));

let mut cursor = pbo.to_cursor().unwrap();
let reread = PBO::read(&mut cursor).unwrap();

assert!(reread.checksum().is_some());

Implementations§

Source§

impl PBO

Source

pub fn new() -> PBO

An empty PBO without entries and header extensions.

Source

pub fn entries(&self) -> impl Iterator<Item = (&str, &[u8])>

The entries in the order the PBO has them: header order for a PBO that was read and not modified, the order PBO::write uses (sorted by name) for any other. Data is as stored, so compressed entries stay compressed; see PBO::file_data.

Source

pub fn entry_names(&self) -> impl Iterator<Item = &str>

The entry names, in the order of PBO::entries.

Source

pub fn insert_entry( &mut self, name: impl Into<String>, data: Vec<u8>, ) -> Result<(), Error>

Adds an entry, or replaces the data of the entry with the same name. Replacing an existing entry also replaces its stored name bytes with the new name’s.

§Errors

/ in the name is stored as \. Returns an error if the name has an empty component (leading, trailing or doubled separator, or no name at all) or is one safe_relative_path rejects (drive letter, .. component and so on). Modifying a PBO that was read drops its stored checksum: it is signed as the PBO that would be written.

Source

pub fn remove_entry(&mut self, name: &str) -> Option<Vec<u8>>

Removes an entry and returns its stored data.

Source

pub fn header_extensions(&self) -> impl Iterator<Item = (&str, &str)>

The header extensions (key=value) in file order, including the prefix.

Source

pub fn header_extension(&self, key: &str) -> Option<&str>

The value of a header extension.

Source

pub fn set_header_extension( &mut self, key: impl Into<String>, value: impl Into<String>, )

Sets a header extension; a repeated key keeps its position and takes the new value.

Source

pub fn prefix(&self) -> Option<&str>

The PBO prefix (the header extension prefix).

Source

pub fn checksum(&self) -> Option<&[u8]>

The SHA-1 trailer of a PBO that was read and not modified; None otherwise.

Source

pub fn computed_checksum(&self) -> Option<&[u8]>

The SHA-1 of the bytes of a PBO that was read and not modified (header block and entry data, everything before the trailer); None otherwise. A PBO whose stored checksum differs from it is corrupt or was tampered with.

Source

pub fn entry_headers(&self) -> Vec<EntryHeader>

The entry headers of a PBO that was read, in header order (empty for one made by PBO::from_directory).

Source

pub fn name_bytes(&self, name: &str) -> Vec<u8> ⓘ

Returns the bytes an entry name is stored as in the PBO header.

Source

pub fn header_extensions_bytes(&self) -> Vec<(Vec<u8>, Vec<u8>)>

The header extensions as (key, value) bytes, in the order of PBO::header_extensions: what the PBO header stores for a PBO that was read (a value set since is its UTF-8 bytes), the UTF-8 bytes of the strings otherwise. A repeated key has the bytes of its first key and its last value.

Source

pub fn read<I: Read>(input: &mut I) -> Result<PBO, Error>

Reads an existing PBO from input.

§Errors

Returns an error if the input is not a valid PBO.

Source

pub fn read_headers<I: Read>(input: &mut I) -> Result<HeaderSummary, Error>

Reads only the header block of a PBO: the header extensions and the entry names, in file order. The entry data is never read, so this is cheap for PBOs of any size. Pass a buffered reader.

The input is untrusted: every name is limited to MAX_HEADER_STRING bytes, the number of entries and extensions are limited, and nothing is allocated from a size in the file.

§Errors

Returns an error if the header block is truncated, malformed or exceeds the limits. The extensions are (key, value) pairs in file order.

Source

pub fn read_entries<I: Read + Seek>( input: &mut I, wanted: impl Fn(&str) -> bool, ) -> Result<PboSelection, Error>

Reads the header block of a seekable PBO and only the entries wanted accepts, by seeking to their data. Memory use is bounded by the selected entries, not by the size of the PBO, which can be many hundred MB.

The input is untrusted: the header block is bounded like read_headers, and an entry whose data selected for reading does not lie inside the file is an error (nothing is allocated from a size before it is checked against the file length).

§Errors

Returns an error if the header block is malformed or exceeds the limits, or the data of a selected entry is truncated.

Source

pub fn read_entries_tolerant<I: Read + Seek>( input: &mut I, wanted: impl Fn(&str) -> bool, options: &TolerantRead, ) -> Result<PboSelection, Error>

Like PBO::read_entries, but a damaged entry does not fail the whole selection, and the selection is bounded.

A selected entry whose data is truncated or cannot be decompressed is an error of its own (SelectedEntry::data). The decompressed sizes of the selected entries are added up in file order; the first entry that would take the total past TolerantRead::max_bytes is not read, and neither is any selected entry after it (a smaller later one included); each reports SelectedEntry::is_over_limit. A malformed header block is still an error.

§Errors

Returns an error if the header block is malformed or exceeds the limits, or the entry sizes overflow.

Source

pub fn from_directory( directory: &Path, options: &PackOptions, binarizer: Option<&mut Binarizer>, warnings: &mut dyn WarningSink, ) -> Result<PBO, Error>

Constructs a PBO from a directory, binarizing and rapifying where options.build is set.

options.exclude contains glob patterns to exclude from the PBO, options.include_folders the paths to search recursively for absolute includes and options.direct_include_folders the paths checked only directly (generally the current working directory). options.header_extensions are applied after $PBOPREFIX$; for the same key the option wins. A $NOBIN$ file in the directory turns build off. Models are only binarized when a binarizer is given; without one they are copied as-is with a warning.

§Errors

Returns an error if the directory cannot be read or a file cannot be processed.

Source

pub fn write<O: Write>(&self, output: &mut O) -> Result<(), Error>

Writes PBO to output.

§Errors

Returns an error on I/O failure, if an entry is too large, or if a header extension key or value contains a NUL byte.

Source

pub fn file_data(&self, name: &str) -> Result<Option<Vec<u8>>, Error>

Returns the contents of a file, decompressing it if the PBO stores it compressed. files keeps the stored bytes, because signing hashes those.

§Errors

Returns an error if a compressed entry cannot be decompressed.

Source

pub fn to_cursor(&self) -> Result<Cursor<Vec<u8>>, Error>

Returns the PBO as a Cursor.

§Errors

Returns an error if the PBO cannot be written.

Trait Implementations§

Source§

impl Default for PBO

Source§

fn default() -> PBO

Returns the “default value” for a type. Read more

Auto Trait Implementations§

§

impl Freeze for PBO

§

impl RefUnwindSafe for PBO

§

impl Send for PBO

§

impl Sync for PBO

§

impl Unpin for PBO

§

impl UnsafeUnpin for PBO

§

impl UnwindSafe for PBO

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
§

impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
where ST: ?Sized, DT: ?Sized,

§

impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> IntoEither for T

Source§

fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ

Converts self into a Left variant of Either<Self, Self> if into_left is true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
Source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
where F: FnOnce(&Self) -> bool,

Converts self into a Left variant of Either<Self, Self> if into_left(&self) returns true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
§

impl<T> Pointable for T

§

const ALIGN: usize

The alignment of pointer.
§

type Init = T

The type for initializers.
§

unsafe fn init(init: <T as Pointable>::Init) -> usize

Initializes a with the given initializer. Read more
§

unsafe fn deref<'a>(ptr: usize) -> &'a T

Dereferences the given pointer. Read more
§

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

Mutably dereferences the given pointer. Read more
§

unsafe fn drop(ptr: usize)

Drops the object pointed to by the given pointer. Read more
§

impl<T> Read<Exclusive, BecauseExclusive> for T
where T: ?Sized,

Source§

impl<R, P> ReadPrimitive<R> for P
where R: Read + ReadEndian<P>, P: Default,

Source§

fn read_from_little_endian(read: &mut R) -> Result<Self, Error>

Read this value from the supplied reader. Same as ReadEndian::read_from_little_endian().
Source§

fn read_from_big_endian(read: &mut R) -> Result<Self, Error>

Read this value from the supplied reader. Same as ReadEndian::read_from_big_endian().
Source§

fn read_from_native_endian(read: &mut R) -> Result<Self, Error>

Read this value from the supplied reader. Same as ReadEndian::read_from_native_endian().
Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.