bookfile/
lib.rs

1//! ## Bookfile: an immutable container file format
2//!
3//! **This crate is still under development.**
4//!
5//! Bookfile allows creating a file in `Book` format, by writing sequential
6//! chapters. A bookfile can be created in streaming mode, making it possible
7//! to create a Bookfile while writing it into a network socket or other
8//! streaming-only device. Any target supporting `std::io::Write` will work.
9//!
10//! Each chapter contains a `[u8]` payload and is read independently.
11//!
12//! The [`Book`] type represents a read-only Bookfile. Invividual chapters can
13//! be read using the `std::io::Read` interface. `Seek` and `read_at` are
14//! also provided, and work within the context of that chapter: the seek offset
15//! is the offset within the chapter, and a read at the end of the chapter will
16//! return EOF.
17//!
18//! A chapter's offset, length, and id number are all kept in a *Table of Contents*
19//! stored at the end of the file. The TOC will be read when a Book is opened,
20//! but no chapters will be read until requested.
21
22#![warn(missing_docs)]
23#![forbid(unsafe_code)]
24#![warn(clippy::cast_possible_truncation)]
25
26use aversion::util::cbor::CborDataError;
27use std::io;
28use thiserror::Error;
29
30mod book;
31#[doc(inline)]
32pub use book::{Book, BookWriter, ChapterId, ChapterWriter};
33
34mod read;
35#[doc(inline)]
36pub use read::BoundedReader;
37
38/// Book error type
39#[derive(Debug, Error)]
40pub enum BookError {
41    /// A `std::io::Error` occurred while reading or writing data.
42    #[error("IO Error")]
43    Io(Option<io::Error>),
44    /// An EOF happened while attempting to read data.
45    #[error("Premature EOF")]
46    Eof,
47    /// An error occurred while serializing or deserializing data.
48    #[error("Serialize/Deserialize Error")]
49    Serializer,
50    /// The requested chapter was not found.
51    #[error("Chapter not found")]
52    NoChapter,
53}
54
55impl From<CborDataError> for BookError {
56    fn from(e: CborDataError) -> Self {
57        match e {
58            CborDataError::Io(opt) => BookError::Io(opt),
59            CborDataError::Serializer => BookError::Serializer,
60            CborDataError::Eof => BookError::Eof,
61        }
62    }
63}
64
65impl From<io::Error> for BookError {
66    fn from(e: io::Error) -> Self {
67        BookError::Io(Some(e))
68    }
69}
70
71/// A Result type for things that may return [`BookError`].
72pub type Result<T> = std::result::Result<T, BookError>;
bookfile/lib.rs

bookfile/
lib.rs
