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//! **Stability — FAFb wire v2 is frozen.** The byte layout is immutable,
21//! enforced by a byte-exact golden-master test in this crate (`compile()` must
22//! reproduce the vendored `.fafb` byte-for-byte; any structural change is caught
23//! immediately). New capabilities ship only as forward-compatible additions —
24//! chunks or flag bits older readers skip; we do not break v2. Because the
25//! `.faf` source is always authoritative, you recompile, never migrate —
26//! nothing gets trapped in an old binary.
27//!
28//! ## Usage
29//!
30//! ```rust
31//! use faf_fafb::{compile, decompile, CompileOptions};
32//!
33//! let yaml = "faf_version: 2.5.0\nproject:\n  name: my-project\n";
34//! let opts = CompileOptions { use_timestamp: false };
35//! let bytes = compile(yaml, &opts).unwrap();
36//! let result = decompile(&bytes).unwrap();
37//! let name = result.get_section_string_by_name("project").unwrap();
38//! assert!(name.contains("my-project"));
39//! ```
40
41pub mod canon;
42pub mod compile;
43pub mod error;
44pub mod flags;
45pub mod header;
46pub mod priority;
47pub mod section;
48pub mod string_table;
49
50// Re-exports for convenience
51pub use canon::{
52    CANONICAL_CHUNKS, CLASSIFICATION_MASK, CanonicalChunk, ChunkClassification, canonical_chunk,
53    is_canonical,
54};
55pub use compile::{CompileOptions, DecompiledFafb, compile, decompile};
56pub use error::{FafbError, FafbResult};
57pub use flags::{
58    FLAG_COMPRESSED, FLAG_EMBEDDINGS, FLAG_MODEL_HINTS, FLAG_RESOLVED, FLAG_SIGNED,
59    FLAG_STRING_TABLE, FLAG_TOKENIZED, FLAG_WEIGHTED, Flags,
60};
61pub use header::{
62    FafbHeader, HEADER_SIZE, MAGIC, MAGIC_U32, MAX_FILE_SIZE, MAX_SECTIONS, VERSION_MAJOR,
63    VERSION_MINOR,
64};
65pub use priority::{
66    PRIORITY_CRITICAL, PRIORITY_HIGH, PRIORITY_LOW, PRIORITY_MEDIUM, PRIORITY_OPTIONAL, Priority,
67};
68pub use section::{SECTION_ENTRY_SIZE, SectionEntry, SectionTable};
69pub use string_table::StringTable;
70
71/// Library version
72pub const VERSION: &str = env!("CARGO_PKG_VERSION");
faf_fafb/lib.rs

faf_fafb/
lib.rs
