Debian Codegraph @

internal/toml-test/specs/v1.0.0.md

raw
1 ![TOML Logo](logos/toml-200.png)
2
3 TOML v1.0.0
4 ===========
5
6 Tom's Obvious, Minimal Language.
7
8 By Tom Preston-Werner, Pradyun Gedam, et al.
9
10 Objectives
11 ----------
12
13 TOML aims to be a minimal configuration file format that's easy to read due to
14 obvious semantics. TOML is designed to map unambiguously to a hash table. TOML
15 should be easy to parse into data structures in a wide variety of languages.
16
17 Table of contents
18 -----------------
19
20 - [Spec](#spec)
21 - [Comment](#comment)
22 - [Key/Value Pair](#keyvalue-pair)
23 - [Keys](#keys)
24 - [String](#string)
25 - [Integer](#integer)
26 - [Float](#float)
27 - [Boolean](#boolean)
28 - [Offset Date-Time](#offset-date-time)
29 - [Local Date-Time](#local-date-time)
30 - [Local Date](#local-date)
31 - [Local Time](#local-time)
32 - [Array](#array)
33 - [Table](#table)
34 - [Inline Table](#inline-table)
35 - [Array of Tables](#array-of-tables)
36 - [Filename Extension](#filename-extension)
37 - [MIME Type](#mime-type)
38 - [ABNF Grammar](#abnf-grammar)
39
40 Spec
41 ----
42
43 * TOML is case-sensitive.
44 * A TOML file must be a valid UTF-8 encoded Unicode document.
45 * Whitespace means tab (0x09) or space (0x20).
46 * Newline means LF (0x0A) or CRLF (0x0D 0x0A).
47
48 Comment
49 -------
50
51 A hash symbol marks the rest of the line as a comment, except when inside a
52 string.
53
54 ```toml
55 # This is a full-line comment
56 key = "value" # This is a comment at the end of a line
57 another = "# This is not a comment"
58 ```
59
60 Control characters other than tab (U+0000 to U+0008, U+000A to U+001F, U+007F)
61 are not permitted in comments.
62
63 Key/Value Pair
64 --------------
65
66 The primary building block of a TOML document is the key/value pair.
67
68 Keys are on the left of the equals sign and values are on the right. Whitespace
69 is ignored around key names and values. The key, equals sign, and value must be
70 on the same line (though some values can be broken over multiple lines).
71
72 ```toml
73 key = "value"
74 ```
75
76 Values must have one of the following types.
77
78 - [String](#string)
79 - [Integer](#integer)
80 - [Float](#float)
81 - [Boolean](#boolean)
82 - [Offset Date-Time](#offset-date-time)
83 - [Local Date-Time](#local-date-time)
84 - [Local Date](#local-date)
85 - [Local Time](#local-time)
86 - [Array](#array)
87 - [Inline Table](#inline-table)
88
89 Unspecified values are invalid.
90
91 ```toml
92 key = # INVALID
93 ```
94
95 There must be a newline (or EOF) after a key/value pair. (See [Inline
96 Table](#inline-table) for exceptions.)
97
98 ```
99 first = "Tom" last = "Preston-Werner" # INVALID
100 ```
101
102 Keys
103 ----
104
105 A key may be either bare, quoted, or dotted.
106
107 **Bare keys** may only contain ASCII letters, ASCII digits, underscores, and
108 dashes (`A-Za-z0-9_-`). Note that bare keys are allowed to be composed of only
109 ASCII digits, e.g. `1234`, but are always interpreted as strings.
110
111 ```toml
112 key = "value"
113 bare_key = "value"
114 bare-key = "value"
115 1234 = "value"
116 ```
117
118 **Quoted keys** follow the exact same rules as either basic strings or literal
119 strings and allow you to use a much broader set of key names. Best practice is
120 to use bare keys except when absolutely necessary.
121
122 ```toml
123 "127.0.0.1" = "value"
124 "character encoding" = "value"
125 "ʎǝʞ" = "value"
126 'key2' = "value"
127 'quoted "value"' = "value"
128 ```
129
130 A bare key must be non-empty, but an empty quoted key is allowed (though
131 discouraged).
132
133 ```toml
134 = "no key name" # INVALID
135 "" = "blank" # VALID but discouraged
136 '' = 'blank' # VALID but discouraged
137 ```
138
139 **Dotted keys** are a sequence of bare or quoted keys joined with a dot. This
140 allows for grouping similar properties together:
141
142 ```toml
143 name = "Orange"
144 physical.color = "orange"
145 physical.shape = "round"
146 site."google.com" = true
147 ```
148
149 In JSON land, that would give you the following structure:
150
151 ```json
152 {
153 "name": "Orange",
154 "physical": {
155 "color": "orange",
156 "shape": "round"
157 },
158 "site": {
159 "google.com": true
160 }
161 }
162 ```
163
164 For details regarding the tables that dotted keys define, refer to the
165 [Table](#table) section below.
166
167 Whitespace around dot-separated parts is ignored. However, best practice is to
168 not use any extraneous whitespace.
169
170 ```toml
171 fruit.name = "banana" # this is best practice
172 fruit. color = "yellow" # same as fruit.color
173 fruit . flavor = "banana" # same as fruit.flavor
174 ```
175
176 Indentation is treated as whitespace and ignored.
177
178 Defining a key multiple times is invalid.
179
180 ```
181 # DO NOT DO THIS
182 name = "Tom"
183 name = "Pradyun"
184 ```
185
186 Note that bare keys and quoted keys are equivalent:
187
188 ```
189 # THIS WILL NOT WORK
190 spelling = "favorite"
191 "spelling" = "favourite"
192 ```
193
194 As long as a key hasn't been directly defined, you may still write to it and
195 to names within it.
196
197 ```
198 # This makes the key "fruit" into a table.
199 fruit.apple.smooth = true
200
201 # So then you can add to the table "fruit" like so:
202 fruit.orange = 2
203 ```
204
205 ```
206 # THE FOLLOWING IS INVALID
207
208 # This defines the value of fruit.apple to be an integer.
209 fruit.apple = 1
210
211 # But then this treats fruit.apple like it's a table.
212 # You can't turn an integer into a table.
213 fruit.apple.smooth = true
214 ```
215
216 Defining dotted keys out-of-order is discouraged.
217
218 ```toml
219 # VALID BUT DISCOURAGED
220
221 apple.type = "fruit"
222 orange.type = "fruit"
223
224 apple.skin = "thin"
225 orange.skin = "thick"
226
227 apple.color = "red"
228 orange.color = "orange"
229 ```
230
231 ```toml
232 # RECOMMENDED
233
234 apple.type = "fruit"
235 apple.skin = "thin"
236 apple.color = "red"
237
238 orange.type = "fruit"
239 orange.skin = "thick"
240 orange.color = "orange"
241 ```
242
243 Since bare keys can be composed of only ASCII integers, it is possible to write
244 dotted keys that look like floats but are 2-part dotted keys. Don't do this
245 unless you have a good reason to (you probably don't).
246
247 ```toml
248 3.14159 = "pi"
249 ```
250
251 The above TOML maps to the following JSON.
252
253 ```json
254 { "3": { "14159": "pi" } }
255 ```
256
257 String
258 ------
259
260 There are four ways to express strings: basic, multi-line basic, literal, and
261 multi-line literal. All strings must contain only valid UTF-8 characters.
262
263 **Basic strings** are surrounded by quotation marks (`"`). Any Unicode character
264 may be used except those that must be escaped: quotation mark, backslash, and
265 the control characters other than tab (U+0000 to U+0008, U+000A to U+001F,
266 U+007F).
267
268 ```toml
269 str = "I'm a string. \"You can quote me\". Name\tJos\u00E9\nLocation\tSF."
270 ```
271
272 For convenience, some popular characters have a compact escape sequence.
273
274 ```
275 \b - backspace (U+0008)
276 \t - tab (U+0009)
277 \n - linefeed (U+000A)
278 \f - form feed (U+000C)
279 \r - carriage return (U+000D)
280 \" - quote (U+0022)
281 \\ - backslash (U+005C)
282 \uXXXX - unicode (U+XXXX)
283 \UXXXXXXXX - unicode (U+XXXXXXXX)
284 ```
285
286 Any Unicode character may be escaped with the `\uXXXX` or `\UXXXXXXXX` forms.
287 The escape codes must be valid Unicode [scalar
288 values](https://unicode.org/glossary/#unicode_scalar_value).
289
290 All other escape sequences not listed above are reserved; if they are used, TOML
291 should produce an error.
292
293 Sometimes you need to express passages of text (e.g. translation files) or would
294 like to break up a very long string into multiple lines. TOML makes this easy.
295
296 **Multi-line basic strings** are surrounded by three quotation marks on each
297 side and allow newlines. A newline immediately following the opening delimiter
298 will be trimmed. All other whitespace and newline characters remain intact.
299
300 ```toml
301 str1 = """
302 Roses are red
303 Violets are blue"""
304 ```
305
306 TOML parsers should feel free to normalize newline to whatever makes sense for
307 their platform.
308
309 ```toml
310 # On a Unix system, the above multi-line string will most likely be the same as:
311 str2 = "Roses are red\nViolets are blue"
312
313 # On a Windows system, it will most likely be equivalent to:
314 str3 = "Roses are red\r\nViolets are blue"
315 ```
316
317 For writing long strings without introducing extraneous whitespace, use a "line
318 ending backslash". When the last non-whitespace character on a line is an
319 unescaped `\`, it will be trimmed along with all whitespace (including newlines)
320 up to the next non-whitespace character or closing delimiter. All of the escape
321 sequences that are valid for basic strings are also valid for multi-line basic
322 strings.
323
324 ```toml
325 # The following strings are byte-for-byte equivalent:
326 str1 = "The quick brown fox jumps over the lazy dog."
327
328 str2 = """
329 The quick brown \
330
331
332 fox jumps over \
333 the lazy dog."""
334
335 str3 = """\
336 The quick brown \
337 fox jumps over \
338 the lazy dog.\
339 """
340 ```
341
342 Any Unicode character may be used except those that must be escaped: backslash
343 and the control characters other than tab, line feed, and carriage return
344 (U+0000 to U+0008, U+000B, U+000C, U+000E to U+001F, U+007F).
345
346 You can write a quotation mark, or two adjacent quotation marks, anywhere inside
347 a multi-line basic string. They can also be written just inside the delimiters.
348
349 ```toml
350 str4 = """Here are two quotation marks: "". Simple enough."""
351 # str5 = """Here are three quotation marks: """.""" # INVALID
352 str5 = """Here are three quotation marks: ""\"."""
353 str6 = """Here are fifteen quotation marks: ""\"""\"""\"""\"""\"."""
354
355 # "This," she said, "is just a pointless statement."
356 str7 = """"This," she said, "is just a pointless statement.""""
357 ```
358
359 If you're a frequent specifier of Windows paths or regular expressions, then
360 having to escape backslashes quickly becomes tedious and error-prone. To help,
361 TOML supports literal strings which do not allow escaping at all.
362
363 **Literal strings** are surrounded by single quotes. Like basic strings, they
364 must appear on a single line:
365
366 ```toml
367 # What you see is what you get.
368 winpath = 'C:\Users\nodejs\templates'
369 winpath2 = '\\ServerX\admin$\system32\'
370 quoted = 'Tom "Dubs" Preston-Werner'
371 regex = '<\i\c*\s*>'
372 ```
373
374 Since there is no escaping, there is no way to write a single quote inside a
375 literal string enclosed by single quotes. Luckily, TOML supports a multi-line
376 version of literal strings that solves this problem.
377
378 **Multi-line literal strings** are surrounded by three single quotes on each
379 side and allow newlines. Like literal strings, there is no escaping whatsoever.
380 A newline immediately following the opening delimiter will be trimmed. All other
381 content between the delimiters is interpreted as-is without modification.
382
383 ```toml
384 regex2 = '''I [dw]on't need \d{2} apples'''
385 lines = '''
386 The first newline is
387 trimmed in raw strings.
388 All other whitespace
389 is preserved.
390 '''
391 ```
392
393 You can write 1 or 2 single quotes anywhere within a multi-line literal string,
394 but sequences of three or more single quotes are not permitted.
395
396 ```toml
397 quot15 = '''Here are fifteen quotation marks: """""""""""""""'''
398
399 # apos15 = '''Here are fifteen apostrophes: '''''''''''''''''' # INVALID
400 apos15 = "Here are fifteen apostrophes: '''''''''''''''"
401
402 # 'That,' she said, 'is still pointless.'
403 str = ''''That,' she said, 'is still pointless.''''
404 ```
405
406 Control characters other than tab are not permitted in a literal string. Thus,
407 for binary data, it is recommended that you use Base64 or another suitable ASCII
408 or UTF-8 encoding. The handling of that encoding will be application-specific.
409
410 Integer
411 -------
412
413 Integers are whole numbers. Positive numbers may be prefixed with a plus sign.
414 Negative numbers are prefixed with a minus sign.
415
416 ```toml
417 int1 = +99
418 int2 = 42
419 int3 = 0
420 int4 = -17
421 ```
422
423 For large numbers, you may use underscores between digits to enhance
424 readability. Each underscore must be surrounded by at least one digit on each
425 side.
426
427 ```toml
428 int5 = 1_000
429 int6 = 5_349_221
430 int7 = 53_49_221 # Indian number system grouping
431 int8 = 1_2_3_4_5 # VALID but discouraged
432 ```
433
434 Leading zeros are not allowed. Integer values `-0` and `+0` are valid and
435 identical to an unprefixed zero.
436
437 Non-negative integer values may also be expressed in hexadecimal, octal, or
438 binary. In these formats, leading `+` is not allowed and leading zeros are
439 allowed (after the prefix). Hex values are case-insensitive. Underscores are
440 allowed between digits (but not between the prefix and the value).
441
442 ```toml
443 # hexadecimal with prefix `0x`
444 hex1 = 0xDEADBEEF
445 hex2 = 0xdeadbeef
446 hex3 = 0xdead_beef
447
448 # octal with prefix `0o`
449 oct1 = 0o01234567
450 oct2 = 0o755 # useful for Unix file permissions
451
452 # binary with prefix `0b`
453 bin1 = 0b11010110
454 ```
455
456 Arbitrary 64-bit signed integers (from −2^63 to 2^63−1) should be accepted and
457 handled losslessly. If an integer cannot be represented losslessly, an error
458 must be thrown.
459
460 Float
461 -----
462
463 Floats should be implemented as IEEE 754 binary64 values.
464
465 A float consists of an integer part (which follows the same rules as decimal
466 integer values) followed by a fractional part and/or an exponent part. If both a
467 fractional part and exponent part are present, the fractional part must precede
468 the exponent part.
469
470 ```toml
471 # fractional
472 flt1 = +1.0
473 flt2 = 3.1415
474 flt3 = -0.01
475
476 # exponent
477 flt4 = 5e+22
478 flt5 = 1e06
479 flt6 = -2E-2
480
481 # both
482 flt7 = 6.626e-34
483 ```
484
485 A fractional part is a decimal point followed by one or more digits.
486
487 An exponent part is an E (upper or lower case) followed by an integer part
488 (which follows the same rules as decimal integer values but may include leading
489 zeros).
490
491 The decimal point, if used, must be surrounded by at least one digit on each
492 side.
493
494 ```
495 # INVALID FLOATS
496 invalid_float_1 = .7
497 invalid_float_2 = 7.
498 invalid_float_3 = 3.e+20
499 ```
500
501 Similar to integers, you may use underscores to enhance readability. Each
502 underscore must be surrounded by at least one digit.
503
504 ```toml
505 flt8 = 224_617.445_991_228
506 ```
507
508 Float values `-0.0` and `+0.0` are valid and should map according to IEEE 754.
509
510 Special float values can also be expressed. They are always lowercase.
511
512 ```toml
513 # infinity
514 sf1 = inf # positive infinity
515 sf2 = +inf # positive infinity
516 sf3 = -inf # negative infinity
517
518 # not a number
519 sf4 = nan # actual sNaN/qNaN encoding is implementation-specific
520 sf5 = +nan # same as `nan`
521 sf6 = -nan # valid, actual encoding is implementation-specific
522 ```
523
524 Boolean
525 -------
526
527 Booleans are just the tokens you're used to. Always lowercase.
528
529 ```toml
530 bool1 = true
531 bool2 = false
532 ```
533
534 Offset Date-Time
535 ----------------
536
537 To unambiguously represent a specific instant in time, you may use an [RFC
538 3339](https://tools.ietf.org/html/rfc3339) formatted date-time with offset.
539
540 ```toml
541 odt1 = 1979-05-27T07:32:00Z
542 odt2 = 1979-05-27T00:32:00-07:00
543 odt3 = 1979-05-27T00:32:00.999999-07:00
544 ```
545
546 For the sake of readability, you may replace the T delimiter between date and
547 time with a space character (as permitted by RFC 3339 section 5.6).
548
549 ```toml
550 odt4 = 1979-05-27 07:32:00Z
551 ```
552
553 Millisecond precision is required. Further precision of fractional seconds is
554 implementation-specific. If the value contains greater precision than the
555 implementation can support, the additional precision must be truncated, not
556 rounded.
557
558 Local Date-Time
559 ---------------
560
561 If you omit the offset from an [RFC 3339](https://tools.ietf.org/html/rfc3339)
562 formatted date-time, it will represent the given date-time without any relation
563 to an offset or timezone. It cannot be converted to an instant in time without
564 additional information. Conversion to an instant, if required, is
565 implementation-specific.
566
567 ```toml
568 ldt1 = 1979-05-27T07:32:00
569 ldt2 = 1979-05-27T00:32:00.999999
570 ```
571
572 Millisecond precision is required. Further precision of fractional seconds is
573 implementation-specific. If the value contains greater precision than the
574 implementation can support, the additional precision must be truncated, not
575 rounded.
576
577 Local Date
578 ----------
579
580 If you include only the date portion of an
581 [RFC 3339](https://tools.ietf.org/html/rfc3339) formatted date-time, it will
582 represent that entire day without any relation to an offset or timezone.
583
584 ```toml
585 ld1 = 1979-05-27
586 ```
587
588 Local Time
589 ----------
590
591 If you include only the time portion of an [RFC
592 3339](https://tools.ietf.org/html/rfc3339) formatted date-time, it will
593 represent that time of day without any relation to a specific day or any offset
594 or timezone.
595
596 ```toml
597 lt1 = 07:32:00
598 lt2 = 00:32:00.999999
599 ```
600
601 Millisecond precision is required. Further precision of fractional seconds is
602 implementation-specific. If the value contains greater precision than the
603 implementation can support, the additional precision must be truncated, not
604 rounded.
605
606 Array
607 -----
608
609 Arrays are square brackets with values inside. Whitespace is ignored. Elements
610 are separated by commas. Arrays can contain values of the same data types as
611 allowed in key/value pairs. Values of different types may be mixed.
612
613 ```toml
614 integers = [ 1, 2, 3 ]
615 colors = [ "red", "yellow", "green" ]
616 nested_arrays_of_ints = [ [ 1, 2 ], [3, 4, 5] ]
617 nested_mixed_array = [ [ 1, 2 ], ["a", "b", "c"] ]
618 string_array = [ "all", 'strings', """are the same""", '''type''' ]
619
620 # Mixed-type arrays are allowed
621 numbers = [ 0.1, 0.2, 0.5, 1, 2, 5 ]
622 contributors = [
623 "Foo Bar <[email protected]>",
624 { name = "Baz Qux", email = "[email protected]", url = "https://example.com/bazqux" }
625 ]
626 ```
627
628 Arrays can span multiple lines. A terminating comma (also called a trailing
629 comma) is permitted after the last value of the array. Any number of newlines
630 and comments may precede values, commas, and the closing bracket. Indentation
631 between array values and commas is treated as whitespace and ignored.
632
633 ```toml
634 integers2 = [
635 1, 2, 3
636 ]
637
638 integers3 = [
639 1,
640 2, # this is ok
641 ]
642 ```
643
644 Table
645 -----
646
647 Tables (also known as hash tables or dictionaries) are collections of key/value
648 pairs. They are defined by headers, with square brackets on a line by
649 themselves. You can tell headers apart from arrays because arrays are only ever
650 values.
651
652 ```toml
653 [table]
654 ```
655
656 Under that, and until the next header or EOF, are the key/values of that table.
657 Key/value pairs within tables are not guaranteed to be in any specific order.
658
659 ```toml
660 [table-1]
661 key1 = "some string"
662 key2 = 123
663
664 [table-2]
665 key1 = "another string"
666 key2 = 456
667 ```
668
669 Naming rules for tables are the same as for keys (see definition of
670 [Keys](#keys) above).
671
672 ```toml
673 [dog."tater.man"]
674 type.name = "pug"
675 ```
676
677 In JSON land, that would give you the following structure:
678
679 ```json
680 { "dog": { "tater.man": { "type": { "name": "pug" } } } }
681 ```
682
683 Whitespace around the key is ignored. However, best practice is to not use any
684 extraneous whitespace.
685
686 ```toml
687 [a.b.c] # this is best practice
688 [ d.e.f ] # same as [d.e.f]
689 [ g . h . i ] # same as [g.h.i]
690 [ j . "ʞ" . 'l' ] # same as [j."ʞ".'l']
691 ```
692
693 Indentation is treated as whitespace and ignored.
694
695 You don't need to specify all the super-tables if you don't want to. TOML knows
696 how to do it for you.
697
698 ```toml
699 # [x] you
700 # [x.y] don't
701 # [x.y.z] need these
702 [x.y.z.w] # for this to work
703
704 [x] # defining a super-table afterward is ok
705 ```
706
707 Empty tables are allowed and simply have no key/value pairs within them.
708
709 Like keys, you cannot define a table more than once. Doing so is invalid.
710
711 ```
712 # DO NOT DO THIS
713
714 [fruit]
715 apple = "red"
716
717 [fruit]
718 orange = "orange"
719 ```
720
721 ```
722 # DO NOT DO THIS EITHER
723
724 [fruit]
725 apple = "red"
726
727 [fruit.apple]
728 texture = "smooth"
729 ```
730
731 Defining tables out-of-order is discouraged.
732
733 ```toml
734 # VALID BUT DISCOURAGED
735 [fruit.apple]
736 [animal]
737 [fruit.orange]
738 ```
739
740 ```toml
741 # RECOMMENDED
742 [fruit.apple]
743 [fruit.orange]
744 [animal]
745 ```
746
747 The top-level table, also called the root table, starts at the beginning of the
748 document and ends just before the first table header (or EOF). Unlike other
749 tables, it is nameless and cannot be relocated.
750
751 ```toml
752 # Top-level table begins.
753 name = "Fido"
754 breed = "pug"
755
756 # Top-level table ends.
757 [owner]
758 name = "Regina Dogman"
759 member_since = 1999-08-04
760 ```
761
762 Dotted keys create and define a table for each key part before the last one,
763 provided that such tables were not previously created.
764
765 ```toml
766 fruit.apple.color = "red"
767 # Defines a table named fruit
768 # Defines a table named fruit.apple
769
770 fruit.apple.taste.sweet = true
771 # Defines a table named fruit.apple.taste
772 # fruit and fruit.apple were already created
773 ```
774
775 Since tables cannot be defined more than once, redefining such tables using a
776 `[table]` header is not allowed. Likewise, using dotted keys to redefine tables
777 already defined in `[table]` form is not allowed. The `[table]` form can,
778 however, be used to define sub-tables within tables defined via dotted keys.
779
780 ```toml
781 [fruit]
782 apple.color = "red"
783 apple.taste.sweet = true
784
785 # [fruit.apple] # INVALID
786 # [fruit.apple.taste] # INVALID
787
788 [fruit.apple.texture] # you can add sub-tables
789 smooth = true
790 ```
791
792 Inline Table
793 ------------
794
795 Inline tables provide a more compact syntax for expressing tables. They are
796 especially useful for grouped data that can otherwise quickly become verbose.
797 Inline tables are fully defined within curly braces: `{` and `}`. Within the
798 braces, zero or more comma-separated key/value pairs may appear. Key/value pairs
799 take the same form as key/value pairs in standard tables. All value types are
800 allowed, including inline tables.
801
802 Inline tables are intended to appear on a single line. A terminating comma (also
803 called trailing comma) is not permitted after the last key/value pair in an
804 inline table. No newlines are allowed between the curly braces unless they are
805 valid within a value. Even so, it is strongly discouraged to break an inline
806 table onto multiples lines. If you find yourself gripped with this desire, it
807 means you should be using standard tables.
808
809 ```toml
810 name = { first = "Tom", last = "Preston-Werner" }
811 point = { x = 1, y = 2 }
812 animal = { type.name = "pug" }
813 ```
814
815 The inline tables above are identical to the following standard table
816 definitions:
817
818 ```toml
819 [name]
820 first = "Tom"
821 last = "Preston-Werner"
822
823 [point]
824 x = 1
825 y = 2
826
827 [animal]
828 type.name = "pug"
829 ```
830
831 Inline tables are fully self-contained and define all keys and sub-tables within
832 them. Keys and sub-tables cannot be added outside the braces.
833
834 ```toml
835 [product]
836 type = { name = "Nail" }
837 # type.edible = false # INVALID
838 ```
839
840 Similarly, inline tables cannot be used to add keys or sub-tables to an
841 already-defined table.
842
843 ```toml
844 [product]
845 type.name = "Nail"
846 # type = { edible = false } # INVALID
847 ```
848
849 Array of Tables
850 ---------------
851
852 The last syntax that has not yet been described allows writing arrays of tables.
853 These can be expressed by using a header with a name in double brackets. The
854 first instance of that header defines the array and its first table element, and
855 each subsequent instance creates and defines a new table element in that array.
856 The tables are inserted into the array in the order encountered.
857
858 ```toml
859 [[products]]
860 name = "Hammer"
861 sku = 738594937
862
863 [[products]] # empty table within the array
864
865 [[products]]
866 name = "Nail"
867 sku = 284758393
868
869 color = "gray"
870 ```
871
872 In JSON land, that would give you the following structure.
873
874 ```json
875 {
876 "products": [
877 { "name": "Hammer", "sku": 738594937 },
878 { },
879 { "name": "Nail", "sku": 284758393, "color": "gray" }
880 ]
881 }
882 ```
883
884 Any reference to an array of tables points to the most recently defined table
885 element of the array. This allows you to define sub-tables, and even sub-arrays
886 of tables, inside the most recent table.
887
888 ```toml
889 [[fruits]]
890 name = "apple"
891
892 [fruits.physical] # subtable
893 color = "red"
894 shape = "round"
895
896 [[fruits.varieties]] # nested array of tables
897 name = "red delicious"
898
899 [[fruits.varieties]]
900 name = "granny smith"
901
902
903 [[fruits]]
904 name = "banana"
905
906 [[fruits.varieties]]
907 name = "plantain"
908 ```
909
910 The above TOML maps to the following JSON.
911
912 ```json
913 {
914 "fruits": [
915 {
916 "name": "apple",
917 "physical": {
918 "color": "red",
919 "shape": "round"
920 },
921 "varieties": [
922 { "name": "red delicious" },
923 { "name": "granny smith" }
924 ]
925 },
926 {
927 "name": "banana",
928 "varieties": [
929 { "name": "plantain" }
930 ]
931 }
932 ]
933 }
934 ```
935
936 If the parent of a table or array of tables is an array element, that element
937 must already have been defined before the child can be defined. Attempts to
938 reverse that ordering must produce an error at parse time.
939
940 ```
941 # INVALID TOML DOC
942 [fruit.physical] # subtable, but to which parent element should it belong?
943 color = "red"
944 shape = "round"
945
946 [[fruit]] # parser must throw an error upon discovering that "fruit" is
947 # an array rather than a table
948 name = "apple"
949 ```
950
951 Attempting to append to a statically defined array, even if that array is empty,
952 must produce an error at parse time.
953
954 ```
955 # INVALID TOML DOC
956 fruits = []
957
958 [[fruits]] # Not allowed
959 ```
960
961 Attempting to define a normal table with the same name as an already established
962 array must produce an error at parse time. Attempting to redefine a normal table
963 as an array must likewise produce a parse-time error.
964
965 ```
966 # INVALID TOML DOC
967 [[fruits]]
968 name = "apple"
969
970 [[fruits.varieties]]
971 name = "red delicious"
972
973 # INVALID: This table conflicts with the previous array of tables
974 [fruits.varieties]
975 name = "granny smith"
976
977 [fruits.physical]
978 color = "red"
979 shape = "round"
980
981 # INVALID: This array of tables conflicts with the previous table
982 [[fruits.physical]]
983 color = "green"
984 ```
985
986 You may also use inline tables where appropriate:
987
988 ```toml
989 points = [ { x = 1, y = 2, z = 3 },
990 { x = 7, y = 8, z = 9 },
991 { x = 2, y = 4, z = 8 } ]
992 ```
993
994 Filename Extension
995 ------------------
996
997 TOML files should use the extension `.toml`.
998
999 MIME Type
1000 ---------
1001
1002 When transferring TOML files over the internet, the appropriate MIME type is
1003 `application/toml`.
1004
1005 ABNF Grammar
1006 ------------
1007
1008 A formal description of TOML's syntax is available, as a separate [ABNF file][abnf].
1009
1010 [abnf]: https://github.com/toml-lang/toml/blob/1.0.0/toml.abnf