diff --git a/README.md b/README.md index 37f27c3..95933f0 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,14 @@ # toml4j -toml4j is a [TOML 0.1.0](https://github.com/mojombo/toml) parser for Java that uses the [Parboiled](http://www.parboiled.org) PEG parser. +toml4j is a [TOML 0.1.0](https://github.com/mojombo/toml/tree/v0.1.0) parser for Java that uses the [Parboiled](http://www.parboiled.org) PEG parser. + +[TOML 0.2.0](https://github.com/mojombo/toml/tree/v0.2.0) support is under development on the master branch. [![Build Status](https://travis-ci.org/mwanji/toml4j.svg?branch=master)](https://travis-ci.org/mwanji/toml4j) ## Installation -Add the following dependency to your POM: +Add the following dependency to your POM (or equivalent for other dependency managers): ````xml @@ -16,11 +18,30 @@ Add the following dependency to your POM: ```` +## Quick start + +````java +Toml toml = new Toml().parse(getTomlFile()); +String someValue = toml.getString("someKey"); +Date someDate = toml.getDate("someKeyGroup.someDate"); +MyClass myClass = toml.to(MyClass.class); +```` + ## Usage +A `com.moandjiezana.toml.Toml` instance is populated by calling one of `parse(File)` or `parse(String)`. + +````java +Toml toml = new Toml().parse("a=1"); +```` + +An exception is thrown if the file is not valid TOML. + +The data can then be accessed either by converting the Toml instance to your own class or by accessing tables and keys by name. + ### Custom classes -A Toml object can be mapped to a custom class with the `Toml#to(Class)` method. +`Toml#to(Class)` maps a Toml instance to the given class. Any keys not found in both the TOML and the class are ignored. @@ -35,20 +56,19 @@ name = "Mwanji Ezana" ```` ````java - class Address { - String street; - String city; - } +class Address { + String street; + String city; +} - class User { - String name; - Address address; - } +class User { + String name; + Address address; +} ```` ````java -Toml toml = new Toml().parse(tomlFile); -User user = toml.to(User.class); +User user = new Toml().parse(tomlFile).to(User.class); assert user.name.equals("Mwanji Ezana"); assert user.address.street.equals("123 A Street"); @@ -58,21 +78,53 @@ When defaults are present, a shallow merge is performed. ### Key names -1. Create a `com.moandjiezana.toml.Toml` instance -2. Call the `parse` method of your choice -3. Use the getters to retrieve the data +Use the getters to retrieve the data: + +* `getString(String)` +* `getDate(String)` +* `getBoolean(String)` +* `getLong(String)` +* `getDouble(String)` +* `getList(String, Class)` + +Key groups can be accessed with `getKeyGroup(String)`, which returns a new Toml instance containing only the keys in that key group. + +You can directly access values within a key group with a compound key: ````java -Toml toml = new Toml().parse(getTomlFile()); // throws an Exception if the TOML is incorrect +String s = toml.getString("keygroup1.keygroup2.key"); +```` + +Non-existant keys return null. + +```` +title = "TOML Example" + +[database] + ports = [ 8001, 8001, 8002 ] + enabled = true + +[servers] + cluster = "hyades" + [servers.alpha] + ip = "10.0.0.1" +```` + +````java +Toml toml = new Toml().parse(getTomlFile()); + +String title = toml.getString("title"); +Boolean enabled = toml.getBoolean("database.enabled"); +List ports = toml.getList("database.ports", Long.class); +Toml servers = toml.getKeyGroup("servers"); +String cluster = servers.getString("cluster"); +String ip = servers.getString("alpha.ip"); -String title = toml.getString("title"); // if a key doesn't exist, returns null -Boolean enabled = toml.getBoolean("database.enabled"); // gets the value of enabled from the database key group -Toml servers = toml.getKeyGroup("servers"); // returns a new Toml instance containing only the key group's values ```` ### Defaults -The constructor can be given a set of default values that will be used if necessary. +The constructor can be given a set of default values that will be used as fallbacks. ````java Toml defaults = new Toml().parse("a = 2\nb = 3"); @@ -91,7 +143,7 @@ Long c = toml.getLong("c"); // returns null ### Table arrays -Table arrays are mapped to `List`s with `Toml#getTables(String)`. Custom classes and nested table arrays are supported. +Table arrays are mapped to `List`s with `Toml#getTables(String)`. Custom classes and nested table arrays are supported. ```` [[products]]