Prepared README for 0.2.0

README.md

@@ -1,10 +1,8 @@
 # toml4j
 
-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.
+toml4j is a [TOML 0.2.0](https://github.com/mojombo/toml/tree/v0.2.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)
+[![Build Status](https://travis-ci.org/mwanji/toml4j.svg?branch=master)](https://travis-ci.org/mwanji/toml4j) [![Coverage Status](https://coveralls.io/repos/mwanji/toml4j/badge.png)](https://coveralls.io/r/mwanji/toml4j)
 
 ## Installation
 
@@ -14,7 +12,7 @@ Add the following dependency to your POM (or equivalent for other dependency man
 <dependency>
   <groupId>com.moandjiezana.toml</groupId>
   <artifactId>toml4j</artifactId>
-  <version>0.1.0</version>
+  <version>0.2.0</version>
 </dependency>
 ````
 
@@ -23,7 +21,7 @@ Add the following dependency to your POM (or equivalent for other dependency man
 ````java
 Toml toml = new Toml().parse(getTomlFile());
 String someValue = toml.getString("someKey");
-Date someDate = toml.getDate("someKeyGroup.someDate");
+Date someDate = toml.getDate("someTable.someDate");
 MyClass myClass = toml.to(MyClass.class);
 ````
 
@@ -35,7 +33,7 @@ A `com.moandjiezana.toml.Toml` instance is populated by calling one of `parse(Fi
 Toml toml = new Toml().parse("a=1");
 ````
 
-An exception is thrown if the file is not valid TOML.
+An exception is thrown if the source 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.
 
@@ -43,18 +41,6 @@ The data can then be accessed either by converting the Toml instance to your own
 
 `Toml#to(Class<T>)` maps a Toml instance to the given class.
 
-Any keys not found in both the TOML and the class are ignored.
-
-Key groups can be mapped to other custom classes. Fields may be private.
-
-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 single-letter TOML string can be converted to a `Character`
-* A TOML string can be converted to an enum or a `java.net.URL`
-* A TOML array can be converted to a `Set`
-* A TOML table can be converted to a `Map<String, Object>`
-
 ````
 name = "Mwanji Ezana"
 
@@ -82,7 +68,17 @@ assert user.name.equals("Mwanji Ezana");
 assert user.address.street.equals("123 A Street");
 ````
 
-When defaults are present, a shallow merge is performed.
+Any keys not found in both the TOML and the class are ignored. Fields may be private.
+
+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`
+* 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.
 
 ### Key names
 
@@ -94,14 +90,10 @@ Use the getters to retrieve the data:
 * `getLong(String)`
 * `getDouble(String)`
 * `getList(String, Class<T>)`
+* `getTable(String)` returns a new Toml instance containing only the keys in that table.
+* `getTables(String)`, for table arrays, returns `List<Toml>`. 
 
-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
-String s = toml.getString("keygroup1.keygroup2.key");
-````
+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.
 
 Non-existant keys return null.
 
@@ -111,11 +103,28 @@ title = "TOML Example"
 [database]
   ports = [ 8001, 8001, 8002 ]
   enabled = true
+  [database.credentials]
+    password = "password"
     
 [servers]
   cluster = "hyades"
   [servers.alpha]
   ip = "10.0.0.1"
+  
+[[networks]]
+  name = "Level 1"
+  [networks.status]
+    bandwidth = 10
+
+[[networks]]
+  name = "Level 2"
+
+[[networks]]
+  name = "Level 3"
+  [[networks.operators]]
+    location = "Geneva"
+  [[networks.operators]]
+    location = "Paris"
 ````
 
 ````java
@@ -124,54 +133,58 @@ Toml toml = new Toml().parse(getTomlFile());
 String title = toml.getString("title");
 Boolean enabled = toml.getBoolean("database.enabled");
 List<Long> ports = toml.getList("database.ports", Long.class);
-Toml servers = toml.getKeyGroup("servers");
-String cluster = servers.getString("cluster");
+String password = toml.getString("database.credentials.password");
+
+Toml servers = toml.getTable("servers");
+String cluster = servers.getString("cluster"); // navigation is relative to current Toml instance
 String ip = servers.getString("alpha.ip");
 
+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"
 ````
 
 ### Defaults
 
-The constructor can be given a set of default values that will be used as fallbacks.
+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
+````
 
 ````java
-Toml defaults = new Toml().parse("a = 2\nb = 3");
-Toml toml = new Toml(defaults).parse("a = 1");
+Toml defaults = new Toml().parse(getDefaultsFile());
+Toml toml = new Toml(defaults).parse(getTomlFile());
 
 Long a = toml.getLong("a"); // returns 1, not 2
 Long b = toml.getLong("b"); // returns 3
 Long c = toml.getLong("c"); // returns null
+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
 ````
 
 ## TODO
 
 * Fail on invalid definitions
 
-## Coming in 0.2.0
-
-### Table arrays
-
-Table arrays are mapped to `List<Toml>`s with `Toml#getTables(String)`. Custom classes and nested table arrays are supported.
-
-````
-[[products]]
-  name = "Hammer"
-  sku = 738594937
-
-[[products]]
-  name = "Nail"
-  sku = 284758393
-  color = "gray"
-````
-
-````java
-Toml toml = new Toml().parse(getTomlFile());
-
-List<Toml> tables = toml.getTables("products");
-tables.get(1).getLong("sku"); // returns 284758393
-````
-
 ## License
 
 toml4j is copyright of Moandji Ezana and is licensed under the [MIT License](LICENSE)
-