Detailed Description

YAML configuration class for AliPhysics.

A class to handle generic reading and writing to YAML files. This can be used to configure tasks, coordinate trains, or many other tasks which require configuration. While yaml-cpp can be used directly, this class handles many details such as accessing files on AliEn, as well as generally simplifying the user experience. The class can also handle multiple configuration files, first looking in the first file, and then if the value is not found, looking in subsequent configurations until the value is found. Values that are used in multiple places can be set together using "Shared Paramaters" (see the section below) or using YAML anchors.

Usage information:

Consider the following example YAML configuration.

hello:
  world:
    exampleValue: 10
importantValue:
  - entry1
  - entry2
  - entry3

To use the class, at least one YAML configuration file must be added to the class. To do so, use:

AliYAMLConfiguration config;
config.AddConfiguration(filename, name);
// Will only be checked if a requested value is not in the first configuration.
config.AddConfiguration(filename2, name2);
// Can also just start with an empty configuration if desired. Perhaps for writing.
config.AddEmptyConfiguration(name3);
// Once all configuration is done and the YAML nodes will not be modified any more
// (for example, at the end of an AddTask), call Initialize() to lock in the configurations
// for streaming to the grid.
config.Initialize();

YAML objects cannot be streamed, so after the configuration class is streamed, it must be re-initialized. This can be done in any function after streaming has been completed, such as UserCreateOutputObjects(). It only needs to be performed once.

fYAMLConfig.Reinitialize();

To access a value, use the GetProperty(...) or WriteProperty(...) functions. To use them, you must define an object of the desired type that you would like to read or write, and then describe the path to the property. The path consists of the names of YAML nodes, separated by a user specified delimiter (":" is the default). For the example YAML above, to read "exampleValue", the user would define an int to be set to the read value and the path would be "hello:world:exampleValue". As a convenience, there is a helper function which simplifies specifying the path. It will instead take a std::vector of strings to specify the path, thereby also setting the proper delimiter. So the path would be {"hello", "world", "exampleValue"}. Note that you may need to explicitly specify such an initialization as std::vector<std::string> if you don't define it as a variable.

That's basically all there is to using it. For more information, look at the documentation of the various GetProperty(...) and WriteProperty(...) functions.

Notes on using shared parameters:

sharedParameters are inherently limited. It can only retrieve values where the requested type is arithmetic, string, or bool. The retrieved shared parameters value can only be of those same types. Note that the shared parameters correspond to each configuration file. ie. If "sharedParameters:test" is requested in the first configuration file, then it will only look for the sharedParameters value in that configuration. Thus, if a sharedParameter is requested in a later configuration file, the earlier configuration shared parameter values will not be considered.

Given the limitations, YAML anchors are recommended for more advanced usage as they can be much more sophisticated.

Author: Raymond Ehlers raymo.nosp@m.nd.e.nosp@m.hlers.nosp@m.@yal.nosp@m.e.edu, Yale University

Date: Sept 19, 2017

The documentation for this class was generated from the following file:

PWG/Tools/AliYAMLConfiguration.h