dsl

The base of a groovy DSL is the Script class or the DelegatingScript. To provide some functions to your DSL, you define them in this class, implement the missingMethod or enhance the metaclass. No matter which way you choose, it blows up your class with rising amount of functions. So after some time you might want to restructure your code. For some other reason you might want to enable other people to enhance the DSL without touching the base DSL class.

The idea is to provide a class that can be instantiated in you DSL with a create-method.

1. Define a marker interface to find the plugin class (you can do this with annotations as well)

Every class implementing this marker interface will be instantiable in your DSL

interface Instantiable {}

1	interface Instantiable {}

2. A class that enhances your DSL

We’ll have a Car class that has only one field describing the color of our car

class Car implements Instantiable {
    def color = "blue"

    def printColor() {
        println color
    }
}

class Car implements Instantiable {

def color = "blue"

def printColor() {

println color

}

3. The actual DSL-backing class

Now we’ll go to the bone. As mentioned above, there are several ways to enhance the DSL class with new functions. In this sample we’ll add new functions by enhancing DSL’s metaClass.

We’ll have two functions to get an instance of Car: newCar and newCarWith.

newCar is calling the Default-Constructor without arguments. newCarWith calls the “Named” Default-Constructor with a map. To achieve this, there are two closures defined in line 3 and 4. First one with two params (actual class and the map) and one with a single param (only the class to instantiate).

Now we need to find the classes to instantiate. I used the reflections-API to find all classes implementing the Instantiable interface (line 6). In this sample only classes of the package de.metacode.dslplugin are scanned. You can scann the whole known classes as well.

Line 7 and 8 is where the magic happens: Two new methods are added to metaClass. Note the curry-call on the newInstance-closures. What this does is called currying (or Schönfinkeln). It reduces a function with n arguments to a function with n-1 arguments. In this case curry generates a new closure without the first parameter Class clazz. So we have one closure without any parameter and another one with a map.

class DSL {
    static {
        def newInstanceWithArgs = { Class clazz, Map args -> clazz.newInstance(args) }
        def newInstance = { Class clazz -> clazz.newInstance() }

        new Reflections("de.metacode.dslplugin").getSubTypesOf(Instantiable).each { Class clazz ->
            DSL.metaClass."new${clazz.simpleName}With" = newInstanceWithArgs.curry(clazz)
            DSL.metaClass."new${clazz.simpleName}" = newInstance.curry(clazz)
        }
    }
}

class DSL {

static {

def newInstanceWithArgs = { Class clazz, Map args -> clazz.newInstance(args) }

def newInstance = { Class clazz -> clazz.newInstance() }

new Reflections("de.metacode.dslplugin").getSubTypesOf(Instantiable).each { Class clazz ->

DSL.metaClass."new${clazz.simpleName}With" = newInstanceWithArgs.curry(clazz)

DSL.metaClass."new${clazz.simpleName}" = newInstance.curry(clazz)

}

4. Writing some DSL-code

Now we can instantiate the Car without params or with named params:

blueCar = newCar() //blue is the default value
blueCar.printColor()

redCar = newCarWith color: 'red'
redCar.printColor()

blueCar = newCar() //blue is the default value

blueCar.printColor()

redCar = newCarWith color: 'red'

redCar.printColor()

The output is

blue
red

blue

red

That’s it

Here you’ll find executable wired-together code:

https://gist.github.com/codeeraser/31d031cd921e168049ac

You’ll might get some issues with reflections-API when running this code via command-line. To get reflections work like one would expect can be pretty annoying (see stackoverflow…). The shortest way is to run the sample in an IDE.

This is how you can implement a gradle-ish behavior of executing a designated method before everything else in a dsl script (gradle executes doFirst{} first). Actually, I have no clue how gradle does it. This approach is about manipulating the AST with an implementation of CompilationCustomizer. I’ll describe two variations. First, how to execute the script twice, e.g. to set up an environment and execute the actual code sometimes later. And than how you can re-order the statements before execution. It’ll be helpful if you know about how AST transformations work (if you don’t, see the links at the end of this article).

Let’s say we have a DSL script like this:

println "this is text that will not be printed out in first line!"

doFirst { println "First things first: e.g. setting up environment" }

doStuff { println "doing some stuff now" }

println "That's it!"

println "this is text that will not be printed out in first line!"

doFirst { println "First things first: e.g. setting up environment" }

doStuff { println "doing some stuff now" }

println "That's it!"

First variation:

We’ll handle the DSL using DelegatingScript. The is the delegate for the first run (only doFirst will be executed):

class DoFirstProcessor {
    def doFirst(Closure c) {
        c()
    }
}

class DoFirstProcessor {

def doFirst(Closure c) {

c()

}

For the second run this is doing everything else:

class TheRestProcessor {
    def doStuff(Closure c) {
        c()
    }

    def methodMissing(String name, args) {
        //nothing to do
    }
}

class TheRestProcessor {

def doStuff(Closure c) {

c()

}

def methodMissing(String name, args) {

//nothing to do

}

At this point we’ve got everything we need to execute the DSL. Now comes the AST transformation part. The following CompilerCustomizer removes every statement from the AST except a designated method. Because there can only be one (method), this is called the HighlanderCustomizer 😉

class HighlanderCustomizer extends CompilationCustomizer {
    def methodName

    HighlanderCustomizer(def methodName) {
        super(CompilePhase.SEMANTIC_ANALYSIS)
        this.methodName = methodName
    }

    @Override
    void call(SourceUnit sourceUnit, GeneratorContext generatorContext, ClassNode classNode) throws CompilationFailedException {
        def methods = classNode.getMethods()
        methods.each { MethodNode m ->
            m.code.each { Statement st ->
                if (!(st instanceof BlockStatement)) {
                    return
                }
                def removeStmts = []
                st.statements.each { Statement bst ->
                    if (bst instanceof ExpressionStatement) {
                        def ex = bst.expression
                        if (ex instanceof MethodCallExpression) {
                            if (!ex.methodAsString.equals(methodName)) {
                                removeStmts << bst
                            }
                        } else {
                            removeStmts << bst
                        }
                    } else {
                        removeStmts << bst
                    }
                }
                st.statements.removeAll(removeStmts)
            }
        }
    }
}

class HighlanderCustomizer extends CompilationCustomizer {

def methodName

HighlanderCustomizer(def methodName) {

super(CompilePhase.SEMANTIC_ANALYSIS)

this.methodName = methodName

}

@Override

void call(SourceUnit sourceUnit, GeneratorContext generatorContext, ClassNode classNode) throws CompilationFailedException {

def methods = classNode.getMethods()

methods.each { MethodNode m ->

m.code.each { Statement st ->

if (!(st instanceof BlockStatement)) {

return

}

def removeStmts = []

st.statements.each { Statement bst ->

if (bst instanceof ExpressionStatement) {

def ex = bst.expression

if (ex instanceof MethodCallExpression) {

if (!ex.methodAsString.equals(methodName)) {

removeStmts << bst

}

} else {

removeStmts << bst

}

} else {

removeStmts << bst

}

st.statements.removeAll(removeStmts)

}

Bring it all together:

def cc = new CompilerConfiguration()
cc.addCompilationCustomizers new HighlanderCustomizer("doFirst")
cc.scriptBaseClass = DelegatingScript.class.name

def doFirstShell = new GroovyShell(new Binding(), cc)
def doFirstScript = doFirstShell.parse dsl
doFirstScript.setDelegate new AllStuffProcessor()
doFirstScript.run()

// Next run could be sometimes later. This will handle everything else than doFirst:

cc.compilationCustomizers.clear() // no customizer needed for second run
def shell = new GroovyShell(new Binding(), cc)
def script = shell.parse dsl
script.setDelegate new TheRestProcessor()
script.run()

def cc = new CompilerConfiguration()

cc.addCompilationCustomizers new HighlanderCustomizer("doFirst")

cc.scriptBaseClass = DelegatingScript.class.name

def doFirstShell = new GroovyShell(new Binding(), cc)

def doFirstScript = doFirstShell.parse dsl

doFirstScript.setDelegate new AllStuffProcessor()

doFirstScript.run()

// Next run could be sometimes later. This will handle everything else than doFirst:

cc.compilationCustomizers.clear() // no customizer needed for second run

def shell = new GroovyShell(new Binding(), cc)

def script = shell.parse dsl

script.setDelegate new TheRestProcessor()

script.run()

The console output should look like this:

First things first: e.g. setting up environment
this is text that will not be printed out in first line!
doing some stuff now
That's it!

First things first: e.g. setting up environment

this is text that will not be printed out in first line!

doing some stuff now

That's it!

Second variation:

Now the DSL will not be executed in two steps but rather in one single run. We’ll use a CompilationCustomizer again. This time the customizer finds a designated method call and changes the order of execution.

Our Delegate (this time only one is needed):

class AllStuffProcessor {
    def doFirst(Closure c) {
        c()
    }
    def doStuff(Closure c) {
        c()
    }

    def methodMissing(String name, args) {
        //nothing to do
    }
}

class AllStuffProcessor {

def doFirst(Closure c) {

c()

}

def doStuff(Closure c) {

c()

}

def methodMissing(String name, args) {

//nothing to do

}

The ReOrderCustomizer:

class ReOrderCustomizer extends CompilationCustomizer {
    def methodName

    ReOrderCustomizer(def methodName) {
        super(CompilePhase.SEMANTIC_ANALYSIS)
        this.methodName = methodName
    }

    @Override
    void call(SourceUnit sourceUnit, GeneratorContext generatorContext, ClassNode classNode) throws CompilationFailedException {
        def methods = classNode.getMethods()
        methods.each { MethodNode m ->
            m.code.each { Statement st ->
                if (!(st instanceof BlockStatement)) {
                    return
                }
                def doFirstStmt
                st.statements.each { Statement bst ->
                    if (bst instanceof ExpressionStatement) {
                        def ex = bst.expression
                        if (ex instanceof MethodCallExpression) {
                            if (ex.methodAsString.equals(methodName)) {
                                doFirstStmt = bst
                            }
                        }
                    }
                }
                if (doFirstStmt) {
                    st.statements.remove(doFirstStmt)
                    st.statements.add(0, doFirstStmt)
                }
            }
        }
    }
}

class ReOrderCustomizer extends CompilationCustomizer {

def methodName

ReOrderCustomizer(def methodName) {

super(CompilePhase.SEMANTIC_ANALYSIS)

this.methodName = methodName

}

@Override

void call(SourceUnit sourceUnit, GeneratorContext generatorContext, ClassNode classNode) throws CompilationFailedException {

def methods = classNode.getMethods()

methods.each { MethodNode m ->

m.code.each { Statement st ->

if (!(st instanceof BlockStatement)) {

return

}

def doFirstStmt

st.statements.each { Statement bst ->

if (bst instanceof ExpressionStatement) {

def ex = bst.expression

if (ex instanceof MethodCallExpression) {

if (ex.methodAsString.equals(methodName)) {

doFirstStmt = bst

}

if (doFirstStmt) {

st.statements.remove(doFirstStmt)

st.statements.add(0, doFirstStmt)

}

Bring it all together:

def cc = new CompilerConfiguration()
cc.addCompilationCustomizers new ReOrderCustomizer("doFirst")
cc.scriptBaseClass = DelegatingScript.class.name

def shell = new GroovyShell(new Binding(), cc)
def script = shell.parse dsl
script.setDelegate new AllStuffProcessor()
script.run()

def cc = new CompilerConfiguration()

cc.addCompilationCustomizers new ReOrderCustomizer("doFirst")

cc.scriptBaseClass = DelegatingScript.class.name

def shell = new GroovyShell(new Binding(), cc)

def script = shell.parse dsl

script.setDelegate new AllStuffProcessor()

script.run()

Additionally, one should check that the designated method appears only once in the DSL script.

To understand how the AST looks like, just debug the customizer’s call method.

This article is based on a question I postet on Stackoverflow: http://stackoverflow.com/questions/29967886/groovy-dsl-how-can-i-let-two-delegating-classes-handle-different-parts-of-a-dsl

Links:

Great example of using Groovy to implement a DSL: https://groovy.codeplex.com/wikipage?title=Guillaume%20Laforge’s%20%22Mars%20Rover%22%20tutorial%20on%20Groovy%20DSL’s

About CompilationCustomizer: http://www.jroller.com/melix/entry/customizing_groovy_compilation_process

AST transformation workshop: http://melix.github.io/ast-workshop/

Joe’s series of AST articles: http://joesgroovyblog.blogspot.de

Hackserei

It's about software

Widgets

Search

Enhance your Groovy DSL in a plugin-ish way

1. Define a marker interface to find the plugin class (you can do this with annotations as well)

2. A class that enhances your DSL

3. The actual DSL-backing class

4. Writing some DSL-code

That’s it

Groovy DSL: How to split up execution of method calls like gradle does

First variation:

Second variation: