You combine scope functions with Kotlin DSLs by using each scope function for a clear role:

• apply {} to configure DSL objects
• also {} to log, validate, or attach side effects
• run {} to produce a final value
• let {} to transform intermediate values
• with {} to operate on an existing DSL context

The most important DSL feature is the lambda with receiver:

Builder.() -> Unit

That lets your DSL block behave as if it is “inside” the builder object.

---

Basic pattern

A typical DSL builder function looks like this:

fun route(init: RouteBuilder.() -> Unit): Route {
    return RouteBuilder()
        .apply(init)
        .build()
}

Here:

RouteBuilder()
    .apply(init)

means:

Create a builder, run the DSL block against it, and keep the configured builder.

Then:

.build()

turns the builder into the final domain object.

---

Example: small HTTP route DSL

data class Route(
    val path: String,
    val method: String,
    val headers: Map<String, String>,
    val handlerName: String?
)

class RouteBuilder {
    var path: String = "/"
    var method: String = "GET"
    private val headers = mutableMapOf<String, String>()
    private var handlerName: String? = null

    fun header(name: String, value: String) {
        headers[name] = value
    }

    fun handler(name: String) {
        handlerName = name
    }

    fun build(): Route {
        return Route(
            path = path,
            method = method,
            headers = headers.toMap(),
            handlerName = handlerName
        )
    }
}

fun route(init: RouteBuilder.() -> Unit): Route {
    return RouteBuilder()
        .apply(init)
        .also {
            require(it.path.startsWith("/")) {
                "Route path must start with /"
            }
        }
        .build()
}

Usage:

val usersRoute = route {
    path = "/users"
    method = "GET"

    header("Accept", "application/json")
    handler("listUsers")
}

This reads like a small language:

route {
    path = "/users"
    method = "GET"
    header("Accept", "application/json")
    handler("listUsers")
}

---

Where scope functions fit

Use apply to configure builders

This is the most common pairing in Kotlin DSLs.

fun route(init: RouteBuilder.() -> Unit): Route {
    return RouteBuilder()
        .apply(init)
        .build()
}

Because apply:

• uses this as the receiver
• returns the same object

That matches DSL setup perfectly.

---

Use also for validation or logging

Use also when you want to inspect the builder without changing the chain result.

fun route(init: RouteBuilder.() -> Unit): Route {
    return RouteBuilder()
        .apply(init)
        .also {
            require(it.path.isNotBlank()) {
                "Route path cannot be blank"
            }
        }
        .build()
}

also keeps the configured RouteBuilder flowing into build().

---

Use run to compute the final result

You can use run when the final step is more than a direct build() call.

fun route(init: RouteBuilder.() -> Unit): Route {
    return RouteBuilder()
        .apply(init)
        .run {
            require(path.startsWith("/")) {
                "Route path must start with /"
            }

            build()
        }
}

Inside run, the builder is available as this, and the return value is the result of the block.

So this returns a Route, not a RouteBuilder.

---

Nested DSLs

Scope functions become especially useful when your DSL creates nested structures.

data class Page(
    val title: String,
    val sections: List<Section>
)

data class Section(
    val heading: String,
    val paragraphs: List<String>
)

class PageBuilder {
    var title: String = ""
    private val sections = mutableListOf<Section>()

    fun section(init: SectionBuilder.() -> Unit) {
        sections += SectionBuilder()
            .apply(init)
            .build()
    }

    fun build(): Page {
        return Page(
            title = title,
            sections = sections.toList()
        )
    }
}

class SectionBuilder {
    var heading: String = ""
    private val paragraphs = mutableListOf<String>()

    fun paragraph(text: String) {
        paragraphs += text
    }

    fun build(): Section {
        return Section(
            heading = heading,
            paragraphs = paragraphs.toList()
        )
    }
}

fun page(init: PageBuilder.() -> Unit): Page {
    return PageBuilder()
        .apply(init)
        .build()
}

Usage:

val page = page {
    title = "Kotlin DSLs"

    section {
        heading = "Introduction"
        paragraph("Kotlin DSLs are built with lambdas with receivers.")
        paragraph("Scope functions help keep builder code concise.")
    }

    section {
        heading = "Best Practices"
        paragraph("Use apply for configuration.")
        paragraph("Use run when returning a final computed value.")
    }
}

The key part is this:

sections += SectionBuilder()
    .apply(init)
    .build()

That pattern is the backbone of many Kotlin DSLs.

---

More expressive builder helpers

You can combine DSL functions with scope functions to keep code readable.

class FormBuilder {
    private val fields = mutableListOf<Field>()

    fun textField(name: String, init: TextFieldBuilder.() -> Unit = {}) {
        fields += TextFieldBuilder(name)
            .apply(init)
            .build()
    }

    fun build(): Form = Form(fields.toList())
}

data class Form(val fields: List<Field>)

data class Field(
    val name: String,
    val label: String,
    val required: Boolean
)

class TextFieldBuilder(
    private val name: String
) {
    var label: String = name
    var required: Boolean = false

    fun build(): Field {
        return Field(
            name = name,
            label = label,
            required = required
        )
    }
}

fun form(init: FormBuilder.() -> Unit): Form {
    return FormBuilder()
        .apply(init)
        .build()
}

Usage:

val signupForm = form {
    textField("email") {
        label = "Email address"
        required = true
    }

    textField("username") {
        label = "Username"
    }
}

---

Adding validation with also

fun form(init: FormBuilder.() -> Unit): Form {
    return FormBuilder()
        .apply(init)
        .build()
        .also {
            require(it.fields.isNotEmpty()) {
                "Form must contain at least one field"
            }
        }
}

This works, but note the validation happens after build() and validates the final Form.

If you want to validate the builder before building:

fun form(init: FormBuilder.() -> Unit): Form {
    return FormBuilder()
        .apply(init)
        .also {
            // validate builder state here
        }
        .build()
}

---

Transforming DSL output with let

Use let when you want to build something and then convert it.

val fieldNames = form {
    textField("email") {
        required = true
    }

    textField("username")
}.let { builtForm ->
    builtForm.fields.map { it.name }
}

Here, the DSL produces a Form, and let transforms it into a List<String>.

---

Using run for rendering

A common pattern is:

1. Build a DSL object
2. Render it to a final string

val html = page {
    title = "Kotlin"

    section {
        heading = "DSLs"
        paragraph("DSLs can make configuration expressive.")
    }
}.run {
    buildString {
        appendLine("# $title")

        sections.forEach { section ->
            appendLine()
            appendLine("## ${section.heading}")

            section.paragraphs.forEach { paragraph ->
                appendLine(paragraph)
            }
        }
    }
}

Here:

page { ... }

returns a Page.

Then:

.run { ... }

uses that Page to compute a rendered String.

---

Practical guideline

For DSL internals, the most common pattern is:

fun dsl(init: Builder.() -> Unit): Result {
    return Builder()
        .apply(init)
        .also {
            // optional validation, logging, debugging
        }
        .build()
}

For nested DSL elements:

fun child(init: ChildBuilder.() -> Unit) {
    children += ChildBuilder()
        .apply(init)
        .build()
}

For transforming the finished DSL result:

val output = dsl {
    // configuration
}.run {
    // render or compute final value
}

---

Avoid excessive nesting

This is expressive:

val config = server {
    port = 8080

    route {
        path = "/users"
        method = "GET"
    }
}

This is harder to follow:

val config = ServerBuilder().apply {
    RouteBuilder().apply {
        path = "/users"
    }.also {
        println(it)
    }.run {
        build()
    }.also {
        addRoute(it)
    }
}.run {
    build()
}

Prefer creating named DSL functions like route {} instead of exposing too many raw scope-function chains to DSL users.

---

Rule of thumb

Inside DSL builders:
apply = configure a builder
also  = validate, log, debug
run   = compute or build a final result
let   = transform a DSL result
with  = group operations on an existing context

A clean Kotlin DSL usually hides the scope functions inside the implementation, while exposing a readable API to callers:

val app = application {
    name = "Demo"

    server {
        port = 8080

        route {
            method = "GET"
            path = "/health"
        }
    }
}

Internally, that elegant syntax is often powered by simple patterns like:

Builder()
    .apply(init)
    .build()