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()` |

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    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)`
    `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()` |
    `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
    `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 Detail

    - #### YamlBuilder

          public YamlBuilder()

  - ### Method Detail

    - #### getContent

          public Object getContent()

    - #### 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)`
      Parameters:
        `coll` -
        `c` -

    - #### 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