binread_derive 2.1.0

Derive macro for binread
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

# binread_derive

## Quick start for adding a new directive to `BinRead`

In all cases, look to existing directives to follow established code and test
conventions.

1. Add a keyword for the new directive in `parser::keywords`.
2. Define the meta-type of the new directive in `parser::attrs`. If you need a
   new meta-type, add it to `parser::meta_types` along with tests.
3. If the new directive needs a special final type (e.g. `CondEndian`), add
   that to a new `parser::types` module and export it from `parser::types`. New
   types must ultimately implement `parser::TrySet`, but can sometimes do so
   more simply (using trait generic impls) by implementing `From` or `TryFrom`
   instead.
4. Add the new directive as a field to the relevant structs in
   `parser::top_level_attrs` and `parser::field_level_attrs`.
5. If the new directive combines with other directives in ways that may be
   invalid, and the relationship cannot be expressed using an enum type
   (e.g. `ReadMode`), add validation in either `FromInput::push_field` (if the
   validation can occur immediately after the field is constructed) or
   `FromInput::validate` (if it can only be validated after the entire struct
   has been parsed).
6. Use the new fields to emit code in the appropriate places in
   `codegen::read_options`.
7. Add new integration tests in the `binread` crate’s `tests` directory.
8. If the new directive generates new errors (e.g. from validation), add unit
   tests to validate those code paths in `parser::tests` (in `mod.rs`) and add
   identical trybuild tests to the `binread` crate’s `tests/ui` directory. (A
   nightly compiler is required to run the trybuild tests; see the comment in
   `binread::tests::ui` for more detail.)