Package groovy.toml

# Class TomlBuilder

java.lang.Object
groovy.lang.GroovyObjectSupport
groovy.toml.TomlBuilder

All Implemented Interfaces:
  `GroovyObject`, `Writable`

@Incubating public class TomlBuilder extends GroovyObjectSupport implements Writable
A builder for creating TOML payloads.

Since:
  4.0.0

- ## Constructor Summary

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

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Object`
  `call(Closure c)`
  A closure passed to a TOML builder will create a root TOML object
  `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
  `Object`
  `call(Object... args)`
  Varargs elements as arguments to the TOML builder create a root TOML 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 TOML builder creates a root TOML array
  `Object`
  `call(Map m)`
  Named arguments can be passed to the TOML builder instance to create a root TOML object
  `Object`
  `getContent()`
  Returns the current root structure managed by this builder.
  `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.
  `String`
  `toString()`
  Serializes the internal data structure built with the builder to a conformant TOML payload string
  `static String`
  `toToml(Object object)`
  Serializes a typed object to a TOML string using Jackson databinding.
  `Writer`
  `writeTo(Writer out)`
  The TOML builder implements the `Writable` interface, so that it can serialize its TOML 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

  - ### TomlBuilder

    public TomlBuilder()
    Creates an empty builder ready to assemble a TOML document.

- ## Method Details

  - ### toToml

    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

  - ### getContent

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

  - ### call

    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

  - ### call

    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

  - ### call

    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

  - ### call

    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

  - ### 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 TOML content
      `c` - the closure that maps each collection element to TOML content
    Returns:
      a list of values

  - ### call

    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

  - ### invokeMethod

    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 = {}
         '''

    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 TOML payload string

    Example:

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

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

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

  - ### writeTo

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

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