openharmony/third_party_rust_nom
1
0
Fork 0
mirror of https://gitee.com/openharmony/third_party_rust_nom synced 2024-11-26 17:20:29 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Fixing a lot of minor issues & inconsistencies in the documentation (#1143)

Browse Source
This commit is contained in:
nnt 2020-05-30 11:53:44 +02:00 committed by GitHub
parent 974233f2e8
commit 4a95dfa532
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
38 changed files with 744 additions and 825 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

54
README.md
View File

@ -75,7 +75,7 @@ fn parse_color() {
- [Reference documentation](https://docs.rs/nom)
- [Various design documents and tutorials](https://github.com/Geal/nom/tree/master/doc)
- [list of combinators and their behaviour](https://github.com/Geal/nom/blob/master/doc/choosing_a_combinator.md)
- [List of combinators and their behaviour](https://github.com/Geal/nom/blob/master/doc/choosing_a_combinator.md)
If you need any help developing your parsers, please ping `geal` on IRC (freenode, geeknode, oftc), go to `#nom-parsers` on Freenode IRC, or on the [Gitter chat room](https://gitter.im/Geal/nom).
@ -83,16 +83,16 @@ If you need any help developing your parsers, please ping `geal` on IRC (freenod
If you want to write:
### binary format parsers
### Binary format parsers
nom was designed to properly parse binary formats from the beginning. Compared
to the usual handwritten C parsers, nom parsers are just as fast, free from
buffer overflow vulnerabilities, and handle common patterns for you:
- [TLV](https://en.wikipedia.org/wiki/Type-length-value)
- bit level parsing
- hexadecimal viewer in the debugging macros for easy data analysis
- streaming parsers for network formats and huge files
- Bit level parsing
- Hexadecimal viewer in the debugging macros for easy data analysis
- Streaming parsers for network formats and huge files
Example projects:
@ -106,10 +106,10 @@ While nom was made for binary format at first, it soon grew to work just as
well with text formats. From line based formats like CSV, to more complex, nested
formats such as JSON, nom can manage it, and provides you with useful tools:
- fast case insensitive comparison
- recognizers for escaped strings
- regular expressions can be embedded in nom parsers to represent complex character patterns succinctly
- special care has been given to managing non ASCII characters properly
- Fast case insensitive comparison
- Recognizers for escaped strings
- Regular expressions can be embedded in nom parsers to represent complex character patterns succinctly
- Special care has been given to managing non ASCII characters properly
Example projects:
@ -139,7 +139,7 @@ Example projects:
While a lot of formats (and the code handling them) assume that they can fit
the complete data in memory, there are formats for which we only get a part
of the data at once, like network formats, or huge files.
nom has been designed for a correct behaviour with partial data: if there is
nom has been designed for a correct behaviour with partial data: If there is
not enough data to decide, nom will tell you it needs more instead of silently
returning a wrong result. Whether your data comes entirely or in chunks, the
result should be the same.
@ -149,7 +149,7 @@ It allows you to build powerful, deterministic state machines for your protocols
Example projects:
- [HTTP proxy](https://github.com/sozu-proxy/sozu/blob/master/lib/src/protocol/http/parser.rs)
- [using nom with generators](https://github.com/Geal/generator_nom)
- [Using nom with generators](https://github.com/Geal/generator_nom)
## Parser combinators
@ -165,24 +165,24 @@ written with other parser approaches.
This has a few advantages:
- the parsers are small and easy to write
- the parsers components are easy to reuse (if they're general enough, please add them to nom!)
- the parsers components are easy to test separately (unit tests and property-based tests)
- the parser combination code looks close to the grammar you would have written
- you can build partial parsers, specific to the data you need at the moment, and ignore the rest
- The parsers are small and easy to write
- The parsers components are easy to reuse (if they're general enough, please add them to nom!)
- The parsers components are easy to test separately (unit tests and property-based tests)
- The parser combination code looks close to the grammar you would have written
- You can build partial parsers, specific to the data you need at the moment, and ignore the rest
## Technical features
nom parsers are for:
- [x] **byte-oriented**: the basic type is `&[u8]` and parsers will work as much as possible on byte array slices (but are not limited to them)
- [x] **byte-oriented**: The basic type is `&[u8]` and parsers will work as much as possible on byte array slices (but are not limited to them)
- [x] **bit-oriented**: nom can address a byte slice as a bit stream
- [x] **string-oriented**: the same kind of combinators can apply on UTF-8 strings as well
- [x] **zero-copy**: if a parser returns a subset of its input data, it will return a slice of that input, without copying
- [x] **string-oriented**: The same kind of combinators can apply on UTF-8 strings as well
- [x] **zero-copy**: If a parser returns a subset of its input data, it will return a slice of that input, without copying
- [x] **streaming**: nom can work on partial data and detect when it needs more data to produce a correct result
- [x] **descriptive errors**: the parsers can aggregate a list of error codes with pointers to the incriminated input slice. Those error lists can be pattern matched to provide useful messages.
- [x] **custom error types**: you can provide a specific type to improve errors returned by parsers
- [x] **descriptive errors**: The parsers can aggregate a list of error codes with pointers to the incriminated input slice. Those error lists can be pattern matched to provide useful messages.
- [x] **custom error types**: You can provide a specific type to improve errors returned by parsers
- [x] **safe parsing**: nom leverages Rust's safe memory handling and powerful types, and parsers are routinely fuzzed and tested with real world data. So far, the only flaws found by fuzzing were in code written outside of nom
- [x] **speed**: benchmarks have shown that nom parsers often outperform many parser combinators library like Parsec and attoparsec, some regular expression engines and even handwritten C parsers
- [x] **speed**: Benchmarks have shown that nom parsers often outperform many parser combinators library like Parsec and attoparsec, some regular expression engines and even handwritten C parsers
Some benchmarks are available on [Github](https://github.com/Geal/nom_benchmarks).
@ -209,15 +209,15 @@ Then include it in your code like this:
extern crate nom;
```
**NOTE: if you have existing code using nom below the 5.0 version, please take a look
**NOTE: If you have existing code using nom below the 5.0 version, please take a look
at the [upgrade documentation](https://github.com/Geal/nom/blob/master/doc/upgrading_to_nom_5.md)
to handle the breaking changes.**
There are a few compilation features:
* `std`: (activated by default) if disabled, nom can work in `no_std` builds
* `regexp`: enables regular expression parsers with the `regex` crate
* `regexp_macros`: enables regular expression parsers with the `regex` and `regex_macros` crates. Regular expressions can be defined at compile time, but it requires a nightly version of rustc
* `regexp`: Enables regular expression parsers with the `regex` crate
* `regexp_macros`: Enables regular expression parsers with the `regex` and `regex_macros` crates. Regular expressions can be defined at compile time, but it requires a nightly version of rustc
You can activate those features like this:
@ -229,8 +229,8 @@ features = ["regexp"]
# Related projects
- [get line and column info in nom's input type](https://github.com/fflorent/nom_locate)
- [using nom as lexer and parser](https://github.com/Rydgel/monkey-rust)
- [Get line and column info in nom's input type](https://github.com/fflorent/nom_locate)
- [Using nom as lexer and parser](https://github.com/Rydgel/monkey-rust)
# Parsers written with nom

1
doc/FAQ.md
View File

@ -9,4 +9,3 @@ named!(multi<Vec<&str>>, many0!( map_res!(tag!( "abcd" ), str::from_utf8) ) );
```
This happens because the macro processor mistakes `>>` for an operator. It will work correctly by adding a space, like this: `named!(multi< Vec<&str> >, ...`

169
doc/choosing_a_combinator.md
View File

@ -1,6 +1,6 @@
# List of macros parsers and combinators
**note**: this list is meant to provide a nicer way to find a nom macros than reading through the
**Note**: this list is meant to provide a nicer way to find a nom macros than reading through the
documentation on docs.rs, since rustdoc puts all the macros at the top level. Function combinators
are organized in module so they are a bit easier to find.
@ -10,129 +10,128 @@ Those are used to recognize the lowest level elements of your grammar, like, "he
| combinator | usage | input | output | comment |
|---|---|---|---|---|
| [char](https://docs.rs/nom/latest/nom/macro.char.html) | `char!('a')` | `"abc"` | `Ok(("bc", 'a'))`| matches one character (works with non ASCII chars too) |
| [is_a](https://docs.rs/nom/latest/nom/macro.is_a.html) | ` is_a!("ab")` | `"ababc"` | `Ok(("c", "abab"))`|matches a sequence of any of the characters passed as arguments|
| [is_not](https://docs.rs/nom/latest/nom/macro.is_not.html) |`is_not!("cd")` | `"ababc"` | `Ok(("c", "abab"))`|matches a sequence of none of the characters passed as arguments|
| [one_of](https://docs.rs/nom/latest/nom/macro.one_of.html) |`one_of!("abc")` | `"abc"` | `Ok(("bc", 'a'))`|matches one of the provided characters (works with non ASCII characters too)|
| [none_of](https://docs.rs/nom/latest/nom/macro.none_of.html) |`none_of!("abc")` | `"xyab"` | `Ok(("yab", 'x'))`|matches anything but the provided characters|
| [tag](https://docs.rs/nom/latest/nom/macro.tag.html) |`tag!("hello")` | `"hello world"` | `Ok((" world", "hello"))`|recognizes a specific suite of characters or bytes|
| [tag_no_case](https://docs.rs/nom/latest/nom/macro.tag_no_case.html) |`tag_no_case!("hello")` | `"HeLLo World"` | `Ok((" World", "HeLLo"))`|case insensitive comparison. Note that case insensitive comparison is not well defined for unicode, and that you might have bad surprises|
| [take](https://docs.rs/nom/latest/nom/macro.take.html) |`take!(4)` | `"hello"` | `Ok(("o", "hell"))`|takes a specific number of bytes or characters|
| [take_while](https://docs.rs/nom/latest/nom/macro.take_while.html) |`take_while!(is_alphabetic)` | `"abc123"` | `Ok(("123", "abc"))`| returns the longest list of bytes for which the provided function returns true. `take_while1` does the same, but must return at least one character|
| [take_till](https://docs.rs/nom/latest/nom/macro.take_till.html) |`take_till!(is_alphabetic)` | `"123abc"` | `Ok(("abc", "123"))`|returns the longest list of bytes or characters until the provided function returns true. `take_till1` does the same, but must return at least one character. This is the reverse behaviour from `take_while`: `take_till!(f)` is equivalent to `take_while!(|c| !f(c))`|
| [take_until](https://docs.rs/nom/latest/nom/macro.take_until.html) | `take_until!("world")` | `"Hello world"` | `Ok(("world", "Hello "))`|returns the longest list of bytes or characters until the provided tag is found. `take_until1` does the same, but must return at least one character|
| [char](https://docs.rs/nom/latest/nom/macro.char.html) | `char!('a')` | `"abc"` | `Ok(("bc", 'a'))` |Matches one character (works with non ASCII chars too) |
| [is_a](https://docs.rs/nom/latest/nom/macro.is_a.html) | ` is_a!("ab")` | `"ababc"` | `Ok(("c", "abab"))` |Matches a sequence of any of the characters passed as arguments|
| [is_not](https://docs.rs/nom/latest/nom/macro.is_not.html) | `is_not!("cd")` | `"ababc"` | `Ok(("c", "abab"))` |Matches a sequence of none of the characters passed as arguments|
| [one_of](https://docs.rs/nom/latest/nom/macro.one_of.html) | `one_of!("abc")` | `"abc"` | `Ok(("bc", 'a'))` |Matches one of the provided characters (works with non ASCII characters too)|
| [none_of](https://docs.rs/nom/latest/nom/macro.none_of.html) | `none_of!("abc")` | `"xyab"` | `Ok(("yab", 'x'))` |Matches anything but the provided characters|
| [tag](https://docs.rs/nom/latest/nom/macro.tag.html) | `tag!("hello")` | `"hello world"` | `Ok((" world", "hello"))` |Recognizes a specific suite of characters or bytes|
| [tag_no_case](https://docs.rs/nom/latest/nom/macro.tag_no_case.html) | `tag_no_case!("hello")` | `"HeLLo World"` | `Ok((" World", "HeLLo"))` |Case insensitive comparison. Note that case insensitive comparison is not well defined for unicode, and that you might have bad surprises|
| [take](https://docs.rs/nom/latest/nom/macro.take.html) | `take!(4)` | `"hello"` | `Ok(("o", "hell"))` |Takes a specific number of bytes or characters|
| [take_while](https://docs.rs/nom/latest/nom/macro.take_while.html) | `take_while!(is_alphabetic)` | `"abc123"` | `Ok(("123", "abc"))` |Returns the longest list of bytes for which the provided function returns true. `take_while1` does the same, but must return at least one character|
| [take_till](https://docs.rs/nom/latest/nom/macro.take_till.html) | `take_till!(is_alphabetic)` | `"123abc"` | `Ok(("abc", "123"))` |Returns the longest list of bytes or characters until the provided function returns true. `take_till1` does the same, but must return at least one character. This is the reverse behaviour from `take_while`: `take_till!(f)` is equivalent to `take_while!(\|c\| !f(c))`|
| [take_until](https://docs.rs/nom/latest/nom/macro.take_until.html) | `take_until!("world")` | `"Hello world"` | `Ok(("world", "Hello "))` |Returns the longest list of bytes or characters until the provided tag is found. `take_until1` does the same, but must return at least one character|
## Choice combinators
| combinator | usage | input | output | comment |
|---|---|---|---|---|
| [alt](https://docs.rs/nom/latest/nom/macro.alt.html) |`alt!(tag!("ab") \| tag!("cd"))` | `"cdef"` | `Ok( ("ef", "cd") )`|try a list of parsers and return the result of the first successful one|
| [switch](https://docs.rs/nom/latest/nom/macro.switch.html) |`switch!(take!(2), "ab" => tag!("XYZ") \| "cd" => tag!("123"))` | `"cd1234"` | `Ok(("4", "123"))`|choose the next parser depending on the result of the first one, if successful, and returns the result of the second parser|
| [permutation](https://docs.rs/nom/latest/nom/macro.permutation.html) | `permutation!(tag!("ab"), tag!("cd"), tag!("12"))` | `"cd12abc"` | `Ok( ("c", ("ab", "cd", "12") )`|succeeds when all its child parser have succeeded, whatever the order|
| [alt](https://docs.rs/nom/latest/nom/macro.alt.html) | `alt!(tag!("ab") \| tag!("cd"))` | `"cdef"` | `Ok(("ef", "cd"))` |Try a list of parsers and return the result of the first successful one|
| [switch](https://docs.rs/nom/latest/nom/macro.switch.html) | `switch!(take!(2), "ab" => tag!("XYZ") \| "cd" => tag!("123"))` | `"cd1234"` | `Ok(("4", "123"))` |Choose the next parser depending on the result of the first one, if successful, and returns the result of the second parser|
| [permutation](https://docs.rs/nom/latest/nom/macro.permutation.html) | `permutation!(tag!("ab"), tag!("cd"), tag!("12"))` | `"cd12abc"` | `Ok(("c", ("ab", "cd", "12"))` |Succeeds when all its child parser have succeeded, whatever the order|
## Sequence combinators
| combinator | usage | input | output | comment |
|---|---|---|---|---|
| [delimited](https://docs.rs/nom/latest/nom/macro.delimited.html) |`delimited!(char!('('), take!(2), char!(')'))` | `"(ab)cd"` | `Ok( ("cd", "ab") )`||
| [preceded](https://docs.rs/nom/latest/nom/macro.preceded.html) |`preceded!(tag!("ab"), tag!("XY"))` | `"abXYZ"` | `Ok( ("Z", "XY") )`||
| [terminated](https://docs.rs/nom/latest/nom/macro.terminated.html) |`terminated!(tag!("ab"), tag!("XY"))` | `"abXYZ"` | `Ok( ("Z", "ab") )`||
| [pair](https://docs.rs/nom/latest/nom/macro.pair.html) |`pair!(tag!("ab"), tag!("XY"))` | `"abXYZ"` | `Ok( ("Z", ("ab", "XY")) )`||
| [separated_pair](https://docs.rs/nom/latest/nom/macro.separated_pair.html) |`separated_pair!(tag!("hello"), char!(','), tag!("world"))` | `"hello,world!"` | `Ok( ("!", ("hello", "world")) )`||
| [tuple](https://docs.rs/nom/latest/nom/macro.tuple.html) |`tuple!(tag!("ab"), tag!("XY"), take!(1))` | `"abXYZ!"` | `Ok( ("!", ("ab", "XY", "Z")) )`|chains parsers and assemble the sub results in a tuple. You can use as many child parsers as you can put elements in a tuple|
| [do_parse](https://docs.rs/nom/latest/nom/macro.do_parse.html) |`do_parse!(tag: take!(2) >> length: be_u8 >> data: take!(length) >> (Buffer { tag: tag, data: data}) )` | `&[0, 0, 3, 1, 2, 3][..]` | `Buffer { tag: &[0, 0][..], data: &[1, 2, 3][..] }`|`do_parse` applies sub parsers in a sequence. it can store intermediary results and make them available for later parsers|
| [delimited](https://docs.rs/nom/latest/nom/macro.delimited.html) | `delimited!(char!('('), take!(2), char!(')'))` | `"(ab)cd"` | `Ok(("cd", "ab"))` ||
| [preceded](https://docs.rs/nom/latest/nom/macro.preceded.html) | `preceded!(tag!("ab"), tag!("XY"))` | `"abXYZ"` | `Ok(("Z", "XY"))` ||
| [terminated](https://docs.rs/nom/latest/nom/macro.terminated.html) | `terminated!(tag!("ab"), tag!("XY"))` | `"abXYZ"` | `Ok(("Z", "ab"))` ||
| [pair](https://docs.rs/nom/latest/nom/macro.pair.html) | `pair!(tag!("ab"), tag!("XY"))` | `"abXYZ"` | `Ok(("Z", ("ab", "XY")))` ||
| [separated_pair](https://docs.rs/nom/latest/nom/macro.separated_pair.html) | `separated_pair!(tag!("hello"), char!(','), tag!("world"))` | `"hello,world!"` | `Ok(("!", ("hello", "world")))` ||
| [tuple](https://docs.rs/nom/latest/nom/macro.tuple.html) | `tuple!(tag!("ab"), tag!("XY"), take!(1))` | `"abXYZ!"` | `Ok(("!", ("ab", "XY", "Z")))` |Chains parsers and assemble the sub results in a tuple. You can use as many child parsers as you can put elements in a tuple|
| [do_parse](https://docs.rs/nom/latest/nom/macro.do_parse.html) | `do_parse!(tag: take!(2) >> length: be_u8 >> data: take!(length) >> (Buffer { tag: tag, data: data}) )` | `&[0, 0, 3, 1, 2, 3][..]` | `Buffer { tag: &[0, 0][..], data: &[1, 2, 3][..] }` |`do_parse` applies sub parsers in a sequence. It can store intermediary results and make them available for later parsers|
## Applying a parser multiple times
| combinator | usage | input | output | comment |
|---|---|---|---|---|
| [count](https://docs.rs/nom/latest/nom/macro.count.html) |`count!(take!(2), 3)` | `"abcdefgh"` | `Ok( ("gh", vec!("ab", "cd", "ef")) )`|applies the child parser a specified number of times|
| [many0](https://docs.rs/nom/latest/nom/macro.many0.html) |`many0!(tag!("ab"))` | `"abababc"` | `Ok( ("c", vec!("ab", "ab", "ab")) )`|Applies the parser 0 or more times and returns the list of results in a Vec. `many1` does the same operation but must return at least one element|
| [many_m_n](https://docs.rs/nom/latest/nom/macro.many_m_n.html) |`many_m_n!(1, 3, tag!("ab"))` | `"ababc"` | `Ok( ("c", vec!("ab", "ab")) )`|applies the parser between m and n times (n included) and returns the list of results in a Vec|
| [many_till](https://docs.rs/nom/latest/nom/macro.many_till.html) |`many_till!( tag!( "ab" ), tag!( "ef" ) )` | `"ababefg"` | `Ok( ("g", (vec!("ab", "ab"), "ef")) )`|Applies the first parser until the second applies. Returns a tuple containing the list of results from the first in a Vec and the result of the second.|
| [separated_list](https://docs.rs/nom/latest/nom/macro.separated_list.html) |`separated_list!(tag!(","), tag!("ab"))` | `"ab,ab,ab."` | `Ok( (".", vec!("ab", "ab", "ab")) )`|`separated_nonempty_list` works like `separated_list` but must returns at least one element|
| [fold_many0](https://docs.rs/nom/latest/nom/macro.fold_many0.html) |`fold_many0!(be_u8, 0, \|acc, item\| acc + item)` | `[1, 2, 3]` | `Ok( ([], 6) )`|applies the parser 0 or more times and folds the list of return values. The `fold_many1` version must apply the child parser at least one time|
| [fold_many_m_n](https://docs.rs/nom/latest/nom/macro.fold_many_m_n.html) |`fold_many_m_n!(1, 2, be_u8, 0, \|acc, item\| acc + item)` | `[1, 2, 3]` | `Ok( ([3], 3))`|applies the parser between m and n times (n included) and folds the list of return value|
| [length_count](https://docs.rs/nom/latest/nom/macro.length_count.html) |`length_count!(number, tag!("ab"))` | `"2ababab"` | `Ok( ("ab", vec!("ab", "ab")) )`|gets a number from the first parser, then applies the second parser that many times|
| [count](https://docs.rs/nom/latest/nom/macro.count.html) | `count!(take!(2), 3)` | `"abcdefgh"` | `Ok(("gh", vec!("ab", "cd", "ef")))` |Applies the child parser a specified number of times|
| [many0](https://docs.rs/nom/latest/nom/macro.many0.html) | `many0!(tag!("ab"))` | `"abababc"` | `Ok(("c", vec!("ab", "ab", "ab")))` |Applies the parser 0 or more times and returns the list of results in a Vec. `many1` does the same operation but must return at least one element|
| [many_m_n](https://docs.rs/nom/latest/nom/macro.many_m_n.html) | `many_m_n!(1, 3, tag!("ab"))` | `"ababc"` | `Ok(("c", vec!("ab", "ab")))` |Applies the parser between m and n times (n included) and returns the list of results in a Vec|
| [many_till](https://docs.rs/nom/latest/nom/macro.many_till.html) | `many_till!(tag!( "ab" ), tag!( "ef" ))` | `"ababefg"` | `Ok(("g", (vec!("ab", "ab"), "ef")))` |Applies the first parser until the second applies. Returns a tuple containing the list of results from the first in a Vec and the result of the second|
| [separated_list](https://docs.rs/nom/latest/nom/macro.separated_list.html) | `separated_list!(tag!(","), tag!("ab"))` | `"ab,ab,ab."` | `Ok((".", vec!("ab", "ab", "ab")))` |`separated_nonempty_list` works like `separated_list` but must returns at least one element|
| [fold_many0](https://docs.rs/nom/latest/nom/macro.fold_many0.html) | `fold_many0!(be_u8, 0, \|acc, item\| acc + item)` | `[1, 2, 3]` | `Ok(([], 6))` |Applies the parser 0 or more times and folds the list of return values. The `fold_many1` version must apply the child parser at least one time|
| [fold_many_m_n](https://docs.rs/nom/latest/nom/macro.fold_many_m_n.html) | `fold_many_m_n!(1, 2, be_u8, 0, \|acc, item\| acc + item)` | `[1, 2, 3]` | `Ok(([3], 3))` |Applies the parser between m and n times (n included) and folds the list of return value|
| [length_count](https://docs.rs/nom/latest/nom/macro.length_count.html) | `length_count!(number, tag!("ab"))` | `"2ababab"` | `Ok(("ab", vec!("ab", "ab")))` |Gets a number from the first parser, then applies the second parser that many times|
## Integers
Parsing integers from binary formats can be done in two ways: with parser functions, or combinators with configurable endianness:
Parsing integers from binary formats can be done in two ways: With parser functions, or combinators with configurable endianness:
- **configurable endianness:** `i16!`, `i32!`, `i64!`, `u16!`, `u32!`, `u64!` are combinators that take as argument a `nom::Endianness`, like this: `i16!(endianness)`. If the parameter is `nom::Endianness::Big`, parse a big endian `i16` integer, otherwise a little endian `i16` integer.
- **fixed endianness**: the functions are prefixed by `be_` for big endian numbers, and by `le_` for little endian numbers, and the suffix is the type they parse to. As an example, `be_u32` parses a big endian unsigned integer stored in 32 bits.
- `be_f32`, `be_f64`, `le_f32`, `le_f64`: recognize floating point numbers
- `be_i8`, `be_i16`, `be_i32`, `be_i24`, `be_i32`, `be_i64`: big endian signed integers
- `be_u8`, `be_u16`, `be_u32`, `be_u24`, `be_u32`, `be_u64`: big endian unsigned integers
- `le_i8`, `le_i16`, `le_i32`, `le_i24`, `le_i32`, `le_i64`: little endian signed integers
- `le_u8`, `le_u16`, `le_u32`, `le_u24`, `le_u32`, `le_u64`: little endian unsigned integers
- **fixed endianness**: The functions are prefixed by `be_` for big endian numbers, and by `le_` for little endian numbers, and the suffix is the type they parse to. As an example, `be_u32` parses a big endian unsigned integer stored in 32 bits.
- `be_f32`, `be_f64`, `le_f32`, `le_f64`: Recognize floating point numbers
- `be_i8`, `be_i16`, `be_i24`, `be_i32`, `be_i64`: Big endian signed integers
- `be_u8`, `be_u16`, `be_u24`, `be_u32`, `be_u64`: Big endian unsigned integers
- `le_i8`, `le_i16`, `le_i24`, `le_i32`, `le_i64`: Little endian signed integers
- `le_u8`, `le_u16`, `le_u24`, `le_u32`, `le_u64`: Little endian unsigned integers
## Streaming related
- `eof!`: returns its input if it is at the end of input data
- `complete!`: replaces an `Incomplete` returned by the child parser with an `Error`
- `eof!`: Returns its input if it is at the end of input data
- `complete!`: Replaces an `Incomplete` returned by the child parser with an `Error`
## Modifiers
- `cond!`: conditional combinator. Wraps another parser and calls it if the condition is met.
- `flat_map!`:
- `map!`: maps a function on the result of a parser
- `map_opt!`: maps a function returning an `Option` on the output of a parser
- `map_res!`: maps a function returning a `Result` on the output of a parser
- `not!`: returns a result only if the embedded parser returns `Error` or `Incomplete`. Does not consume the input.
- `opt!`: make the underlying parser optional
- `opt_res!`: make the underlying parser optional
- `parse_to!`: uses the parse method from `std::str::FromStr` to convert the current input to the specified type
- `peek!`: returns a result without consuming the input
- `recognize!`: if the child parser was successful, return the consumed input as the produced value
- `return_error!`: prevents backtracking if the child parser fails
- `tap!`: allows access to the parser's result without affecting it
- `verify!`: returns the result of the child parser if it satisfies a verification function
- `cond!`: Conditional combinator. Wraps another parser and calls it if the condition is met
- `flat_map!`:
- `map!`: Maps a function on the result of a parser
- `map_opt!`: Maps a function returning an `Option` on the output of a parser
- `map_res!`: Maps a function returning a `Result` on the output of a parser
- `not!`: Returns a result only if the embedded parser returns `Error` or `Incomplete`. Does not consume the input
- `opt!`: Make the underlying parser optional
- `opt_res!`: Make the underlying parser optional
- `parse_to!`: Uses the parse method from `std::str::FromStr` to convert the current input to the specified type
- `peek!`: Returns a result without consuming the input
- `recognize!`: If the child parser was successful, return the consumed input as the produced value
- `return_error!`: Prevents backtracking if the child parser fails
- `tap!`: Allows access to the parser's result without affecting it
- `verify!`: Returns the result of the child parser if it satisfies a verification function
## Error management and debugging
- `add_return_error!`: Add an error if the child parser fails
- `dbg!`: Prints a message if the parser fails
- `dbg_dmp!`: Prints a message and the input if the parser fails
- `error_node_position!`: creates a parse error from a `nom::ErrorKind`, the position in the input and the next error in the parsing tree. If the `verbose-errors` feature is not activated, it defaults to only the error code
- `error_position!`: creates a parse error from a `nom::ErrorKind` and the position in the input. If the `verbose-errors` feature is not activated, it defaults to only the error code.
- `fix_error!`: translate parser result from `IResult` to `IResult` with a custom type
- `error_node_position!`: Creates a parse error from a `nom::ErrorKind`, the position in the input and the next error in the parsing tree. If the `verbose-errors` feature is not activated, it defaults to only the error code
- `error_position!`: Creates a parse error from a `nom::ErrorKind` and the position in the input. If the `verbose-errors` feature is not activated, it defaults to only the error code
- `fix_error!`: Translate parser result from `IResult` to `IResult` with a custom type
## Text parsing
- `escaped!`: matches a byte string with escaped characters.
- `escaped_transform!`: matches a byte string with escaped characters, and returns a new string with the escaped characters replaced
- `escaped!`: Matches a byte string with escaped characters
- `escaped_transform!`: Matches a byte string with escaped characters, and returns a new string with the escaped characters replaced
## Binary format parsing
- `length_data!`: gets a number from the first parser, then takes a subslice of the input of that size, and returns that subslice
- `length_bytes!`: alias for length_data
- `length_value!`: gets a number from the first parser, takes a subslice of the input of that size, then applies the second parser on that subslice. If the second parser returns `Incomplete`, `length_value!` will return an error
- `length_data!`: Gets a number from the first parser, then takes a subslice of the input of that size, and returns that subslice
- `length_bytes!`: Alias for length_data
- `length_value!`: Gets a number from the first parser, takes a subslice of the input of that size, then applies the second parser on that subslice. If the second parser returns `Incomplete`, `length_value!` will return an error
## Bit stream parsing
- `bits!`: transforms the current input type (byte slice `&[u8]`) to a bit stream on which bit specific parsers and more general combinators can be applied
- `bytes!`: transforms its bits stream input back into a byte slice for the underlying parsers.
- `tag_bits!`: matches an integer pattern to a bitstream. The number of bits of the input to compare must be specified
- `take_bits!`: generates a parser consuming the specified number of bits
- `bits!`: Transforms the current input type (byte slice `&[u8]`) to a bit stream on which bit specific parsers and more general combinators can be applied
- `bytes!`: Transforms its bits stream input back into a byte slice for the underlying parser
- `tag_bits!`: Matches an integer pattern to a bitstream. The number of bits of the input to compare must be specified
- `take_bits!`: Generates a parser consuming the specified number of bits
Whitespace delimited formats parsing
## Whitespace delimited formats parsing
- `eat_separator!`: helper macro to build a separator parser
- `sep!`: parser rewriting macro for whitespace separated formats
- `wrap_sep!`:
- `ws!`: consumes whitespace characters, i.e. the `\s` regex pattern
- `eat_separator!`: Helper macro to build a separator parser
- `sep!`: Parser rewriting macro for whitespace separated formats
- `wrap_sep!`:
- `ws!`: Consumes whitespace characters, i.e. the `\s` regex pattern
## Remaining combinators
- `apply!`: emulate function currying: `apply!(my_function, arg1, arg2, ...)` becomes `my_function(input, arg1, arg2, ...)`
- `apply!`: Emulate function currying: `apply!(my_function, arg1, arg2, ...)` becomes `my_function(input, arg1, arg2, ...)`
- `call!`: Used to wrap common expressions and function as macros
- `method!`: Makes a method from a parser combination
- `named!`: Makes a function from a parser combination
- `named_args!`: Makes a function from a parser combination with arguments.
- `named_attr!`: Makes a function from a parser combination, with attributes
- `try_parse!`: A bit like `std::try!`, this macro will return the remaining input and parsed value if the child parser returned `Ok`, and will do an early return for `Error` and `Incomplete`. This can provide more flexibility than `do_parse!` if needed.
- `named_args!`: Makes a function from a parser combination with arguments
- `named_attr!`: Makes a function from a parser combination with attributes
- `try_parse!`: A bit like `std::try!`, this macro will return the remaining input and parsed value if the child parser returned `Ok` and will do an early return for `Error` and `Incomplete`. This can provide more flexibility than `do_parse!` if needed
## Character test functions
@ -143,15 +142,15 @@ Use these functions with a combinator like `take_while!`:
- `is_digit`: Tests if byte is ASCII digit: `[0-9]`
- `is_hex_digit`: Tests if byte is ASCII hex digit: `[0-9A-Fa-f]`
- `is_oct_digit`: Tests if byte is ASCII octal digit: `[0-7]`
- `is_space`: Tests if byte is ASCII space or tab
- `is_space`: Tests if byte is ASCII space or tab: `[ \t]`
- `alpha`: Recognizes one or more lowercase and uppercase alphabetic characters: `[a-zA-Z]`
- `alphanumeric`: Recognizes one or more numerical and alphabetic characters: `[0-9a-zA-Z]`
- `anychar`:
- `begin`:
- `crlf`:
- `anychar`:
- `begin`:
- `crlf`:
- `digit`: Recognizes one or more numerical characters: `[0-9]`
- `double`: Recognizes floating point number in a byte string and returns a `f64`
- `eol`:
- `eol`:
- `float`: Recognizes floating point number in a byte string and returns a `f32`
- `hex_digit`: Recognizes one or more hexadecimal numerical characters: `[0-9A-Fa-f]`
- `hex_u32`: Recognizes a hex-encoded integer
@ -159,10 +158,10 @@ Use these functions with a combinator like `take_while!`:
- `multispace`: Recognizes one or more spaces, tabs, carriage returns and line feeds
- `newline`: Matches a newline character `\n`
- `non_empty`: Recognizes non empty buffers
- `not_line_ending`:
- `not_line_ending`:
- `oct_digit`: Recognizes one or more octal characters: `[0-7]`
- `rest`: Return the remaining input.
- `shift`:
- `sized_buffer`:
- `rest`: Return the remaining input
- `shift`:
- `sized_buffer`:
- `space`: Recognizes one or more spaces and tabs
- `tab`: Matches a tab character `\t`

26
doc/custom_input_types.md
View File

@ -23,21 +23,21 @@ Here are the traits we have to implement for `MyInput`:
| trait | usage |
|---|---|
| [AsBytes](https://docs.rs/nom/latest/nom/trait.AsBytes.html) | casts the input type to a byte slice |
| [Compare](https://docs.rs/nom/latest/nom/trait.Compare.html) | character comparison operations |
| [ExtendInto](https://docs.rs/nom/latest/nom/trait.ExtendInto.html) |abstracts something which can extend an Extend |
| [FindSubstring](https://docs.rs/nom/latest/nom/trait.FindSubstring.html) | look for a substring in self |
| [FindToken](https://docs.rs/nom/latest/nom/trait.FindToken.html) |look for self in the given input stream |
| [InputIter](https://docs.rs/nom/latest/nom/trait.InputIter.html) | common iteration operations on the input type |
| [InputLength](https://docs.rs/nom/latest/nom/trait.InputLength.html) | calculate the input length |
| [InputTake](https://docs.rs/nom/latest/nom/trait.InputTake.html) | slicing operations |
| [InputTakeAtPosition](https://docs.rs/nom/latest/nom/trait.InputTakeAtPosition.html) | look for a specific token and split at its position |
| [Offset](https://docs.rs/nom/latest/nom/trait.Offset.html) | calculate the offset between slices |
| [ParseTo](https://docs.rs/nom/latest/nom/trait.ParseTo.html) | used to integrate `&str`'s parse() method |
| [Slice](https://docs.rs/nom/latest/nom/trait.Slice.html) | slicing operations using ranges |
| [AsBytes](https://docs.rs/nom/latest/nom/trait.AsBytes.html) |Casts the input type to a byte slice|
| [Compare](https://docs.rs/nom/latest/nom/trait.Compare.html) |Character comparison operations|
| [ExtendInto](https://docs.rs/nom/latest/nom/trait.ExtendInto.html) |Abstracts something which can extend an `Extend`|
| [FindSubstring](https://docs.rs/nom/latest/nom/trait.FindSubstring.html) |Look for a substring in self|
| [FindToken](https://docs.rs/nom/latest/nom/trait.FindToken.html) |Look for self in the given input stream|
| [InputIter](https://docs.rs/nom/latest/nom/trait.InputIter.html) |Common iteration operations on the input type|
| [InputLength](https://docs.rs/nom/latest/nom/trait.InputLength.html) |Calculate the input length|
| [InputTake](https://docs.rs/nom/latest/nom/trait.InputTake.html) |Slicing operations|
| [InputTakeAtPosition](https://docs.rs/nom/latest/nom/trait.InputTakeAtPosition.html) |Look for a specific token and split at its position|
| [Offset](https://docs.rs/nom/latest/nom/trait.Offset.html) |Calculate the offset between slices|
| [ParseTo](https://docs.rs/nom/latest/nom/trait.ParseTo.html) |Used to integrate `&str`'s `parse()` method|
| [Slice](https://docs.rs/nom/latest/nom/trait.Slice.html) |Slicing operations using ranges|
Here are the traits we have to implement for `MyItem`:
| trait | usage |
|---|---|
| [AsChar](https://docs.rs/nom/latest/nom/trait.AsChar.html) | transforms common types to a char for basic token parsing |
| [AsChar](https://docs.rs/nom/latest/nom/trait.AsChar.html) |Transforms common types to a char for basic token parsing|

24
doc/error_management.md
View File

@ -26,9 +26,9 @@ for an example of choosing different error types at the call site.
The `Err<E>` enum expresses 3 conditions for a parser error:
- `Incomplete` indicates that a parser did not have enough data to decide. This can be returned by parsers found in `streaming` submodules to indicate that we should buffer more data from a file or socket. Parsers in the `complete` submodules assume that they have the entire input data, so if it was not sufficient, they will instead return a `Err::Error`
- `Error` is a normal parser error. If a child parser of the `alt` combinator returns `Error`, it will try another child parser
- `Failure` is an error from which we cannot recover: the `alt` combinator will not try other branches if a child parser returns `Failure`
- `Failure` is an error from which we cannot recover: The `alt` combinator will not try other branches if a child parser returns `Failure`
## the `ParseError` trait
## The `ParseError` trait
To allow configurable error types, nom uses the `ParseError` trait in all
combinators, defined as follows:
@ -55,19 +55,19 @@ pub trait ParseError<I>: Sized {
Any error type has to implement that trait, that requires ways to build an
error:
- `from_error_kind`: from the input position and the `ErrorKind` enum that indicates in which parser we got an error
- `append`: allows the creation of a chain of errors as we backtrack through the parser tree (various combinators will add more context)
- `from_char`: creates an error that indicates which character we were expecting
- `or`: in combinators like `alt`, allows choosing between errors from various branches (or accumulating them)
- `add_context`: works like `append` but uses a static string instead of an `ErrorKind`. Usable with the `nom::error`::context` function
- `from_error_kind`: From the input position and the `ErrorKind` enum that indicates in which parser we got an error
- `append`: Allows the creation of a chain of errors as we backtrack through the parser tree (various combinators will add more context)
- `from_char`: Creates an error that indicates which character we were expecting
- `or`: In combinators like `alt`, allows choosing between errors from various branches (or accumulating them)
- `add_context`: Works like `append` but uses a static string instead of an `ErrorKind`. Usable with the `nom::error`::context` function
This trait is currently implemented for 3 types:
- `()`: if you want to ignore errors completely
- `(I, ErrorKind)`: the default error type
- `nom::error::VerboseError`: this type accumulates a chain of errors and leverages `from_char` and `add_context`
- `()`: If you want to ignore errors completely
- `(I, ErrorKind)`: The default error type
- `nom::error::VerboseError`: This type accumulates a chain of errors and leverages `from_char` and `add_context`
The `VerboseError` type is especially useful if you need precise position information,
and you want to a user friendly way of displaying the error.
and you want to have a user friendly way of displaying the error.
By calling the `nom::error::convert_error` function with the original input data
(in `&str`) and the error, you can get a trace like this:
@ -179,5 +179,3 @@ preceded "data: (1,2,3)"
-> Ok(["1", "2", "3"])
-> Ok(["1", "2", "3"])
```

11
doc/how_nom_macros_work.md
View File

@ -3,9 +3,9 @@
nom uses Rust macros heavily to provide a nice syntax and generate parsing code.
This has multiple advantages:
* it gives the appearance of combining functions without the runtime cost of closures
* it helps Rust's code inference and borrow checking (less lifetime issues than iterator based solutions)
* the generated code is very linear, just a large chain of pattern matching
* It gives the appearance of combining functions without the runtime cost of closures
* It helps Rust's code inference and borrow checking (less lifetime issues than iterator based solutions)
* The generated code is very linear, just a large chain of pattern matching
As a prerequisite, if you need more information on macros, please refer to
[the little book of Rust macros](https://danielkeep.github.io/tlborm/book/README.html)
@ -58,7 +58,7 @@ parameter that you do not use:
($i:expr, $f:expr)
```
while you call:
While you call:
```rust
opt!(digit)
@ -161,7 +161,7 @@ The macro is called with the input we got, as first argument, then we pattern
match on the result. Every combinator or parser must return a `IResult`, which
is a `Result<(I, O), nom::Err<I, E>>`, so you know which patterns you need to
verify. If you need to call two parsers in a sequence, use the first parameter
of `Ok((i,o))`: it is the input remaining after the first parser was applied.
of `Ok((i,o))`: It is the input remaining after the first parser was applied.
As an example, see how the `preceded!` macro works:
@ -180,4 +180,3 @@ As an example, see how the `preceded!` macro works:
It applies the first parser, and if it succeeds, discards its result, and applies
the remaining input `i1` to the second parser.

6
doc/making_a_new_parser_from_scratch.md
View File

@ -1,7 +1,7 @@
# Making a new parser from scratch
Writing a parser is a very fun, interactive process, but sometimes a daunting
task. How do you test it? How to see ambiguities in specifications?
task. How do you test it? How to see ambiguities in specifications?
nom is designed to abstract data manipulation (counting array offsets,
converting to structures, etc) while providing a safe, composable API. It also
@ -185,7 +185,7 @@ There are a few tools you can use to debug how code is generated.
## dbg_dmp
this function wraps a parser that accepts a `&[u8]` as input and
This function wraps a parser that accepts a `&[u8]` as input and
prints its hexdump if the child parser encountered an error:
```rust
@ -203,7 +203,7 @@ fn f(i: &[u8]) -> IResult<&[u8], &[u8]> {
f(a);
```
## macros specific debugging tools
## Macros specific debugging tools
### trace\_macros

23
doc/upgrading_to_nom_5.md
View File

@ -1,14 +1,13 @@
# Upgrading to nom 5.0
## Changes in error types
**if you have a lot of unit tests, this is probably the biggest issue you'll encounter**
**If you have a lot of unit tests, this is probably the biggest issue you'll encounter**
Error management has been rewritten to avoid two issues present in previous
versions:
- the error type was causing type inference issues in macros
- the `verbose-errors` was changing the API (adding a variant in an enum) and
- The error type was causing type inference issues in macros
- The `verbose-errors` was changing the API (adding a variant in an enum) and
reducing the parsing speed. Since compilation features are additive, if a
dependency used nom with `verbose-errors`, it would be activated for all dependencies
@ -49,7 +48,7 @@ Now the error type is completely generic, so you can choose exactly
what you need, from erasing errors entirely, to reproducing the
`verbose-errors` feature with the [`VerboseError` type](https://docs.rs/nom/latest/nom/error/struct.VerboseError.html).
The [`ErrorKind` enum](https://docs.rs/nom/latest/nom/error/enum.ErrorKind.html)
is not generic now: it does not need to hold a custom error type.
is not generic now: It does not need to hold a custom error type.
Any error type has to implement the [`ParseError` trait](https://docs.rs/nom/latest/nom/error/trait.ParseError.html)
that specifies methods to build an error from a position in input data,
@ -67,7 +66,7 @@ error type `(Input, ErrorKind)`.
Those types were introduced in nom 4 as alternative input types, to
solve issues with streaming parsers.
A core feature of nom is its support for streaming parsers: when you are
A core feature of nom is its support for streaming parsers: When you are
handling network packets or large files, you might not have all of the data.
As an example, if you use a parser recognizing numbers and you pass as input
"123", the parser will return `Err(Err::Incomplete(_))` because it cannot decide
@ -114,15 +113,15 @@ list, we have functions that take other functions as arguments, and return
functions.
This technique has a lot of advantages over macros:
- no type inference issues, you can explicitely describe the error type in
- No type inference issues, you can explicitely describe the error type in
function definitions
- nicer compilation errors: rustc can show you exactly what is missing when calling
a combinator, if you need to import new traits, etc
- those functions are actually faster than nom 4's macros when built with link time
- Nicer compilation errors: rustc can show you exactly what is missing when calling
a combinator, if you need to import new traits, etc.
- Those functions are actually faster than nom 4's macros when built with link time
optimization
- small gain in compilation speed (since code can be reused instead of regenerated
- Small gain in compilation speed (since code can be reused instead of regenerated
everywhere)
- the macros are still there, but were rewritten to use the functions instead, so
- The macros are still there, but were rewritten to use the functions instead, so
they gain the performance benefit immediately
In practice, nom parsers will have the following signature:

6
src/bits/complete.rs
View File

@ -1,4 +1,4 @@
//! bit level parsers
//! Bit level parsers
//!
use crate::error::{ErrorKind, ParseError};
@ -6,7 +6,7 @@ use crate::internal::{Err, IResult};
use crate::lib::std::ops::{AddAssign, Div, RangeFrom, Shl, Shr};
use crate::traits::{InputIter, InputLength, Slice, ToUsize};
/// generates a parser taking `count` bits
/// Generates a parser taking `count` bits
pub fn take<I, O, C, E: ParseError<(I, usize)>>(
count: C,
) -> impl Fn((I, usize)) -> IResult<(I, usize), O, E>
@ -58,7 +58,7 @@ where
}
}
/// generates a parser taking `count` bits and comparing them to `pattern`
/// Generates a parser taking `count` bits and comparing them to `pattern`
pub fn tag<I, O, C, E: ParseError<(I, usize)>>(
pattern: O,
count: C,

2
src/bits/macros.rs
View File

@ -40,7 +40,7 @@ macro_rules! bits (
);
);
/// Counterpart to bits, bytes! transforms its bit stream input into a byte slice for the underlying
/// Counterpart to `bits`, `bytes!` transforms its bit stream input into a byte slice for the underlying
/// parser, allowing byte-slice parsers to work on bit streams.
///
/// Signature:

4
src/bits/mod.rs
View File

@ -1,4 +1,4 @@
//! bit level parsers
//! Bit level parsers
//!
#[macro_use]
@ -63,7 +63,7 @@ where
bits(parser)(input)
}
/// Counterpart to bits, bytes transforms its bit stream input into a byte slice for the underlying
/// Counterpart to `bits`, `bytes` transforms its bit stream input into a byte slice for the underlying
/// parser, allowing byte-slice parsers to work on bit streams.
///
/// A partial byte remaining in the input will be ignored and the given parser will start parsing

6
src/bits/streaming.rs
View File

@ -1,4 +1,4 @@
//! bit level parsers
//! Bit level parsers
//!
use crate::error::{ErrorKind, ParseError};
@ -6,7 +6,7 @@ use crate::internal::{Err, IResult, Needed};
use crate::lib::std::ops::{AddAssign, Div, RangeFrom, Shl, Shr};
use crate::traits::{InputIter, InputLength, Slice, ToUsize};
/// generates a parser taking `count` bits
/// Generates a parser taking `count` bits
pub fn take<I, O, C, E: ParseError<(I, usize)>>(
count: C,
) -> impl Fn((I, usize)) -> IResult<(I, usize), O, E>
@ -55,7 +55,7 @@ where
}
}
/// generates a parser taking `count` bits and comparing them to `pattern`
/// Generates a parser taking `count` bits and comparing them to `pattern`
pub fn tag<I, O, C, E: ParseError<(I, usize)>>(
pattern: O,
count: C,

10
src/branch/macros.rs
View File

@ -94,7 +94,7 @@
///
/// **BE CAREFUL** there is a case where the behaviour of `alt!` can be confusing:
///
/// when the alternatives have different lengths, like this case:
/// When the alternatives have different lengths, like this case:
///
/// ```ignore
/// named!( test, alt!( tag!( "abcd" ) | tag!( "ef" ) | tag!( "ghi" ) | tag!( "kl" ) ) );
@ -138,7 +138,7 @@
/// named!( test, alt!( tag!( "abcd" ) | tag!( "ab" ) | tag!( "ef" ) ) );
/// ```
///
/// in that case, if you order by size, passing `"abcd"` as input will always be matched by the
/// In that case, if you order by size, passing `"abcd"` as input will always be matched by the
/// smallest parser, so the solution using `complete!` is better suited.
///
/// You can also nest multiple `alt!`, like this:
@ -382,13 +382,11 @@ macro_rules! switch (
);
);
///
///
/// `permutation!(I -> IResult<I,A>, I -> IResult<I,B>, ... I -> IResult<I,X> ) => I -> IResult<I, (A,B,...X)>`
/// applies its sub parsers in a sequence, but independent from their order
/// this parser will only succeed if all of its sub parsers succeed
/// this parser will only succeed if all of its sub parsers succeed.
///
/// the tuple of results is in the same order as the parsers are declared
/// The tuple of results is in the same order as the parsers are declared
///
/// ```
/// # #[macro_use] extern crate nom;

22
src/branch/mod.rs
View File

@ -1,4 +1,4 @@
//! choice combinators
//! Choice combinators
#[macro_use]
mod macros;
@ -7,15 +7,15 @@ use crate::error::ErrorKind;
use crate::error::ParseError;
use crate::internal::{Err, IResult, Parser};
/// helper trait for the [alt()] combinator
/// Helper trait for the [alt()] combinator.
///
/// this trait is implemented for tuples of up to 21 elements
/// This trait is implemented for tuples of up to 21 elements
pub trait Alt<I, O, E> {
/// tests each parser in the tuple and returns the result of the first one that succeeds
/// Tests each parser in the tuple and returns the result of the first one that succeeds
fn choice(&mut self, input: I) -> IResult<I, O, E>;
}
/// tests a list of parsers one by one until one succeeds
/// Tests a list of parsers one by one until one succeeds.
///
/// It takes as argument a tuple of parsers.
///
@ -40,7 +40,7 @@ pub trait Alt<I, O, E> {
/// # }
/// ```
///
/// with a custom error type, it is possible to have alt return the error of the parser
/// With a custom error type, it is possible to have alt return the error of the parser
/// that went the farthest in the input data
pub fn alt<I: Clone, O, E: ParseError<I>, List: Alt<I, O, E>>(
mut l: List,
@ -48,17 +48,17 @@ pub fn alt<I: Clone, O, E: ParseError<I>, List: Alt<I, O, E>>(
move |i: I| l.choice(i)
}
/// helper trait for the [permutation()] combinator
/// Helper trait for the [permutation()] combinator.
///
/// this trait is implemented for tuples of up to 21 elements
/// This trait is implemented for tuples of up to 21 elements
pub trait Permutation<I, O, E> {
/// tries to apply all parsers in the tuple in various orders until all of them succeed
/// Tries to apply all parsers in the tuple in various orders until all of them succeed
fn permutation(&mut self, input: I) -> IResult<I, O, E>;
}
/// applies a list of parsers in any order
/// Applies a list of parsers in any order.
///
/// permutation will succeed if all of the child parsers succeeded.
/// Permutation will succeed if all of the child parsers succeeded.
/// It takes as argument a tuple of parsers, and returns a
/// tuple of the parser results.
///

73
src/bytes/complete.rs
View File

@ -1,4 +1,4 @@
//! parsers recognizing bytes streams, complete input version
//! Parsers recognizing bytes streams, complete input version
use crate::error::ErrorKind;
use crate::error::ParseError;
@ -51,12 +51,12 @@ where
}
}
/// Recognizes a case insensitive pattern
/// Recognizes a case insensitive pattern.
///
/// The input data will be compared to the tag combinator's argument and will return the part of
/// the input that matches the argument with no regard to case
/// the input that matches the argument with no regard to case.
///
/// It will return `Err(Err::Error((_, ErrorKind::Tag)))` if the input doesn't match the pattern
/// It will return `Err(Err::Error((_, ErrorKind::Tag)))` if the input doesn't match the pattern.
/// # Example
/// ```rust
/// # #[macro_use] extern crate nom;
@ -95,13 +95,13 @@ where
}
}
/// Parse till certain characters are met
/// Parse till certain characters are met.
///
/// The parser will return the longest slice till one of the characters of the combinator's argument are met.
///
/// It doesn't consume the matched character,
/// It doesn't consume the matched character.
///
/// It will return a `Err::Error(("", ErrorKind::IsNot))` if the pattern wasn't met
/// It will return a `Err::Error(("", ErrorKind::IsNot))` if the pattern wasn't met.
/// # Example
/// ```rust
/// # #[macro_use] extern crate nom;
@ -130,13 +130,12 @@ where
}
}
/// Returns the longest slice of the matches the pattern
/// Returns the longest slice of the matches the pattern.
///
/// The parser will return the longest slice consisting of the characters in provided in the
/// combinator's argument
///
/// It will return a `Err(Err::Error((_, ErrorKind::IsA)))` if the pattern wasn't met
/// combinator's argument.
///
/// It will return a `Err(Err::Error((_, ErrorKind::IsA)))` if the pattern wasn't met.
/// # Example
/// ```rust
/// # #[macro_use] extern crate nom;
@ -166,11 +165,10 @@ where
}
}
/// Returns the longest input slice (if any) that matches the predicate
/// Returns the longest input slice (if any) that matches the predicate.
///
/// The parser will return the longest slice that matches the given predicate *(a function that
/// takes the input and returns a bool)*
///
/// takes the input and returns a bool)*.
/// # Example
/// ```rust
/// # #[macro_use] extern crate nom;
@ -197,13 +195,12 @@ where
move |i: Input| i.split_at_position_complete(|c| !cond(c))
}
/// Returns the longest (atleast 1) input slice that matches the predicate
/// Returns the longest (atleast 1) input slice that matches the predicate.
///
/// The parser will return the longest slice that matches the given predicate *(a function that
/// takes the input and returns a bool)*
///
/// It will return an `Err(Err::Error((_, ErrorKind::TakeWhile1)))` if the pattern wasn't met
/// takes the input and returns a bool)*.
///
/// It will return an `Err(Err::Error((_, ErrorKind::TakeWhile1)))` if the pattern wasn't met.
/// # Example
/// ```rust
/// # #[macro_use] extern crate nom;
@ -232,14 +229,13 @@ where
}
}
/// Returns the longest (m <= len <= n) input slice that matches the predicate
/// Returns the longest (m <= len <= n) input slice that matches the predicate.
///
/// The parser will return the longest slice that matches the given predicate *(a function that
/// takes the input and returns a bool)*
/// takes the input and returns a bool)*.
///
/// It will return an `Err::Error((_, ErrorKind::TakeWhileMN))` if the pattern wasn't met or is out
/// of range (m <= len <= n)
///
/// of range (m <= len <= n).
/// # Example
/// ```rust
/// # #[macro_use] extern crate nom;
@ -322,11 +318,10 @@ where
}
}
/// Returns the longest input slice (if any) till a predicate is met
/// Returns the longest input slice (if any) till a predicate is met.
///
/// The parser will return the longest slice till the given predicate *(a function that
/// takes the input and returns a bool)*
///
/// takes the input and returns a bool)*.
/// # Example
/// ```rust
/// # #[macro_use] extern crate nom;
@ -352,14 +347,13 @@ where
move |i: Input| i.split_at_position_complete(|c| cond(c))
}
/// Returns the longest (atleast 1) input slice till a predicate is met
/// Returns the longest (atleast 1) input slice till a predicate is met.
///
/// The parser will return the longest slice till the given predicate *(a function that
/// takes the input and returns a bool)*
/// takes the input and returns a bool)*.
///
/// It will return `Err(Err::Error((_, ErrorKind::TakeTill1)))` if the input is empty or the
/// predicate matches the first input
///
/// predicate matches the first input.
/// # Example
/// ```rust
/// # #[macro_use] extern crate nom;
@ -388,10 +382,9 @@ where
}
}
/// Returns an input slice containing the first N input elements (Input[..N])
///
/// It will return `Err(Err::Error((_, ErrorKind::Eof)))` if the input is shorter than the argument
/// Returns an input slice containing the first N input elements (Input[..N]).
///
/// It will return `Err(Err::Error((_, ErrorKind::Eof)))` if the input is shorter than the argument.
/// # Example
/// ```rust
/// # #[macro_use] extern crate nom;
@ -424,8 +417,7 @@ where
/// Returns the longest input slice till it matches the pattern.
///
/// It doesn't consume the pattern. It will return `Err(Err::Error((_, ErrorKind::TakeUntil)))`
/// if the pattern wasn't met
///
/// if the pattern wasn't met.
/// # Example
/// ```rust
/// # #[macro_use] extern crate nom;
@ -459,10 +451,9 @@ where
/// Matches a byte string with escaped characters.
///
/// * The first argument matches the normal characters (it must not accept the control character),
/// * the second argument is the control character (like `\` in most languages),
/// * the third argument matches the escaped characters
///
/// * The first argument matches the normal characters (it must not accept the control character)
/// * The second argument is the control character (like `\` in most languages)
/// * The third argument matches the escaped characters
/// # Example
/// ```
/// # #[macro_use] extern crate nom;
@ -578,9 +569,9 @@ where
/// Matches a byte string with escaped characters.
///
/// * The first argument matches the normal characters (it must not match the control character),
/// * the second argument is the control character (like `\` in most languages),
/// * the third argument matches the escaped characters and transforms them.
/// * The first argument matches the normal characters (it must not match the control character)
/// * The second argument is the control character (like `\` in most languages)
/// * The third argument matches the escaped characters and transforms them
///
/// As an example, the chain `abc\tdef` could be `abc def` (it also consumes the control character)
///

54
src/bytes/macros.rs
View File

@ -3,10 +3,9 @@
#[allow(unused_variables)]
/// `tag!(&[T]: nom::AsBytes) => &[T] -> IResult<&[T], &[T]>`
/// declares a byte array as a suite to recognize
///
/// consumes the recognized characters
/// declares a byte array as a suite to recognize.
///
/// Consumes the recognized characters.
/// # Example
/// ```
/// # #[macro_use] extern crate nom;
@ -24,10 +23,9 @@ macro_rules! tag (
);
/// `tag_no_case!(&[T]) => &[T] -> IResult<&[T], &[T]>`
/// declares a case insensitive ascii string as a suite to recognize
///
/// consumes the recognized characters
/// declares a case insensitive ascii string as a suite to recognize.
///
/// Consumes the recognized characters.
/// # Example
/// ```
/// # #[macro_use] extern crate nom;
@ -46,8 +44,7 @@ macro_rules! tag_no_case (
);
/// `is_not!(&[T:AsBytes]) => &[T] -> IResult<&[T], &[T]>`
/// returns the longest list of bytes that do not appear in the provided array
///
/// returns the longest list of bytes that do not appear in the provided array.
/// # Example
/// ```
/// # #[macro_use] extern crate nom;
@ -66,8 +63,7 @@ macro_rules! is_not (
);
/// `is_a!(&[T]) => &[T] -> IResult<&[T], &[T]>`
/// returns the longest list of bytes that appear in the provided array
///
/// returns the longest list of bytes that appear in the provided array.
/// # Example
/// ```
/// # #[macro_use] extern crate nom;
@ -92,10 +88,9 @@ macro_rules! is_a (
/// U: AsChar`
/// matches a byte string with escaped characters.
///
/// The first argument matches the normal characters (it must not accept the control character),
/// the second argument is the control character (like `\` in most languages),
/// the third argument matches the escaped characters
///
/// * The first argument matches the normal characters (it must not accept the control character)
/// * The second argument is the control character (like `\` in most languages)
/// * The third argument matches the escaped characters
/// # Example
/// ```
/// # #[macro_use] extern crate nom;
@ -133,12 +128,11 @@ macro_rules! escaped (
/// `escaped_transform!(&[T] -> IResult<&[T], &[T]>, T, &[T] -> IResult<&[T], &[T]>) => &[T] -> IResult<&[T], Vec<T>>`
/// matches a byte string with escaped characters.
///
/// The first argument matches the normal characters (it must not match the control character),
/// the second argument is the control character (like `\` in most languages),
/// the third argument matches the escaped characters and transforms them.
///
/// As an example, the chain `abc\tdef` could be `abc def` (it also consumes the control character)
/// * The first argument matches the normal characters (it must not match the control character)
/// * The second argument is the control character (like `\` in most languages)
/// * The third argument matches the escaped characters and transforms them
///
/// As an example, the chain `abc\tdef` could be `abc def` (it also consumes the control character).
/// # Example
/// ```rust
/// # #[macro_use] extern crate nom;
@ -192,7 +186,6 @@ macro_rules! escaped_transform (
/// returns the longest list of bytes until the provided function fails.
///
/// The argument is either a function `T -> bool` or a macro returning a `bool`.
///
/// # Example
/// ```
/// # #[macro_use] extern crate nom;
@ -218,8 +211,7 @@ macro_rules! take_while (
/// `take_while1!(T -> bool) => &[T] -> IResult<&[T], &[T]>`
/// returns the longest (non empty) list of bytes until the provided function fails.
///
/// The argument is either a function `&[T] -> bool` or a macro returning a `bool`
///
/// The argument is either a function `&[T] -> bool` or a macro returning a `bool`.
/// # Example
/// ```
/// # #[macro_use] extern crate nom;
@ -247,10 +239,9 @@ macro_rules! take_while1 (
/// `take_while_m_n!(m: usize, n: usize, T -> bool) => &[T] -> IResult<&[T], &[T]>`
/// returns a list of bytes or characters for which the provided function returns true.
/// the returned list's size will be at least m, and at most n
/// The returned list's size will be at least m, and at most n.
///
/// The argument is either a function `T -> bool` or a macro returning a `bool`.
///
/// # Example
/// ```
/// # #[macro_use] extern crate nom;
@ -274,10 +265,9 @@ macro_rules! take_while_m_n (
);
/// `take_till!(T -> bool) => &[T] -> IResult<&[T], &[T]>`
/// returns the longest list of bytes until the provided function succeeds
/// returns the longest list of bytes until the provided function succeeds.
///
/// The argument is either a function `&[T] -> bool` or a macro returning a `bool`.
///
/// # Example
/// ```
/// # #[macro_use] extern crate nom;
@ -302,7 +292,7 @@ macro_rules! take_till (
);
/// `take_till1!(T -> bool) => &[T] -> IResult<&[T], &[T]>`
/// returns the longest non empty list of bytes until the provided function succeeds
/// returns the longest non empty list of bytes until the provided function succeeds.
///
/// The argument is either a function `&[T] -> bool` or a macro returning a `bool`.
///
@ -332,8 +322,7 @@ macro_rules! take_till1 (
);
/// `take!(nb) => &[T] -> IResult<&[T], &[T]>`
/// generates a parser consuming the specified number of bytes
///
/// generates a parser consuming the specified number of bytes.
/// # Example
/// ```
/// # #[macro_use] extern crate nom;
@ -356,8 +345,7 @@ macro_rules! take (
);
/// `take_str!(nb) => &[T] -> IResult<&[T], &str>`
/// same as take! but returning a &str
///
/// same as `take!` but returning a `&str`.
/// # Example
/// ```
/// # #[macro_use] extern crate nom;
@ -384,7 +372,6 @@ macro_rules! take_str (
/// consumes data until it finds the specified tag.
///
/// The remainder still contains the tag.
///
/// # Example
/// ```
/// # #[macro_use] extern crate nom;
@ -403,10 +390,9 @@ macro_rules! take_until (
);
/// `take_until1!(tag) => &[T] -> IResult<&[T], &[T]>`
/// consumes data (at least one byte) until it finds the specified tag
/// consumes data (at least one byte) until it finds the specified tag.
///
/// The remainder still contains the tag.
///
/// # Example
/// ```
/// # #[macro_use] extern crate nom;

2
src/bytes/mod.rs
View File

@ -1,4 +1,4 @@
//! parsers recognizing bytes streams
//! Parsers recognizing bytes streams
#[macro_use]
mod macros;

73
src/bytes/streaming.rs
View File

@ -1,4 +1,4 @@
//! parsers recognizing bytes streams, streaming version
//! Parsers recognizing bytes streams, streaming version
use crate::error::ErrorKind;
use crate::error::ParseError;
@ -10,10 +10,10 @@ use crate::traits::{
InputTakeAtPosition, Slice, ToUsize,
};
/// Recognizes a pattern
/// Recognizes a pattern.
///
/// The input data will be compared to the tag combinator's argument and will return the part of
/// the input that matches the argument
/// the input that matches the argument.
/// # Example
/// ```rust
/// # #[macro_use] extern crate nom;
@ -51,10 +51,10 @@ where
}
}
/// Recognizes a case insensitive pattern
/// Recognizes a case insensitive pattern.
///
/// The input data will be compared to the tag combinator's argument and will return the part of
/// the input that matches the argument with no regard to case
/// the input that matches the argument with no regard to case.
/// # Example
/// ```rust
/// # #[macro_use] extern crate nom;
@ -94,13 +94,13 @@ where
}
}
/// Parse till certain characters are met
/// Parse till certain characters are met.
///
/// The parser will return the longest slice till one of the characters of the combinator's argument are met.
///
/// It doesn't consume the matched character,
/// It doesn't consume the matched character.
///
/// It will return a `Err::Incomplete(Needed::new(1))` if the pattern wasn't met
/// It will return a `Err::Incomplete(Needed::new(1))` if the pattern wasn't met.
/// # Example
/// ```rust
/// # #[macro_use] extern crate nom;
@ -129,14 +129,14 @@ where
}
}
/// Returns the longest slice of the matches the pattern
/// Returns the longest slice of the matches the pattern.
///
/// The parser will return the longest slice consisting of the characters in provided in the
/// combinator's argument
/// combinator's argument.
///
/// # Streaming specific
/// *Streaming version* will return a `Err::Incomplete(Needed::new(1))` if the pattern wasn't met
/// or if the pattern reaches the end of the input
/// or if the pattern reaches the end of the input.
/// # Example
/// ```rust
/// # #[macro_use] extern crate nom;
@ -166,13 +166,13 @@ where
}
}
/// Returns the longest input slice (if any) that matches the predicate
/// Returns the longest input slice (if any) that matches the predicate.
///
/// The parser will return the longest slice that matches the given predicate *(a function that
/// takes the input and returns a bool)*
/// takes the input and returns a bool)*.
///
/// # Streaming Specific
/// *Streaming version* will return a `Err::Incomplete(Needed::new(1))` if the pattern reaches the end of the input
/// *Streaming version* will return a `Err::Incomplete(Needed::new(1))` if the pattern reaches the end of the input.
/// # Example
/// ```rust
/// # #[macro_use] extern crate nom;
@ -199,12 +199,12 @@ where
move |i: Input| i.split_at_position(|c| !cond(c))
}
/// Returns the longest (atleast 1) input slice that matches the predicate
/// Returns the longest (atleast 1) input slice that matches the predicate.
///
/// The parser will return the longest slice that matches the given predicate *(a function that
/// takes the input and returns a bool)*
/// takes the input and returns a bool)*.
///
/// It will return an `Err(Err::Error((_, ErrorKind::TakeWhile1)))` if the pattern wasn't met
/// It will return an `Err(Err::Error((_, ErrorKind::TakeWhile1)))` if the pattern wasn't met.
///
/// # Streaming Specific
/// *Streaming version* will return a `Err::Incomplete(Needed::new(1))` or if the pattern reaches the end of the input.
@ -237,12 +237,12 @@ where
}
}
/// Returns the longest (m <= len <= n) input slice that matches the predicate
/// Returns the longest (m <= len <= n) input slice that matches the predicate.
///
/// The parser will return the longest slice that matches the given predicate *(a function that
/// takes the input and returns a bool)*
/// takes the input and returns a bool)*.
///
/// It will return an `Err::Error((_, ErrorKind::TakeWhileMN))` if the pattern wasn't met
/// It will return an `Err::Error((_, ErrorKind::TakeWhileMN))` if the pattern wasn't met.
/// # Streaming Specific
/// *Streaming version* will return a `Err::Incomplete(Needed::new(1))` if the pattern reaches the end of the input or is too short.
///
@ -323,14 +323,14 @@ where
}
}
/// Returns the longest input slice (if any) till a predicate is met
/// Returns the longest input slice (if any) till a predicate is met.
///
/// The parser will return the longest slice till the given predicate *(a function that
/// takes the input and returns a bool)*
/// takes the input and returns a bool)*.
///
/// # Streaming Specific
/// *Streaming version* will return a `Err::Incomplete(Needed::new(1))` if the match reaches the
/// end of input or if there was not match
/// end of input or if there was not match.
///
/// # Example
/// ```rust
@ -357,14 +357,14 @@ where
move |i: Input| i.split_at_position(|c| cond(c))
}
/// Returns the longest (atleast 1) input slice till a predicate is met
/// Returns the longest (atleast 1) input slice till a predicate is met.
///
/// The parser will return the longest slice till the given predicate *(a function that
/// takes the input and returns a bool)*
/// takes the input and returns a bool)*.
///
/// # Streaming Specific
/// *Streaming version* will return a `Err::Incomplete(Needed::new(1))` if the match reaches the
/// end of input or if there was not match
/// end of input or if there was not match.
/// # Example
/// ```rust
/// # #[macro_use] extern crate nom;
@ -393,11 +393,11 @@ where
}
}
/// Returns an input slice containing the first N input elements (Input[..N])
/// Returns an input slice containing the first N input elements (Input[..N]).
///
/// # Streaming Specific
/// *Streaming version* will return a `Err::Incomplete(Needed::new(N))` where N is the
/// argument if the input is less than the length provided
/// argument if the input is less than the length provided.
/// # Example
/// ```rust
/// # #[macro_use] extern crate nom;
@ -429,11 +429,11 @@ where
/// Returns the longest input slice till it matches the pattern.
///
/// It doesn't consume the pattern
/// It doesn't consume the pattern.
///
/// # Streaming Specific
/// *Streaming version* will return a `Err::Incomplete(Needed::new(N))` if the input doesn't
/// contain the pattern or if the input is smaller than the pattern
/// contain the pattern or if the input is smaller than the pattern.
/// # Example
/// ```rust
/// # #[macro_use] extern crate nom;
@ -469,10 +469,9 @@ where
/// Matches a byte string with escaped characters.
///
/// * The first argument matches the normal characters (it must not accept the control character),
/// * the second argument is the control character (like `\` in most languages),
/// * the third argument matches the escaped characters
///
/// * The first argument matches the normal characters (it must not accept the control character)
/// * The second argument is the control character (like `\` in most languages)
/// * The third argument matches the escaped characters
/// # Example
/// ```
/// # #[macro_use] extern crate nom;
@ -579,9 +578,9 @@ where
/// Matches a byte string with escaped characters.
///
/// * The first argument matches the normal characters (it must not match the control character),
/// * the second argument is the control character (like `\` in most languages),
/// * the third argument matches the escaped characters and transforms them.
/// * The first argument matches the normal characters (it must not match the control character)
/// * The second argument is the control character (like `\` in most languages)
/// * The third argument matches the escaped characters and transforms them
///
/// As an example, the chain `abc\tdef` could be `abc def` (it also consumes the control character)
///

69
src/character/complete.rs
View File

@ -11,8 +11,7 @@ use crate::traits::{Compare, CompareResult};
/// Recognizes one character.
///
/// *complete version*: Will return an error if there's not enough input data.
///
/// *Complete version*: Will return an error if there's not enough input data.
/// # Example
///
/// ```
@ -40,8 +39,7 @@ where
/// Recognizes one of the provided characters.
///
/// *complete version*: Will return an error if there's not enough input data.
///
/// *Complete version*: Will return an error if there's not enough input data.
/// # Example
///
/// ```
@ -67,8 +65,7 @@ where
/// Recognizes a character that is not in the provided characters.
///
/// *complete version*: Will return an error if there's not enough input data.
///
/// *Complete version*: Will return an error if there's not enough input data.
/// # Example
///
/// ```
@ -94,8 +91,7 @@ where
/// Recognizes the string "\r\n".
///
/// *complete version*: Will return an error if there's not enough input data.
///
/// *Complete version*: Will return an error if there's not enough input data.
/// # Example
///
/// ```
@ -130,8 +126,7 @@ where
//FIXME: there's still an incomplete
/// Recognizes a string of any char except '\r' or '\n'.
///
/// *complete version*: Will return an error if there's not enough input data.
///
/// *Complete version*: Will return an error if there's not enough input data.
/// # Example
///
/// ```
@ -183,8 +178,7 @@ where
/// Recognizes an end of line (both '\n' and '\r\n').
///
/// *complete version*: Will return an error if there's not enough input data.
///
/// *Complete version*: Will return an error if there's not enough input data.
/// # Example
///
/// ```
@ -221,8 +215,7 @@ where
/// Matches a newline character '\n'.
///
/// *complete version*: Will return an error if there's not enough input data.
///
/// *Complete version*: Will return an error if there's not enough input data.
/// # Example
///
/// ```
@ -248,8 +241,7 @@ where
/// Matches a tab character '\t'.
///
/// *complete version*: Will return an error if there's not enough input data.
///
/// *Complete version*: Will return an error if there's not enough input data.
/// # Example
///
/// ```
@ -276,8 +268,7 @@ where
/// Matches one byte as a character. Note that the input type will
/// accept a `str`, but not a `&[u8]`, unlike many other nom parsers.
///
/// *complete version*: Will return an error if there's not enough input data.
///
/// *Complete version*: Will return an error if there's not enough input data.
/// # Example
///
/// ```
@ -308,9 +299,8 @@ where
/// Recognizes zero or more lowercase and uppercase ASCII alphabetic characters: a-z, A-Z
///
/// *complete version*: Will return the whole input if no terminating token is found (a non
/// *Complete version*: Will return the whole input if no terminating token is found (a non
/// alphabetic character).
///
/// # Example
///
/// ```
@ -336,9 +326,8 @@ where
/// Recognizes one or more lowercase and uppercase ASCII alphabetic characters: a-z, A-Z
///
/// *complete version*: Will return an error if there's not enough input data,
/// *Complete version*: Will return an error if there's not enough input data,
/// or the whole input if no terminating token is found (a non alphabetic character).
///
/// # Example
///
/// ```
@ -364,9 +353,8 @@ where
/// Recognizes zero or more ASCII numerical characters: 0-9
///
/// *complete version*: Will return an error if there's not enough input data,
/// *Complete version*: Will return an error if there's not enough input data,
/// or the whole input if no terminating token is found (a non digit character).
///
/// # Example
///
/// ```
@ -393,9 +381,8 @@ where
/// Recognizes one or more ASCII numerical characters: 0-9
///
/// *complete version*: Will return an error if there's not enough input data,
/// *Complete version*: Will return an error if there's not enough input data,
/// or the whole input if no terminating token is found (a non digit character).
///
/// # Example
///
/// ```
@ -421,8 +408,7 @@ where
/// Recognizes zero or more ASCII hexadecimal numerical characters: 0-9, A-F, a-f
///
/// *complete version*: Will return the whole input if no terminating token is found (a non hexadecimal digit character).
///
/// *Complete version*: Will return the whole input if no terminating token is found (a non hexadecimal digit character).
/// # Example
///
/// ```
@ -447,9 +433,8 @@ where
}
/// Recognizes one or more ASCII hexadecimal numerical characters: 0-9, A-F, a-f
///
/// *complete version*: Will return an error if there's not enough input data,
/// *Complete version*: Will return an error if there's not enough input data,
/// or the whole input if no terminating token is found (a non hexadecimal digit character).
///
/// # Example
///
/// ```
@ -475,9 +460,8 @@ where
/// Recognizes zero or more octal characters: 0-7
///
/// *complete version*: Will return the whole input if no terminating token is found (a non octal
/// *Complete version*: Will return the whole input if no terminating token is found (a non octal
/// digit character).
///
/// # Example
///
/// ```
@ -503,9 +487,8 @@ where
/// Recognizes one or more octal characters: 0-7
///
/// *complete version*: Will return an error if there's not enough input data,
/// *Complete version*: Will return an error if there's not enough input data,
/// or the whole input if no terminating token is found (a non octal digit character).
///
/// # Example
///
/// ```
@ -531,9 +514,8 @@ where
/// Recognizes zero or more ASCII numerical and alphabetic characters: 0-9, a-z, A-Z
///
/// *complete version*: Will return the whole input if no terminating token is found (a non
/// *Complete version*: Will return the whole input if no terminating token is found (a non
/// alphanumerical character).
///
/// # Example
///
/// ```
@ -559,9 +541,8 @@ where
/// Recognizes one or more ASCII numerical and alphabetic characters: 0-9, a-z, A-Z
///
/// *complete version*: Will return an error if there's not enough input data,
/// *Complete version*: Will return an error if there's not enough input data,
/// or the whole input if no terminating token is found (a non alphanumerical character).
///
/// # Example
///
/// ```
@ -587,9 +568,8 @@ where
/// Recognizes zero or more spaces and tabs.
///
/// *complete version*: Will return the whole input if no terminating token is found (a non space
/// *Complete version*: Will return the whole input if no terminating token is found (a non space
/// character).
///
/// # Example
///
/// ```
@ -618,9 +598,8 @@ where
/// Recognizes one or more spaces and tabs.
///
/// *complete version*: Will return an error if there's not enough input data,
/// *Complete version*: Will return an error if there's not enough input data,
/// or the whole input if no terminating token is found (a non space character).
///
/// # Example
///
/// ```
@ -652,9 +631,8 @@ where
/// Recognizes zero or more spaces, tabs, carriage returns and line feeds.
///
/// *complete version*: will return the whole input if no terminating token is found (a non space
/// *Complete version*: will return the whole input if no terminating token is found (a non space
/// character).
///
/// # Example
///
/// ```
@ -683,9 +661,8 @@ where
/// Recognizes one or more spaces, tabs, carriage returns and line feeds.
///
/// *complete version*: will return an error if there's not enough input data,
/// *Complete version*: will return an error if there's not enough input data,
/// or the whole input if no terminating token is found (a non space character).
///
/// # Example
///
/// ```

6
src/character/macros.rs
View File

@ -1,6 +1,6 @@
/// Character level parsers
/// matches one of the provided characters
/// Matches one of the provided characters.
///
/// # Example
/// ```
@ -18,7 +18,7 @@ macro_rules! one_of (
($i:expr, $inp: expr) => ( $crate::character::streaming::one_of($inp)($i) );
);
/// matches anything but the provided characters
/// Matches anything but the provided characters.
///
/// # Example
/// ```
@ -37,7 +37,7 @@ macro_rules! none_of (
($i:expr, $inp: expr) => ( $crate::character::streaming::none_of($inp)($i) );
);
/// matches one character: `char!(char) => &[u8] -> IResult<&[u8], char>
/// Matches one character: `char!(char) => &[u8] -> IResult<&[u8], char>`.
///
/// # Example
/// ```

4
src/character/mod.rs
View File

@ -1,6 +1,6 @@
//! character specific parsers and combinators
//! Character specific parsers and combinators
//!
//! functions recognizing specific characters
//! Functions recognizing specific characters
#[macro_use]
mod macros;

73
src/character/streaming.rs
View File

@ -1,6 +1,6 @@
//! character specific parsers and combinators, streaming version
//! Character specific parsers and combinators, streaming version
//!
//! functions recognizing specific characters
//! Functions recognizing specific characters
use crate::error::ParseError;
use crate::internal::{Err, IResult, Needed};
@ -12,8 +12,7 @@ use crate::error::ErrorKind;
/// Recognizes one character.
///
/// *streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there's not enough input data.
///
/// *Streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there's not enough input data.
/// # Example
///
/// ```
@ -42,8 +41,7 @@ where
/// Recognizes one of the provided characters.
///
/// *streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there's not enough input data.
///
/// *Streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there's not enough input data.
/// # Example
///
/// ```
@ -70,8 +68,7 @@ where
/// Recognizes a character that is not in the provided characters.
///
/// *streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there's not enough input data.
///
/// *Streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there's not enough input data.
/// # Example
///
/// ```
@ -98,8 +95,7 @@ where
/// Recognizes the string "\r\n".
///
/// *streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there's not enough input data.
///
/// *Streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there's not enough input data.
/// # Example
///
/// ```
@ -130,8 +126,7 @@ where
/// Recognizes a string of any char except '\r' or '\n'.
///
/// *streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there's not enough input data.
///
/// *Streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there's not enough input data.
/// # Example
///
/// ```
@ -180,8 +175,7 @@ where
/// Recognizes an end of line (both '\n' and '\r\n').
///
/// *streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there's not enough input data.
///
/// *Streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there's not enough input data.
/// # Example
///
/// ```
@ -215,8 +209,7 @@ where
/// Matches a newline character '\\n'.
///
/// *streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there's not enough input data.
///
/// *Streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there's not enough input data.
/// # Example
///
/// ```
@ -238,8 +231,7 @@ where
/// Matches a tab character '\t'.
///
/// *streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there's not enough input data.
///
/// *Streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there's not enough input data.
/// # Example
///
/// ```
@ -262,8 +254,7 @@ where
/// Matches one byte as a character. Note that the input type will
/// accept a `str`, but not a `&[u8]`, unlike many other nom parsers.
///
/// *streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there's not enough input data.
///
/// *Streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there's not enough input data.
/// # Example
///
/// ```
@ -290,9 +281,8 @@ where
/// Recognizes zero or more lowercase and uppercase ASCII alphabetic characters: a-z, A-Z
///
/// *streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there's not enough input data,
/// *Streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there's not enough input data,
/// or if no terminating token is found (a non alphabetic character).
///
/// # Example
///
/// ```
@ -314,9 +304,8 @@ where
/// Recognizes one or more lowercase and uppercase ASCII alphabetic characters: a-z, A-Z
///
/// *streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there's not enough input data,
/// *Streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there's not enough input data,
/// or if no terminating token is found (a non alphabetic character).
///
/// # Example
///
/// ```
@ -338,9 +327,8 @@ where
/// Recognizes zero or more ASCII numerical characters: 0-9
///
/// *streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there's not enough input data,
/// *Streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there's not enough input data,
/// or if no terminating token is found (a non digit character).
///
/// # Example
///
/// ```
@ -362,9 +350,8 @@ where
/// Recognizes one or more ASCII numerical characters: 0-9
///
/// *streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there's not enough input data,
/// *Streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there's not enough input data,
/// or if no terminating token is found (a non digit character).
///
/// # Example
///
/// ```
@ -386,9 +373,8 @@ where
/// Recognizes zero or more ASCII hexadecimal numerical characters: 0-9, A-F, a-f
///
/// *streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there's not enough input data,
/// *Streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there's not enough input data,
/// or if no terminating token is found (a non hexadecimal digit character).
///
/// # Example
///
/// ```
@ -410,9 +396,8 @@ where
/// Recognizes one or more ASCII hexadecimal numerical characters: 0-9, A-F, a-f
///
/// *streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there's not enough input data,
/// *Streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there's not enough input data,
/// or if no terminating token is found (a non hexadecimal digit character).
///
/// # Example
///
/// ```
@ -434,9 +419,8 @@ where
/// Recognizes zero or more octal characters: 0-7
///
/// *streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there's not enough input data,
/// *Streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there's not enough input data,
/// or if no terminating token is found (a non octal digit character).
///
/// # Example
///
/// ```
@ -458,9 +442,8 @@ where
/// Recognizes one or more octal characters: 0-7
///
/// *streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there's not enough input data,
/// *Streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there's not enough input data,
/// or if no terminating token is found (a non octal digit character).
///
/// # Example
///
/// ```
@ -482,9 +465,8 @@ where
/// Recognizes zero or more ASCII numerical and alphabetic characters: 0-9, a-z, A-Z
///
/// *streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there's not enough input data,
/// *Streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there's not enough input data,
/// or if no terminating token is found (a non alphanumerical character).
///
/// # Example
///
/// ```
@ -506,9 +488,8 @@ where
/// Recognizes one or more ASCII numerical and alphabetic characters: 0-9, a-z, A-Z
///
/// *streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there's not enough input data,
/// *Streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there's not enough input data,
/// or if no terminating token is found (a non alphanumerical character).
///
/// # Example
///
/// ```
@ -530,9 +511,8 @@ where
/// Recognizes zero or more spaces and tabs.
///
/// *streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there's not enough input data,
/// *Streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there's not enough input data,
/// or if no terminating token is found (a non space character).
///
/// # Example
///
/// ```
@ -556,9 +536,8 @@ where
}
/// Recognizes one or more spaces and tabs.
///
/// *streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there's not enough input data,
/// *Streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there's not enough input data,
/// or if no terminating token is found (a non space character).
///
/// # Example
///
/// ```
@ -586,9 +565,8 @@ where
/// Recognizes zero or more spaces, tabs, carriage returns and line feeds.
///
/// *streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there's not enough input data,
/// *Streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there's not enough input data,
/// or if no terminating token is found (a non space character).
///
/// # Example
///
/// ```
@ -613,9 +591,8 @@ where
/// Recognizes one or more spaces, tabs, carriage returns and line feeds.
///
/// *streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there's not enough input data,
/// *Streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there's not enough input data,
/// or if no terminating token is found (a non space character).
///
/// # Example
///
/// ```

72
src/combinator/macros.rs
View File

@ -17,7 +17,7 @@
//! );
//! ```
//!
//! But when used in other combinators, are Used
//! But when used in other combinators, are used
//! like this:
//!
//! ```ignore
@ -45,8 +45,8 @@
//! ```
//!
//! Combinators must have a specific variant for
//! non-macro arguments. Example: passing a function
//! to take_while! instead of another combinator.
//! non-macro arguments. Example: Passing a function
//! to `take_while!` instead of another combinator.
//!
//! ```ignore
//! macro_rules! take_while(
@ -67,7 +67,7 @@
/// Makes a function from a parser combination
///
/// The type can be set up if the compiler needs
/// more information
/// more information.
///
/// Function-like declaration:
/// ```
@ -145,7 +145,7 @@ macro_rules! named (
/// );
/// ```
///
/// Note: if using arguments that way gets hard to read, it is always
/// Note: If using arguments that way gets hard to read, it is always
/// possible to write the equivalent parser definition manually, like
/// this:
///
@ -192,7 +192,7 @@ macro_rules! named_args {
};
}
/// Makes a function from a parser combination, with attributes
/// Makes a function from a parser combination, with attributes.
///
/// The usage of this macro is almost identical to `named!`, except that
/// you also pass attributes to be attached to the generated function.
@ -247,7 +247,7 @@ macro_rules! named_attr (
);
);
/// Used to wrap common expressions and function as macros
/// Used to wrap common expressions and function as macros.
///
/// ```
/// # #[macro_use] extern crate nom;
@ -266,7 +266,7 @@ macro_rules! call (
);
//FIXME: error rewrite
/// Prevents backtracking if the child parser fails
/// Prevents backtracking if the child parser fails.
///
/// This parser will do an early return instead of sending
/// its result to the parent parser.
@ -363,11 +363,11 @@ macro_rules! return_error (
);
//FIXME: error rewrite
/// Add an error if the child parser fails
/// Add an error if the child parser fails.
///
/// While `return_error!` does an early return and avoids backtracking,
/// add_return_error! backtracks normally. It just provides more context
/// for an error
/// `add_return_error!` backtracks normally. It just provides more context
/// for an error.
///
/// ```
/// # #[macro_use] extern crate nom;
@ -407,8 +407,8 @@ macro_rules! add_return_error (
);
);
/// replaces a `Incomplete` returned by the child parser
/// with an `Error`
/// Replaces a `Incomplete` returned by the child parser
/// with an `Error`.
///
/// ```
/// # #[macro_use] extern crate nom;
@ -438,7 +438,7 @@ macro_rules! complete (
/// parsed value if the child parser returned `Ok`, and will do an early
/// return for the `Err` side.
///
/// this can provide more flexibility than `do_parse!` if needed
/// This can provide more flexibility than `do_parse!` if needed.
///
/// ```
/// # #[macro_use] extern crate nom;
@ -479,7 +479,7 @@ macro_rules! try_parse (
/// `map!(I -> IResult<I, O>, O -> P) => I -> IResult<I, P>`
///
/// maps a function on the result of a parser
/// Maps a function on the result of a parser.
///
/// ```rust
/// # #[macro_use] extern crate nom;
@ -511,7 +511,7 @@ macro_rules! map(
);
/// `map_res!(I -> IResult<I, O>, O -> Result<P>) => I -> IResult<I, P>`
/// maps a function returning a Result on the output of a parser
/// maps a function returning a `Result` on the output of a parser.
///
/// ```rust
/// # #[macro_use] extern crate nom;
@ -552,7 +552,7 @@ macro_rules! map_res (
);
/// `map_opt!(I -> IResult<I, O>, O -> Option<P>) => I -> IResult<I, P>`
/// maps a function returning an Option on the output of a parser
/// maps a function returning an `Option` on the output of a parser.
///
/// ```rust
/// # #[macro_use] extern crate nom;
@ -593,10 +593,10 @@ macro_rules! map_opt (
);
/// `parse_to!(O) => I -> IResult<I, O>`
/// uses the `parse` method from `std::str::FromStr` to convert the current
/// input to the specified type
/// Uses the `parse` method from `std::str::FromStr` to convert the current
/// input to the specified type.
///
/// this will completely consume the input
/// This will completely consume the input.
///
/// ```rust
/// # #[macro_use] extern crate nom;
@ -637,7 +637,7 @@ macro_rules! parse_to (
);
/// `verify!(I -> IResult<I, O>, O -> bool) => I -> IResult<I, O>`
/// returns the result of the child parser if it satisfies a verification function
/// returns the result of the child parser if it satisfies a verification function.
///
/// ```
/// # #[macro_use] extern crate nom;
@ -666,7 +666,7 @@ macro_rules! verify (
/// or `value!(T) => R -> IResult<R, T>`
///
/// If the child parser was successful, return the value.
/// If no child parser is provided, always return the value
/// If no child parser is provided, always return the value.
///
/// ```
/// # #[macro_use] extern crate nom;
@ -694,10 +694,10 @@ macro_rules! value (
);
/// `opt!(I -> IResult<I,O>) => I -> IResult<I, Option<O>>`
/// make the underlying parser optional
/// make the underlying parser optional.
///
/// returns an Option of the returned type. This parser returns `Some(result)` if the child parser
/// succeeds,`None` if it fails, and `Incomplete` if it did not have enough data to decide
/// Returns an `Option` of the returned type. This parser returns `Some(result)` if the child parser
/// succeeds, `None` if it fails, and `Incomplete` if it did not have enough data to decide.
///
/// *Warning*: if you are using `opt` for some kind of optional ending token (like an end of line),
/// you should combine it with `complete` to make sure it works.
@ -731,9 +731,9 @@ macro_rules! opt(
);
/// `opt_res!(I -> IResult<I,O>) => I -> IResult<I, Result<nom::Err,O>>`
/// make the underlying parser optional
/// make the underlying parser optional.
///
/// returns a Result, with Err containing the parsing error
/// Returns a `Result`, with `Err` containing the parsing error.
///
/// ```ignore
/// # #[macro_use] extern crate nom;
@ -810,9 +810,9 @@ macro_rules! cond(
);
/// `peek!(I -> IResult<I,O>) => I -> IResult<I, O>`
/// returns a result without consuming the input
/// returns a result without consuming the input.
///
/// the embedded parser may return Err(Err::Incomplete
/// The embedded parser may return `Err(Err::Incomplete)`.
///
/// ```
/// # #[macro_use] extern crate nom;
@ -834,8 +834,8 @@ macro_rules! peek(
);
/// `not!(I -> IResult<I,O>) => I -> IResult<I, ()>`
/// returns a result only if the embedded parser returns Error or Err(Err::Incomplete)
/// does not consume the input
/// returns a result only if the embedded parser returns `Error` or `Err(Err::Incomplete)`.
/// Does not consume the input.
///
/// ```
/// # #[macro_use] extern crate nom;
@ -866,7 +866,7 @@ macro_rules! not(
);
/// `tap!(name: I -> IResult<I,O> => { block }) => I -> IResult<I, O>`
/// allows access to the parser's result without affecting it
/// allows access to the parser's result without affecting it.
///
/// ```
/// # #[macro_use] extern crate nom;
@ -900,10 +900,10 @@ macro_rules! tap (
);
);
/// `eof!()` returns its input if it is at the end of input data
/// `eof!()` returns its input if it is at the end of input data.
///
/// When we're at the end of the data, this combinator
/// will succeed
/// will succeed.
///
///
/// ```
@ -934,7 +934,7 @@ macro_rules! eof (
);
);
/// `exact!()` will fail if the child parser does not consume the whole data
/// `exact!()` will fail if the child parser does not consume the whole data.
///
/// TODO: example
#[macro_export(local_inner_macros)]
@ -948,7 +948,7 @@ macro_rules! exact (
);
/// `recognize!(I -> IResult<I, O> ) => I -> IResult<I, I>`
/// if the child parser was successful, return the consumed input as produced value
/// if the child parser was successful, return the consumed input as produced value.
///
/// ```
/// # #[macro_use] extern crate nom;

50
src/combinator/mod.rs
View File

@ -1,4 +1,4 @@
//! general purpose combinators
//! General purpose combinators
#![allow(unused_imports)]
@ -19,7 +19,7 @@ use crate::traits::{Compare, CompareResult, Offset, Slice};
#[macro_use]
mod macros;
/// Return the remaining input
/// Return the remaining input.
///
/// ```rust
/// # use nom::error::ErrorKind;
@ -36,7 +36,7 @@ where
Ok((input.slice(input.input_len()..), input))
}
/// Return the length of the remaining input
/// Return the length of the remaining input.
///
/// ```rust
/// # use nom::error::ErrorKind;
@ -53,7 +53,7 @@ where
Ok((input, len))
}
/// maps a function on the result of a parser
/// Maps a function on the result of a parser.
///
/// ```rust
/// # #[macro_use] extern crate nom;
@ -91,7 +91,7 @@ where
map(first, second).parse(input)
}
/// applies a function returning a Result over the result of a parser
/// Applies a function returning a `Result` over the result of a parser.
///
/// ```rust
/// # #[macro_use] extern crate nom;
@ -143,7 +143,7 @@ where
map_res(first, second)(input)
}
/// applies a function returning an Option over the result of a parser
/// Applies a function returning an `Option` over the result of a parser.
///
/// ```rust
/// # #[macro_use] extern crate nom;
@ -195,7 +195,7 @@ where
map_opt(first, second)(input)
}
/// applies a parser over the result of another one
/// Applies a parser over the result of another one.
///
/// ```rust
/// # #[macro_use] extern crate nom;
@ -242,7 +242,7 @@ where
map_parser(first, second)(input)
}
/// creates a new parser from the output of the first parser, then apply that parser over the rest of the input
/// Creates a new parser from the output of the first parser, then apply that parser over the rest of the input.
///
/// ```rust
/// # #[macro_use] extern crate nom;
@ -273,7 +273,7 @@ where
}
}
/// optional parser: will return None if not successful
/// Optional parser: Will return `None` if not successful.
///
/// ```rust
/// # #[macro_use] extern crate nom;
@ -312,7 +312,7 @@ where
opt(f)(input)
}
/// calls the parser if the condition is met
/// Calls the parser if the condition is met.
///
/// ```rust
/// # #[macro_use] extern crate nom;
@ -358,7 +358,7 @@ where
cond(b, f)(input)
}
/// tries to apply its parser without consuming the input
/// Tries to apply its parser without consuming the input.
///
/// ```rust
/// # #[macro_use] extern crate nom;
@ -394,7 +394,7 @@ where
peek(f)(input)
}
/// transforms Incomplete into Error
/// Transforms Incomplete into `Error`.
///
/// ```rust
/// # #[macro_use] extern crate nom;
@ -430,7 +430,7 @@ where
complete(f)(input)
}
/// succeeds if all the input has been consumed by its child parser
/// Succeeds if all the input has been consumed by its child parser.
///
/// ```rust
/// # #[macro_use] extern crate nom;
@ -461,10 +461,10 @@ where
}
}
/// returns the result of the child parser if it satisfies a verification function
/// Returns the result of the child parser if it satisfies a verification function.
///
/// the verification function takes as argument a reference to the output of the
/// parser
/// The verification function takes as argument a reference to the output of the
/// parser.
///
/// ```rust
/// # #[macro_use] extern crate nom;
@ -517,7 +517,7 @@ where
verify(first, second)(input)
}
/// returns the provided value if the child parser succeeds
/// Returns the provided value if the child parser succeeds.
///
/// ```rust
/// # #[macro_use] extern crate nom;
@ -554,7 +554,7 @@ where
value(val, parser)(input)
}
/// succeeds if the child parser returns an error
/// Succeeds if the child parser returns an error.
///
/// ```rust
/// # #[macro_use] extern crate nom;
@ -591,7 +591,7 @@ where
not(parser)(input)
}
/// if the child parser was successful, return the consumed input as produced value
/// If the child parser was successful, return the consumed input as produced value.
///
/// ```rust
/// # #[macro_use] extern crate nom;
@ -636,7 +636,7 @@ where
recognize(parser)(input)
}
/// transforms an error to failure
/// Transforms an error to failure.
///
/// ```rust
/// # #[macro_use] extern crate nom;
@ -669,10 +669,10 @@ where
cut(parser)(input)
}
/// creates an iterator from input data and a parser
/// Creates an iterator from input data and a parser.
///
/// call the iterator's [finish] method to get the remaining input if successful,
/// or the error value if we encountered an error
/// Call the iterator's [finish] method to get the remaining input if successful,
/// or the error value if we encountered an error.
///
/// ```rust
/// use nom::{combinator::iterator, IResult, bytes::complete::tag, character::complete::alpha1, sequence::terminated};
@ -699,7 +699,7 @@ where
}
}
/// main structure associated to the [iterator] function
/// Main structure associated to the [iterator] function.
pub struct ParserIterator<I, E, F> {
iterator: F,
input: I,
@ -707,7 +707,7 @@ pub struct ParserIterator<I, E, F> {
}
impl<I: Clone, E, F> ParserIterator<I, E, F> {
/// returns the remaining input if parsing was successful, or the error if we encountered an error
/// Returns the remaining input if parsing was successful, or the error if we encountered an error.
pub fn finish(mut self) -> IResult<I, (), E> {
match self.state.take().unwrap() {
State::Running | State::Done => Ok((self.input.clone(), ())),

54
src/error.rs
View File

@ -5,38 +5,38 @@
use crate::internal::Parser;
/// this trait must be implemented by the error type of a nom parser
/// This trait must be implemented by the error type of a nom parser.
///
/// There are already implementations of it for `(Input, ErrorKind)`
/// and `VerboseError<Input>`.
///
/// It provides methods to create an error from some combinators,
/// and combine existing errors in combinators like `alt`
/// and combine existing errors in combinators like `alt`.
pub trait ParseError<I>: Sized {
/// creates an error from the input position and an [ErrorKind]
/// Creates an error from the input position and an [ErrorKind]
fn from_error_kind(input: I, kind: ErrorKind) -> Self;
/// combines an existing error with a new one created from the input
/// Combines an existing error with a new one created from the input
/// position and an [ErrorKind]. This is useful when backtracking
/// through a parse tree, accumulating error context on the way
fn append(input: I, kind: ErrorKind, other: Self) -> Self;
/// creates an error from an input position and an expected character
/// Creates an error from an input position and an expected character
fn from_char(input: I, _: char) -> Self {
Self::from_error_kind(input, ErrorKind::Char)
}
/// combines two existing error. This function is used to compare errors
/// Combines two existing errors. This function is used to compare errors
/// generated in various branches of [alt]
fn or(self, other: Self) -> Self {
other
}
}
/// this trait is required by the `context` combinator to add a static string
/// This trait is required by the `context` combinator to add a static string
/// to an existing error
pub trait ContextError<I>: Sized {
/// create a new error from an input position, a static string and an existing error.
/// Create a new error from an input position, a static string and an existing error.
/// This is used mainly in the [context] combinator, to add user friendly information
/// to errors when backtracking through a parse tree
fn add_context(_input: I, _ctx: &'static str, other: Self) -> Self {
@ -64,38 +64,38 @@ impl<I> ParseError<I> for () {
impl<I> ContextError<I> for () {}
/// creates an error from the input position and an [ErrorKind]
/// Creates an error from the input position and an [ErrorKind]
pub fn make_error<I, E: ParseError<I>>(input: I, kind: ErrorKind) -> E {
E::from_error_kind(input, kind)
}
/// combines an existing error with a new one created from the input
/// Combines an existing error with a new one created from the input
/// position and an [ErrorKind]. This is useful when backtracking
/// through a parse tree, accumulating error context on the way
pub fn append_error<I, E: ParseError<I>>(input: I, kind: ErrorKind, other: E) -> E {
E::append(input, kind, other)
}
/// this error type accumulates errors and their position when backtracking
/// This error type accumulates errors and their position when backtracking
/// through a parse tree. With some post processing (cf `examples/json.rs`),
/// it can be used to display user friendly error messages
#[cfg(feature = "alloc")]
#[derive(Clone, Debug, PartialEq)]
pub struct VerboseError<I> {
/// list of errors accumulated by `VerboseError`, containing the affected
/// List of errors accumulated by `VerboseError`, containing the affected
/// part of input data, and some context
pub errors: crate::lib::std::vec::Vec<(I, VerboseErrorKind)>,
}
#[cfg(feature = "alloc")]
#[derive(Clone, Debug, PartialEq)]
/// error context for `VerboseError`
/// Error context for `VerboseError`
pub enum VerboseErrorKind {
/// static string added by the `context` function
/// Static string added by the `context` function
Context(&'static str),
/// indicates which character was expected by the `char` function
/// Indicates which character was expected by the `char` function
Char(char),
/// error kind given by various nom parsers
/// Error kind given by various nom parsers
Nom(ErrorKind),
}
@ -129,7 +129,7 @@ impl<I> ContextError<I> for VerboseError<I> {
use crate::internal::{Err, IResult};
/// create a new error from an input position, a static string and an existing error.
/// Create a new error from an input position, a static string and an existing error.
/// This is used mainly in the [context] combinator, to add user friendly information
/// to errors when backtracking through a parse tree
pub fn context<I: Clone, E: ContextError<I>, F, O>(
@ -147,7 +147,7 @@ where
}
}
/// transforms a `VerboseError` into a trace with input position information
/// Transforms a `VerboseError` into a trace with input position information
#[cfg(feature = "alloc")]
pub fn convert_error(input: &str, e: VerboseError<&str>) -> crate::lib::std::string::String {
use crate::lib::std::fmt::Write;
@ -257,7 +257,7 @@ pub fn convert_error(input: &str, e: VerboseError<&str>) -> crate::lib::std::str
result
}
/// indicates which parser returned an error
/// Indicates which parser returned an error
#[cfg_attr(rustfmt, rustfmt_skip)]
#[derive(Debug,PartialEq,Eq,Hash,Clone,Copy)]
#[allow(deprecated,missing_docs)]
@ -318,7 +318,7 @@ pub enum ErrorKind {
#[cfg_attr(rustfmt, rustfmt_skip)]
#[allow(deprecated)]
/// converts an ErrorKind to a number
/// Converts an ErrorKind to a number
pub fn error_to_u32(e: &ErrorKind) -> u32 {
match *e {
ErrorKind::Tag => 1,
@ -379,7 +379,7 @@ pub fn error_to_u32(e: &ErrorKind) -> u32 {
impl ErrorKind {
#[cfg_attr(rustfmt, rustfmt_skip)]
#[allow(deprecated)]
/// converts an ErrorKind to a text description
/// Converts an ErrorKind to a text description
pub fn description(&self) -> &str {
match *self {
ErrorKind::Tag => "Tag",
@ -438,7 +438,7 @@ impl ErrorKind {
}
}
/// creates a parse error from a `nom::ErrorKind`
/// Creates a parse error from a `nom::ErrorKind`
/// and the position in the input
#[allow(unused_variables)]
#[macro_export(local_inner_macros)]
@ -448,9 +448,9 @@ macro_rules! error_position(
});
);
/// creates a parse error from a `nom::ErrorKind`,
/// Creates a parse error from a `nom::ErrorKind`,
/// the position in the input and the next error in
/// the parsing tree.
/// the parsing tree
#[allow(unused_variables)]
#[macro_export(local_inner_macros)]
macro_rules! error_node_position(
@ -545,9 +545,9 @@ macro_rules! fix_error (
/// `flat_map!(R -> IResult<R,S>, S -> IResult<S,T>) => R -> IResult<R, T>`
///
/// combines a parser R -> IResult<R,S> and
/// a parser S -> IResult<S,T> to return another
/// parser R -> IResult<R,T>
/// Combines a parser `R -> IResult<R,S>` and
/// a parser `S -> IResult<S,T>` to return another
/// parser `R -> IResult<R,T>`
///
/// ```rust
/// # #[macro_use] extern crate nom;

41
src/internal.rs
View File

@ -11,20 +11,19 @@ use core::num::NonZeroUsize;
///
/// The `Ok` side is a pair containing the remainder of the input (the part of the data that
/// was not parsed) and the produced value. The `Err` side contains an instance of `nom::Err`.
///
pub type IResult<I, O, E = (I, ErrorKind)> = Result<(I, O), Err<E>>;
/// Contains information on needed data if a parser returned `Incomplete`
#[derive(Debug, PartialEq, Eq, Clone, Copy)]
pub enum Needed {
/// needs more data, but we do not know how much
/// Needs more data, but we do not know how much
Unknown,
/// contains the required data size
/// Contains the required data size
Size(NonZeroUsize),
}
impl Needed {
/// creates Needed instance, returns `Needed::Unknown` if the argument is zero
/// Creates `Needed` instance, returns `Needed::Unknown` if the argument is zero
pub fn new(s: usize) -> Self {
match NonZeroUsize::new(s) {
Some(sz) => Needed::Size(sz),
@ -32,7 +31,7 @@ impl Needed {
}
}
/// indicates if we know how many bytes we need
/// Indicates if we know how many bytes we need
pub fn is_known(&self) -> bool {
*self != Unknown
}
@ -74,7 +73,7 @@ pub enum Err<E> {
}
impl<E> Err<E> {
/// tests if the result is Incomplete
/// Tests if the result is Incomplete
pub fn is_incomplete(&self) -> bool {
if let Err::Incomplete(_) = self {
true
@ -95,7 +94,7 @@ impl<E> Err<E> {
}
}
/// automatically converts between errors if the underlying type supports it
/// Automatically converts between errors if the underlying type supports it
pub fn convert<F>(e: Err<F>) -> Self
where
E: From<F>,
@ -105,7 +104,7 @@ impl<E> Err<E> {
}
impl<T> Err<(T, ErrorKind)> {
/// maps `Err<(T, ErrorKind)>` to `Err<(U, ErrorKind)>` with the given F: T -> U
/// Maps `Err<(T, ErrorKind)>` to `Err<(U, ErrorKind)>` with the given `F: T -> U`
pub fn map_input<U, F>(self, f: F) -> Err<(U, ErrorKind)>
where
F: FnOnce(T) -> U,
@ -128,7 +127,7 @@ impl Err<(&[u8], ErrorKind)> {
#[cfg(feature = "std")]
impl Err<(&str, ErrorKind)> {
/// automatically converts between errors if the underlying type supports it
/// Automatically converts between errors if the underlying type supports it
pub fn to_owned(self) -> Err<(String, ErrorKind)> {
self.map_input(ToOwned::to_owned)
}
@ -167,13 +166,13 @@ where
}
}
/// all nom parsers implement ths trait
/// All nom parsers implement ths trait
pub trait Parser<I, O, E> {
/// a parser takes in input type, and returns a `Result` containing
/// A parser takes in input type, and returns a `Result` containing
/// either the remaining input and the output value, or an error
fn parse(&mut self, input: I) -> IResult<I, O, E>;
/// maps a function over the result of a parser
/// Maps a function over the result of a parser
fn map<G, O2>(self, g: G) -> Map<Self, G, O>
where
G: Fn(O) -> O2,
@ -186,7 +185,7 @@ pub trait Parser<I, O, E> {
}
}
/// creates a second parser from the output of the first one, then apply over the rest of the input
/// Creates a second parser from the output of the first one, then apply over the rest of the input
fn flat_map<G, H, O2>(self, g: G) -> FlatMap<Self, G, O>
where
G: Fn(O) -> H,
@ -200,7 +199,7 @@ pub trait Parser<I, O, E> {
}
}
/// applies a second parser over the output of the first one
/// Applies a second parser over the output of the first one
fn and_then<G, O2>(self, g: G) -> AndThen<Self, G, O>
where
G: Parser<O, O2, E>,
@ -213,7 +212,7 @@ pub trait Parser<I, O, E> {
}
}
/// applies a second parser after the first one, return their results as a tuple
/// Applies a second parser after the first one, return their results as a tuple
fn and<G, O2>(self, g: G) -> And<Self, G>
where
G: Parser<I, O2, E>,
@ -222,7 +221,7 @@ pub trait Parser<I, O, E> {
And { f: self, g }
}
/// applies a second parser over the input if the first one failed
/// Applies a second parser over the input if the first one failed
fn or<G>(self, g: G) -> Or<Self, G>
where
G: Parser<I, O, E>,
@ -241,7 +240,7 @@ where
}
}
/// implementation of Parser:::map
/// Implementation of `Parser:::map`
pub struct Map<F, G, O1> {
f: F,
g: G,
@ -257,7 +256,7 @@ impl<'a, I, O1, O2, E, F: Parser<I, O1, E>, G: Fn(O1) -> O2> Parser<I, O2, E> fo
}
}
/// implementation of Parser::flat_map
/// Implementation of `Parser::flat_map`
pub struct FlatMap<F, G, O1> {
f: F,
g: G,
@ -273,7 +272,7 @@ impl<'a, I, O1, O2, E, F: Parser<I, O1, E>, G: Fn(O1) -> H, H: Parser<I, O2, E>>
}
}
/// implementation of Parser::and_then
/// Implementation of `Parser::and_then`
pub struct AndThen<F, G, O1> {
f: F,
g: G,
@ -290,7 +289,7 @@ impl<'a, I, O1, O2, E, F: Parser<I, O1, E>, G: Parser<O1, O2, E>> Parser<I, O2,
}
}
/// implementation of Parser::and
/// Implementation of `Parser::and`
pub struct And<F, G> {
f: F,
g: G,
@ -306,7 +305,7 @@ impl<'a, I, O1, O2, E, F: Parser<I, O1, E>, G: Parser<I, O2, E>> Parser<I, (O1,
}
}
/// implementation of Parser::or
/// Implementation of `Parser::or`
pub struct Or<F, G> {
f: F,
g: G,

27
src/lib.rs
View File

@ -81,11 +81,11 @@
//!
//! This gives us a few advantages:
//!
//! - the parsers are small and easy to write
//! - the parsers components are easy to reuse (if they're general enough, please add them to nom!)
//! - the parsers components are easy to test separately (unit tests and property-based tests)
//! - the parser combination code looks close to the grammar you would have written
//! - you can build partial parsers, specific to the data you need at the moment, and ignore the rest
//! - The parsers are small and easy to write
//! - The parsers components are easy to reuse (if they're general enough, please add them to nom!)
//! - The parsers components are easy to test separately (unit tests and property-based tests)
//! - The parser combination code looks close to the grammar you would have written
//! - You can build partial parsers, specific to the data you need at the moment, and ignore the rest
//!
//! Here is an example of one such parser, to recognize text between parentheses:
//!
@ -187,14 +187,13 @@
//!
//! It can have the following values:
//!
//! - a correct result `Ok((I,O))` with the first element being the remaining of the input (not parsed yet), and the second the output value;
//! - an error `Err(Err::Error(c))` with `c` an error that can be built from the input position and a parser specific error
//! - an error `Err(Err::Incomplete(Needed))` indicating that more input is necessary. `Needed` can indicate how much data is needed
//! - an error `Err(Err::Failure(c))`. It works like the `Error` case, except it indicates an unrecoverable error: we cannot backtrack and test another parser
//! - A correct result `Ok((I,O))` with the first element being the remaining of the input (not parsed yet), and the second the output value;
//! - An error `Err(Err::Error(c))` with `c` an error that can be built from the input position and a parser specific error
//! - An error `Err(Err::Incomplete(Needed))` indicating that more input is necessary. `Needed` can indicate how much data is needed
//! - An error `Err(Err::Failure(c))`. It works like the `Error` case, except it indicates an unrecoverable error: We cannot backtrack and test another parser
//!
//! Please refer to the ["choose a combinator" guide](https://github.com/Geal/nom/blob/master/doc/choosing_a_combinator.md) for an exhaustive list of parsers.
//! See also the rest of the documentation [here](https://github.com/Geal/nom/blob/master/doc).
//! .
//!
//! ## Making new parsers with function combinators
//!
@ -276,9 +275,9 @@
//!
//! Here are some basic combining macros available:
//!
//! - **`opt`**: will make the parser optional (if it returns the `O` type, the new parser returns `Option<O>`)
//! - **`many0`**: will apply the parser 0 or more times (if it returns the `O` type, the new parser returns `Vec<O>`)
//! - **`many1`**: will apply the parser 1 or more times
//! - **`opt`**: Will make the parser optional (if it returns the `O` type, the new parser returns `Option<O>`)
//! - **`many0`**: Will apply the parser 0 or more times (if it returns the `O` type, the new parser returns `Vec<O>`)
//! - **`many1`**: Will apply the parser 1 or more times
//!
//! There are more complex (and more useful) parsers like `tuple!`, which is
//! used to apply a series of parsers then assemble their results.
@ -398,7 +397,7 @@
//! // while the complete version knows that all of the data is there
//! assert_eq!(alpha0_complete("abcd"), Ok(("", "abcd")));
//! ```
//! **Going further:** read the [guides](https://github.com/Geal/nom/tree/master/doc)!
//! **Going further:** Read the [guides](https://github.com/Geal/nom/tree/master/doc)!
#![cfg_attr(not(feature = "std"), no_std)]
#![cfg_attr(feature = "cargo-clippy", allow(doc_markdown))]
#![cfg_attr(nightly, feature(test))]

38
src/multi/macros.rs
View File

@ -1,7 +1,7 @@
//! Parsers for applying parsers multiple times
/// `separated_list0!(I -> IResult<I,T>, I -> IResult<I,O>) => I -> IResult<I, Vec<O>>`
/// separated_list0(sep, X) returns a Vec<X>
/// `separated_list0(sep, X)` returns a `Vec<X>`.
///
/// ```rust
/// # #[macro_use] extern crate nom;
@ -40,9 +40,9 @@ macro_rules! separated_list0(
);
/// `separated_list1!(I -> IResult<I,T>, I -> IResult<I,O>) => I -> IResult<I, Vec<O>>`
/// separated_list1(sep, X) returns a Vec<X>
/// `separated_list1(sep, X)` returns a `Vec<X>`.
///
/// it will return an error if there is no element in the list
/// It will return an error if there is no element in the list.
/// ```rust
/// # #[macro_use] extern crate nom;
/// # use nom::{Err, error::ErrorKind, Needed, IResult};
@ -80,9 +80,9 @@ macro_rules! separated_list1(
);
/// `many0!(I -> IResult<I,O>) => I -> IResult<I, Vec<O>>`
/// Applies the parser 0 or more times and returns the list of results in a Vec.
/// Applies the parser 0 or more times and returns the list of results in a `Vec`.
///
/// The embedded parser may return Incomplete.
/// The embedded parser may return `Incomplete`.
///
/// `many0` will only return `Error` if the embedded parser does not consume any input
/// (to avoid infinite loops).
@ -113,9 +113,9 @@ macro_rules! many0(
);
/// `many1!(I -> IResult<I,O>) => I -> IResult<I, Vec<O>>`
/// Applies the parser 1 or more times and returns the list of results in a Vec
/// Applies the parser 1 or more times and returns the list of results in a `Vec`.
///
/// the embedded parser may return Incomplete
/// The embedded parser may return `Incomplete`.
///
/// ```
/// # #[macro_use] extern crate nom;
@ -147,7 +147,7 @@ macro_rules! many1(
/// Applies the first parser until the second applies. Returns a tuple containing the list
/// of results from the first in a Vec and the result of the second.
///
/// The first embedded parser may return Incomplete
/// The first embedded parser may return `Incomplete`.
///
/// ```
/// # #[macro_use] extern crate nom;
@ -190,7 +190,7 @@ macro_rules! many_till(
/// `many_m_n!(usize, usize, I -> IResult<I,O>) => I -> IResult<I, Vec<O>>`
/// Applies the parser between m and n times (n included) and returns the list of
/// results in a Vec
/// results in a `Vec`.
///
/// the embedded parser may return Incomplete
///
@ -277,7 +277,7 @@ macro_rules! many1_count {
}
/// `count!(I -> IResult<I,O>, nb) => I -> IResult<I, Vec<O>>`
/// Applies the child parser a specified number of times
/// Applies the child parser a specified number of times.
///
/// ```
/// # #[macro_use] extern crate nom;
@ -307,7 +307,7 @@ macro_rules! count(
);
/// `length_count!(I -> IResult<I, nb>, I -> IResult<I,O>) => I -> IResult<I, Vec<O>>`
/// gets a number from the first parser, then applies the second parser that many times
/// Gets a number from the first parser, then applies the second parser that many times.
///
/// ```rust
/// # #[macro_use] extern crate nom;
@ -357,7 +357,7 @@ macro_rules! length_count(
/// `length_data!(I -> IResult<I, nb>) => O`
///
/// `length_data` gets a number from the first parser, then takes a subslice of the input
/// of that size and returns that subslice
/// of that size and returns that subslice.
///
/// ```rust
/// # #[macro_use] extern crate nom;
@ -386,7 +386,7 @@ macro_rules! length_data(
///
/// Gets a number from the first parser, takes a subslice of the input of that size,
/// then applies the second parser on that subslice. If the second parser returns
/// `Incomplete`, `length_value` will return an error
/// `Incomplete`, `length_value` will return an error.
///
/// ```rust
/// # #[macro_use] extern crate nom;
@ -422,9 +422,9 @@ macro_rules! length_value(
);
/// `fold_many0!(I -> IResult<I,O>, R, Fn(R, O) -> R) => I -> IResult<I, R>`
/// Applies the parser 0 or more times and folds the list of return values
/// Applies the parser 0 or more times and folds the list of return values.
///
/// the embedded parser may return Incomplete
/// The embedded parser may return `Incomplete`.
///
/// ```
/// # #[macro_use] extern crate nom;
@ -455,9 +455,9 @@ macro_rules! fold_many0(
);
/// `fold_many1!(I -> IResult<I,O>, R, Fn(R, O) -> R) => I -> IResult<I, R>`
/// Applies the parser 1 or more times and folds the list of return values
/// Applies the parser 1 or more times and folds the list of return values.
///
/// the embedded parser may return Incomplete
/// The embedded parser may return `Incomplete`.
///
/// ```
/// # #[macro_use] extern crate nom;
@ -492,9 +492,9 @@ macro_rules! fold_many1(
);
/// `fold_many_m_n!(usize, usize, I -> IResult<I,O>, R, Fn(R, O) -> R) => I -> IResult<I, R>`
/// Applies the parser between m and n times (n included) and folds the list of return value
/// Applies the parser between m and n times (n included) and folds the list of return value.
///
/// the embedded parser may return Incomplete
/// The embedded parser may return `Incomplete`.
///
/// ```
/// # #[macro_use] extern crate nom;

14
src/multi/mod.rs
View File

@ -1,4 +1,4 @@
//! combinators applying their child parser multiple times
//! Combinators applying their child parser multiple times
#[macro_use]
mod macros;
@ -80,9 +80,9 @@ where
/// # Arguments
/// * `f` The parser to apply.
///
/// *Note*: if the parser passed to `many1` accepts empty inputs
/// *Note*: If the parser passed to `many1` accepts empty inputs
/// (like `alpha0` or `digit0`), `many1` will return an error,
/// to prevent going into an infinite loop
/// to prevent going into an infinite loop.
///
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed, IResult};
@ -970,8 +970,8 @@ where
/// Gets a number from the parser and returns a
/// subslice of the input of that size.
/// If the parser returns Incomplete,
/// length_data will return an error.
/// If the parser returns `Incomplete`,
/// `length_data` will return an error.
/// # Arguments
/// * `f` The parser to apply.
/// ```rust
@ -1011,8 +1011,8 @@ where
/// Gets a number from the first parser,
/// takes a subslice of the input of that size,
/// then applies the second parser on that subslice.
/// If the second parser returns Incomplete,
/// length_value will return an error.
/// If the second parser returns `Incomplete`,
/// `length_value` will return an error.
/// # Arguments
/// * `f` The parser to apply.
/// ```rust

146
src/number/complete.rs
View File

@ -1,4 +1,4 @@
//! parsers recognizing numbers, complete input version
//! Parsers recognizing numbers, complete input version
use crate::branch::alt;
use crate::character::complete::{char, digit1};
@ -11,9 +11,9 @@ use crate::sequence::{pair, tuple};
use crate::traits::{AsChar, InputIter, InputLength, InputTakeAtPosition};
use crate::traits::{Offset, Slice};
/// Recognizes an unsigned 1 byte integer
/// Recognizes an unsigned 1 byte integer.
///
/// *complete version*: returns an error if there is not enough input data
/// *Complete version*: Returns an error if there is not enough input data.
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed};
/// # use nom::Needed::Size;
@ -41,9 +41,9 @@ where
}
}
/// Recognizes a big endian unsigned 2 bytes integer
/// Recognizes a big endian unsigned 2 bytes integer.
///
/// *complete version*: returns an error if there is not enough input data
/// *Complete version*: Returns an error if there is not enough input data.
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed};
/// # use nom::Needed::Size;
@ -74,9 +74,9 @@ where
}
}
/// Recognizes a big endian unsigned 3 byte integer
/// Recognizes a big endian unsigned 3 byte integer.
///
/// *complete version*: returns an error if there is not enough input data
/// *Complete version*: Returns an error if there is not enough input data.
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed};
/// # use nom::Needed::Size;
@ -107,9 +107,9 @@ where
}
}
/// Recognizes a big endian unsigned 4 bytes integer
/// Recognizes a big endian unsigned 4 bytes integer.
///
/// *complete version*: returns an error if there is not enough input data
/// *Complete version*: Returns an error if there is not enough input data.
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed};
/// # use nom::Needed::Size;
@ -140,9 +140,9 @@ where
}
}
/// Recognizes a big endian unsigned 8 bytes integer
/// Recognizes a big endian unsigned 8 bytes integer.
///
/// *complete version*: returns an error if there is not enough input data
/// *Complete version*: Returns an error if there is not enough input data.
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed};
/// # use nom::Needed::Size;
@ -173,9 +173,9 @@ where
}
}
/// Recognizes a big endian unsigned 16 bytes integer
/// Recognizes a big endian unsigned 16 bytes integer.
///
/// *complete version*: returns an error if there is not enough input data
/// *Complete version*: Returns an error if there is not enough input data.
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed};
/// # use nom::Needed::Size;
@ -207,9 +207,9 @@ where
}
}
/// Recognizes a signed 1 byte integer
/// Recognizes a signed 1 byte integer.
///
/// *complete version*: returns an error if there is not enough input data
/// *Complete version*: Returns an error if there is not enough input data.
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed};
/// # use nom::Needed::Size;
@ -230,9 +230,9 @@ where
map!(input, be_u8, |x| x as i8)
}
/// Recognizes a big endian signed 2 bytes integer
/// Recognizes a big endian signed 2 bytes integer.
///
/// *complete version*: returns an error if there is not enough input data
/// *Complete version*: Returns an error if there is not enough input data.
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed};
/// # use nom::Needed::Size;
@ -253,9 +253,9 @@ where
map!(input, be_u16, |x| x as i16)
}
/// Recognizes a big endian signed 3 bytes integer
/// Recognizes a big endian signed 3 bytes integer.
///
/// *complete version*: returns an error if there is not enough input data
/// *Complete version*: Returns an error if there is not enough input data.
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed};
/// # use nom::Needed::Size;
@ -281,9 +281,9 @@ where
})
}
/// Recognizes a big endian signed 4 bytes integer
/// Recognizes a big endian signed 4 bytes integer.
///
/// *complete version*: returns an error if there is not enough input data
/// *Complete version*: Teturns an error if there is not enough input data.
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed};
/// # use nom::Needed::Size;
@ -304,9 +304,9 @@ where
map!(input, be_u32, |x| x as i32)
}
/// Recognizes a big endian signed 8 bytes integer
/// Recognizes a big endian signed 8 bytes integer.
///
/// *complete version*: returns an error if there is not enough input data
/// *Complete version*: Returns an error if there is not enough input data.
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed};
/// # use nom::Needed::Size;
@ -327,9 +327,9 @@ where
map!(input, be_u64, |x| x as i64)
}
/// Recognizes a big endian signed 16 bytes integer
/// Recognizes a big endian signed 16 bytes integer.
///
/// *complete version*: returns an error if there is not enough input data
/// *Complete version*: Returns an error if there is not enough input data.
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed};
/// # use nom::Needed::Size;
@ -351,9 +351,9 @@ where
map!(input, be_u128, |x| x as i128)
}
/// Recognizes an unsigned 1 byte integer
/// Recognizes an unsigned 1 byte integer.
///
/// *complete version*: returns an error if there is not enough input data
/// *Complete version*: Returns an error if there is not enough input data.
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed};
/// # use nom::Needed::Size;
@ -381,9 +381,9 @@ where
}
}
/// Recognizes a little endian unsigned 2 bytes integer
/// Recognizes a little endian unsigned 2 bytes integer.
///
/// *complete version*: returns an error if there is not enough input data
/// *Complete version*: Returns an error if there is not enough input data.
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed};
/// # use nom::Needed::Size;
@ -414,9 +414,9 @@ where
}
}
/// Recognizes a little endian unsigned 3 byte integer
/// Recognizes a little endian unsigned 3 byte integer.
///
/// *complete version*: returns an error if there is not enough input data
/// *Complete version*: Returns an error if there is not enough input data.
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed};
/// # use nom::Needed::Size;
@ -447,9 +447,9 @@ where
}
}
/// Recognizes a little endian unsigned 4 bytes integer
/// Recognizes a little endian unsigned 4 bytes integer.
///
/// *complete version*: returns an error if there is not enough input data
/// *Complete version*: Returns an error if there is not enough input data.
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed};
/// # use nom::Needed::Size;
@ -480,9 +480,9 @@ where
}
}
/// Recognizes a little endian unsigned 8 bytes integer
/// Recognizes a little endian unsigned 8 bytes integer.
///
/// *complete version*: returns an error if there is not enough input data
/// *Complete version*: Returns an error if there is not enough input data.
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed};
/// # use nom::Needed::Size;
@ -513,9 +513,9 @@ where
}
}
/// Recognizes a little endian unsigned 16 bytes integer
/// Recognizes a little endian unsigned 16 bytes integer.
///
/// *complete version*: returns an error if there is not enough input data
/// *Complete version*: Returns an error if there is not enough input data.
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed};
/// # use nom::Needed::Size;
@ -547,9 +547,9 @@ where
}
}
/// Recognizes a signed 1 byte integer
/// Recognizes a signed 1 byte integer.
///
/// *complete version*: returns an error if there is not enough input data
/// *Complete version*: Returns an error if there is not enough input data.
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed};
/// # use nom::Needed::Size;
@ -570,9 +570,9 @@ where
map!(input, le_u8, |x| x as i8)
}
/// Recognizes a little endian signed 2 bytes integer
/// Recognizes a little endian signed 2 bytes integer.
///
/// *complete version*: returns an error if there is not enough input data
/// *Complete version*: Returns an error if there is not enough input data.
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed};
/// # use nom::Needed::Size;
@ -593,9 +593,9 @@ where
map!(input, le_u16, |x| x as i16)
}
/// Recognizes a little endian signed 3 bytes integer
/// Recognizes a little endian signed 3 bytes integer.
///
/// *complete version*: returns an error if there is not enough input data
/// *Complete version*: Returns an error if there is not enough input data.
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed};
/// # use nom::Needed::Size;
@ -621,9 +621,9 @@ where
})
}
/// Recognizes a little endian signed 4 bytes integer
/// Recognizes a little endian signed 4 bytes integer.
///
/// *complete version*: returns an error if there is not enough input data
/// *Complete version*: Returns an error if there is not enough input data.
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed};
/// # use nom::Needed::Size;
@ -644,9 +644,9 @@ where
map!(input, le_u32, |x| x as i32)
}
/// Recognizes a little endian signed 8 bytes integer
/// Recognizes a little endian signed 8 bytes integer.
///
/// *complete version*: returns an error if there is not enough input data
/// *Complete version*: Returns an error if there is not enough input data.
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed};
/// # use nom::Needed::Size;
@ -667,9 +667,9 @@ where
map!(input, le_u64, |x| x as i64)
}
/// Recognizes a little endian signed 16 bytes integer
/// Recognizes a little endian signed 16 bytes integer.
///
/// *complete version*: returns an error if there is not enough input data
/// *Complete version*: Returns an error if there is not enough input data.
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed};
/// # use nom::Needed::Size;
@ -691,9 +691,9 @@ where
map!(input, le_u128, |x| x as i128)
}
/// Recognizes a big endian 4 bytes floating point number
/// Recognizes a big endian 4 bytes floating point number.
///
/// *complete version*: returns an error if there is not enough input data
/// *Complete version*: Returns an error if there is not enough input data.
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed};
/// # use nom::Needed::Size;
@ -717,9 +717,9 @@ where
}
}
/// Recognizes a big endian 8 bytes floating point number
/// Recognizes a big endian 8 bytes floating point number.
///
/// *complete version*: returns an error if there is not enough input data
/// *Complete version*: Returns an error if there is not enough input data.
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed};
/// # use nom::Needed::Size;
@ -743,9 +743,9 @@ where
}
}
/// Recognizes a little endian 4 bytes floating point number
/// Recognizes a little endian 4 bytes floating point number.
///
/// *complete version*: returns an error if there is not enough input data
/// *Complete version*: Returns an error if there is not enough input data.
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed};
/// # use nom::Needed::Size;
@ -769,9 +769,9 @@ where
}
}
/// Recognizes a little endian 8 bytes floating point number
/// Recognizes a little endian 8 bytes floating point number.
///
/// *complete version*: returns an error if there is not enough input data
/// *Complete version*: Returns an error if there is not enough input data.
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed};
/// # use nom::Needed::Size;
@ -795,9 +795,9 @@ where
}
}
/// Recognizes a hex-encoded integer
/// Recognizes a hex-encoded integer.
///
/// *complete version*: will parse until the end of input if it has less than 8 bytes
/// *Complete version*: Will parse until the end of input if it has less than 8 bytes.
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed};
/// # use nom::Needed::Size;
@ -834,9 +834,9 @@ pub fn hex_u32<'a, E: ParseError<&'a [u8]>>(input: &'a [u8]) -> IResult<&'a [u8]
Ok((remaining, res))
}
/// Recognizes floating point number in a byte string and returns the corresponding slice
/// Recognizes floating point number in a byte string and returns the corresponding slice.
///
/// *complete version*: can parse until the end of input
/// *Complete version*: Can parse until the end of input.
///
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed};
@ -879,9 +879,9 @@ where
)(input)
}
/// Recognizes floating point number in a byte string and returns a f32
/// Recognizes floating point number in a byte string and returns a f32.
///
/// *complete version*: can parse until the end of input
/// *Complete version*: Can parse until the end of input.
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed};
/// # use nom::Needed::Size;
@ -915,12 +915,12 @@ where
}
}
/// Recognizes floating point number in a byte string and returns a f32
/// Recognizes floating point number in a byte string and returns a f32.
///
/// *complete version*: can parse until the end of input
/// *Complete version*: Can parse until the end of input.
///
/// this function uses the lexical-core crate for float parsing by default, you
/// can deactivate it by removing the "lexical" feature
/// This function uses the `lexical-core` crate for float parsing by default, you
/// can deactivate it by removing the "lexical" feature.
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed};
/// # use nom::Needed::Size;
@ -946,9 +946,9 @@ where
}
}
/// Recognizes floating point number in a byte string and returns a f64
/// Recognizes floating point number in a byte string and returns a f64.
///
/// *complete version*: can parse until the end of input
/// *Complete version*: Can parse until the end of input.
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed};
/// # use nom::Needed::Size;
@ -982,12 +982,12 @@ where
}
}
/// Recognizes floating point number in a byte string and returns a f64
/// Recognizes floating point number in a byte string and returns a f64.
///
/// *complete version*: can parse until the end of input
/// *Complete version*: Can parse until the end of input.
///
/// this function uses the lexical-core crate for float parsing by default, you
/// can deactivate it by removing the "lexical" feature
/// This function uses the `lexical-core` crate for float parsing by default, you
/// can deactivate it by removing the "lexical" feature.
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed};
/// # use nom::Needed::Size;

34
src/number/macros.rs
View File

@ -1,7 +1,7 @@
//! parsers recognizing numbers
//! Parsers recognizing numbers
/// if the parameter is nom::Endianness::Big, parse a big endian u16 integer,
/// otherwise a little endian u16 integer
/// If the parameter is `nom::Endianness::Big`, parse a big endian u16 integer,
/// otherwise a little endian u16 integer.
///
/// ```rust
/// # #[macro_use] extern crate nom;
@ -23,8 +23,8 @@
#[macro_export(local_inner_macros)]
macro_rules! u16 ( ($i:expr, $e:expr) => ( {if $crate::number::Endianness::Big == $e { $crate::number::streaming::be_u16($i) } else { $crate::number::streaming::le_u16($i) } } ););
/// if the parameter is nom::Endianness::Big, parse a big endian u32 integer,
/// otherwise a little endian u32 integer
/// If the parameter is `nom::Endianness::Big`, parse a big endian u32 integer,
/// otherwise a little endian u32 integer.
///
/// ```rust
/// # #[macro_use] extern crate nom;
@ -46,8 +46,8 @@ macro_rules! u16 ( ($i:expr, $e:expr) => ( {if $crate::number::Endianness::Big =
#[macro_export(local_inner_macros)]
macro_rules! u32 ( ($i:expr, $e:expr) => ( {if $crate::number::Endianness::Big == $e { $crate::number::streaming::be_u32($i) } else { $crate::number::streaming::le_u32($i) } } ););
/// if the parameter is nom::Endianness::Big, parse a big endian u64 integer,
/// otherwise a little endian u64 integer
/// If the parameter is `nom::Endianness::Big`, parse a big endian u64 integer,
/// otherwise a little endian u64 integer.
///
/// ```rust
/// # #[macro_use] extern crate nom;
@ -69,8 +69,8 @@ macro_rules! u32 ( ($i:expr, $e:expr) => ( {if $crate::number::Endianness::Big =
#[macro_export(local_inner_macros)]
macro_rules! u64 ( ($i:expr, $e:expr) => ( {if $crate::number::Endianness::Big == $e { $crate::number::streaming::be_u64($i) } else { $crate::number::streaming::le_u64($i) } } ););
/// if the parameter is nom::Endianness::Big, parse a big endian u128 integer,
/// otherwise a little endian u128 integer
/// If the parameter is `nom::Endianness::Big`, parse a big endian u128 integer,
/// otherwise a little endian u128 integer.
///
/// ```rust
/// # #[macro_use] extern crate nom;
@ -93,8 +93,8 @@ macro_rules! u64 ( ($i:expr, $e:expr) => ( {if $crate::number::Endianness::Big =
#[cfg(stable_i128)]
macro_rules! u128 ( ($i:expr, $e:expr) => ( {if $crate::number::Endianness::Big == $e { $crate::number::streaming::be_u128($i) } else { $crate::number::streaming::le_u128($i) } } ););
/// if the parameter is nom::Endianness::Big, parse a big endian i16 integer,
/// otherwise a little endian i16 integer
/// If the parameter is `nom::Endianness::Big`, parse a big endian i16 integer,
/// otherwise a little endian i16 integer.
///
/// ```rust
/// # #[macro_use] extern crate nom;
@ -116,8 +116,8 @@ macro_rules! u128 ( ($i:expr, $e:expr) => ( {if $crate::number::Endianness::Big
#[macro_export(local_inner_macros)]
macro_rules! i16 ( ($i:expr, $e:expr) => ( {if $crate::number::Endianness::Big == $e { $crate::number::streaming::be_i16($i) } else { $crate::number::streaming::le_i16($i) } } ););
/// if the parameter is nom::Endianness::Big, parse a big endian i32 integer,
/// otherwise a little endian i32 integer
/// If the parameter is `nom::Endianness::Big`, parse a big endian i32 integer,
/// otherwise a little endian i32 integer.
///
/// ```rust
/// # #[macro_use] extern crate nom;
@ -139,8 +139,8 @@ macro_rules! i16 ( ($i:expr, $e:expr) => ( {if $crate::number::Endianness::Big =
#[macro_export(local_inner_macros)]
macro_rules! i32 ( ($i:expr, $e:expr) => ( {if $crate::number::Endianness::Big == $e { $crate::number::streaming::be_i32($i) } else { $crate::number::streaming::le_i32($i) } } ););
/// if the parameter is nom::Endianness::Big, parse a big endian i64 integer,
/// otherwise a little endian i64 integer
/// If the parameter is `nom::Endianness::Big`, parse a big endian i64 integer,
/// otherwise a little endian i64 integer.
///
/// ```rust
/// # #[macro_use] extern crate nom;
@ -162,8 +162,8 @@ macro_rules! i32 ( ($i:expr, $e:expr) => ( {if $crate::number::Endianness::Big =
#[macro_export(local_inner_macros)]
macro_rules! i64 ( ($i:expr, $e:expr) => ( {if $crate::number::Endianness::Big == $e { $crate::number::streaming::be_i64($i) } else { $crate::number::streaming::le_i64($i) } } ););
/// if the parameter is nom::Endianness::Big, parse a big endian i64 integer,
/// otherwise a little endian i64 integer
/// If the parameter is `nom::Endianness::Big`, parse a big endian i64 integer,
/// otherwise a little endian i64 integer.
///
/// ```rust
/// # #[macro_use] extern crate nom;

6
src/number/mod.rs
View File

@ -1,4 +1,4 @@
//! parsers recognizing numbers
//! Parsers recognizing numbers
#[macro_use]
mod macros;
@ -9,8 +9,8 @@ pub mod streaming;
/// Configurable endianness
#[derive(Debug, PartialEq, Eq, Clone, Copy)]
pub enum Endianness {
/// big endian
/// Big endian
Big,
/// little endian
/// Little endian
Little,
}

138
src/number/streaming.rs
View File

@ -1,4 +1,4 @@
//! parsers recognizing numbers, streaming version
//! Parsers recognizing numbers, streaming version
use crate::branch::alt;
use crate::character::streaming::{char, digit1};
@ -10,9 +10,9 @@ use crate::sequence::{pair, tuple};
use crate::traits::{AsChar, InputIter, InputLength, InputTakeAtPosition};
use crate::traits::{Offset, Slice};
/// Recognizes an unsigned 1 byte integer
/// Recognizes an unsigned 1 byte integer.
///
/// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if there is not enough data
/// *Streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there is not enough data.
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed};
/// use nom::number::streaming::be_u8;
@ -39,9 +39,9 @@ where
}
}
/// Recognizes a big endian unsigned 2 bytes integer
/// Recognizes a big endian unsigned 2 bytes integer.
///
/// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if there is not enough data
/// *Streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there is not enough data.
///
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed};
@ -72,9 +72,9 @@ where
}
}
/// Recognizes a big endian unsigned 3 byte integer
/// Recognizes a big endian unsigned 3 byte integer.
///
/// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if there is not enough data
/// *Streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there is not enough data.
///
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed};
@ -105,9 +105,9 @@ where
}
}
/// Recognizes a big endian unsigned 4 bytes integer
/// Recognizes a big endian unsigned 4 bytes integer.
///
/// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if there is not enough data
/// *Streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there is not enough data.
///
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed};
@ -138,9 +138,9 @@ where
}
}
/// Recognizes a big endian unsigned 8 bytes integer
/// Recognizes a big endian unsigned 8 bytes integer.
///
/// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if there is not enough data
/// *Streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there is not enough data.
///
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed};
@ -171,9 +171,9 @@ where
}
}
/// Recognizes a big endian unsigned 16 bytes integer
/// Recognizes a big endian unsigned 16 bytes integer.
///
/// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if there is not enough data
/// *Streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there is not enough data.
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed};
/// use nom::number::streaming::be_u128;
@ -204,9 +204,9 @@ where
}
}
/// Recognizes a signed 1 byte integer
/// Recognizes a signed 1 byte integer.
///
/// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if there is not enough data
/// *Streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there is not enough data.
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed};
/// use nom::number::streaming::be_i8;
@ -224,9 +224,9 @@ where
map!(input, be_u8, |x| x as i8)
}
/// Recognizes a big endian signed 2 bytes integer
/// Recognizes a big endian signed 2 bytes integer.
///
/// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if there is not enough data
/// *Streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there is not enough data.
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed};
/// use nom::number::streaming::be_i16;
@ -244,9 +244,9 @@ where
map!(input, be_u16, |x| x as i16)
}
/// Recognizes a big endian signed 3 bytes integer
/// Recognizes a big endian signed 3 bytes integer.
///
/// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if there is not enough data
/// *Streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there is not enough data.
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed};
/// use nom::number::streaming::be_i24;
@ -269,9 +269,9 @@ where
})
}
/// Recognizes a big endian signed 4 bytes integer
/// Recognizes a big endian signed 4 bytes integer.
///
/// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if there is not enough data
/// *Streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there is not enough data.
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed};
/// use nom::number::streaming::be_i32;
@ -289,9 +289,9 @@ where
map!(input, be_u32, |x| x as i32)
}
/// Recognizes a big endian signed 8 bytes integer
/// Recognizes a big endian signed 8 bytes integer.
///
/// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if there is not enough data
/// *Streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there is not enough data.
///
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed};
@ -310,9 +310,9 @@ where
map!(input, be_u64, |x| x as i64)
}
/// Recognizes a big endian signed 16 bytes integer
/// Recognizes a big endian signed 16 bytes integer.
///
/// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if there is not enough data
/// *Streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there is not enough data.
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed};
/// use nom::number::streaming::be_i128;
@ -331,9 +331,9 @@ where
map!(input, be_u128, |x| x as i128)
}
/// Recognizes an unsigned 1 byte integer
/// Recognizes an unsigned 1 byte integer.
///
/// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if there is not enough data
/// *Streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there is not enough data.
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed};
/// use nom::number::streaming::le_u8;
@ -358,9 +358,9 @@ where
}
}
/// Recognizes a little endian unsigned 2 bytes integer
/// Recognizes a little endian unsigned 2 bytes integer.
///
/// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if there is not enough data
/// *Streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there is not enough data.
///
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed};
@ -391,9 +391,9 @@ where
}
}
/// Recognizes a little endian unsigned 3 bytes integer
/// Recognizes a little endian unsigned 3 bytes integer.
///
/// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if there is not enough data
/// *Streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there is not enough data.
///
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed};
@ -424,9 +424,9 @@ where
}
}
/// Recognizes a little endian unsigned 4 bytes integer
/// Recognizes a little endian unsigned 4 bytes integer.
///
/// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if there is not enough data
/// *Streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there is not enough data.
///
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed};
@ -457,9 +457,9 @@ where
}
}
/// Recognizes a little endian unsigned 8 bytes integer
/// Recognizes a little endian unsigned 8 bytes integer.
///
/// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if there is not enough data
/// *Streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there is not enough data.
///
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed};
@ -490,9 +490,9 @@ where
}
}
/// Recognizes a little endian unsigned 16 bytes integer
/// Recognizes a little endian unsigned 16 bytes integer.
///
/// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if there is not enough data
/// *Streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there is not enough data.
///
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed};
@ -524,9 +524,9 @@ where
}
}
/// Recognizes a signed 1 byte integer
/// Recognizes a signed 1 byte integer.
///
/// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if there is not enough data
/// *Streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there is not enough data.
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed};
/// use nom::number::streaming::le_i8;
@ -544,9 +544,9 @@ where
map!(input, le_u8, |x| x as i8)
}
/// Recognizes a little endian signed 2 bytes integer
/// Recognizes a little endian signed 2 bytes integer.
///
/// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if there is not enough data
/// *Streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there is not enough data.
///
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed};
@ -567,9 +567,9 @@ where
map!(input, le_u16, |x| x as i16)
}
/// Recognizes a little endian signed 3 bytes integer
/// Recognizes a little endian signed 3 bytes integer.
///
/// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if there is not enough data
/// *Streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there is not enough data.
///
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed};
@ -595,9 +595,9 @@ where
})
}
/// Recognizes a little endian signed 4 bytes integer
/// Recognizes a little endian signed 4 bytes integer.
///
/// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if there is not enough data
/// *Streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there is not enough data.
///
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed};
@ -618,9 +618,9 @@ where
map!(input, le_u32, |x| x as i32)
}
/// Recognizes a little endian signed 8 bytes integer
/// Recognizes a little endian signed 8 bytes integer.
///
/// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if there is not enough data
/// *Streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there is not enough data.
///
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed};
@ -641,9 +641,9 @@ where
map!(input, le_u64, |x| x as i64)
}
/// Recognizes a little endian signed 16 bytes integer
/// Recognizes a little endian signed 16 bytes integer.
///
/// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if there is not enough data
/// *Streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there is not enough data.
///
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed};
@ -665,9 +665,9 @@ where
map!(input, le_u128, |x| x as i128)
}
/// Recognizes a big endian 4 bytes floating point number
/// Recognizes a big endian 4 bytes floating point number.
///
/// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if there is not enough data
/// *Streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there is not enough data.
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed};
/// use nom::number::streaming::be_f32;
@ -690,9 +690,9 @@ where
}
}
/// Recognizes a big endian 8 bytes floating point number
/// Recognizes a big endian 8 bytes floating point number.
///
/// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if there is not enough data
/// *Streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there is not enough data.
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed};
/// use nom::number::streaming::be_f64;
@ -715,9 +715,9 @@ where
}
}
/// Recognizes a little endian 4 bytes floating point number
/// Recognizes a little endian 4 bytes floating point number.
///
/// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if there is not enough data
/// *Streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there is not enough data.
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed};
/// use nom::number::streaming::le_f32;
@ -740,9 +740,9 @@ where
}
}
/// Recognizes a little endian 8 bytes floating point number
/// Recognizes a little endian 8 bytes floating point number.
///
/// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if there is not enough data
/// *Streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there is not enough data.
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed};
/// use nom::number::streaming::le_f64;
@ -765,9 +765,9 @@ where
}
}
/// Recognizes a hex-encoded integer
/// Recognizes a hex-encoded integer.
///
/// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if there is not enough data
/// *Streaming version*: Will return `Err(nom::Err::Incomplete(_))` if there is not enough data.
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed};
/// use nom::number::streaming::hex_u32;
@ -804,9 +804,9 @@ pub fn hex_u32<'a, E: ParseError<&'a [u8]>>(input: &'a [u8]) -> IResult<&'a [u8]
Ok((remaining, res))
}
/// Recognizes a floating point number in text format and returns the corresponding part of the input
/// Recognizes a floating point number in text format and returns the corresponding part of the input.
///
/// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if it reaches the end of input
/// *Streaming version*: Will return `Err(nom::Err::Incomplete(_))` if it reaches the end of input.
///
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed};
@ -848,9 +848,9 @@ where
)(input)
}
/// Recognizes floating point number in a byte string and returns a f32
/// Recognizes floating point number in a byte string and returns a `f32`.
///
/// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if it reaches the end of input
/// *Streaming version*: Will return `Err(nom::Err::Incomplete(_))` if it reaches the end of input.
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed};
/// use nom::number::streaming::float;
@ -883,9 +883,9 @@ where
}
}
/// Recognizes floating point number in a byte string and returns a f32
/// Recognizes floating point number in a byte string and returns a `f32`.
///
/// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if it reaches the end of input
/// *Streaming version*: Will return `Err(nom::Err::Incomplete(_))` if it reaches the end of input.
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed};
/// use nom::number::streaming::float;
@ -919,9 +919,9 @@ where
}
}
/// Recognizes floating point number in a byte string and returns a f64
/// Recognizes floating point number in a byte string and returns a `f64`.
///
/// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if it reaches the end of input
/// *Streaming version*: Will return `Err(nom::Err::Incomplete(_))` if it reaches the end of input.
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed};
/// use nom::number::streaming::double;
@ -954,9 +954,9 @@ where
}
}
/// Recognizes floating point number in a byte string and returns a f64
/// Recognizes floating point number in a byte string and returns a `f64`.
///
/// *streaming version*: will return `Err(nom::Err::Incomplete(_))` if it reaches the end of input
/// *Streaming version*: Will return `Err(nom::Err::Incomplete(_))` if it reaches the end of input.
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed};
/// use nom::number::streaming::double;

40
src/regexp/macros.rs
View File

@ -1,7 +1,7 @@
/// `re_match!(regexp) => &[T] -> IResult<&[T], &[T]>`
/// Returns the whole input if a match is found
/// Returns the whole input if a match is found.
///
/// requires the `regexp` feature
/// Requires the `regexp` feature.
#[macro_export(local_inner_macros)]
macro_rules! re_match (
($i:expr, $re:expr) => ( {
@ -11,9 +11,9 @@ macro_rules! re_match (
);
/// `re_bytes_match!(regexp) => &[T] -> IResult<&[T], &[T]>`
/// Returns the whole input if a match is found
/// Returns the whole input if a match is found.
///
/// requires the `regexp` feature
/// Requires the `regexp` feature.
#[macro_export(local_inner_macros)]
macro_rules! re_bytes_match (
($i:expr, $re:expr) => ( {
@ -23,9 +23,9 @@ macro_rules! re_bytes_match (
);
/// `re_find!(regexp) => &[T] -> IResult<&[T], &[T]>`
/// Returns the first match
/// Returns the first match.
///
/// requires the `regexp` feature
/// Requires the `regexp` feature.
#[macro_export(local_inner_macros)]
macro_rules! re_find (
($i:expr, $re:expr) => ( {
@ -35,9 +35,9 @@ macro_rules! re_find (
);
/// `re_bytes_find!(regexp) => &[T] -> IResult<&[T], &[T]>`
/// Returns the first match
/// Returns the first match.
///
/// requires the `regexp` feature
/// Requires the `regexp` feature.
#[macro_export(local_inner_macros)]
macro_rules! re_bytes_find (
($i:expr, $re:expr) => ( {
@ -47,9 +47,9 @@ macro_rules! re_bytes_find (
);
/// `re_matches!(regexp) => &[T] -> IResult<&[T], Vec<&[T]>>`
/// Returns all the matched parts
/// Returns all the matched parts.
///
/// requires the `regexp` feature
/// Requires the `regexp` feature.
#[macro_export(local_inner_macros)]
macro_rules! re_matches (
($i:expr, $re:expr) => ( {
@ -59,9 +59,9 @@ macro_rules! re_matches (
);
/// `re_bytes_matches!(regexp) => &[T] -> IResult<&[T], Vec<&[T]>>`
/// Returns all the matched parts
/// Returns all the matched parts.
///
/// requires the `regexp` feature
/// Requires the `regexp` feature.
#[macro_export(local_inner_macros)]
macro_rules! re_bytes_matches (
($i:expr, $re:expr) => ( {
@ -71,9 +71,9 @@ macro_rules! re_bytes_matches (
);
/// `re_capture!(regexp) => &[T] -> IResult<&[T], Vec<&[T]>>`
/// Returns the capture groups of the first match
/// Returns the capture groups of the first match.
///
/// requires the `regexp` feature
/// Requires the `regexp` feature.
#[macro_export(local_inner_macros)]
macro_rules! re_capture (
($i:expr, $re:expr) => ( {
@ -83,9 +83,9 @@ macro_rules! re_capture (
);
/// `re_bytes_capture!(regexp) => &[T] -> IResult<&[T], Vec<&[T]>>`
/// Returns the capture groups of the first match
/// Returns the capture groups of the first match.
///
/// requires the `regexp` feature
/// Requires the `regexp` feature.
#[macro_export(local_inner_macros)]
macro_rules! re_bytes_capture (
($i:expr, $re:expr) => ( {
@ -96,9 +96,9 @@ macro_rules! re_bytes_capture (
);
/// `re_captures!(regexp) => &[T] -> IResult<&[T], Vec<Vec<&[T]>>>`
/// Returns the capture groups of all matches
/// Returns the capture groups of all matches.
///
/// requires the `regexp` feature
/// Requires the `regexp` feature.
#[macro_export(local_inner_macros)]
macro_rules! re_captures (
($i:expr, $re:expr) => ( {
@ -108,9 +108,9 @@ macro_rules! re_captures (
);
/// `re_bytes_captures!(regexp) => &[T] -> IResult<&[T], Vec<Vec<&[T]>>>`
/// Returns the capture groups of all matches
/// Returns the capture groups of all matches.
///
/// requires the `regexp` feature
/// Requires the `regexp` feature.
#[macro_export(local_inner_macros)]
macro_rules! re_bytes_captures (
($i:expr, $re:expr) => ( {

24
src/sequence/macros.rs
View File

@ -4,7 +4,7 @@
/// The input type `I` must implement `nom::InputLength`.
///
/// This combinator will count how much data is consumed by every child parser
/// and take it into account if there is not enough data
/// and take it into account if there is not enough data.
///
/// ```
/// # #[macro_use] extern crate nom;
@ -38,7 +38,7 @@ macro_rules! tuple (
);
);
/// Internal parser, do not use directly
/// Internal parser, do not use directly.
#[doc(hidden)]
#[macro_export(local_inner_macros)]
macro_rules! tuple_parser (
@ -88,7 +88,7 @@ macro_rules! tuple_parser (
);
/// `pair!(I -> IResult<I,O>, I -> IResult<I,P>) => I -> IResult<I, (O,P)>`
/// pair returns a tuple of the results of its two child parsers of both succeed
/// `pair` returns a tuple of the results of its two child parsers of both succeed.
///
/// ```
/// # #[macro_use] extern crate nom;
@ -123,8 +123,8 @@ macro_rules! pair(
);
/// `separated_pair!(I -> IResult<I,O>, I -> IResult<I, T>, I -> IResult<I,P>) => I -> IResult<I, (O,P)>`
/// separated_pair(X,sep,Y) returns a tuple of its first and third child parsers
/// if all 3 succeed
/// `separated_pair(X,sep,Y)` returns a tuple of its first and third child parsers
/// if all 3 succeed.
///
/// ```
/// # #[macro_use] extern crate nom;
@ -156,7 +156,7 @@ macro_rules! separated_pair(
);
/// `preceded!(I -> IResult<I,T>, I -> IResult<I,O>) => I -> IResult<I, O>`
/// preceded returns the result of its second parser if both succeed
/// `preceded` returns the result of its second parser if both succeed.
///
/// ```
/// # #[macro_use] extern crate nom;
@ -191,7 +191,7 @@ macro_rules! preceded(
);
/// `terminated!(I -> IResult<I,O>, I -> IResult<I,T>) => I -> IResult<I, O>`
/// terminated returns the result of its first parser if both succeed
/// `terminated` returns the result of its first parser if both succeed.
///
/// ```
/// # #[macro_use] extern crate nom;
@ -226,7 +226,7 @@ macro_rules! terminated(
);
/// `delimited!(I -> IResult<I,T>, I -> IResult<I,O>, I -> IResult<I,U>) => I -> IResult<I, O>`
/// delimited(opening, X, closing) returns X
/// `delimited(opening, X, closing)` returns X.
///
/// ```
/// # #[macro_use] extern crate nom;
@ -261,14 +261,14 @@ macro_rules! delimited(
);
/// `do_parse!(I->IResult<I,A> >> I->IResult<I,B> >> ... I->IResult<I,X> , ( O ) ) => I -> IResult<I, O>`
/// do_parse applies sub parsers in a sequence.
/// it can store intermediary results and make them available
/// for later parsers
/// `do_parse` applies sub parsers in a sequence.
/// It can store intermediary results and make them available
/// for later parsers.
///
/// The input type `I` must implement `nom::InputLength`.
///
/// This combinator will count how much data is consumed by every child parser
/// and take it into account if there is not enough data
/// and take it into account if there is not enough data.
///
/// ```
/// # #[macro_use] extern crate nom;

10
src/sequence/mod.rs
View File

@ -1,4 +1,4 @@
//! combinators applying parsers in sequence
//! Combinators applying parsers in sequence
#[macro_use]
mod macros;
@ -255,11 +255,11 @@ where
delimited(first, sep, second)(input)
}
/// helper trait for the tuple combinator
/// Helper trait for the tuple combinator.
///
/// this trait is implemented for tuples of parsers of up to 21 elements
/// This trait is implemented for tuples of parsers of up to 21 elements.
pub trait Tuple<I, O, E> {
/// parses the input and returns a tuple of results of each parser
/// Parses the input and returns a tuple of results of each parser.
fn parse(&mut self, input: I) -> IResult<I, O, E>;
}
@ -321,7 +321,7 @@ macro_rules! tuple_trait_inner(
tuple_trait!(FnA A, FnB B, FnC C, FnD D, FnE E, FnF F, FnG G, FnH H, FnI I, FnJ J, FnK K, FnL L,
FnM M, FnN N, FnO O, FnP P, FnQ Q, FnR R, FnS S, FnT T, FnU U);
/// applies a tuple of parsers one by one and returns their results as a tuple
///Aapplies a tuple of parsers one by one and returns their results as a tuple.
///
/// ```rust
/// # use nom::{Err, error::ErrorKind};

147
src/traits.rs
View File

@ -1,5 +1,4 @@
//! Traits input types have to implement to work with nom combinators
//!
use crate::error::{ErrorKind, ParseError};
use crate::internal::{Err, IResult, Needed};
use crate::lib::std::iter::Enumerate;
@ -17,9 +16,9 @@ use crate::lib::std::string::String;
#[cfg(feature = "alloc")]
use crate::lib::std::vec::Vec;
/// abstract method to calculate the input length
/// Abstract method to calculate the input length
pub trait InputLength {
/// calculates the input length, as indicated by its name,
/// Calculates the input length, as indicated by its name,
/// and the name of the trait itself
fn input_len(&self) -> usize;
}
@ -47,9 +46,9 @@ impl<'a> InputLength for (&'a [u8], usize) {
}
}
/// useful functions to calculate the offset between slices and show a hexdump of a slice
/// Useful functions to calculate the offset between slices and show a hexdump of a slice
pub trait Offset {
/// offset between the first byte of self and the first byte of the argument
/// Offset between the first byte of self and the first byte of the argument
fn offset(&self, second: &Self) -> usize;
}
@ -91,7 +90,7 @@ impl<'a> Offset for &'a str {
/// Helper trait for types that can be viewed as a byte slice
pub trait AsBytes {
/// casts the input type to a byte slice
/// Casts the input type to a byte slice
fn as_bytes(&self) -> &[u8];
}
@ -150,27 +149,27 @@ as_bytes_array_impls! {
30 31 32
}
/// transforms common types to a char for basic token parsing
/// Transforms common types to a char for basic token parsing
pub trait AsChar {
/// makes a char from self
fn as_char(self) -> char;
/// tests that self is an alphabetic character
/// Tests that self is an alphabetic character
///
/// warning: for `&str` it recognizes alphabetic
/// Warning: for `&str` it recognizes alphabetic
/// characters outside of the 52 ASCII letters
fn is_alpha(self) -> bool;
/// tests that self is an alphabetic character
/// Tests that self is an alphabetic character
/// or a decimal digit
fn is_alphanum(self) -> bool;
/// tests that self is a decimal digit
/// Tests that self is a decimal digit
fn is_dec_digit(self) -> bool;
/// tests that self is an hex digit
/// Tests that self is an hex digit
fn is_hex_digit(self) -> bool;
/// tests that self is an octal digit
/// Tests that self is an octal digit
fn is_oct_digit(self) -> bool;
/// gets the len in bytes for self
/// Gets the len in bytes for self
fn len(self) -> usize;
}
@ -301,37 +300,37 @@ impl<'a> AsChar for &'a char {
}
}
/// abstracts common iteration operations on the input type
/// Abstracts common iteration operations on the input type
pub trait InputIter {
/// the current input type is a sequence of that `Item` type.
/// The current input type is a sequence of that `Item` type.
///
/// example: `u8` for `&[u8]` or `char` for &str`
/// Example: `u8` for `&[u8]` or `char` for `&str`
type Item;
/// an iterator over the input type, producing the item and its position
/// An iterator over the input type, producing the item and its position
/// for use with [Slice]. If we're iterating over `&str`, the position
/// corresponds to the byte index of the character
type Iter: Iterator<Item = (usize, Self::Item)>;
/// an iterator over the input type, producing the item
/// An iterator over the input type, producing the item
type IterElem: Iterator<Item = Self::Item>;
/// returns an iterator over the elements and their byte offsets
/// Returns an iterator over the elements and their byte offsets
fn iter_indices(&self) -> Self::Iter;
/// returns an iterator over the elements
/// Returns an iterator over the elements
fn iter_elements(&self) -> Self::IterElem;
/// finds the byte position of the element
/// Finds the byte position of the element
fn position<P>(&self, predicate: P) -> Option<usize>
where
P: Fn(Self::Item) -> bool;
/// get the byte offset from the element's position in the stream
/// Get the byte offset from the element's position in the stream
fn slice_index(&self, count: usize) -> Option<usize>;
}
/// abstracts slicing operations
/// Abstracts slicing operations
pub trait InputTake: Sized {
/// returns a slice of `count` bytes. panics if count > length
/// Returns a slice of `count` bytes. panics if count > length
fn take(&self, count: usize) -> Self;
/// split the stream at the `count` byte offset. panics if count > length
/// Split the stream at the `count` byte offset. panics if count > length
fn take_split(&self, count: usize) -> (Self, Self);
}
@ -436,7 +435,7 @@ impl<'a> InputTake for &'a str {
/// Dummy trait used for default implementations (currently only used for `InputTakeAtPosition` and `Compare`).
///
/// When implementing a custom input type, it is possible to use directly the
/// default implementation: if the input type implements `InputLength`, `InputIter`,
/// default implementation: If the input type implements `InputLength`, `InputIter`,
/// `InputTake` and `Clone`, you can implement `UnspecializedInput` and get
/// a default version of `InputTakeAtPosition` and `Compare`.
///
@ -444,29 +443,29 @@ impl<'a> InputTake for &'a str {
/// `InputTakeAtPosition` (like the one for `&[u8]`).
pub trait UnspecializedInput {}
/// methods to take as much input as possible until the provided function returns true for the current element
/// Methods to take as much input as possible until the provided function returns true for the current element.
///
/// a large part of nom's basic parsers are built using this trait
/// A large part of nom's basic parsers are built using this trait.
pub trait InputTakeAtPosition: Sized {
/// the current input type is a sequence of that `Item` type.
/// The current input type is a sequence of that `Item` type.
///
/// example: `u8` for `&[u8]` or `char` for &str`
/// Example: `u8` for `&[u8]` or `char` for `&str`
type Item;
/// looks for the first element of the input type for which the condition returns true,
/// and returns the input up to this position
/// Looks for the first element of the input type for which the condition returns true,
/// and returns the input up to this position.
///
/// *streaming version*: if no element is found matching the condition, this will return `Incomplete`
/// *streaming version*: If no element is found matching the condition, this will return `Incomplete`
fn split_at_position<P, E: ParseError<Self>>(&self, predicate: P) -> IResult<Self, Self, E>
where
P: Fn(Self::Item) -> bool;
/// looks for the first element of the input type for which the condition returns true
/// and returns the input up to this position
/// Looks for the first element of the input type for which the condition returns true
/// and returns the input up to this position.
///
/// fails if the produced slice is empty
/// Fails if the produced slice is empty.
///
/// *streaming version*: if no element is found matching the condition, this will return `Incomplete`
/// *streaming version*: If no element is found matching the condition, this will return `Incomplete`
fn split_at_position1<P, E: ParseError<Self>>(
&self,
predicate: P,
@ -475,10 +474,10 @@ pub trait InputTakeAtPosition: Sized {
where
P: Fn(Self::Item) -> bool;
/// looks for the first element of the input type for which the condition returns true,
/// and returns the input up to this position
/// Looks for the first element of the input type for which the condition returns true,
/// and returns the input up to this position.
///
/// *complete version*: if no element is found matching the condition, this will return the whole input
/// *complete version*: If no element is found matching the condition, this will return the whole input
fn split_at_position_complete<P, E: ParseError<Self>>(
&self,
predicate: P,
@ -486,12 +485,12 @@ pub trait InputTakeAtPosition: Sized {
where
P: Fn(Self::Item) -> bool;
/// looks for the first element of the input type for which the condition returns true
/// and returns the input up to this position
/// Looks for the first element of the input type for which the condition returns true
/// and returns the input up to this position.
///
/// fails if the produced slice is empty
/// Fails if the produced slice is empty.
///
/// *complete version*: if no element is found matching the condition, this will return the whole input
/// *complete version*: If no element is found matching the condition, this will return the whole input
fn split_at_position1_complete<P, E: ParseError<Self>>(
&self,
predicate: P,
@ -691,26 +690,26 @@ impl<'a> InputTakeAtPosition for &'a str {
}
}
/// indicates wether a comparison was successful, an error, or
/// Indicates wether a comparison was successful, an error, or
/// if more data was needed
#[derive(Debug, PartialEq)]
pub enum CompareResult {
/// comparison was successful
/// Comparison was successful
Ok,
/// we need more data to be sure
/// We need more data to be sure
Incomplete,
/// comparison failed
/// Comparison failed
Error,
}
/// abstracts comparison operations
/// Abstracts comparison operations
pub trait Compare<T> {
/// compares self to another value for equality
/// Compares self to another value for equality
fn compare(&self, t: T) -> CompareResult;
/// compares self to another value for equality
/// Compares self to another value for equality
/// independently of the case.
///
/// warning: for `&str`, the comparison is done
/// Warning: for `&str`, the comparison is done
/// by lowercasing both strings and comparing
/// the result. This is a temporary solution until
/// a better one appears
@ -875,9 +874,9 @@ impl<'a, 'b> Compare<&'b str> for &'a str {
}
}
/// look for a token in self
/// Look for a token in self
pub trait FindToken<T> {
/// returns true if self contains the token
/// Returns true if self contains the token
fn find_token(&self, token: T) -> bool;
}
@ -927,9 +926,9 @@ impl<'a> FindToken<char> for &'a str {
}
}
/// look for a substring in self
/// Look for a substring in self
pub trait FindSubstring<T> {
/// returns the byte position of the substring if it is found
/// Returns the byte position of the substring if it is found
fn find_substring(&self, substr: T) -> Option<usize>;
}
@ -983,10 +982,10 @@ impl<'a, 'b> FindSubstring<&'b str> for &'a str {
}
}
/// used to integrate str's parse() method
/// Used to integrate `str`'s `parse()` method
pub trait ParseTo<R> {
/// succeeds if `parse()` succeeded. The byte slice implementation
/// will first convert it to a &str, then apply the `parse()` function
/// Succeeds if `parse()` succeeded. The byte slice implementation
/// will first convert it to a `&str`, then apply the `parse()` function
fn parse_to(&self) -> Option<R>;
}
@ -1002,13 +1001,13 @@ impl<'a, R: FromStr> ParseTo<R> for &'a str {
}
}
/// slicing operations using ranges
/// Slicing operations using ranges.
///
/// this trait is loosely based on
/// This trait is loosely based on
/// `Index`, but can actually return
/// something else than a `&[T]` or `&str`
pub trait Slice<R> {
/// slices self according to the range argument
/// Slices self according to the range argument
fn slice(&self, range: R) -> Self;
}
@ -1137,20 +1136,20 @@ array_impls! {
30 31 32
}
/// abstracts something which can extend an `Extend`
/// used to build modified input slices in `escaped_transform`
/// Abstracts something which can extend an `Extend`.
/// Used to build modified input slices in `escaped_transform`
pub trait ExtendInto {
/// the current input type is a sequence of that `Item` type.
/// The current input type is a sequence of that `Item` type.
///
/// example: `u8` for `&[u8]` or `char` for &str`
/// Example: `u8` for `&[u8]` or `char` for `&str`
type Item;
/// the type that will be produced
/// The type that will be produced
type Extender: Extend<Self::Item>;
/// create a new `Extend` of the correct type
/// Create a new `Extend` of the correct type
fn new_builder(&self) -> Self::Extender;
/// accumulate the input into an accumulator
/// Accumulate the input into an accumulator
fn extend_into(&self, acc: &mut Self::Extender);
}
@ -1229,9 +1228,9 @@ impl ExtendInto for char {
}
}
/// Helper trait to convert numbers to usize
/// Helper trait to convert numbers to usize.
///
/// by default, usize implements `From<u8>` and `From<u16>` but not
/// By default, usize implements `From<u8>` and `From<u16>` but not
/// `From<u32>` and `From<u64>` because that would be invalid on some
/// platforms. This trait implements the conversion for platforms
/// with 32 and 64 bits pointer platforms
@ -1277,9 +1276,9 @@ impl ToUsize for u64 {
}
}
/// equivalent From implementation to avoid orphan rules in bits parsers
/// Equivalent From implementation to avoid orphan rules in bits parsers
pub trait ErrorConvert<E> {
/// transform to another error type
/// Transform to another error type
fn convert(self) -> E;
}

10
src/util.rs
View File

@ -7,11 +7,11 @@ use std::fmt::Debug;
/// Helper trait to show a byte slice as a hex dump
pub trait HexDisplay {
/// Converts the value of `self` to a hex dump, returning the owned
/// string.
/// `String`.
fn to_hex(&self, chunk_size: usize) -> String;
/// Converts the value of `self` to a hex dump beginning at `from` address, returning the owned
/// string.
/// `String`.
fn to_hex_from(&self, chunk_size: usize, from: usize) -> String;
}
@ -97,7 +97,7 @@ macro_rules! nom_stringify (
($($args:tt)*) => (stringify!($($args)*));
);
/// Prints a message if the parser fails
/// Prints a message if the parser fails.
///
/// The message prints the `Error` or `Incomplete`
/// and the parser's calling code
@ -135,7 +135,7 @@ macro_rules! dbg (
);
);
/// Prints a message and the input if the parser fails
/// Prints a message and the input if the parser fails.
///
/// The message prints the `Error` or `Incomplete`
/// and the parser's calling code.
@ -173,7 +173,7 @@ where
}
}
/// Prints a message and the input if the parser fails
/// Prints a message and the input if the parser fails.
///
/// The message prints the `Error` or `Incomplete`
/// and the parser's calling code.