Building blocks of type-safe builders in Kotlin

Introduction

Type-safe builders help you create complex objects step-by-step with clear rules. They make your code easier to read and safer by catching mistakes early.

When you want to create complex objects with many parts in a clear way.

When you want to avoid mistakes by making sure only valid steps are allowed.

When you want your code to look like a small language for building things.

When you want to write code that is easy to understand and maintain.

When you want to group related settings or elements together safely.

Syntax

Kotlin

class Builder {
    fun part(block: PartBuilder.() -> Unit) { /*...*/ }
    fun build(): Result { /*...*/ }
}

class PartBuilder {
    fun setProperty(value: Any) { /*...*/ }
}

fun buildObject(block: Builder.() -> Unit): Result {
    val builder = Builder()
    builder.block()
    return builder.build()
}

The builder class defines how to add parts and build the final object.

The block parameter uses a lambda with receiver to allow clean syntax inside the builder.

Examples

This example builds a meal by adding items and then joining them into a string.

Kotlin

class MealBuilder {
    private val items = mutableListOf<String>()
    fun addItem(item: String) { items.add(item) }
    fun build() = items.joinToString(", ")
}

fun meal(block: MealBuilder.() -> Unit): String {
    val builder = MealBuilder()
    builder.block()
    return builder.build()
}

Here we use the meal builder to create a meal with three items.

Kotlin

val myMeal = meal {
    addItem("Burger")
    addItem("Fries")
    addItem("Soda")
}
println(myMeal)

Sample Program

This program builds a simple HTML page using type-safe builders for <html>, <head>, and <body> sections. It shows how to organize code clearly and safely.

Kotlin

class HtmlBuilder {
    private val children = mutableListOf<String>()

    fun head(block: HeadBuilder.() -> Unit) {
        val headBuilder = HeadBuilder()
        headBuilder.block()
        children.add("<head>${headBuilder.build()}</head>")
    }

    fun body(block: BodyBuilder.() -> Unit) {
        val bodyBuilder = BodyBuilder()
        bodyBuilder.block()
        children.add("<body>${bodyBuilder.build()}</body>")
    }

    fun build() = "<html>" + children.joinToString("") + "</html>"
}

class HeadBuilder {
    private val elements = mutableListOf<String>()
    fun title(text: String) { elements.add("<title>$text</title>") }
    fun build() = elements.joinToString("")
}

class BodyBuilder {
    private val elements = mutableListOf<String>()
    fun p(text: String) { elements.add("<p>$text</p>") }
    fun build() = elements.joinToString("")
}

fun html(block: HtmlBuilder.() -> Unit): String {
    val builder = HtmlBuilder()
    builder.block()
    return builder.build()
}

fun main() {
    val page = html {
        head {
            title("Welcome")
        }
        body {
            p("Hello, this is a type-safe builder example.")
        }
    }
    println(page)
}

Important Notes

Type-safe builders use lambdas with receivers to create a clean and readable syntax.

They help prevent errors by limiting what can be called inside each builder block.

You can nest builders to represent complex structures like HTML or UI layouts.

Summary

Type-safe builders help build complex objects step-by-step with clear rules.

They use special functions and lambdas to make code easy to read and safe.

You can create nested builders to represent structured data like HTML.

Practice

1. What is the main purpose of type-safe builders in Kotlin?

easy

A. To create complex objects step-by-step with safety and clarity

B. To write faster loops for collections

C. To handle exceptions automatically

D. To convert data types implicitly

Solution

1. Step 1: Understand the concept of type-safe builders

   Type-safe builders allow building complex objects in a structured and safe way using Kotlin's DSL features.

2. Step 2: Identify the main purpose

   The main goal is to create objects step-by-step with clear rules, avoiding errors and improving readability.

3. Final Answer:

   To create complex objects step-by-step with safety and clarity -> Option A

4. Quick Check:

   Type-safe builders = safe, clear object creation [OK]

Hint: Type-safe builders help build objects safely step-by-step [OK]

Common Mistakes:

• Confusing builders with loops or exception handling
• Thinking they convert data types automatically

2. Which Kotlin syntax correctly defines a type-safe builder function named html that takes a lambda with receiver?

easy

A. fun html(block: (Html) -> Unit) { /*...*/ }

B. fun html(block: () -> Html) { /*...*/ }

C. fun html(block: Html.() -> Unit) { /*...*/ }

D. fun html(block: () -> Unit) { /*...*/ }

Solution

1. Step 1: Identify lambda with receiver syntax

   Type-safe builders use lambdas with receiver, which have the form ReceiverType.() -> ReturnType.

2. Step 2: Match the correct function signature

   The function should accept a lambda with receiver Html and return Unit, so Html.() -> Unit is correct.

3. Final Answer:

   fun html(block: Html.() -> Unit) { /*...*/ } -> Option C

4. Quick Check:

   Lambda with receiver = Html.() -> Unit [OK]

Hint: Look for lambda with receiver syntax ReceiverType.() -> Unit [OK]

Common Mistakes:

• Using regular lambda (Html) -> Unit instead of lambda with receiver
• Omitting the receiver type in the lambda
• Returning Html instead of Unit

3. Given the following Kotlin code, what is the output?

class Html {
    val children = mutableListOf<String>()
    fun body(block: Body.() -> Unit) {
        val body = Body()
        body.block()
        children.addAll(body.contents)
    }
    override fun toString() = children.joinToString(", ")
}

class Body {
    val contents = mutableListOf<String>()
    fun p(text: String) {
        contents.add("
$text
")
    }
}

fun html(block: Html.() -> Unit): Html {
    val html = Html()
    html.block()
    return html
}

fun main() {
    val result = html {
        body {
            p("Hello")
            p("World")
        }
    }
    println(result)
}

medium

A. Hello, World

B. <p>Hello</p>, <p>World</p>

C. <body><p>Hello</p><p>World</p></body>

D. Compilation error

Solution

1. Step 1: Understand the builder structure

   The html function creates an Html object, calls body which creates a Body object, then calls p twice adding <p>Hello</p> and <p>World</p> to Body's contents.

2. Step 2: Check how children are collected and printed

   The Html object's children list gets Body's contents added, then toString() joins them with ", ". So output is "<p>Hello</p>, <p>World</p>".

3. Final Answer:

   <p>Hello</p>, <p>World</p> -> Option B

4. Quick Check:

   Children list joined = <p>Hello</p>, <p>World</p> [OK]

Hint: Look for toString join of children list for output [OK]

Common Mistakes:

• Assuming HTML tags are printed as is without escaping
• Expecting full HTML tags like <body> in output
• Thinking code causes compilation error

4. What is the error in this Kotlin builder code snippet?

class Html {
    fun body(block: Body.() -> Unit) {
        val body = Body()
        block()
    }
}

class Body {
    fun p(text: String) { /*...*/ }
}

fun main() {
    val html = Html()
    html.body {
        p("Hello")
    }
}

medium

A. The lambda is called without receiver, so 'p' is unresolved

B. Body class is missing a constructor

C. Html class should inherit from Body

D. The 'body' function should return a value

Solution

1. Step 1: Check how the lambda is called inside body()

   The lambda block is called as block() without receiver, so inside the lambda 'p' is not recognized.

2. Step 2: Identify correct lambda invocation

   It should be called as body.block() to set the receiver to the Body instance, allowing 'p' to be resolved.

3. Final Answer:

   The lambda is called without receiver, so 'p' is unresolved -> Option A

4. Quick Check:

   Lambda call without receiver = unresolved 'p' [OK]

Hint: Call lambda with receiver: use receiver.lambda() syntax [OK]

Common Mistakes:

• Calling lambda without receiver inside builder
• Assuming inheritance fixes builder scope
• Expecting return value from builder function

5. How can you extend a type-safe builder to support nested elements, for example adding a div inside body, while keeping type safety?

hard

A. Use a global div function outside the builder classes

B. Add a div property of type String to Body

C. Make Body inherit from Div

D. Define a div function inside Body that takes a lambda with receiver of a new Div class

Solution

1. Step 1: Understand nested builder pattern

   To support nested elements, define functions inside builder classes that accept lambdas with receivers of nested element classes.

2. Step 2: Apply to 'div' inside 'body'

   Inside Body, define a div function taking Div.() -> Unit lambda, creating a Div instance and applying the lambda to it.

3. Final Answer:

   Define a div function inside Body that takes a lambda with receiver of a new Div class -> Option D

4. Quick Check:

   Nested builders = functions with lambdas with receiver [OK]

Hint: Nested builders use functions with lambdas with receiver inside classes [OK]

Common Mistakes:

• Using simple properties instead of nested builder functions
• Trying inheritance instead of composition
• Defining builder functions outside the class scope