JarCastingDuzzt
An Annotation-based Embedded DSL Generator for Java
What is Duzzt?
Duzzt is a Java Annotation Processor (library) to easily generate Embedded DSLs for Java. An Embedded DSL (or EDSL) is a fluent interface which follows a certain syntax, i.e., rules that describe legal sequences of method invocation chains. In Duzzt, regular expressions are used to define the syntax of embedded DSLs.
Using Duzzt
The steps required to use Duzzt naturally depend on which build system you are using.
Using Maven
The easiest way to use Duzzt is when using Apache Maven. Simply add the following snippet to your <dependencies> section:
<dependency>
<groupId>com.github.misberner.duzzt</groupId>
<artifactId>duzzt-processor</artifactId>
<version>0.0.2</version>
<!-- This will make sure the dependency is non-transitive! -->
<scope>provided</scope>
</dependency>
Manual Setup
If you are not using Maven (and do not use a build system with a compatible dependency management, such as Apache Ivy, you need the following libraries to be present in your classpath during compile time (for the latest stable version 0.0.1):
- duzzt-annotations-0.0.1.jar, containing the annotations used by Duzzt
- duzzt-processor-0.0.1.jar, containing the actual Duzzt annotation processor
- ST-4.0.7.jar, the StringTemplate library
- automaton-1.11-8.jar, the Brics Automaton library
- ap-commons-0.0.1.jar, a commons library for annotation processing
Note that none of these libraries is required during runtime of your program.
Getting Started
Check the examples in the Git repository for some usage examples, or the Wiki for a tutorial introduction. Or take a look at the Javadoc of the main annotation, @GenerateEmbeddedDSL.
Why Duzzt?
Some of the advantages (in my view) over other embedded DSL/fluent interface generators are:
- Very lightweight. The processor library (which only needs to be present during compile time) only depends on StringTemplate, the Brics Automaton Library and the AP Commons Library. The generated code does not have any dependencies (except for what you use in your implementation class).
- Easy syntax specification through regular expressions.
- The complete specification is written in pure Java, no external configuration files (e.g., XML) are required. You can profit from the full editing and content assist capabilities of your IDE.
- Convenience features, such as automatic creation of varargs method overloads.
- Highly configurable, but minimum configuration sufficient for many applications
Libraries used by Duzzt
Duzzt makes use of the following external libraries:
- StringTemplate (BSD License), for the template-based source code generation
- Brics Automaton (BSD License), for converting regular expressions into finite automata
- AP Commons (Apache License), for easier writing of annotation processors
License
Duzzt is distributed under the terms of the Apache License, Version 2.0.