YAML Building

/**
 * A builder for creating YAML payloads using Groovy's builder pattern.
 * Extends GroovyObjectSupport for dynamic method support and implements Writable for output.
 */
public class YamlBuilder extends GroovyObjectSupport implements Writable {
    /**
     * Creates a new YAML builder instance.
     * Initializes internal JsonBuilder for processing.
     */
    public YamlBuilder();
    
    /**
     * Get the internal content object built by the builder.
     * @return the content object
     */
    public Object getContent();
}

/**
 * Named arguments can be passed to the YAML builder instance to create a root YAML object.
 * @param m a map of key / value pairs
 * @return a map of key / value pairs
 */
public Object call(Map m);

import groovy.yaml.YamlBuilder;
import java.util.Map;

YamlBuilder yaml = new YamlBuilder();
yaml.call(Map.of("name", "Guillaume", "age", 33));

assert yaml.toString().equals("""---
name: "Guillaume"
age: 33
""");

/**
 * A list of elements as arguments to the YAML builder creates a root YAML array.
 * @param l a list of values
 * @return a list of values
 */
public Object call(List l);

import groovy.yaml.YamlBuilder;
import java.util.List;

YamlBuilder yaml = new YamlBuilder();
Object result = yaml.call(List.of(1, 2, 3));

assert result instanceof List;
assert yaml.toString().equals("""---
- 1
- 2
- 3
""");

/**
 * Varargs elements as arguments to the YAML builder create a root YAML array.
 * @param args an array of values
 * @return a list of values
 */
public Object call(Object... args);

import groovy.yaml.YamlBuilder;

YamlBuilder yaml = new YamlBuilder();
Object result = yaml.call(1, 2, 3);

assert result instanceof List;
assert yaml.toString().equals("""---
- 1
- 2
- 3
""");

/**
 * A collection and closure passed to a YAML builder will create a root YAML array applying
 * the closure to each object in the collection.
 * @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);

/**
 * Delegates to the Iterable version.
 * @param coll a collection
 * @param c a closure used to convert the objects of coll
 * @return a list of values
 */
public Object call(Collection coll, Closure c);

import groovy.yaml.YamlBuilder

class Author {
    String name
}
def authors = [new Author(name: "Guillaume"), new Author(name: "Jochen"), new Author(name: "Paul")]

def yaml = new YamlBuilder()
yaml.call(authors) { Author author ->
    name author.name
}

assert yaml.toString() == '''---
- name: "Guillaume"
- name: "Jochen"  
- name: "Paul"
'''

/**
 * A closure passed to a YAML builder will create a root YAML object.
 * @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);

import groovy.yaml.YamlBuilder

def yaml = new YamlBuilder()
def result = yaml {
    name "Guillaume"
    age 33
}

assert result instanceof Map
assert yaml.toString() == '''---
name: "Guillaume"
age: 33
'''

/**
 * 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 various argument types including closures, maps, or no arguments.
 * @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);

import groovy.yaml.YamlBuilder

// Builder-style with closure
def yaml = new YamlBuilder()
def result = yaml.person {
    name "Guillaume"
    age 33
}

assert yaml.toString() == '''---
person:
  name: "Guillaume"
  age: 33
'''

// Named arguments
yaml = new YamlBuilder()
yaml.person(name: "Guillaume", age: 33)

assert yaml.toString() == '''---
person:
  name: "Guillaume"
  age: 33
'''

// Mixed named arguments and closure
yaml = new YamlBuilder()
yaml.person(name: "Guillaume", age: 33) { town "Paris" }

assert yaml.toString() == '''---
person:
  name: "Guillaume"
  age: 33
  town: "Paris"
'''

// Empty args create empty object
yaml = new YamlBuilder()
yaml.person()

assert yaml.toString() == '''---
person: {}
'''

/**
 * Serializes the internal data structure built with the builder to a conformant YAML payload string.
 * @return a YAML output string
 */
@Override
public String toString();

import groovy.yaml.YamlBuilder

def yaml = new YamlBuilder()
yaml { temperature 37 }

assert yaml.toString() == '''---
temperature: 37
'''

/**
 * The YAML builder implements the Writable interface,
 * so that you can have the builder serialize itself the YAML payload to a writer.
 * @param out a writer on which to serialize the YAML payload
 * @return the writer
 * @throws IOException if writing fails
 */
@Override
public Writer writeTo(Writer out) throws IOException;

import groovy.yaml.YamlBuilder
import java.io.StringWriter

def yaml = new YamlBuilder()
yaml { temperature 37 }

def out = new StringWriter()
out << yaml

assert out.toString() == '''---
temperature: 37
'''

public class YamlRuntimeException extends GroovyRuntimeException {
    public YamlRuntimeException(String msg);
    public YamlRuntimeException(Throwable cause);
    public YamlRuntimeException(String msg, Throwable cause);
}