groovy.yaml.YamlBuilder Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of groovy-yaml Show documentation
Show all versions of groovy-yaml Show documentation
Groovy: A powerful multi-faceted language for the JVM
/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/
package groovy.yaml;
import groovy.json.JsonBuilder;
import groovy.lang.Closure;
import groovy.lang.GroovyObjectSupport;
import groovy.lang.Writable;
import org.apache.groovy.yaml.util.YamlConverter;
import java.io.IOException;
import java.io.StringReader;
import java.io.Writer;
import java.util.Collection;
import java.util.List;
import java.util.Map;
/**
* A builder for creating YAML payloads.
*
* @since 3.0.0
*/
public class YamlBuilder extends GroovyObjectSupport implements Writable {
private final JsonBuilder jsonBuilder;
public YamlBuilder() {
this.jsonBuilder = new JsonBuilder();
}
public Object getContent() {
return jsonBuilder.getContent();
}
/**
* Named arguments can be passed to the YAML builder instance to create a root YAML object
*
* Example:
*
* def yaml = new groovy.yaml.YamlBuilder()
* yaml name: "Guillaume", age: 33
*
* assert yaml.toString() == '''---
* name: "Guillaume"
* age: 33
* '''
*
*
* @param m a map of key / value pairs
* @return a map of key / value pairs
*/
public Object call(Map m) {
return jsonBuilder.call(m);
}
/**
* A list of elements as arguments to the YAML builder creates a root YAML array
*
* Example:
*
* def yaml = new groovy.yaml.YamlBuilder()
* def result = yaml([1, 2, 3])
*
* assert result instanceof List
* assert yaml.toString() == '''---
* - 1
* - 2
* - 3
* '''
*
*
* @param l a list of values
* @return a list of values
*/
public Object call(List l) {
return jsonBuilder.call(l);
}
/**
* Varargs elements as arguments to the YAML builder create a root YAML array
*
* Example:
*
* def yaml = new groovy.yaml.YamlBuilder()
* def result = yaml 1, 2, 3
*
* assert result instanceof List
* assert yaml.toString() == '''---
* - 1
* - 2
* - 3
* '''
*
*
* @param args an array of values
* @return a list of values
*/
public Object call(Object... args) {
return jsonBuilder.call(args);
}
/**
* A collection and closure passed to a YAML builder will create a root YAML array applying
* the closure to each object in the collection
*
* Example:
*
* class Author {
* String name
* }
* def authors = [new Author (name: "Guillaume"), new Author (name: "Jochen"), new Author (name: "Paul")]
*
* def yaml = new groovy.yaml.YamlBuilder()
* yaml authors, { Author author {@code ->}
* name author.name
* }
*
* assert yaml.toString() == '''---
* - name: "Guillaume"
* - name: "Jochen"
* - name: "Paul"
* '''
*
* @param coll a collection
* @param c a closure used to convert the objects of coll
* @return a list of values
*/
public Object call(Iterable coll, Closure c) {
return jsonBuilder.call(coll, c);
}
/**
* Delegates to {@link #call(Iterable, Closure)}
* @param coll
* @param c
*/
public Object call(Collection coll, Closure c) {
return jsonBuilder.call(coll, c);
}
/**
* A closure passed to a YAML builder will create a root YAML object
*
* Example:
*
* def yaml = new groovy.yaml.YamlBuilder()
* def result = yaml {
* name "Guillaume"
* age 33
* }
*
* assert result instanceof Map
* assert yaml.toString() == '''---
* name: "Guillaume"
* age: 33
* '''
*
*
* @param c a closure whose method call statements represent key / values of a YAML object
* @return a map of key / value pairs
*/
public Object call(Closure c) {
return jsonBuilder.call(c);
}
/**
* A method call on the YAML 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:
*
* - a closure
* - a map (ie. named arguments)
* - a map and a closure
* - or no argument at all
*
*
* Example with a classical builder-style:
*
* def yaml = new groovy.yaml.YamlBuilder()
* def result = yaml.person {
* name "Guillaume"
* age 33
* }
*
* assert result instanceof Map
* assert yaml.toString() == '''---
* person:
* name: "Guillaume"
* age: 33
* '''
*
*
* Or alternatively with a method call taking named arguments:
*
* def yaml = new groovy.yaml.YamlBuilder()
* yaml.person name: "Guillaume", age: 33
*
* assert yaml.toString() == '''---
* person:
* name: "Guillaume"
* age: 33
* '''
*
*
* 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.
*
* def yaml = new groovy.yaml.YamlBuilder()
* yaml.person(name: "Guillaume", age: 33) { town "Paris" }
*
* assert yaml.toString() == '''---
* person:
* name: "Guillaume"
* age: 33
* town: "Paris"
* '''
*
*
* The empty args call will create a key whose value will be an empty YAML object:
*
* def yaml = new groovy.yaml.YamlBuilder()
* yaml.person()
*
* assert yaml.toString() == '''---
* person: {}
* '''
*
*
* @param name the single key
* @param args the value associated with the key
* @return a map with a single key
*/
@Override
public Object invokeMethod(String name, Object args) {
return jsonBuilder.invokeMethod(name, args);
}
/**
* Serializes the internal data structure built with the builder to a conformant YAML payload string
*
* Example:
*
* def yaml = new groovy.yaml.YamlBuilder()
* yaml { temperature 37 }
*
* assert yaml.toString() == '''---
* temperature: 37
* '''
*
*
* @return a YAML output
*/
@Override
public String toString() {
return YamlConverter.convertJsonToYaml(new StringReader(jsonBuilder.toString()));
}
/**
* The YAML builder implements the Writable interface,
* so that you can have the builder serialize itself the YAML payload to a writer.
*
* Example:
*
* def yaml = new groovy.yaml.YamlBuilder()
* yaml { temperature 37 }
*
* def out = new StringWriter()
* out {@code <<} yaml
*
* assert out.toString() == '''---
* temperature: 37
* '''
*
*
* @param out a writer on which to serialize the YAML payload
* @return the writer
*/
@Override
public Writer writeTo(Writer out) throws IOException {
return out.append(toString());
}
}