jomini 0.34.1

Low level, performance oriented parser for save and game files from EU4, CK3, HOI4, Vic3, Imperator, and other PDS titles
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84

//! Types for parsing clausewitz binary input
//!
//! Main binary deserialization APIs:
//!  - [BinaryFlavor::deserialize_slice]
//!  - [BinaryFlavor::deserialize_reader]
//!
//! If the serde deserialization API is too high level, one can build
//! abstractions ontop of.
//!  - [TokenReader]: An incremental binary lexer designed for handling large
//!    saves in a memory efficient manner.
//!  - [Lexer]: The lowest level, a zero cost binary data scanner over a byte
//!    slice.
//!
//! ## Direct identifier deserialization with `token` attribute
//!
//! There may be some performance loss during binary deserialization as
//! tokens are resolved to strings via a `TokenResolver` and then matched against the
//! string representations of a struct's fields.
//!
//! We can fix this issue by directly encoding the expected token value into the struct:
//!
//! ```rust
//! # #[cfg(feature = "derive")] {
//! # use jomini::{Encoding, JominiDeserialize, Windows1252Encoding, binary::BinaryFlavor};
//! # use std::{borrow::Cow, collections::HashMap};
//! #
//! # #[derive(Debug, Default)]
//! # pub struct BinaryTestFlavor;
//! #
//! # impl BinaryFlavor for BinaryTestFlavor {
//! #     fn visit_f32(&self, data: [u8; 4]) -> f32 {
//! #         f32::from_le_bytes(data)
//! #     }
//! #
//! #     fn visit_f64(&self, data: [u8; 8]) -> f64 {
//! #         f64::from_le_bytes(data)
//! #     }
//! # }
//! #
//! # impl Encoding for BinaryTestFlavor {
//! #     fn decode<'a>(&self, data: &'a [u8]) -> Cow<'a, str> {
//! #         Windows1252Encoding::decode(data)
//! #     }
//! # }
//! #
//! # let data = [ 0x82, 0x2d, 0x01, 0x00, 0x0f, 0x00, 0x03, 0x00, 0x45, 0x4e, 0x47 ];
//! #
//! #[derive(JominiDeserialize, PartialEq, Debug)]
//! struct MyStruct {
//!     #[jomini(token = 0x2d82)]
//!     field1: String,
//! }
//!
//! // Empty token to string resolver
//! let map = HashMap::<u16, String>::new();
//!
//! let actual: MyStruct = BinaryTestFlavor.deserialize_slice(&data[..], &map)?;
//! assert_eq!(actual, MyStruct { field1: "ENG".to_string() });
//! # }
//! # Ok::<(), Box<dyn std::error::Error>>(())
//! ```
//!
//! Couple notes:
//!
//! - This does not obviate need for the token to string resolver as tokens may be used as values.
//! - If the `token` attribute is specified on one field on a struct, it must be specified on all fields of that struct.

/// binary deserialization
#[cfg(feature = "serde")]
pub mod de;
#[cfg(feature = "serde")]
pub use self::de::{BinaryDeserializer, BinaryDeserializerBuilder};

mod flavor;
mod lexer;
mod reader;
mod resolver;
mod rgb;

pub use self::flavor::BinaryFlavor;
pub use self::lexer::{LexError, LexemeId, Lexer, LexerError, Token, TokenKind};
pub use self::reader::{ReaderError, ReaderErrorKind, TokenReader, TokenReaderBuilder};
pub use self::resolver::{BasicTokenResolver, FailedResolveStrategy, TokenResolver};
pub use self::rgb::*;