Crate cdragon_prop
source ·Expand description
Support of Riot PROP files
Overview
PROP files, more commonly called bin files, contain nested data structures. All structures are typed and usually abide to the same type, but type is provided in the data itself, so there is no need to have a schema to decode it.
Each PROP File contains a list of entries which itself contains a nested list of fields of various data types.
Dynamic types
Container types store data whose type is defined dynamically. Since Rust types are defined statically, they cannot be used directly. Moreover, even if the embedded bin type is known by the container at run-time, the Rust type system requires the user to explicitely request a given type, one way or the other.
The binget!()
macro makes it easier to chain casts and should be enough when the names and
types to get are known in advance.
Data can also be casted explicitely, using the downcast()
method provided by
all types wrapping dynamically typed data:
field.downcast::<BinString>();
// => `Some(BinString)` if field contains a string, `None` otherwise
Containers with fields provide a getv()
helper to follow a get()
with a downcast()
.
If all possible types have to be handled, the binvalue_map_type!()
can be used to provide a
single generic expression to handle all possible types.
Map keys support only a subset or types. binvalue_map_keytype!()
can be used to map only
key types. It can be combined with another binvalue_map_type!()
to handle both keys and
values.
Note: those macros are expanded to a match
handling all possible cases; resulting code can be
large.
Examples
binvalue_map_type!(field.vtype, T, {
let value: &T = field.downcast::<T>().unwrap();
});
binvalue_map_keytype!(map.ktype, K,
binvalue_map_type!(map.vtype, V, {
let entries: &Vec<(K, V)> = map.downcast::<K, V>().unwrap();
})
);
Bin hashes
Bin files use 32-bit FNV-1a hashes for several identifier names:
Hash values can be computed at compile-time with cdragon_hashes::binh!()
, or
using other methods from cdragon_hashes::bin
.
A BinHashMappers
gather all hash-to-string conversion needed by bin data.
Re-exports
pub use visitor::BinVisitor;
pub use visitor::BinTraversal;
pub use data::*;
Modules
- Bin data definitions
- Visit a nested bin value
Macros
- Helper to access nested bin values
- Same as
binvalue_map_type!
, but limited to types used aBinMap
keys - Map
BinType
variant toBinValue
concrete type in an expression
Structs
- Entry in a PROP file
- Scan entries from a bin file
- Generic type to associate each kind of hash from bin files to a value
- Serialize bin values to JSON
- PROP file, with entries
- Serialize bin values to a human readable text tree
Enums
- Enum with a variant for each kind of bin hash
- Error in a PROP file
Constants
- Files known to not be PROP files, despite their extension
Traits
- Serialize streamed bin entries
- Serialize bin data
Functions
- Return
true
if a path is a bin file path
Type Aliases
- Entry header, used by parsers that iterate on entries
- Item type for entry scanning
- Mapper for bin hashes
- Hash mappers for all kinds of bin hashes