Improved custom error tutorial / how-to?

[scriptandcompile]

First off, thanks for the hard work making an awesome library!

Is there anywhere we can get more information on how to do custom errors with winnow?

The tutorial mentions error reporting then goes into a tangent around err_cut and nothing really more is found. There is some discussion in: https://docs.rs/winnow/latest/winnow/_topic/error/index.html but I'm not sure how out of date this is since it mentions nom.

Ideally, more depth could be had around how custom errors fit into the entire ecosystem.

How a custom error can be reported with the context around it (with an example!) how that fits into ErrorContext, ErrorTree, ErrKind, ErrMode, ParserError, AddContext, and FromExternalError.

When it comes to the docs (and theory of documentation https://docs.divio.com/documentation-system/) you have reference nailed. Tutorial is...alright, explanation is adequate enough, and how-to is almost non-existent.

Do you have a suggestion for further reading/tutorials/how-to's/videos? I've basically found two videos on youtube (https://www.youtube.com/watch?v=QF3kMyzMC40 and https://www.youtube.com/watch?v=LUcI6KkM-PE) but these are more a rough look around of what winnow is and a bit of 'getting to know the general area' type thing.

[epage]

To provide direction improving this, it would help to know what question you had or challenge that led you to custom errors and how the documentation didn't help.

[scriptandcompile]

Sure! So, I'm having issues because I'm in a bit of a weird edge case here.

I'm trying to parse vb6 code, so of course, I can't use UTF since it predates it and we get all kinds of weird broken characters. This means I have to use &'a [u8] or BStr (from burntsushi, another awesome crate as well!) This means I need to implement things carefully to get it to work with this non-standard stream. I get a ton of 'as Stream' trait restrictions which I need to handle. That I eventually figured out since you have a whole section on implementing Stream, but we don't have a similar basic walkthrough for errors. I'm generally looking for 'how to implement custom errors' as a walkthrough. The one we have is...very barebones and when I tried to do the same thing for another section of my code, and I think I've done it the same way, it utterly failed and fell down. I'm definitely doing something wrong, but I can't figure out what since I'm getting lost in the traits.

The Stream section was very clear: implement these traits, use them in this way, result! The example is barebones, but it definitely gets things across. It's not so much 'the info isn't here' I'm sure it is. I'm just having issue converting 'reference material' into 'functional understanding.'

You can check out what I've got so far at: https://github.com/scriptandcompile/vb6parse/tree/master/src

and you can see in the project.rs and error.rs that I've got....some.... idea how this is supposed to work, but I'm definitely not using the library in the right way. I started to work on classes.rs (the first place where we have actual AST parsing that will need to happen!) I've mostly cobbled things together in a working-ish way, but I'm having a lot of issue so it's clear I'm doing something wrong with this and it feels like I'm trying to operate a chainsaw with my feet. It's very clearly not the chainsaw's fault, I'm doing something wrong here, but all I've got is a maintenance and assembly guide to the chainsaw so I'm doing the best I can! But, I'm not sure where and how and why things are going sideways.

Lots of 'type annotation needed <_, ParseError> stuff popping up and it just feels...like I'm fighting things instead of doing things the 'right way' (tm).

[scriptandcompile]

I was mostly just pointing to the Stream as contrast to the errors. I'm still confused on that side, but you have done a tad more there and it's basically what I was asking for more of. How-tos and tutorial side vs reference.

Thanks for getting back so fast like this, I appreciate the work you've put into this project.

[epage]

I think there might be a misunderstanding. I'm looking to better understand what would be the right error documentation to write. An important detail for that is use cases. Within your application, you've decided to use a custom error type. Understanding why would help a lot towards knowing how to further improve the documentation.

[scriptandcompile]

Mostly, I'm just confused on what I should do in order to get the results I'm looking for.

So, as I imagine it, the interface I want is, at a high level, a parse function with a Result<VB6Class, MyErrorCollection> where MyErrorCollection has a collection of specific enum error variants that describe the error (UnpairedFor, as an example which indicates no 'next' match for the 'for') this would also include a slice for the text line and the location (or multiple locations) that indicate the parse area of the error. With those things building error reporting like rust has shouldn't be that hard.

Now all of that? All of that is very clearly specific to my exact case and should have nothing to do with your library really. But under the Parse function, I would be using your errors from winnow and I should mate those to my errors in a way that lets me collect the error information (Example: I'm looking for a literal('next') so of course I know that I'm trying to match, but I need the 'line' of the unmatched 'for' and so on). But internal to my collection of winnow parsers my errors are going to end up being something else, something that can mate to your stuff and the internal winnow error stuff shouldn't end up polluting the outer error scope where the 'parse' lives.

ie, I'm floundering around in the 'how-to' and the 'tutorial' side of things rather than the reference side. I just need a simple example of how these things mate together and I can sort of see how things should work. The tutorial you have so far mostly works well enough, but it doesn't really help much with the errors. Stuff like 'how to use winnow to get the current full line of the input from last newline to next newline so you can add this to an error to report.'

Basically, little 'chunks' of problems that might come up when building a full language parser.

[epage]

Thanks, that is a lot of helpful context! I've posted #538

• Updates the error topic to point out the value of custom context types with ContextError as that can help a lot in cases like this
• Updated the error tutorial to show how one could adapt ContextError into a custom error type

With flow changes to the tutorial to support that change and misc other improvements to the error chapter of the tutorial.

One limitation I ran into is my own imagination. Its a lot of work to come up with arbitrary examples that feel real enough that show a principle. I built this on what I do for error reporting in toml_edit with the limitations that comes with. In #104, one user goes a bit further in customizing error reporting.

Would be interested to hear your thoughts in how well this helps in bridging that gap you had and what more could help!

[scriptandcompile]

This is great! Thanks for your work. I can see now how I was screwing up. I read it and it basically clicked! That's a great sign that this documentation cleared up some confusion.

I basically had no clue all the stuff that ContextError could handle and how I could use that to build up my own error handling issues later.

This is great! I've noticed a few other nit-fiddly areas where the docs confused me, but can't remember them at the moment. I'm sure I'll run into them again while working on my parser, when I run into them I'll note them down and then at the end of my work I'll see if I can figure out changes which would help.

I vaguely remember something about a function that had an example that didn't actually use the function but a different function, or it used the function but relied on peek_next instead of parse_next which meant to understand the example you had to learn another new concept, namely peek_next, when all the other examples used parse_next. It was something like that.

But that's a different issue and me just rambling on. Still, thank you! This really helped!