"Extend, Scope, Delegate" — Kotlin's Power Tools

// Fragment of story/ThreadedContext.kt
// Kabir's Friday version: region and log threaded through every layer by hand.
fun percentOff(pricePaise: Long, percent: Int, region: String, log: AuditLog): Long {
    val result = pricePaise * (100 - percent) / 100
    log.lines += "$region: -$percent% -> $result"
    return result
}

fun priceLine(pricePaise: Long, quantity: Int, region: String, log: AuditLog): Long =
    percentOff(pricePaise, 10, region, log) * quantity

fun priceBasket(lines: List<Pair<Long, Int>>, region: String, log: AuditLog): Long =
    lines.sumOf { (price, quantity) -> priceLine(price, quantity, region, log) }

// An extension function: called like a member, compiled to a static method that takes the receiver first.
fun String.isSku(): Boolean = matches(Regex("SHW-\\d{4}"))

// Extension properties have no backing field: they are getters (and setters) only.
val Int.rupees: Long get() = this * 100L

fun Long.formatPaise(): String = "₹${this / 100}.${(this % 100).toString().padStart(2, '0')}"

// A nullable receiver: callable on null, and 'this' may be null inside.
fun String?.orUnknown(): String = this ?: "UNKNOWN"

open class Shelf
class ChilledShelf : Shelf()

fun Shelf.kind() = "shelf"
fun ChilledShelf.kind() = "chilled shelf"

class Label(val text: String) {
    fun render() = "member: $text"
}

// A member always wins over an extension with the same signature. The compiler warns.
fun Label.render() = "extension: $text"

fun main() {
    println("SHW-1001".isSku()) // -> true
    println(165.rupees) // -> 16500
    println(16_550L.formatPaise()) // -> ₹165.50

    val missing: String? = null
    println(missing.orUnknown()) // -> UNKNOWN

    // Extensions dispatch on the static type: there is no virtual call to override.
    val shelf: Shelf = ChilledShelf()
    println(shelf.kind()) // -> shelf
    println(ChilledShelf().kind()) // -> chilled shelf

    println(Label("Toor Dal").render()) // -> member: Toor Dal
}

// javap -p com.shelfwise.part06.extensions.ExtensionsKt
public static final boolean isSku(java.lang.String);
public static final long getRupees(int);
public static final java.lang.String formatPaise(long);
public static final java.lang.String orUnknown(java.lang.String);
public static final java.lang.String kind(com.shelfwise.part06.extensions.Shelf);
public static final java.lang.String kind(com.shelfwise.part06.extensions.ChilledShelf);
...

class ProductDraft {
    var sku = ""
    var name = ""
    var pricePaise = 0L
    val tags = mutableListOf<String>()
}

fun findName(sku: String): String? = mapOf("SHW-1001" to "Toor Dal 1kg")[sku]

class Reviewer(val name: String) {
    // Inside run, unqualified names resolve against the draft first: 'name' is the product's name.
    fun sign(draft: ProductDraft) = draft.run { "$name, reviewed by ${this@Reviewer.name}" }
}

fun main() {
    // apply: configure an object and return it. Inside, 'this' is the object.
    val draft = ProductDraft().apply {
        sku = "SHW-1001"
        name = "Toor Dal 1kg"
        pricePaise = 16_500
        tags += "staples"
    }

    // also: a side effect that returns the object unchanged. Inside, 'it' is the object.
    val same = draft.also { println("created ${it.sku}") } // -> created SHW-1001
    println(same === draft) // -> true

    // let: transform a value, most often after ?. to run only for non-null.
    println(findName("SHW-1001")?.let { "$it (${it.length} chars)" }) // -> Toor Dal 1kg (12 chars)
    println(findName("SHW-9999")?.let { "found $it" } ?: "no such SKU") // -> no such SKU

    // run: compute a result from an object, with 'this' as the receiver.
    println(draft.run { "$sku: $name at ${pricePaise / 100}" }) // -> SHW-1001: Toor Dal 1kg at 165

    // with: the same as run, but the object is an argument. Reads well for "with this object, do...".
    println(with(draft.tags) { joinToString(prefix = "#") }) // -> #staples

    // takeIf: the value if it passes the check, otherwise null.
    println(15.takeIf { it in 1..90 }) // -> 15
    println(500.takeIf { it in 1..90 }) // -> null

    println(Reviewer("Lena").sign(draft)) // -> Toor Dal 1kg, reviewed by Lena
}

class AuditLog(private val component: String) {
    val lines = mutableListOf<String>()

    fun info(message: String) {
        lines += "[$component] $message"
    }
}

data class Region(val code: String, val vatPercent: Int)

// Context parameters (Stable since 2.4.0): declared once, supplied by the caller's context.
context(region: Region, log: AuditLog)
fun priceWithVat(pricePaise: Long): Long {
    val total = pricePaise * (100 + region.vatPercent) / 100
    log.info("${region.code}: $pricePaise -> $total")
    return total
}

// A caller with the same context passes it on without naming it.
context(region: Region, log: AuditLog)
fun basketTotal(prices: List<Long>): Long = prices.sumOf { priceWithVat(it) }

class Transaction(val id: String) {
    private val writes = mutableListOf<String>()

    fun write(row: String) {
        writes += row
    }

    fun commit(): List<String> = writes.toList()
}

context(tx: Transaction)
fun savePrice(sku: String, pricePaise: Long) = tx.write("$sku=$pricePaise")

// '_': this function never touches the Transaction; it only passes it on, implicitly, to savePrice.
context(_: Transaction)
fun reprice(skus: List<String>, pricePaise: Long) = skus.forEach { savePrice(it, pricePaise) }

// The block's type has a context: inside it, a Transaction is available implicitly.
fun transaction(id: String, block: context(Transaction) () -> Unit) {
    val tx = Transaction(id)
    context(tx) { block() }
    println("commit ${tx.id}: ${tx.commit()}")
}

fun main() {
    val log = AuditLog("pricing")
    // context(a, b) { } (standard library) puts values into the context for the block.
    context(Region("MH", 5), log) {
        println(basketTotal(listOf(10_000, 20_000))) // -> 31500
    }
    log.lines.forEach(::println)
    // -> [pricing] MH: 10000 -> 10500
    // -> [pricing] MH: 20000 -> 21000

    // priceWithVat(10_000)  // error: no context argument for 'region: Region' found.

    transaction("tx-1") {
        savePrice("SHW-1001", 15_900)
        reprice(listOf("SHW-2040", "SHW-2041"), 69_000)
    } // -> commit tx-1: [SHW-1001=15900, SHW-2040=69000, SHW-2041=69000]
}

// javap -p com.shelfwise.part06.context.ContextParametersKt
public static final long priceWithVat(Region, AuditLog, long);
public static final long basketTotal(Region, AuditLog, java.util.List<java.lang.Long>);
public static final void savePrice(Transaction, java.lang.String, long);
public static final void transaction(java.lang.String, kotlin.jvm.functions.Function1<? super Transaction, kotlin.Unit>);

import kotlin.concurrent.thread

// Option 1 from the whiteboard: context in a ThreadLocal.
val currentRegion = ThreadLocal<String>()

fun regionFromThreadLocal(): String? = currentRegion.get()

// The alternative: context as a context parameter.
context(region: Region)
fun regionFromContext(): String = region.code

fun main() {
    currentRegion.set("MH")
    var seen: String? = "unset"
    thread { seen = regionFromThreadLocal() }.join() // the new thread has its own, empty slot
    println(seen) // -> null

    context(Region("MH", 5)) {
        thread { seen = regionFromContext() }.join() // the lambda captures the context like any value
    }
    println(seen) // -> MH
}

interface Catalog {
    fun priceOf(sku: String): Long?
    fun skus(): Set<String>

    // A default method that calls another interface method.
    fun pricedCount(): Int = skus().count { priceOf(it) != null }
}

class InMemoryCatalog(private val prices: Map<String, Long?>) : Catalog {
    override fun priceOf(sku: String) = prices[sku]
    override fun skus() = prices.keys
}

// 'by inner': the compiler writes every Catalog method as a call to 'inner', except those we override.
class CountingCatalog(private val inner: Catalog) : Catalog by inner {
    var lookups = 0
        private set

    override fun priceOf(sku: String): Long? {
        lookups++
        return inner.priceOf(sku)
    }
}

// 'var inner' looks like a swappable decorator, but 'by' captured the value at construction.
class SwitchableCatalog(var inner: Catalog) : Catalog by inner

fun main() {
    val catalog = CountingCatalog(InMemoryCatalog(mapOf("SHW-1001" to 16_500, "SHW-2040" to null)))

    println(catalog.priceOf("SHW-1001")) // -> 16500
    println(catalog.skus()) // -> [SHW-1001, SHW-2040]
    println(catalog.lookups) // -> 1

    // pricedCount() is forwarded to 'inner', and inner's calls to priceOf() never come back here.
    println(catalog.pricedCount()) // -> 1
    println(catalog.lookups) // -> 1

    val switchable = SwitchableCatalog(InMemoryCatalog(mapOf("SHW-1001" to 16_500)))
    switchable.inner = InMemoryCatalog(mapOf("SHW-1001" to 14_900))
    println(switchable.priceOf("SHW-1001")) // -> 16500
}

// javap -c CountingCatalog (simplified)
public int pricedCount();
   0: aload_0
   1: getfield      inner:Lcom/shelfwise/part06/delegation/Catalog;
   4: invokeinterface Catalog.pricedCount:()I
   9: ireturn

import kotlin.properties.Delegates
import kotlin.properties.ReadOnlyProperty
import kotlin.properties.ReadWriteProperty
import kotlin.reflect.KProperty

class Store(val code: String) {
    // lazy: computed on first access, then cached. Thread-safe (synchronized) by default.
    val planogram: List<String> by lazy {
        println("loading planogram for $code")
        listOf("A1: staples", "A2: snacks")
    }
}

class PriceTag(initialPaise: Long) {
    val history = mutableListOf<String>()

    // observable: a callback after every assignment.
    var pricePaise: Long by Delegates.observable(initialPaise) { _, old, new -> history += "$old -> $new" }

    // vetoable: the callback decides whether the assignment happens.
    var discountPercent: Int by Delegates.vetoable(0) { _, _, new -> new in 0..90 }
}

// Map delegation: each property reads the map entry with its own name.
class StoreConfig(values: Map<String, Any?>) {
    val region: String by values
    val openHour: Int by values
}

// A custom delegate: any object with getValue/setValue operators. ReadWriteProperty spells them out.
class Trimmed : ReadWriteProperty<Any?, String> {
    private var value = ""

    override fun getValue(thisRef: Any?, property: KProperty<*>): String = value

    override fun setValue(thisRef: Any?, property: KProperty<*>, value: String) {
        this.value = value.trim()
    }
}

class Listing {
    var title: String by Trimmed()
}

// provideDelegate runs once, when the property is declared: here it registers a column by property name.
open class Table(val name: String) {
    val columns = mutableListOf<String>()

    fun column() = ColumnProvider()

    inner class ColumnProvider {
        operator fun provideDelegate(thisRef: Any?, property: KProperty<*>): ReadOnlyProperty<Any?, String> {
            columns += property.name
            val qualified = "$name.${property.name}"
            return ReadOnlyProperty { _, _ -> qualified }
        }
    }
}

object Products : Table("products") {
    val sku by column()
    val price by column()
}

fun main() {
    // What field-access frameworks (JPA, Gson, Jackson field visibility) see: the delegate, not the value.
    println(Store::class.java.declaredFields.map { it.name }.sorted()) // -> [code, planogram$delegate]

    val pune = Store("PUN-014")
    println("store created") // -> store created
    println(pune.planogram.size)
    // -> loading planogram for PUN-014
    // -> 2
    println(pune.planogram.first()) // -> A1: staples

    val tag = PriceTag(16_500)
    tag.pricePaise = 15_900
    tag.pricePaise = 14_900
    println(tag.history) // -> [16500 -> 15900, 15900 -> 14900]
    tag.discountPercent = 20
    tag.discountPercent = 500 // vetoed: the value stays 20
    println(tag.discountPercent) // -> 20

    val settings = mutableMapOf<String, Any?>("region" to "MH", "openHour" to 7)
    val config = StoreConfig(settings)
    println("${config.region} opens at ${config.openHour}") // -> MH opens at 7
    settings["openHour"] = 9 // the delegate reads the map on every access: no snapshot
    println(config.openHour) // -> 9

    val listing = Listing()
    listing.title = "  Toor Dal 1kg  "
    println("[${listing.title}]") // -> [Toor Dal 1kg]

    println(Products.columns) // -> [sku, price]
    println(Products.sku) // -> products.sku
}

@JvmInline
value class Paise(val amount: Long) : Comparable<Paise> {
    operator fun plus(other: Paise) = Paise(amount + other.amount)

    operator fun times(quantity: Int) = Paise(amount * quantity)

    override fun compareTo(other: Paise) = amount.compareTo(other.amount)

    override fun toString() = "₹${amount / 100}.${(amount % 100).toString().padStart(2, '0')}"
}

// infix: a two-argument call written without dots and parentheses.
infix fun Paise.percentOff(percent: Int) = Paise(amount * (100 - percent) / 100)

class PriceBook {
    private val prices = mutableMapOf<String, Paise>()

    operator fun get(sku: String): Paise? = prices[sku]

    operator fun set(sku: String, price: Paise) {
        prices[sku] = price
    }

    operator fun contains(sku: String) = sku in prices
}

fun main() {
    val dal = Paise(16_500)
    val rice = Paise(72_000)

    println(dal + rice) // -> ₹885.00
    println(dal * 3) // -> ₹495.00
    println(dal < rice) // -> true
    println(dal percentOff 10) // -> ₹148.50

    val book = PriceBook()
    book["SHW-1001"] = dal // set(...)
    println(book["SHW-1001"]) // -> ₹165.00
    println("SHW-9999" in book) // -> false

    var basket = Paise(0)
    basket += dal // no plusAssign defined, so this is basket = basket + dal
    basket += rice
    println(basket) // -> ₹885.00
}

// Fragment of dsl/ProductQuery.kt
data class Product(
    val sku: String,
    val name: String,
    val category: String,
    val pricePaise: Long,
    val tags: Set<String> = emptySet(),
)

// Step 1: the marker. Builders annotated with it can't silently reach an outer builder's methods.
@DslMarker
annotation class QueryDsl

// Step 1 (continued): an extension property, so prices read as 200.rupees.
val Int.rupees: Long get() = this * 100L

typealias Criterion = (Product) -> Boolean

// Fragment of dsl/ProductQuery.kt
// Step 2: the nested builder for alternatives.
@QueryDsl
class AnyOfBuilder {
    internal val alternatives = mutableListOf<Criterion>()

    fun category(name: String) {
        alternatives += { it.category == name }
    }

    fun tagged(tag: String) {
        alternatives += { tag in it.tags }
    }
}

// Fragment of dsl/ProductQuery.kt
// Step 3: the top-level builder. Each call adds a criterion; nothing runs until the query does.
@QueryDsl
class QueryBuilder {
    private val criteria = mutableListOf<Criterion>()
    private var order: Comparator<Product> = compareBy { it.sku }
    private var limit = Int.MAX_VALUE

    fun category(name: String) {
        criteria += { it.category == name }
    }

    fun tagged(vararg tags: String) {
        criteria += { product -> tags.all { it in product.tags } }
    }

    fun priceBelow(paise: Long) {
        criteria += { it.pricePaise < paise }
    }

    fun anyOf(block: AnyOfBuilder.() -> Unit) {
        val alternatives = AnyOfBuilder().apply(block).alternatives.toList()
        criteria += { product -> alternatives.any { it(product) } }
    }

    fun cheapestFirst() {
        order = compareBy { it.pricePaise }
    }

    fun limit(count: Int) {
        limit = count
    }

    fun build() = ProductQuery(criteria.toList(), order, limit)
}

// Fragment of dsl/ProductQuery.kt
class ProductQuery(
    private val criteria: List<Criterion>,
    private val order: Comparator<Product>,
    private val limit: Int,
) {
    // invoke: the query object can be called like a function.
    operator fun invoke(products: List<Product>): List<Product> =
        products.filter { product -> criteria.all { it(product) } }.sortedWith(order).take(limit)
}

// Step 4: the entry point. The lambda's receiver is the builder.
fun query(block: QueryBuilder.() -> Unit): ProductQuery = QueryBuilder().apply(block).build()

// Fragment of dsl/ProductQuery.kt
// Step 5: use it.
fun main() {
    val catalog = listOf(
        Product("SHW-4001", "Penne Rigate 500g", "pasta", 12_000, setOf("gluten-free")),
        Product("SHW-4002", "Fusilli 500g", "pasta", 9_500),
        Product("SHW-4003", "Brown Rice Spaghetti 400g", "pasta", 18_900, setOf("gluten-free", "vegan")),
        Product("SHW-4004", "Quinoa Pasta 250g", "pasta", 24_500, setOf("gluten-free")),
        Product("SHW-5001", "Rice Noodles 200g", "noodles", 8_500, setOf("gluten-free")),
    )

    // "Gluten-free pasta under ₹200?"
    val glutenFreePasta = query {
        category("pasta")
        tagged("gluten-free")
        priceBelow(200.rupees)
        cheapestFirst()
    }
    glutenFreePasta(catalog).forEach { println("${it.sku} ${it.name}") }
    // -> SHW-4001 Penne Rigate 500g
    // -> SHW-4003 Brown Rice Spaghetti 400g

    val noodlesOrVegan = query {
        anyOf {
            category("noodles")
            tagged("vegan")
            // limit(1)  // error: 'fun limit(count: Int): Unit' cannot be called in this context with an implicit receiver. Use an explicit receiver if necessary.
        }
        limit(1)
    }
    println(noodlesOrVegan(catalog).map { it.name }) // -> [Brown Rice Spaghetti 400g]
}

class Log(val name: String)

context(log: Log)
fun whoLogs(): String = log.name

fun main() {
    // Context arguments resolve by type. An inner context of the same type silently wins.
    context(Log("request")) {
        println(whoLogs()) // -> request
        context(Log("batch")) {
            println(whoLogs()) // -> batch
        }
    }
    // Two of the same type at the same level is ambiguous, like two candidate beans for @Autowired.
    // context(Log("a"), Log("b")) { whoLogs() }  // error: multiple potential context arguments for 'log: Log' in scope.
}

        // An extension is a static method on the file's facade class, receiver first.
        System.out.println(ExtensionsKt.isSku("SHW-1001")); // -> true

        // A DSL entry point takes a Function1<QueryBuilder, Unit>: usable, but no longer a DSL.
        ProductQuery pasta = ProductQueryKt.query(q -> {
            q.category("pasta");
            q.limit(1);
            return Unit.INSTANCE;
        });