Improve docs by adding `parse` earlier

[woile]

Please complete the following tasks

• [X] I have searched the discussions
• [X] I have searched the open and rejected issues

winnow version

1.65

Describe your use case

The docs don't make enough use of parse till Tutorial 7. I think introducing earlier would help people close the gap between the initial parser and the finished app.

On top of that, it makes winnow "less scary", because the &mut str is only required while parsing, you can still use your &str with it, which doesn't have to be mutable (does it make sense?)

The way I usually approach it, is to write a simple parser and then I want to see it working.

Describe the solution you'd like

I propose adding parse earlier on. On:

• chapter 1 (either change the existing example, which currently uses parse_next, but at that point I think it should be used the user facing parse, or at least mention it)
• The main example in libs.rs I think it should be changed, the parse inside the Color::from_str IMO is a very important point, but it's a bit lost. And it's not used on css/main.rs as far as I can see, I propose keeping it as simple as possible.

Something like this, would highlight the most important parts of the parser:

use winnow::combinator::seq;
use winnow::prelude::*;
use winnow::token::take_while;

#[derive(Debug, Eq, PartialEq)]
pub(crate) struct Color {
    pub(crate) red: u8,
    pub(crate) green: u8,
    pub(crate) blue: u8,
}

fn hex_primary(input: &mut &str) -> PResult<u8> {
    take_while(2, |c: char| c.is_ascii_hexdigit())
        .try_map(|input| u8::from_str_radix(input, 16))
        .parse_next(input)
}

pub(crate) fn hex_color(input: &mut &str) -> PResult<Color> {
    seq!(Color {
        _: '#',
        red: hex_primary,
        green: hex_primary,
        blue: hex_primary
    })
    .parse_next(input)
}

fn main() {
    let input = "#AAAAAA";

    match hex_color.parse(input) {
        Ok(result) => {
            println!("  {:?}", result);
        }
        Err(err) => {
            println!("  {}", err);
        }
    }
}

Thoughts? I don't mind sending some PRs

Alternatives, if applicable

No response

Additional Context

No response

[epage]

For the tutorial,

• I'm not seeing how to fit parse in. We need to be using parse_next as part of teaching what the parser is doing. Understanding it is incremental is an important concept.
• The tutorial is focused on people writing parsers. The top-level parse operation is a small piece to the overall structure.

As far as the Color example, I get where you are coming from but it is also important to idiomatic code and that is how it would be written in an idiomtic way.

[woile]

Maybe for the tutorial, in chapter 1, it could be a small mention right after the example.

Do not confuse parse_next with parse, the latter is used as the entry point for the top level parse, while parse_next is used when parsers call other parsers

What do you think?

As far as the Color example, I get where you are coming from but it is also important to idiomatic code and that is how it would be written in an idiomtic way.

I think the example you see the moment you go to https://docs.rs/winnow/latest/winnow/ can be a bit hard for beginners. But I agree with your point.

Feel free to close the issue if it doesn't apply, I think my main wish would be to see the parse highlighted somewhere early on

[epage]

What are your thoughts on #536?

[woile]

That looks much better! Thanks 🙏🏻

On Tue, 4 Jun 2024, 19:59 Ed Page, @.***> wrote:

What are your thoughts on #536 https://github.com/winnow-rs/winnow/pull/536?

— Reply to this email directly, view it on GitHub https://github.com/winnow-rs/winnow/issues/529#issuecomment-2148204356, or unsubscribe https://github.com/notifications/unsubscribe-auth/AATXJWDDZ7VWJF5O676JTMTZFYFBBAVCNFSM6AAAAABIQLHR5SVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDCNBYGIYDIMZVGY . You are receiving this because you authored the thread.Message ID: @.***>