Readme

# toml.dart

This package provides an implementation of a TOML (Tom's Obvious, Minimal Language) parser and encoder for dart. It can be used with the dart_config library which allows you to dynamically load configuration files.

It currently supports version v0.3.1 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.1.0 <0.2.0"

Usage

With dart_config

If you want to use dart_config and your code is running in the browser add the following import directive:

import 'package:toml/browser.dart';

For command line and server side applications write:

import 'package:toml/server.dart';

Both imports define a loadConfig function which takes an optional path to the configuration file (defaults to 'config.toml') and returns a Future of the parsed document as an unmodifiable Map. They use the default ConfigHttpRequestLoader and ConfigFilesystemLoader, respectively.

loadConfig().then((Map document) {
  // ...
})

If you want to use a custom ConfigLoader add the following import instead:

import 'package:toml/config.dart';

There you will find the TomlConfigParser which implements the ConfigParser interface and can be used in conjunction with dart_configs Config class and your loader:

var config = new Config(filename,
  new MyConfigLoader(),
  new TomlConfigParser()
);
config.readConfig().then((Map document) {
  // ...
});

Without dart_config

If you don't want to use dart_config at all, add:

import 'package:toml/toml.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

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);

Clases 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 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 eqivalent:

  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 '/examples' directory.

License

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