lookahead documentation

[upgradingdave]

This is a really great project, I'm having a blast learning about parser combinators, thanks so much for your work.

I noticed there was no documentation about the lookahead parser so I tried to add something that will hopefully be useful to other newbies like me. Please take a look and if you think it'd be helpful please feel free to pull it in.

But also, if this isn't the intended use for lookahead or if you can think of a better example, or if my documentation is confusing in anyway, just let me know and feel free to reject.

Thanks again,
Dave

[upgradingdave]

I see a few grammar mistakes. Please let me know first if you want to pull this in and then, if so, I can fix the mistakes along with any other suggestions/feedback.

[youngnh]

This is good and I'm always willing to accept new documentation. I like where you put the section. lookahead almost certainly makes the most sense right after the section for choice. I thought the first two paragraphs were a very clear and concise overview.

The example, however, strikes me as far too long and it gets muddled in the details of a headline parser. I do think we need an example, and I the headline idea is in the right direction, since I think it should be fairly real-world and not super-contrived. But I would try to keep it short and to the point, maybe demonstrate an input for which choices overlap, and then show how to use lookahead to solve that.

If the headline parser you wrote is part of a larger parser for markdown or some other markup format, please feel free to stash it in the src/parsatron/languages folder and submit a pull request. Sometimes longer-form, fully working code is better documentation than prose.

[upgradingdave]

Hi Nate, thanks much for the feedback. That makes good sense, I thought that example might be a bit too long and complicated.

I'm trying to build a markdown parser using parsatron just for fun to learn more about parsing and clojure. I have a good start and will keep you posted. I'd be happy to contribute it to languages if I have time to get it into better shape.

As I continue to tinker on the markdown parser, I'll keep thinking to try and come up with a better, more concise, example for the lookahead doc section and will update the pull request as soon as I come up with something.

Thanks!