boundbook/lib.rs
1//! boundbook - a Rust implementation of the Bound Book specification
2mod _types;
3mod builder;
4mod error;
5mod reader;
6
7pub use {
8 builder::BbfBuilder,
9 error::{BbfError, Result},
10 reader::BbfReader,
11};
12
13pub mod types {
14 //! binary data structures used in BBF files
15 //!
16 //! contains all struct definitions for headers, footers, and index entries. these are
17 //! `#[repr(c, packed)]` structs that map directly to the binary file format.
18 //!
19 //! # structures
20 //!
21 //! - [`BbfHeader`] - file header with version and footer offset
22 //! - [`BbfFooter`] - file footer with all table offsets and integrity hash
23 //! - [`AssetEntry`] - describes a unique image asset with offset, size, and hash
24 //! - [`PageEntry`] - links a logical page to an asset
25 //! - [`Section`] - defines chapters or volumes with hierarchical structure
26 //! - [`Metadata`] - key-value pairs for book information
27 //! - [`MediaType`] - enum identifying image format (png, avif, webp, etc)
28 //! - [`Expansion`] - reserved for future format extensions
29 //!
30 //! # usage
31 //!
32 //! ```no_run
33 //! use boundbook::types::*;
34 //! use boundbook::BbfReader;
35 //!
36 //! # fn example() -> boundbook::Result<()> {
37 //! let reader = unsafe { BbfReader::open("book.BBF")? };
38 //! let assets: &[AssetEntry] = reader.assets()?;
39 //! let pages: &[PageEntry] = reader.pages()?;
40 //! # Ok(())
41 //! # }
42 //! ```
43 pub use crate::_types::{
44 AssetEntry, BbfFooter, BbfHeader, Expansion, MediaType, Metadata, PageEntry, Section,
45 };
46}
47
48pub mod format {
49 //! contains all constant values used in the BBF format including magic numbers, version
50 //! info, default alignment settings, size limits, and configuration flags.
51 //!
52 //! # constants
53 //!
54 //! - [`MAGIC`] - BBF3 magic number for format identification
55 //! - [`VERSION`] - current format version (3)
56 //! - [`ALIGNMENT`] - standard 4kb alignment constant
57 //! - [`DEFAULT_GUARD_ALIGNMENT`] - default alignment exponent (12 = 4kb)
58 //! - [`DEFAULT_SMALL_REAM_THRESHOLD`] - default ream size exponent (16 = 64kb)
59 //! - [`MAX_BALE_SIZE`] - maximum index region size (16mb)
60 //! - [`MAX_FORME_SIZE`] - maximum string scan length (2kb)
61 //!
62 //! # flags
63 //!
64 //! - [`BBF_PETRIFICATION_FLAG`] - marks file as read-only/immutable
65 //! - [`BBF_VARIABLE_REAM_SIZE_FLAG`] - enables variable alignment for small assets
66 //!
67 //! # usage
68 //!
69 //! ```no_run
70 //! use boundbook::BbfBuilder;
71 //! use boundbook::format::{BBF_VARIABLE_REAM_SIZE_FLAG, DEFAULT_GUARD_ALIGNMENT};
72 //!
73 //! # fn example() -> boundbook::Result<()> {
74 //! let builder = BbfBuilder::new(
75 //! "book.BBF",
76 //! DEFAULT_GUARD_ALIGNMENT,
77 //! 16,
78 //! BBF_VARIABLE_REAM_SIZE_FLAG
79 //! )?;
80 //! # Ok(())
81 //! # }
82 //! ```
83 pub use crate::_types::{
84 ALIGNMENT, BBF_PETRIFICATION_FLAG, BBF_VARIABLE_REAM_SIZE_FLAG, DEFAULT_GUARD_ALIGNMENT,
85 DEFAULT_SMALL_REAM_THRESHOLD, MAGIC, MAX_BALE_SIZE, MAX_FORME_SIZE, VERSION,
86 };
87}
88
89pub mod prelude {
90 //! prelude module for convenient imports
91 //!
92 //! import this module with `use boundbook::prelude::*;` to get all commonly used types and
93 //! functions without needing to specify each one individually.
94 //!
95 //! # included exports
96 //!
97 //! - [`BbfBuilder`] - for creating BBF files
98 //! - [`BbfReader`] - for reading BBF files
99 //! - [`BbfError`] - error type for BBF operations
100 //! - [`crate::types::MediaType`] - image format enum
101 //!
102 //! # usage
103 //!
104 //! ```no_run
105 //! use boundbook::prelude::*;
106 //!
107 //! fn create_book() -> Result<()> {
108 //! let mut builder = BbfBuilder::with_defaults("manga.BBF")?;
109 //! builder.add_page("cover.png", 0, 0)?;
110 //! builder.finalize()?;
111 //! Ok(())
112 //! }
113 //! ```
114 pub use crate::{BbfBuilder, BbfError, BbfReader, Result, format::*, types::*};
115}