Crate cdragon_prop

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:

• entry paths
• class names
• field names
• “bin hash” values.

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

data

Bin data definitions

visitor

Visit a nested bin value

Macros

binget

Helper to access nested bin values

binvalue_map_keytype

Same as binvalue_map_type!, but limited to types used a BinMap keys

binvalue_map_type

Map BinType variant to BinValue concrete type in an expression

Structs

BinEntry

Entry in a PROP file

BinEntryScanner

Scan entries from a bin file

BinHashKindMapping

Generic type to associate each kind of hash from bin files to a value

JsonSerializer

Serialize bin values to JSON

PropFile

PROP file, with entries

TextTreeSerializer

Serialize bin values to a human readable text tree

Enums

BinHashKind

Enum with a variant for each kind of bin hash

PropError

Error in a PROP file

Constants

NON_PROP_BASENAMES

Files known to not be PROP files, despite their extension

Traits

BinEntriesSerializer

Serialize streamed bin entries

BinSerializer

Serialize bin data

Functions

is_binfile_path

Return true if a path is a bin file path

Type Aliases

BinEntryHeader

Entry header, used by parsers that iterate on entries

BinEntryScannerItem

Item type for entry scanning

BinHashMapper

Mapper for bin hashes

BinHashMappers

Hash mappers for all kinds of bin hashes