
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:

   * The extension would like to modify the typing rules, which may
     require modifying the AST. 
   * Adding a new language primitive.     

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.
