Convertir INI a YAML

Una aplicación que llevaba años configurándose por SSH cambia de casa. El archivo INI que alguien editaba en el servidor tiene que entrar ahora en un repositorio, donde se revisa en una petición de cambios en lugar de tocarse en caliente, y el sistema que lo va a leer espera YAML.

Es un cambio de sitio más que un cambio de formato. Lo que se gana es que cada modificación quede firmada y comentada en el historial; lo que se arriesga es que algún valor signifique algo distinto al otro lado. Esta página trata sobre lo segundo, porque lo primero se resuelve solo.

Cada cabecera entre corchetes se convierte en una clave de primer nivel y sus ajustes quedan sangrados dos espacios por debajo. Las claves escritas antes de la primera cabecera se quedan arriba, junto a esos bloques. La sangría son espacios: YAML prohíbe el tabulador para sangrar, así que un conversor que lo usara devolvería un archivo que ningún analizador acepta.

El resultado es un documento YAML completo, no un fragmento. Conviene tenerlo presente cuando el destino es un archivo de valores o un conjunto de variables, porque lo habitual es querer todo eso anidado un nivel más abajo bajo una clave propia, y sangrar un documento que ya se sabe correcto es más fácil que razonar sobre un trozo suelto.

Los archivos INI dicen `On` y `Off` mucho más a menudo que `true` y `false`. Lo hace `php.ini`, lo hace media docena de demonios y lo hacía casi todo lo que se configuraba en Windows. El lector de aquí no convierte esas palabras en booleanos, así que siguen siendo texto, y el escritor las deja sin comillas: `engine: On`.

Que esa línea signifique una cadena o un booleano depende de qué versión de YAML implemente quien la lea. YAML 1.2, que es la que implementa el analizador de esta página, dice que es la cadena «On». YAML 1.1 dice que es verdadero, y PyYAML implementa 1.1, con lo que todo el instrumental escrito en Python la leerá como booleano. Lo mismo vale para `yes`, `no`, `y` y `n`.

La solución son las comillas y hay que ponerlas a mano, porque el conversor no puede saber cuáles de tus `On` eran interruptores y cuáles el nombre de algo. Escribe `engine: "On"` si quieres la cadena en todos los analizadores, o `engine: true` si quieres el booleano en todos. Las dos formas se leen igual bajo 1.1 y bajo 1.2, que es la única propiedad que merece la pena perseguir.

Hazlo como una revisión deliberada y no arreglando lo que se rompa. Un booleano leído como cadena casi siempre resulta verdadero y por tanto queda encendido en silencio; una cadena leída como booleano suele fallar ruidosamente contra un esquema. El camino peligroso es el silencioso: un ajuste que desactivaste vuelve activado y nada falla hasta que falla.

El tipado ocurre en el lector. Todo valor que se pueda interpretar como número finito pasa a número, `true` y `false` pasan a booleano, y el resto se queda como texto. Cuando el escritor de YAML entra en escena, la decisión ya está tomada y no hay opción que la cambie.

Tres casos cambian de significado por el camino. Una versión anclada como `1.0` sale como `1`. Un modo de archivo escrito `0755` sale como `755`, que no es el mismo permiso. Una máscara `0x1F` sale como `31`. En cambio los valores con unidad pegada aguantan: `128M` sigue siendo `128M` y `30s` sigue siendo `30s`.

Aquí hay una asimetría que conviene conocer si el archivo se escribió en español. Un valor como `precio=1,50` no se interpreta como número, porque la conversión numérica del navegador sólo entiende el punto decimal, así que llega al YAML tal cual, como texto. El mismo valor escrito `1.50` sí se vuelve número y pierde el cero final.

Lo mismo ocurre con `hora=08:00`, con `ip=127.0.0.1` y con cualquier referencia con guiones: nada de eso se lee como un número, y por tanto nada de eso se toca. La consecuencia práctica es que los archivos escritos con convenciones españolas sufren menos esta conversión que los escritos con punto decimal, lo cual es una de las pocas veces que la costumbre local juega a favor.

Una sección escrita `[tool.pytest]` o `[correo.smtp]` produce una única clave con ese nombre literal, no dos niveles anidados. El lector toma todo lo que hay entre corchetes como un nombre entero, que es la única lectura defendible: en `php.ini` los puntos forman parte del nombre de secciones y de claves por todas partes.

YAML admite esa clave sin comillas, así que el archivo es válido y se lee bien. Tampoco es lo que espera una plantilla de despliegue, donde `correo.smtp.host` suele ser tres niveles. Partirlo es una edición manual y debe serlo, porque al hacerlo estás decidiendo algo que el archivo de origen nunca dijo.

Las configuraciones que se armaron pegando un archivo de entorno detrás de uno base terminan con la misma cabecera dos veces. El lector crea una sección nueva y vacía cada vez que encuentra una cabecera, así que sólo sobrevive la última aparición y la anterior desaparece sin decir nada. La misma regla del último gana se aplica a una clave repetida dentro de una sección.

Conviene comprobarlo antes de migrar y no después, porque lo que sale es un YAML impecable al que sencillamente le faltan ajustes, y una clave ausente en un despliegue suele manifestarse como un valor por defecto aplicado en silencio y no como un error. Busca cabeceras duplicadas en el INI antes de soltarlo aquí.

YAML admite comentarios y el INI también, y ninguno de los tuyos sobrevive. Las líneas que empiezan por punto y coma o por almohadilla se saltan al leer y nada las vuelve a escribir, así que un archivo que era mitad explicación llega convertido en puros ajustes.

En una configuración editada durante años esos comentarios son la memoria de la casa: la nota que dice por qué se subió un tiempo de espera para un informe concreto, el bloque comentado durante una incidencia y nunca retirado, las iniciales junto a un valor que nadie quiere tocar. Guarda el INI original en el repositorio, en el mismo commit que el YAML. No cuesta nada y es el único sitio donde ese razonamiento sigue existiendo.

Hay dos formas de perder una línea en silencio y conviene conocerlas. Una línea que no contenga un signo de igual se descarta sin más, lo cual es lo correcto para las líneas en blanco y no lo es tanto para una clave escrita a medias. Y como las líneas que empiezan por punto y coma o por almohadilla se tratan como comentarios, una clave que empiece por uno de esos caracteres desaparece con ellos.

A cambio, el orden se respeta escrupulosamente: nada en la conversión ordena claves ni secciones, así que el YAML sale en el mismo orden en que estaba escrito el INI. Eso hace que comparar los dos archivos lado a lado sea un ejercicio razonable, y es la mejor comprobación disponible: si el número de claves no coincide, alguna de las dos trampas anteriores se ha llevado una.

Tanto el lector como el escritor son JavaScript corriendo en esta página, de modo que el archivo no se envía a ninguna parte. Es una propiedad general de las conversiones de datos de este sitio y este par es donde se gana el sueldo: el INI que se está migrando de un servidor viejo es, con mucha frecuencia, el que lleva dentro la contraseña de la base de datos, las credenciales de correo y alguna clave de API.

El techo gratuito es de 100 MB por archivo, una cifra que ninguna configuración se acerca a rozar. En la práctica la conversión es instantánea y lo único que conviene hacer despacio es leer la salida, porque en cuanto esos secretos entren en un YAML versionado se quedan en el historial del repositorio para siempre.

Si la aplicación lee INI y va a seguir leyéndolo, convertir es trabajo sin retorno. YAML aporta anidamiento, listas, comentarios revisables y un validador, y nada de eso ayuda a un programa cuyo analizador espera corchetes y signos de igual. La migración vale la pena cuando la configuración se muda a un sistema que habla YAML de forma nativa, no cuando el archivo simplemente parece antiguo.

La otra razón honesta para no convertir es el tamaño. Un archivo con tres secciones y veinte claves se reescribe a mano más rápido de lo que se convierte y se reordena, y reescribirlo obliga a leer cada valor una vez, que es exactamente lo que hace falta. Usa el conversor cuando el archivo sea lo bastante grande como para que leerlo entero a mano sea la opción propensa a errores.