Package: groovy.toml

## [Java] Class TomlBuilder

- groovy.toml.TomlBuilder

- All Implemented Interfaces and Traits:
    Writable

      @Incubating
      public class TomlBuilder
      extends GroovyObjectSupport
      implements Writable

  A builder for creating TOML payloads.

  Since:
    4.0.0

- - ### Constructor Summary

    Constructors
    Constructor and description
    `TomlBuilder()` Creates an empty builder ready to assemble a TOML document.

  - ### Methods Summary

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

  - ### Inherited Methods Summary

    Inherited Methods
    Methods inherited from class | Name
    --- | ---
    `class GroovyObjectSupport` | `getMetaClass, setMetaClass`

- - ### Constructor Detail

    - #### public TomlBuilder()

      Creates an empty builder ready to assemble a TOML document.

  - ### Method Detail

    - #### public Object call(Map m)

      Named arguments can be passed to the TOML builder instance to create a root TOML object

      Example:

           def toml = new groovy.toml.TomlBuilder()
           toml name: "Guillaume", age: 33

           assert toml.toString() == '''\
           name = 'Guillaume'
           age = 33
           '''

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

    - #### public Object call(List l)

      A list of elements as arguments to the TOML builder creates a root TOML array

      Example:

           def toml = new groovy.toml.TomlBuilder()
           def result = toml([1, 2, 3])

           assert result instanceof List
           assert toml.toString() == '''\
            = [1, 2, 3]
           '''

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

    - #### public Object call(Object args)

      Varargs elements as arguments to the TOML builder create a root TOML array

      Example:

           def toml = new groovy.toml.TomlBuilder()
           def result = toml 1, 2, 3

           assert result instanceof List
           assert toml.toString() == '''\
            = [1, 2, 3]
           '''

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

    - #### public Object call(Iterable coll, Closure c)

      A collection and closure passed to a TOML builder will create a root TOML 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 toml = new groovy.toml.TomlBuilder()
           toml authors, { Author author ->
                name author.name
           }

           assert toml.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

    - #### public Object call(Collection coll, Closure c)

      Delegates to call(Iterable, Closure) for collection inputs.

      Parameters:
        `coll` - the collection whose elements are converted into TOML content
        `c` - the closure that maps each collection element to TOML content
      Returns:
        a list of values

    - #### public Object call(Closure c)

      A closure passed to a TOML builder will create a root TOML object

      Example:

           def toml = new groovy.toml.TomlBuilder()
           def result = toml {
                name "Guillaume"
                age 33
           }

           assert result instanceof Map
           assert toml.toString() == '''\
           name = 'Guillaume'
           age = 33
           '''

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

    - #### public Object getContent()

      Returns the current root structure managed by this builder.

      Returns:
        the current TOML table, array, or scalar content

    - #### public Object invokeMethod(String name, Object args)

      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:

      - a closure
      - a map (ie. named arguments)
      - a map and a closure
      - or no argument at all

      Example with a classical builder-style:

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

      Or alternatively with a method call taking named arguments:

           def toml = new groovy.toml.TomlBuilder()
           toml.person name: "Guillaume", age: 33

           assert toml.toString() == '''\
           person.name = 'Guillaume'
           person.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 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'
           '''

      The empty args call will create a key whose value will be an empty TOML object:

           def toml = new groovy.toml.TomlBuilder()
           toml.person()

           assert toml.toString() == '''\
           person = {}
           '''

      Parameters:
        `name` - the single key
        `args` - the value associated with the key
      Returns:
        a map with a single key

    - #### public String toString()

      Serializes the internal data structure built with the builder to a conformant TOML payload string

      Example:

           def toml = new groovy.toml.TomlBuilder()
           toml { temperature 37 }

           assert toml.toString() == '''\
           temperature = 37
           '''

      Returns:
        a TOML output

    - #### public static String toToml(Object object)

      Serializes a typed object to a TOML string using Jackson databinding. Supports `@JsonProperty` and `@JsonFormat` annotations.

      Parameters:
        `object` - the object to serialize
      Returns:
        the TOML string
      Since:
        6.0.0

    - #### public Writer writeTo(Writer out)

      The TOML builder implements the `Writable` interface, so that it can serialize its TOML payload to a writer.

      Example:

           def toml = new groovy.toml.TomlBuilder()
           toml { temperature 37 }

           def out = new StringWriter()
           out << toml

           assert out.toString() == '''\
           temperature = 37
           '''

      Parameters:
        `out` - a writer on which to serialize the TOML payload
      Returns:
        the writer