[WIP] [toml/en] Add TOML support (#2282)

* Init support for TOML

* Add scalar types section

* Move comment to key value

* Improve introduction

* Move int comment to int key value

* Add array support

* Add version warning

* Add support for table

* Add inline table part

* Add support array of table part

* Fix bugs/typos to follow the review

* Improve sub tables example

* Fix wrong quotes on multiLineLiteralString

* Fix letter case for coherence

* Remove old comment

* Move from variety to color

Thanks @robochat

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)