nom_derive/lib.rs
1//! # nom-derive
2//!
3//! [](./LICENSE-MIT)
4//! [](./LICENSE-APACHE)
5//! [](https://docs.rs/nom-derive)
6//! [](https://travis-ci.org/chifflier/nom-derive)
7//! [](https://crates.io/crates/nom-derive)
8//!
9//! ## Overview
10//!
11//! nom-derive is a custom derive attribute, to derive [nom] parsers automatically from the structure definition.
12//!
13//! It is not meant to replace [nom], but to provide a quick and easy way to generate parsers for
14//! structures, especially for simple structures. This crate aims at simplifying common cases.
15//! In some cases, writing the parser manually will remain more efficient.
16//!
17//! - [API documentation](https://docs.rs/nom-derive)
18//! - The [docs::Nom] pseudo-module. This is the main
19//! documentation for the `Nom` attribute, with all possible options and many examples.
20//!
21//! *Feedback welcome !*
22//!
23//! ## `#[derive(Nom)]`
24//!
25//! This crate exposes a single custom-derive macro `Nom` which
26//! implements `parse` for the struct it is applied to.
27//!
28//! The goal of this project is that:
29//!
30//! * `derive(Nom)` should be enough for you to derive [nom] parsers for simple
31//! structures easily, without having to write it manually
32//! * it allows overriding any parsing method by your own
33//! * it allows using generated parsing functions along with handwritten parsers and
34//! combining them without efforts
35//! * it remains as fast as nom
36//!
37//! `nom-derive` adds declarative parsing to `nom`. It also allows mixing with
38//! procedural parsing easily, making writing parsers for byte-encoded formats
39//! very easy.
40//!
41//! For example:
42//!
43//! ```rust
44//! use nom_derive::*;
45//!
46//! #[derive(Nom)]
47//! struct S {
48//! a: u32,
49//! b: u16,
50//! c: u16
51//! }
52//! ```
53//!
54//! This generates an implementation of the [`Parse`] trait to `S`. The generated code looks
55//! like (code simplified):
56//! ```rust,ignore
57//! impl<'a> Parse<&'a> for S {
58//! pub fn parse_be(i: &'a [u8]) -> nom::IResult(&'a [u8], S) {
59//! let (i, a) = be_u32(i)?;
60//! let (i, b) = be_u16(i)?;
61//! let (i, c) = be_u16(i)?;
62//! Ok((i, S{ a, b, c }))
63//! }
64//! pub fn parse_le(i: &'a [u8]) -> nom::IResult(&'a [u8], S) {
65//! let (i, a) = le_u32(i)?;
66//! let (i, b) = le_u16(i)?;
67//! let (i, c) = le_u16(i)?;
68//! Ok((i, S{ a, b, c }))
69//! }
70//! pub fn parse(i: &'a [u8]) -> nom::IResult(&'a [u8], S) {
71//! S::parse_be(i)
72//! }
73//! }
74//! ```
75//!
76//! To parse input, just call `let res = S::parse_be(input);`.
77//!
78//! If the endianness of the struct is fixed (for ex. using the top-level `BigEndian` or
79//! `LittleEndian` attributes, or the `NomBE` and `NomLE` custom derive), then the implementation
80//! always uses this endianness, and all 3 functions are equivalent.
81//!
82//! For extensive documentation of all attributes and examples, see the documentation of [docs::Nom]
83//! custom derive attribute.
84//!
85//! Many examples are provided, and more can be found in the [project
86//! tests](https://github.com/rust-bakery/nom-derive/tree/master/tests).
87//!
88//! ## Combinators visibility
89//!
90//! All inferred parsers will generate code with absolute type path, so there is no need
91//! to add `use` statements for them. However, if you use any combinator directly (or in a `Parse`
92//! statement, for ex.), it has to be imported as usual.
93//!
94//! That is probably not going to change, since
95//! * a proc_macro cannot export items other than functions tagged with `#[proc_macro_derive]`
96//! * there are variants of combinators with the same names (complete/streaming, bits/bytes), so
97//! re-exporting them would create side-effects.
98//!
99//! ## Debug tips
100//!
101//! * If the generated parser does not compile, add `#[nom(DebugDerive)]` to the structure.
102//! It will dump the generated parser to `stderr`.
103//! * If the generated parser fails at runtime, try adding `#[nom(Debug)]` to the structure or
104//! to fields. It wraps subparsers in `dbg_dmp` and will print the field name and input to
105//! `stderr` if the parser fails.
106//!
107//! [nom]: https://github.com/geal/nom
108
109pub mod docs;
110mod helpers;
111mod traits;
112
113pub use helpers::*;
114pub use traits::*;
115
116pub use nom;
117pub use nom_derive_impl::*;