Ámbito, doble receptor e importación

Una extensión declarada en el nivel superior de un archivo pertenece a un paquete y se importa como cualquier otra función. Una extensión declarada dentro de una clase no pertenece a un paquete: pertenece al cuerpo de esa clase, y solo existe mientras haya una instancia de ella disponible como receptor. Esa segunda forma es la que sostiene todos los constructores de DSL que has usado en Kotlin, y también la que produce la única situación del lenguaje donde una misma llamada se resuelve a la vez de forma estática y de forma virtual, cada mitad por un receptor distinto. Entender la mecánica del doble receptor y la de la importación es entender por qué las extensiones no ensucian el espacio global: no existe ningún espacio global de extensiones, solo ámbitos donde unas están y otras no.

Dos receptores en la misma función

Cuando una extensión se declara dentro de una clase, hay dos objetos implicados en cada llamada. El receptor de despacho es la instancia de la clase donde la extensión está declarada. El receptor de extensión es la instancia del tipo que precede al nombre. Dentro del cuerpo, ambos están accesibles; this sin cualificar es el de extensión, que es el más cercano, y al de despacho se llega con this cualificado por el nombre de la clase.

class Conexion(val host: String) {

    fun String.enviar(): Boolean {
        // this        -> el String, receptor de extension
        // this@Conexion -> la Conexion, receptor de despacho
        println("enviando ${this.length} bytes a ${this@Conexion.host}")
        return true
    }

    fun ejecutar() {
        "PING".enviar()      // legal: hay receptor de despacho
    }
}

fun main() {
    "PING".enviar()          // error: enviar no existe en este ambito
}

Esa restricción es el mecanismo entero de los DSL con receptor. La extensión enviar no contamina el proyecto: no se puede importar, no aparece en el autocompletado general y solo cobra existencia dentro de un cuerpo donde haya una Conexion disponible. Es la misma técnica con la que buildString te da un StringBuilder, con la que los constructores de HTML habilitan las etiquetas solo dentro de su bloque y con la que Compose limita ciertos modificadores a un contenedor concreto. with, apply y run sirven para introducir ese receptor de despacho desde fuera.

fun main() {
    with(Conexion("ejemplo.org")) {
        "PING".enviar()      // legal: with aporta el receptor de despacho
    }
}

Cuando los bloques se anidan hay varios receptores de despacho activos a la vez, y ahí es donde @DslMarker gana su sueldo: una anotación marcada con ella impide que un receptor externo se cuele implícitamente dentro de un bloque interno, obligando a cualificar con this si de verdad se quiere salir un nivel.

flowchart TB
call[llamada texto punto enviar dentro de Conexion] --> d[receptor de despacho igual a la Conexion]
call --> e[receptor de extension igual al String]
d --> vir[se resuelve de forma virtual por la clase real]
e --> est[se resuelve de forma estatica por el tipo declarado]

El receptor de despacho sí es virtual

Aquí está la asimetría que conviene tener grabada. Una extensión declarada dentro de una clase puede ser open y puede sobrescribirse, porque en ese caso lo que se sobrescribe es un miembro de la clase contenedora. Lo que sigue siendo estático es la elección por el tipo del receptor de extensión.

open class Base
class Derivada : Base()

open class Emisor {
    open fun Base.marcar() = "Emisor sobre Base"
    open fun Derivada.marcar() = "Emisor sobre Derivada"
    fun disparar(b: Base) = b.marcar()
}

class SubEmisor : Emisor() {
    override fun Base.marcar() = "SubEmisor sobre Base"
    override fun Derivada.marcar() = "SubEmisor sobre Derivada"
}

fun main() {
    println(Emisor().disparar(Derivada()))     // Emisor sobre Base
    println(SubEmisor().disparar(Derivada()))  // SubEmisor sobre Base
}

Las dos salidas dicen lo mismo desde ángulos distintos. Cambiar el receptor de despacho de Emisor a SubEmisor sí cambia la implementación elegida: ahí hay despacho virtual de verdad. Cambiar el objeto del receptor de extensión de Base a Derivada no cambia nada, porque dentro de disparar el parámetro está declarado como Base y esa decisión se tomó al compilar. Una misma línea, dos reglas de resolución opuestas.

Visibilidad, importación y organización

Una extensión de nivel superior obedece a los modificadores habituales, y cada uno traza un radio de alcance distinto. private la limita al archivo donde se declara, que es la herramienta correcta para los ayudantes que solo dan servicio a un módulo pequeño. internal la limita al módulo de compilación y es el valor por defecto razonable en una aplicación. public la ofrece a todo el mundo y, si el proyecto es una librería, la convierte en superficie pública con todo lo que eso implica en compatibilidad.

Pero la visibilidad solo dice quién puede verla; quién la ve lo decide la importación. Una extensión pública que nadie importa es, a efectos de resolución, inexistente en ese archivo.

import dominio.texto.esPalindromo                    // solo esta
import dominio.texto.*                               // todas las del paquete
import otro.paquete.formatear as formatearComoTabla  // alias para desambiguar

Hay una excepción cómoda: las extensiones declaradas en el mismo paquete que el archivo que las usa no necesitan importación. Es práctico dentro de un módulo y engañoso cuando se publica, porque el código de la librería compila sin importaciones y el de los clientes no. Al escribir los ejemplos de una API conviene ponerlos en otro paquete, precisamente para descubrir cuántas importaciones va a necesitar quien la use.