GroovyDSL scripting framework
GroovyDSL is a framework with a domain-specific language designed to define the behaviour of end-user DSLs as script files which are executed by the IDE on the fly, bringing new reference resolution and code completion logic into the scope of a project. GroovyDSL relies on the Program Structure Interface (PSI), a set of internal classes and interfaces of IntelliJ IDEA, which allow all programming languages to be described in a uniform way. Due to Groovy's meta-programming capabilities, the developer of DSL descriptions in GroovyDSL need not be aware of how PSI works. All interoperation with PSI is covered by calls to methods and properties of GroovyDSL scripts.
Stable builds of IntelliJ IDEA with embedded JetGroovy plugin and GroovyDSL support are available at http://www.jetbrains.net/confluence/display/IDEADEV/Maia+EAP.
Writing a simple GroovyDSL script
Let's write a simple GroovyDSL script to add a piece of new behavior to an existing class. If you create a new Java project in IntelliJ IDEA, make sure, that you attach Groovy facet to it. For existing projects Groovy facet may be adjusted via Project Structure settings. Also don't forget to attach Java SDK to your project.
Suppose, we have the following script "DayCounter.groovy", which adds `daysFromNow' property to the Integer class.
As one could notice, an invocation of the appropriate property is highlighted as an unresolved call. To fix it, we write a simple GrooyDSL script. To create a GroovyDSL script, invoke the `new Groovy Script' action in project view and choose GroovyDSL script type from the drop-down.
In the body of GroovyDSL script write the following code
First two lines describe a context, to which we are going to add a new behaviour. It may be read as "augment class java.lang.Integer" in script with the name "DayCounter.groovy".
Next two lines describe a contributor, which is in charge for the new behaviour. It takes a context `ctx' and in a passed closure adds new property with name "daysFromNow" and type "Calendar" to the target class, namely "java.lang.Integer" which is known from the passed context.
After finishing editing a GroovyDSL script one can notice a yellow band on top of an editor screen, informing, that modified GroovyDSL script should be reloaded. After clicking on it an actual script will be processed and activated to make the IDE aware about new behaviour.
Switching back to the DayCounter script we'll see that `daysFromNow' is highlighted now as a class property, and, moreover, it's available for completion. This works pretty like Dynamic Properties feature, but GroovyDSL scripting gives much larger freedom in defining context. For example, by script we just have written, `daysFromNow' property will be available only on top of DayCounter scripts, not in others, whereas being defined with dynamic properties it would be available in all Groovy files in project. Of course, there are various scopes to define contexts of different granularity.
More examples of GroovyDSL scripts.
GroovyDSL internal language relies on the IntelliJ IDEA open API, namely the set of Program Structure Interfaces (PSI). All GroovyDSL functions and properties are nothing but wrappers around existing PSI interfaces. To get an adequate code assistance with code completion it's strongly recommended to attach openapi.jar from $IDEA_DIR/lib folder as a library to an actual project. GroovyDSL scripts will be working fine even without it being attached, but in this cases some references will be marked as unresolved. In light of said above, all standard PSI methods are available in GroovyDSL as well as synthetic ones, described below.
Next example shows, how to describe generic methods in terms of GroovyDSL for class Position.
The GroovyDSL script below describes injection of dynamic methods `findAll*Positions' for all fields of Position class.
It's important to remark, that classType is a predefined property of a closure, passes as a parameter to contributor() method and it's available only inside of it, whereas fields is an invocation of the getFields() method of a PsiClass class. Here we are also using Groovy's higher-order functions to iterate by method `each' through the collection of fetched fields.
One can use GroovyDSL to describe delegation-based semantics of Groovy programs. The following code gives a definition of the class Runner, whose method run() takes first parameters, namely, any object obj and a closure cl. It redefines a default delegate of a given closure and assigns obj to its delegate property. When passing a closure to the method run() as a parameter, according to Groovy's rules of reference resolution it is allowed to invoke unqualified method of its first parameter inside of a body of closure
This delegation-dependent logic may be captured by the following GroovyDSL code:
Several predefined GroovyDSL methods are used in this code fragment. enclosingCall(methodName) call returns a mathod invocation expression of a given context with a name, matching methodName or null otherwise. delegatesTo method takes an expression and adds all member of its type to the augmented class reference. In the given example this is enclosing clousre, since the context's scope is defined as closureScope()