datacard_rs/lib.rs
1//! # DataCard: Generic Binary Card Format Library
2//!
3//! DataCard provides a generic binary card format for storing payloads with
4//! self-describing metadata and optional CRC32 checksums.
5//!
6//! ## Generic Card System
7//!
8//! Implementors define their own card formats by implementing `CardFormat`:
9//!
10//! ```rust,ignore
11//! use datacard_rs::{CardFormat, GenericCard, CardError};
12//!
13//! pub struct TernsigFormat;
14//!
15//! impl CardFormat for TernsigFormat {
16//! const MAGIC: [u8; 4] = *b"TERN";
17//! const VERSION_MAJOR: u8 = 1;
18//! const VERSION_MINOR: u8 = 0;
19//!
20//! fn format_name() -> &'static str { "Ternsig" }
21//! }
22//!
23//! // Create and use cards
24//! let card: GenericCard<TernsigFormat> = GenericCard::new("program", payload);
25//! card.save("program.card")?;
26//!
27//! let loaded: GenericCard<TernsigFormat> = GenericCard::load("program.card")?;
28//! ```
29//!
30//! ## Format Structure
31//!
32//! ```text
33//! ┌────────────────────────────────┐
34//! │ Header (8 bytes) │
35//! │ - Magic (4 bytes) │
36//! │ - Version (2 bytes) │
37//! │ - Flags (2 bytes) │
38//! ├────────────────────────────────┤
39//! │ Metadata (JSON, length-prefix) │
40//! ├────────────────────────────────┤
41//! │ Payload (raw bytes) │
42//! ├────────────────────────────────┤
43//! │ Footer (4 bytes, optional) │
44//! │ - CRC32 checksum │
45//! └────────────────────────────────┘
46//! ```
47
48// Generic card system (preferred)
49mod format;
50mod generic;
51pub mod checksum;
52mod error;
53mod header;
54
55// Re-export generic API
56pub use format::CardFormat;
57pub use generic::{GenericCard, GenericHeader, GenericMetadata};
58pub use error::{CardError, Result};
59pub use header::FLAG_HAS_CHECKSUM;
60
61// =============================================================================
62// Legacy CML-specific API (deprecated - will move to content-markup-language)
63// =============================================================================
64
65#[deprecated(note = "Use GenericCard with your own CardFormat instead")]
66mod card;
67#[deprecated(note = "Use GenericMetadata instead")]
68mod metadata;
69
70#[allow(deprecated)]
71pub use card::Card;
72#[allow(deprecated)]
73pub use header::{CardHeader, FLAG_HAS_TIMESTAMP, MAGIC, VERSION_MAJOR, VERSION_MINOR};
74#[allow(deprecated)]
75pub use metadata::CardMetadata;