Enables deconstructive pattern-matching on algebraic data types, similar to Scala's syntax. Offers custom patterns, supports type parameters, and integrates with Kotlin Symbol Processing for generating extensions.
Scala-Style Deconstructive Pattern-Matching for Kotlin.
Decomat is available on Maven Central. To use it, add the following to your build.gradle.kts:
implementation("io.exoquery:decomat-core:0.0.2")
ksp("io.exoquery:decomat-ksp:0.0.2")
Decomat is a library that gives Kotlin a way to do pattern-matching on ADTs (Algebraic Data Types) in a way that is similar to Scala's pattern-matching. For example:
case class Customer(name: Name, affiliate: Affiliate)
case class Name(first: String, last: String)
sealed trait Affiliate
case class Partner(id: Int) extends Affiliate
case class Organization(name: String) extends Affiliate
someone match {
case Customer(Name(first @ "Joe", last), Partner(id)) => func(first, last, id)
case Customer(Name(first @ "Jack", last), Organization("BigOrg")) => func(first, last)
}
Similarly, in Kotlin with Decomat you can do this:
bigListOfPeople.mapNotNull { p ->
p.match(
case( Customer[FullName[Is("Joe"), Is()], Partner[Is()]] )
.then { first, last, id -> func(first, last, id) },
)
}
on(someone).match(
case( Customer[Name[Is("Joe"), Is()], Partner[Is()]] )
.then { first, last, id -> func(first, last, id) },
case( Customer[Name[Is("Jack"), Is()], Organization[Is("BigOrg")]] )
.then { first, last -> func(first, last) }
)
Whereas normally the following would be needed:
when(someone) {
is Customer ->
if (someone.name.first == "Joe") {
when (val aff = someone.affiliate) {
is Partner -> {
func(someone.name.first, someone.name.last, aff.id)
}
-> fail()
}
} (someone.name.first == ) {
( aff = someone.affiliate) {
Organization -> {
(aff.name == ) {
func(someone.name.first, someone.name.last)
} fail()
}
-> fail()
}
} fail()
}
Decomat is not a full replacement of Scala's pattern-matching, but it does have some of the same features and usage patterns in a limited scope. The primary insight behind Decomat is that for in most of the cases where Scala ADT pattern matching is used:
if statement (see thenIfThis below).In order to get started with Decomat, add the needed dependencies to your build.gradle.kts
file and enable KSP. Decomat relies on various extension methods that are generated by KSP.
// build.gradle.kts
plugins {
...
id("com.google.devtools.ksp") version "<ksp-version>"
}
implementation("io.exoquery:decomat-core:<version>")
ksp("io.exoquery:decomat-ksp:<version>")
Then:
@Matchable annotation your class and @Component annotation to (up to two) constructor parameters.HasProductClass<YourDataClass>.productComponents field to your class and pass this and the component-fields into it.@Matchable
data class Customer(@Component val name: Name, @Component val affiliate: Affiliate) {
override val productComponents = productComponentsOf(this, name, affiliate)
companion object {}
}
Follow these steps for all other classes that you want to pattern match on, in the case above to Name and Partner as follows:
@Matchable
data class ( first: String, last: String) {
productComponents = productComponentsOf(, first, last)
{}
}
( id: ) {
productComponents = productComponentsOf(, id)
{}
}
Then use KSP to generate the needed extension methods, in IntelliJ this typically just means
running the 'Rebuild Project' command. The extension-methods will be generated inside of your
project under projectDir/build/generated/ksp/main/kotlin/. They will
be placed in the same package as the @Matchable data classes.
Note that ONLY the parameters that you actually want to deconstruct shuold be annotated with
@Componentand only 2 are supported. You can use thethenIfThisand methods to conveniently interact with non-component methods during filtration. There can be other non-component parameters in the constructor before, after, and in-between them:
Then you can use the on and case functions to pattern match on the ADTs and the then function to
perform transformations.
on(someone).match(
case( Customer[Name[Is("Joe"), Is()], Partner(Is())] )
.then { first, last, id -> func(first, last, id) },
// Other cases...
}
Note that Scala also allows you to match a variable based on just a type. For example:
someone match {
case Customer(Name(first, last), partner: Partner) => func(first, last, part)
}
In Decomat, you can do using the the Is function with a type and empty parameter-list.
on(someone).match(
case( Customer[Name[Is(), Is()], Is<Partner>()] )
// Note how since we are not deconstructing the Partner class anymore, the 3rd parameter
// switches from the `id: Int` type to the `partner: Partner` type.
.then { first, last, partner /*: Partner*/ -> func(first, last, partner) },
// Other cases...
)
There are several other methods provided for pattern-matching convenience.
The thenIf method allows you to perform a transformation only if the predicate is true. This is similar
to adding a if clause to a Scala pattern-match case. For example:
someone match {
case Customer(Name(first, last), Partner(id)) if (first == "Joe") => func(first, last, id)
...
}
In Decomat, this would be done as follows:
on(someone).match(
case( Customer[Name[Is(), Is()], Partner(Is())] )
.thenIf { first, last, id -> first == "Joe" }
.then { first, last, id -> func(first, last, id) },
// Other cases...
)
If you want to filter by a non @Component annoated field, you can use the thenIfThis method.
This method allows you to use the pattern-matched object as a reciever. For example:
@Matchable
data class Customer(val something: String, @Component val name: Name, @Component val affiliate: Affiliate) { ... }
on(something).match(
case( Customer[Name[Is(), Is()], Partner(Is())] )
.thenIfThis {{ first, last, id ->
// Note that the first, last, and id properties are available here but you do not necessarily need to use them,
// since you can use the `this` keyword to refer to the `Customer` instance (also `this` can be omitted entirely).
something ==
}}
.then { name, affiliate -> func(name, affiliate) },
)
Here we are using the Customer class as a reciever in the thenIfThis class above. The properties
first, last, and id are also available to use if you need them.
The actual signature of
thenIfThisis:R.() -> (component1, component2, ...) -> BooleanThat is why the double braches
{{ ... }}are needed.
If you want to use any fields of the pattern-matched object that are not one of the components, you can use the thenThis method.
This method allows you to use the pattern-matched object as a reciever. For example:
@Matchable
data class Customer(val something: String, @Component val name: Name, @Component val affiliate: Affiliate) {
val somethingElse = "somethingElse"
...
}
on(something).match(
case( Customer[Name[Is(), Is()], Partner(Is())] )
.thenThis { first, last, id ->
.something + .somethingElse
}
)
The Is(...) pattern is use to match the innermost patterns. It can be use to match by value, or by type.
Matching by value:
```kotlin
// Match only when affiliate is a Partner with id 123
on(something).match(
case( Customer[..., Is(Partner(123))] ).then { ... },
// Other cases...
)
Matching by type:
// Match only when affiliate is of the type: Partner
on(something).match(
case( Customer[..., Is<Partner>] ).then { ... },
// Other cases...
)
It is also possible to use the Is pattern to match by a custom predicate. Use this for more complex pattern
matching but be warned that it may be less performant than the other methods because the predicate does not inline.
on(something).match(
case( Customer[..., Is<Partner> { p -> (p.id == 123 || p.id == 456) }] ).then { ... },
// Other cases...
)
You can also define custom Is-variants based on predicates for example:
def isPartnerWithIds(vararg ids: Int) = IsIs<Partner> { p -> p is Partner && ids.contains(p.id) }
on(something).match(
case( Customer[..., isPartnerWithIds(123, 456)] ).then { ... },
// Other cases...
)
Note that in many cases, you can use the thenIf method instead of the Is { ... } predicate function which
does inline leading to better performance.
on(something).match(
case( Customer[..., Is<Partner>() )
// This will be inlined
.thenIf { _, aff -> aff is Partner && (aff.id == 123 || aff.id == 456) }
.then { ... },
// Other cases...
)
One extremely powerful feature of Scala pattern-matching is that one can use custom patterns in a composable manner. For example:
// Create a Data model
case class Person(name: Name, age: Int)
sealed trait Name
case class SimpleName(first: String, last: String) extends Name
case class FullName(first: String, middle: String, last: String) extends Name
// Create a custom pattern
object FirstLast {
def unapply(name: Name): Option[(String, String)] = name match {
case SimpleName(first, last) => Some(first, last)
case FullName(first, _, last) => Some(first, last)
case _ => None
}
}
// Now we can use the pattern to match and extract custom data
val p: Person = ...
p match {
case Person(FirstLast("Joe", last), age) => ...
}
Similarly, Decomat allows you to create custom patterns. For example:
Note that when Scala pattern matching clauses get complex, it is common to use pattern matching itself in order to deconstruct
patterns into smaller patterns. That means that if we make SimpleName and FullName matchable, we can
use them with Decomat's matching instead of Kotlin when statement. This gives us more versatility.
For example:
This latter approach is particularly useful when you want the custom pattern matching function itself to have complex nested conditional logic. For example:
// Match all full-names where the first-name is "Joe" or "Jack"
// Match all simple-names where the last-name is "Bloggs" and "Roogs"
object FirstLast {
operator fun get(first: Pattern0<String>, last: Pattern0<String>) =
customPattern2(first, last) { it: Name ->
on(it).match(
case(FullName[Is { it == || it == }, Is()])
.then { first, last -> Components2(first, last) },
case(SimpleName[Is(), Is { it == || it == }])
.then { first, last -> Components2(first, last) }
)
}
}
Decomat supports ADTs with type parameters but they are not used in the Pattern-components. Instead, they are converted into start-projections. This is because typing all of the parameters would make the matching highly restrictive. (Also, type-parameters cannot be used as part of the pattern-matching due to type-erasure.)
For example:
<>
<>( head: Query<T>, body: Query<R>): Query<R> {
}
<>( value: T): Query<T> {
: Query<R> = Property(, getter())
}
The Query interface must be up-casted into into a star-projection when it is used in a match.
val query: Query<Something> = ...
on(query as Query<*>).match(
case( Map[Is(), Is()] )
.then { head: Query<*>, body: Query<*> -> func(head, body) },
case( Entity[Is()] )
.then { value: Entity<*> -> func(value) },
// Other cases...
)
Note how the head and body elements are star projections instead of the origin types?
This is done so that the Map case can match any Query type, otherwise the matching logic would be too restrictive.
(E.g. it would be difficult to deduce the type of the head and body elements causing the generated code to be incorrect)
If you want to experiment with fully-typed ADT-components nonetheless, use @Matchable(simplifyTypes = false).
Kotlin allows changing an import name using the import ... as ... syntax. This can be used to change the
@Matchable annotation name to something else, however due to issue #783 it is not possible to genenerically
detect this change inside of a KSP processor. Therefore, if you change the annotation name, you must also
add the following setting to your build.gradle.kts file:
// build.gradle.kts
ksp {
arg("matchableName", "Mat")
arg("componentName", "Slot")
}
Then rename the @Matchable annotation to @Mat and the @Component annotation to @Slot
in the import:
import io.decomat.Matchable as Mat
import io.decomat.Component as Slot
// Then use the annotations as follows:
@Mat
data class Person(@Slot val firstName: String, @Slot val lastName: String) {
override productComponents = productComponentsOf(, firstName, lastName)
{}
}
thenThis@Matchable
data class Customer(
val something: String,
@Component val name: Name,
val somethingElse: String,
@Component val affiliate: Affiliate,
val yetSomethingElse: String
) { ... }
// First Create our data model
data class Person( val name: Name, val age: Int): HasProductClass<Person> {
override val productComponents = ProductClass2(this, name, age)
companion object { }
}
sealed interface Name
data class SimpleName(val first: String, val last: String): Name
data class FullName(val first: String, val middle: String, val last: String): Name
// Then create our custom pattern matcher. Use the customPattern1 or customPattern2 functions to create the custom pattern.
object FirstLast {
operator fun get(first: Pattern0<String>, last: Pattern0<String>) =
customPattern2(first, last) { it: Name ->
when(it) {
is SimpleName -> first.matches(it.first) && last.matches(it.last)
is FullName -> first.matches(it.first) && last.matches(it.last)
else -> false
}
}
}
// Then use the `FirstLast` custom pattern to match and extract data
val p: Person = ...
val out =
on(p).match(
case(Person[FirstLast[Is("Joe"), Is()], Is()]).then { (first, last), age -> ... }
)
// Annotate SimpleName and FullName as @Matchable in additionl to `Person`
data class Person( val name: Name, val age: Int): HasProductClass<Person> {
override val productComponents = ProductClass2(this, name, age)
companion object { }
}
sealed interface Name
data class SimpleName( val first: String, val last: String): Name, HasProductClass<SimpleName> {
override val productComponents = ProductClass2(this, first, last)
companion object { }
}
data class FullName( val first: String, val middle: String, val last: String): Name, HasProductClass<FullName> {
override val productComponents = ProductClass3(this, first, middle, last)
companion object { }
}
// Then create our custom pattern matcher which itself uses on/match functions:
object FirstLast {
operator fun get(first: Pattern0<String>, last: Pattern0<String>) =
customPattern2(first, last) { it: Name ->
on(it).match(
case(FullName[Is(), Is()]).then { first, last -> Components2(first, last) },
case(SimpleName[Is(), Is()]).then { first, last -> Components2(first, last) }
)
}
}
// Then use the `FirstLast` custom pattern to match and extract data the same as before...
val p: Person = ...
val out =
on(p).match(
case(Person[FirstLast[Is("Joe"), Is()], Is()]).then { (first, last), age -> ... }
)
Surfaced from shared tags and platforms — no rankings paid for.