zesterer
Update Errors and Recovery Documentation
As mentioned in #774, I'm working on updating errors and recovery docs with the info I find. This will be a draft for now, as I'll be needing some pointers on maintaining the writing style of the rest of the documentation as well as tips on extra detail to include.
I've not had time to review everything (I'm writing this on a train right now), but hopefully I'll get the time to finish off tonight or tomorrow. Don't worry about it, I'm not in any rush here - I'm recovering from surgery and have a lot of free time
Don't worry about it! I'm currently recovering from surgery so I might not be extremely responsive myself. I've noted your suggestions and will try to work on it later today, thank you for your time :)
Wrote a little more today, I think the example I provided for a recovery strategy might be a little too extensive for the section its in (it does show a few different concepts at once), but I'm curious about your thoughts.
I sprinkled a couple TODO comments asking questions in the commit, but they (and a couple additional ones) are entirely summarized in the list below:
- I have not been able to discover what the "fallback" parameter of skip_until is. What is it used for? Is it equivalent to chaining a new recover_with?
- Need some pointers on writing for skip_then_retry_until. I believe I had seen some of it defined elsewhere in the docs before, but I haven't been able to find it again today, and trying to write by memory just left me blank.
- Unsure about how much we should write about ariadne in this page. I think at least a link to the docs (and maybe one example on how to handle automated diagnostics) would be nice. Having a more dedicated guide might be even nicer, but I'm unsure if that's out of the scope of Chumsky's docs.
- I'm lacking a bit of intuition on recover_with. When it's called on a parser, does it resume parsing where the previous one stopped, or does it entirely restart? The distinction can feel a little difficult to grasp in practice when working with recursive descent parsers since each individual parser span is chopped so thin.
- What's next? I suppose we shouldn't yet include a section on the RecoveryStrategy trait since it's sealed. Am I missing any additional traits that may be relevant? Some other function that I haven't noticed yet? Feel free to comment.
Urgh, I'm so sorry. GitHub swallowed my notification for this PR and I promptly forgot about it until now.
* I have not been able to discover what the "fallback" parameter of skip_until is. What is it used for? Is it equivalent to chaining a new recover_with?
It allows you to specify a function that generates the parser's output value in the case of successful recovery. Usually, this means you just want a function that returns an Expr::Error or whatever your AST's error node is.
* Need some pointers on writing for skip_then_retry_until. I believe I had seen some of it defined elsewhere in the docs before, but I haven't been able to find it again today, and trying to write by memory just left me blank.
Perhaps hold fire on these other recovery strategies for now - they're included because they existed in 0.9, but they can be trivially replicated using 'native' chumsky combinators nowadays, so I think there's a good argument for removing them entirely.
In fact, I might try doing that soon.
* I'm lacking a bit of intuition on recover_with. When it's called on a parser, does it resume parsing where the previous one stopped, or does it entirely restart? The distinction can feel a little difficult to grasp in practice when working with recursive descent parsers since each individual parser span is chopped so thin.
You can think of it as behaving like a a.or(b) - with the notable exception that it remembers and reports the error that a generated. It really is that simple, and the Strategy trait increasingly acts to confuse that fact nowadays, in my view.
* What's next? I suppose we shouldn't yet include a section on the RecoveryStrategy trait since it's sealed. Am I missing any additional traits that may be relevant? Some other function that I haven't noticed yet? Feel free to comment.
My feeling is that it's best to get this PR into a mergeable state. It doesn't matter if it's not exhaustive, that's fine (since I'm probably going to be making some changes to the API anyway). Let me know when you think you're happy with it!
For the time being I am going to merge this, and fix the minor issues later.