# Processing YAML

version 3.0.3

Groovy has an optional `groovy-yaml` module which provides support for converting between Groovy objects and YAML. The classes dedicated to YAML serialisation and parsing are found in the `groovy.yaml` package.

## 1. YamlSlurper

`YamlSlurper` is a class that parses YAML text or reader content into Groovy data structures (objects) such as maps, lists and primitive types like `Integer`, `Double`, `Boolean` and `String`.

The class comes with a bunch of overloaded `parse` methods plus some special methods such as `parseText` and others. For the next example we will use the `parseText` method. It parses a YAML `String` and recursively converts it to a list or map of objects. The other `parse*` methods are similar in that they return a YAML `String` but for different parameter types.

            def ys = new YamlSlurper()
            def yaml = ys.parseText '''
    language: groovy
    sudo: required
    dist: trusty

    matrix:
      include:
    #    - jdk: oraclejdk11
        - jdk: openjdk10
        - jdk: oraclejdk9
        - jdk: oraclejdk8

    before_script:
      - |
        unset _JAVA_OPTIONS

            '''

            assert 'groovy' == yaml.language
            assert 'required' == yaml.sudo
            assert 'trusty' == yaml.dist
            assert ['openjdk10', 'oraclejdk9', 'oraclejdk8'] ==  yaml.matrix.include.jdk
            assert ['unset _JAVA_OPTIONS'] == yaml.before_script*.trim()

Notice the result is a plain map and can be handled like a normal Groovy object instance. `YamlSlurper` parses the given YAML as defined by the YAML Ain’t Markup Language (YAML™).

As `YamlSlurper` is returning pure Groovy object instances without any special YAML classes in the back, its usage is transparent. In fact, `YamlSlurper` results conform to GPath expressions. GPath is a powerful expression language that is supported by multiple slurpers for different data formats (`XmlSlurper` for XML being one example).

| For more details please have a look at the section on GPath expressions.

The following table gives an overview of the YAML types and the corresponding Groovy data types:

YAML | Groovy
--- | ---
string | `java.lang.String`
number | `java.lang.BigDecimal` or `java.lang.Integer`
object | `java.util.LinkedHashMap`
array | `java.util.ArrayList`
true | `true`
false | `false`
null | `null`
date | `java.util.Date` based on the `yyyy-MM-dd’T’HH:mm:ssZ` date format

| Whenever a value in YAML is `null`, `YamlSlurper` supplements it with the Groovy `null` value. This is in contrast to other YAML parsers that represent a `null` value with a library-provided singleton object.

### 1.1. Builders

Another way to create YAML from Groovy is to use `YamlBuilder`. The builder provide a DSL which allows to formulate an object graph which is then converted to YAML.

            def builder = new YamlBuilder()
            builder.records {
                car {
                    name 'HSV Maloo'
                    make 'Holden'
                    year 2006
                    country 'Australia'
                    homepage new URL('http://example.org')
                    record {
                        type 'speed'
                        description 'production pickup truck with speed of 271kph'
                    }
                }
            }

            assert builder.toString() == '''---
    records:
      car:
        name: "HSV Maloo"
        make: "Holden"
        year: 2006
        country: "Australia"
        homepage: "http://example.org"
        record:
          type: "speed"
          description: "production pickup truck with speed of 271kph"
    '''