JavaScript:SpiderMonkey:Parser API
Brendan's notes
Currently jsparse.h defines a JSParseNode struct, a variant record documented by the major comment before its declaration, and a few JS_FRIEND_API entry points for parsing and compiling, but not executing, token streams.
There is interest, from the jseng newsgroup, in adding a jsparseapi.[ch] module to SpiderMonkey that exposes these parse-tree internals in a sustainable way. See my post in the thread on this topic.
In a followup post, I talk about various APIs that could be used to glean information from the direct members of JSParseNode, but with a new jsparseapi.h interface, we would do better to use functions to hide all data types that are not already exposed via jspubtd.h and jsapi.h.
The parse-tree API should expose a JSParseTree opaque struct type. This type represents a tree parsed from a token stream, or a subtree (even just one leaf node). We should not expose JSTokenStream, rather we should make API entry points such as
extern JS_PUBLIC_API(JSParseTree *) JS_ParseScript(JSContext *cx, const jschar *chars, size_t length);
that returns NULL on failure and a pointer to a valid ParseTree on success.
The API would consist of accessors only, no mutators. We might want an API modeled on the visitor pattern. Please feel free to add your design notes below.