Convertir YAML a INI

Es una migración hacia atrás y casi siempre por la misma razón: el consumidor no se puede cambiar. Un servicio de Windows con años encima, un demonio cuyo analizador es anterior al equipo actual, un instalador, un emulador, un componente comprado que nadie mantiene. La configuración vive en YAML porque así se escribe hoy, y el programa que la tiene que leer no ha oído hablar de la sangría.

La conversión existe para ese caso concreto y no pretende ser una mejora. Lo que hace es sacar los valores del árbol y colocarlos en un formato de dos niveles, y lo que cuesta hacerlo conviene leerlo antes de fiarse del resultado, porque parte del coste no se ve en el fichero de salida sino en cómo lo interpreta el programa de destino.

INI tiene exactamente un nivel de agrupación: una cabecera entre corchetes y las claves que van dentro. YAML tiene tantos niveles como quieras sangrar. La conversión resuelve la diferencia recorriendo el árbol entero, construyendo una ruta con puntos para cada valor final y partiendo después cada ruta una sola vez: lo que hay antes del primer punto es la sección, todo lo demás es el nombre de la clave.

Así, un mapa llamado «base» que contiene «pool» que contiene «timeout» produce una sección «base» y una clave «pool.timeout». Todos los valores del documento sobreviven; lo que desaparece es la forma. Al otro lado, un analizador ve claves planas con puntos dentro y no tiene manera de saber cuáles de esos puntos eran anidamiento y cuáles formaban parte de un nombre.

Una secuencia de YAML no tiene equivalente en INI, así que cada elemento se convierte en una clave con su índice por nombre. Un guion de tres órdenes escrito como lista sale como tres claves terminadas en 0, 1 y 2 dentro de su sección, en el orden en que estaban escritas.

El orden se conserva, que es la parte que importa, pero la convención es nuestra y no un estándar. Algunos analizadores de INI entienden las claves numeradas como una lista, la mayoría no, y unos cuantos esperan en su lugar un nombre de clave repetido. Comprueba qué hace con ellas el programa que va a leer el fichero antes de dar por hecho que la lista ha sobrevivido en algún sentido útil: una secuencia ordenada que llega como tres ajustes independientes se ha convertido bien y se ha entendido mal.

Una configuración de dos niveles de profundidad, con valores simples y sin textos de varias líneas, se convierte perfectamente y no necesita ninguna edición posterior. Muchísimas configuraciones de aplicación tienen exactamente esa forma, y por eso el par existe.

Una lista de mapas no. Una secuencia de definiciones de servidor, cada una con su máquina y su puerto, sale como una serie de claves numeradas con dos puntos dentro del nombre, todas dentro de una misma sección. Es una codificación fiel de los datos y un fichero de configuración ilegible. Si tu origen tiene esa forma, el consejo honesto es que INI no es un destino adecuado y que lo que salga vas a tener que reescribirlo de todas formas.

Un escalar en bloque —una barra vertical con un bloque sangrado debajo, que es como cualquier fichero de integración continua guarda un guion— se analiza como una sola cadena con saltos de línea dentro. Hasta el 9 de agosto de 2026 el escritor la emitía tal cual, así que esos saltos se convertían en saltos reales: la primera línea del guion quedaba tras el signo igual y todas las demás se quedaban solas. Al leer el fichero de vuelta esas líneas se descartaban, y cualquiera de ellas que pareciera una cabecera entre corchetes abría una sección que no estaba en el YAML, llevándose dentro la clave siguiente.

Ahora el escritor entrecomilla los valores de varias líneas y escribe cada salto como una barra invertida seguida de una ene, así que el guion se queda en una línea, sigue siendo una sola entrada y vuelve intacto por este mismo conversor. Lo que no ha cambiado es el destino: los dialectos de INI no se ponen de acuerdo sobre los escapes, y un analizador que trate la barra invertida como un carácter normal te devolverá esos dos caracteres en lugar de un salto.

El entrecomillado es deliberadamente selectivo, porque un INI en el que todos los valores llevan comillas no es lo que nadie espera abrir. Se entrecomilla lo que de otro modo no sobreviviría a volver a leerse: un valor con un salto de línea dentro, uno con espacios al principio o al final, y uno que ya venía rodeado de comillas.

Sólo se escapan tres caracteres: la barra invertida, el salto de línea y el retorno de carro. El primero tiene que escaparse porque, si no, una ruta de Windows escrita con barras invertidas volvería con un salto de línea dentro. Y como los valores sólo se desescapan cuando venían entrecomillados, una línea escrita a mano con una ruta sin comillas se conserva tal como está: es el caso más común en un fichero INI y era el que había que no romper.

Una clave de YAML sin nada detrás se analiza como nulo y se escribe como la clave, el signo igual y nada más. INI no sabe expresar la diferencia entre una clave sin asignar y una cadena vacía, así que las dos vuelven como cadena vacía cuando alguien lee el fichero.

Si esa distinción le importa al programa de destino, hay que codificarla de otra manera: un valor centinela acordado, o directamente no escribir la clave. Es una de las decisiones que conviene tomar antes de generar el fichero definitivo, porque descubrirla después obliga a repasar todas las claves vacías a mano.

Los booleanos salen como las palabras true y false, que es lo que decía el origen. No es lo que espera todo consumidor de INI: buena parte de la configuración heredada de Windows y algunos intérpretes usan On y Off, y un analizador que busque esas palabras va a tratar true como una cadena que no reconoce, normalmente sin quejarse.

Los números salen tal cual, sin comillas, y quien lea el fichero decidirá si son números o texto: INI no lleva tipos. Eso significa que un código con ceros por delante o un identificador largo dependen por completo del analizador de destino, y que revisar esos valores en la salida es más barato que depurar por qué el programa arrancó con una configuración ligeramente distinta a la que creías.

Un valor simple en la raíz del YAML —una versión, un nombre, un interruptor único— no tiene padre que se convierta en sección. Esos valores se escriben los primeros, antes de cualquier cabecera entre corchetes, que es la convención habitual para un bloque global y la que entienden la mayoría de los analizadores.

Los bloques de sección van después, en el orden en que aparecían sus claves en el YAML. Ese orden importa si el fichero lo va a revisar una persona y no sólo una máquina, porque hace que la salida se lea más o menos en la misma secuencia que el origen y que dos conversiones del mismo fichero se puedan comparar de un vistazo.

Un YAML con separadores de tres guiones contiene varios documentos, y un fichero INI describe un solo conjunto de ajustes. El analizador se detiene con un mensaje que dice que el origen contiene varios documentos e indica la línea y la columna donde empieza el segundo, en lugar de elegir uno por su cuenta.

Es deliberado. Quedarse en silencio con el primer documento produciría una configuración a la que le falta la mayor parte de sí misma y que además arranca, que es la peor combinación posible. Parte el fichero por los separadores y convierte el documento que necesites.

Se pierden todos. Los dos formatos los admiten, el analizador los descarta al leer y el escritor no tiene de dónde sacarlos. La explicación encima de un tiempo de espera es justamente el tipo de línea que hacía que mereciera la pena leer el YAML, y no está en el INI.

Si el fichero resultante va a vivir años, el momento de volver a escribirlos es justo después de convertir, con el YAML todavía abierto al lado. Dentro de seis meses nadie va a recordar por qué un valor está donde está, y un INI sin comentarios delante de un programa antiguo es la definición exacta de una configuración que nadie se atreve a tocar.

La conversión merece la pena cuando el YAML es grande, plano y aburrido. No la merece cuando el origen es pequeño: veinte ajustes se teclean antes de lo que se tarda en convertir y luego reparar, y teclearlos obliga a leer cada valor una vez, que en una configuración a punto de ser confiada a un programa viejo es una ventaja y no un coste.

Tampoco es la herramienta cuando el destino espera un dialecto concreto: valores siempre entrecomillados, booleanos como On y Off, listas separadas por comas en una sola clave o claves repetidas. Convierte para sacar los valores del árbol y después ajústalos a la forma del analizador al que de verdad estás alimentando. Todo esto ocurre dentro de la pestaña, así que una configuración con credenciales dentro no sale de tu equipo en ningún momento.