Formatador TOML

Última atualização: abril de 2026

O Que É a Formatação de TOML?

TOML (Tom's Obvious Minimal Language) é um formato de arquivo de configuração criado por Tom Preston-Werner em 2013. Ele mapeia diretamente para uma tabela hash e utiliza tipagem explícita para todos os valores. Um formatador TOML recebe um TOML bruto ou com estilo inconsistente e o re-serializa com espaçamento uniforme, indentação adequada e ordenação canônica de chaves. O resultado é um arquivo que segue as mesmas convenções em todo o projeto, tornando as alterações de configuração mais fáceis de revisar em diffs.

A especificação TOML v1.0.0, finalizada em janeiro de 2021, define a gramática com rigor suficiente para que qualquer parser compatível produza uma estrutura de dados idêntica a partir da mesma entrada. A formatação não altera o conteúdo semântico de um arquivo TOML. Ela ajusta apenas o espaço em branco, o agrupamento de chaves e o estilo de aspas. Isso significa que você pode formatar arquivos TOML livremente sem se preocupar em quebrar o comportamento da sua aplicação.

Ao contrário do JSON, o TOML suporta comentários, tipos nativos de data e hora e múltiplas formas de string (básica, literal e multilinha). Um bom formatador preserva os comentários e respeita a distinção entre tabelas inline e cabeçalhos de tabela padrão. Ele também trata corretamente arrays de tabelas, mantendo o agrupamento de seções intacto para que o arquivo permaneça legível tanto para humanos quanto para os parsers que o consomem.

title="My App"
version="1.0.0"
debug=false
[database]
host="localhost"
port=5432
name="mydb"
[database.pool]
max_connections=25
timeout=30
[[servers]]
name="web"
host="web.example.com"
[[servers]]
name="api"
host="api.example.com"

title = "My App"
version = "1.0.0"
debug = false

[database]
host = "localhost"
port = 5432
name = "mydb"

[database.pool]
max_connections = 25
timeout = 30

[[servers]]
name = "web"
host = "web.example.com"

[[servers]]
name = "api"
host = "api.example.com"

Por Que Usar um Formatador TOML?

Arquivos de configuração acumulam desvios de estilo à medida que diferentes membros da equipe os editam ao longo do tempo. Tabs se misturam com espaços, algumas chaves são desnecessariamente colocadas entre aspas e as seções de tabela perdem seu agrupamento visual. Um formatador TOML normaliza tudo isso em uma única passagem.

Casos de Uso do Formatador TOML

Referência de Sintaxe TOML

O TOML possui um conjunto reduzido de construções. A tabela abaixo lista todos os elementos estruturais definidos na especificação TOML v1.0.0. Um formatador aplica espaçamento e agrupamento consistentes a todos eles.

TOML vs JSON vs YAML

TOML, JSON e YAML resolvem problemas semelhantes, mas fazem escolhas diferentes.

Exemplos de Código

Os exemplos abaixo formatam TOML de forma programática em diferentes linguagens e ferramentas. Cada um lê um arquivo, faz o parsing e grava uma versão formatada.

import { parse, stringify } from '@iarna/toml'
import fs from 'fs'

const raw = fs.readFileSync('config.toml', 'utf-8')
const doc = parse(raw)
const formatted = stringify(doc)
// stringify() outputs canonical TOML with consistent spacing
fs.writeFileSync('config.toml', formatted)

// Quick one-liner with npx:
// npx taplo fmt config.toml

import tomllib   # Python 3.11+ (read-only)
import tomli_w   # pip install tomli-w (write)

# Parse and re-serialize to format
with open("config.toml", "rb") as f:
    data = tomllib.load(f)

formatted = tomli_w.dumps(data)
# tomli_w produces sorted keys, consistent quoting, and
# proper whitespace around = signs
print(formatted)

# CLI alternative: taplo fmt config.toml

package main

import (
    "fmt"
    "os"
    "github.com/BurntSushi/toml"
    "bytes"
)

func main() {
    var data map[string]interface{}
    _, err := toml.DecodeFile("config.toml", &data)
    if err != nil {
        fmt.Fprintln(os.Stderr, err) // parse error with line number
        os.Exit(1)
    }
    var buf bytes.Buffer
    enc := toml.NewEncoder(&buf)
    enc.Indent = "  "
    enc.Encode(data) // re-serialized with consistent formatting
    fmt.Print(buf.String())
}

# Install taplo — the standard TOML toolkit
cargo install taplo-cli
# or: npm install -g @taplo/cli

# Format a single file in place
taplo fmt config.toml

# Format all .toml files in a project
taplo fmt

# Check formatting without modifying (CI-friendly)
taplo fmt --check

# Validate TOML syntax without formatting
taplo lint config.toml

Perguntas Frequentes