search

rust-bakery / nom

Rust parser combinator framework
MIT License
9.46k stars 805 forks source link

Parser from scratch docs is hard to follow #993

Open ottosson opened 5 years ago

ottosson commented 5 years ago

Hi, thanks for all your hard work with Nom in general, and the new version specifically. Nom 5 made me want to try it out for the first time, but I find it a bit hard to get started since I need clear and precise documentation to understand.

I'm novice in Rust and completely new to Nom, so I look at the documentation and the chapter "Making a new parser from scratch".

The start is ok, but you talk about a parser for "12345", but never really show how it's implemented and start to talk about the IResult type instead, never to come back to the 12345-parser.

In the HTTP example you declare a bunch of parsers in what seems to be the global scope of the program and not in a function which will result in a expected item, found keyword let error when copying the code to my own test project, which makes it hard to understand where they should be declared.

If possible I would also like to see the "Testing the parsers" and the rest of the chapters continue with the HTTP parser as an example to make the tutorial feel more coherent.

As a beginner I would love to be able to copy/paste some working examples with associated tests and just be able to play around to see what affect changes have on the working code. And the more examples you add, simple and complex, the better :)

Not sure if this is of any value, I just wanted to share an absolute beginners point of view. Hope you'll have time to write some more documentation at some point. And thanks again. Nom looks really interesting and I hope I manage to wrap my head around it with time.

shonfeder commented 4 years ago

I agree on this point. afaik, the code in https://github.com/Geal/nom/blob/master/doc/making_a_new_parser_from_scratch.md#writing-a-first-parser is syntactically invalid, so it's hard for someone getting their bearings to puzzle it out.

[Edited to remove misdirected expression of frustration].

ghost commented 3 years ago

Is there an update available on when this will be addressed? 6.0 has been released, 6.1 even, and the docs are still impenetrable to a newcomer.

eminence commented 2 years ago

The start is ok, but you talk about a parser for "12345", but never really show how it's implemented and start to talk about the IResult type instead, never to come back to the 12345-parser.

I would also like to see the guide follow through on this :)