Merge ea28bb9c62 into 990878a11f

.github/workflows/lint.yml

@@ -11,7 +11,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: ruby/setup-ruby@ec02537da5712d66d4d50a0f33b7eb52773b5ed1
+      - uses: ruby/setup-ruby@v1
         with:
           ruby-version: '3.2'
       - run: gem install mdl

toml.html.markdown

@@ -14,30 +14,90 @@ This document follows [TOML v1.0.0](https://toml.io/en/v1.0.0). Future [changes]
 ```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.
+##################
+# Key/Value Pair #
+##################
 
+# The primary building block of a TOML document is the key/value pair.
 # The key, equals sign, and value must be on the same line
 # (though some values can be broken over multiple lines).
 key = "value"
+
+# Valus types must be one of the followings.
 string = "hello"
-number = 42
+integer = 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
-"unquoted key may contain" = "letters, numbers, underscores, and dashes"
-other_kêys = "are permitted by spec but most implementations don't actually permit them"
+offsetDateTime = 1979-05-27T07:32:00Z
+localDateTime = 1979-05-27T07:32:00
+localDate = 1979-05-27
+localTime = 07:32:00
+array = [ 1, 2, 3 ]
+inlineTable = { first = "Tom", last = "Preston-Werner" }
 
+# A key may be either bare, quoted, or dotted.
+
+## bare
+bare_key = "value" # bare keys may only contain ASCII letters/digits, underscore, and dashes
+1234 = "value" # only-digits bare keys are allowed
+= "no key name" # empty bare key is invalid
+# defining duplicated key is invalid
+name = "Tom"
+name = "Pradyun" # invalid
+
+## quoted
+"key can be quoted" = true # Both " and ' are fine
 # A bare key must be non-empty, but an empty quoted key is allowed
 "" = "blank"     # VALID but discouraged
 '' = 'blank'     # VALID but discouraged
 
+# between bare and quoted key, best practice is to use bare keys except when absolutely necessary
+
+## dotted
+# dotted keys are a sequence of bare or quoted keys joined with a dot.
+# This allows for grouping similar properties together:
+name = "Orange"
+physical.color = "orange"
+physical.shape = "round"
+site."google.com" = true
+# In JSON land, that would give you the following structure:
+# {
+#   "name": "Orange",
+#   "physical": {
+#     "color": "orange",
+#     "shape": "round"
+#   },
+#   "site": {
+#     "google.com": true
+#   }
+# }
+# Tips: online TOML/JSON converter like this helps to understand TOML document structure
+# https://pseitz.github.io/toml-to-json-online-converter/
+
+other_kêys = "are permitted by spec but most implementations don't actually permit them"
+
+## When defining long dotted key, indirectly defined key can be wrote into.
+# Below indirectly makes the key "fruit" and "apple" into a table (more on table below).
+fruit.apple.smooth = true
+
+# So then you can add to the "fruit" and "apple" like so:
+fruit.orange = 2
+fruit.apple.amount = 1
+# In JSON land, that would give you the following structure:
+# {
+#   "fruit": {
+#     "orange": 2,
+#     "apple": {
+#       "amount": 1,
+#       "smooth": true
+#     }
+#   }
+# }
+
+# And obviously, you can not do this:
+fruit.apple = "something" # because that would be a duplicated key for 'fruit.apple'
+
+
 ##########
 # String #
 ##########
@@ -61,17 +121,19 @@ The first newline is trimmed in raw strings.
    is preserved. #! are preserved?
 '''
 
-# For binary data it is recommended that you use Base64, another ASCII or UTF8
+# Control characters other than tab are not permitted in a literal string.
+# Thus, 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 allowed.
-## Values that cannot be expressed as a series of digits are not allowed.
+# Integers can start with a +, a - or nothing.
+# Leading zeros are not allowed.
+# Hex, octal, and binary forms are allowed.
+# Values that cannot be expressed as a series of digits are not allowed.
 int1 = +42
 int2 = 0
 int3 = -21
@@ -80,10 +142,12 @@ int5 = 0o755
 int6 = 0b11011100
 integerRange = 64
 
-## You can use underscores to enhance readability. Each
-## underscore must be surrounded by at least one digit.
+# You can use underscores to enhance readability.
+# Each underscore must be surrounded by at least one digit on each side.
 int4 = 5_349_221
 int5 = 1_2_3_4_5     # VALID but discouraged
+int6 = _1_2_3        # INVALID
+
 
 #########
 # Float #
@@ -94,6 +158,7 @@ flt1 = 3.1415
 flt2 = -5e6
 flt3 = 6.626E-34
 
+
 ###########
 # Boolean #
 ###########
@@ -102,6 +167,7 @@ bool1 = true
 bool2 = false
 boolMustBeLowercase = true
 
+
 ############
 # Datetime #
 ############
@@ -111,6 +177,7 @@ date2 = 1979-05-26T15:32:00+08:00 # with RFC 3339/ISO 8601 offset
 date3 = 1979-05-27T07:32:00 # without offset
 date4 = 1979-05-27 # without offset or time
 
+
 ####################
 # COLLECTION TYPES #
 ####################
@@ -131,12 +198,13 @@ array5 = [
 # Table #
 #########
 
-# Tables (or hash tables or dictionaries) are collections of key/value
-# pairs. They appear in square brackets on a line by themselves.
+## Tables (also known as hash tables or dictionaries) are collections of key/value pairs.
+# They are defined by headers, with 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.
+
+## 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"
@@ -146,65 +214,107 @@ key2 = 123
 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.
+
+## Naming rules for tables 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" } } }
+# {
+#   "dog": {
+#     "tater.man": {
+#       "type": "pug"
+#     }
+#   }
+# }
+ 
 
-# Whitespace around dot-separated parts is ignored, however, best practice is to
+## 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
+
+## 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
-
-# Will generate the following in JSON:
-# { "a": {"b": {"c": 1}, "d": 2 } }
-
-# You cannot define any key or table more than once. Doing so is invalid.
 
+## Like keys, you cannot define a table more than once. Doing so is invalid.
 # DO NOT DO THIS
-[a]
-b = 1
+[fruit]
+apple = "red"
 
-[a]
-c = 2
+[fruit] # invalid: key duplication
+orange = "orange"
 
 # DO NOT DO THIS EITHER
-[a]
-b = 1
+[fruit]
+apple = "red"
 
-[a.b]
-c = 2
+[fruit.apple] # fruit.apple is a string, not a table, thus can not add key/value pair
+texture = "smooth"
 
-# All table names must be non-empty.
+
+## The whole TOML document is a top-level table, starts at the beginning of the 
+# document and ends just before the first table header (or EOF). Unlike other
+# tables, it is nameless and cannot be relocated.
+
+
+## Dotted keys create and define a table for each key part before the last one,
+# provided that such tables were not previously created. Examples:
+
+# This line also...
+fruit.apple.color = "red"
+# defines a table named fruit
+# defines a table named fruit.apple
+
+# Similarly, this line also...
+fruit.apple.taste.sweet = true
+# defines a table named fruit.apple.taste
+# fruit and fruit.apple were already created
+
+
+## Since tables cannot be defined more than once, redefining such tables using
+# a [table] header is not allowed. Likewise, using dotted keys to redefine tables
+# already defined in [table] form is not allowed. 
+[fruit]
+apple.color = "red"
+apple.taste.sweet = true
+# table named fruit, fruit.apple, fruit.apple.taste defined
+
+# so belows are invalid:
+[fruit.apple]  # INVALID
+[fruit.apple.taste]  # INVALID
+
+# The [table] form can, however, be used to define sub-tables within tables defined via dotted keys.
+[fruit]
+apple.color = "red"
+apple.taste.sweet = true
+# same as above, fruit, fruit.apple, fruit.apple.taste defined
+
+# below add sub-table named fruit.apple.texture
+[fruit.apple.texture]  # you can add sub-tables
+smooth = true
+
+
+## All table names must be non-empty.
 []     # INVALID
 [a.]   # INVALID
 [a..b] # INVALID
 [.b]   # INVALID
 [.]    # INVALID
 
+
 ################
 # Inline table #
 ################
 
+# Inline tables provide a more compact syntax for expressing tables.
+# They are intended to appear on a single line.
 inlineTables = { areEnclosedWith = "{ and }", a = { b = { c = { d = 1 } } } }
 point = { x = 1, y = 2 }
 usingMultiple = {
@@ -212,50 +322,55 @@ usingMultiple = {
   instead = "use normal TOML tables",
 }
 
+# this inline table:
+name = { first = "Tom", last = "Preston-Werner" }
+# is equivalent to this standard table:
+[name]
+first = "Tom"
+last = "Preston-Werner"
+
+
 ###################
 # Array of Tables #
 ###################
 
-# An array of tables can be expressed by using a table name in double brackets.
+## 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]]
+[[products]] # define array and first table element
 name = "array of table"
 sku = 738594937
 emptyTableAreAllowed = true
 
-[[products]]
+[[products]] # second element is an empty table
 
-[[products]]
+[[products]] # third table element
 name = "Nail"
 sku = 284758393
 color = "gray"
-```
 
-The equivalent in JSON would be:
+# The equivalent in JSON would be:
+# { 
+#   "products": [
+#     {
+#       "name": "array of table",
+#       "sku": 7385594937,
+#       "emptyTableAreAllowed": true
+#     },
+#     {},
+#     {
+#       "name": "Nail",
+#       "sku": 284758393,
+#       "color": "gray"
+#     }
+#   ]
+# }
 
-```json
-{ 
-  "products": [
-    {
-      "name": "array of table",
-      "sku": 7385594937,
-      "emptyTableAreAllowed": true
-    },
-    {},
-    {
-      "name": "Nail",
-      "sku": 284758393,
-      "color": "gray"
-    }
-  ]
-}
-```
 
-```toml
-# You can create nested arrays of tables as well. Each double-bracketed
+## 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" # I am a property in fruit table/map
@@ -278,30 +393,59 @@ The equivalent in JSON would be:
   [[fruit.color]]
     name = "yellow"
     note = "I am an array item in banana fruit's table/map"
-```
 
-The equivalent in JSON would be:
+# According to spec, indentation is treated as whitespace and ignored.
+# Here is just for better demonstration.
+
+# The equivalent in JSON would be:
+# {
+#   "fruit": [
+#     {
+#       "name": "apple",
+#       "geometry": { "shape": "round", "note": "..."},
+#       "color": [
+#         { "name": "red", "note": "..." },
+#         { "name": "green", "note": "..." }
+#       ]
+#     },
+#     {
+#       "name": "banana",
+#       "color": [
+#         { "name": "yellow", "note": "..." }
+#       ]
+#     }
+#   ]
+# }
+
+
+## The following TOML is invalid
+# this table by itself is subtable, but what unclear is its parent element type
+[fruit.physical]  
+color = "red"
+shape = "round"
+
+# and if this array of tables definition follows
+# parser will complain the key fruit is already defined
+[[fruit]] 
+name = "apple"
+
+# But otherwise this TOML would be valid
+# array of tables comes first
+[[fruit]]
+name = "apple"
+
+# the following is array's first element
+[fruit.physical]
+color = "red"
+shape = "round"
+
+# As spec explained:
+# If the parent of a table or array of tables is an array element, that element
+# must already have been defined before the child can be defined.
+# Use TOML/JSON Online converter to get the hang of it.
 
 ```
-{
-  "fruit": [
-    {
-      "name": "apple",
-      "geometry": { "shape": "round", "note": "..."},
-      "color": [
-        { "name": "red", "note": "..." },
-        { "name": "green", "note": "..." }
-      ]
-    },
-    {
-      "name": "banana",
-      "color": [
-        { "name": "yellow", "note": "..." }
-      ]
-    }
-  ]
-}
-```
+
 
 ### More Resources