Exhaustive
An annotation and Kotlin compiler plugin for enforcing a when statement is exhaustive.
Note: This plugin is reaching its end-of-life and is soft deprecated. Learn more.
enum class RouletteColor { Red, Black, Green }
fun printColor(color: RouletteColor) {
@Exhaustive
when (color) {
Red -> println("red")
Black -> println("black")
}
}
e: Example.kt:5: @Exhaustive when is not exhaustive!
Missing branches:
- RouletteColor.Green
No more assigning to dummy local properties or referencing pointless functions or properties to force the when to be an expression for exhaustiveness checking. The plugin reuses the same check that is used for a when expression.
In addition to being forced to be exhaustive, an annotated when statement is forbidden from using an else branch.
fun printColor(color: RouletteColor) {
@Exhaustive
when (color) {
Red -> println("red")
Black -> println("black")
else -> println("green")
}
}
e: Example.kt:5: @Exhaustive when must not contain an 'else' branch
The presence of an else block indicates support for a default action. The exhaustive check would otherwise always pass with this branch which is why it is disallowed.
Sealed classes are also supported.
sealed class RouletteColor {
object Red : RouletteColor()
object Black : RouletteColor()
object Green : RouletteColor()
}
fun printColor(color: RouletteColor) {
@Exhaustive
when (color) {
RouletteColor.Red -> println("red")
RouletteColor.Black -> println("black")
}
}
e: Example.kt:9: @Exhaustive when is not exhaustive!
Missing branches:
- RouletteColor.Green
Soft Deprecated
We did it! Kotlin 1.7 will make all when statements exhaustive by default (where possible) and this plugin will no longer be required.
In order to change the language behavior, Kotlin 1.6 will first warn when a when statement is not exhaustive. Kotlin 1.5.30 ships with this warning as opt-in behavior by setting your languageVersion to 1.6.
kotlin {
sourceSets.all {
languageSettings {
languageVersion = '1.6'
}
}
}
If you want to opt-in to errors instead of warnings, enable progressive mode.
kotlin {
sourceSets.all {
languageSettings {
languageVersion = '1.6'
progressiveMode = true
}
}
}
This plugin will continue to be maintained until Kotlin 1.7.0 is released for those who cannot enable these in their builds.
Usage
buildscript {
dependencies {
classpath 'app.cash.exhaustive:exhaustive-gradle:0.2.0'
}
repositories {
mavenCentral()
}
}
apply plugin: 'org.jetbrains.kotlin.jvm' // or .android or .multiplatform or .js
apply plugin: 'app.cash.exhaustive'
The @Exhaustive annotation will be made available in your main and test source sets but will not be shipped as a dependency of the module.
Since Kotlin compiler plugins are an unstable API, certain versions of Exhaustive only work with certain versions of Kotlin.
| Kotlin | Exhaustive |
|---|---|
| 1.4.10 - 1.5.10 | 0.1.1 |
| 1.5.20 - 1.5.30 | 0.2.0 |
Versions of Kotlin older than 1.4.10 are not supported. Versions newer than those listed may be supported but are untested.
Snapshots of the development version are available in Sonatype's snapshots repository.
buildscript {
dependencies {
classpath 'app.cash.exhaustive:exhaustive-gradle:0.3.0-SNAPSHOT'
}
repositories {
maven {
url 'https://oss.sonatype.org/content/repositories/snapshots/'
}
}
}
// 'apply' same as above
Alternatives Considered
In the weeks prior to building this project a set of alternatives were explored and rejected for various reasons. They are listed below. If you evaluate their merits differently, you are welcome to use them instead. The solution provided by this plugin is not perfect either.
Unused local and warning suppression
fun printColor(color: RouletteColor) {
@Suppress("UNUSED_VARIABLE")
val exhaustive = when (color) {
RouletteColor.Red -> println("red")
RouletteColor.Black -> println("black")
}
}
Pros:
- Works everywhere without library or plugin
- No overhead or impact on compiled code
Neutral:
- Somewhat self-describing as to the intent, assuming good local property names
- Good locality as the exhaustiveness forcing is very close to the
whenkeyword, although somewhat overshadowed by the warning suppression
Cons:
- Requires suppression of warning which need to be put into a shared template or requires alt+enter,enter-ing to create the final form
- Requires the use of unique local property names (
_is not allowed here)
Built-in trailing property or function call
fun printColor(color: RouletteColor) {
when (color) {
RouletteColor.Red -> println("red")
RouletteColor.Black -> println("black")
}.javaClass // or .hashCode() or anything else...
}
Pros:
- Works everywhere without library or plugin
Cons:
- Not self-describing as to the effect on the
whenand the developer intent behind adding it - Poor locality as the property is far away from the
whenkeyword it modifies - Impact on compiled code in the form of a property call, function call, and/or additional instructions at the call-site
Library trailing property
@Suppress("unused") // Receiver reference forces when into expression form.
inline val Any?.exhaustive get() = Unit
fun printColor(color: RouletteColor) {
when (color) {
RouletteColor.Red -> println("red")
RouletteColor.Black -> println("black")
}.exhaustive
}
Pros:
- Self-describing effect on the
when - No impact on compiled code
Cons:
- Requires a library
- Poor locality as the property is far away from the
whenkeyword it modifies - Pollutes the extension namespace by showing up for everything, not just
when
Library leading expression
@Suppress("NOTHING_TO_INLINE", "ClassName", "UNUSED_PARAMETER") // Faking a soft keyword.
object exhaustive {
inline operator fun minus(other: Any?) = Unit
}
fun printColor(color: RouletteColor) {
exhaustive-when (color) {
RouletteColor.Red -> println("red")
RouletteColor.Black -> println("black")
}
}
Pro:
- Great locality as the syntactical trick appears almost like a soft keyword modifying the
when
Neutral:
- Slight impact on compiled code (which could be mitigated on Android with an embedded R8 rule)
Cons:
- Requires a library
- Feels too clever
- Code formatting will insert a space before and after the minus sign breaking the effect
Use soft keyword in compiler
fun printColor(color: RouletteColor) {
sealed when (color) {
RouletteColor.Red -> println("red")
RouletteColor.Black -> println("black")
}
}
Pros:
- Great locality as a soft keyword directly modifying the
when - No impact on compiled code
- Part of the actual language
Cons:
- Requires forking the compiler and IDE plugin which is an overwhelming long-term commitment!!!
License
Copyright 2020 Square, Inc.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
18 Nov 24, 2022
7 Oct 14, 2022
10 Dec 2, 2022
1.4k Dec 28, 2022
2 Oct 9, 2022
25 Aug 18, 2022
0 Feb 5, 2022
17 Nov 22, 2021
3 Jan 10, 2022
3 Dec 21, 2022
116 Jan 3, 2023
1 Feb 14, 2022
0 Jan 20, 2022
3 Dec 10, 2022
14 Dec 26, 2022
10 Sep 20, 2022
17 Oct 29, 2022
8 Nov 26, 2022
8 Dec 29, 2022