DSLs en la práctica: leer la magia

Un DSL bien hecho tiene un efecto secundario indeseado: hace que su usuario deje de leer. Quien escribe un fichero de Gradle o una configuración de Ktor acaba tratando cada bloque como una fórmula aprendida de memoria, copiada de una respuesta de internet y modificada por aproximación, y en cuanto algo falla no tiene ningún modelo mental al que acudir porque nunca hubo modelo, solo imitación. La cura no consiste en memorizar más fórmulas sino en descubrir que ahí dentro no hay nada nuevo: cada llave, cada nombre suelto y cada paréntesis ausente corresponde a una construcción concreta del lenguaje que ya conoces, y una vez que se tiene el catálogo completo, cualquier DSL ajeno se puede desarmar en unos minutos con el propio entorno de desarrollo. Esta lección es ese catálogo y ese método, aplicados a los dos DSLs que más manos han pasado por ellos.

Gradle, línea a línea

El fichero de construcción de Gradle en su variante Kotlin es el DSL más leído del ecosistema y el peor entendido. Su apariencia de formato de configuración es completamente engañosa: es un script que se compila, y cada bloque es una llamada a una función cuyo parámetro es un tipo función con receptor.

plugins {
    kotlin("jvm") version "2.1.0"
}

dependencies {
    implementation("io.ktor:ktor-server-core:3.0.0")
    testImplementation(kotlin("test"))
}

tasks.withType<Test> {
    useJUnitPlatform()
}

El bloque plugins es una llamada a una función cuyo receptor es un contenedor de especificaciones de plugin. Dentro, kotlin("jvm") es una función ordinaria que devuelve un objeto, y version "2.1.0" no es sintaxis de versión sino una función infix invocada sobre ese objeto: por eso no hay punto ni paréntesis. El bloque dependencies recibe como receptor el manejador de dependencias, y aquí ocurre la parte que más desconcierta, porque implementation no está declarada en ninguna clase del propio Gradle. Es un accesor de tipos generado: Gradle inspecciona las configuraciones que existen en el proyecto tras aplicar los plugins y genera código Kotlin con una función de extensión por cada una. El DSL, literalmente, cambia de vocabulario según los plugins aplicados, y por eso el autocompletado solo lo conoce después de sincronizar el proyecto.

La línea de las tareas añade la última pieza. En tasks.withType<Test> { ... } conviven un parámetro de tipo reificado, que permite a la función conocer en ejecución la clase pedida sin recibirla como argumento, y un bloque de configuración cuyo receptor es cada tarea seleccionada. Dentro, useJUnitPlatform() es un método corriente de esa tarea. No queda ni un solo elemento de sintaxis especial en toda la línea.

El mismo repertorio con otra ropa

Cambiar de DSL no significa cambiar de mecanismos. La configuración de un servidor de Ktor tiene una apariencia muy distinta de la de Gradle y está construida exactamente con las mismas piezas.

fun Application.modulo() {
    install(ContentNegotiation) {
        json()
    }
    routing {
        get("/salud") {
            call.respondText("ok")
        }
        route("/api") {
            post("/pedidos") { /* ... */ }
        }
    }
}

Merece la pena detenerse en la primera línea antes de entrar en el bloque, porque contiene ya el mecanismo entero. La función se declara como extensión de Application, de modo que todo su cuerpo tiene ese objeto como receptor y install y routing son métodos suyos disponibles sin cualificar. La llamada install recibe un objeto que identifica el plugin y un bloque cuyo receptor es el tipo de configuración de ese plugin concreto, lo cual explica que dentro solo aparezcan las opciones pertinentes y que json() no exista en ningún otro sitio. En routing, el receptor es un constructor de rutas, y route anida creando un receptor hijo del mismo tipo: por eso la anidación es arbitrariamente profunda con una sola clase. Dentro de get, en cambio, el receptor ya no es el constructor de rutas sino el contexto de la petición, que es de donde sale call.

El contraste entre ambos ejemplos enseña algo que ninguna documentación dice de frente. Gradle y Ktor no comparten ni un solo tipo, ni un plugin de compilador, ni una convención de nombres, y sin embargo se leen igual porque están hechos con el mismo puñado de construcciones. Cuando dos DSLs de dominios completamente ajenos producen la misma sensación de sintaxis dedicada, la explicación no puede estar en el dominio: está en el lenguaje, y es enumerable.

flowchart TD
A[Una linea de DSL que parece magia] --> B{Hay llaves detras del nombre}
B -- Si --> C[Es una lambda final: mira el tipo del parametro]
C --> D{El tipo lleva punto antes de los parentesis}
D -- Si --> E[Hay receptor: el vocabulario de dentro es ese tipo]
D -- No --> F[Sin receptor: dentro solo hay it y el ambito externo]
B -- No --> G{Falta el punto entre dos nombres}
G -- Si --> H[Es una funcion infix]
G -- No --> I{Se invoca un objeto como si fuera funcion}
I -- Si --> J[Hay un operador invoke]
I -- No --> K[Es una llamada ordinaria o un delegado]

El catálogo cerrado

Todo lo que produce apariencia de sintaxis nueva en Kotlin cabe en una lista corta, y esa lista no ha crecido en años. Reconocerla entera convierte la lectura de cualquier DSL en un ejercicio mecánico.

// Lambda final fuera de los parentesis: quita el aspecto de llamada
medir("carga") { cargar() }

// Tipo funcion con receptor: cambia el vocabulario de dentro
fun html(bloque: HtmlBuilder.() -> Unit) { /* ... */ }

// Funcion infix: elimina el punto y los parentesis
infix fun String.version(v: String) { /* ... */ }

// Operador invoke: permite llamar a un objeto como si fuera funcion
operator fun Repositorio.invoke(id: Int) { /* ... */ }

// Extension: anade vocabulario a un tipo ajeno sin tocarlo
fun DependencyHandler.implementation(dep: String) { /* ... */ }

// Delegacion de propiedad: convierte una declaracion en una llamada
val version: String by extra

// Tipo reificado: la clase viaja sin escribirla como argumento
inline fun <reified T> tareas(bloque: T.() -> Unit) { /* ... */ }

El método: tres preguntas y un atajo del entorno

Ante cualquier línea incomprensible de un DSL ajeno, la investigación siempre es la misma y no requiere documentación. La primera pregunta es quién es el receptor de este bloque, y se responde yendo a la declaración de la función que lo abrió y leyendo el tipo de su último parámetro; ese tipo es el diccionario completo de lo que puede escribirse dentro. La segunda es de dónde sale este nombre, y se responde saltando a su declaración con el atajo de navegación del entorno, que distingue en el acto entre un miembro, una extensión y un accesor generado. La tercera es qué construcción produce esta forma extraña, y se responde con el catálogo anterior: ausencia de punto significa infix, invocación de un objeto significa invoke, una declaración con by significa delegación.

El ejercicio termina siempre igual y conviene hacerlo al menos una vez con papel: reescribir la línea sin ningún azúcar, con todos los receptores escritos y todos los paréntesis puestos. Si la versión desnuda compila y hace lo mismo, la comprensión es correcta; si no compila, el error señala justamente la parte que se había entendido mal.

// Como se escribe
tasks.withType<Test> { useJUnitPlatform() }

// Que significa, con todo explicito
tasks.withType(Test::class.java, { tarea: Test -> tarea.useJUnitPlatform() })

Hay un atajo adicional que resuelve los casos difíciles de un golpe. Casi todos los entornos ofrecen una acción que muestra la forma desazucarada de una expresión o que abre la declaración compilada del descriptor; en su defecto, escribir explícitamente el receptor delante del nombre y comprobar si el código sigue compilando confirma en un segundo contra quién se estaba resolviendo. Si al anteponer this@routing la línea sigue siendo válida, ese era el receptor; si deja de compilar, era otro.