Debian Codegraph @

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

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