Thursday, May 19, 2011

Writing Groovy DSL descriptors (DSLD) for Eclipse

Andrew Eisenberg  recently announced new great feature in Groovy Eclipse - the new DSL descriptors which brings you better code completion based on domain specific languages into your Groovy scripts and classes. If you are library developer or just enthusiastic user who wants better Eclipse coding go ahead and create your own DSL descriptor. It's surprisingly easy. In this article I want to share my experience from creating DSLD file for the Gaelyk.

Preparation
Before you start, be sure you have all items on the following check list
You should also explore the sources at the end of the article. DSL Descriptors for Groovy Eclipse is actually only source describing the DSLD and DSLD Examples could give you good overview what is possible to achieve with DSLDs.

When everything in place, you can open your Eclipse, create new Groovy project and add libraries you want the DSLD create for to the classpath (for testing and documentation purposes). Then save the DSLD files descriptor into the src folder and also create your new DSLD file in the src folder too.


Creating the DSLD file
The DSL descriptor is all about finding the right places using the pointcuts and contributing right method or properties to the scope found. If you successfully download the DSLD files descriptor you should have a code completion on place and can start coding.

If you are author of the framework or library it is easy to find out which contribution you want to create. If you aren't you should find the origins of contributions you want to cover in your DSLD not to forget anything. In the case of Gaelyk there are a few places where this happens: variables for views and templates are added using GaelykBindingEnhancerroutes DSL is defined in RoutesBaseScript and finally App Engine enhancements comes from GaelykCategory.

The DSLD official documentation is little bit messy so I've created following tables of all available pointcuts and contributions.

Pointcuts and Contributions


As soon as you know what do you want contribute and how should you do it the rest is all about copy pasting and rewriting (unless your DSL comes from a category so you can use the Category Explorer for scaffolding).

Shortcuts for Groovlets
Groovlets are scripts which resides in war/WEB-INF/groovy so we could pick them using sourceFolderOfCurrentType('war/WEB-INF/groovy') pointcut in combination with enclosingScript().  Everything else is just about declaring the right methods and properties.


App Engine Shortcuts
App Engine shortcuts are all defined inside GaelykCategory class. They apply on particular App Engine types (currentType(type)) inside Groovlets which are scripts residing in war/WEB-INF/groovy as written above. We define the pointcut once and then we can use it for each supported type. Since GaelykCategory  is category the Category Explorer was used for scaffolding.


Image Manipulation Language
The definition of image manipulation language is the most advanced one. We are looking for closure passed into the method call named transform on com.google.appengine.api.images.Image type. Everything else is just the same boring copy pasting again.


Tips, tricks and pitfalls 
Here are some ideas which I learnt when I created the Gaelyk DSDL.
  • The DSLD file won't compile and show in DSLD preferences screen if you import any non-standard class even it is on the project's classpath so you'd better prefer to use fully qualified strings to specify the types e.g. javax.servlet.http.HttpServletRequest.
  • Some of the pointcuts could be tricky, e.g. name of the script when name() pointcut is used is always without the suffix. To get name with the suffix included use fileName() one. You can also get only the suffix by using fileSuffix() pointcut.
  • I cannot find the easy way to debug the script but you can run your STS from console and watch the log. You can insert console prints in your DSLD files to explore the states of the variables.
  • Divide a editor viewport on half vertically and show a 'test' file/script/class bellow your DSLD file. If something goes wrong you get visual feedback immediately.
  • Try to be DRY. Combine pointcuts to the closures and reuse them.
  • Find the source of contributions and try to reuse them. For example you can scaffold the DSLD from Category class using the simple Category Explorer
  • Think twice when arguments are type of Map. Aren't they just named args? So you should use useNamedArgs = true and write all the desired named args in params (see e.g. add method on queues)
  • DSLDs are greate but there are still some features missing. For example I couldn't find how to specify what parameters are expected to be passed into the closure or how to specify type parameters for parametrized types e.g. maps.
 Splitted viewport for better visual feedback


Summary 
DSL descriptors takes coding Groovy in Eclipse one level higher. Where used to be underlined methods and properties you now get full code completion. Even more advanced DSL could be supported, just like Gaelyk's image manipulation language. So don't wait and write DSL descriptor for your favourite library! The Groovy Eclipse users will love you for it!

Sources
Written by Vladimir Oraný (@musketyr)

7 comments:

  1. Not a single word about what this is all about. The link in the beginning explained it for me afterwards - DSL code completion in Groovy Eclipse.

    PS: you have a typo in your summary.

    ReplyDelete
  2. Thank you for valuable feedback, Lars. I've updated the first paragraph and fixed the typos.

    ReplyDelete
  3. It is possible to debug your dslds. It is very complicated, though and requires using a runtime workspace (generally used for Eclipse plugin development). In the next few days, I'll try to get a blog post together on this.

    ReplyDelete
  4. Thanks for notice, Andrew. Using PDE didn't come on my mind but it's definitely the way it could be done. Looking forward on your blog post! Please, tweet me as soon as it's done.

    ReplyDelete
  5. Nice article! Above all the table with contributions and pointcuts should definitely find its way to the official documentation.

    ReplyDelete
  6. Thanks Matthias! I've written to Andrew if it is possible. Meanwhile I've published the table to be browsed from GDocs directly here

    http://link.appsatori.eu/dsld-table

    ReplyDelete
  7. "The DSLD file won't compile and show in DSLD preferences screen if you import any non-standard class even it is on the project's classpath so you'd better prefer to use fully qualified strings to specify the types"

    Don't you know why this happens:
    annotatedBy("groovy.lang.Delegate") - works
    annotatedBy("my.custom.MyAnnotation") - doesn't work

    ReplyDelete