Issue #249 add GUIDE.md

[wavebeem]

Fixes #249, adding a guide for using Parsimmon

[coveralls]

Coverage remained the same at 100.0% when pulling 5d9c212 on issues/249 into 6690c37 on master.

[wavebeem]

@ivan-kleshnin, @anko, are either of you interesting in looking at what I've got here so far? No pressure

[ivan-kleshnin]

Thanks! I'll review this, for sure.

[halfzebra]

I think it might be worth mentioning that for parsing efficiency it is good to have the preceding parser to eat all the trailing whitespace, so the next one doesn't have to munch through it again.

const token = Parsimmon.regex(/[a-Z]+/)

const whitespace1 = Parsimmon.regex(/[ \t]+/)

const parser = Parsimmon.seq(
    token.skip(whitespace1), 
    Parsimmon.alt(
        Parsimmon.string('World'),
        // Other parsers.
    )
)

parser.parse('Hello                         World!')
                //  ☝️ all the whitespace is gone after `token` is parsed,
                //     instead of munching through it in every parser in `Parsimmon.alt`

This is not very useful for the example above, but in general, I feel like it's a fairly common optimization technique.

[halfzebra]

Maybe a good place to put the references to the API docs 🙂