This needs a lot more examples

[chippyash]

Hi

I think this project is really important, and a potential winner for making parsing easy ( and ultimately interpreting bizarre languages). As engineers, we have to turn someone else's dialect into code all the time, so what you are doing is important. The problem I have is the syntax required to make it work. It's about as clear as mud.

I think you are assuming that all devs know the internals of go intimately. THEY DON'T. So talking about the Go AST system leaves most without a clue. What is AST (Hint - you don't explain in the readme.) What are the steps after producing an AST (hint - no guidance).

But first and foremost, I really appreciate that you have done this, but as an engineer of some 30 years standing, I can't understand how to make it work. And that, my friend, means that all the beautiful hard work you have done is for nothing

Kind regards
Ashley

[chippyash]

By way of an example

type Primary struct {
	//Pos lexer.Position

	Number        *int                `  @Int`
	ArrayIndex    *ArrayIndex `| @@`
	Ident         string               `| @Ident`
	SubExpression *Expr       `| "(" @@ ")" `
}

what is @int, | @@, | @Ident or | "(" @@ ")" supposed to mean? It's gibberish.

[alecthomas]

All of the syntax is fully documented in the README.

[alecthomas]

And a tutorial that goes into more detail with examples.

[alecthomas]

And finally an _examples directory with 20+ examples.

[testitm]

I agree, this is awesome project, and have good readme. but some things i didn't get without source digging :)

[alecthomas]

I'm interested in having the documentation improve, however:

1. I'm not going to write an introduction to parsing - grammar, lexer, AST, etc. are all assumed knowledge.
2. re. examples, there are over 20 examples included, so I'm not sure what else can be done there.
3. Without specifics I have no clue what needs improving.

Finally, parsing is one of those things that is difficult and takes a while to grok. But once you do it all clicks and you can pick up most parsing tools quite quickly. It's just not easy.

All that said, PRs improving the documentation would be the most constructive thing to do.