Cómo las tablas TOML se convierten en objetos JSON: [tabla], [[matriz]] y claves de puntos Los encabezados de

¿De dónde vino el anidamiento? — un archivo TOML de apariencia plana convertido a JSON profundamente anidado y los encabezados que lo causaron

Un archivo TOML puede parecer casi plano porque los corchetes llevan el anidamiento. `[a.b.c]` abre tablas intermedias, por lo que `d = 1` debajo se convierte en `{"a":{"b":{"c":{"d":1}}}}`. Las llaves JSON hacen visible una jerarquía que TOML expresa a través de la ruta de la tabla activa.

ToolAcre delega el análisis de sintaxis a smol-toml y luego normaliza los valores que JSON no puede transportar. Esto no es una reescritura basada en líneas. Las tablas, las claves de puntos y las matrices de tablas se convierten en objetos y matrices comunes antes de la serialización JSON, razón por la cual su ortografía y comentarios no están disponibles en la salida.

encabezados [tabla]: cómo un encabezado abre un objeto anidado y cómo [a.b.c] crea objetos intermedios implícitamente

Un encabezado de un solo corchete abre una tabla. `[owner]` dirige las siguientes asignaciones a `owner`; `[owner.contact]` crea o ingresa el objeto de contacto anidado. Los objetos intermedios no necesitan tener encabezados separados. Su existencia se desprende de los segmentos de ruta en el encabezado.

Las asignaciones anteriores a cualquier encabezado permanecen en la raíz. Las tablas posteriores no las mueven retroactivamente. Al revisar JSON convertido, siga la ruta de propiedad completa en lugar de la distancia física entre líneas: la tabla actual de TOML permanece activa hasta que otro encabezado la cambie.

[[matriz de tablas]]: por qué un encabezado repetido de doble corchete agrega objetos a una matriz y el orden que conserva

Un encabezado de doble corchete agrega una tabla a una matriz. Dos secciones `[[server]]` se convierten en `server: [{...},{...}]` en orden de origen. Los campos debajo de cada encabezado pertenecen a ese miembro de la matriz hasta que comienza otro encabezado, lo que hace que la configuración repetida sea explícita en JSON.

El orden dentro de la matriz son datos y se conservan. La presentación de la clave del objeto se puede ordenar más tarde cuando se selecciona la opción, pero los miembros de la matriz nunca se reordenan. Confundir los dos cambiaría la prioridad del servidor o la secuencia de complementos en lugar de simplemente formatear un documento.

Claves punteadas y tablas en línea: a.b = 1 y { x = 1 } como dos formas más de expresar el mismo anidamiento

Las asignaciones de puntos proporcionan otra notación de ruta: `a.b.c = true` produce la misma forma de objeto anidado que los encabezados de tabla correspondientes. Las tablas en línea como `point = { x = 1, y = 2 }` se convierten en objetos anidados inmediatamente. Estas formas pueden describir árboles similares y al mismo tiempo verse muy diferentes para un revisor.

JSON registra solo las claves y los valores resultantes, no la notación TOML que los creó. Por lo tanto, volver a convertir no puede restaurar la elección original entre encabezados, claves de puntos y tablas en línea. El escritor TOML elige su propia serialización válida del árbol.

Los tipos que se transfieren y los tipos que no (enteros, flotantes, booleanos y cadenas se asignan directamente); las fechas y horas se convierten en cadenas y JSON null no tiene fuente TOML

Cadenas, enteros seguros, flotantes, valores booleanos, matrices y tablas se asignan directamente. Los cuatro tipos temporales de TOML no: fecha-hora compensada, fecha-hora local, fecha local y hora local se convierten en sus cadenas de origen tipo RFC 3339, y una advertencia nombra cada ruta y tipo. Posteriormente, el escritor cita esas cadenas en lugar de recrear tokens de fecha y hora.

Los enteros de 64 bits con signo de TOML pueden exceder el rango de enteros seguros de JavaScript. smol-toml devuelve valores como BigInt cuando es necesario; ToolAcre los convierte en cadenas decimales y advierte en lugar de redondear los dígitos. Esto preserva la ortografía a costa de cambiar el tipo JSON.

Ejemplo resuelto: un pyproject.toml — [proyecto], [project.optional-dependencies] y una lista [[tool.plugins]] convertida a JSON con cada nivel rastreado

Pruebe `name = "demo"`, `[project]`, `dependencies = ["a", "b"]`, `[project.optional]`, `test = ["vitest"]`, luego dos tablas `[[tool.plugins]]` con nombres distintos. JSON coloca el nombre en la raíz, anida el proyecto y es opcional, y produce una matriz de complementos debajo de la herramienta.

Agregue `released = 1979-05-27` y `huge = 9223372036854775807`. El primero se convierte en la cadena `1979-05-27`; el segundo se convierte en una cadena decimal. Ambas advertencias identifican las rutas modificadas, lo que hace que los tipos que no son JSON sean revisables en lugar de permitir la coerción silenciosa de Fecha o Número.

Lo que esto no cubre: convertir JSON nuevamente al TOML idiomático con una agrupación de encabezados sensata, lo que implica opciones de estilo que ninguna regla determina por completo

JSON-to-TOML se admite para un objeto raíz, pero no recrea comentarios o opciones idiomáticas del autor. Se omiten las claves con valores nulos; null dentro de una matriz se convierte en una cadena vacía para preservar las posiciones. Se rechaza una matriz raíz, escalar o nula porque un documento TOML debe ser una tabla.

Ese comportamiento corrige la implicación del esquema de que la conversión inversa está fuera del alcance. El convertidor escribe TOML, pero la fidelidad del estilo está fuera de su promesa. La distinción es importante: la serialización admitida no es lo mismo que restaurar el archivo fuente byte por byte o elegir el diseño que preferiría un mantenedor.

Se admite la escritura JSON en TOML, pero los comentarios, los tipos de fecha y hora y el estilo del autor no regresan.

Lea los encabezados TOML como rutas y los corchetes dobles como operaciones de adición. La vista JSON es valiosa para rastrear el árbol resultante, mientras que las advertencias exponen fechas y números enteros anchos que cruzan un límite de tipo. No llame a la operación sin pérdidas cuando aparezca cualquiera de las advertencias.

Para la migración de la configuración, mantenga el original junto a la salida convertida. Primero verifique los valores y luego edite la organización TOML para los lectores y la herramienta de destino. Los convertidores de sintaxis realizan el paso mecánico de análisis y escritura; no puede decidir la agrupación específica del proyecto, las claves aceptadas o si la aplicación admite ese archivo.

Una comparación final debe separar tres preguntas que son fáciles de confundir. En primer lugar, ¿sobrevivieron los valores analizados? En segundo lugar, ¿algún tipo exclusivo de TOML se convirtió en una cadena JSON o desapareció algún nulo? En tercer lugar, ¿el TOML recién serializado está organizado de una manera que un mantenedor pueda entender? Los dos primeros se pueden comparar con valores y advertencias; el tercero necesita una revisión humana. Mantener esas comprobaciones separadas evita que una serialización técnicamente válida se llame migración fiel cuando sus tipos o estructura de autor cambiaron.