Package selection guidance compiled from public package information, community data, and project usage.
A Flutter/Dart package for parsing and encoding TOML (Tom's Obvious, Minimal Language) configuration files, compliant with TOML v1.0.0. It enables seamless reading and writing of structured configuration data in a human-readable format. Ideal for apps requiring external configuration management, such as environment settings or app preferences. The package supports all major platforms including Android, iOS, Web, macOS, Windows, and Linux. It is lightweight and integrates easily via pub.dev.
Use cases
Reading application configuration files
Writing config data in TOML format
Storing environment-specific settings
Migrating from JSON/YAML to TOML
Cross-platform configuration management
Key features
TOML v1.0.0 compliance
Support for nested tables and arrays
Easy-to-use parse and encode methods
Platform-agnostic implementation
Lightweight and fast
Suitable for
Apps needing structured config files
Developers preferring TOML over JSON/YAML
Cross-platform projects
Configuration-driven applications
CLI tools with config needs
Considerations
Not suitable for binary data storage
Limited to configuration use cases
Requires valid TOML syntax
No built-in validation beyond parsing
Best used with static or known schema configurations
Original README
Original README snapshot from the linked source repository. Visit the repository for the latest content.
toml.dart
This package provides an implementation of a TOML parser and encoder for Dart.
It currently supports version 1.1.0 of the TOML specification.
To get started add toml as a dependency to your pubspec.yaml and run the dart pub get or flutter pub get command.
dependencies:toml:"^0.18.0"
Usage
The toml.dart package can be used for loading, decoding and encoding TOML documents.
To get started, just add the following import.
import'package:toml/toml.dart';
The subsequent sections describe how to use the library in more detail.
Additional examples can be found in the ./example directory.
Loading TOML
In order to load a TOML document, invoke the static TomlDocument.load method and pass the name of the configuration file to load.
The method returns a Future of the loaded TomlDocument.
When the code is running in the browser, package:web is used to fetch the configuration file via HTTP.
When the code is running on the Dart VM or natively, the file is loaded from the local file system.
If the loaded TOML file contains a syntax error, a TomlParserException is thrown.
Sometimes the two default mechanisms for loading TOML documents with TomlDocument.load are not sufficient.
In those cases, you can simply load the contents of the configuration file yourself and parse them as a TOML document manually using the static TomlDocument.parse function.
If the loaded TOML file contains a syntax error, a TomlParserException is thrown.
An example for writing a custom configuration file loader and parsing the loaded file manually can be found in ./example/toml_parser.
Decoding TOML
In the last two subsections we've learned how to load or parse a TomlDocument.
Such a TomlDocument is an abstract representation of the syntax of a TOML document.
In order to access the configuration options that are stored in the TOML document, we first have to convert it to a hash map with the TomlDocument.toMap method.
voidmain() {
var config = TomlDocument.parse('...').toMap();
// ...
}
If the TOML document is semantically invalid, a TomlException is thrown.
In the next section the type and structure of the generated hash map will be elaborated in more detail.
Encoding TOML
This package also includes a TOML encoder that can convert a hash map to a TOML document.
Simply use the TomlDocument.fromMap factory constructor to convert the hash map into the internal representation.
The resulting document can be converted to a TOML encoded string using the toString method.
The type and structure of the hash map should match the format described in the next section.
Additionally, the map may contain arbitrary keys and values that implement the TomlEncodableKey and TomlEncodableValue interfaces, respectively.
Classes which implement those interfaces must define a toTomlKey or toTomlValue method, whose return value is either implements the interface itself or is natively encodable by TOML.
If an object cannot be encoded as a TOML key or value, a TomlUnknownKeyTypeException or TomlUnknownValueTypeException is thrown by TomlDocument.fromMap.
An example for using the encoder and the TomlEncodableValue interface to encode a Map can be found in ./example/toml_encoder.
Data Structure
This section describes how the decoder (i.e., TomlDocument.toMap) maps TOML values to Dart values and which Dart values are accepted by the encoder (i.e., TomlDocument.fromMap).
Table and Inline Table
TOML documents and tables including inline tables are represented through nested Map objects whose keys are Strings and values dynamic representations of the corresponding TOML value or sub-table.
The encoder does not require all keys to have the static type String.
A map of type Map<MyKey, dynamic> can be encoded, provided that the class MyKey implements the TomlEncodableKey interface.
The encoder never produces inline-tables or dotted keys at the moment.
Array and Array of Tables
The decoder produces List objects for all kinds of arrays including arrays of tables.
For example, given the following TOML document
The encoder preferably generates literal strings.
If a string contains apostrophes or other characters that are not allowed in literal strings, a basic string is produced instead.
Strings that contain newlines produce multiline strings.
Whether a multiline literal or multiline basic string is generated depends on the remaining characters in the string.
All produced multiline strings start with a trimmed newline and multiline basic strings never contain escaped whitespace.
If you need more control over the type of string that is produced by the encoder, you can wrap the value with a TomlLiteralString, TomlBasicString, TomlMultilineLiteralString or TomlMultilineBasicString.
Integer
Integers are represented by ints or BigInts.
The decoder produces an int only if the number can be represented losslessly by an int.
Whether a number can be represented by an int is platform specific.
When the code is running in the VM, numbers between -2^63 and 2^63 - 1 can be represented as an int.
In JavaScript, only numbers in the range from -(2^53 - 1) to 2^53 - 1 are guaranteed to be converted to int but smaller or larger numbers may still produce an int if they can be represented without loss of precision.
The encoder accepts either representation and uses the decimal integer format by default.
If you need more control over the format used by the encoder, the value has to be wrapped in a TomlInteger.
Floating point numbers are represented as doubles.
The special floating point values inf, -inf and nan are mapped to double.infinity, double.negativeInfinity and double.nan, respectively.
The value -nan is also mapped to double.nan.
When compiled to JavaScript, a double without decimal places cannot be distinguished from an int.
Thus, the encoder produces an integer for double values without decimal place.
If you want to force a JavaScript number to be encoded as a float, it has to be wrapped in a TomlFloat.
Boolean
Boolean values are represented as values of type bool.
The encoder produces the TOML values true and false.
Offset Date-Time
Offset Date-Time values are represented by the TomlOffsetDateTime class.
They can be converted to a UTC DateTime object with the toUtcDateTime method.
The encoder accepts TomlOffsetDateTime as well as DateTime objects.
A UTC DateTime is encoded as a offset date-time in the UTC time-zone.
A local DateTime is encoded as a offset date0time in the local time-zone.
For example, the following dates
are encoded as shown below when the code runs in the UTC+01:00 time-zone.
utc = 1969-07-2020:17:00Z
local = 1969-07-2020:17:00+01:00
Local Date-Time
Local Date-Time values are represented by the TomlLocalDateTime class.
Before they can be converted to a DateTime, you must provide a time-zone information in which to interpret the date-time.
For example, to interpret a local date-time in the time-zone the code is running in, type the following.
localDateTime.withOffset(TomlTimeZoneOffset.local()) // interpret in local time-zone
To interpret the local date-time value in a specific time-zone, write the following for example.
localDateTime.withOffset(TomlTimeZoneOffset.positive(1, 0)) // interpret in UTC+01:00
In both cases the result is a TomlOffsetDateTime that can be converted to a DateTime as described above.
The encoder accepts TomlLocalDateTime objects only, i.e., a DateTime will never be encoded as a local date-time automatically.
Local Date
Local Date values are represented by the TomlLocalDate class.
Before they can be converted to a DateTime, both a time and time-zone offset have to be provided.
First add a time with the atTime method and use withOffset from the resulting TomlLocalDateTime to obtain a offset date-time that can then be converted to a DateTime.
localDate.atTime(time).withOffset(timeZoneOffset)
Local Time
Local Time values are represented by the TomlLocalTime class.
Before they can be converted to a DateTime, both a date and time-zone offset have to be provided.
First add a date with the atDate method and use withOffset from the resulting TomlLocalDateTime to obtain a offset date-time that can then be converted to a DateTime.
localTime.atDate(date).withOffset(timeZoneOffset)
Testing
To see whether everything is working correctly change into the root directory of this package and run the included tests as follows:
dart test
You may pass the --platform command line argument to test the package on other platforms than the VM.
Run dart test --help for a list of all available platforms.
Additionally, the language-agnostic test suite toml-test is supported.
To speedup the tests, it is recommended to compile the encoder and decoder scripts first.