A utility class for centralizing basic YAML operations required by Jervis. Reads and writes YAML. This utility class is necessary because of a few major changes around how YAML loading works due to vulnerabilities or usage. So this utility class is to help minimize required changes to YAML usage.
To run this example, clone Jervis and execute ./gradlew console to bring up a Groovy Console with the classpath set up.
import net.gleske.jervis.tools.YamlOperator
String yaml = '''
key: value
list:
- one
- two
- three
'''
// Load YAML from many object types
Map result = YamlOperator.loadYamlFrom(yaml)
// Export YAML as a String
println(YamlOperator.writeObjToYaml(result))
// Write YAML to a File
YamlOperator.writeObjToYaml(new File('/tmp/file.yaml')), result)
Type Params | Return Type | Name and description |
---|---|---|
|
static Object |
getObjectValue(Map object, String key, Object defaultValue) Get an object from a Map or return any object from defaultValue. |
|
static def |
loadYamlFrom(InputStream srcStream) Parse YAML from an InputStream. |
|
static def |
loadYamlFrom(String srcString) Parse YAML from a String. |
|
static def |
loadYamlFrom(StringWriter srcString) Parse YAML from a StringWriter which is typically used by Jervis as an in-memory String buffer. |
|
static def |
loadYamlFrom(byte[] srcBytes) Parse YAML from a Byte array. |
|
static def |
loadYamlFrom(File srcFile) Given a file, this will load YAML from a File and return a Java object consisting of standard classes. |
|
static String |
writeObjToYaml(def yamlToSerialize) Convert a POJO consisting of standard Java classes into a YAML string. |
|
static void |
writeObjToYaml(File destFile, def yamlToSerialize) Convert a POJO consisting of standard Java classes into YAML written in a file. |
Get an object from a Map or return any object from defaultValue. Guarantees that what is returned is the same type as defaultValue. This is used to get optional keys from YAML or JSON files.
import static net.gleske.jervis.tools.YamlOperator.getObjectValue
Map hexKeys = [
'hello.io': 'world',
hello: ['jervis.io{': 'friend'],
friend: [name: 'dog']
]
// Do a normal lookup with a hierarchy of keys
assert getObjectValue(hexKeys, 'friend.name', '') == 'dog'
// Do a normal lookup with a hierarchy of keys; but result is not a List so
// falls back to default
assert getObjectValue(hexKeys, 'friend.name', [['item']]) == ['item']
// The above is not to be confused with a List of default fallbacks. Which
// would result in the dog being returned.
assert getObjectValue(hexKeys, 'friend.name', ['item']) == 'dog'
// top level lookup; but the key has a period in it
assert getObjectValue(hexKeys, 'hello\\.io', '') == 'world'
// top level lookup; but the period is already escaped with a hex code.
assert getObjectValue(hexKeys, 'hello%{2e}io', '') == 'world'
// A hierarchy of keys but some of the child keys have special characters
assert getObjectValue(hexKeys, 'hello.jervis\\.io\\{', '') == 'friend'
// quoting works, too
assert getObjectValue(hexKeys, '"hello.io"', '') == 'world'
assert getObjectValue(hexKeys, 'hello."jervis.io"{', '') == 'friend'
// you can request fallback expressions by separting expressions with ' // '
assert getObjectValue(hexKeys, 'hello."jervis.io"{ // friend', [:]) == [name: 'dog']
// Check the hello key for multiple types and if none, then return the first
// default. The following will check for a String or a List as the default.
assert getObjectValue(hexKeys, 'hello', [ '', [] ]) == ''
// and now the same using both search fallback and default fallback
assert getObjectValue(hexKeys, 'hello // friend.name', [ '', [] ]) == 'dog'
In the above example, notice that some characters can be escaped. For example, if the key has a period in its name it is escaped with \\.. Any character can be escaped this way.
key can take multiple fallback expressions if you separate expressions with // .
defaultValue can take multiple fallback defaults. So you can search for multiple types on a single path falling back to ones you support.
If you need a List of items to be the defaultValue, then you must nest it within a List such as [['item']]. This List contains a List of one item.
object
- A Map which was likely created from a YAML or JSON file.key
- A String with keys and subkeys separated by periods which is
used to search the object for a possible value.defaultValue
- A default value and type that should be returned.Parse YAML from an InputStream.
srcStream
- A stream which contains String-data consisting of YAML.Parse YAML from a String.
srcString
- A String which contains YAML to be parsed.Parse YAML from a StringWriter which is typically used by Jervis as an in-memory String buffer.
srcString
- A String which contains YAML to be parsed.Parse YAML from a Byte array.
srcBytes
- A Byte array which contains YAML to be parsed.Given a file, this will load YAML from a File and return a Java object consisting of standard classes.
srcFile
- A file with YAML content.Convert a POJO consisting of standard Java classes into a YAML string.
yamlToSerialize
- A POJO consisting of standard Java class instance
objects.Convert a POJO consisting of standard Java classes into YAML written in a file. This will overwrite the provided file if it exists.
destFile
- A file where the YAML output will be written.yamlToSerialize
- A POJO consisting of standard Java class instance
objects.