Autoinclude Implementation
From OpenLaszlo
The autoinclude mechanism is used to link in the implementations of components such as <button> and <window> without requiring an explicit <include> element. It was originally envisioned as a way to make programs less verbose; however, users of the Laszlo platform more commonly think of it as a mechanism for stripping unused code from an application: the linker omits the definitions of unused classes, that the autoinclude mechanism is a specific strategy for implementing this optimization feature.
The autoinclude mechanism is documented in Program Structure.
Specification
The <dfn>source set</dfn> of an application is the main (<canvas>) document of the application, together with its the transitive closure of its <include> and <import> elements.
An <dfn>XML island</dfn> is the content of a top-level <dataset> element in an application source.
A tag is <dfn>referenced</dfn> in an application source set if it occurs as the name of an element outside of XML island, or if it occurs as the value of the extends attribute of a <class> element outside of an XML island.
A tag is <dfn>defined</dfn> in an application source set if it occurs as the value of the name attribute of a <class> element outside of an XML island.
A tag is <dfn>defined</dfn> if it is defined in the application source set or the LZX schema.
The <dfn>autoinclude map</dfn> is a map from element names to Laszlo source file pathnames.
A Laszlo application whose source set references tags that are not defined, and are the keys of entries in the autoinclude map, is compiled as though the children of its main file's document root element were preceded by a set of <include> statements whose targets are the values of those entries.
The content of the autoinclude map is currently specified by the LPS 2.x implementation. There is a to do item to move the definition of this content to an implementation-independent specification.
Note that the existence of the autoinclude mechanism does not affect the treatment of a program that defines non-schema classes that it references. Its only effect is to cause some otherwise invalid programs to be valid.
Implementation
The first pass of the compiler scans for tags that are referenced but not defined in the program source. If any such tags are the names of keys in the autoinclude map, the files that define these tags (the values in the autoinclude map) are include as though by an <include> statement at the beginning of the application source root element.
The autoinclude map is in WEB-INF/lps/misc/lzx-autoincludes.properties.
The implementation of the algorithm for visiting the source was in compiler/CanvasCompiler.java. More recently, it will move to ToplevelCompiler.java.
Todo
The visitor should be factored into a Visitor class.
The autoinclude mechanism can't be used within a class that is itself autoincluded.
