search

nanopass / nanopass-framework-racket

nanopass compiler framework for Racket
http://nanopass.org
MIT License
181 stars 29 forks source link

Incorrect docs for parsing and unparsing #2

Open schuster opened 8 years ago

schuster commented 8 years ago

Section 2.3 claims that define-language produces a parser function parse-<language-name> and an unparser unparse-<language-name>, but I'm told that's not the case and to use with-output-language instead. This should be reflected in the docs.

akeep commented 8 years ago

We removed the automatic parser-, but you can still define one using define-parser:

(define-parser parse- )

I think of the auto generated parser and with-output-language as being for slightly different purposes.  I use parse when I’m reading in a full program.  I tend to use with-output-language when I’m ginning up bits of language form outside of the right-hand side of a pass body.

When I get some spare time, I will update the docs accordingly.

Since I’ve noticed you’ve commented more on this :)

Kent and I made the strategic decision to make the asymmetric change of having define-parser be separate while define-unparsed is not, because we were basically never using the parsers for the Chez Scheme compiler.  The parsers are too simple to really be useful inside a commercial compiler, but they are great for a teaching compiler.  The unparsers, on the other hand, and useful for tracing and for error messages and almost always end up getting used.  (In particular the trace-define-pass makes use of the unparsers, which is handy for debugging.)

That said, there is actually a separate define-unparsed form as well, and you can define separate unparsers with it, if you wanted a different name, or something along those lines.

-andy:) On March 4, 2016 at 3:01:45 PM, Jonathan Schuster (notifications@github.com) wrote:

Section 2.3 claims that define-language produces a parser function parse- and an unparser unparse-, but I'm told that's not the case and to use with-output-language instead. This should be reflected in the docs.

— Reply to this email directly or view it on GitHub.

leafac commented 7 years ago

I’m reading Nanopass’ documentation and I just tripped over the false claim that parse-language-name would be provided. Only unparse-language-name is provided, and parse-language-name has to be defined with define-parser.

In other words, the implementation behaves like @akeep described in the comment above, of course. But the documentation doesn’t reflect that.

jbclements commented 5 years ago

I believe #21 fixes this. Should have referenced this issue in the Pull request, sorry.