Add docs and best practice guides

[svenstaro]

trafficstars

I'm just starting out with combine and I'm having a hard time dealing with what I assume are common errors and mistakes. It would help if there were a guide pointing to the right bits in the docs and also some best practice guides.

[Marwes]

Trying to think of things that could be improved.

• Add some example error messages and how to resolved them? In some sense this should be covered by rust's own documentation as they are not unique to combine (both the Iterator and especially the Future trait have many of the same issues).

• Point out that RangeStream is required in https://docs.rs/combine/3.5.1/combine/parser/range/index.html

• Point to alternative non-RangeStream parsers if they exist (and maybe vice-versa for the Stream based alternatives)

• more?

[svenstaro]

A git book would be great. It would be neat if you could just walk people through some common problems and their solutions using this library. Try to think of examples to cover as much of the lib as possible. I know there are examples but a walkthrough would be more effective I think.

[svenstaro]

Also add a full example on how to use take_until and friends with functions in order to create more powerful parsers.

[Phaiax]

In the last days I dug into combine and it took far too much effort (>15h to be able to write and compose parsers and understand the why). I'll use my experience to write guide/tutorial like documentation, we'll see what comes out as I am not a good explainer. I'll use the github wiki for drafting. Later I can move this into the souce code or a mdbook or just .md files.

[Phaiax]

Doc is finished from my side, see the Wiki. @Marwes, please comment and I will make little improvements based on your comments, but I ran out of time to do more documentation. These three parts are missing for now, but I consider them not as important as the others:

• Partial Parsing
• impl Parser
• How to make a type alias to the input type to simplify the method signature of the self defined parsers. (makes the parsers function signature more clean, would also help #230)

Additionally, I think a few more examples in the examples folder would make a great job.

[Marwes]

@Phaiax Sorry for not getting to this sooner (I have been away on a company conference this week). I have read through it once so far and spotted some errors but should be able to have a proper go at it tomorrow!

[sbuller]

I've been benefiting from the docs already; thanks @Phaiax. I would really appreciate documentation on making a type alias; it's a familiar pattern from using MegaParsec in Haskell, but I'm not terribly well versed in Rust to be able to derive it without assistance.

[sbuller]

I should note, the type alias one defines in MegaParsec still takes an additional type parameter for the output type of the parser.

Selected excerpt from Mark Karpov, note the type Parser and how Parser is further parameterised when used:

type Parser = Parsec Void String

sc :: Parser ()
sc = L.space space1 lineCmnt blockCmnt
  where
    lineCmnt  = L.skipLineComment "//"
    blockCmnt = L.skipBlockComment "/*" "*/"

lexeme :: Parser a -> Parser a
lexeme = L.lexeme sc

integer :: Parser Integer
integer = lexeme L.decimal

[Marwes]

Gone through https://github.com/Marwes/combine/wiki and https://github.com/Marwes/combine/wiki/Tutorial at least, sorry for being slow about this (partly because of a cold).

I edited them and pushed the changes we can be seen below. The changes are mostly grammatical fixes/changes (I have tried to make it read as if from a more authoritative source), a few factual corrections and one section around choice which I re-ordered and removed the part about then in as I believe that is a bit more of an advanced use-case so I moved the text about choice up. I'd like to bring the section on then back later but I didn't want to delays this feedback any longer.

https://github.com/Marwes/combine/wiki/Home/_compare/b5ea426d9f0111819dc278962c484242f20eea61...c0ba8ee96f2631c18a5cc719de918a4e4a3b5e04?short_path=b4d7124#diff-b4d7124d2993cd13aabeec1fc19baf51

https://github.com/Marwes/combine/wiki/Tutorial/_compare/a271c6bd6e08e24809beac65158c4e4e6a7eebef...dafeef00e3a9889c8be60edb3631290e93ffc078?short_path=eb37036#diff-eb3703691aed07935bf8e584cf7873c9

[Marwes]

How to make a type alias to the input type to simplify the method signature of the self defined parsers. (makes the parsers function signature more clean, would also help #230)

Would this be something like

trait MyParser<O> : Parser<Input = MyInput, Output = O> { }

impl<O, P> MyParser<O> for P where P: Parser<Input = MyInput, Output = O> {}

fn parser() -> impl MyParser<String>
where // etc
{
}

[Marwes]

Finally went through the rest of it, sorry this has taken so long!

https://github.com/Marwes/combine/wiki/Error-Handling/_compare/c88b8dc687d04575b7af3fa17f8931187db0f9d5?short_path=ef17afe#diff-ef17afe15a0870202f6ce747383e3cab

https://github.com/Marwes/combine/wiki/Input-Machinery/_compare/4c1083a30470e27353e64e1b47b8ccf1f48d8b27?short_path=a0ac0bb#diff-a0ac0bbc1447a16ecd31831812b33bc3

With the 3.7.7 release I now link directly to the wiki from the readme. Huge thank again @Phaiax for writing this!