Exploring Tables in TOML

00:00 Tables in TOML. You’ve learned that a TOML document consists of one or more key-value pairs. When represented in a programming language, these should be stored in a hash table data structure. In Python, that would be a dictionary or another dictionary-like data structure.

00:17 To organize your key-value pairs, you can use tables. TOML supports three different ways of specifying tables. The end results will be the same independently of how you represent your tables, but the different tables do have slightly different use cases.

00:33 Use regular tables with headers in most cases, use dotted key tables when you need to specify a few key-value pairs that are closely tied to their parent table, and use inline tables for very small tables with up to three key-value pairs where the data makes up a clearly defined entity.

00:51 The table representations are mostly interchangeable. You should default to regular tables and only switch to dotted or inline tables when you think it improves your configuration’s readability or clarifies your intent.

01:04 Let’s take a look at how these different table types look in practice. Regular tables are defined by adding a table header above the key-value pairs. A header is a key without a value wrapped inside square brackets. On screen, you can see that three tables have been defined.

01:21 The tables are named [user], [constant], and [server]. The contents or value of a table are all the key-value pairs listed below the header and above the next one. [constant] and [server] only contain one nested key-value pair each. Dotted key tables are also in use in this configuration.

01:40 Inside the user section, you can see that dots are in use.

01:45 The dot in the keys creates a table named by the part of the key before the dot. You can also represent the same part of the configuration by nesting regular tables as seen here.

01:59 Indentation isn’t important in TOML, but you can use it to represent the nesting of the tables. You can see that the user table contains two sub-tables, player_x and player_O.

02:11 Each of those sub-tables contains one key-value pair.

02:17 You can nest TOML tables arbitrarily deep. For example, a key or table header such as [player.x.color.name] represents name within a color table within an x table within the player table.

02:30 Note that you need to use a dotted key in the header of nested tables and name all of the intermediate tables. This makes TOML header specifications quite verbose.

02:42 Now let’s look at the same data represented in three different ways firstly, starting with nested regular tables. This representation makes it very clear that you have two different player tables.

02:54 You don’t need to explicitly define tables that only contain sub-tables and no regular keys. Compare the nested tables with the dotted key configuration.

03:05 This is shorter and more concise than nested tables, but the structure is less clear and you need to expend some effort on parsing the keys before you realize there are two player tables nested within [user].

03:16 The dotted tables are more beneficial when you have a few nested tables with one key each, such as the early example with color sub-keys.

03:25 Finally, inline tables. An inline table is defined with curly braces wrapped around comma-separated key-value pairs. In this example, the inline table brings a nice balance of readability and compactness as the grouping of the player table becomes clear.

03:42 Inline tables should only be used sparingly and mostly in cases where, like this, a table represents a small and well-defined entity such as a player. Inline tables are intentionally limited compared to regular tables.

03:54 In particular, an inline table must be written on one line in the TOML file, and you can’t use conveniences such as trailing commas. On screen, you can see the three previous examples representing the same data for comparison purposes.

04:13 In general, you can define your tables in any order and you should strive to order your configuration in a way that makes sense to users. A TOML document is represented by a nameless root table that contains all other tables and key-value pairs.

04:27 Key-value pairs that you write at the top of your TOML configuration before any table header are stored directly in the root table. Here, title is a key in the root table, [constant] is a table that’s nested within the root table, and board_size is a key in the [constant] table.

04:45 Be aware that a table includes all key-value pairs written between its header and the next table header. In practice, this means that you must define nested sub-tables below the key-value pairs belonging to the table.

04:58 Consider the document seen on screen. The indentation suggests that background_color is supposed to be a key in the [user] table, but TOML will ignore the indentation and checks only the table headers.

05:11 As a result of this, background_color is part of user.player_o. To correct this, background _color should be defined before the nested tables.

05:22 Now, background_color is a key in [user] as intended.

05:28 If you use a dotted key table, then you can more freely use any order of keys. Now, there are no explicit table headers except for user, so background_colorwill be a key in the [user] table.

05:41 You’ve learned about the basic data types in TOML and how you can use tables to organize your data. In the next section of the course, you’ll see the final data types that you can play with in your TOML documents.