TOML v0.2.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. Exemplo ------- ```toml # Este é um documento TOML. Boom. título = "Exemplo do TOML" [dono] nome = "Tom Preston-Werner" organização = "GitHub" bio = "Cofundador e CEO do GitHub\nGosta de batatinha e cerveja." dtnasc = 1979-05-27T07:32:00-0800 # Datas da primeira classe? Por que não? [banco-de-dados] servidor = "192.168.1.1" portas = [ 8001, 8001, 8002 ] max_conexoes = 5000 habilitado = true [servidores] # Recue conforme desejado. Tabulações ou espaços. TOML não se importa. [servidores.alfa] ip = "10.0.0.1" dc = "eqdc10" [servidores.beta] ip = "10.0.0.2" dc = "eqdc10" [clientes] dados = [ ["gama", "delta"], [1, 2] ] # Quebras de linha são aceitas dentro de arrays hosts = [ "alfa", "omega" ] ``` 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. ```toml # 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 colocadas 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). ```toml "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. ```toml 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 Base64 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. ```toml 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. ```toml 3.1415 -0.01 ``` Booleano -------- Booleanos são apenas os tokens com os quais você está acostumado. Sempre minúsculos. ```toml true false ``` Data e hora ----------- Datas/horas são datas ISO 8601, mas apenas a forma zulu completa é permitida. ```toml 1979-05-27T07:32:00Z ``` Array ----- Arrays são colchetes com outros primitivos dentro. O espaço em branco é ignorado. Os elementos são separados por vírgulas. Os tipos de dados podem ser misturados. ```toml [ 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. ```toml chave = [ 1, 2, 3 ] chave = [ 1, 2, # tudo bem ] ``` Tabela ------ Tabelas (também conhecidas como tabelas hash ou dicionários) são coleções de pares chave/valor. Elas aparecem entre colchetes em uma linha própria. Você pode diferenciá-las de arrays porque os arrays são apenas valores. ```toml [tabela] ``` Abaixo disso, e até o próximo cabeçalho ou EOF, estão as chaves/valores dessa tabela. 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 de tabelas não são ordenadas. ```toml [tabela] 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 tabelas aninhadas. Massa demais. As tabelas aninhadas são indicadas por nomes de tabela com pontos. Nomeie suas tabelas como quiser, apenas não use um ponto. Ponto é reservado. OBEDEÇA. ```toml [cachorro.batatinha] tipo = "pug" ``` Na terra do JSON, isso resultaria na seguinte estrutura: ```json { "cachorro": { "batatinha": { "tipo": "pug" } } } ``` Você não precisa especificar todas as supertabelas se não quiser. TOML sabe como fazer isso para você. ```toml # [x] você # [x.y] não # [x.y.z] precisa disso [x.y.z.w] # para que isso funcione ``` Tabelas vazias são permitidas e simplesmente não possuem pares chave/valor dentro delas. Desde que uma supertabela não tenha sido definida diretamente e não tenha definido uma chave específica, você ainda pode escrever nela. ```toml [a.b] c = 1 [a] d = 2 ``` Você não pode definir nenhuma chave ou tabela mais de uma vez. Fazer isso é inválido. ```toml # NÃO FAÇA ISSO [a] b = 1 [a] c = 2 ``` ```toml # TAMBÉM NÃO FAÇA ISSO [a] b = 1 [a.b] c = 2 ``` Array de tabelas ---------------- A última sintaxe que ainda não foi expressa é um array de tabelas. Este pode ser expresso usando um nome de tabela entre colchetes duplos. Cada tabela com o mesmo nome entre colchetes duplos será um elemento no array. As tabelas são inseridas no array na ordem encontrada. Uma tabela com colchetes duplos sem nenhum par chave/valor será considerada uma tabela vazia. ```toml [[produtos]] nome = "Martelo" sku = 738594937 [[produtos]] [[produtos]] nome = "Prego" sku = 284758393 cor = "cinza" ``` Na terra do JSON, isso resultaria na seguinte estrutura. ```json { "produtos": [ { "nome": "Martelo", "sku": 738594937 }, { }, { "nome": "Prego", "sku": 284758393, "color": "cinza" } ] } ``` Você também pode criar arrays aninhados de tabelas. Basta usar a mesma sintaxe de colchetes duplos nas subtabelas. Cada subtabela entre colchetes pertencerá ao elemento de tabela definido mais recentemente acima dela. ```toml [[fruta]] nome = "uva" [fruta.fisico] cor = "roxa" forma = "redonda" [[fruta.variedade]] nome = "roxa deliciosa" [[fruta.variedade]] nome = "cabernet sauvignon" [[fruta]] nome = "banana" [[fruta.variedade]] nome = "banana-da-terra" ``` O TOML acima é mapeado para o seguinte JSON. ```json { "fruta": [ { "nome": "uva", "fisico": { "cor": "roxa", "forma": "redonda" }, "variedade": [ { "nome": "roxa deliciosa" }, { "nome": "cabernet sauvignon" } ] }, { "nome": "banana", "variedade": [ { "nome": "banana-da-terra" } ] } ] } ``` A tentativa de definir uma tabela normal com o mesmo nome de um array já estabelecido deve produzir um erro no momento da análise. ```toml # DOCUMENTO TOML INVÁLIDO [[fruta]] nome = "uva" [[fruta.variedade]] nome = "roxa deliciosa" # Esta tabela conflita com a tabela anterior [fruta.variedade] nome = "cabernet sauvignon" ``` Sério? ------ É. Mas por que? ------------ Porque precisamos de um formato decente legível por humanos que mapeie inequivocamente para uma tabela hash e a especificação YAML tenha cerca de 80 páginas e me dê raiva. Não, JSON não conta. Você sabe porque. 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. - C#/.NET - https://github.com/LBreedlove/Toml.net - C#/.NET - https://github.com/rossipedia/toml-net - C#/.NET - https://github.com/RichardVasquez/TomlDotNet - C (@ajwans) - https://github.com/ajwans/libtoml - C++ (@evilncrazy) - https://github.com/evilncrazy/ctoml - C++ (@skystrife) - https://github.com/skystrife/cpptoml - Clojure (@lantiga) - https://github.com/lantiga/clj-toml - Clojure (@manicolosi) - https://github.com/manicolosi/clojoml - CoffeeScript (@biilmann) - https://github.com/biilmann/coffee-toml - Common Lisp (@pnathan) - https://github.com/pnathan/pp-toml - Erlang - https://github.com/kalta/etoml.git - Erlang - https://github.com/kaos/tomle - Emacs Lisp (@gongoZ) - https://github.com/gongo/emacs-toml - Go (@thompelletier) - https://github.com/pelletier/go-toml - Go (@laurent22) - https://github.com/laurent22/toml-go - Go com Reflection (@BurntSushi) - https://github.com/BurntSushi/toml - Haskell (@seliopou) - https://github.com/seliopou/toml - Haxe (@raincole) - https://github.com/raincole/haxetoml - Java (@agrison) - https://github.com/agrison/jtoml - Java (@johnlcox) - https://github.com/johnlcox/toml4j - Java (@mwanji) - https://github.com/mwanji/toml4j - Java - https://github.com/asafh/jtoml - Java w/ ANTLR (@MatthiasSchuetz) - https://github.com/mschuetz/toml - Julia (@pygy) - https://github.com/pygy/TOML.jl - Literate CoffeeScript (@JonathanAbrams) - https://github.com/JonAbrams/tomljs - node.js - https://github.com/aaronblohowiak/toml - node.js/browser - https://github.com/ricardobeat/toml.js (npm install tomljs) - node.js - https://github.com/BinaryMuse/toml-node - node.js (@redhotvengeance) - https://github.com/redhotvengeance/topl (topl npm package) - node.js/browser (@alexanderbeletsky) - https://github.com/alexanderbeletsky/toml-js (npm browser amd) - Objective C (@mneorr) - https://github.com/mneorr/toml-objc.git - Objective-C (@SteveStreza) - https://github.com/amazingsyco/TOML - Ocaml (@mackwic) https://github.com/mackwic/to.ml - Perl (@alexkalderimis) - https://github.com/alexkalderimis/config-toml.pl - Perl - https://github.com/dlc/toml - PHP (@leonelquinteros) - https://github.com/leonelquinteros/php-toml.git - PHP (@jimbomoss) - https://github.com/jamesmoss/toml - PHP (@coop182) - https://github.com/coop182/toml-php - PHP (@checkdomain) - https://github.com/checkdomain/toml - PHP (@zidizei) - https://github.com/zidizei/toml-php - PHP (@yosymfony) - https://github.com/yosymfony/toml - Python (@socketubs) - https://github.com/socketubs/pytoml - Python (@f03lipe) - https://github.com/f03lipe/toml-python - Python (@uiri) - https://github.com/uiri/toml - Python - https://github.com/bryant/pytoml - Python (@elssar) - https://github.com/elssar/tomlgun - Python (@marksteve) - https://github.com/marksteve/toml-ply - Python (@hit9) - https://github.com/hit9/toml.py - Ruby (@jm) - https://github.com/jm/toml (toml gem) - Ruby (@eMancu) - https://github.com/eMancu/toml-rb (toml-rb gem) - Ruby (@charliesome) - https://github.com/charliesome/toml2 (toml2 gem) - Ruby (@sandeepravi) - https://github.com/sandeepravi/tomlp (tomlp gem) - Scala - https://github.com/axelarge/tomelette Validadores ----------- - Go (@BurntSushi) - https://github.com/BurntSushi/toml/tree/master/tomlv Conjunto de testes agnósticos de linguagem para analisadores TOML ----------------------------------------------------------------- - toml-test (@BurntSushi) - https://github.com/BurntSushi/toml-test Suporte em editores ------------------- - Emacs (@dryman) - https://github.com/dryman/toml-mode.el - Sublime Text 2 e 3 (@lmno) - https://github.com/lmno/TOML - TextMate (@infininight) - https://github.com/textmate/toml.tmbundle - Vim (@cespare) - https://github.com/cespare/vim-toml Codificador ----------- - PHP (@ayushchd) - https://github.com/ayushchd/php-toml-encoder