Writing DSLs in Kotlin (part 1)

Kotlin brings a lot of language features to developers that focus on making code more readable and less verbose. One of the cool things we can do with these features is design an expressive domain-specific language or DSL

What are domain-specific languages?

First of all, what are DSLs exactly and why should we use them? Let’s have a look at Wikipedia’s definition on DSLs:

A domain-specific language (DSL) is a computer language specialized to a particular application domain. This is in contrast to a general-purpose language (GPL), which is broadly applicable across domains.

Basically, a DSL is a language that focuses on just one particular part of an application. A general-purpose language, such as Kotlin or Java, on the other hand, can be used in multiple parts of one application. There are several domain-specific languages that we’re already familiar with, like SQL for example. If we have a look at a statement in SQL, we notice that it’s almost like a sentence in English, making it expressive and quite readable:

SELECT Person.name, Person.age FROM Person ORDER BY Person.age DESC

There is no specific criteria that distinguishes a DSL from a normal API but most of the time we see one difference: The use of a certain structure or grammar. This makes the code more human-readable, which is easier to understand, not only for developers but also for less-technical people.

DSLs with Kotlin

Now, how can we create DSLs with some of Kotlin’s language features and what advantages does it bring us?

When we’re creating a DSL in another general-purpose programming language such as Kotlin, we’re actually talking about internal DSLs. We’re not creating an independent syntax but we’re setting up a specific way to use an existing language. This gives us the advantage using code we already know and allows us to add other Kotlin statements such as for-loops to our DSL.

Besides that, Kotlin provides several ways to create a cleaner syntax and avoid using too many unnecessary symbols. In this first part, we’ll focus on three specific features:

• Use of lambdas outside of method parentheses
• Lambdas with receivers
• Extension functions

The use of these will become more clear in a minute, when we continue with the examples.

For making everything understandable, I’ll be using a simple model to create our DSL in this part. We shouldn’t be creating DSLs whenever we create a class. This would be an unnecessary overkill. A good place to use DSLs could be a configuration class or a library interface where the user doesn’t have to be aware of the models.

Let’s write our first DSL

In this part we will create a simple DSL that’s able to instantiate an object of our Person class. Note that this is just as an example. Here’s an example of what we’re gonna get at the end of this tutorial.

As you can see, the code above is very self-explanatory and easy to understand. Even people with no developer experience would be able to read this and even make adjustments. In order to understand how we can get there, we will take several steps. Here’s the model we’re gonna start with.

It’s obvious that this is not the cleanest model we can write. Eventually we want to have immutable vals. We will get to that in the upcoming parts of this series.

First thing we will do is create a new file. We will keep the DSL separated from the actual classes in our model. Let’s start by creating some sort of constructor function for our Person class. Looking at the result we want to have, we see that the properties of Person are defined within a code block. These curly brackets are actually defining a lambda. This is where we’re using the first of the three Kotlin language features mentioned above: Use of lambdas outside of method parentheses.

If the last parameter of a function is a lambda, we can put it outside of the parentheses. And when you only have a lambda as parameter, you can simply remove the parentheses completely. This means that person {…} is actually the same as person({…}). This results in less syntactic noise in our DSL. Now, we will write a first version of our person function.

So here we have a function that creates a Person object. It requires a lambda that has the object we create in line 2. When we execute this lambda on line 3, we expect the object to get the properties it needs before we return the object on line 4. This is how we can use this function:

Since this lambda receives only one argument, we’re able to call the person object with it. This looks quite nice, but we’re not there yet. The it isn’t really something we want to see in our DSL. Especially when we’re gonna add extra layers of objects in there. This brings us to our next mentioned Kotlin feature: Lambdas with receivers.

In the definition of the person function, we can add a receiver to the lambda. This way we can only access functions of that receiver in the lambda. Since the functions in the lambda are within the scope of the receiver, we can simply execute the lambda on the receiver instead of providing it as an argument.

This can actually be rewritten in a simple one-liner by using the apply function, provided by Kotlin.

Now we are able to remove the it out of our DSL.

Looks great, doesn’t it? :) We’re almost there. We’re just missing one more thing, the Address class. In our desired result, it looks a lot like the person function we’ve just created. The only difference here is that we have to assign it to the address property of the Person object. To do this, we’ll use the last of our three mentioned Kotlin language features: Extension functions.

Extension functions give us the ability to add functions to classes without accessing the source code of the class itself. This is perfect for creating an Address object and directly assign it to the address property of Person. This is the final version of our Dsl file (for now).

We add an address function to Person that accepts a lambda with Address as receiver, just like we did with the person constructor function. It then sets the created Address object to the property of Person. Now we have created a domain-specific language for creating our model.

This is the first part of a larger series on writing DSLs in Kotlin. In the second part, we’ll talk about adding collections, using the cleaner Builder pattern and the @DslMarker annotation. There is also a real life example with GsonBuilder included. Part two can be found here.

Hopefully this article was helpful for you and you’re interested in learning more about Kotlin DSLs. Please provide some claps if you liked it :)