winnow-rs / winnow

Making parsing a breeze
https://docs.rs/winnow
Other
572 stars 44 forks source link

Tutorial examples are incomplete #571

Open dave-doty opened 3 months ago

dave-doty commented 3 months ago

Please complete the following tasks

rust version

1.79.0

winnow version

0.6.15

Minimal reproducible code

See next.

Steps to reproduce the bug with the above code

Some of the code in the tutorial is incomplete. For example, at https://docs.rs/winnow/latest/winnow/_tutorial/chapter_2/index.html there is this program:

use winnow::token::take_while;

fn parse_digits<'s>(input: &mut &'s str) -> PResult<&'s str> {
    take_while(1.., ('0'..='9', 'a'..='f', 'A'..='F')).parse_next(input)
}

fn main() {
    let mut input = "1a2b Hello";

    let output = parse_digits.parse_next(&mut input).unwrap();
    assert_eq!(input, " Hello");
    assert_eq!(output, "1a2b");

    assert!(parse_digits.parse_next(&mut "Z").is_err());
}

but it does not compile. It needs these two lines added at the top:

use winnow::Parser;
use winnow::PResult;

Actual Behaviour

Put this in a main.rs file and run cargo check. This error results:

error[E0412]: cannot find type `PResult` in this scope
   --> src/main.rs:3:45
    |
3   | fn parse_digits<'s>(input: &mut &'s str) -> PResult<&'s str> {
    |                                             ^^^^^^^
    |
   ::: C:\Users\pexat\.rustup\toolchains\stable-x86_64-pc-windows-msvc\lib/rustlib/src/rust\library\core\src\result.rs:502:1
    |
502 | pub enum Result<T, E> {
    | --------------------- similarly named enum `Result` defined here
    |
help: an enum with a similar name exists
    |
3   | fn parse_digits<'s>(input: &mut &'s str) -> Result<&'s str> {
    |                                             ~~~~~~
help: consider importing this type alias
    |
1   + use winnow::PResult;
    |

Expected Behaviour

Should compile without errors.

Additional Context

No response

epage commented 3 months ago

To be clear, this isn't a typo as cargo test builds and runs all of the examples.

All of winnow examples (except Special Topics), only show the use for the item in question (e.g. see be_u128).

In particular, for the Tutorial, we also leave out large bodies of code, building on what we've previously shown. We show // ... when eliding functions but it appears we don't do that when eliding use statements.