This release improves attribute tracing with new tracing events and bug fixes.
INC_FLUSH_START
and INC_FLUSH_END
for tracing the start and
completion of attribute flushing.tracing=compute
is
enabled, fixing COMPUTE_END
events having the wrong attribute value.Improvements to Java 8 support, bug fixes and various internal code cleanups.
setParent()
on empty container singleton.grammar
option is now optional when using the jjtree
option.Performance improvements and bugfixes were added for incremental evaluation. A very simplified summary of the changes:
The component setting methods (setChild, addChild, setX, etc.) now return the reference to the modified node so that AST construction calls can be chained together in a sequence of method calls.
This feature was contributed by Alexandru Dura in pull request 10.
JastAdd can now remove most unused imports in generated code. Enable this by
adding the --optimize-imports
option to the JastAdd command.
A collection attribute with implicit collection root can now be used in grammars with multiple root node types. The collection root will then be the root of the current AST (dynamically found). See issue 294.
A new option to enable concurrent attribute evaluation has been added. This option makes the generated code for attributes safe to run in multiple threads concurrently. Automatic parallelization is also available via parallelized collection attributes. To be able to safely use circular attributes with concurrent evaluation, all generated code (except for the parallelized collection attributes) is lock-free.
To enable concurrent code generation, add the --concurrent
option.
Collection attributes can be parallelized by annotating the attribute
declarations with @Parallel
and/or @ParallelSurvey
.
The new --emptyContainerSingletons
option has been added to reduce runtime
memory use. This option was developed by Axel Mårtensson for his Master
Thesis. He found a 5-24% memory reduction using this option on ExtendJ and
JModelica.
The option alters the setChild
method for list and optional children so that
it replaces empty lists and optionals by singleton objects representing these
empty containers. The singleton objects are non-mutable, and they throw
exceptions if you try to mutate them. This works well with the way JastAdd ASTs
are usually constructed: they are typically only mutated during parsing via the
setChild
methods.
The way circular rewrites are evaluated has been changed: the
Object.equals(Object)
method is now used, instead of
ASTNode.is$Equal(ASTNode,ASTNode)
, to test if the rewritten node is equal to the
previous node. This means that it is possible to define a custom node
comparison method. The previous way rewrite values were compared was to compare
the AST structure and tokens. The old behaviour can easily be reimplemented if
it is desired and if not then a simpler equality test can be used.
This change affects rewrites that don't have a rewrite condition and rewrite to the same node type.
Removed an obsolete variant of the refine
statement.
The refinement syntax for methods and synthesized equations had a variation where the equation or code block was replaced by "to refine", for example:
refine Aspect1 eq A.x() to refine Aspect2 eq A.y() = ...;
This could be used to rename an attribute, however a similar effect can be achieved by simply creating a new attribute calling the old one. The only difference is that the old attribute remains.
The tracing API has been redesigned to be more light-weight and flexible.
Trace events are no longer filtered, stored, and processed by the tracing API.
Instead, a listener model is used to handle tracing events.
Users that need to listen to trace events should now register a class
implementing the interface ASTState.Trace.Receiver
by calling
ASTState.Trace.setReceiver(Receiver)
.
Some benefits of the tracing API changes are:
Summary of tracing changes:
api
option to the --tracing
flag. Specifying --tracing=api
will
generate the ASTState.Trace
class, but not insert trace events in generated
code. This is used to make user code using the tracing API compile even
without incurring the runtime overhead of generating trace events in
attributes.--cache=analyze
option.CACHED
trace event to CACHE_WRITE
- this makes the naming
consistent with the CACHE_READ
event.ASTState.Trace.Receiver
.ASTState.Trace.setReceiver(Receiver)
.ASTState.Trace.Entry
.ASTState.Trace.InputFilter
.ASTState.Trace.Processor
.ASTState.Trace.PrintProcessor
.ASTState.Trace
:
registerInputFilter
, process
, clear
, getEventList
, printReport
,
printTrace
, printComputeReport
, printCacheAbortReport
,
printCacheReport
, printCopyReport
, printCircularNtaNestingReport
,lazy
keyword
is optional.inhEqCheck
option in the JastAdd Ant task.addAll
method in the generated List
class.jastadd.JastAdd
- use org.jastadd.JastAdd
instead.jastadd.JastAddTask
- use
org.jastadd.JastAddTask
instead.get{X,XList,XOpt}NoTransform
for NTA components. This change caused certain
NTAs using inherited attributes to trigger an unbounded recursion. The change
to the NoTransform
getters has been reverted, so that they do not evaluate
the corresponding NTA component.
More info--safeLazy
option which enables non-circular cached attributes to
be safely used in a circular evaluation cycle. It is still required that at
least one attribute in every circular dependency cycle is declared circular,
but using --safeLazy
allows more lightweight caching of attributes
in a circular evaluation cycle.getXNoTransform(int)
method, which
is equivalent to calling getXList().getChildNoTransform(int)
.
More infogetXNoTransform()
, getXListNoTransform()
, and getXOptNoTransform()
, so
that now they are equivalent to getX()
, getXList()
, and getXOpt()
. This
means that these methods no longer return null if the NTA was not previously computed,
however they do trigger rewrites on the NTA value despite the NoTransform
suffix.
More infoadd
method
is used if no update method is specified.
More info--cache=implicit
and --cache=config
options, as they are now obsolete.ASTNodeAnnotations.DeclaredAt
annotation.
More infoIterable<ASTNode>
interface from ASTNode
.
More infoASTNode.astChildren()
returning an
Iterable<ASTNode>
object for iterating over the children of an AST node.
This replaces using ASTNode
as an iterable.ASTNode
.
More infoASTNode.state
is now private.--stateClassName
option, which can be used to customize the name of
the generated class ASTNode$State
.nta
keyword on the equation and simultaneously having the
corresponding child declared using the /NTA/
syntax in the grammar now
store their value in the child array. This fixes a long-standing issue where
such NTAs effectively discarded their equation value. A new warning message is
generated to warn about NTAs that were affected by this issue. The warning can
be silenced by removing the nta
keyword from the NTA equation. More
infosyn
, eq
, and inh
as
regular Java identifiers in certain Java code contexts such as attribute
equations or method bodies. More
infoDefine_XXX
method names.--help
output.--ASTNodeSuper
option to set a custom superclass for ASTNode.
More
info--dot
option to generate a class diagram for the input grammar in
the Dot format.--generateImplicits
option. Setting this to false
means that
ASTNode, List, and Opt must be declared in the grammar. This makes it
possible to declare ASTNode abstract.--rewrite
option accepts the true
value again. The true
value was
unintentionally removed in version 2.1.9.--java1.4
option has been disabled. If Java 1.4 support is required
then a third-party translator can be used, such as Retrotranslator
(http://retrotranslator.sourceforge.net/)public <T> void A.m()
JastAdd now generates annotations for children, tokens and attributes
(@Child
, @ListChild
, @OptChild
, @Token
, @Attribute
).
Removed obsolete aspect "sons" declaration.
JastAdd no longer strips modifiers from aspect interface declarations.
JastAdd no longer removes static or adds public modifier to aspect class declarations.
Fixed regression introduced in 2.1.6 which caused circular collection attributes to crash JastAdd.
Fixed some cases where the order of parsing aspect files could produce different results.
JastAdd now inlines all equation compute methods where the equation is a single Java expression.
JastAdd uses a new inherited equation checking analysis that runs quicker on grammars with many inherited attributes. This can reduce JastAdd compile times for large projects.
JastAdd now generates the trace class as the nested class
ASTNode$State.Trace
. The global Trace
instance is accessed using the
method ASTNode$State.trace()
.
Added the ASTNode.treeCopyNoTransform()
method to replace
ASTNode.fullCopy()
, deprecating fullCopy
.
Added the ASTNode.doFullTraversal()
method which uses getChild()
to
traverse the subtree and trigger rewrites.
Added the ASTNode.treeCopy()
method which uses doFullTraversal()
to
trigger rewrites before copying the tree with treeCopyNoTransform()
.
JastAdd now supports a flush flag which allows for configuring of flushing.
The flag takes the following values: attr
, coll
, rewrite
, full
.
Default is attr
and coll
. The rewrite
value makes flushing of outermost
rewrites possible by storing their initial values. The full
value includes
all values.
The default flushing API provided by JastAdd has been extended with a
flushTreeCache()
method calling flushCache()
and traversing the tree. A
call to this method together with the use of the flush=full
will result in a
full flush of an AST.
Attributes are flushed via separate reset methods, one per cache attribute.
All cached attributes in a node are flushed from a flushAttrCache()
method
which is called from flushCache()
.
Rewrites are flushed from a flushRewriteCache()
method which is called from
flushCache()
.
Added support for static configuration of tracer events via the --tracing
flag. The flag can now be given a comma separated list of event categories
to be generated. Accepted values are compute
,cache
,rewrite
,circular
,
and copy
. All events are generated by default.
Added support for a --cache
flag taking one of the following values: all
,
none
, config
, implicit
, and analyze
. This flag provides a global
cache configuration, replacing local configuration with the lazy
keyword.
The config
and implicit
values use a .config
file to provide a cache
configuration on attribute level. The analyze
value uses tracing together
with full caching to analyze caching behavior and to compute a cache
configuration via the CacheAnalyzer
class.
The Ant task jastadd.JastAddTask
now prints a deprecation warning. The
classname org.jastadd.JastAddTask
should be used instead.
JastAdd now requires at least one grammar file (.ast) given on the command line.
If there is any problem in the JastAdd configuration, JastAdd no longer prints the full help text. A single line is printed describing how to get more help. This avoids the problem of the help text drowning out error messages.
Undeprecated the --visitCheck
option (will replace --noVisitCheck
in the
future by adding a boolean argument)
Undeprecated the --cacheCycle
option (will replace --noCacheCycle
in the
future by adding boolean argument)
Fixed regression in version 2.1.3 that caused the generated Tracer
class to
always be generated in the default package. If it is generated, the Tracer
class is now generated in the same package as the rest of the AST.
The generated methods clone
, copy
, and fullCopy
can now be refined just
like regular aspect methods.
The undocumented sons
declaration is now deprecated. This feature did not
actually alter code generation in any way, but was still used in for example
JastAddJ. If the JastAdd parser encounters such a declaration it now generates
a warning.
JastAdd no longer requires an implicit root node in the AST grammar. A root node is a non-abstract node that can not be a child of any other node type. Root nodes are still required for collection attributes, so if you use a collection attribute with a grammar that lacks an implicit root node, you must declare the root node in the attribute declaration.
The warning messages for missing inherited equations have been improved by including an example AST path that lacks an equation for the attribute.
An example of the new warning messages: "missing inherited equation for attribute attr in class Expr when being child of X (path: Program->C->X->Expr)"
JastAdd no longer generates the Tracer
class when the --tracing
option is
absent.
Disabled the generation of an unused interface named Filter
. This interface
was generated by the previous version of JastAdd as a side-effect of how the
Tracer
class was generated.
Interface Modifiers: JastAdd strips all modifiers from interface declarations. This stripping of access modifiers is probably an unintentional error in the parser.
In future versions of JastAdd the interface modifiers will be retained in the generated code. Unfortunately if incorrect modifiers are given to an interface declaration in an aspect, then the generated code will fail to compile.
Note that the protected
, private
and static
modifiers are only
allowed on member interfaces (declared inside an enclosing class). Top-level
interface declarations should not use protected
, private
, or static
.
JastAdd now prints warning messages for each interface declaration that has any modifiers. Check that your interfaces use correct modifiers to ensure that your code continues to compile even with future JastAdd versions.
Type Declaration Modifiers: In addition to the stripping of modifiers
from interface declarations JastAdd alters the modifiers of class and
interface declarations by removing any occurrence of static
and adding the
public
modifier if the modifier list was empty.
We want to remove this behaviour from JastAdd, so a new warning message is
generated for all type declarations where the implicit public
modifier is
added. The message warns that future versions of JastAdd will cease to make the
class public
automatically. To silence the warning, simply add public
or
protected
modifiers to the declaration.
SuppressWarnings: JastAdd no longer generates @SuppressWarnings
annotations. The purpose of using the annotation was to reduce the number of
Java warnings in the generated code - however JastAdd was not smart enough to
correctly use the annotation, and if the annotation is incorrectly used it will
raise another warning. Ideally the number of warnings should be reduced by
generating better code instead.
The --suppressWarnings
flag, and corresponding JastAddTask option, has
been deprecated and will be removed from JastAdd in a future release.
Renaming ASTNode, List, Opt: New options have been added to JastAdd that
allow renaming the generated ASTNode
, List
and Opt
classes. The names
can be specified using the following command-line flags (corresponding options
for the Ant task are also available):
--ASTNode=<NewName>
ASTNode will be named "NewName"--List=<NewName>
List will be named "NewName"--Opt=<NewName>
Opt will be named "NewName"Annotations: Annotations are now supported for synthesized attributes and aspect-declared classes and interfaces!
Annotations on attributes are allowed before the attribute keyword (syn
,
eq
). For synthesized attributes the annotation is generated on the method
with the same name - not the "compute" method. Annotations are not yet
supported for other kinds of attributes although they should now produce more
readable error messages rather than standard mysterious parser syntax errors.
Tracing: Attribute evaluation tracing is now done in-memory by the
generated class Tracer
.
Comments: Fixed several issues with comments in the generated code:
@ast method
tagJastAdd now generates the utility method List.addAll(Collection)
which can
be used to initialize an AST List with a set of children.
List components now get a "has" accessor which returns true
if the list
component is non-empty.
Added flag --lineColumnNumbers
which makes JastAdd generate methods to get
and set start- and end positions for AST nodes. This can be used with version
1.0.2 and later of JastAddParser (by passing --no-beaver-symbol
to
JastAddParser) to remove the need of having beaver.Symbol as a supertype of
ASTNode when Beaver is used as the parser generator. See the JastAddParser
documentation for further details.
The syntax for annotating collection attributes has been slightly changed.
Annotations are now only allowed before the coll
keyword, rather than
after. The supported annotations for collection attributes are not discussed in
the documentation, so we don't expect this change to affect anyone. It is
possible that these annotations will disappear in the future anyway - use at
your own peril!
Generated source files have been moved to the package org.jastadd
The build script now compiles to ant-bin in order to avoid conflicts with the eclipse project
fullCopy
to initialize NTA children with
incorrect child indices.org.jastadd
(but left a deprecated
class with the same name as a working entry point for backward compatibility)List
nodes (previously also affected
Opt
nodes)minListSize
optionfullFlush
was added to enable more thorough flush behaviour
(makes flushCache
flush rewrites and NTAs)ASTNode.copy()
now sets the parent pointer of the copy to null
ASTNode.getChild(ASTNode,int)
--doxygen
option is now deprecated--indent
command-line option which allows changing the
indentation in generated code. Can be set to tabs or 2-, 4-, and 8 space
indentation.