search

fab13n / metalua-parser

luarock packaging of Metalua's parser
48 stars 2 forks source link

Better documentation for AST format #7

Open agladysh opened 10 years ago

agladysh commented 10 years ago

Right now it takes some thought and specialized debug printing to guess, how exactly a given AST node data is laid out.

It would be cool if the documentation would give more detailed examples for AST nodes — both for Lua code and for resulting data, including corner-cases.

Since debug printing actually solves this, this is a low priority nice-to-have request :-)

fab13n commented 10 years ago

The proper way to address this is through a sample which pretty-prints the AST corresponding to any given code fragment. But it would force to embed more dependencies (at least the table pretty printer). On Dec 23, 2013 10:20 PM, "Alexander Gladysh" notifications@github.com wrote:

Right now it takes some thought and specialized debug printing to guess, how exactly a given AST node data is laid out.

It would be cool if the documentation would give more detailed examples for AST nodes — both for Lua code and for resulting data, including corner-cases.

Since debug printing actually solves this, this is a low priority nice-to-have request :-)

— Reply to this email directly or view it on GitHubhttps://github.com/fab13n/metalua-parser/issues/7 .

agladysh commented 10 years ago

While it would be nice to have such tool, I'm not sure if it is the proper way. You can't beat the formal documentation in this case, IMHO :-)

BTW, I think that it is OK for examples to have extra dependencies — as long as the main rockspec doesn't install them.

On Tue, Dec 24, 2013 at 1:32 AM, Fleutot notifications@github.com wrote:

The proper way to address this is through a sample which pretty-prints the AST corresponding to any given code fragment. But it would force to embed more dependencies (at least the table pretty printer). On Dec 23, 2013 10:20 PM, "Alexander Gladysh" notifications@github.com wrote:

Right now it takes some thought and specialized debug printing to guess, how exactly a given AST node data is laid out.

It would be cool if the documentation would give more detailed examples for AST nodes — both for Lua code and for resulting data, including corner-cases.

Since debug printing actually solves this, this is a low priority nice-to-have request :-)

— Reply to this email directly or view it on GitHub< https://github.com/fab13n/metalua-parser/issues/7> .

— Reply to this email directly or view it on GitHubhttps://github.com/fab13n/metalua-parser/issues/7#issuecomment-31145058 .

fab13n commented 10 years ago

Added a pretty-printing library, for proper rendering of ASTs. I think it's arguably one of the basic tools needed for AST manipulations. I Will document & port unit tests, create a script that translates Lua chunk sources into rendered AST.

agladysh commented 10 years ago

Remember "json library" argument at the Workshop? :-)

Everybody already has own pretty-printing library.

Me too — and I want to keep using mine, not yours. But I do not oppose your decision too strongly, it is not that much code.

fab13n commented 10 years ago

You know the http client syndrome? The simpler a task seems, the more its implementation attempts suck in practice.

Last time I checked, no pretty printer handled cycles, line returns, indentation etc. properly.

Maybe it should be offered as a separate rock? On Dec 27, 2013 10:52 PM, "Alexander Gladysh" notifications@github.com wrote:

Remember "json library" argument at the Workshop? :-)

Everybody already has own pretty-printing library.

— Reply to this email directly or view it on GitHubhttps://github.com/fab13n/metalua-parser/issues/7#issuecomment-31281761 .

agladysh commented 10 years ago

Good idea.

On Sat, Dec 28, 2013 at 9:19 AM, Fleutot notifications@github.com wrote:

You know the http client syndrome? The simpler a task seems, the more its implementation attempts suck in practice.

Last time I checked, no pretty printer handled cycles, line returns, indentation etc. properly.

Maybe it should be offered as a separate rock? On Dec 27, 2013 10:52 PM, "Alexander Gladysh" notifications@github.com wrote:

Remember "json library" argument at the Workshop? :-)

Everybody already has own pretty-printing library.

— Reply to this email directly or view it on GitHub< https://github.com/fab13n/metalua-parser/issues/7#issuecomment-31281761> .

— Reply to this email directly or view it on GitHubhttps://github.com/fab13n/metalua-parser/issues/7#issuecomment-31290793 .