TOML (Tom’s Obvious, Minimal Language) is a popular configuration language that’s easy to read and write, with a focus on simplicity and minimalism. If you’re working with TOML for configuration files or settings, understanding how arrays work is crucial. In this guide, we’ll explore TOML arrays in detail, covering everything from simple arrays to nested structures and arrays containing different data types.

What Is an Array in TOML?

In TOML, an array is simply a collection of values. You define an array by placing the values inside square brackets ([ ]). These values can be of the same type, like a list of integers, or they can be mixed types, like strings, numbers, and objects. Arrays are an essential part of TOML, as they help organize data in a readable and structured way.

Basic Array Syntax in TOML

Let’s start with the basics of arrays in TOML. Here’s the syntax:

array_name = [ value1, value2, value3 ]  # it's just syntax so toml validation failed 

The values inside the array are separated by commas, and the array itself is enclosed in square brackets. Whitespace (spaces and newlines) between the elements doesn’t affect the array, so you can format the array in any way that makes it more readable.

Examples

Simple Array of Integers

integers = [ 1, 2, 3, 4 ]

Here,

• integers is the name of the array.
• The array contains four integer values: 1, 2, 3, and 4.

Simple Array of Strings

fruits = [ "apple", "banana", "cherry" ]

• fruits is an array of strings.
• The array contains the values "apple", "banana", and "cherry".

Mixed-Type Arrays in TOML

TOML arrays are not limited to a single data type. You can mix different types of values in a single array. This allows for more complex data structures, depending on your needs.

Mixed-Type Array with Numbers and Strings

mixed_array = [ 1, 2.5, "hello", 3.7, "world" ]

In this array:

• The first element is an integer (1).
• The second element is a floating-point number (2.5).
• The third element is a string ("hello").
• The fourth element is another floating-point number (3.7).
• The fifth element is a string ("world").

By allowing mixed types, TOML provides flexibility to store various data formats in one array.

Nested Arrays in TOML

You can create more complex arrays by nesting arrays inside other arrays. A nested array is an array that contains other arrays as its elements.

Nested Arrays of Integers

nested_integers = [ [ 1, 2 ], [ 3, 4, 5 ] ]

Here,

nested_integers is an array that holds two sub-arrays.

• The first sub-array is [ 1, 2 ].
• The second sub-array is [ 3, 4, 5 ].

This makes nested_integers a two-dimensional array, where each element is itself an array.

Nested Arrays with Mixed Types

mixed_nested = [ [ 1, 2 ], ["a", "b", "c"] ]

Here,

mixed_nested is an array with two elements:

• The first element is an array of integers [1, 2].
• The second element is an array of strings ["a", "b", "c"].

TOML allows you to mix different data types within nested arrays, which adds flexibility when organizing data.

Arrays of Objects in TOML

One of the powerful features of TOML arrays is that they can store objects as their elements. Objects in TOML are essentially key-value pairs, and they are enclosed in curly braces ({ }).

Array of Objects

contributors = [
  { name = "Amol", role = "Developer" },
  { name = "Niyati", role = "Designer" }
]

Here,

contributors is an array of objects.

• Each object has two keys: name and role.
• The first object represents "Amol", who is a "Developer".
• The second object represents "Niyati", who is a "Designer".

Arrays of objects allow you to group related data together in a structured way.

Array of Objects with Multiple Keys

team_members = [
  "softAai Tech Team",
  { name = "Amol", email = "[email protected]", url = "https://amol.softaai.com" },
  { name = "Niyati", email = "[email protected]", url = "https://niyati.softaai.com" }
]

In this case:

• Each object contains name, email, and url as keys, representing team members’ details.
• An additional string value (softAai Tech Team) is added just to represent its mixed type array. It’s also possible.

Empty Arrays in TOML

TOML also supports empty arrays, which can be useful when you don’t have any values to store initially but still need to define the array.

empty_array = []

Here,

• empty_array is just an empty array with no values inside.

Formatting Arrays in TOML

TOML is flexible when it comes to formatting arrays. You can span arrays across multiple lines, add comments, and even include trailing commas. This makes TOML more user-friendly, especially for larger files.

Multi-line Array with Comments

numbers = [
  1,  # The first value
  2,  # The second value
  3,  # The third value
  4   # The fourth value
]

Here,

• The array spans across multiple lines for readability.
• Each element has a comment next to it explaining what the value represents.

Trailing Comma in Arrays

numbers = [
  1,
  2,
  3,  # Trailing comma is allowed
]

The trailing comma after 3 is allowed, making it easier to add or remove values in the future without worrying about missing commas.

Newlines and Comments Before Values

numbers = [
  
  # This is the first number
  1,
  
  # This is the second number
  2,
  
  # This is the third number
  3
  
]  # Closing bracket can also have a comment

In this example,

• Blank lines before values: Notice how there’s an empty line before the first value (1).
• Comments before values: Each number has a comment above it.
• Closing bracket with a comment: The closing bracket (]) can also have a comment next to it.

This flexibility allows you to structure your TOML file in a way that’s easy to read and maintain without affecting the actual data.

Practical Use of Arrays in TOML

Arrays are frequently used in TOML files to represent lists of data, such as configurations for software, lists of contributors, or settings in an application. For example:

dependencies = [
  "numpy",
  "pandas",
  "requests"
]

In this case:

• dependencies is an array listing the names of required libraries for a project.
• numpy: A fundamental package for numerical computing in Python.
• pandas: A powerful library for data manipulation and analysis.
• requests: A library for making HTTP requests, essential for interacting with web APIs.

Configuring a Web Server

ports = [8080, 443, 3000]
allowed_ips = ["192.168.1.1", "10.0.0.2"]

• ports defines the available ports.
• allowed_ips specifies which IPs can access the server.

Best Practices for Using TOML Arrays

1. Use homogeneous arrays whenever possible — This keeps data consistent.
2. Use multiline arrays for readability — Especially useful for long lists.
3. Avoid excessive nesting — Deeply nested arrays or tables can make TOML difficult to read and maintain.

Conclusion

TOML arrays are a powerful and flexible feature that allows you to store various types of data in a structured, easy-to-read format. Whether you’re dealing with simple lists, nested arrays, mixed data types, or even arrays of objects, TOML provides a straightforward way to organize and manage data in configuration files.

By understanding how arrays work in TOML, you can harness the full potential of this configuration language to structure your data efficiently and clearly. Whether you’re building configuration files for a small project or managing more complex data sets, TOML’s array syntax will help you keep things organized.