CHANGES

Polyglot Change Log
===================

This file documents changes between releases of Polyglot. More information
about some releases may be found in the appropriate directory
doc/release-notes-<version>.

December x, 2021: Polyglot 2.8.0
================================

- Added JL8 extension (polyglot.ext.jl8) to support a subset of new Java 8
  language features, including lambda expressions and method references.
  Note that not all of Java 8 support is implemented. Notably, support for
  effectively final variables and annotations on generic type parameters are
  missing.

- The polyglot compiler is now compiled with JDK 8 and can compile itself.

- The polyglot compiler project can now run on JDK newer than JDK 8.

- Fixed most of the failing test cases.

June 23, 2016: Polyglot 2.7.1
=============================

- Non-backward compatible change: 'super' is now a keyword in PPG.

- CUP was updated to a variant of version 0.11v (20151001).

- Bug fixes to command-line argument handling, the base compiler, generics, and
  CupEx.

August 1, 2015: Polyglot 2.7.0
==============================

- The PPG parser generator now has much better debugging support, in the form
  of counterexamples to parsing conflicts. The algorithm is described in the
  PLDI 2015 paper by Isradisaikul and Myers.

- Many bug fixes, especially related to generics.

- Comments are now preserved in translated code, supporting use of
  Javadoc.

- Improvements to the pth testing harness.


June 10, 2014 : Polyglot 2.6.1
==============================

Minor changes were made to type serialization.

June 4, 2014 : Polyglot 2.6.0
=============================

Delegate objects and delegate factories are now deprecated.  AST nodes in
an extension need not be attached with delegate objects.  Rather, a _language
dispatcher_, an instance of type polyglot.ast.Lang, defines appropriate
dispatching mechanisms for all AST nodes.  Any class implementing Lang should be
singleton; multiple instances of the same Lang implementation are unnecessary.

Because AST nodes can represent multiple languages, NodeVisitor now requires an
instance of Lang to determine the appropriate language to work on.  Similarly,
Context now requires an instance of Lang.

The return type of polyglot.ast.Node_c:del() is changed from JLDel to NodeOps
because Node no longer extends JLDel.  Both extend NodeOps, however, which is
essentially what we need to dispatch to compiler operations.

Interface polyglot.util.Copy is now generic, to customize the return type of
copy().  Classes implementing Copy<T> should have T, instead of Object, as the
return type of copy().

JFlex was updated to to version 1.5.1 and CUP to a variant of version 0.11b beta
20140226.  The regular expression ".|\n" in *.flex files should be replaced with
"[^]" because "." excludes Unicode newline characters.

Deprecated features should still work with this version, with the exception of
any overriding of del() and copy() methods described above.

Changed the signature of reconstruct(...) to also take the node under
reconstruction.  Existing calls to reconstruct(...) should now be
reconstruct(this, ...).  This additional parameter allows the method to be used
by subclasses without creating temporary node objects when updating their
fields.


December 3, 2013 : Polyglot 2.5.4rc1
====================================

Changed signature of polyglot.visit.Dataflow to use Peer instead
of (Node,boolean) pairs. This change is not backward compatible.
For example, the signature of flow changed from
    flow(FlowItem in, FlowGraph<FlowItem> graph, Term n, boolean entry, Set<EdgeKey> edgeKeys)
to
    flow(FlowItem in, FlowGraph<FlowItem> graph, Peer<FlowItem> peer)
and the signature of confluence changed from
    confluence(List<FlowItem> items, List<EdgeKey> itemKeys, Term node, boolean entry, FlowGraph<FlowItem> graph)
to
    confluence(List<FlowItem> items, List<EdgeKey> itemKeys, Peer<FlowItem> peer, FlowGraph<FlowItem> graph).
From a Peer object p, the AST node can be obtained with p.node() and the
boolean indicating whether the dataflow is for entry or exit to the node
can be obtained with p.isEntry(). Edge keys for edges to successor nodes
is available via p.succEdgeKeys().

polyglot.ast.JL renamed to polyglot.ast.JLDel and polyglot.ast.JL_c renamed
to polyglot.ast.JLDel_c. This is intended to clarify the use of the
delegate pattern in Polyglot.

polyglot.ast.JLDel_c (the base class for JL delegate objects, formerly
polyglot.ast.JL_c) no longer extends polyglot.ast.Ext_c.


June 21, 2013 : Polyglot 2.5.3
===============================

Many bug fixes, especially for generics.

One non-backward compatible change: Annotation elements are no longer Exprs.
This fixes issues with constant folding.


April 25, 2013 : Polyglot 2.5.2
===============================

Many bug fixes, and improved annotation support.

Fields ImportTable.CLASS and ImportTable.PACKAGE renamed to
ImportTable.SINGLE_TYPE and ImportTable.TYPE_IMPORT_ON_DEMAND
respectively, to reflect both Java Language Specification terminology,
and the actual semantics.


October 15, 2012 : Polyglot 2.5.1
=================================

Changes to FileManager to remove some artificial limitations. The method
FileManager.getAbsPathObjMap() was removed from the FileManager API.  Access to
in-memory files should be performed via the core API.


August 10, 2012 : Polyglot 2.5.0
================================

Added JL5 extension (polyglot.ext.jl5) to support Java 1.5 language features.
Based on the "Polyglot for Java 5" project by Milan Stanojevic and Todd
Millstein (http://www.cs.ucla.edu/~todd/research/polyglot5.html), with
additional input from Vincent Cavé. The extension currently
supports all Java 5 langage features, except for annotations.

New FileManager support so that intermediate files generated by
Polyglot, including Java sources, are maintained within the JVM rather
than being written out to the file system. Performance is also improved
by running the javac backend, by default, directly within the same JVM
as Polyglot. See the release notes for more details about how to modify
existing extensions accordingly.

The source code of Polyglot has itself been updated to take advantage of the
generics support introduced in Java 1.5. This may break older extensions that
assume non-generic interfaces.

A common pattern used for outputting AST nodes as input to another extension
has been imported into the Polyglot framework.  The polyglot.translate package
contains the ExtensionRewriter for rewriting ASTs and many convenience classes
for default translations.

Parsing of command line options has been overhauled.  These changes bring more
flexibility to configuring multiple extensions in a pipeline using ExtensionRewriters.

Precedence of = vs. ?: fixed.

The -mergestrings option was added.

Class polyglot.visit.DataFlow refactored to allow detection of back
edges in control flow graphs, which allows subclasses to use a
widening operator.

Many miscellaneous bug fixes were made.


Aug 14, 2008: Polyglot 2.4.0
============================

New command line options for output directories: -D can be used to specify the
output directory for *.java files, while -d remains the output directory for
*.class files. If only one of the two is given, both directories are set to be
the same. That is, if only -d is given, the current behavior of placing both the
*.java and *.class files into the specified directory is maintained.

Combined type-check and constant-check passes since they're interdependent.

Added visitor InnerClassRemover to remove inner classes.

Miscellaneous bug fixes.


Oct 5, 2007: Polyglot 2.3
=========================

Dataflow framework changed to add functionality. CFGs now have two nodes per
term, one representing the "entry" into that term, another the "exit".
Extensions will have to be updated to work with this new framework.
See doc/DATAFLOW_2_0.txt for a more detailed explanation of the changes.
Contributed by Xin Zheng.

Miscellaneous bug fixes.


Jul 27, 2007: Polyglot 2.2.3
============================

Miscellaneous bug fixes.


Jun 5, 2007: Polyglot 2.2.2
===========================

Miscellaneous bug fixes.


May 11, 2007: Polyglot 2.2.1
============================

Fixed assumption that return statements occur only within methods.

Added copy(NodeFactory) method to Node interface to generate a new
version of a node with a different node factory.

Miscellaneous bug fixes.


Feb 23, 2007: Polyglot 2.2.0
============================

Added CodeNode and CodeBlock as a super-interfaces of CodeDecl that are
not a ClassMembers.  This is to help extensions with things like
closures.  Changed DataFlow to use CodeNode.  This change may break some
extensions.

Removed MemberInstance as a super-interface of CodeInstance and
ProcedureInstance.  This change may break some extensions.  Replacing
uses of CodeInstance with MemberCodeInstance and ProcedureInstance with
MemberProcedureInstance should fix the problems in most cases.

Added FunctionInstance interface: procedures with return types that are
not methods.

Miscellaneous bug fixes.  Patch from Bob Fuhrer (rfuhrer@us.ibm.com).


Feb 8, 2007: Polyglot 2.1.0
===========================

To provide better position information for identifiers in the AST, replaced
Strings in the AST with an Id node.  The old factory methods and accessor
methods for the Strings should still work, but the node constructor signatures
for Local, LocalDecl, Formal, ConstructorDecl, MethodDecl, Call, Field,
FieldDecl, ClassDecl, Branch, Labeled, and Amb* have changed Subclasses may
break if they access the old String fields directly rather than through
accessors.  Be especially careful to check visitChildren and calls to equals
on the old String field.

Added NamedVariable super-interface of Field and Local.

Miscellaneous bug fixes.


Jan 8, 2007: Polyglot 2.0.2
===========================

Cleaned up build.xml

Added TypeBuilder.pushContext.

Miscellaneous bug fixes.


Dec 22, 2006: Polyglot 2.0.1
============================

Removed references from to BaseParser in polyglot.parse.Name
so extensions can use Name without pulling in java_cup.

Fixes to build.xml.

Miscellaneous bug fixes.


Dec 8, 2006: Polyglot 2.0.0
===========================

Allow code generation of untyped ASTs using Translator.
TypedTranslator can be used for type-directed code generation.

Moved example extensions to top-level examples directory.

Moved skeleton extension to top-level.

Added file offsets to Position (patch from Bob Fuhrer).

More precise Position annotations for some nodes (patch from Bob Fuhrer).

Don't assume String is final in Binary (patch from Bob Fuhrer).

Numerous bug fixes.


Jun 8, 2006: Polyglot 2.0rc1
============================

Fixed bug with post compiler not handling spaces in file names.
Patch from Igor Peshansky (igorp@us.ibm.com).

Moved classes in polyglot.ext.jl.* to polyglot.*.
Renamed polyglot.ext.jl.ExtensionInfo to polyglot.frontend.JLExtensionInfo.
Renamed polyglot.ext.jl.Version to polyglot.frontend.JLVersion.
Renamed polyglot.ext.jl.JLScheduler to polyglot.frontend.JLScheduler.


Feb 2, 2006: Polyglot 2.0alpha4
================================

Fixed numerous bugs with serialization of type information.

Fixed bug where MembersAdded goal was reached before
default constructor was added.

Added factory method in ExtensionInfo for
polyglot.types.reflect.ClassFile (thanks to Jennifer Lhotak
for the patch).

Miscellaneous minor bug fixes.


Nov 25, 2005: Polyglot 2.0alpha3
================================

Fixed numerous bugs with serialization of type information.

Moved (member) class lookup to ClassContextResolver and
PackageContextResolver to eliminate duplicate code.
Resolver performance improvements.

Deprecated TypeSystem.parsedResolver().  Use TypeSystem.systemResolver()
instead.

Removed outer() resolver from ImportTable and PackageContextResolver.
Use TypeSystem.systemResolver() instead.

Fixed bugs with accessibility checking for member classes.
Added AccessControlResolver interface.

Added Type.typeEquals and Package.packageEquals.  These methods
should implement semantic equality for types and packages.
TypeObject.equals implements structural equality.  In the base
compiler, the implementations are the same, but in extensions,
especially those with features like type aliases, the distinction
is important.

Fixed bugs with exception checking.  More precise exception error
message positions.

Bug fixes and performance enhancements in CodeWriter.
Improved quality of pretty-printer output.

Compiler.compile(Collection sources) takes a collection of Sources
rather than filenames.  Old behavior available with
Compiler.compileFiles(Collection filenames).

More efficient pass scheduling.  Better infinite loop reporting.
Moved goal dependencies from scheduler to Goal classes.

Restored Node.isTypeChecked().

Added ErrorInfo.DEBUG.

Fixed bugs with constant checking.

Fixed bugs with disambiguation of anonymous classes.

Fixed bugs with switch statement semantic checking.


Aug 31, 2005: Polyglot 2.0alpha2
================================

Simplified scheduler interface.  See Scheduler.java for details.

Renamed Node.enterScope to Node.enterChildScope.


Jul 6, 2005: Polyglot 2.0alpha
==============================

New pass scheduler and many other non-backward-compatible changes.
See doc/Upgrade.txt for more details on the changes and
for instructions on upgrading extensions.

New command-line option, -commandlineonly, tells the compiler
to compile only files listed on the command-line, not dependees
of those files.


Jul 5, 2005: Polyglot 1.3.2
===========================

Miscellaneous bug fixes with method lookup.

Changed implementation of polyglot.util.Base64 to allow relicensing.

Certain files in the distribution are now licensed under the Eclipse Public
License as well as LGPL.  See the README for more details.


Mar 24, 2005: Polyglot 1.3.1
============================

Miscellaneous bug fixes with operator precedence, lexing,
pass scheduling, data flow, class loading.

Added -j to jlc script to allow options to be passed to the VM.
For example, 'jlc -j -Xmx512m -ext pao' will pass -Xmx512m to the VM.

Added method Position.compilerGenerated(), which creates a Position
object for the line number in the compiler that called
Position.compilerGenerated().

TypeSystem.packageForName can now throw a SemanticException.
TypeSystem.createPackage implements the old behavior.


Jul 30, 2004: Polyglot 1.3.0
============================

Miscellaneous bug fixes in data flow, class loading, constant folding,
and other areas.

Faster data flow analysis.

Improved error recovery in the Java parser and in ErrorHandlingVisitor.

Added some simple statistics reporting enabled from the command-line
with "jlc -report time=1".

Improvements to the Polyglot Test Harness (PTH): results are saved
after each file, permitting a test run to be aborted and resumed
later more easily.

Language extensions can now compile files with different file
extensions, e.g., ".jl" and ".java".

Rewrote the Java lexer to avoid licensing problems.


Apr 9, 2004: Polyglot 1.2.0
============================

Miscellaneous bug fixes.

The class polyglot.util.Position can now record end column and
line numbers. The CUP or PPG grammar file is responsible for
setting the position for AST nodes correctly (for an example, see
the file src/polyglot/ext/jl/parse/java12.cup). Support is however
required from the lexer. If your extension uses a PPG file that
extends the file java12.cup, you should be able to take advantage
of the end positions by modifying your JFlex file to record end
positions, as done in src/polyglot/ext/jl/parse/java.flex. The
changes are backwards compatible: if your JFlex file does not
record end positions, the functionality of Positions will be the
same as in the previous release. Thanks to Ondrej Lhotak and
Jennifer Lhotak for suggesting this change, and providing the code
for it.

pth (Polyglot Test Harness) is a small tool to assist in automated
regression testing of Polyglot extensions. See the file
tools/pth/README for more information.

Illegal forward references now detected.

Control flow graph for binary and unary operators is now more
precise, permitting more precise dataflow analyses.

The signature for the methods findMethod, findConstructor, and
findMemberClass, in polyglot.types.TypeSystem have changed; old
versions of these methods are still present but deprecated.


Dec 18, 2003: Polyglot 1.1.1
============================

Bug fixes in initialization checking.

Refactored data flow slightly to allow subclasses to have more control of
the confluence operation.  Legacy behavior is maintained, so no
subclass will be invalidated by this change.

Made Term_c.acceptCFG() abstract to force new Terms to implement
it rather than using the default implementation.

Added some accessors for private/protected fields.  Made some
package-scoped fields protected.


Nov 19, 2003: Polyglot 1.1.0
============================

Numerous changes have been made to improve the performance of
Polyglot.  It is now more efficient, especially when compiling
large code bases.

The scheduling of passes run on source files has been modified to
take advantage of more precise dependencies between source files.
This allows for more efficient scheduling.  See
polyglot.frontend.AbstractExtensionInfo for more details.

A global barrier pass has been added to facilitate whole program
analyses.  See polyglot.frontend.GlobalBarrierPass for more
information.

The dataflow framework (polyglot.visit.DataFlow) has been modified
to allow dataflow upon either entering or leaving a code
declaration.  This allows the results of dataflow analyses to be
available when visiting the AST nodes inside a code
declaration.  The default (and legacy) behavior is to perform
dataflow upon leaving a code declaration.

The serialized type information that Polyglot produces in output
files is now encoded in base 64, which reduces the size and improves
the readability of the Java output files.  Class files compiled with
previous versions of Polyglot are not readable with Polyglot 1.1.

Serialized type information for member classes is now stored as a
field in the member class itself, instead of as part of the
serialized type information of the top level class that contains
the nested class.  This resolves a circular dependency bug in
class loading.

Terms record whether or not they are reachable, as this
information is useful in later passes.  The ReachChecker visitor
sets this information.

The reachability pass is now performed before the exception
checking pass, making exception checking more precise.

A utility class PolyglotAntTask (in $POLYGLOT/tools) facilitates
the compilation of language extensions in the ANT framework.

PPG now passes through precedence modifiers to JavaCUP.

Numerous bug fixes, including:
  - numeric conversions of short, int, etc.
  - constant folding
  - nested classes
  - imported class lookup
  - code generation


Converting existing extensions:
-------------------------------
Terms must now have methods to access and record reachability
information.  If you have defined AST nodes that do not extend
polyglot.ext.jl.ast.Term_c, you may need to modify them.  See
polyglot.ast.Term and polyglot.ext.jl.ast.Term_c for
information/examples.

ParsedClassTypes now record from which source they were parsed
from, if they were parsed during the current compilation.  If you
have defined ParsedClassTypes that do not extend
polyglot.ext.jl.types.ParsedClassType_c, you may need to modify
them.

The signature for the class polyglot.types.TypeSystem has changed.
  * void initialize(LoadedClassResolver loadedResolver)
    has changed to
    void initialize(LoadedClassResolver loadedResolver,
                    ExtensionInfo extInfo)

  * ParsedClassType createClassType(LazyClassInitializer init)
    has changed to
    ParsedClassType createClassType(LazyClassInitializer init,
                    Source fromSource)

  If you have overridden these methods in a subclass of
  polyglot.ext.jl.types.TypeSystem_c, you should change your
  method signatures.


Aug 18, 2003: Polyglot 1.0.1
============================

Bug fixes:
- "import" declarations now import member classes.
- Detect uses of "this" in a static context.
- Detect multiply-defined local variables.
- Detect circular constructor invocations.
- Fixed bugs with Node.childExpectedType for arithmetic expressions.
- Fixed bugs with data-flow analysis through local and anonymous
  classes.
- Renamed some protected methods in Context_c to avoid some
  confusion.


Jul 8, 2003: Polyglot 1.0.0
===========================

We have changed the license from GPL to LGPL.  This should allow
more flexibility in licensing extensions to Java.

Many bugs in the base compiler have been fixed.

Node factories have been redesigned to be more extensible.
Existing subclasses of the base compiler node and extension
factories may need to be modified.

The quasiquoting interface has been changed to be easier to use.

New AST node types for local, field, and array assignment were
added.  Distinguishing the type of the left-hand-side permits
easier implementation of data-flow analyses.

The data-flow analysis framework was reworked to permit more
precise analyses.