QwOptions.h

Go to the documentation of this file.

/*!
 * \file   QwOptions.h
 * \brief  An options class which parses command line, config file and environment
 *
 * \author Wouter Deconinck
 * \date   2009-12-01
 */
 
/*!
 * \file   QwOptions.h
 * \brief  Command-line options processing using Boost.Program_options
 */
 
#pragma once
 
// System headers
#include <iostream>
#include <string>
#include <vector>
 
// Boost headers
#include <boost/program_options.hpp>
namespace po = boost::program_options;
 
// ROOT headers
#include <TString.h>
 
// Qweak headers
#include "QwLog.h"
 
#define gQwOptions QwOptions::Instance()
 
// Helper functions for safe environment variable parsing
inline const char* getenv_safe (const char* name) {
 if (getenv(name))
   return getenv(name);
 else {
   QwError << "Environment variable " << name << " undefined!" << QwLog::endl;
   QwWarning << "Using current directory instead." << QwLog::endl;
   return ".";
 }
}
inline const std::string getenv_safe_string (const char* name) {
 return std::string(getenv_safe(name));
}
inline const TString getenv_safe_TString (const char* name) {
 return TString(getenv_safe(name));
}
 
 
// Starting with boost::program_options 1.35.0 there is support for the semantic
// implicit_value.  An explicit option value is optional, but if given, must be
// strictly adjacent to the option.
#define default_bool_value(b) default_value(b)->implicit_value(true)
 
 
/**
 *  \class QwOptions
 *  \ingroup QwAnalysis
 *  \brief Command-line and configuration file options processor
 *
 * QwOptions provides a unified interface for handling command-line arguments,
 * configuration files, and environment variables using Boost.Program_options.
 * It supports typed options with defaults, positional arguments, and
 * hierarchical configuration loading. The global gQwOptions singleton
 * is available throughout the framework.
 *
 * On instantiation of the global gQwOptions object the argc and argv are passed.
 * The filename is set to a default value, but on instantiation a check is done
 * for the option --config filename.  After this no parsing is done without the
 * user requesting a value.
 *
 * To use this class in your own programs, just include the header file.  This
 * will make the global object gQwOptions available.   Set the command line and
 * config file with the methods SetCommandLine() and SetConfigFile() in the main
 * routine.  In other classes you can add subsystem-specific config files with
 * the AddConfigFile() method.
 * \code
 * gQwOptions.SetCommandLine(argc, argv); // store command line arguments
 * gQwOptions.SetConfigFile("qwtracking.conf"); // set the default config file
 * gQwOptions.AddConfigFile("qweak-tracking.conf"); // add another config file
 * \endcode
 *
 * Define your own options by calling the AddOptions() method.  Look in the
 * documentation of boost::program_options for the allowed syntax if you need
 * more than just '--key value' pairs.  Positional arguments are supported
 * (untested), default values can and should preferably be given, and multiple
 * values can be put into a vector corresponding to a single key (untested).
 * \code
 * gQwOptions.AddOptions()("int,i", po::value<int>(), "integer-valued option");
 * gQwOptions.AddOptions()("bool,b", po::value<bool>(), "boolean-valued option");
 * gQwOptions.AddOptions()("float,f", po::value<float>(), "float-valued option");
 * gQwOptions.AddOptions()("string,s", po::value<string>(), "string-valued option");
 * gQwOptions.AddOptions()("range,r", po::value<string>(), "range-valued option");
 * gQwOptions.AddOptions()("def-int", po::value<int>()->default_value(1), "int-valued option, default of 1");
 * \endcode
 * For boolean-valued options you might want to use zero_tokens() to allow the
 * option to be specified as --bool instead of --bool yes.
 * \code
 * gQwOptions.AddOptions()("bool,b", po::value<bool>()->zero_tokens(), "boolean-valued option");
 * \endcode
 * Keep in mind, though, that this then ignores the value after the option completely,
 * and it will not allow you to unset settings in the default configuration file.
 * A better approach is to use the implicit_value(b) semantic that will still accept
 * the value after the option.  However, this was only introduced in boost 1.35.0.
 * To avoid the need to test for this, use the syntax default_bool_value(b), with b
 * the default value.  If the flag is specified, the option will be set to true
 * regardless of the specified default value.
 *
 * It is easiest if you define your options in a static function DefineOptions()
 * and then call that function in the QwOptionsTracking.h or QwOptionsParity.h
 * header files.  This ensures that only a single call to gQwOptions.DefineOptions()
 * will load all the options and provide the information on a --help call.
 *
 * To use the options, check first for the existence with HasValue(key), then
 * get their value using GetValue<type>(key).  Flags defined without type are
 * treated as 'existence-only' keys, so use HasValue(key) on them instead of
 * GetValue<bool>(key).  If you define an option as bool, you should still use
 * the regular GetValue<bool>(key) to retrieve the value.
 * \code
 * // Test for presence of the option before using its value
 * if (gQwOptions.HasValue("string")) string my_string = gQwOptions.GetValue<string>("string");
 * // Or use options with default values (preferable)
 * int my_int = gQwOptions.GetValue<int>("def-int");
 * \endcode
 *
 * To get the results of an integer range argument (strictly speaking a string
 * argument), you can use GetIntValuePair() which returns a pair<int,int>, or
 * the more specific GetIntValuePairFirst() and GetIntValuePairLast().
 * \code
 * std::pair<int,int> my_run_pair = gQwOptions.GetIntValuePair("run");
 * gQwOptions.GetIntValuePair("run").first == gQwOptions.GetIntValuePairFirst("run");
 * gQwOptions.GetIntValuePair("run").second == gQwOptions.GetIntValuePairLast("run");
 * \endcode
 *
 * The default allowed options are:
 * - --usage: print a help message
 * - --help, -h: print a help message
 * - --config, -c: configuration file to read
 */
class QwOptions {
 
  private:
    static QwOptions* fInstance;
 
    /// \brief Private default constructor
    QwOptions();
    /// \brief Private copy constructor, not implemented
    QwOptions(QwOptions const&);
    /// \brief Private assignment operator, not implemented
    QwOptions& operator=(QwOptions const&);
 
  public:
    /// \brief Get instance
    static QwOptions& Instance() {
      if (! fInstance) fInstance = new QwOptions();
      return *fInstance;
    }
 
    /// \brief Default destructor
    virtual ~QwOptions();
 
 
    /// \brief Add a default option
    po::options_description_easy_init AddDefaultOptions() {
      return AddOptions("Default options");
    };
    /// \brief Add an option to a named block or create new block
    po::options_description_easy_init
    AddOptions(const std::string& blockname = "Specialized options") {
      // Clear the parsed options
      Clear();
      // Note: Would like to solve this with find_if(b,e,bind()) but no access to block name
      // Search for the block name if it exists
      for (size_t i = 0; i < fOptionBlockName.size(); i++)
        if (blockname == fOptionBlockName.at(i))
          return fOptionBlock.at(i)->add_options();
      // Create new block if not existing yet
      fOptionBlock.push_back(new po::options_description(blockname));
      fOptionBlockName.push_back(blockname);
      return fOptionBlock.back()->add_options();
    };
 
 
    /// \brief Print usage information
    void Usage();
 
    /// \brief Print version string
    void Version();
 
    /// \brief Define the options
    static void DefineOptions(QwOptions& options);
 
    /// \brief Set the command line arguments
    void SetCommandLine(int argc, char* argv[], bool default_config_file = true);
 
    /// \brief Set a configuration file
    void SetConfigFile(const std::string& configfile);
 
    /// \brief Add a configuration file
    void AddConfigFile(const std::string& configfile);
 
    /// \brief Add some configuration files
    void AddConfigFile(std::vector<std::string> configfiles) {
      for (size_t i = 0; i < configfiles.size(); i++)
    AddConfigFile(configfiles.at(i));
    };
 
    /// \brief List the configuration files
    void ListConfigFiles() {
      QwMessage << "Config files:" << QwLog::endl;
      for (size_t i = 0; i < fConfigFiles.size(); i++)
        QwMessage << fConfigFiles.at(i) << QwLog::endl;
    };
 
 
    /// \brief Parse all sources of options
    void Parse(bool force = false) {
      if (! fParsed || force) {
        ParseCommandLine();
        ParseEnvironment();
        ParseConfigFile();
        fParsed = true;
      }
    };
 
 
    /// \brief Has this key been defined
    bool HasValue(const std::string& key) {
      if (fParsed == false) Parse();
      return (fVariablesMap.count(key) > 0);
    };
 
    /// \brief Get a templated value
    template < class T >
    T GetValue(const std::string& key) {
      if (fParsed == false) Parse();
      if (fVariablesMap.count(key)) {
        QwVerbose << "Option " << key << ": "
                  << fVariablesMap[key].as<T>() << QwLog::endl;
        return fVariablesMap[key].as<T>();
      } else {
        QwError << "Variable " << key << " unknown" << QwLog::endl;
        return {};
      }
    }
    /// \brief Get a list of templated values
    template < class T >
    std::vector < T > GetValueVector(const std::string& key) {
      std::vector<T> list;
      if (fParsed == false) Parse();
      if (fVariablesMap.count(key)) {
        list = fVariablesMap[key].as< std::vector<T> >();
      }
      return list;
    }
 
    /// \brief Get a pair of integer values
    std::pair<int,int> GetIntValuePair(const std::string& key);
 
    /// \brief Get the first of a pair of integer values
    int GetIntValuePairFirst(const std::string& key) {
      return GetIntValuePair(key).first;
    };
 
    /// \brief Get the last of a pair of integer values
    int GetIntValuePairLast(const std::string& key) {
      return GetIntValuePair(key).second;
    };
 
    /// \brief Get the number of command line arguments
    int GetArgc()    { return (int) fArgc; };
    /// \brief Get the vector of command line arguments
    char** GetArgv() { return (char**) fArgv; };
 
    /// \brief Clear the parsed variables
    void Clear() {
      fVariablesMap.clear();
      fParsed = false;
    };
 
  private:
 
    /// \brief Combine the various option description in one
    po::options_description* CombineOptions();
 
    /// \brief Parse the command line arguments
    void ParseCommandLine();
 
    /// \brief Parse the configuration file
    void ParseConfigFile();
 
    /// \brief Parse the environment variables
    void ParseEnvironment();
 
    /// \brief Configuration file
    std::vector<std::string> fConfigFiles;
 
    /** \brief Command line arguments
     *
     * Because argc and argv are only available in the main routine, we need
     * to store a copy of them for later parsing.  The copy is static to have
     * them available in local copies of the options object.
     */
    int fArgc;
    char** fArgv;
 
    // Vector with option blocks
    // Notes:
    // - boost::po cannot work with object array
    // - no access to the name of the block after creation
    std::vector<po::options_description*> fOptionBlock;
    std::vector<std::string> fOptionBlockName;
 
    // Options descriptions
    po::variables_map fVariablesMap;
 
    bool fParsed;
};