toml 0.5.0

Parser and encoder for TOML v0.4.0 (Tom's Obvious, Minimal Language) configuration files.

toml.dart

This package provides an implementation of a TOML (Tom's Obvious, Minimal Language) parser and encoder for Dart.

It currently supports version v0.4.0 of the TOML specification.

Installation

To get started add toml as a dependency to your pubspec.yaml and run the pub get command.

dependencies:
  toml: "^0.5.0"

Usage

This package includes three libraries for loading, decoding and encoding TOML documents, which are further described below.

If you want to use both the encoder and decoder, a single import suffices:

import 'package:toml/toml.dart';

Load configuration files.

Before any configuration file can be parsed the library needs to know how to load it. There are two default methods available, but you can easily implement your own loading mechanism as further described below.

If your code is running in the browser, you probably want to use XHR to fetch the file from the server. To do so import the toml.loader.http library and call the static HttpConfigLoader.use method, e.g. from your main function.

import 'package:toml/loader/http.dart';

void main() {
  HttpConfigLoader.use();
  // ...
}

If your code is running on the server, you can load configuration files from the local file system. Simply import the toml.loader.fs library and call the static FilesystemConfigLoader.use method, e.g. from your main function.

import 'package:toml/loader/fs.dart';

void main() {
  FilesystemConfigLoader.use();
  // ...
}

For convenience both libraries export the loadConfig function from the toml.loader library. It optionally takes the path to the configuration file as its only argument (defaults to 'config.toml') and returns a Future of the parsed configuration options.

Future main() async {
  // ...
  var cfg = await loadConfig();
  // ...
}

Implement a custom loader.

To create a custom loader which fits exactly your needs import the toml.loader library, create a new class and implement the ConfigLoader interface. You can use this code as a starting point:

library my.config.loader;

import 'package:toml/loader.dart';
export 'package:toml/loader.dart' show loadConfig;

class MyConfigLoader implements ConfigLoader {

  static void use() {
    ConfigLoader.use(new MyConfigLoader());
  }

  @override
  Future<String> loadConfig(String filename) {
    // ...
  }

}

In your main function invoke the MyConfigLoader.use method and call the loadConfig function as usual.

Decode TOML

If you only want to decode a string of TOML, add the following import directive to your script:

import 'package:toml/decoder.dart';

This library contains the actual TomlParser class whose parse method takes a String and returns a Result object. The results value property holds an unmodifiable Map of the parsed document.

var toml = '''
  # ...
''';
var parser = new TomlParser();
var document = parser.parse(toml).value;

Encode TOML

This package includes a TOML encoder. To use it simply import:

import 'package:toml/encoder.dart';

The library provides a TomlEncoder class whose encode method takes a Map and returns a TOML encoded String. All values of the map must be natively representable by TOML or implement the TomlEncodable interface.

var document = {
  // ...
};
var encoder = new TomlEncoder();
var toml = encoder.encode(document);

Classes which implement the TomlEncodable interface define a toToml method whose return value can be represented by TOML in turn.

Data Structure

TOML documents and tables as well as inline tables are represented through nested UnmodifiableMapView objects whose keys are Strings and values dynamic read-only representations of the corresponding TOML value or sub-table. The contents of a table declared by:

[a.b.c]
key = 'value'

may be accessed using []:

var table = document['a']['b']['c']; // ok
var value = table['key'];

The following, however, is invalid:

var table = document['a.b.c']; // error
table['key'] = value; // error

All kinds of arrays including arrays of tables are stored as UnmodifiableListView objects. Though the encoder accepts any Iterable. The items of the list represent either a value or a table. Given a document:

[[items]]
name = 'A'

[[items]]
name = 'B'

[[items]]
name = 'C'

One might iterate over the items of the list:

document['items'].forEach((Map item) { // ok
  print(item.name);
});

But it is not allowed to add, remove or modify its entries:

document['items'].add({ // error
  'name': 'D'
});
document['items'][0] = { // error
  'name': 'E'
};

All string variants produce regular dart Strings. These are therefore all equivalent:

str1 = "Hello World!"
str2 = 'Hello World!'
str3 = """
  Hello \
  World!\
"""
str4 = '''Hello World!'''

Integers are of type int and floating point numbers are represented as doubles. When compiled to JavaScript these two types are not distinct. Thus a float without decimal places might accidentally be encoded as an integer. This behavior would lead to the generation of invalid numeric arrays. The TomlEncoder addresses this issue by analyzing the contents of numeric arrays first. If any of its items cannot be represented as an integer, all items will be encoded as floats instead. Encoding the following map:

var document = {
  'array': [1, 2.0, 3.141]
};

would throw an MixedArrayTypesError in the vm but yields this document when compiled to JavaScript:

array = [1.0, 2.0, 3.141]

Boolean values are obviously of type bool.

Datetime values are UTC DateTime objects.

Examples

Check out the scripts located in the '/example' directory.

Testing

To see whether everything is working correctly change into the root directory of this package and run the included tests as follows:

pub run test

You may pass the --platform command line argument to test the package on other platforms than the VM. Run pub run test --help for a list of all available platforms.

Alternatively you can run toml-test (again from the package root):

$GOPATH/bin/toml-test bin/decoder.dart
$GOPATH/bin/toml-test -encoder bin/encoder.dart

However, note that toml-test currently supports v0.2.0 only. Thus a workaround is needed at the time to fix datetimes which have changed slightly since then.

License

toml.dart is licensed under the MIT license agreement. See the LICENSE file for details.