nom-derive

Overview

nom-derive is a custom derive attribute, to derive nom parsers automatically from the structure definition.

It is not meant to replace nom, but to provide a quick and easy way to generate parsers for structures, especially for simple structures. This crate aims at simplifying common cases. In some cases, writing the parser manually will remain more efficient.

• API documentation
• Documentation of Nom attribute. This is the main documentation for this crate, with all possible options and many examples.

This is only test code for now. Feedback welcome !

#[derive(Nom)]

This crate exposes a single custom-derive macro Nom which implements parse for the struct it is applied to.

The goal of this project is that:

• derive(Nom) should be enough for you to derive nom parsers for simple structures easily, without having to write it manually
• it allows overriding any parsing method by your own
• it allows using generated parsing functions along with handwritten parsers and combining them without efforts

Changes

0.5.0

• Upgrade to nom 5.0
• The parse method is now public
• Upgrade dependencies (syn, quote, proc-macro2)

0.4.0

• Add support for Enum parser generator
  • Enums require a selector to choose the variant
  • Fieldless enums (list of constants) are handled as a special case
• Add NomDeriveDebug attribute to display generated parser on stderr during build

0.3.0

• Move crate to rust-bakery github project
• Add Count attribute

Usage

Add to your Cargo.toml file::

 nom-derive = "0.3"
 nom = "4.2"

Add #[derive(Nom)] to the structure(s) you want.

See the tests directory for examples.

Example

This implementation:

#[macro_use]
extern crate nom_derive;

#[macro_use]
extern crate nom;

use nom::*;

#[derive(Nom)]
struct SimpleStruct {
    pub a: u32,
    b: u64,
}

Allows you to generate the nom parser for SimpleStruct automatically. The function is called SimpleStruct::parse.

The generated code is equivalent to::

impl SimpleStruct {
    fn parse(i: &[u8]) -> IResult<&[u8],SimpleStruct> {
        do_parse!(
            i,
            a: be_u32 >>
            b: be_u64 >>
            ( SimpleStruct{ a,b } )
        )
    }
}

See the API documentation for more examples.

Limitations

• Debugging macros is hard. Debugging macros generated by a custom derive is a nightmare.
  • Try replacing the Nom attribute with the NomDeriveDebug attribute. It has exactly the same syntax, but will print the generated parser on stderr.
  • The expand cargo subcommand can help

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.