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,
               const char *filename, uintN lineno);

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. So JSParseTree would be a Visitable and the API would introduce a Visitor interface (in the C callbacks or poor-man's vtable sense) for API clients to implement.

Please feel free to add your design notes below.

/be