Convertir XML a TOML

Cada elemento con hijos se convierte en una tabla, escrita como una cabecera entre corchetes que nombra la ruta completa separada por puntos. Un elemento a tres niveles de profundidad produce una sola cabecera con tres nombres dentro, no tres bloques anidados, porque TOML expresa la profundidad en la cabecera y no en el sangrado.

Dentro de cada tabla salen primero los valores simples y después las tablas anidadas, que es el único orden que TOML permite: todo lo que hay bajo una cabecera le pertenece hasta que aparece la siguiente. Eso significa que la salida no se lee en el mismo orden que el XML, y en una configuración con muchos elementos pequeños la reordenación es considerable. Es una reordenación y no un cambio: ningún valor acaba en una ruta distinta de la que tenía.

Esta es la parte de la conversión que no hay que reparar. Dos o más elementos hermanos con la misma etiqueta se convierten en un array de tablas de TOML, con la cabecera de doble corchete escrita una vez por elemento y en el orden del documento. Una lista de dependencias, una de servidores, una de reglas: todas aterrizan en la forma que habría tenido una configuración escrita directamente en TOML.

Debajo sigue funcionando la vieja pega del XML. Una sola aparición de un elemento repetible no es un array, así que se convierte en una tabla normal con cabecera de un solo corchete. Convierte un archivo con una entrada y el mismo archivo con dos, y las dos salidas se diferencian estructuralmente. Si la configuración se genera o se guarda en un repositorio, esa es una diferencia que conviene entender antes de que aparezca en una revisión.

Las claves desnudas de TOML solo admiten letras, dígitos, guiones bajos y guiones. Los atributos llegan del analizador como claves que empiezan por arroba, el texto propio de un elemento bajo una clave llamada #text, y una declaración de espacio de nombres como algo del estilo de @xmlns:soap. Todas se escriben entrecomilladas, lo cual es TOML correcto y queda tan raro como suena.

Y también son un aviso. Una clave entrecomillada es el conversor diciéndote que ese nombre viene de la maquinaria del XML y no de tu configuración, y casi todas deberían renombrarse: un atributo @value pasa a ser una clave value normal, una clave @xmlns se borra, una clave #text pasa a llamarse como aquello que el elemento realmente contenía. Haz esa pasada una vez, enseguida, mientras todavía recuerdas qué significaba el XML.

Un documento TOML es en sí mismo una tabla, y un documento XML tiene exactamente un elemento raíz, así que la configuración entera aparece bajo una única cabecera con el nombre de esa raíz. Un archivo cuya raíz sea configuracion produce una tabla configuracion que contiene absolutamente todo.

Promocionar el contenido es una edición mecánica: borra la primera cabecera y quita ese segmento de todas las demás cabeceras del archivo. Merece la pena hacerlo en vez de convivir con ello, porque cada ruta de la configuración se acorta un nivel y un archivo TOML se lee por sus cabeceras. Hacerlo a mano además obliga a una pasada completa sobre el archivo, que en una migración es tiempo bien invertido.

TOML no tiene valor nulo, y convertir desde formatos que sí lo tienen —YAML es el caso clásico— hace que algunas claves se esfumen cuando su valor está vacío. Aquí eso no puede pasar, porque XML tampoco tiene nulo. Un elemento vacío y un elemento autocerrado significan lo mismo y los dos se convierten en una cadena vacía, escrita como dos comillas.

Así que la garantía de esta dirección es más fuerte que la de sus vecinas: todo elemento que tenía valor en el XML tiene clave en el TOML. Las cadenas vacías son fáciles de pasar por alto en un archivo largo, eso sí, de modo que si la migración es también la ocasión de eliminar ajustes que ya no usa nadie, buscar esos pares vacíos en la salida es la forma más rápida de encontrarlos.

TOML lleva la fecha y la hora en su especificación básica —fechas con desplazamiento, fechas y horas locales, fechas sueltas y horas sueltas— y un analizador las devuelve como fechas y no como texto. Es una de las razones reales para migrar a este formato y no a otro.

Un valor de XML es texto, así que una fecha en el origen llega como una cadena entrecomillada y se queda así. Quitarle las comillas en la salida es lo que la convierte en una fecha TOML de verdad, y cuesta un minuto. Merece la pena vigilar también el caso inverso: un valor escrito 1.0 en el XML se analiza como número y se escribe como el entero 1, con lo que una versión ha pasado a ser un entero y ha perdido su forma. Volver a entrecomillarlo es el arreglo.

Un elemento que contiene varias líneas —una descripción, un bloque de licencia, un fragmento de guion incrustado— se convierte en una única cadena básica de TOML con barra invertida y ene donde estaban los saltos. Es correcto, es ilegible, y anula precisamente el motivo de mudarse a un formato que la gente edita a mano.

TOML tiene una sintaxis de cadena multilínea con comillas triples que sostiene ese valor de forma legible, y el escritor no la usa. Busca los valores que traigan escapes y reescribe cada uno como un bloque de comillas triples. En la mayoría de las configuraciones hay uno o dos; en una llena de texto incrustado, eso es una señal de que ese contenido quiere vivir en su propio archivo y no dentro de un archivo de ajustes.

Los comentarios se descartan al analizar, aunque los dos formatos los admitan, así que las explicaciones del archivo viejo no aparecen en el nuevo. Los espacios de nombres dejan de significar nada en cuanto los prefijos se convierten en caracteres dentro de una clave. Y el esquema desaparece: un XML se puede validar contra un XSD antes de que arranque una aplicación, y TOML no tiene lenguaje de esquema en su especificación.

Esa última es la que hay que aceptar conscientemente. TOML es más fácil de leer, más fácil de escribir a mano e inequívoco sobre los tipos, y renuncia a poder rechazar mecánicamente una configuración malformada. Si el XML se estaba validando de verdad en tu compilación, estás quitando una comprobación, y reponerla con una validación al arrancar la aplicación forma parte de la migración y no es un añadido opcional.

La comparación que casi todo el mundo hace en este punto es con YAML, y hay una diferencia que decide bastantes discusiones: los tipos con nombre de fecha y hora están en el núcleo de TOML, mientras que en YAML pertenecen a una biblioteca de tipos de la versión 1.1 y no al esquema básico de la 1.2, de modo que lo que te devuelve un cargador depende de qué cargador sea.

Lo demás es de estilo y de riesgo. YAML expresa mucho más y por eso tiene muchas más formas de sorprenderte con el sangrado y con valores que parecen texto y llegan como otra cosa. TOML expresa menos y a cambio se lee igual en todas partes. Desde un XML, además, el mapeo estructural es mejor hacia TOML, porque los elementos repetidos y los arrays de tablas encajan de forma directa.

Lo que te da la herramienta es cada valor del XML, en la tabla correcta, con el nombre correcto en la mayoría de los casos y con un nombre entrecomillado y evidentemente equivocado en el resto. Eso es un buen punto de partida y no un archivo de configuración terminado.

El trabajo posterior es corto y no es opcional: quitar la tabla raíz, renombrar las claves con arroba y #text, desentrecomillar las fechas, reescribir los valores de varias líneas y traerte los comentarios del archivo original. Una hora sobre un archivo grande. Saltárselo produce una configuración que funciona y que nadie que la lea dentro de un año va a creer que se escribió a propósito.

Tanto el analizador de XML como el escritor de TOML son JavaScript que carga esta página bajo demanda, así que la configuración no se sube a ningún sitio. En este par eso pesa más de lo normal, porque los archivos de configuración antiguos son justo donde acaban las cadenas de conexión, los usuarios de servicio y algún secreto que alguien dejó ahí hace años.

Se admiten archivos de hasta 100 MB y cien por tanda, que para configuraciones es un techo que no vas a ver nunca. Aun así, revisa la salida antes de pegarla en un repositorio: si el XML llevaba credenciales dentro, el TOML también las lleva, y ahora en un archivo que resulta cómodo de leer.