Improve documentation

[dragostis]

Four critical areas:

• iterators example
• prec_climber example
• PrecClimber example (can be the same as above)
• any undocumented stuff

[XAMPPRocky]

Hello, I'd also like to add that there is a lack of examples beyond what is in the README. The only example I can find is one in pest/examples and it seems to not use the same syntax as the README's examples. Something for feature complete like a ini parser that's small but shows best practices for parsing file formats would be great!

[dragostis]

@Aaronepower Examples and reference are found in the pest_derive crate whose documentation is currently offline because of a bug in docs.rs.

[oleid]

Yesterday, I discovered pest and defined a language to define a graph for some toy project of mine. Writing the grammar was really straight forward, although I never did anything like that before -- kudos!

I also found the test cases in the grammar sub-repo quite helpful to validate the language I defined. Yet, what I'm struggling with is using the parsed output to fill my types with information. While it's working now, it felt more complicated than needed and the code looks ugly (i.e. unwrap all over the place for things, I can safely unwrap, since it parsed correctly before), so I assume I misused the API. Hence, it would be wonderful to get a few "best practices". What I found strange, for example, was that I had to use i.e. a for loop to iterate over the output just to be able to use an into_inner() on the iteration variable for something like this:

[...]
whitelist = { "[" ~ port_or_type ~ ("," ~ port_or_type)* ~ "]" | "[" ~ "]" }
blacklist = { "!" ~ whitelist }

port_or_type = { identifier | int  }
[...]

I'd need iter over blacklist and use into_inner() to get the whitelist. So I end up matching the Rule in the loop and returning from the function in the match arm. Same goes for port_or_type. Or I manually called next() on the iterator. Iterating over the whitelist, however, is okay, since it's a list.

[benruijl]

I am trying to find out how to do custom error messages, but I can't seem to find anything about this in the documentation, nor in the examples.

[dragostis]

@benruijl, what kind of custom errors? Error type has a custom error that you could use at semantic level. For parsing, you can have special rules, that, when they match, you know that an error was caused.

[benruijl]

I meant giving a more descriptive error than just the rule name at the semantic level. It is not clear to me how to add that (I do not see that in the documentation).

[dragostis]

I'm not exactly sure what you're looking for. Feel free to drop a message on Gitter.

[Eh2406]

The Stan language was considering using Rust for there new compiler, in so doing they tried pest and describe it as "is not fully documented yet and I wasn’t able to parse something fairly simple with it". In a follow up conversation they elaborated with "I can’t find in my notes what I was specifically having trouble with with Pest. It wasn’t like there was one particular bug - pest in particular admits its documentation is half-finished. I think if you said to them “Someone tried to parse a C-like language” they would probably know what was missing."

[CAD97]

Really, what needs to be done is more example work in the book. If we flush out the planned example chapters there, I think we'll have a pretty stellar onboarding experience.

[dragostis]

To me, the documentation right now is definitely good enough to do more than just a fairily simple example. Did the author give the book a fair chance? It might be the case that it's a bit slow for someone looking tl get right into action.

I'd very much like to offer help if the author would like to give pest another chance! :)

[Eh2406]

I don't know if they want to give Rust another chance, I think they have settled on OCaml. That is the problem with documentation issues, a lot of the people turned off by it never ask for help.

Ther rust code is at https://github.com/seantalts/stan3/tree/170e6afc5b0e00dc5f201a25a881b7aa11f679b2
I think it would be reasonable to fork the repo and rewrite the example to use pest. I don't know if they will accept a PR, but it would make a good example.

[Timmmm]

I think the missing documentation is pretty clear to be honest:

• How do you actually get the nice errors mentioned in the readme? For me it just prints a standard #[derive(debug)] output.
• How do you handle keywords - it's easy for a generic identifier to match before keywords do. (See this section for tree sitter). I think the answer is that you put the identifier last in alternatives lists, but it would be nice if the documentation said.
• How do I just dump the output of the parser? There doesn't seem to be an easy way.
• The examples should include a dump of the parser output. Except for the readme, they all just jump straight into processing it before we get to see what the thing that we are processing looks like!
• Why is all the reference documentation for the grammar syntax in pest-derive, seems like an odd place for it!

Great project, and the documentation isn't too bad to be honest but I feel like it could be great without too much work.