AliYAMLConfiguration.h

Go to the documentation of this file.

#ifndef ALIYAMLCONFIGURATION_H
#define ALIYAMLCONFIGURATION_H

// CINT can't handle the yaml header because it has c++11!
#if !(defined(__CINT__) || defined(__MAKECINT__))
#include <yaml-cpp/yaml.h>
#endif

#include <string>
#include <vector>
#include <ostream>

#include <TObject.h>
#include <TString.h>

#include <AliLog.h>

#if !(defined(__CINT__) || defined(__MAKECINT__))
namespace YAML {
template<>
  struct convert<TString> {
    static Node encode(const TString & str) {
      return Node(str.Data());
    }
    static bool decode(const Node & node, TString & str) {
      if (!node.IsScalar()) {
        return false;
      }
      str = node.Scalar();
      return true;
    }
  };
}
#endif

template <typename It>
class Range
{
  It b, e;

 public:
  Range(It b, It e) : b(b), e(e) {}
  It begin() const { return b; }
  It end() const { return e; }
};

template <typename ORange, typename OIt = decltype(std::begin(std::declval<ORange>())),
     typename It = std::reverse_iterator<OIt>>
Range<It> reverse(ORange&& originalRange)
{
  return Range<It>(It(std::end(originalRange)), It(std::begin(originalRange)));
}

// operator<< has to be forward declared carefully to stay in the global namespace so that it works with CINT.
// For generally how to keep the operator in the global namespace, See: https://stackoverflow.com/a/38801633
namespace PWG { namespace Tools { class AliYAMLConfiguration; } }
std::ostream & operator<< (std::ostream &in, const PWG::Tools::AliYAMLConfiguration &myTask);

namespace PWG {
namespace Tools {

class AliYAMLConfiguration : public TObject {
 public:
  AliYAMLConfiguration(const std::string prefixString = "AliEmcalCorrection", const std::string delimiterCharacter = ":");
  virtual ~AliYAMLConfiguration() {}

  bool Initialize();
  bool Reinitialize();
  int AddEmptyConfiguration(const std::string & configurationName);
  int AddConfiguration(std::string configurationFilename, std::string configurationName = "");
  #if !(defined(__CINT__) || defined(__MAKECINT__))
  int AddConfiguration(const YAML::Node node, std::string configurationName = "");
  bool DoesConfigurationExist(const int i)                                              const { return i >= 0 && static_cast<const unsigned int>(i) < fConfigurations.size(); }
  bool DoesConfigurationExist(const std::string & name)                                 const { return DoesConfigurationExist(GetConfigurationIndexFromName(name, fConfigurations)); }
  const std::pair<std::string, YAML::Node> & GetConfiguration(const int i)              const { return fConfigurations.at(i); }
  const std::pair<std::string, YAML::Node> & GetConfiguration(const std::string & name) const { return GetConfiguration(GetConfigurationIndexFromName(name, fConfigurations)); }
  std::pair<std::string, YAML::Node> & GetConfiguration(const int i)                          { return fConfigurations.at(i); }
  std::pair<std::string, YAML::Node> & GetConfiguration(const std::string & name)             { return GetConfiguration(GetConfigurationIndexFromName(name, fConfigurations)); }
  std::string GetConfigurationNameFromIndex(const unsigned int i)                       const { return fConfigurations.at(i).first; }
  int GetConfigurationIndexFromName(const std::string & name)                           const { return GetConfigurationIndexFromName(name, fConfigurations); }
  bool RemoveConfiguration(const unsigned int i);
  bool RemoveConfiguration(const std::string & name)                                          { return RemoveConfiguration(GetConfigurationIndexFromName(name, fConfigurations)); }
  // Helper functions to retrieve property values
  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;
  // Retrieve property driver function.
  template<typename T>
  bool GetProperty(std::string propertyName, T & property, const bool requiredProperty = true) const;
  // Write property driver function.
  template<typename T>
  bool WriteProperty(std::string propertyName, T & property, std::string configurationName = "");
  #endif

  bool WriteConfiguration(const std::string & filename, const unsigned int i) const;
  bool WriteConfiguration(const std::string & filename, const std::string & configurationName) const;
  bool CompareConfigurations(const int config1, const int config2)                     const;
  bool CompareConfigurations(const int config1, const std::string & config2)           const { return CompareConfigurations(config1, GetConfigurationIndexFromName(config2, fConfigurations)); }
  bool CompareConfigurations(const std::string & config1, const std::string & config2) const { return CompareConfigurations(GetConfigurationIndexFromName(config1, fConfigurations), GetConfigurationIndexFromName(config2, fConfigurations)); }

  std::string toString(const int index = -1) const;
  std::ostream & Print(std::ostream &in, const int index = -1) const;
  std::ostream & Print(std::ostream &in, const std::string & configurationName) const;
  friend std::ostream & ::operator<< (std::ostream &in, const AliYAMLConfiguration &myTask);
  void Print(Option_t* /* opt */ = "") const;
 protected:

  // Utility functions
  // File utilities
  inline 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;
  #if !(defined(__CINT__) || defined(__MAKECINT__))
  // Printing
  void PrintConfiguration(std::ostream & stream, const std::pair<std::string, YAML::Node> & configPair) const;
  #endif
  // Configuration utilities
  template<typename T>
  unsigned int GetConfigurationIndexFromName(const std::string & name, const std::vector<std::pair<std::string, T>> & configurations) const;

  bool IsSharedValue(std::string & value) const;
  #if !(defined(__CINT__) || defined(__MAKECINT__))
  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);

  std::vector<std::pair<std::string, YAML::Node> > fConfigurations;         
  #endif
  std::vector<std::pair<std::string, std::string> > fConfigurationsStrings; 

  bool fInitialized;                          
  std::string fPrefixString;                  
  std::string fDelimiter;                     

  ClassDef(AliYAMLConfiguration, 1); // YAML Configuration
};

#if !(defined(__CINT__) || defined(__MAKECINT__))

template<typename T>
auto AliYAMLConfiguration::PrintRetrievedPropertyValueImpl(std::stringstream & tempMessage, const T & property, int) const -> decltype(tempMessage << property, void())
{
  tempMessage << " with value \"" << property << "\"";
}

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())
{
  tempMessage << " with value(s):";
  for (auto it = property.begin(); it != property.end(); it++) {
    tempMessage << "\n\t- " << *it;
  }
}

template<typename T>
void AliYAMLConfiguration::PrintRetrievedPropertyValueImpl(std::stringstream & tempMessage, const T & property, long) const
{
  // Cannot easily print these types, so just note that is the case!
  tempMessage << " with a value that cannot be trivially printed";
}

template<typename T>
void AliYAMLConfiguration::PrintRetrievedPropertyValue(std::stringstream & tempMessage, const T & property) const
{
  // By passing zero, it will first lookup the int, and then the long
  AliYAMLConfiguration::PrintRetrievedPropertyValueImpl(tempMessage, property, 0);
}

template<typename T>
bool AliYAMLConfiguration::GetPropertyFromNode(const YAML::Node & node, std::string propertyName, T & property) const
{
  if (node[propertyName])
  {
    property = node[propertyName].as<T>();
    return true;
  }
  return false;
}

template<typename T>
bool AliYAMLConfiguration::GetProperty(std::vector <std::string> propertyPath, const std::string & propertyName, T & property, const bool requiredProperty) const
{
  propertyPath.push_back(propertyName);
  return GetProperty(propertyPath, property, requiredProperty);
}

template<typename T>
bool AliYAMLConfiguration::GetProperty(const std::vector <std::string> propertyPath, T & property, const bool requiredProperty) const
{
  // Combine the requested names together
  std::string requestedName = "";
  for (auto & str : propertyPath)
  {
    if (requestedName.length() > 0) {
      requestedName += ":" + str;
    }
    else {
      requestedName = str;
    }
  }

  // Pass on the properly requested call
  return GetProperty(requestedName, property, requiredProperty);
}

template<typename T>
bool AliYAMLConfiguration::GetProperty(std::string propertyName, T & property, const bool requiredProperty) const
{
  // Remove the prefix string if in name
  std::size_t prefixStringLocation = propertyName.find(fPrefixString);
  if (prefixStringLocation != std::string::npos)
  {
    // Remove the prefix string
    propertyName.erase(prefixStringLocation, prefixStringLocation + fPrefixString.length());
  }

  bool setProperty = false;
  // Search in reverse so it is possible to override configuration values.
  for (auto configPair : reverse(fConfigurations))
  {
    if (setProperty == true) {
      AliDebugGeneralStream("AliYAMLConfiguration", 2) << "Property \"" << propertyName << "\" found!\n";
      break;
    }

    // IsNull checks is a node is empty. A node is empty if it is created.
    // IsDefined checks if the node that was requested was not actually created.
    if (configPair.second.IsNull() != true)
    {
      AliDebugGeneralStream("AliYAMLConfiguration", 2) << "Looking for parameter \"" << propertyName << "\" in \"" << configPair.first << "\" configuration\n";
      // NOTE: This may not exist, but that is entirely fine.
      YAML::Node sharedParameters = configPair.second["sharedParameters"];
      setProperty = GetProperty(configPair.second, sharedParameters, configPair.first, propertyName, property);
    }
  }

  if (setProperty != true && requiredProperty == true)
  {
    std::stringstream message;
    message << "Failed to retrieve required property \""
        << propertyName << "\" from available configurations!" << std::endl;
    AliFatalGeneral("AliYAMLConfiguration", message.str().c_str());
  }

  // Return whether the value was actually set
  return setProperty;
}

template<typename T>
bool AliYAMLConfiguration::GetProperty(YAML::Node & node, YAML::Node & sharedParametersNode, const std::string & configurationName, std::string propertyName, T & property) const
{
  // Used as a buffer for printing complicated messages
  std::stringstream tempMessage;

  bool returnValue = false;

  const std::string specializationDelimiter = "_";
  size_t delimiterPosition = 0;
  std::string tempPropertyName = propertyName;

  if ((delimiterPosition = tempPropertyName.find(fDelimiter)) != std::string::npos)
  {
    std::string nodeName = tempPropertyName.substr(0, delimiterPosition);
    tempPropertyName.erase(0, delimiterPosition + fDelimiter.length());

    // Attempt to use the node name
    if (node[nodeName].IsDefined() == true)
    {
      // Retrieve node and then recurse
      YAML::Node tempNode = node[nodeName];
      AliDebugGeneralStream("AliYAMLConfiguration", 2) << "Attempting to retrieving property \"" << tempPropertyName << "\" by going a node deeper with node \"" << nodeName << "\".\n";
      returnValue = GetProperty(tempNode, sharedParametersNode, configurationName, tempPropertyName, property);
    }

    // Check for the specialization if the nodeName is undefined.
    // Alternatively, if the value was not returned successfully, we should also check for the specialization
    //   such as inheritnace for input objects.
    if (node[nodeName].IsDefined() == false || returnValue == false)
    {
      // Check for specialization
      if ((delimiterPosition = nodeName.find(specializationDelimiter)) != std::string::npos)
      {
        std::string specializationNodeName = nodeName.substr(0, delimiterPosition);
        YAML::Node tempNode = node[specializationNodeName];
        AliDebugGeneralStream("AliYAMLConfiguration", 2) << "Attempting to retrieving property \"" << tempPropertyName << "\" by going a node deeper through dropping the specializtion and using node \"" << specializationNodeName << "\".\n";
        returnValue = GetProperty(tempNode, sharedParametersNode, configurationName, tempPropertyName, property);
      }
      else {
        returnValue = false;
      }
    }
  }
  else
  {
    // Check if node exists!
    if (node[propertyName])
    {
      // Handle shared parameters
      bool isShared = false;
      // Will contain the name of the property in the sharedParameters section that should be retrieved
      // if it is requested through the user configuration.
      std::string sharedValueName = "";
      // Necessary because it fails on vectors and other complex objects that are YAML sequences.
      if (std::is_arithmetic<T>::value || std::is_same<T, std::string>::value || std::is_same<T, bool>::value)
      {
        // Retrieve value as string to check for shared value
        sharedValueName = node[propertyName].as<std::string>();
        // Check for a shared value
        isShared = IsSharedValue(sharedValueName);
      }

      // Setup printable message
      tempMessage.str("");
      tempMessage << "property \""
            << propertyName
            << "\" using " << ( isShared ? "\"sharedParameters:" + sharedValueName + "\" in " : "" )
            << "values from the " << configurationName << " configuration";

      AliDebugGeneralStream("AliYAMLConfiguration", 2) << "Retrieveing " << tempMessage.str() << "\n";

      // Retrieve result
      bool retrievalResult = false;
      if (isShared == true) {
        // Retrieve from the shared parameter node directly.
        retrievalResult = GetPropertyFromNode(sharedParametersNode, sharedValueName, property);
      }
      else {
        retrievalResult = GetPropertyFromNode(node, propertyName, property);
      }

      // Inform about the result
      if (retrievalResult == true) {
        // Add the retrieved value to the message (only if trivially printable)
        AliYAMLConfiguration::PrintRetrievedPropertyValue(tempMessage, property);
        AliDebugGeneralStream("AliYAMLConfiguration", 2) << "Succeeded in retrieveing " << tempMessage.str() << "\n";
        returnValue = true;
      }
      else {
        returnValue = false;
      }
    }
  }

  return returnValue;
}

template<typename T>
bool AliYAMLConfiguration::WriteProperty(std::string propertyName, T & property, std::string configurationName)
{
  unsigned int configurationIndex = 0;
  if (configurationName != "")
  {
    configurationIndex = GetConfigurationIndexFromName(configurationName, fConfigurations);
  }

  if (fConfigurations.size() == 0) {
    AliErrorStream() << "No configurations available! Property will not be written!\n";
    return false;
  }

  std::pair<std::string, YAML::Node> & configPair = fConfigurations.at(configurationIndex);

  WriteValue(configPair.second, propertyName, property);
  AliDebugGeneralStream("AliYAMLConfiguration", 2) << "Final Node:\n" << configPair.second << "\n";

  return true;
}

template<typename T>
void AliYAMLConfiguration::WriteValue(YAML::Node & node, std::string propertyName, T & property)
{
  // Find the node name we are interested in
  // Derived from: https://stackoverflow.com/a/14266139
  const std::string delimiter = ":";
  size_t delimiterPosition = 0;
  std::string tempPropertyName = propertyName;

  if ((delimiterPosition = tempPropertyName.find(delimiter)) != std::string::npos)
  {
    std::string nodeName = tempPropertyName.substr(0, delimiterPosition);
    tempPropertyName.erase(0, delimiterPosition + delimiter.length());
    AliDebugGeneralStream("AliYAMLConfiguration", 2) << "nodeName: " << nodeName << "\n";
    AliDebugGeneralStream("AliYAMLConfiguration", 2) << "Node Before:\n" << node << "\n";
    if (node[nodeName].IsDefined()) {
      AliDebugGeneralStream("AliYAMLConfiguration", 2) << "Using existing node\n";
      YAML::Node tempNode = node[nodeName];
      WriteValue(tempNode, tempPropertyName, property);
    }
    else {
      AliDebugGeneralStream("AliYAMLConfiguration", 2) << "Creating new node\n";
      YAML::Node tempNode;
      node[nodeName] = tempNode;
      WriteValue(tempNode, tempPropertyName, property);
    }
    AliDebugGeneralStream("AliYAMLConfiguration", 2) << "Node After:\n" << node << "\n";
  }
  else {
    // We have finished the recursion. Now we need to save the actual property.
    node[propertyName] = property;
  }
}

#endif

template<typename T>
unsigned int AliYAMLConfiguration::GetConfigurationIndexFromName(const std::string & name, const std::vector<std::pair<std::string, T>> & configurations) const
{
  int index = -1;
  for (const auto & configPair : configurations)
  {
    if (configPair.first == name) {
      // Retrieve index
      // See: https://stackoverflow.com/a/10962459
      index = std::addressof(configPair) - std::addressof(configurations[0]);
      break;
    }
  }

  return index;
}

} // namespace Tools
} // namespace PWG

#endif /* ALIYAMLCONFIGURATION_H */