diff options
| -rwxr-xr-x | toml.html.markdown | 274 |
1 files changed, 274 insertions, 0 deletions
diff --git a/toml.html.markdown b/toml.html.markdown new file mode 100755 index 00000000..980563f9 --- /dev/null +++ b/toml.html.markdown @@ -0,0 +1,274 @@ +--- +language: toml +filename: learntoml.toml +contributors: + - ["Alois de Gouvello", "https://github.com/aloisdg"] +--- + +TOML stands for Tom's Obvious, Minimal Language. It is a data serialisation language designed to be a minimal configuration file format that's easy to read due to obvious semantics. + +It is an alternative to YAML and JSON. It aims to be more human friendly than JSON and simpler that YAML. TOML is designed to map unambiguously to a hash table. TOML should be easy to parse into data structures in a wide variety of languages. + +Be warned, TOML's spec is still changing a lot. Until it's marked as 1.0, you +should assume that it is unstable and act accordingly. This document follows TOML v0.4.0. + +```toml +# Comments in TOML look like this. + +################ +# SCALAR TYPES # +################ + +# Our root object (which continues for the entire document) will be a map, +# which is equivalent to a dictionary, hash or object in other languages. + +# The key, equals sign, and value must be on the same line +# (though some values can be broken over multiple lines). +key = "value" +string = "hello" +number = 42 +float = 3.14 +boolean = true +dateTime = 1979-05-27T07:32:00-08:00 +scientificNotation = 1e+12 +"key can be quoted" = true # Both " and ' are fine +"key may contains" = "letters, numbers, underscores, and dashes" + +# A bare key must be non-empty, but an empty quoted key is allowed +"" = "blank" # VALID but discouraged +'' = 'blank' # VALID but discouraged + +########## +# String # +########## + +# All strings must contain only valid UTF-8 characters. +# We can escape characters and some of them have a compact escape sequence. +# For example, \t add a tabulation. Refers to the spec to get all of them. +basicString = "are surrounded by quotation marks. \"I'm quotable\". Name\tJos" + +multiLineString = """ +are surrounded by three quotation marks +on each side and allow newlines.""" + +literalString = 'are surrounded by single quotes. Escaping are not allowed.' + +multiLineLiteralString = ''' +are surrounded by three single quotes on each side +and allow newlines. Still no escaping. +The first newline is trimmed in raw strings. + All other whitespace + is preserved. #! are preserved? +''' + +# For binary data it is recommended that you use Base64, another ASCII or UTF8 +# encoding. The handling of that encoding will be application specific. + +########### +# Integer # +########### + +## Integers can start with a +, a - or nothing. +## Leading zeros are not allowed. Hex, octal, and binary forms are not allowed. +## Values that cannot be expressed as a series of digits are not allowed. +int1 = +42 +int2 = 0 +int3 = -21 +integerRange = 64 + +## You can use underscores to enhance readability. Each +## underscore must be surrounded by at least one digit. +int4 = 5_349_221 +int5 = 1_2_3_4_5 # VALID but discouraged + +######### +# Float # +######### + +# Floats are an integer followed by a fractional and/or an exponent part. +flt1 = 3.1415 +flt2 = -5e6 +flt3 = 6.626E-34 + +########### +# Boolean # +########### + +bool1 = true +bool2 = false +boolMustBeLowercase = true + +############ +# Datetime # +############ + +date1 = 1979-05-27T07:32:00Z # follows the RFC 3339 spec +date2 = 1979-05-27T07:32:00 # without offset +date3 = 1979-05-27 # without offset nor time + +#################### +# COLLECTION TYPES # +#################### + +######### +# Array # +######### + +array1 = [ 1, 2, 3 ] +array2 = [ "Commas", "are", "delimiters" ] +array3 = [ "Don't mixed", "different", "types" ] +array4 = [ [ 1.2, 2.4 ], ["all", 'strings', """are the same""", '''type'''] ] +array5 = [ + "Whitespace", "is", "ignored" +] + +######### +# Table # +######### + +# Tables (or hash tables or dictionaries) are collections of key/value +# pairs. They appear in square brackets on a line by themselves. +# Empty tables are allowed and simply have no key/value pairs within them. +[table] + +# Under that, and until the next table or EOF are the key/values of that table. +# Key/value pairs within tables are not guaranteed to be in any specific order. +[table-1] +key1 = "some string" +key2 = 123 + +[table-2] +key1 = "another string" +key2 = 456 + +# Dots are prohibited in bare keys because dots are used to signify nested tables. +# Naming rules for each dot separated part are the same as for keys. +[dog."tater.man"] +type = "pug" + +# In JSON land, that would give you the following structure: +# { "dog": { "tater.man": { "type": "pug" } } } + +# Whitespace around dot-separated parts is ignored, however, best practice is to +# not use any extraneous whitespace. +[a.b.c] # this is best practice +[ d.e.f ] # same as [d.e.f] +[ j . "ʞ" . 'l' ] # same as [j."ʞ".'l'] + +# You don't need to specify all the super-tables if you don't want to. TOML knows +# how to do it for you. +# [x] you +# [x.y] don't +# [x.y.z] need these +[x.y.z.w] # for this to work + +# As long as a super-table hasn't been directly defined and hasn't defined a +# specific key, you may still write to it. +[a.b] +c = 1 + +[a] +d = 2 + +# You cannot define any key or table more than once. Doing so is invalid. + +# DO NOT DO THIS +[a] +b = 1 + +[a] +c = 2 + +# DO NOT DO THIS EITHER +[a] +b = 1 + +[a.b] +c = 2 + +# All table names must be non-empty. +[] # INVALID +[a.] # INVALID +[a..b] # INVALID +[.b] # INVALID +[.] # INVALID + +################ +# Inline table # +################ + +inlineTables = { areEnclosedWith = "{ and }", mustBeInline = true } +point = { x = 1, y = 2 } + +################### +# Array of Tables # +################### + +# An array of tables can be expressed by using a table name in double brackets. +# Each table with the same double bracketed name will be an item in the array. +# The tables are inserted in the order encountered. + +[[products]] +name = "array of table" +sku = 738594937 +emptyTableAreAllowed = true + +[[products]] + +[[products]] +name = "Nail" +sku = 284758393 +color = "gray" + +# You can create nested arrays of tables as well. Each double-bracketed +# sub-table will belong to the nearest table element above it. + +[[fruit]] + name = "apple" + + [fruit.Geometry] + shape = "round" + note = "I am an fruit's property" + + [[fruit.color]] + name = "red" + note = "I am an array's item in apple" + + [[fruit.color]] + name = "green" + note = "I am in the same array than red" + +[[fruit]] + name = "banana" + + [[fruit.color]] + name = "yellow" + note = "I am an array's item too but banana's one" +``` + +In JSON land, this code will be: + +```json +{ + "fruit": [ + { + "name": "apple", + "geometry": { "shape": "round", "note": "..."}, + "color": [ + { "name": "red", "note": "..." }, + { "name": "green", "note": "..." } + ] + }, + { + "name": "banana", + "color": [ + { "name": "yellow", "note": "..." } + ] + } + ] +} +``` + +### More Resources + ++ [TOML official repository](https://github.com/toml-lang/toml) |