DSL Examples & Idioms

build.gradle.kts is a Gradle build script written in Kotlin instead of Groovy. Because it is real Kotlin code, the IDE gives autocomplete, type checking, and click-through navigation that the Groovy script cannot.

Each block is a lambda that runs 'on' an object (a receiver). Inside the block you can call that object's functions directly, so body() and p() are methods of the current builder.

An infix function lets you call it without a dot or parentheses, like 1 to "a". You mark it with the infix keyword. It must be a member or extension function with exactly one parameter and no default value.

The braces are a function passed as the last argument. Inside, this is a settings object, so you set properties like isLenient directly without naming the object.

The plus sign is the unary-plus operator. You define operator fun String.unaryPlus() on the tag class so it adds the string as a text child. It's used because it reads cleanly and only works inside a tag.

Kotlin maps symbols to specially named functions. + calls plus, a[i] calls get, a[i]=v calls set, x in c calls contains, a..b calls rangeTo. You mark each with the operator keyword so the compiler allows the symbolic call.

Each block is a lambda whose this is a route node. route("/api") makes a child node and runs the inner lambda against it, so get inside attaches to /api, building a tree of routes.

Without it, an inner block can accidentally call functions from an outer tag, building a wrong tree. @DslMarker tells the compiler to hide outer receivers inside nested blocks, so only the closest tag's functions are available implicitly.

You define a task with tasks.register("name") { ... }, configuring it inside the receiver block. register creates the task lazily (only when needed), while create makes it eagerly every build, which is slower.

Type-safe accessors are auto-generated Kotlin functions and properties that let you refer to plugin-created things (configurations, tasks, extensions) by name with full typing. Gradle generates them from the plugins you apply.

Make a Tag class holding children. Each tag function creates a child, adds it to children, runs the block on it, and returns it. Add operator fun String.unaryPlus() to append text. A render() walks children to build the HTML string.

Both use a trailing lambda over a settings object. Json { } configures a JsonBuilder; install(Plugin) { } configures that plugin's own Configuration class. The receiver type tells you which settings are available inside the block.

Each block is a normal Kotlin function call whose last argument is a lambda with a receiver. Inside the lambda, this is set to a typed handler object, so methods like implementation(...) are really calls on that receiver.

actual shouldBe expected calls actual.shouldBe(expected). The generic T is inferred from both sides, so types must line up. You should warn that infix doesn't chain cleanly and equality uses equals, which can surprise with platform types or floating-point.

unaryPlus lets +x mean 'add x', so +"hello" inside a builder appends text. invoke lets you call an object like a function — thing(args) runs thing.invoke(args). Both remove method-name noise so DSL blocks read cleanly.

Use a mutable builder with var fields and nested builder functions. The top-level function creates the builder, runs the user's lambda, validates, then copies the values into an immutable data class it returns.

In nested blocks, both the inner and outer this receivers are in scope, so you can call an outer builder by accident. @DslMarker on the receiver types blocks the implicit outer receiver, forcing you to be explicit.

Kotlin DSL gives type safety, autocomplete, and safer refactoring; Groovy is more concise and dynamic but errors show up only at build time. For Kotlin teams the Kotlin DSL usually wins, despite slightly slower first builds and a migration cost.

A Kotlin DSL gives type safety, refactoring, and IDE help but couples markup to code and adds a learning curve. Good DSLs use @DslMarker for scope safety, escape output, keep blocks inline, and return useful nodes.

Property delegation (val x by delegate) uses getValue and setValue operator functions on the delegate, with an optional provideDelegate to customize creation. The get/set operators are different — they back the [] indexing syntax, not the by keyword.