v1.0.0
Publicado em 3/17/2013 – Versão de texto

TOML v0.1.0

Tom's Obvious, Minimal Language.

Por Tom Preston-Werner.

Fique ciente de que esta especificação ainda está mudando muito. Até que seja marcado como 1.0, você deve presumir que é instável e agir de acordo.

Objetivos

TOML visa ser um formato de arquivo de configuração mínimo que seja fácil de ler devido à semântica óbvia. O TOML foi projetado para mapear inequivocamente para uma tabela de hash. O TOML deve ser fácil de analisar em estruturas de dados em uma ampla variedade de idiomas.

Especificação

  • TOML é case-sensitive, ou seja, diferencia maiúsculo de minúsculo.
  • Espaço em branco significa tabulação (0x09) ou espaço (0x20).

Comentário

Fale o que pensa com o símbolo de cerquilha. Eles vão do símbolo até o final da linha.

# Sou um comentário. Ouça-me rugir. Grrrrr.
chave = "valor" # É, você pode fazer isso.

String

Dica Pro™: Você pode notar que esta especificação é a mesma que a definição de string do JSON, exceto que TOML requer codificação UTF-8. Isso é de propósito.

Strings são valores uma única linha colocados entre aspas. Strings devem conter apenas caracteres UTF-8 válidos. Qualquer caractere Unicode pode ser usado exceto aqueles que devem ter escape: aspas, barra invertida e os caracteres de controle (U+0000 a U+001F).

"Sou uma string. \"Você me colocar entre aspas\". Nome\tJos\u00E9\nLocal\tSF."

Por conveniência, alguns caracteres populares têm uma sequência de escape compacta.

\b     - backspace         (U+0008)
\t     - tabulação         (U+0009)
\n     - linefeed          (U+000A)
\f     - form feed         (U+000C)
\r     - carriage return   (U+000D)
\"     - aspas             (U+0022)
\/     - barra             (U+002F)
\\     - barra invertida   (U+005C)
\uXXXX - unicode           (U+XXXX)

Qualquer caractere Unicode pode ser escapado com a forma \uXXXX.

Outros caracteres especiais são reservados e, se usados, TOML deve produzir um erro. Isso significa que os caminhos no Windows sempre terão que usar barras invertidas duplas.

errado = "C:\Users\nodejs\templates" # note: não produz um caminho válido
correto = "C:\\Users\\nodejs\\templates"

Para dados binários, é recomendável usar Base 64 ou outra codificação ASCII ou UTF-8 adequada. A manipulação dessa codificação será específica do aplicativo.

Inteiro

Números inteiros são números simples, sozinhos. Sentindo-se negativo? Faça o que é natural. Tamanho mínimo de 64 bits esperado.

42
-17

Ponto flutuante

Pontos flutuantes são números com um único ponto dentro. Deve haver pelo menos um número em cada lado da vírgula. Precisão (dupla) de 64 bits esperada.

3.1415
-0.01

Booleano

Booleanos são apenas os tokens com os quais você está acostumado. Sempre minúsculos.

true
false

Data e hora

Datas/horas são datas ISO8601, mas apenas a forma zulu completa é permitida.

1979-05-27T07:32:00Z

Array

Arrays são colchetes com outras primitivas dentro. O espaço em branco é ignorado. Os elementos são separados por vírgulas. Não, você não pode misturar tipos de dados, isso é estúpido.

[ 1, 2, 3 ]
[ "vermelho", "amarelo", "verde" ]
[ [ 1, 2 ], [3, 4, 5] ]
[ [ 1, 2 ], ["a", "b", "c"] ] # tudo bem
[ 1, 2.0 ] # nota: isso NÃO está correto

Arrays também podem ser multilinhas. Portanto, além de ignorar os espaços em branco, os arrays também ignoram as novas linhas entre os colchetes. As vírgulas de terminação são aceitas antes do colchete de fechamento.

chave = [
  1, 2, 3
]

chave = [
  1,
  2, # tudo bem
]

Hash

Existem duas maneiras de fazer chaves. Eu os chamo de "grupos de chaves" e "chaves". Ambos são apenas chaves regulares, mas os grupos de chaves sempre têm apenas um único hash como valor.

Grupos de chaves aparecem entre colchetes em uma linha própria. Você pode diferenciá-los dos arrays porque os arrays são apenas valores.

[grupochaves]

Abaixo disso, e até o próximo cabeçalho ou EOF, estão as chaves/valores daquele grupo de chaves. As chaves estão à esquerda do sinal de igual e os valores à direita. Chaves começam com o primeiro caractere diferente de espaço em branco e terminam com o último caractere diferente de espaço em branco antes do sinal de igual. Pares chave/valor dentro do grupo de chaves não são ordenadas.

[grupochaves]
chave = "valor"

Você pode recuar as chaves e seus valores o quanto quiser. Tabulações ou espaços. Fique à vontade. Por que, você pergunta? Porque você pode ter hashes aninhados. Massa demais.

Os hashes aninhados são indicados por grupos de chaves com pontos. Nomeie seus grupos de chaves como quiser, apenas não use um ponto. Ponto é reservado. OBEDEÇA.

[chave.batatinha]
tipo = "pug"

Na terra do JSON, isso resultaria na seguinte estrutura.

{ "chave": { "batatinha": { "tipo": "pug" } } }

Você não precisa especificar todas as superchaves se não quiser. TOML sabe como fazer isso para você.

# [x] você
# [x.y] não
# [x.y.z] precisa disso
[x.y.z.w] # para que isso funcione

Quando convertido em uma tabela hash, um grupo de chaves vazio deve resultar no valor da chave sendo uma tabela hash vazia.

Tenha cuidado para não sobrescrever as chaves anteriores. Isso é tolice. E deve produzir um erro.

# VOCÊ NÃO QUER
[fruta]
tipo = "uva"

[fruta.tipo]
uva = "sim"

Sério?

É.

Mas por que?

Porque precisamos de um formato decente legível por humanos que mapeie inequivocamente para um hash e a especificação YAML tenha cerca de 80 páginas e me dê raiva. Não, JSON não conta. Você sabe o porquê.

Oh Deus, você está certo

É isso aí. Quer ajudar? Envie uma pull request. Ou escreva um analisador. SEJA CORAJOSO.

Implementações

Se você tiver uma implementação, envie uma pull request adicionando a esta lista. Observe o commit SHA1 ou tag de versão compatível com seu analisador em seu Readme.

Validadores

Conjunto de testes agnósticos de linguagem para analisadores TOML

Suporte em editores

Codificador