What is a "receiver" in Kotlin?
When you call:
"Hello, World!".length()
the string "Hello, World!"
whose length you're trying to get is called the receiver.
More generally, any time you write someObject.someFunction()
, with a .
between the object and the function name, the object is acting as the receiver for the function. This isn't special to Kotlin, and is common to many programming languages that use objects. So the concept of a receiver is likely very familiar to you, even if you haven't heard the term before.
It's called a receiver because you can think of the function call as sending a request which the object will receive.
Not all functions have a receiver. For example, Kotlin's println()
function is a top-level function. When you write:
println("Hello, World!")
you don't have to put any object (or .
) before the function call. There's no receiver because the println()
function doesn't live inside an object.
On the receiving end
Now let's look at what a function call looks like from the point of view of the receiver itself. Imagine we've written a class that displays a simple greeting message:
class Greeter(val name: String) {
fun displayGreeting() {
println("Hello, ${this.name}!")
}
}
To call displayGreeting()
, we first create an instance of Greeter
, then we can use that object as a receiver to call the function:
val aliceGreeter = Greeter("Alice")
val bobGreeter = Greeter("Bob")
aliceGreeter.displayGreeting() // prints "Hello, Alice!"
bobGreeter.displayGreeting() // prints "Hello, Bob!"
How does the displayGreeting
function know which name to display each time? The answer is the keyword this
, which always refers to the current receiver.
- When we call
aliceGreeter.displayGreeting()
, the receiver isaliceGreeter
, sothis.name
points to"Alice"
. - When we call
bobGreeter.displayGreeting()
, the receiver isbobGreeter
, sothis.name
points to"Bob"
.
Implicit receivers
Most of the time, there's actually no need to write this
. We can replace this.name
with just name
and it will implicitly point to the name
property of the current receiver.
class Greeter(val name: String) {
fun displayGreeting() {
println("Hello, $name!")
}
}
Notice how that differs from accessing a property from outside the class. To print the name from outside, we'd have to write out the full name of the receiver:
println("Hello, ${aliceGreeter.name}")
By writing the function inside the class, we can omit the receiver completely, making the whole thing much shorter. The call to name
still has a receiver, we just didn't have to write it out. We can say that we accessed the name
property using an implicit receiver.
Member functions of a class often need to access many other functions and properties of their own class, so implicit receivers are very useful. They shorten the code and can make it easier to read and write.
How do receivers relate to extensions?
So far, it seems like a receiver is doing two things for us:
- Sending a function call to a specific object, because the function lives inside that object
- Allowing a function convenient and and concise access to the other properties and functions that live inside the same object
What if we want to write a function that can use an implicit receiver for convenient access to the properties and functions of an object, but we don't want to (or can't) write our new function inside that object/class? This is where Kotlin's extension functions come in.
fun Greeter.displayAnotherGreeting() {
println("Hello again, $name!")
}
This function doesn't live inside Greeter
, but it accesses Greeter
as if it was a receiver. Notice the receiver type before the function name, which tells us that this is an extension function. In the body of the extension function, we can once again access name
without its receiver, even though we're not actually inside the Greeter
class.
You could say that this isn't a "real" receiver, because we're not actually sending the function call to an object. The function lives outside the object. We're just using the syntax and appearance of a receiver because it makes for convenient and concise code. We can call this an extension receiver, to distinguish it from the dispatch receiver that exists for functions that are really inside an object.
Extension functions are called in the same way as member functions, with a receiver object before the function name.
val aliceGreeter = Greeter("Alice")
aliceGreeter.displayAnotherGreeting() // prints "Hello again, Alice!"
Because the function is always called with an object in the receiver position before the function name, it can access that object using the keyword this
. Like a member function, an extension function can also leave out this
and access the receiver's other properties and functions using the current receiver instance as the implicit receiver.
One of the main reasons extension functions are useful is that the current extension receiver instance can be used as an implicit receiver inside the body of the function.
What does with
do?
So far we've seen two ways to make something available as an implicit receiver:
- Create a function inside the receiver class
- Create an extension function outside the class
Both approaches require creating a function. Can we have the convenience of an implicit receiver without declaring a new function at all?
The answer is to call with
:
with(aliceGreeter) {
println("Hello again, $name!")
}
Inside the block body of the call to with(aliceGreeter) { ... }
, aliceGreeter
is available as an implicit receiver and we can once again access name
without its receiver.
So how come with
can be implemented as a function, rather than a language feature? How is it possible to simply take an object and magic it into an implicit receiver?
The answer lies with lambda functions. Let's consider our displayAnotherGreeting
extension function again. We declared it as a function, but we could instead write it as a lambda:
val displayAnotherGreeting: Greeter.() -> Unit = {
println("Hello again, $name!")
}
We can still call aliceGreeter.displayAnotherGreeting()
the same as before, and the code inside the function is the same, complete with implicit receiver. Our extension function has become a lambda with receiver. Note the way the Greeter.() -> Unit
function type is written, with the extension receiver Greeter
listed before the (empty) parameter list ()
.
Now, watch what happens when we pass this lambda function as an argument to another function:
fun runLambda(greeter: Greeter, lambda: Greeter.() -> Unit) {
greeter.lambda()
}
The first argument is the object that we want to use as the receiver. The second argument is the lambda function we want to run. All runLambda
does is to call the provided lambda parameter, using the greeter
parameter as the lambda's receiver.
Substituting the code from our displayAnotherGreeting
lambda function into the second argument, we can call runLambda
like this:
runLambda(aliceGreeter) {
println("Hello again, $name!")
}
And just like that, we've turned aliceGreeter
into an implicit receiver. Kotlin's with
function is simply a generic version of this that works with any type.
Recap
- When you call
someObject.someFunction()
, someObject
is acting as the receiver that receives the function call
- Inside
someFunction
, someObject
is "in scope" as the current receiver instance, and can be accessed as this
- When a receiver is in scope, you can leave out the word
this
and access its properties and functions using an implicit receiver
- Extension functions let you benefit from the receiver syntax and implicit receivers without actually dispatching a function call to an object
- Kotlin's
with
function uses a lambda with receiver to make receivers available anywhere, not just inside member functions and extension functions
Function Literals/Lambda with Receiver
someObject.someFunction()
, someObject
is acting as the receiver that receives the function callsomeFunction
, someObject
is "in scope" as the current receiver instance, and can be accessed as this
this
and access its properties and functions using an implicit receiverwith
function uses a lambda with receiver to make receivers available anywhere, not just inside member functions and extension functionsKotlin supports the concept of “function literals with receivers”. It enables the access on visible methods and properties of a receiver of a lambda in its body without any additional qualifiers. This is very similar to extension functions in which it’s also possible to access visible members of the receiver object inside the extension.
A simple example, also one of the greatest functions in the Kotlin standard library, is apply
:
public inline fun <T> T.apply(block: T.() -> Unit): T { block(); return this }
As you can see, such a function literal with receiver is taken as the argument block
here. This block is simply executed and the receiver (which is an instance of T
) is returned. In action this looks as follows:
val foo: Bar = Bar().apply {
color = RED
text = "Foo"
}
We instantiate an object of Bar
and call apply
on it. The instance of Bar
becomes the “receiver”. The block
, passed as an argument in {}
(lambda expression) does not need to use additional qualifiers to access and modify the shown visible properties color
and text
.
The concept of lambdas with receiver is also the most important feature for writing DSLs with Kotlin.
It is true that there appears to be little existing documentation for the concept of receivers (only a small side note related to extension functions), which is surprising given:
- their existence springing out of extension functions;
- their role in building a DSL using said extension functions;
- the existence of a standard library function
with
, which given no knowledge of receivers might look like a keyword; - a completely separate syntax for function types.
All these topics have documentation, but nothing goes in-depth on receivers.
First:
What's a receiver?
Any block of code in Kotlin may have a type (or even multiple types) as a receiver, making functions and properties of the receiver available in that block of code without qualifying it.
Imagine a block of code like this:
{ toLong() }
Doesn't make much sense, right? In fact, assigning this to a function type of (Int) -> Long
- where Int
is the (only) parameter, and the return type is Long
- would rightfully result in a compilation error. You can fix this by simply qualifying the function call with the implicit single parameter it
. However, for DSL building, this will cause a bunch of issues:
- Nested blocks of DSL will have their upper layers shadowed:
html { it.body { // how to access extensions of html here? } ... }
This may not cause issues for a HTML DSL, but may for other use cases. - It can litter the code with
it
calls, especially for lambdas that use their parameter (soon to be receiver) a lot.
This is where receivers come into play.
By assigning this block of code to a function type that has Int
as a receiver (not as a parameter!), the code suddenly compiles:
val intToLong: Int.() -> Long = { toLong() }
Whats going on here?
A little side note
This topic assumes familiarity with function types, but a little side note for receivers is needed.
Function types can also have one receiver, by prefixing it with the type and a dot. Examples:
Int.() -> Long // taking an integer as receiver producing a long
String.(Long) -> String // taking a string as receiver and long as parameter producing a string
GUI.() -> Unit // taking an GUI and producing nothing
Such function types have their parameter list prefixed with the receiver type.
Resolving code with receivers
It is actually incredibly easy to understand how blocks of code with receivers are handled:
Imagine that, similar to extension functions, the block of code is evaluated inside the class of the receiver type. this effectively becomes amended by the receiver type.
For our earlier example, val intToLong: Int.() -> Long = { toLong() }
, it effectively results in the block of code being evaluated in a different context, as if it was placed in a function inside Int
. Here's a different example using handcrafted types that showcases this better:
class Bar
class Foo {
fun transformToBar(): Bar = TODO()
}
val myBlockOfCodeWithReceiverFoo: (Foo).() -> Bar = { transformToBar() }
effectively becomes (in the mind, not code wise - you cannot actually extend classes on the JVM):
class Bar
class Foo {
fun transformToBar(): Bar = TODO()
fun myBlockOfCode(): Bar { return transformToBar() }
}
val myBlockOfCodeWithReceiverFoo: (Foo) -> Bar = { it.myBlockOfCode() }
Notice how inside of a class, we don't need to use this
to access transformToBar
- the same thing happens in a block with a receiver.
It just so happens that the documentation on this also explains how to use an outermost receiver if the current block of code has two receivers, via a qualified this.
Wait, multiple receivers?
Yes. A block of code can have multiple receivers, but this currently has no expression in the type system. The only way to achieve this is via multiple higher-order functions that take a single receiver function type. Example:
class Foo
class Bar
fun Foo.functionInFoo(): Unit = TODO()
fun Bar.functionInBar(): Unit = TODO()
inline fun higherOrderFunctionTakingFoo(body: (Foo).() -> Unit) = body(Foo())
inline fun higherOrderFunctionTakingBar(body: (Bar).() -> Unit) = body(Bar())
fun example() {
higherOrderFunctionTakingFoo {
higherOrderFunctionTakingBar {
functionInFoo()
functionInBar()
}
}
}
Do note that if this feature of the Kotlin language seems inappropriate for your DSL, @DslMarker is your friend!
Conclusion
Why does all of this matter? With this knowledge:
- you now understand why you can write
toLong()
in an extension function on a number, instead of having to reference the number somehow. Maybe your extension function shouldn't be an extension? - You can build a DSL for your favorite markup language, maybe help parsing the one or other (who needs regular expressions?!).
- You understand why
with
, a standard library function and not a keyword, exists - the act of amending the scope of a block of code to save on redundant typing is so common, the language designers put it right in the standard library. - (maybe) you learned a bit about function types on the offshoot.
var greet: String.() -> Unit = { println("Hello $this") }
this defines a variable of type String.() -> Unit
, which tells you
String
is the receiver() -> Unit
is the function type
Like F. George mentioned above, all methods of this receiver can be called in the method body.
So, in our example, this
is used to print the String
. The function can be invoked by writing...
greet("Fitzgerald") // result is "Hello Fitzgerald"
the above code snippet was taken from Kotlin Function Literals with Receiver – Quick Introduction by Simon Wirtz.