You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@groovy.apache.org by su...@apache.org on 2021/05/03 12:51:02 UTC
[groovy] branch GROOVY-9804 updated: Add sample codes for TOML to
javadoc
This is an automated email from the ASF dual-hosted git repository.
sunlan pushed a commit to branch GROOVY-9804
in repository https://gitbox.apache.org/repos/asf/groovy.git
The following commit(s) were added to refs/heads/GROOVY-9804 by this push:
new 560ed65 Add sample codes for TOML to javadoc
560ed65 is described below
commit 560ed65abe82c1260778dd03e6bf114caa433cc6
Author: Daniel Sun <su...@apache.org>
AuthorDate: Mon May 3 20:50:00 2021 +0800
Add sample codes for TOML to javadoc
---
.../src/main/java/groovy/toml/TomlBuilder.java | 150 ++++++++++++++++++++-
.../org/apache/groovy/toml/util/TomlConverter.java | 8 --
2 files changed, 149 insertions(+), 9 deletions(-)
diff --git a/subprojects/groovy-toml/src/main/java/groovy/toml/TomlBuilder.java b/subprojects/groovy-toml/src/main/java/groovy/toml/TomlBuilder.java
index 7a04571..fa3fa42 100644
--- a/subprojects/groovy-toml/src/main/java/groovy/toml/TomlBuilder.java
+++ b/subprojects/groovy-toml/src/main/java/groovy/toml/TomlBuilder.java
@@ -49,6 +49,17 @@ public class TomlBuilder extends GroovyObjectSupport implements Writable {
/**
* Named arguments can be passed to the TOML builder instance to create a root TOML object
+ * <p>
+ * Example:
+ * <pre><code class="groovyTestCase">
+ * def toml = new groovy.toml.TomlBuilder()
+ * toml name: "Guillaume", age: 33
+ *
+ * assert toml.toString() == '''\
+ * name = 'Guillaume'
+ * age = 33
+ * '''
+ * </code></pre>
*
* @param m a map of key / value pairs
* @return a map of key / value pairs
@@ -59,6 +70,17 @@ public class TomlBuilder extends GroovyObjectSupport implements Writable {
/**
* A list of elements as arguments to the TOML builder creates a root TOML array
+ * <p>
+ * Example:
+ * <pre><code class="groovyTestCase">
+ * def toml = new groovy.toml.TomlBuilder()
+ * def result = toml([1, 2, 3])
+ *
+ * assert result instanceof List
+ * assert toml.toString() == '''\
+ * = [1, 2, 3]
+ * '''
+ * </code></pre>
*
* @param l a list of values
* @return a list of values
@@ -69,6 +91,17 @@ public class TomlBuilder extends GroovyObjectSupport implements Writable {
/**
* Varargs elements as arguments to the TOML builder create a root TOML array
+ * <p>
+ * Example:
+ * <pre><code class="groovyTestCase">
+ * def toml = new groovy.toml.TomlBuilder()
+ * def result = toml 1, 2, 3
+ *
+ * assert result instanceof List
+ * assert toml.toString() == '''\
+ * = [1, 2, 3]
+ * '''
+ * </code></pre>
*
* @param args an array of values
* @return a list of values
@@ -80,7 +113,24 @@ public class TomlBuilder extends GroovyObjectSupport implements Writable {
/**
* A collection and closure passed to a TOML builder will create a root TOML array applying
* the closure to each object in the collection
-
+ * <p>
+ * Example:
+ * <pre><code class="groovyTestCase">
+ * class Author {
+ * String name
+ * }
+ * def authors = [new Author (name: "Guillaume"), new Author (name: "Jochen"), new Author (name: "Paul")]
+ *
+ * def toml = new groovy.toml.TomlBuilder()
+ * toml authors, { Author author {@code ->}
+ * name author.name
+ * }
+ *
+ * assert toml.toString() == '''\
+ * = [{name = 'Guillaume'}, {name = 'Jochen'}, {name = 'Paul'}]
+ * '''
+ * </code></pre>
+ *
* @param coll a collection
* @param c a closure used to convert the objects of coll
* @return a list of values
@@ -100,6 +150,21 @@ public class TomlBuilder extends GroovyObjectSupport implements Writable {
/**
* A closure passed to a TOML builder will create a root TOML object
+ * <p>
+ * Example:
+ * <pre><code class="groovyTestCase">
+ * def toml = new groovy.toml.TomlBuilder()
+ * def result = toml {
+ * name "Guillaume"
+ * age 33
+ * }
+ *
+ * assert result instanceof Map
+ * assert toml.toString() == '''\
+ * name = 'Guillaume'
+ * age = 33
+ * '''
+ * </code></pre>
*
* @param c a closure whose method call statements represent key / values of a TOML object
* @return a map of key / value pairs
@@ -111,6 +176,66 @@ public class TomlBuilder extends GroovyObjectSupport implements Writable {
/**
* A method call on the TOML builder instance will create a root object with only one key
* whose name is the name of the method being called.
+ * This method takes as arguments:
+ * <ul>
+ * <li>a closure</li>
+ * <li>a map (ie. named arguments)</li>
+ * <li>a map and a closure</li>
+ * <li>or no argument at all</li>
+ * </ul>
+ * <p>
+ * Example with a classical builder-style:
+ * <pre><code class="groovyTestCase">
+ * def toml = new groovy.toml.TomlBuilder()
+ * def result = toml.person {
+ * name "Guillaume"
+ * age 33
+ * }
+ *
+ * assert result instanceof Map
+ * assert toml.toString() == '''\
+ * person.name = 'Guillaume'
+ * person.age = 33
+ * '''
+ * </code></pre>
+ *
+ * Or alternatively with a method call taking named arguments:
+ * <pre><code class="groovyTestCase">
+ * def toml = new groovy.toml.TomlBuilder()
+ * toml.person name: "Guillaume", age: 33
+ *
+ * assert toml.toString() == '''\
+ * person.name = 'Guillaume'
+ * person.age = 33
+ * '''
+ * </code></pre>
+ *
+ * If you use named arguments and a closure as last argument,
+ * the key/value pairs of the map (as named arguments)
+ * and the key/value pairs represented in the closure
+ * will be merged together —
+ * the closure properties overriding the map key/values
+ * in case the same key is used.
+ * <pre><code class="groovyTestCase">
+ * def toml = new groovy.toml.TomlBuilder()
+ * toml.person(name: "Guillaume", age: 33) { town "Paris" }
+ *
+ * assert toml.toString() == '''\
+ * person.name = 'Guillaume'
+ * person.age = 33
+ * person.town = 'Paris'
+ * '''
+ * </code></pre>
+ *
+ * The empty args call will create a key whose value will be an empty YAML object:
+ * <pre><code class="groovyTestCase">
+ * def toml = new groovy.toml.TomlBuilder()
+ * toml.person()
+ *
+ * assert toml.toString() == '''\
+ * person = {}
+ * '''
+ * </code></pre>
*
* @param name the single key
* @param args the value associated with the key
@@ -123,6 +248,16 @@ public class TomlBuilder extends GroovyObjectSupport implements Writable {
/**
* Serializes the internal data structure built with the builder to a conformant TOML payload string
+ * <p>
+ * Example:
+ * <pre><code class="groovyTestCase">
+ * def toml = new groovy.toml.TomlBuilder()
+ * toml { temperature 37 }
+ *
+ * assert toml.toString() == '''\
+ * temperature = 37
+ * '''
+ * </code></pre>
*
* @return a TOML output
*/
@@ -134,6 +269,19 @@ public class TomlBuilder extends GroovyObjectSupport implements Writable {
/**
* The TOML builder implements the <code>Writable</code> interface,
* so that you can have the builder serialize itself the TOML payload to a writer.
+ * <p>
+ * Example:
+ * <pre><code class="groovyTestCase">
+ * def toml = new groovy.toml.TomlBuilder()
+ * toml { temperature 37 }
+ *
+ * def out = new StringWriter()
+ * out {@code <<} toml
+ *
+ * assert out.toString() == '''\
+ * temperature = 37
+ * '''
+ * </code></pre>
*
* @param out a writer on which to serialize the TOML payload
* @return the writer
diff --git a/subprojects/groovy-toml/src/main/java/org/apache/groovy/toml/util/TomlConverter.java b/subprojects/groovy-toml/src/main/java/org/apache/groovy/toml/util/TomlConverter.java
index 4e22288..cbc293e 100644
--- a/subprojects/groovy-toml/src/main/java/org/apache/groovy/toml/util/TomlConverter.java
+++ b/subprojects/groovy-toml/src/main/java/org/apache/groovy/toml/util/TomlConverter.java
@@ -26,7 +26,6 @@ import groovy.toml.TomlRuntimeException;
import java.io.IOException;
import java.io.Reader;
-import java.io.StringReader;
/**
* A converter for converting TOML to JSON, vice versa
@@ -64,11 +63,4 @@ public class TomlConverter {
}
private TomlConverter() {}
-
- public static void main(String[] args) {
- String json = TomlConverter.convertTomlToJson(new StringReader("number = 42"));
- System.out.println(json);
- String toml = TomlConverter.convertJsonToToml(new StringReader(json));
- System.out.println(toml);
- }
}