faf_fafb/
lib.rs

1//! faf-fafb — FAFb v2, the compiled binary form of `.faf`.
2//!
3//! IFF-inspired chunked binary: a string table for section names, a section
4//! table at the end for O(1) random access, classification bits (DNA /
5//! Context / Pointer), priority-based truncation, and a CRC32 seal over the
6//! source `.faf`.
7//!
8//! **Closed canonical.** The writer emits exactly the canonical chunk set
9//! (see [`canon`]), in canonical order; non-canonical top-level keys fold into
10//! the `context` chunk. Identical content produces byte-identical output
11//! regardless of input key order — so a `.fafb` is content-addressable: the
12//! same project context yields the same hash, everywhere. The reader keeps the
13//! IFF rule (skip unknown section names gracefully), so a future minor version
14//! can add a chunk without breaking deployed readers.
15//!
16//! **v2 only.** FAFb v1 is pre-release history and is rejected on read
17//! (`IncompatibleVersion`) — re-compile from the `.faf` source, which is always
18//! the source of truth.
19//!
20//! ## Usage
21//!
22//! ```rust
23//! use faf_fafb::{compile, decompile, CompileOptions};
24//!
25//! let yaml = "faf_version: 2.5.0\nproject:\n  name: my-project\n";
26//! let opts = CompileOptions { use_timestamp: false };
27//! let bytes = compile(yaml, &opts).unwrap();
28//! let result = decompile(&bytes).unwrap();
29//! let name = result.get_section_string_by_name("project").unwrap();
30//! assert!(name.contains("my-project"));
31//! ```
32
33pub mod canon;
34pub mod compile;
35pub mod error;
36pub mod flags;
37pub mod header;
38pub mod priority;
39pub mod section;
40pub mod string_table;
41
42// Re-exports for convenience
43pub use canon::{
44    CANONICAL_CHUNKS, CLASSIFICATION_MASK, CanonicalChunk, ChunkClassification, canonical_chunk,
45    is_canonical,
46};
47pub use compile::{CompileOptions, DecompiledFafb, compile, decompile};
48pub use error::{FafbError, FafbResult};
49pub use flags::{
50    FLAG_COMPRESSED, FLAG_EMBEDDINGS, FLAG_MODEL_HINTS, FLAG_RESOLVED, FLAG_SIGNED,
51    FLAG_STRING_TABLE, FLAG_TOKENIZED, FLAG_WEIGHTED, Flags,
52};
53pub use header::{
54    FafbHeader, HEADER_SIZE, MAGIC, MAGIC_U32, MAX_FILE_SIZE, MAX_SECTIONS, VERSION_MAJOR,
55    VERSION_MINOR,
56};
57pub use priority::{
58    PRIORITY_CRITICAL, PRIORITY_HIGH, PRIORITY_LOW, PRIORITY_MEDIUM, PRIORITY_OPTIONAL, Priority,
59};
60pub use section::{SECTION_ENTRY_SIZE, SectionEntry, SectionTable};
61pub use string_table::StringTable;
62
63/// Library version
64pub const VERSION: &str = env!("CARGO_PKG_VERSION");
faf_fafb/lib.rs

faf_fafb/
lib.rs
