Package groovy.yaml

# Class YamlBuilder

java.lang.Object
groovy.lang.GroovyObjectSupport
groovy.yaml.YamlBuilder

All Implemented Interfaces:
  `GroovyObject`, `Writable`

public class YamlBuilder extends GroovyObjectSupport implements Writable
A builder for creating YAML payloads.

Since:
  3.0.0

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `YamlBuilder()`
  Creates an empty builder ready to assemble a YAML document.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Object`
  `call(Closure c)`
  A closure passed to a YAML builder will create a root YAML object
  `Object`
  `call(Iterable coll, Closure c)`
  A collection and closure passed to a YAML builder will create a root YAML array applying the closure to each object in the collection
  `Object`
  `call(Object... args)`
  Varargs elements as arguments to the YAML builder create a root YAML array
  `Object`
  `call(Collection coll, Closure c)`
  Delegates to `call(Iterable, Closure)` for collection inputs.
  `Object`
  `call(List l)`
  A list of elements as arguments to the YAML builder creates a root YAML array
  `Object`
  `call(Map m)`
  Named arguments can be passed to the YAML builder instance to create a root YAML object
  `Object`
  `getContent()`
  Returns the current root structure managed by this builder.
  `Object`
  `invokeMethod(String name, Object args)`
  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.
  `String`
  `toString()`
  Serializes the internal data structure built with the builder to a conformant YAML payload string
  `static String`
  `toYaml(Object object)`
  Serializes a typed object to a YAML string using Jackson databinding.
  `Writer`
  `writeTo(Writer out)`
  The YAML builder implements the `Writable` interface, so that you can have the builder serialize itself the YAML payload to a writer.

  ### Methods inherited from class groovy.lang.GroovyObjectSupport

  `getMetaClass, setMetaClass`

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

  ### Methods inherited from interface groovy.lang.GroovyObject

  `getProperty, setProperty`

- ## Constructor Details

  - ### YamlBuilder

    public YamlBuilder()
    Creates an empty builder ready to assemble a YAML document.

- ## Method Details

  - ### toYaml

    public static String toYaml(Object object)
    Serializes a typed object to a YAML string using Jackson databinding. Supports `@JsonProperty` and `@JsonFormat` annotations.
    Parameters:
      `object` - the object to serialize
    Returns:
      the YAML string
    Since:
      6.0.0

  - ### getContent

    public Object getContent()
    Returns the current root structure managed by this builder.
    Returns:
      the current YAML object, array, or scalar content

  - ### call

    public Object call(Map m)
    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
         '''

    Parameters:
      `m` - a map of key / value pairs
    Returns:
      a map of key / value pairs

  - ### call

    public Object call(List l)
    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
         '''

    Parameters:
      `l` - a list of values
    Returns:
      a list of values

  - ### call

    public Object call(Object... args)
    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
         '''

    Parameters:
      `args` - an array of values
    Returns:
      a list of values

  - ### call

    public Object call(Iterable coll, Closure c)
    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 ->
              name author.name
         }

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

    Parameters:
      `coll` - a collection
      `c` - a closure used to convert the objects of coll
    Returns:
      a list of values

  - ### call

    public Object call(Collection coll, Closure c)
    Delegates to `call(Iterable, Closure)` for collection inputs.
    Parameters:
      `coll` - the collection whose elements are converted into YAML content
      `c` - the closure that maps each collection element to YAML content
    Returns:
      a list of values

  - ### call

    public Object call(Closure 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
         '''

    Parameters:
      `c` - a closure whose method call statements represent key / values of a YAML object
    Returns:
      a map of key / value pairs

  - ### invokeMethod

    public Object invokeMethod(String name, Object args)
    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: {}
         '''

    Specified by:
      `invokeMethod` in interface `GroovyObject`
    Parameters:
      `name` - the single key
      `args` - the value associated with the key
    Returns:
      a map with a single key

  - ### toString

    public String toString()
    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
         '''

    Overrides:
      `toString` in class `Object`
    Returns:
      a YAML output

  - ### writeTo

    public Writer writeTo(Writer out) throws IOException
    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 << yaml

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

    Specified by:
      `writeTo` in interface `Writable`
    Parameters:
      `out` - a writer on which to serialize the YAML payload
    Returns:
      the writer
    Throws:
      `IOException` - if an error occurred while outputting data to the writer