initTag(tag: T, init: T.() -> Unit): T {
tag.init()
children.add(tag)
return tag
}
override fun render(builder: StringBuilder, indent: String) {
builder.append("$indent<$name${renderAttributes()}>\n")
for (c in children) {
c.render(builder, indent + " ")
}
builder.append("$indent\n")
}
private fun renderAttributes(): String {
val builder = StringBuilder()
for ((attr, value) in attributes) {
builder.append(" $attr=\"$value\"")
}
return builder.toString()
}
override fun toString(): String {
val builder = StringBuilder()
render(builder, "")
return builder.toString()
}
}
abstract class TagWithText(name: String) : Tag(name) {
operator fun String.unaryPlus() {
children.add(TextElement(this))
}
}
class HTML() : TagWithText("html") {
fun head(init: Head.() -> Unit) = initTag(Head(), init)
fun body(init: Body.() -> Unit) = initTag(Body(), init)
}
class Head() : TagWithText("head") {
fun title(init: Title.() -> Unit) = initTag(Title(), init)
}
class Title() : TagWithText("title")
abstract class BodyTag(name: String) : TagWithText(name) {
fun b(init: B.() -> Unit) = initTag(B(), init)
fun p(init: P.() -> Unit) = initTag(P(), init)
fun h1(init: H1.() -> Unit) = initTag(H1(), init)
fun ul(init: UL.() -> Unit) = initTag(UL(), init)
fun a(href: String, init: A.() -> Unit) {
val a = initTag(A(), init)
a.href = href
}
}
class Body() : BodyTag("body")
class UL() : BodyTag("ul") {
fun li(init: LI.() -> Unit) = initTag(LI(), init)
}
class B() : BodyTag("b")
class LI() : BodyTag("li")
class P() : BodyTag("p")
class H1() : BodyTag("h1")
class A : BodyTag("a") {
var href: String
get() = attributes["href"]!!
set(value) {
attributes["href"] = value
}
}
fun html(init: HTML.() -> Unit): HTML {
val html = HTML()
html.init()
return html
}
```
```
HTML encoding with Kotlin
HTML encoding with Kotlin
this format can be used as an
alternative markup to HTML
Kotlin
This is some
mixed
text. For more see the
Kotlin
project
some text
-
1*2 = 2
-
2*2 = 4
-
3*2 = 6
-
4*2 = 8
-
5*2 = 10
```
## How it works
Assume that you need to implement a type-safe builder in Kotlin.
First of all, define the model you want to build. In this case, you need to model HTML tags.
It is easily done with a bunch of classes.
For example, `HTML` is a class that describes the `` tag defining children like `` and ``.
(See its declaration [below](#full-definition-of-the-com-example-html-package).)
Now, let's recall why you can say something like this in the code:
```KOTLIN
html {
// ...
}
```
`html` is actually a function call that takes a [lambda expression](lambdas.html) as an argument.
This function is defined as follows:
```KOTLIN
fun html(init: HTML.() -> Unit): HTML {
val html = HTML()
html.init()
return html
}
```
This function takes one parameter named `init`, which is itself a function.
The type of the function is `HTML.() -> Unit`, which is a function type with receiver.
This means that you need to pass an instance of type `HTML` (a receiver) to the function,
and you can call members of that instance inside the function.
The receiver can be accessed through the `this` keyword:
```KOTLIN
html {
this.head { ... }
this.body { ... }
}
```
(`head` and `body` are member functions of `HTML`.)
Now, `this` can be omitted, as usual, and you get something that looks very much like a builder already:
```KOTLIN
html {
head { ... }
body { ... }
}
```
So, what does this call do? Let's look at the body of `html` function as defined above.
It creates a new instance of `HTML`, then it initializes it by calling the function that is passed as an argument
(in this example, this boils down to calling `head` and `body` on the `HTML` instance), and then it returns this instance.
This is exactly what a builder should do.
The `head` and `body` functions in the `HTML` class are defined similarly to `html`.
The only difference is that they add the built instances to the `children` collection of the enclosing `HTML` instance:
```KOTLIN
fun head(init: Head.() -> Unit): Head {
val head = Head()
head.init()
children.add(head)
return head
}
fun body(init: Body.() -> Unit): Body {
val body = Body()
body.init()
children.add(body)
return body
}
```
Actually, these two functions do just the same thing, so you can have a generic version, `initTag`:
```KOTLIN
protected fun initTag(tag: T, init: T.() -> Unit): T {
tag.init()
children.add(tag)
return tag
}
```
So, now your functions are very simple:
```KOTLIN
fun head(init: Head.() -> Unit) = initTag(Head(), init)
fun body(init: Body.() -> Unit) = initTag(Body(), init)
```
And you can use them to build `` and `` tags.
One other thing to be discussed here is how you add text to tag bodies. In the example above, you say something like:
```KOTLIN
html {
head {
title {+"XML encoding with Kotlin"}
}
// ...
}
```
So basically, you just put a string inside a tag body, but there is this little `+` in front of it,
so it is a function call that invokes a prefix `unaryPlus()` operation.
That operation is actually defined by an extension function `unaryPlus()` that is a member of the `TagWithText` abstract
class (a parent of `Title`):
```KOTLIN
operator fun String.unaryPlus() {
children.add(TextElement(this))
}
```
So, what the prefix `+` does here is wrapping a string into an instance of `TextElement` and adding it to the `children` collection,
so that it becomes a proper part of the tag tree.
All this is defined in a package `com.example.html` that is imported at the top of the builder example above.
In the last section, you can read through the full definition of this package.
## Scope control: @DslMarker
When using DSLs, one might have come across the problem that too many functions can be called in the context.
You can call methods of every available [implicit receiver](lambdas.html#function-literals-with-receiver) inside a lambda and therefore get an inconsistent result,
like the tag `head` inside another `head`:
```KOTLIN
html {
head {
head {} // should be forbidden
}
// ...
}
```
In this example, only members of the nearest implicit receiver `this@head` must be available; `head()` is a member of the
outer receiver `this@html`, so it must be illegal to call it.
To address this problem, there is a special mechanism to control receiver scope.
To make the compiler start controlling scopes, you only have to annotate the types of all receivers used in the DSL with
the same marker annotation.
For instance, for HTML Builders you declare an annotation `@HtmlTagMarker`:
```KOTLIN
@DslMarker
@Target(AnnotationTarget.CLASS)
annotation class HtmlTagMarker
```
An annotation class is called a DSL marker if it is annotated with the `@DslMarker` annotation.
The `@Target` annotation restricts where `@HtmlTagMarker` can be applied.
DSL markers only affect scope control when applied to:
* Type declarations (`CLASS`): classes or interfaces used as DSL receivers.
* Type usages (`TYPE`): receiver types in function type signatures.
* Type aliases (`TYPEALIAS`): type aliases that expand to DSL receiver types.
Applying a DSL marker to other targets (such as functions or properties) has no effect on scope control.
Note:
For more details on how DSL marker works, see the corresponding [KEEP document](https://github.com/Kotlin/KEEP/blob/main/notes/0005-dsl-marker.md).
In our DSL, all the tag classes extend the same superclass `Tag`.
It's enough to annotate only the superclass with `@HtmlTagMarker` and after that the Kotlin compiler will treat all the
inherited classes as annotated:
```KOTLIN
@HtmlTagMarker
abstract class Tag(val name: String) { ... }
```
You don't have to annotate the `HTML` or `Head` classes with `@HtmlTagMarker` because their superclass is already annotated:
```KOTLIN
class HTML() : Tag("html") { ... }
class Head() : Tag("head") { ... }
```
After you've added this annotation, the Kotlin compiler knows which implicit receivers are part of the same DSL and allows to call members of the nearest receivers only:
```KOTLIN
html {
head {
head { } // error: a member of outer receiver
}
// ...
}
```
Note that it's still possible to call the members of the outer receiver, but to do that you have to specify this receiver explicitly:
```KOTLIN
html {
head {
this@html.head { } // possible
}
// ...
}
```
You can also apply the `@DslMarker` annotation directly to [function types](lambdas.html#function-types).
This requires including `AnnotationTarget.TYPE` in the annotation targets:
```KOTLIN
@DslMarker
@Target(AnnotationTarget.CLASS, AnnotationTarget.TYPE)
annotation class HtmlTagMarker
```
As a result, the `@DslMarker` annotation can be applied to function types, most commonly to lambdas with receivers. For example:
```KOTLIN
fun html(init: @HtmlTagMarker HTML.() -> Unit): HTML { ... }
fun HTML.head(init: @HtmlTagMarker Head.() -> Unit): Head { ... }
fun Head.title(init: @HtmlTagMarker Title.() -> Unit): Title { ... }
```
When you call these functions, the `@DslMarker` annotation restricts access to outer receivers in the body of a lambda marked with it unless you specify them explicitly:
```KOTLIN
html {
head {
title {
// Access to title, head or other functions of outer receivers is restricted here.
}
}
}
```
Only the nearest receiver's members and extensions are accessible within a lambda, preventing unintended interactions between nested scopes.
When both a member of an implicit receiver and a declaration from a [context parameter](context-parameters.html) are in a scope with the same name,
the compiler reports a warning because the implicit receiver is shadowed by the context parameter.
To resolve this, use a `this` qualifier to explicitly call the receiver, or use `contextOf()` to call the context declaration:
```KOTLIN
interface HtmlTag {
fun setAttribute(name: String, value: String)
}
// Declares a top-level function with the same name,
// which is available through a context parameter
context(tag: HtmlTag)
fun setAttribute(name: String, value: String) { tag.setAttribute(name, value) }
fun test(head: HtmlTag, extraInfo: HtmlTag) {
with(head) {
// Introduces a context value of the same type in an inner scope
context(extraInfo) {
// Reports a warning:
// Uses an implicit receiver shadowed by a context parameter
setAttribute("user", "1234")
// Calls the receiver's member explicitly
this.setAttribute("user", "1234")
// Calls the context declaration explicitly
contextOf().setAttribute("user", "1234")
}
}
}
```
### Full definition of the com.example.html package
This is how the package `com.example.html` is defined (only the elements used in the example above).
It builds an HTML tree. It makes heavy use of [extension functions](extensions.html) and
[lambdas with receiver](lambdas.html#function-literals-with-receiver).
```KOTLIN
package com.example.html
interface Element {
fun render(builder: StringBuilder, indent: String)
}
class TextElement(val text: String) : Element {
override fun render(builder: StringBuilder, indent: String) {
builder.append("$indent$text\n")
}
}
@DslMarker
@Target(AnnotationTarget.CLASS, AnnotationTarget.TYPE)
annotation class HtmlTagMarker
@HtmlTagMarker
abstract class Tag(val name: String) : Element {
val children = arrayListOf()
val attributes = hashMapOf()
protected fun initTag(tag: T, init: T.() -> Unit): T {
tag.init()
children.add(tag)
return tag
}
override fun render(builder: StringBuilder, indent: String) {
builder.append("$indent<$name${renderAttributes()}>\n")
for (c in children) {
c.render(builder, indent + " ")
}
builder.append("$indent\n")
}
private fun renderAttributes(): String {
val builder = StringBuilder()
for ((attr, value) in attributes) {
builder.append(" $attr=\"$value\"")
}
return builder.toString()
}
override fun toString(): String {
val builder = StringBuilder()
render(builder, "")
return builder.toString()
}
}
abstract class TagWithText(name: String) : Tag(name) {
operator fun String.unaryPlus() {
children.add(TextElement(this))
}
}
class HTML : TagWithText("html") {
fun head(init: Head.() -> Unit) = initTag(Head(), init)
fun body(init: Body.() -> Unit) = initTag(Body(), init)
}
class Head : TagWithText("head") {
fun title(init: Title.() -> Unit) = initTag(Title(), init)
}
class Title : TagWithText("title")
abstract class BodyTag(name: String) : TagWithText(name) {
fun b(init: B.() -> Unit) = initTag(B(), init)
fun p(init: P.() -> Unit) = initTag(P(), init)
fun h1(init: H1.() -> Unit) = initTag(H1(), init)
fun a(href: String, init: A.() -> Unit) {
val a = initTag(A(), init)
a.href = href
}
}
class Body : BodyTag("body")
class B : BodyTag("b")
class P : BodyTag("p")
class H1 : BodyTag("h1")
class A : BodyTag("a") {
var href: String
get() = attributes["href"]!!
set(value) {
attributes["href"] = value
}
}
fun html(init: HTML.() -> Unit): HTML {
val html = HTML()
html.init()
return html
}
```
# Using builders with builder type inference
Kotlin supports builder type inference (or builder inference), which can come in useful when you are working with
generic builders. It helps the compiler infer the type arguments of a builder call based on the type information
about other calls inside its lambda argument.
Consider this example of [buildMap()](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/build-map.html)
usage:
```KOTLIN
fun addEntryToMap(baseMap: Map, additionalEntry: Pair?) {
val myMap = buildMap {
putAll(baseMap)
if (additionalEntry != null) {
put(additionalEntry.first, additionalEntry.second)
}
}
}
```
There is not enough type information here to infer type arguments in a regular way, but builder inference can
analyze the calls inside the lambda argument. Based on the type information about `putAll()` and `put()` calls,
the compiler can automatically infer type arguments of the `buildMap()` call into `String` and `Number`.
Builder inference allows to omit type arguments while using generic builders.
## Writing your own builders
### Requirements for enabling builder inference
Note:
Before Kotlin 1.7.0, enabling builder inference for a builder function required `-Xenable-builder-inference` compiler option.
In 1.7.0 the option is enabled by default.
To let builder inference work for your own builder, make sure its declaration has a builder lambda parameter of a
function type with a receiver. There are also two requirements for the receiver type:
1. It should use the type arguments that builder inference is supposed to infer. For example:
```KOTLIN
fun buildList(builder: MutableList.() -> Unit) { ... }
```
Note:
Note that passing the type parameter's type directly like `fun myBuilder(builder: T.() -> Unit)` is not yet supported.
2. It should provide public members or extensions that contain the corresponding type parameters in their signature.
For example:
```KOTLIN
class ItemHolder {
private val items = mutableListOf()
fun addItem(x: T) {
items.add(x)
}
fun getLastItem(): T? = items.lastOrNull()
}
fun ItemHolder.addAllItems(xs: List) {
xs.forEach { addItem(it) }
}
fun itemHolderBuilder(builder: ItemHolder.() -> Unit): ItemHolder =
ItemHolder().apply(builder)
fun test(s: String) {
val itemHolder1 = itemHolderBuilder { // Type of itemHolder1 is ItemHolder
addItem(s)
}
val itemHolder2 = itemHolderBuilder { // Type of itemHolder2 is ItemHolder
addAllItems(listOf(s))
}
val itemHolder3 = itemHolderBuilder { // Type of itemHolder3 is ItemHolder
val lastItem: String? = getLastItem()
// ...
}
}
```
### Supported features
Builder inference supports:
* Inferring several type arguments ```KOTLIN fun myBuilder(builder: MutableMap.() -> Unit): Map { ... } ```
* Inferring type arguments of several builder lambdas within one call including interdependent ones ```KOTLIN fun myBuilder( listBuilder: MutableList.() -> Unit, mapBuilder: MutableMap.() -> Unit ): Pair, Map> = mutableListOf().apply(listBuilder) to mutableMapOf().apply(mapBuilder) fun main() { val result = myBuilder( { add(1) }, { put("key", 2) } ) // result has Pair, Map> type } ```
* Inferring type arguments whose type parameters are lambda's parameter or return types ```KOTLIN fun myBuilder1( mapBuilder: MutableMap.() -> K ): Map = mutableMapOf().apply { mapBuilder() } fun myBuilder2( mapBuilder: MutableMap.(K) -> Unit ): Map = mutableMapOf().apply { mapBuilder(2 as K) } fun main() { // result1 has the Map type inferred val result1 = myBuilder1 { put(1L, "value") 2 } val result2 = myBuilder2 { put(1, "value 1") // You can use `it` as "postponed type variable" type // See the details in the section below put(it, "value 2") } } ```
## How builder inference works
### Postponed type variables
Builder inference works in terms of postponed type variables, which appear inside the builder lambda during builder
inference analysis. A postponed type variable is a type argument's type, which is in the process of inferring.
The compiler uses it to collect type information about the type argument.
Consider the example with [buildList()](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/build-list.html):
```KOTLIN
val result = buildList {
val x = get(0)
}
```
Here `x` has a type of postponed type variable: the `get()` call returns a value of type `E`, but `E` itself is not yet
fixed. At this moment, a concrete type for `E` is unknown.
When a value of a postponed type variable gets associated with a concrete type, builder inference collects this information
to infer the resulting type of the corresponding type argument at the end of the builder inference analysis. For example:
```KOTLIN
val result = buildList {
val x = get(0)
val y: String = x
} // result has the List type inferred
```
After the postponed type variable gets assigned to a variable of the `String` type, builder inference gets the information
that `x` is a subtype of `String`. This assignment is the last statement in the builder lambda, so the builder inference
analysis ends with the result of inferring the type argument `E` into `String`.
Note that you can always call `equals()`, `hashCode()`, and `toString()` functions with a postponed type variable as a
receiver.
### Contributing to builder inference results
Builder inference can collect different varieties of type information that contribute to the analysis result.
It considers:
* Calling methods on a lambda's receiver that use the type parameter's type ```KOTLIN val result = buildList { // Type argument is inferred into String based on the passed "value" argument add("value") } // result has the List type inferred ```
* Specifying the expected type for calls that return the type parameter's type ```KOTLIN val result = buildList { // Type argument is inferred into Float based on the expected type val x: Float = get(0) } // result has the List type ``` ```KOTLIN class Foo { val items = mutableListOf() } fun myBuilder(builder: Foo.() -> Unit): Foo = Foo().apply(builder) fun main() { val result = myBuilder { val x: List = items // ... } // result has the Foo type } ```
* Passing postponed type variables' types into methods that expect concrete types ```KOTLIN fun takeMyLong(x: Long) { ... } fun String.isMoreThan3() = length > 3 fun takeListOfStrings(x: List) { ... } fun main() { val result1 = buildList { val x = get(0) takeMyLong(x) } // result1 has the List type val result2 = buildList { val x = get(0) val isLong = x.isMoreThan3() // ... } // result2 has the List type val result3 = buildList { takeListOfStrings(this) } // result3 has the List