Package ca.spatial.util

Class YamlConfig

java.lang.Object
ca.spatial.util.YamlConfig
public class YamlConfig extends Object
This class supports loading and selectively unpacking values from YAML files. The YAML format is a superset of JSON and is useful for storing structured configuration data. YAML allows arbitrarily nested dictionaries and lists: lists may contain other lists or dictionaries, and dictionaries may contain other dictionaries or lists. Leaf value may be strings, numbers or booleans. Other advanced YAML features such as aliases are also supported.

This class will load the contents of a YAML file into a correspondingly nested set of Map and List objects. Methods in this class can be used to walk through the nodes of the data structure, testing the values of the nodes, and retrieving branch and leaf values.

Example

This example will consider a YAML file with a name of myConfig.yaml containing the following contents: 

 Key1:
   - list value 1
   - list value 2
 Key2:
   Key2a: 3
   Key2b: 4
This YAML file contains a top level dictionary with keys of Key1 and Key2. Under the branch for Key1 is a list containing two entries. Under the branch for Key2 is another dictionary containing two keys.

We can use this YamlConfig class to open and parse this file, loading the contents in to appropriate data structures: 


 YamlConfig config = new YamlConfig("myConfig.yaml");
Now that the file is loaded we can use method to retrieve values. This YamlConfig class contains many convenience features for testing conditions and safely extracting values (for example getDouble, getString, isLeaf, isMap and others). There are also methods to retrieve the raw Map, List or Object values (getMap, getList and get respectively).

There are two types of methods that can be used to extract branches.

  • The methods getMap and getList return references to the raw Map and List objects. Values within these containers can be extracted using the standard Collection interface.
  • The getBranch method returns a YamlConfig object that is rooted at the specified element. This object provides all of the conveience methods, but operating on a different branch of the tree.
Most of the convenience methods accept a list of keys that are then used to traverse the config structure. The keys are either String values to reference the dictionary elements or integers to reference the list elements. In Java, elements of a list (or array) are numbered starting at zero. The first element of a list is at position 0, the second element at position 1, etc.

For example, to access the String "list value 1" that is the first list element under the key Key1 we could use the getString method: 


 String s = config.getString("Key1", 0);
We could do the same operation in several steps: 

 YamlConfig branch1 = config.getBranch("Key1");
 String s = branch1.getString(0);

Rather than returning a branch that is wrapped with the convenience methods, we can get the raw container and process it using the Collection interface methods: 


 for (Object s : config.getList("Key1"))
    System.err.println("list contains "+s);

Scripting with BeanShell

This class can be used within the BeanShell scripting environment with one caveat and a few simplifications.
  1. BeanShell version 2.0b5 which is currently being used in Patchworks does not support the varargs style of variable argument passing. When a variable number of arguments are passed to a constructor or method they must be boxed in to an array.
  2. BeanShell has a relaxed syntax and does not required variable type declarations.
The previous example code could be coded as follows to work in BeanShell: 

 s = config.getString(new Object[] {"Key1", 0});
 branch1 = config.getBranch(new Object[] {"Key1"});
 s = branch1.getString(new Object[] {0});
 for (Object s : config.getList(new Object[] {"Key1"}))
    System.err.println("list contains "+s);

  • Constructor Details

    • YamlConfig

      public YamlConfig​(String configFile)
      Initialize this class with the name of a yaml file

    • YamlConfig

      public YamlConfig​(Map config)
      Initialize this class with a Map object

    • YamlConfig

      public YamlConfig​(List config)
      Initialize this class with a List object

  • Method Details

    • isList

      public boolean isList​(Object... keys)
      Is this object at these keys a List?

    • isMap

      public boolean isMap​(Object... keys)
      Is this object at these keys a Map?

    • isLeaf

      public boolean isLeaf​(Object... keys)
      Is this branch of the config a leaf?

    • containsKey

      public boolean containsKey​(Object key)
      Check if the key exists in the map, or the index number is valid for the list.

    • get

      public Object get​(Object... keys)
      Retrieve an object from the configuration
      Parameters:
      keys - an array of keys in to the configuration

    • getString

      public String getString​(Object... keys)
      Retrieve a String from the configuration
      Parameters:
      keys - an array of keys in to the configuration

    • getInt

      public int getInt​(Object... keys)
      Retrieve an integer from the configuration
      Parameters:
      keys - an array of keys in to the configuration

    • getDouble

      public double getDouble​(Object... keys)
      Retrieve a double from the configuration
      Parameters:
      keys - an array of keys in to the configuration

    • getBoolean

      public boolean getBoolean​(Object... keys)
      Retrieve a boolean from the configuration
      Parameters:
      keys - an array of keys in to the configuration

    • getList

      public List getList​(Object... keys)
      Retrieve a List object from the configuration
      Parameters:
      keys - an array of keys in to the configuration

    • getMap

      public Map getMap​(Object... keys)
      Retrieve a Map object from the configuration
      Parameters:
      keys - an array of keys in to the configuration

    • getMatcher

      public Matcher getMatcher​(Object... keys)
      Retrieve a Matcher object from the configuration. This method will extract a String value from the location in the tree specified by the keys argument, compile this value as a regular expression pattern and retrieve a Matcher object on this pattern.
      Parameters:
      keys - an array of keys in to the configuration

    • getMatchers

      public Matcher[] getMatchers​(Object... keys)
      Retrieve an array of Matcher objects from the configuration. This method will retrieve a list from the location in the configuration as specified by the keys. Each of the list items will be retrieved as a String and compiled as a regular expression pattern. An array of Matcher objects will be returned, one for each element in the list.
      Parameters:
      keys - an array of keys in to the configuration

    • getBranch

      public YamlConfig getBranch​(Object... keys)
      Retrieve a branch object (Map or List) from the configuration and wrap it as a YamlConfig object.
      Parameters:
      keys - an array of keys in to the configuration

    • size

      public int size()

    • get

      public static Object get​(Object config, Class clz, Object... keys)
      Retrieve an entry from the YAML file based on a list of keys. The method will search through a hierarchical set of dictionaries and lists to find the requested entry.

      The found object will be tested against the specified class and an error will be thrown if the type does not match.

      Parameters:
      config - a dictionary or list from the yaml config
      clz - the expected class of the entry. If the class does not match then an error will be thrown. To skip type checking specify Object.class
      keys - the chain of keys to look for in the dictionary