La primera vez que TOML me mordió, no era la sintaxis. Fue el orden. Tenía un objeto de configuración JSON de un antiguo servicio de Node, lo quería como config.toml para una reescritura de Rust, hice lo que todos hacen la primera vez: escribí las tablas a mano. Diez minutos más tarde, el analizador estaba lanzando un error que no entendí, señalando una línea que se veía perfectamente bien. El problema eran tres teclas debajo de a [table] encabezado que pertenecía encima. TOML tiene una regla que JSON no tiene, y una vez que lo tropiezas, nunca lo olvidas.
yo construyo Toolz.dev, y envié un largo estante de convertidores de formato allí, así que escribí el convertidor JSON a TOML para eliminar toda esa categoría de error. Pegas JSON, obtienes TOML que vuelve a analizar los mismos datos y el pedido se maneja por ti. Esta guía es lo que desearía haber leído esa tarde: qué es TOML, dónde no están de acuerdo JSON y TOML y cómo convertir entre ellos sin perder nada de lo que te importaba.
TL;Dr: TOML es un formato de configuración mecanografiado utilizado por Cargo, Poetry, Hugo y muchas herramientas Rust and Go. La conversión de JSON a TOML es principalmente mecánica, pero tres cosas necesitan juicio: orden de tablas (claves antes de subtablas, siempre), cómo se escriben matrices de objetos (matrices de tablas versus tablas en línea) y qué sucede con JSON
null, que TOML no tiene forma de expresar. El Convertidor JSON a TOML hace que los tres sean explícitos y se ejecuta completamente en su navegador.
¿qué es TOML y por qué convertiría JSON en él?
TOML significa Tom's Obvio, Lenguaje mínimo. Se lee como un archivo INI antiguo, pero a diferencia del INI, tiene una especificación real con valores escritos, fechas de primera clase y una gramática definida. Esa especificación es la razón por la que ganó: un formato de configuración que una persona puede leer de un vistazo, que una máquina analiza de la misma manera cada vez, sin ambigüedad sobre si port = 8080 es una cadena o un número. Es un número, porque TOML lo dice.
Busca la conversión de JSON a TOML cuando una máquina le proporciona JSON y una herramienta quiere TOML. Eso sucede más de lo que piensas. Una API devuelve una configuración como JSON y la necesita pyproject.toml. Tienes un viejo config.json y estás moviendo el proyecto a una pila que lee config.toml. Generaste algunos datos mediante programación, salió como JSON porque eso es lo que JSON.stringify produce, y el consumidor es Cargo o Hugo o un servicio Go utilizando una biblioteca TOML. En todos los casos los datos son idénticos. Sólo difiere la serialización.
La dirección inversa también existe, pero es un trabajo diferente. Si vas en sentido contrario, el Formateador JSON vale la pena tener abierto a verificar la cordura del JSON primero y el Convertidor JSON a YAML cubre el otro formato de configuración común. Esta guía trata sobre JSON entrando en TOML.
¿cómo asigna el convertidor JSON a TOML?
Sólo hay un puñado de formas en JSON, y cada una tiene un hogar en TOML. Comprender el mapeo es lo más importante para comprender la herramienta.
UN JSON objeto se convierte en un TOML mesa. El objeto de nivel superior es la tabla raíz, razón por la cual el convertidor insiste en que la entrada sea un objeto. Los objetos anidados se convierten [table] encabezados con camino punteado, entonces { "database": { "pool": { "max": 10 } } } se convierte en [database.pool] sección con max = 10 dentro de él.
UN JSON conjunto de objetos se convierte en un TOML conjunto de tablas, escrito con el doble corchete [[name]] encabezado, un bloque por elemento. Este es el patrón TOML idiomático para una lista de registros: una lista de servidores, una lista de dependencias, una lista de objetivos de compilación. Cada elemento obtiene el suyo propio [[servers]] bloque.
Cada escalar mapas directamente. Una cadena JSON se convierte en una cadena básica TOML entre comillas dobles, con caracteres de control escapados. Un número JSON se convierte en un número entero TOML si es un número entero y un flotante en caso contrario. Un booleano JSON se vuelve true investigaciones operacionales false. Estos son los casos fáciles y el conversor nunca se equivoca.
UN JSON matriz de escalares se convierte en una matriz en línea TOML: ["admin", "editor"] se queda ["admin", "editor"]. Las matrices mixtas y las matrices anidadas también se escriben en línea, porque ese es el único lugar donde encajan.
¿por qué es tan importante realizar pedidos de claves en TOML?
Esta es la regla que atrapa a todos, por lo que vale la pena decirlo claramente. En TOML, dentro de cualquier tabla, todos los pares clave/valor de esa tabla ' deben aparecer antes de cualquiera de sus encabezados de subtabla. Si escribes un [server] encabezado, luego algunas claves, luego otra clave que pertenece a la tabla raíz, el analizador lee esa clave perdida como parte de [server] en cambio. En el mejor de los casos, aterriza en el lugar equivocado; En el peor de los casos, el archivo no se analiza.
JSON no tiene tal regla. En JSON, el orden de las claves ni siquiera es significativo y los objetos y escalares se mezclan libremente dentro de las mismas llaves. Entonces, una conversión ingenua de JSON a TOML que recorre el objeto en orden de inserción y emite cada clave a medida que avanza producirá TOML roto en el momento en que un escalar sigue a un objeto anidado.
El convertidor resuelve esto haciendo dos pasadas sobre cada tabla. Primero emite todas las teclas simples, los escalares y las matrices en línea. Sólo entonces emite los encabezados de subtabla y matriz de tablas, recurriendo a cada uno. Su orden de claves se conserva dentro de cada grupo, que es lo que desea, pero la reorganización requerida entre los dos grupos ocurre automáticamente. Nunca tienes que pensar en ello y nunca obtienes el error que recibí.
¿cuándo deberían ser tablas las matrices de objetos versus en línea?
Ésta es la única opción genuina. Una serie de objetos se pueden escribir de dos maneras en TOML y ambos son válidos.
El primero es un conjunto de tablas, la forma de doble corchete. Es detallado y legible, un bloque por registro, y es como se ve la mayoría de los TOML en estado salvaje. Si has visto un Cargo.toml con varios [[bin]] entradas, has visto esto.
[[servers]]
name = "web"
ip = "10.0.0.1"
[[servers]]
name = "api"
ip = "10.0.0.2"
El segundo es un tabla en línea dentro de una matriz normal, que empaqueta cada objeto en una línea.
servers = [
{ name = "web", ip = "10.0.0.1" },
{ name = "api", ip = "10.0.0.2" },
]
Ambos ida y vuelta a los mismos datos. Cuál desea depende del destino y del gusto. Las matrices de tablas se leen mejor para los registros que un humano editará, y son la convención para la mayoría de las configuraciones de herramientas. Las tablas en línea son más compactas y se acercan más a la forma del JSON original, que algunas personas prefieren cuando la lista es corta o los objetos son pequeños. El convertidor utiliza de forma predeterminada matrices de tablas y le permite cambiar. Si no está seguro, déjelo en el valor predeterminado: es como suele verse un archivo TOML.
¿qué pasa con JSON nulo en TOML?
TOML no tiene nulo. No hay palabra clave, ni valor vacío, nada. Esta es una decisión de diseño deliberada por formato, y es el único lugar donde JSON a TOML es realmente perdido.
Entonces el convertidor tiene que tomar una decisión y te permite hacerlo. Por defecto, una clave cuyo valor es null se descarta y la herramienta enumera las claves descartadas en una nota debajo de la salida para que nada desaparezca silenciosamente. Si prefiere conservar la clave, puede cambiar a escribir nulo como una cadena vacía, lo que conserva la clave a costa de cambiar su tipo. Ninguno de los dos es perfecto, porque no hay una respuesta perfecta. Lo que importa es que la elección sea visible en lugar de enterrada.
Los nulos dentro de las matrices siempre se eliminan, con una advertencia, porque una matriz TOML no puede contener nulo en absoluto. Si tu JSON lo tiene [1, null, 3], el TOML lo será [1, 3] y la herramienta le dirá que eliminó uno. Si esos nulos tienen significado, es una señal para remodelar los datos antes de convertirlos en lugar de después.
¿Por qué mi número perdió su decimal o ganó uno?
Éste sorprende a las personas que se preocupan por los tipos. JSON no distingue 5 de 5.0. Ambos analizan el mismo doble IEEE 754, y por el momento JSON.parse una vez hecho esto, no hay rastro del cero final. Entonces, cuando el convertidor ve el número 5, no tiene forma de saber que te refieres a una carroza, y desde entonces 5 es un número entero, escribe un número entero TOML.
TOML, por otro lado, distingue los números enteros de los flotadores y algunas herramientas se preocupan por la diferencia. Si necesita un valor escrito como flotante, la solución es darle una parte fraccionaria en la fuente 5.1 investigaciones operacionales 5.0 escrito de una manera que sobreviva o para editar el valor único después de la conversión. Es un cambio de un carácter y es raro, pero vale la pena saber por qué sucede en lugar de asumir que el convertidor está equivocado. No está mal. JSON simplemente tiró la información antes de que el convertidor la viera.
El caso inverso aparece con números muy grandes o muy pequeños, donde JavaScript's String() produce notación de exponente como 1e+21. TOML acepta que como flotador, por lo que se convierte bien, pero la forma del número puede verse diferente de lo que escribiste. Nuevamente, el valor es idéntico; sólo cambió la representación.
¿cómo funcionan las claves desnudas y citadas?
TOML permite escribir una clave desnuda si está hecha sólo de letras, dígitos, guiones bajos y guiones. Cualquier otra cosa, se debe citar una clave con un punto, un espacio, una barra diagonal, un carácter Unicode. El convertidor verifica cada clave y cita solo las que la necesitan, por lo que user-name permanece desnudo y "user.name" obtiene comillas para evitar que el punto se lea como una ruta de tabla. No tienes que pensar en esto, pero si ves comillas alrededor de una clave en la salida, es por eso que: la clave contenía un carácter que de otro modo cambiaría su significado.
Un ejemplo trabajado
Aquí está la muestra de las cargas de herramientas, para que pueda ver todas las reglas a la vez. El JSON:
{
"title": "Toolz config",
"version": 2,
"enabled": true,
"owner": { "name": "Liton", "roles": ["admin", "editor"] },
"database": { "host": "localhost", "port": 5432, "pool": { "min": 2, "max": 10 } },
"servers": [
{ "name": "web", "ip": "10.0.0.1" },
{ "name": "api", "ip": "10.0.0.2" }
]
}
se convierte en TOML donde los escalares raíz aparecen primero, los objetos anidados se convierten en tablas de puntos en orden y la matriz de servidores se convierte en dos [[servers]] blocuri:
title = "Toolz config"
version = 2
enabled = true
[owner]
name = "Liton"
roles = ["admin", "editor"]
[database]
host = "localhost"
port = 5432
[database.pool]
min = 2
max = 10
[[servers]]
name = "web"
ip = "10.0.0.1"
[[servers]]
name = "api"
ip = "10.0.0.2"
Note eso title, version y enabled se escriben antes de cualquier encabezado, roles sigue siendo una matriz en línea porque es una matriz de cadenas, y [database.pool] se sienta debajo [database] como camino punteado. Cada regla de esta guía es visible en nueve líneas de salida.
¿Qué herramienta para qué conversión?
TOML es un formato de una familia y la herramienta adecuada depende de dónde comience y termine. Así es como lo pienso.
| Tienes | tu quieres | aprovechamiento |
|---|---|---|
| JISON | Configuración TOML | JSON a TOML |
| JISON | Configuración YAML | JSON a YAM |
| hablar con tachuelas | JISON | YAML a JSON |
| JISON | xml | JSON a XML |
| Json desordenado | Json legible | Formateador JSON |
El patrón es que los formatos de configuración son vistas intercambiables de los mismos datos y el convertidor que desea lleva el nombre de la dirección en la que va. TOML, YAML y JSON expresan datos clave/valor anidados; la diferencia es cuál lee su herramienta de destino.
¿Es seguro convertir un archivo de configuración en línea?
Los archivos de configuración son exactamente el tipo de cosas que debes tener cuidado al pegar en un sitio web, porque a menudo contienen cadenas de conexión, tokens y otros secretos. El Convertidor JSON a TOML Se ejecuta completamente en su navegador. El JSON que pega se analiza en la memoria de su dispositivo, el TOML se produce allí y no se envía nada a un servidor, se escribe en un registro o se almacena. Puede verlo usted mismo: abra la pestaña de su red, ejecute una conversión y vea que no se emite ninguna solicitud. También sigue funcionando sin conexión una vez que se ha cargado la página, que es la prueba práctica de que el trabajo es local. Si te importa adónde van tus datos y con un archivo de configuración deberías hacerlo, esta es la propiedad que importa. Es el mismo principio detrás de cada herramienta del sitio, y la razón por la que escribí extensamente sobre ello en la nota de Privacidad de datos en herramientas en línea.
Donde esto encaja en un flujo de trabajo real
La conversión de formato rara vez es toda la tarea. Es un paso. Sacas un objeto de configuración de una API, lo conviertes y lo dejas caer en un proyecto. El valor de un convertidor del lado del cliente es que se ubica en ese flujo sin fricciones: sin carga, sin cuenta, sin espera en un servidor, sin preguntarte si tus secretos están ahora en alguien 's registros. Esa es la misma razón por la que guardo el conjunto Toolz.dev establezca el lado del cliente y es un tema al que vuelvo en el Herramientas de productividad para desarrolladores artículo, porque las herramientas a las que llegas veinte veces al día son aquellas en las que se suman un viaje de ida y vuelta de dos segundos y una pregunta de privacidad.
TOML se ganó su lugar en ese flujo al ser aburrido de la mejor manera. Se analiza igual en todas partes, se lee bien y su único filo, la regla de orden, es exactamente el tipo de cosas que un conversor debería presentar por usted. Pegue su JSON, elija cómo desea que se manejen las matrices y los nulos y copie TOML que simplemente funcione.
Preguntas frecuentes
¿cómo convierto JSON a TOML?
Pegue su objeto JSON en el convertidor y haga clic en Convertir. La herramienta serializa objetos en tablas TOML, matrices de objetos en matrices de tablas y cualquier otro valor en línea, luego le brinda TOML estándar para copiar. El JSON de nivel superior debe ser un objeto, porque un documento TOML es siempre una tabla.
¿para qué se utiliza TOML?
TOML es un formato de archivo de configuración diseñado para ser fácil de leer y de analizar sin ambigüedades. Es el formato de configuración de Rust's Cargo (Cargo.toml), Python packaging (pyproject.toml), Hugo y muchas herramientas Go y Rust. La gente convierte JSON a TOML para entregar una configuración generada por máquina a una herramienta que espera TOML.
¿qué sucede con los valores nulos de JSON en TOML?
TOML no tiene tipo nulo, por lo que un JSON nulo no se puede representar directamente. De forma predeterminada, este convertidor elimina las claves nulas y agrega una nota que las enumera; en su lugar, puedes pasar a escribirlas como cadenas vacías. Los nulos dentro de las matrices siempre se eliminan porque una matriz TOML no puede contener nulo.
¿cuál es la diferencia entre una matriz de tablas y una tabla en línea?
Una matriz de tablas utiliza encabezados repetidos de doble corchete, un bloque por registro, y es la forma idiomática de TOML de escribir una lista de objetos, como una lista de servidores o dependencias. Una tabla en línea empaqueta un objeto en una línea como un conjunto de claves iguales a pares de valores en llaves. Esta herramienta utiliza de forma predeterminada matrices de tablas, pero le permite elegir en línea.
¿por qué mi JSON número 5.0 se convirtió en 5 en TOML?
JSON no conserva la diferencia entre 5 y 5.0, por lo que el análisis lee ambos como el número 5. Dado que 5 es un número entero, el convertidor lo escribe como un entero TOML. Si necesita escribirlo como flotante, agregue una parte fraccionaria en la fuente o edite el valor único después de la conversión.
¿el convertidor mantiene mi pedido de clave?
Sí. Las claves se emiten en el orden en que aparecen en el JSON, con una reorganización requerida: dentro de cada tabla, las claves simples se escriben antes de cualquier encabezado de subtabla o matriz de tablas. Esa es una regla de sintaxis TOML, no una opción de reordenamiento, y sin ella el archivo no analizaría.
¿Mi json está cargado en un servidor?
No. Toda la conversión se realiza en su navegador utilizando JavaScript simple. Su JSON, incluidos los secretos o credenciales de un archivo de configuración, nunca se transmite, registra ni almacena, y el convertidor sigue funcionando sin conexión una vez que la página se ha cargado.
¿Por qué dice que el nivel superior debe ser un objeto?
Un documento TOML se define como una tabla, lo que significa que debe comenzar a partir de un conjunto de pares clave/valor. Una matriz JSON desnuda o un escalar no tiene una tabla para asignar. Envuélvalo primero en un objeto, por ejemplo, colocando su matriz debajo de una clave con nombre, y se convertirá.
