AliPhysics  cc1c0ba (cc1c0ba)
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
AliYAMLConfiguration Class Reference

YAML configuration class for AliPhysics. More...

#include <AliYAMLConfiguration.h>

Inheritance diagram for AliYAMLConfiguration:

Public Member Functions

 AliYAMLConfiguration (const std::string prefixString="AliEmcalCorrection", const std::string delimiterCharacter=":")
 
virtual ~AliYAMLConfiguration ()
 
bool Initialize ()
 
bool Reinitialize ()
 
bool AddEmptyConfiguration (const std::string &configurationName)
 Add YAML configuration at configurationFilename to available configurations. More...
 
bool AddConfiguration (std::string configurationFilename, std::string configurationName="")
 
bool AddConfiguration (const YAML::Node node, std::string configurationName="")
 
const std::pair< std::string,
YAML::Node > & 
GetConfiguration (const int i) const
 
const std::pair< std::string,
YAML::Node > & 
GetConfiguration (const std::string &name) const
 
std::pair< std::string,
YAML::Node > & 
GetConfiguration (const int i)
 
std::pair< std::string,
YAML::Node > & 
GetConfiguration (const std::string &name)
 
template<typename T >
bool GetProperty (std::vector< std::string > propertyPath, const std::string &propertyName, T &property, const bool requiredProperty) const
 
template<typename T >
bool GetProperty (const std::vector< std::string > propertyPath, T &property, const bool requiredProperty) const
 
template<typename T >
bool GetProperty (std::string propertyName, T &property, const bool requiredProperty=true) const
 
template<typename T >
bool WriteProperty (std::string propertyName, T &property, std::string configurationName="")
 
bool WriteConfiguration (const std::string &filename, const unsigned int i) const
 
bool WriteConfiguration (const std::string &filename, const std::string &configurationName) const
 
void PrintConfiguration (const unsigned int i=0) const
 
void PrintConfiguration (const std::string &name) const
 
void PrintConfigurations () const
 

Protected Member Functions

bool DoesFileExist (const std::string &filename) const
 
void SetupReadingConfigurationFilePath (std::string &filename, const std::string &fileIdentifier) const
 
void WriteConfigurationToFilePath (const std::string &localFilename, std::string filename) const
 
template<typename T >
unsigned int GetConfigurationIndexByName (const std::string &name, const std::vector< std::pair< std::string, T >> &configurations) const
 
bool IsSharedValue (std::string &value) const
 
template<typename T >
auto PrintRetrievedPropertyValueImpl (std::stringstream &tempMessage, const T &property, int) const -> decltype(tempMessage<< property, void())
 
template<typename T >
auto PrintRetrievedPropertyValueImpl (std::stringstream &tempMessage, const std::vector< T > &property, int) const -> decltype(property.begin(), property.end(), tempMessage<< std::declval< T >(), void())
 
template<typename T >
void PrintRetrievedPropertyValueImpl (std::stringstream &tempMessage, const T &property, long) const
 
template<typename T >
void PrintRetrievedPropertyValue (std::stringstream &tempMessage, const T &property) const
 
template<typename T >
bool GetPropertyFromNode (const YAML::Node &node, std::string propertyName, T &property) const
 
template<typename T >
bool GetProperty (YAML::Node &node, YAML::Node &sharedParametersNode, const std::string &configurationName, std::string propertyName, T &property) const
 
template<typename T >
void WriteValue (YAML::Node &node, std::string propertyName, T &proeprty)
 

Protected Attributes

std::vector< std::pair
< std::string, YAML::Node > > 
fConfigurations
 ! Contains all YAML configurations. The first element has the highest precedence. More...
 
std::vector< std::pair
< std::string, std::string > > 
fConfigurationsStrings
 Contains all YAML configurations as strings so that they can be streamed. More...
 
bool fInitialized
 True if the configurations have been initialized. More...
 
std::string fPrefixString
 Contains the prefix of any names base node names which should be removed. More...
 
std::string fDelimiter
 Delimiter character to separate each level of the request. More...
 

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:

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

Definition at line 93 of file AliYAMLConfiguration.h.

Constructor & Destructor Documentation

AliYAMLConfiguration::AliYAMLConfiguration ( const std::string  prefixString = "AliEmcalCorrection",
const std::string  delimiterCharacter = ":" 
)

Default constructor.

Parameters
[in]prefixStringPrefix to remove when gettnig a property.
[in]delimiterCharacterCharacter that delimits between each part of the YAML path.

Definition at line 24 of file AliYAMLConfiguration.cxx.

virtual AliYAMLConfiguration::~AliYAMLConfiguration ( )
inlinevirtual

Definition at line 96 of file AliYAMLConfiguration.h.

Member Function Documentation

bool AliYAMLConfiguration::AddConfiguration ( std::string  configurationFilename,
std::string  configurationName = "" 
)

Add YAML configuration at a given filename to the available configurations.

Parameters
[in]configurationFilenameFilename of the YAML configuration file to be added.
[in]configurationNameName of the YAML node. The node will be stored under this name.
Returns
True if the configuration was added successfully.

Definition at line 56 of file AliYAMLConfiguration.cxx.

Referenced by AddEmptyConfiguration(), AliAnalysisTaskEmcalEmbeddingHelper::AutoConfigurePtHardBins(), and AliEmcalCorrectionTask::InitializeConfiguration().

bool AliYAMLConfiguration::AddConfiguration ( const YAML::Node  node,
std::string  configurationName = "" 
)

Add a YAML node to the available configurations.

Parameters
[in]nodeYAML node to be added.
[in]configurationNameName of the YAML node. The node will be stored under this name.
Returns
True if the configuration was added successfully.

Definition at line 86 of file AliYAMLConfiguration.cxx.

bool AliYAMLConfiguration::AddEmptyConfiguration ( const std::string &  configurationName)

Add YAML configuration at configurationFilename to available configurations.

Create an empty YAML node and adds it to the available configurations.

Parameters
[in]configurationNameName of the YAML node. The node will be stored under this name.
Returns
True if the configuration was added successfully.

Definition at line 41 of file AliYAMLConfiguration.cxx.

Referenced by AliAnalysisTaskEmcalEmbeddingHelper::AutoConfigurePtHardBins().

bool AliYAMLConfiguration::DoesFileExist ( const std::string &  filename) const
inlineprotected

Checks if a file exists. This is done inline to make it efficient. See: https://stackoverflow.com/a/19841704

Parameters
filenameString containing the filename of the file to check.
Returns
True if the file exists.

Definition at line 155 of file AliYAMLConfiguration.cxx.

Referenced by AddConfiguration().

const std::pair<std::string, YAML::Node>& AliYAMLConfiguration::GetConfiguration ( const int  i) const
inline
const std::pair<std::string, YAML::Node>& AliYAMLConfiguration::GetConfiguration ( const std::string &  name) const
inline

Definition at line 108 of file AliYAMLConfiguration.h.

std::pair<std::string, YAML::Node>& AliYAMLConfiguration::GetConfiguration ( const int  i)
inline

Definition at line 109 of file AliYAMLConfiguration.h.

std::pair<std::string, YAML::Node>& AliYAMLConfiguration::GetConfiguration ( const std::string &  name)
inline

Definition at line 110 of file AliYAMLConfiguration.h.

template<typename T >
unsigned int AliYAMLConfiguration::GetConfigurationIndexByName ( const std::string &  name,
const std::vector< std::pair< std::string, T >> &  configurations 
) const
protected

Get the index of the configuration given the configuration name.

Parameters
[in]nameName of the configuration.
[in]configurationsConfigurations to search through (could contain YAML nodes, or the string copies).
Returns
Index of the configuration, or -1 if not found.

Definition at line 571 of file AliYAMLConfiguration.h.

Referenced by GetConfiguration(), PrintConfiguration(), WriteConfiguration(), and WriteProperty().

template<typename T >
bool AliYAMLConfiguration::GetProperty ( std::vector< std::string >  propertyPath,
const std::string &  propertyName,
T property,
const bool  requiredProperty 
) const

Helper function for main retrieval function. It automatically adds the property name to the end of the property path. By doing so, it allows the user to specify a general property path and then vary the property name between function calls.

Parameters
[in]propertyPathPath to the property in the YAML file.
[in]propertyNameName of the property to be retrieved.
[out]propertyContains the retrieved property.
[in]requiredPropertyTrue if the property is required
Returns
True if the property was set successfully

Definition at line 278 of file AliYAMLConfiguration.h.

Referenced by AliEmcalCorrectionTask::AddContainer(), AliEmcalCorrectionTask::AddContainersToComponent(), AliAnalysisTaskEmcalEmbeddingHelper::AutoConfigurePtHardBins(), AliEmcalCorrectionTask::CreateInputObjects(), AliEmcalCorrectionTask::DetermineComponentsToExecute(), AliEmcalCorrectionComponent::GetProperty(), GetProperty(), AliEmcalCorrectionComponent::Initialize(), AliEmcalCorrectionTask::SetupCellsInfo(), and AliEmcalCorrectionTask::SetupContainer().

template<typename T >
bool AliYAMLConfiguration::GetProperty ( const std::vector< std::string >  propertyPath,
T property,
const bool  requiredProperty 
) const

Helper function for main retrieval function. Each value in the property path will be joined together, separated by the delimiter set in the configuration class.

Parameters
[in]propertyPathPath to the property in the YAML file.
[out]propertyContains the retrieved property.
[in]requiredPropertyTrue if the property is required
Returns
True if the property was set successfully

Definition at line 295 of file AliYAMLConfiguration.h.

template<typename T >
bool AliYAMLConfiguration::GetProperty ( std::string  propertyName,
T property,
const bool  requiredProperty = true 
) const

Main general function to get a property from a set of YAML configuration files. It first calls checks the user configuration, and then if the property is not found, it then checks the default configuration. If the property is required but it is not found, a fatal error is thrown.

Parameters
[in]propertyNameName of the property to retrieve
[out]propertyContains the retrieved property
[in]requiredPropertyTrue if the property is required
[in]correctionNameName of the correction from where the property should be retrieved
Returns
True if the property was set successfully

Definition at line 326 of file AliYAMLConfiguration.h.

template<typename T >
bool AliYAMLConfiguration::GetProperty ( YAML::Node &  node,
YAML::Node &  sharedParametersNode,
const std::string &  configurationName,
std::string  propertyName,
T property 
) const
protected

Actually handles retrieving parameters from YAML nodes.

For propertyName = "hello:example_special:property", the retrieval procedure is as follows:

  • Extract node name by searching the propertyName up to the delimiter (in this case, "hello").
  • Look up the node name.
    • If the node exists, recurse with node[nodeName] and with remaining propertyName = "example_special:property".
    • If it doesn't exist, check for the specialization delimiter (default: "_") and take the node name as everything before the delimiter (for example, "example_special" leads to "example").
  • If the delimiter is not found, then atempt to extract the property with the remaining node name.
    • If the property is arithmetic, std::string, or bool, it will check if the property is instead a shared parameter. If so, it will retrieve the shared parameter value.
    • The property is stored in the property, and true is returned if the effort was successful.
Parameters
[in]nodeMain YAML node containing the properties
[in]sharedParametersNodeYAML node containing the shared parameters
[in]configurationNameName of the configuration type.
[in]propertyNameName of the property to retrieve
[out]propertyContains the retrieved property
Returns
True if the property was set successfully

Definition at line 390 of file AliYAMLConfiguration.h.

template<typename T >
bool AliYAMLConfiguration::GetPropertyFromNode ( const YAML::Node &  node,
std::string  propertyName,
T property 
) const
protected

Utility function to retrieve the property from a already selected YAML node.

Parameters
[in]nodeYAML node from which the property should be retrieved
[in]propertyNameName of the property to retrieve
[out]propertyContains the retrieved property
Returns
True if the property was set successfully

Definition at line 256 of file AliYAMLConfiguration.h.

Referenced by AddConfiguration(), and GetProperty().

bool AliYAMLConfiguration::Initialize ( )

Initialize configurations.

This includes storing the contents of the YAML configurations into strings so that they can be streamed to the grid. (yaml-cpp objects do not work properly with ROOT streamers).

NOTE: fConfigurationInitialized is set to true if the function is successful.

Definition at line 253 of file AliYAMLConfiguration.cxx.

Referenced by AliEmcalCorrectionTask::InitializeConfiguration().

bool AliYAMLConfiguration::IsSharedValue ( std::string &  value) const
protected

Check if value is a shared parameter, meaning we should look at another node. Also edits the input string to remove "sharedParameters:" if it exists, making it ready for use.

Parameters
[in]valueString containing the string value return by the parameter.
Returns
True if the value is shared.

Definition at line 310 of file AliYAMLConfiguration.cxx.

Referenced by GetProperty().

void AliYAMLConfiguration::PrintConfiguration ( const unsigned int  i = 0) const

Print a particular configuration.

Parameters
[in]iIndex of the YAML configuration.

Definition at line 328 of file AliYAMLConfiguration.cxx.

Referenced by PrintConfiguration(), and PrintConfigurations().

void AliYAMLConfiguration::PrintConfiguration ( const std::string &  name) const

Print a particular configuration.

Parameters
[in]nameName of the YAML configuration.

Definition at line 343 of file AliYAMLConfiguration.cxx.

void AliYAMLConfiguration::PrintConfigurations ( ) const

Print all configurations.

Definition at line 351 of file AliYAMLConfiguration.cxx.

template<typename T >
void AliYAMLConfiguration::PrintRetrievedPropertyValue ( std::stringstream &  tempMessage,
const T property 
) const
protected

Wrapper function to resolve ambiguity in function overloading. By passing 0 as the last argument to the PrintRetrievedPropertyValueImpl(...) functions, it will first attempt to use the matching int function, and then fall back the to the long function. This is effectively a hack to help c++ properly resolve the function to call.

Inspired by: https://stackoverflow.com/a/38283990

Parameters
[in]propertyProperty to be printed
[in,out]tempMessageStringstream into which the property should be streamed

Definition at line 240 of file AliYAMLConfiguration.h.

Referenced by GetProperty().

template<typename T >
auto AliYAMLConfiguration::PrintRetrievedPropertyValueImpl ( std::stringstream &  tempMessage,
const T property,
int   
) const -> decltype(tempMessage << property, void())
protected

Prints the retrieved property value if the type implements operator<<(). For more on how this achieved, see: https://stackoverflow.com/a/22759368 and https://stackoverflow.com/a/11866675. NOTE: This function should not be called directly, but through PrintRetrievedPropertyValue(...)

NOTE: This function returns void!

Parameters
[in]propertyProperty to be printed
[in,out]tempMessageStringstream into which the property should be streamed

Definition at line 188 of file AliYAMLConfiguration.h.

Referenced by PrintRetrievedPropertyValue().

template<typename T >
auto AliYAMLConfiguration::PrintRetrievedPropertyValueImpl ( std::stringstream &  tempMessage,
const std::vector< T > &  property,
int   
) const -> decltype(property.begin(), property.end(), tempMessage << std::declval<T>(), void())
protected

Prints the retrieved values in a vector if the value is a vector (more specifically, if it implements begin() and end()) and if the type of the vector can be streamed in an ostream object. NOTE: This function should not be called directly, but through PrintRetrievedPropertyValue(...)

Parameters
[in]propertyProperty to be printed
[in,out]tempMessageStringstream into which the property should be streamed

Definition at line 202 of file AliYAMLConfiguration.h.

template<typename T >
void AliYAMLConfiguration::PrintRetrievedPropertyValueImpl ( std::stringstream &  tempMessage,
const T property,
long   
) const
protected

Handles all other cases where the property is not covered by the other functions.

NOTE: This function should not be called directly, but through PrintRetrievedPropertyValue(...)

NOTE: Cannot use "..." as a function argument here as a fall back because it causes problems with ROOT dictionary generation...

Parameters
[in]propertyProperty to be printed
[in,out]tempMessageStringstream into which the property should be streamed

Definition at line 222 of file AliYAMLConfiguration.h.

bool AliYAMLConfiguration::Reinitialize ( )

Reinitialize the configurations from the strings after streaming. This is required because the YAML node objects cannot be streamed.

Returns
True if the configurations were re-initialized.

Definition at line 276 of file AliYAMLConfiguration.cxx.

Referenced by AliEmcalCorrectionTask::UserCreateOutputObjects().

void AliYAMLConfiguration::SetupReadingConfigurationFilePath ( std::string &  filename,
const std::string &  fileIdentifier 
) const
protected

Handles setting up the configuration file to be opened, including in AliPhysics and on the grid. Cannot just use TFile::Open() because the YAML file is just text as opposed to a root file. In the case of a file on the grid, it is copied locally.

Parameters
[in,out]filenameName of the file to be open
[in]fileIdentifierAdditional file identifier to add onto the file name

Definition at line 169 of file AliYAMLConfiguration.cxx.

Referenced by AddConfiguration().

bool AliYAMLConfiguration::WriteConfiguration ( const std::string &  filename,
const unsigned int  index 
) const

Write a YAML configuration node to file.

Parameters
[in]indexIndex of the YAML configuration node.
[in]filenameFilename to write the node to.
Returns
True if write was successful.

Definition at line 114 of file AliYAMLConfiguration.cxx.

Referenced by AliAnalysisTaskEmcalEmbeddingHelper::AutoConfigurePtHardBins(), and WriteConfiguration().

bool AliYAMLConfiguration::WriteConfiguration ( const std::string &  filename,
const std::string &  configurationName 
) const

Write a YAML configuration node to file.

Parameters
[in]configurationNameName of the YAML configuration node.
[in]filenameFilename to write the node to.
Returns
True if write was successful.

Definition at line 142 of file AliYAMLConfiguration.cxx.

void AliYAMLConfiguration::WriteConfigurationToFilePath ( const std::string &  localFilename,
std::string  filename 
) const
protected

Write a selected YAML configuration to file. Practically, it copies a local file to the desired location] to ensure seamless access to AliEn.

Parameters
[in]filenameFilename to which the configuration should be written.
[in]localFilenameFilename where the configuration was written locally.

Definition at line 212 of file AliYAMLConfiguration.cxx.

Referenced by WriteConfiguration().

template<typename T >
bool AliYAMLConfiguration::WriteProperty ( std::string  propertyName,
T property,
std::string  configurationName = "" 
)

Write a value to a YAML configuration. Note that the value is written to the YAML configuration, but then the YAML configuration needs to explicitly be written to file if the changes should be persistent.

Parameters
[in]propertyPathPath to the property in the YAML file.
[in]propertyProperty to be written.
[in]configurationNameName of the YAML configuration file to which the property should be written.
Returns
True if the write was successful.

Definition at line 498 of file AliYAMLConfiguration.h.

Referenced by AliAnalysisTaskEmcalEmbeddingHelper::AutoConfigurePtHardBins().

template<typename T >
void AliYAMLConfiguration::WriteValue ( YAML::Node &  node,
std::string  propertyName,
T property 
)
protected

Determine where the value should be written and write it to the appropriate YAML node.

Parameters
[in,out]nodeYAML node where the property should (eventually) be written.
[in]propertyNameName of the property to be written.
[in]propertyProperty to be written to the YAML node.

Definition at line 527 of file AliYAMLConfiguration.h.

Referenced by WriteProperty().

Member Data Documentation

std::vector<std::pair<std::string, YAML::Node> > AliYAMLConfiguration::fConfigurations
protected

! Contains all YAML configurations. The first element has the highest precedence.

Definition at line 163 of file AliYAMLConfiguration.h.

Referenced by AddConfiguration(), GetConfiguration(), GetProperty(), Initialize(), PrintConfiguration(), PrintConfigurations(), Reinitialize(), WriteConfiguration(), and WriteProperty().

std::vector<std::pair<std::string, std::string> > AliYAMLConfiguration::fConfigurationsStrings
protected

Contains all YAML configurations as strings so that they can be streamed.

Definition at line 165 of file AliYAMLConfiguration.h.

Referenced by Initialize(), and Reinitialize().

std::string AliYAMLConfiguration::fDelimiter
protected

Delimiter character to separate each level of the request.

Definition at line 169 of file AliYAMLConfiguration.h.

Referenced by GetProperty().

bool AliYAMLConfiguration::fInitialized
protected

True if the configurations have been initialized.

Definition at line 167 of file AliYAMLConfiguration.h.

Referenced by Initialize(), and Reinitialize().

std::string AliYAMLConfiguration::fPrefixString
protected

Contains the prefix of any names base node names which should be removed.

Definition at line 168 of file AliYAMLConfiguration.h.

Referenced by GetProperty().


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