- noun: someone performing exorcism
- noun: freeing from evil spirit
The Java Syntax Extender
Aim of this project is to create a small and easy to use tool, that can be used to extend the Java language syntactically. Why would you do that? There are basically two reasons:
First, you just might want to fix your pet-peeve in the language itself. For example, create new keywords like 'unless', 'foreach', new operators, or generate setter getters automatically for a bean property.
Secondly, you might tune the language itself for a specific project, so the project code may look more clean and thought out. For example: specific logger keyword, which automatically checks (if statement) whether the logger should be invoked or not, or even ommits the whole logging compile-time, when it's disabled! Or create a method modifier 'transaction' to enclose the whole method in a project specific transaction.
How it works on the outside
Exorcist is a compiler of extended Java code. The compiler can be used in command-line mode, or through Ant. Basically, with no extensions configured, Exorcist only compiles the standard java code. To extend the language, you can plug in classes, which extend a single interface of the exorcist framework, and implement a single (and simple) method. That's it.
How it works inside
Exorcist works like a pre-processor. It translates the extended language into plain Java code, and then compiles it using the standard Java compiler (javac).
To analyze a language, there are two steps involved. The first is a Lexical analysis, the second is the Parsing of the lexical tokens. Lexical tokens are strings, numbers, operators, dots, semicolons, etc. These are also called terminal symbols, because they can not be analyzed further. During parsing, lexical tokens are read, and non-terminal symbols may be produced. These include things like: expression, method body, declaration, if-statement, etc.
The Exorcist's tranformation engine works basically with lexical token lists. Each extension first matches itself to the start of the received token list, using terminal and non-terminal symbols freely. If the match is detected, the extension is free to modify the input token list as it pleases, and with it modify the output clean Java source code.
Features
- Easy to extend. (single interface, single method, single parameter).
- Preserves line numbers and lines during compile. All compile time message will have the same output as the Javac compiler. The file names, line numbers, and even messages will point to the source (extended java) file, and not the pre-processed clean (also called interim) file.
- Preserves line numbers runtime. In all exceptions, and stack traces, the line numbers will point to the original (extended java) file.
Installing
Exorcist must see the following required libraries for compilation:
- antlr.jar
- serp-1.12.1.jar
- exorcist-x.x.x.jar
Currently there are two ways to use the library: command line, or as an ant task.
In command line mode, exorcist works just like javac, only one
additional argument must be supplied, the "-interim <dir> option,
which specifies the directory for the interim (clean java code) files.
$ exorcist -interim build/interim -d build/classes src/com/acme/test/Test.java
For the ant task to work, first, you must include the following task definition
in the ant file:
<taskdef name="exorcist"
classname="hu.netmind.exorcist.ant.ExorcistCompilerTask"
classpathref="pathref"/>
Where pathref points to the required libraries listed above. After defining the
task, the exorcist task works exactly like the javac ant task, with the
additional attribute "interimdir, which specifies the interim files' directory.
<target name="compile" depends="init">
<exorcist classpathref="compile_classpath" srcdir="src/test"
debug="on" deprecation="off" nowarn="on" optimize="off" source="1.4"
destdir="build/test" interimdir="build/interim"/>
</target>
There is a sample build.xml file in the distribution.
For the command line version, or for the ant version to run, it is necessary to
have the exorcist.properties file available from the classpath. This is
a simple properties file which contains the currently active extension. The
file is like this:
# List of extensions, in the form of
# extension.<name>=class
extension.unless=hu.netmind.exorcist.ext.Unless
extension.log4jsyntax=hu.netmind.exorcist.ext.Log4jSyntax
extension.foreach=hu.netmind.exorcist.ext.ForEachLoop
extension.property=hu.netmind.exorcist.ext.BeanProperty
Tutorial
Currently no tutorial exist for extending the exorcist, please browse the source code, and the api documentation to see how it works.
Contact
Contact me (the developer) at: robert <dot> brautigam <at> netmind <dot> hu if you have questions, or you can use the freshmeat project page too.
Download
| File | Size (bytes) | Release Date | State |
|---|---|---|---|
| exorcist-0.3.0.tar.gz | 783068 | 2007/12/12 | Release |
| exorcist-0.2.0.tar.gz | 762835 | 2007/05/05 | Release |
| exorcist-0.1.0.tar.gz | 754695 | 2007/05/03 | Initial release |