Los contratos de la stdlib: cómo la librería habla con el compilador

Hay un momento en el aprendizaje de Kotlin en el que uno repara en una anomalía y no sabe explicarla. Escribir la comparación con nulo a mano concede el estrechamiento, como es de esperar; pero envolver exactamente la misma comparación en una función propia lo destruye, mientras que llamar a una función de la biblioteca estándar que hace lo mismo lo conserva intacto. Durante un tiempo parece magia reservada a la librería, un privilegio del que el código de usuario no participa. No lo es. Lo que hay es un mecanismo declarado, público y disponible para cualquiera, que permite a una función devolver al llamante no solo un valor sino también un hecho comprobable por el análisis de flujo. Entender cómo funciona ese canal es entender por qué la biblioteca estándar de Kotlin se lee como si fuera parte del lenguaje.

Por qué una llamada corta la propagación

El análisis de flujo trabaja dentro de una función y trata cada llamada como una caja negra descrita únicamente por su firma. Si escribes una función auxiliar que comprueba la nulidad y devuelve un booleano, el compilador ve que devuelve Boolean y nada más; no relaciona ese booleano con el argumento, porque en general no puede.

fun estaVacio(t: String?): Boolean = t == null || t.isEmpty()

fun etiqueta(t: String?): String {
    if (estaVacio(t)) return "vacio"
    // return t.trim()   // denegado: el booleano no dice nada sobre t
    return t!!.trim()
}

Un contrato es la declaración explícita de esa relación perdida. Se escribe como primera instrucción del cuerpo, mediante una llamada a una función de la biblioteca que no genera código y cuyo único efecto es informar al compilador. La cláusula más común afirma que, cuando la función devuelve cierto valor, cierta condición sobre los argumentos es verdadera.

@OptIn(ExperimentalContracts::class)
fun estaVacio(t: String?): Boolean {
    contract { returns(false) implies (t != null) }
    return t == null || t.isEmpty()
}

fun etiqueta(t: String?): String {
    if (estaVacio(t)) return "vacio"
    return t.trim()   // ahora si: el contrato reinyecto el hecho
}

Léase con cuidado la dirección de la afirmación. El contrato no dice que devolver falso implique haber comprobado algo, sino que si devuelve falso entonces el argumento no es nulo. Es una implicación en un solo sentido: del valor de retorno hacia el hecho, nunca al revés. Y el compilador la aplica únicamente en la rama del if que corresponde a ese valor de retorno.

Anatomía de los contratos reales

La biblioteca estándar declara el suyo en las funciones que estarían condenadas a inutilizar el análisis. El de la comprobación de vacío es prácticamente idéntico al del ejemplo anterior, con la salvedad de que se aplica a un receptor de extensión y de que la implicación se expresa sobre ese receptor.

// forma equivalente a la de la biblioteca estandar
@OptIn(ExperimentalContracts::class)
fun CharSequence?.isNullOrEmpty(): Boolean {
    contract { returns(false) implies (this@isNullOrEmpty != null) }
    return this == null || this.length == 0
}

Las funciones de validación usan una variante donde la implicación no está condicionada a un valor de retorno concreto sino al mero hecho de haber retornado. Como require lanza una excepción cuando la condición falla, el simple hecho de que el control siga adelante ya demuestra que la condición era cierta, y eso es exactamente lo que declara.

// esquema de las validaciones de la biblioteca
contract { returns() implies (valor) }              // require, check
contract { returns() implies (valor != null) }      // requireNotNull, checkNotNull
contract { returnsNotNull() implies (t != null) }   // forma sobre el retorno

La segunda familia de cláusulas es distinta en naturaleza y mucho menos conocida. No habla del valor de retorno sino de cuántas veces y cuándo se invoca una lambda recibida como parámetro. Todas las funciones de ámbito la declaran, y de ahí procede una comodidad que casi nadie atribuye a su verdadera causa: la posibilidad de asignar un val dentro de un bloque run o apply y que el compilador acepte que quedó inicializado exactamente una vez.

// esquema de las funciones de ambito
@OptIn(ExperimentalContracts::class)
inline fun <T, R> T.let(bloque: (T) -> R): R {
    contract { callsInPlace(bloque, InvocationKind.EXACTLY_ONCE) }
    return bloque(this)
}

fun configurar(): Config {
    val destino: String
    run { destino = leerDestino() }   // valido gracias al contrato
    return Config(destino)
}

flowchart TD
A[Llamada a una funcion] --> B{Declara contrato}
B -->|No| C[Caja negra: solo cuenta la firma]
B -->|Si| D{Que clase de clausula}
D -->|returns implies| E[Reinyecta un hecho sobre los argumentos]
D -->|callsInPlace| F[Informa de cuando y cuantas veces corre la lambda]
E --> G[El analisis de flujo continua en el llamante]
F --> G

Leer las fuentes y predecir el comportamiento

La forma más rentable de dominar esta materia es abrir las fuentes de la biblioteca desde el editor y mirar las primeras líneas de las funciones que usas a diario. La navegación a la declaración muestra el cuerpo real, y el bloque de contrato es siempre lo primero. Ese hábito responde de un vistazo preguntas que de otro modo exigen prueba y error: si una comprobación conservará el estrechamiento, si una lambda puede inicializar un val externo, si una función de validación sirve como guarda.

El inventario merece conocerse por familias antes que por nombres. Las comprobaciones de vacío y de blanco declaran la implicación negativa sobre el receptor. Las validaciones que lanzan declaran la implicación sobre el retorno normal. Las funciones de ámbito declaran la invocación en el sitio, unas con exactamente una vez y otras con como máximo una vez cuando el receptor es nulable. Las funciones de recursos y de sincronización declaran también invocación en el sitio, lo que explica que dentro de ellas se pueda inicializar y retornar como si fueran sintaxis del lenguaje.

Ese conocimiento se traduce en predicciones inmediatas sobre el propio código. La primera es que una guarda escrita con una comprobación de la biblioteca estrecha igual que la comparación manual, de modo que no hay motivo para preferir la forma explícita por desconfianza. La segunda es que la elección de función de ámbito deja de ser cuestión de gusto en cuanto hay una inicialización de por medio, porque solo los modos que garantizan una ejecución sirven para ello.

fun etiquetar(t: String?): String {
    if (t.isNullOrBlank()) return "vacio"
    return t.trim()                 // estrechado por el contrato, sin comparar a mano
}

fun abrir(ruta: String): Contenido {
    val leido: String
    java.io.File(ruta).bufferedReader().use { leido = it.readText() }
    return Contenido(leido)         // valido: use declara invocacion en el sitio
}

La tercera predicción es negativa y conviene tenerla presente. Una función que no declara contrato no informa de nada, por evidente que resulte su cuerpo al leerlo: el compilador no mira dentro. Por eso una comprobación propia, por bien escrita que esté, deja al llamante en la misma situación que una llamada a una librería ajena, y por eso conviene revisar las funciones auxiliares de validación que se acumulan en cualquier proyecto maduro.