Better documentation for AST format

[agladysh]

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]

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//issues/7
.

[agladysh]

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//issues/7#issuecomment-31145058
.

[fab13n]

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]

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]

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//issues/7#issuecomment-31281761
.

[agladysh]

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//issues/7#issuecomment-31290793
.