Validate the API

[ichiriac]

As said in #61, need to pass over :

• Check consistency in the AST tree
• Check variables names (avoid importing $ prefix)
• Check nested block nodes (example into function bodies) - avoid extra levels

[ichiriac]

Hi @mousetraps, @nikic,

As there is multiple AST parsers for PHP, and comming tools based on them, I'm wondering if it would be more clear to define a "sort of" nodes standardisation.

There will be multiple advantages to that :

• a clear & neat documentation (I am lazy on that part 😄)
• a single way to visit nodes (so a tool could switch between solutions according the need)
• simplify/centralize the way new concepts are introduced into php

I'm thinking at a sort of estree (it's the standard on JS for example) repository that will document the tree structure, nodes and their properties.

Maybe there is no need to be fully strict but at least define the minimum structure, each AST parser could add new properties or additionnal nodes if needed based on it's solutions, but for example there will be a single way to extract a list of used variables into a function body.

I'm saying that because it's my Nth tentative to freeze a once for all the nodes structure, and each change may break a tool.

What do you think ?

[mousetraps]

@ichiriac Interesting idea! And in addition to helping out the consumer, it would also help improve on the provider side (because you can do better cross-validation between parsers if you can detect similarities in the shape of the tree.)

While I think it would to be difficult to come to an agreement on a "strict" definition, I like the idea of getting together to share some of the lessons we've learned, perhaps with an end goal of defining some minimum shared set of features of the tree.

API design isn't something that just happens overnight - it takes a lot of iteration, and it's one of those things where the more perspectives we have, the better.

[ichiriac]

Hi @mousetraps,

Agreed, will be hard to declare a strict API, but after some searches found this project : https://github.com/syntax-tree/unist

It's really close of what I mean. He provides a generic way of defining AST, and some syntax trees on html, markdown, etc ... and a list of generic libraries. I'll digg in this direction ...