[
https://issues.apache.org/jira/browse/GROOVY-8794?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16616558#comment-16616558
]
ASF GitHub Bot commented on GROOVY-8794:
----------------------------------------
Github user paulk-asert commented on a diff in the pull request:
https://github.com/apache/groovy/pull/797#discussion_r217899737
--- Diff: subprojects/groovy-yaml/src/spec/doc/yaml-userguide.adoc ---
@@ -0,0 +1,112 @@
+//////////////////////////////////////////
+
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+//////////////////////////////////////////
+
+= Processing YAML
+
+Groovy comes with integrated support for converting between Groovy objects
and YAML. The classes dedicated to
+YAML serialisation and parsing are found in the `groovy.yaml` package.
+
+[[yaml_yamlslurper]]
+== 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.
+
+[source,groovy]
+----
+include::{rootProjectDir}/subprojects/groovy-yaml/src/spec/test/groovy/yaml/YamlParserTest.groovy
+----
+
+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 http://yaml.org/spec/1.2/spec.html[YAML Ain’t
Markup Language (YAML™)].
+
+In addition to maps `YamlSlurper` supports YAML arrays which are converted
to lists.
+
+[source,groovy]
+----
+include::{rootProjectDir}/subprojects/groovy-yaml/src/spec/test/groovy/yaml/YamlParserTest.groovy
+----
+
+The YAML standard supports the following primitive data types: string,
number, object, `true`, `false` and `null`. `YamlSlurper`
+converts these YAML types into corresponding Groovy types.
+
+[source,groovy]
+----
+include::{rootProjectDir}/subprojects/groovy-yaml/src/spec/test/groovy/yaml/YamlParserTest.groovy
+----
+
+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).
+
+[NOTE]
+For more details please have a look at the section on
<<core-semantics.adoc#gpath_expressions,GPath expressions>>.
+
+The following table gives an overview of the YAML types and the
corresponding Groovy data types:
+
+[cols="1,3" options="header"]
+|===
+|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
+|===
+
+[NOTE]
+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.
+
+=== 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.
+
+[source,groovy]
+----
+include::{rootProjectDir}/subprojects/groovy-yaml/src/spec/test/groovy/yaml/YamlBuilderTest.groovy
--- End diff --
I'd just bring in lines 24-50
> Add groovy-yaml subproject to support parsing and building yaml
> ---------------------------------------------------------------
>
> Key: GROOVY-8794
> URL: https://issues.apache.org/jira/browse/GROOVY-8794
> Project: Groovy
> Issue Type: New Feature
> Reporter: Daniel Sun
> Assignee: Daniel Sun
> Priority: Major
> Fix For: 2.5.3
>
>
--
This message was sent by Atlassian JIRA
(v7.6.3#76005)
