Extending the AST
------------------------

This document describes what is involved in writing an extension that adds a new AST Node or modifies the behavior of an existing AST node.

Extensions would add nodes to the AST node or would modify their behavior for the following typical reasons:

Depending upon the nature of the extension, the TypeSystem may also have to be modified to support the new AST node.

The nodes of the AST are created by the parser. The parser is generated from a CUP file (java12.cup). This cup file will have to be modified to instantiate the new AST nodes in place of the of the standard ones. The correct way to to this is to copy the cup file into the package hierarchy of the the extension, and then make any modifications there. This leaves the original version intact.

The parser is instantiated in polyglot.main.Main. polyglot.frontend.Compiler queries main for the compiler. So, to instantiate a Compiler with a new parser, polyglot.main.Main. must be instructed to create the new parser whenever using this Compiler modification.

Currently the only way to do this is by editing Main.java. However, there was an initiative to create a standard modification description file that is requried of any valid Compiler modification: ExtensionInfo.java. This file would have resided in the root of the extension's hierarchy and given  instructions to polyglot.main.Main and polyglot.frontend.Compiler to properly "install" the modifications. Then, the Compiler is notified of the new extension by passing the fully qualified package name of the new extension; the extension reads the ExtensionInfo file, and proceeds. Under this scenario, there is no need to modify polyglot.main.Main to instruct it of a new extension. Unfortunately, this cleaner solution is not yet available.