Skip to main content

Kotlin DSL Basics

Introduction​

Domain-Specific Languages (DSLs) are specialized programming languages designed to solve problems in a particular domain. Unlike general-purpose languages like Kotlin itself, DSLs focus on expressing solutions within a specific context, making them more readable and focused.

Kotlin has excellent support for creating internal DSLs - specialized syntaxes that exist within Kotlin code but appear to be custom languages. This is possible thanks to Kotlin's flexible syntax, extension functions, lambdas with receivers, and other powerful features.

In this tutorial, you'll learn what DSLs are, why they're useful, and how to create your own basic DSLs in Kotlin.

What is a DSL?​

A DSL (Domain-Specific Language) is a programming language specialized to a particular application domain. Examples of DSLs include:

  • SQL for database queries
  • HTML/CSS for web page styling
  • Gradle build scripts
  • Kotlin's own buildString function

When we talk about Kotlin DSLs, we're typically referring to "internal DSLs" that are embedded within Kotlin code but provide syntax that appears custom-tailored for a specific purpose.

Why Use DSLs?​

DSLs offer several advantages:

  1. Readability: They express domain-specific logic in a clear, concise way
  2. Safety: Type checking and IDE support catch errors early
  3. Expressiveness: They allow you to express complex operations with minimal syntax
  4. Consistency: They establish patterns for handling specific types of operations

Building Blocks of Kotlin DSLs​

Let's explore the key features that make Kotlin excellent for building DSLs:

1. Extension Functions​

Extension functions let you add methods to existing classes without modifying their source code:

kotlin
fun String.emphasize() = "*** $this ***"

fun main() {
    val message = "Important"
    println(message.emphasize()) // Output: *** Important ***
}

2. Higher-Order Functions and Lambdas​

Kotlin allows functions to accept other functions as parameters:

kotlin
fun performOperation(value: Int, operation: (Int) -> Int): Int {
    return operation(value)
}

fun main() {
    val result = performOperation(5) { it * 2 }
    println(result) // Output: 10
}

3. Lambda with Receiver​

This is where Kotlin DSLs really shine. A lambda with receiver allows you to call methods on an object without explicitly referring to it:

kotlin
fun buildString(action: StringBuilder.() -> Unit): String {
    val sb = StringBuilder()
    sb.action()
    return sb.toString()
}

fun main() {
    val result = buildString {
        append("Hello, ")
        append("DSL!")
    }
    println(result) // Output: Hello, DSL!
}

In the example above, append() is called on the StringBuilder instance without explicitly naming it.

Creating a Simple DSL​

Let's create a simple DSL for building HTML:

kotlin
class HTML {
    private val content = StringBuilder()
    
    fun head(action: Head.() -> Unit) {
        content.append("<head>")
        val head = Head()
        head.action()
        content.append(head.content)
        content.append("</head>")
    }
    
    fun body(action: Body.() -> Unit) {
        content.append("<body>")
        val body = Body()
        body.action()
        content.append(body.content)
        content.append("</body>")
    }
    
    override fun toString() = "<html>${content}</html>"
}

class Head {
    val content = StringBuilder()
    
    fun title(text: String) {
        content.append("<title>$text</title>")
    }
}

class Body {
    val content = StringBuilder()
    
    fun h1(text: String) {
        content.append("<h1>$text</h1>")
    }
    
    fun p(text: String) {
        content.append("<p>$text</p>")
    }
}

fun html(action: HTML.() -> Unit): HTML {
    val html = HTML()
    html.action()
    return html
}

fun main() {
    val page = html {
        head {
            title("My First DSL")
        }
        body {
            h1("Welcome to Kotlin DSL")
            p("This is a paragraph created using our custom DSL")
        }
    }
    println(page)
    // Output:
    // <html><head><title>My First DSL</title></head><body><h1>Welcome to Kotlin DSL</h1><p>This is a paragraph created using our custom DSL</p></body></html>
}

This HTML DSL allows us to create HTML in a structured, type-safe way. The nesting of functions reflects the nesting of HTML elements.

Real-World Example: Configuration DSL​

Let's look at a more practical example: a DSL for configuring an application:

kotlin
class Server(val port: Int, val environment: String, val logging: Boolean)

class ServerBuilder {
    var port: Int = 8080
    var environment: String = "development"
    var logging: Boolean = true
    
    fun build() = Server(port, environment, logging)
}

fun server(setup: ServerBuilder.() -> Unit): Server {
    val builder = ServerBuilder()
    builder.setup()
    return builder.build()
}

fun main() {
    val myServer = server {
        port = 9000
        environment = "production"
        logging = false
    }
    
    println("Server configured on port ${myServer.port}")
    println("Environment: ${myServer.environment}")
    println("Logging enabled: ${myServer.logging}")
    
    // Output:
    // Server configured on port 9000
    // Environment: production
    // Logging enabled: false
}

This pattern is common in many Kotlin libraries, including Gradle's Kotlin DSL, Ktor, and more.

Advanced DSL Features​

Once you grasp the basics, you can enhance your DSLs with:

1. Context Control with @DslMarker​

The @DslMarker annotation helps avoid accidentally calling methods from outer scopes:

kotlin
@DslMarker
annotation class HtmlDsl

@HtmlDsl
class TableDsl {
    // Table building methods
}

@HtmlDsl
class TdDsl {
    // TD building methods
}

2. Operator Overloading​

Kotlin allows you to define custom behaviors for standard operators:

kotlin
data class Vector(val x: Int, val y: Int) {
    operator fun plus(other: Vector) = Vector(x + other.x, y + other.y)
}

fun main() {
    val v1 = Vector(1, 2)
    val v2 = Vector(3, 4)
    val v3 = v1 + v2 // Using the overloaded + operator
    println(v3) // Output: Vector(x=4, y=6)
}

3. Property Delegates​

Property delegates provide a way to intercept get/set operations:

kotlin
class Configuration {
    var debug by observable(false) { _, old, new ->
        println("Debug changed from $old to $new")
    }
}

Summary​

Kotlin DSLs provide a powerful way to create expressive, readable code that's tailored to specific problems. The key components for building DSLs in Kotlin are:

  1. Extension functions
  2. Higher-order functions and lambdas
  3. Lambdas with receivers
  4. Type-safe builders

By mastering these concepts, you can create DSLs that make your code more concise, easier to understand, and less prone to errors.

Exercises​

  1. Create a DSL for building a simple to-do list
  2. Extend the HTML DSL to support tables, lists, and links
  3. Create a DSL for defining data validation rules
  4. Design a DSL for configuring a mock HTTP server for testing

Additional Resources​


If you spot any mistakes on this website, please let me know at [email protected]. I’d greatly appreciate your feedback! :)