2013-02-26 07:57:26 +00:00
# toml4j
2014-12-15 22:37:20 +00:00
toml4j is a [TOML 0.3.1 ](https://github.com/toml-lang/toml/tree/v0.3.1 ) parser for Java.
2014-04-07 13:41:14 +00:00
2014-12-15 22:49:00 +00:00
[![Maven Central ](https://img.shields.io/maven-central/v/com.moandjiezana.toml/toml4j.svg )](https://search.maven.org/#search|gav|1|g%3A%22com.moandjiezana.toml%22%20AND%20a%3A%22toml4j%22) [![Build Status ](https://img.shields.io/travis/mwanji/toml4j.svg )](https://travis-ci.org/mwanji/toml4j) [![Coverage Status ](https://img.shields.io/coveralls/mwanji/toml4j.svg )](https://coveralls.io/r/mwanji/toml4j)
2014-04-07 12:54:48 +00:00
2014-08-08 23:17:46 +00:00
For the bleeding-edge version integrating the latest specs, see the [work-in-progress branch ](https://github.com/mwanji/toml4j/tree/wip ).
2013-02-26 19:49:57 +00:00
## Installation
2014-04-07 13:41:14 +00:00
Add the following dependency to your POM (or equivalent for other dependency managers):
2013-02-26 19:49:57 +00:00
````xml
< dependency >
< groupId > com.moandjiezana.toml< / groupId >
< artifactId > toml4j< / artifactId >
2014-12-15 22:37:20 +00:00
< version > 0.3.1< / version >
2013-02-26 19:49:57 +00:00
< / dependency >
````
2014-12-15 22:37:20 +00:00
Requires Java 1.6.
2014-04-07 13:41:14 +00:00
## Quick start
````java
Toml toml = new Toml().parse(getTomlFile());
String someValue = toml.getString("someKey");
2014-04-10 13:21:40 +00:00
Date someDate = toml.getDate("someTable.someDate");
2014-04-07 13:41:14 +00:00
MyClass myClass = toml.to(MyClass.class);
````
2013-02-26 07:57:26 +00:00
## Usage
2014-04-08 14:37:02 +00:00
A `com.moandjiezana.toml.Toml` instance is populated by calling one of `parse(File)` , `parse(InputStream)` , `parse(Reader)` or `parse(String)` .
2014-04-07 13:41:14 +00:00
````java
Toml toml = new Toml().parse("a=1");
````
2014-04-10 13:21:40 +00:00
An exception is thrown if the source is not valid TOML.
2014-04-07 13:41:14 +00:00
The data can then be accessed either by converting the Toml instance to your own class or by accessing tables and keys by name.
2013-02-28 10:53:46 +00:00
### Custom classes
2014-04-07 13:41:14 +00:00
`Toml#to(Class<T>)` maps a Toml instance to the given class.
2013-02-28 10:53:46 +00:00
````
name = "Mwanji Ezana"
[address]
street = "123 A Street"
city = "AnyVille"
2015-01-14 07:46:36 +00:00
[contacts]
"email address" = me@example.com
2013-02-28 10:53:46 +00:00
````
````java
2014-04-07 13:41:14 +00:00
class Address {
String street;
String city;
}
class User {
String name;
Address address;
2015-01-14 07:46:36 +00:00
Map< String , Object > contacts;
2014-04-07 13:41:14 +00:00
}
2013-02-28 10:53:46 +00:00
````
````java
2014-04-07 13:41:14 +00:00
User user = new Toml().parse(tomlFile).to(User.class);
2014-04-06 19:56:14 +00:00
assert user.name.equals("Mwanji Ezana");
assert user.address.street.equals("123 A Street");
2015-01-14 07:46:36 +00:00
assert user.contacts.get("\"email address\"").equals("me@example.com");
2013-02-28 10:53:46 +00:00
````
2014-04-10 13:21:40 +00:00
Any keys not found in both the TOML and the class are ignored. Fields may be private.
2015-01-14 07:46:36 +00:00
Quoted keys cannot be mapped directly to a Java object, but they can be used as keys within a `Map` .
2014-04-10 13:21:40 +00:00
All TOML primitives can be mapped, as well as a number of Java-specific types:
* A TOML Number can be converted to any primitive type (or the wrapper equivalent), `BigInteger` or `BigDecimal`
* A TOML string can be converted to a `String` , enum, `java.net.URI` or `java.net.URL`
* A single-letter TOML string can be converted to a `char` or `Character`
2014-12-15 22:31:26 +00:00
* Multiline and literal TOML strings can be converted to `String`
2014-04-10 13:21:40 +00:00
* A TOML array can be converted to a `List` , `Set` or array. The generic type can be anything that can be converted.
* A TOML table can be converted to a custom class or to a `Map<String, Object>` . The generic type of the value can be anything that can be converted.
Custom classes, Maps and collections thereof can be nested to any level. See [TomlToClassTest#should_convert_fruit_table_array() ](src/test/java/com/moandjiezana/toml/TomlToClassTest.java ) for an example.
2013-02-28 10:53:46 +00:00
2014-04-06 19:56:14 +00:00
### Key names
2014-04-07 13:41:14 +00:00
Use the getters to retrieve the data:
* `getString(String)`
* `getDate(String)`
* `getBoolean(String)`
* `getLong(String)`
* `getDouble(String)`
* `getList(String, Class<T>)`
2014-04-10 13:21:40 +00:00
* `getTable(String)` returns a new Toml instance containing only the keys in that table.
* `getTables(String)` , for table arrays, returns `List<Toml>` .
2014-04-07 13:41:14 +00:00
2014-04-10 13:21:40 +00:00
You can also navigate values within a table with a compound key of the form `table.key` . Use a zero-based index such as `tableArray[0].key` to navigate table arrays.
2014-04-07 13:41:14 +00:00
2014-12-15 22:31:26 +00:00
Non-existent keys return null.
2014-04-07 13:41:14 +00:00
2015-01-14 07:46:36 +00:00
When retrieving quoted keys, the quotes must be used and the key must be spelled exactly the same way, including whitespace.
2014-04-07 13:41:14 +00:00
````
title = "TOML Example"
2015-01-14 07:46:36 +00:00
"sub title" = "Now with quoted keys"
2014-04-07 13:41:14 +00:00
[database]
ports = [ 8001, 8001, 8002 ]
enabled = true
2014-04-10 13:21:40 +00:00
[database.credentials]
password = "password"
2014-04-07 13:41:14 +00:00
[servers]
cluster = "hyades"
[servers.alpha]
ip = "10.0.0.1"
2014-04-10 13:21:40 +00:00
[[networks]]
name = "Level 1"
[networks.status]
bandwidth = 10
[[networks]]
name = "Level 2"
[[networks]]
name = "Level 3"
[[networks.operators]]
location = "Geneva"
[[networks.operators]]
location = "Paris"
2014-04-07 13:41:14 +00:00
````
````java
Toml toml = new Toml().parse(getTomlFile());
String title = toml.getString("title");
2015-01-14 07:46:36 +00:00
String subTitle = toml.getString("\"sub title\"");
2014-04-07 13:41:14 +00:00
Boolean enabled = toml.getBoolean("database.enabled");
List< Long > ports = toml.getList("database.ports", Long.class);
2014-04-10 13:21:40 +00:00
String password = toml.getString("database.credentials.password");
Toml servers = toml.getTable("servers");
String cluster = servers.getString("cluster"); // navigation is relative to current Toml instance
2014-04-07 13:41:14 +00:00
String ip = servers.getString("alpha.ip");
2014-04-06 19:56:14 +00:00
2014-04-10 13:21:40 +00:00
Toml network1 = toml.getTable("networks[0]");
String network2Name = toml.getString("networks[1].name"); // "Level 2"
List< Toml > network3Operators = toml.getTables("networks[2].operators");
String network3Operator2Location = toml.getString("networks[2].operators[1].location"); // "Paris"
2014-04-06 19:56:14 +00:00
````
### Defaults
2014-04-10 13:21:40 +00:00
The constructor can be given a set of default values that will be used as fallbacks. For tables and table arrays, a shallow merge is performed.
````
# defaults
a = 2
b = 3
[table]
c = 4
d = 5
````
````
a = 1
[table]
c = 2
[[array]]
d = 3
````
2014-04-06 19:56:14 +00:00
````java
2014-04-10 13:21:40 +00:00
Toml defaults = new Toml().parse(getDefaultsFile());
Toml toml = new Toml(defaults).parse(getTomlFile());
2014-04-06 19:56:14 +00:00
Long a = toml.getLong("a"); // returns 1, not 2
Long b = toml.getLong("b"); // returns 3
Long c = toml.getLong("c"); // returns null
2014-04-10 13:21:40 +00:00
Long tableC = toml.getLong("table.c"); // returns 2, not 4
Long tableD = toml.getLong("table.d"); // returns null, not 5
Long arrayD = toml.getLong("array[0].d"); // returns 3
2014-04-06 19:56:14 +00:00
````
2014-12-15 13:44:03 +00:00
### Limitations
Date precision is limited to milliseconds.
2013-02-26 19:49:57 +00:00
## License
2014-04-08 10:29:19 +00:00
toml4j is copyright of Moandji Ezana and is licensed under the [MIT License ](LICENSE )