1# Upgrading to nom 1.0 2 3The 1.0 release of nom is one of the biggest since the beginning of the project. Its goal was to rework some core parts to be more flexible, and clean code that was awkward or unclear. This resulted in breaking changes, that I hope will not happen again in the future (but hey, we are Rust developers, breaking changes are FUN for us!). 4 5Here are a few tips to update your code to run with nom 1.0: 6 7# Error typing 8 9`nom::Err` now depends on two generic types, the position `P` and the error type `E`: 10 11```rust 12pub enum Err<P,E=u32>{ 13 Code(ErrorKind<E>), 14 Node(ErrorKind<E>, Box<Err<P,E>>), 15 Position(ErrorKind<E>, P), 16 NodePosition(ErrorKind<E>, P, Box<Err<P,E>>) 17} 18``` 19 20The default error type is `u32` to keep some compatibility with older code. To update your code, the first step is to **replace all usages of `nom::ErrorCode` by `nom::ErrorKind`**. `ErrorKind` is now an enum that contains the same instances as the previous `ErrorCode`, with an additional generic parameter: 21 22```rust 23pub enum ErrorKind<E=u32> { 24 Custom(E), 25 Tag, 26 MapRes, 27 MapOpt, 28 Alt, 29 [...] 30} 31``` 32 33`ErrorKind::Custom` is where you will store your custom error type. Note that default nom parsers like `alphabetic` use `u32` as custom type, so you may need to translate the error types coming from those parsers like this: 34 35```rust 36fix_error!(CustomErrorType, alphabetic) 37``` 38 39Since the error type is now an enum instead of a `u32`, you can now **replace any `ErrorCode::Tag as u32` by `ErrorKind::Tag`**. 40 41# Lifetime elision 42 43The error type is now completely generic over the input type, so the lifetime that appeared in `IResult` is not necessary anymore. It changes function declarations like this: 44 45```rust 46fn parse_status<'a>(i: &'a [u8]) -> IResult<'a, &'a [u8], Status> 47 48// To this: 49fn parse_status(i: &[u8]) -> IResult<&[u8], Status> 50``` 51 52# Producers and consumers 53 54The old implementation was not flexible, and a bit slow (because of allocations). The new implementation can be driven more precisely outside of the consumer, step by step if needed, can return a result, has custom error types, and can combine consumers. You can see [an example in the repository](https://github.com/Geal/nom/blob/1.0/tests/omnom.rs#). 55 56# Changes around `Incomplete` 57 58* `chain!` will now count how much data has been consumed before a child parser returns `Incomplete`, and return an `Incomplete` with the added data size 59* an optional parser (in `opt!` or `chain!`) will return `Incomplete` if the child parser returned `Incomplete`, instead of stopping there. This is the correct behaviour, because the result will be the same if the data comes in chunks or complete from the start 60* `alt!` will now return `Incomplete` if one of its alternatives returns `Incomplete` instead of skipping to the next branch 61 62In the cases where you know that the data you get is complete, you can wrap a parser with `complete!`. This combinator will transform `Incomplete` in an `Error`. 63 64# Other changes 65 66`filter!` has been renamed to `take_while!` 67 68