JParser.hh

Go to the documentation of this file.

#ifndef __JEEP__JPARSER__
#define __JEEP__JPARSER__
 
#include <sys/types.h>
#include <unistd.h>
#include <stdio.h>
#include <string>
#include <iostream>
#include <sstream>
#include <fstream>
#include <vector>
#include <map>
#include <ctype.h>
#include <type_traits>
#include <functional>
#include <memory>
 
#include "JLang/Jpp.hh"
#include "JLang/JAbstractIO.hh"
#include "JLang/JException.hh"
#include "JLang/JAbstractObjectStatus.hh"
#include "JLang/JComparable.hh"
#include "JLang/JComparisonAvailable.hh"
#include "JLang/JResolve.hh"
#include "JLang/JLangToolkit.hh"
#include "JLang/JManip.hh"
 
#include "Jeep/JStreamToolkit.hh"
#include "Jeep/JeepToolkit.hh"
#include "Jeep/JArgs.hh"
#include "Jeep/JMessage.hh"
#include "Jeep/JPrint.hh"
 
 
/**
 * \file
 * Utility class to parse command line options.
 * \author mdejong
 */
 
class TString;   //<! Forward declaration of ROOT class
 
/**
 * Local namespace for command line parser.
 */
namespace JPARSER {
 
  using JLANG::JStreamInput;
  using JLANG::JStreamOutput;
  using JLANG::JParserException;
  using JLANG::JAbstractObjectStatus;
  using JLANG::JComparable;
  using JLANG::JComparisonAvailable;
 
  using JEEP::readObject;
  using JEEP::writeObject;
  using JEEP::writeArray;
  using JEEP::getFilename;
  using JEEP::JArgs;
  using JEEP::JMessage;
 
 
  /**
   * Empty structure for specification of parser element that is initialised (i.e.\ does not require input).
   */
  struct initialised {};
 
 
  /**
   * Empty structure for specification of parser element that is not initialised (i.e.\ does require input).
   */
  struct not_initialised {};
 
 
  /**
   * Parser options.
   */
  static char START_OF_OPTION   = '-';           //!< start of an  option
  static char END_OF_OPTIONS    = '-';           //!< end   of all options
  static char HELP_OPTION       = 'h';           //!< help     option
  static char REVISION_OPTION   = 'v';           //!< revision option
  static char PRINT_OPTION      = '!';           //!< print    option
  static char PID_OPTION        = 'P';           //!< print PID to file
  static int  NORMAL_EXIT_CODE  =  0;            //!< exit code of normal end
  static int  WIDTH             =  12;           //!< format specifier
 
 
  /**
   * Check for stream state.
   *
   * Note that end-of-file is not defined as an error so to normally process e.g.\ std::string and std::vector.
   *
   * \param  in            input stream
   * \return               true if failure; else false
   */
  inline bool fail(std::istream& in)
  {
    return in.bad() || (in.fail() && !in.eof());
  }
  
 
  /**
   * Auxiliary class to assign a custom value following the reading of a specific textual value.
   */
  template<class T, bool is_fundamental = std::is_fundamental<T>::value>
  class JProxy;
 
 
  /**
   * Template specialisation of JProxy for fundamental data type.
   */
  template<class T>
  class JProxy<T, true>
  {
  public:
    /**
     * Constructor.
     *
     * \param  option        textual value
     * \param  value         custom  value
     */
    JProxy(const std::string& option, const T& value) :
      __value (),
      __option(option),
      __custom(value)
    {}
     
 
    /**
     * Constructor.
     *
     * \param  value         actual value
     */
    JProxy(const T& value) :
      __value (value),
      __option(),
      __custom()
    {}
    
 
    /**
     * Get actual value.
     *
     * \return               value
     */
    const T& getValue() const
    {
      return __value;
    }
     
 
    /**
     * Get option.
     *
     * \return               option
     */
    const std::string& getOption() const
    {
      return __option;
    }
     
 
    /**
     * Get custom value.
     *
     * \return               value
     */
    const T& getCustom() const
    {
      return __custom;
    }
 
 
    /**
     * Type conversion operator.
     *
     * \return               object
     */
    operator const T&() const
    {
      return __value;
    }
 
 
    /**
     * Assignment operator.
     *
     * Note that only the actual value is assigned.
     *
     * \param  object        object
     * \return               this object
     */
    JProxy& operator=(const JProxy& object)
    {
      __value  = object.__value;
 
      return *this;
    }
 
 
    /** 
     * Assignment to a value.
     *
     * \param  value         value
     * \return               this object
     */
    JProxy& operator=(const T& value)
    {
      __value  = value;
        
      return *this;
    }
 
 
    /**
     * Read option from input.
     *
     * \param  in            input stream
     * \param  object        option
     * \return               input stream
     */
    friend inline std::istream& operator>>(std::istream& in, JProxy& object)
    {
      using namespace std;
      
      string buffer;
 
      if (getline(in, buffer)) {
 
        if (buffer == object.__option) {
 
          object.__value = object.__custom;
 
        } else {
 
          istringstream is(buffer);
 
          is >> object.__value;
 
          in.setstate(is.rdstate());
        }
      }
 
      return in;
    }
 
 
    /**
     * Write options to output.
     *
     * \param  out           output stream
     * \param  object        option
     * \return               output stream
     */
    friend inline std::ostream& operator<<(std::ostream& out, const JProxy& object)
    {
      return out << object.__value;
    }
 
  protected:
    T           __value;
    std::string __option;
    T           __custom;
  };
 
 
  /**
   * Template specialisation of JProxy for non-fundamental data type.
   */
  template<class T>
  class JProxy<T, false> :
    public T
  {
  public:
    /**
     * Constructor.
     *
     * \param  option        textual value
     * \param  value         custom  value
     */
    JProxy(const std::string& option, const T& value) :
      T(),
      __option(option),
      __custom(value)
    {}
     
 
    /**
     * Constructor.
     *
     * \param  value         actual value
     */
    JProxy(const T& value) :
      T(value),
      __option(),
      __custom()
    {}
 
 
    /**
     * Get actual value.
     *
     * \return               value
     */
    const T& getValue() const
    {
      return static_cast<const T&>(*this);
    }
     
 
    /**
     * Get option.
     *
     * \return               option
     */
    const std::string& getOption() const
    {
      return __option;
    }
     
 
    /**
     * Get custom value.
     *
     * \return               value
     */
    const T& getCustom() const
    {
      return __custom;
    }
 
 
    /**
     * Assignment operator.
     *
     * Note that only the actual value is assigned.
     *
     * \param  object        object
     * \return               this object
     */
    JProxy& operator=(const JProxy& object)
    {
      static_cast<T&>(*this)  = static_cast<const T&>(object);
 
      return *this;
    }
 
 
    /** 
     * Assignment to a value.
     *
     * \param  value         value
     * \return               this object
     */
    JProxy& operator=(const T& value)
    {
      static_cast<T&>(*this)  = value;
        
      return *this;
    }
 
 
    /**
     * Read option from input.
     *
     * \param  in            input stream
     * \param  object        option
     * \return               input stream
     */
    friend inline std::istream& operator>>(std::istream& in, JProxy& object)
    {
      using namespace std;
      
      string buffer;
 
      if (getline(in, buffer)) {
 
        if (buffer == object.__option) {
 
          static_cast<T&>(object) = object.__custom;
 
        } else {
 
          istringstream is(buffer);
 
          is >> static_cast<T&>(object);
 
          in.setstate(is.rdstate());
        }
      }
 
      return in;
    }
 
 
    /**
     * Write options to output.
     *
     * \param  out           output stream
     * \param  object        option
     * \return               output stream
     */
    friend inline std::ostream& operator<<(std::ostream& out, const JProxy& object)
    {
      return out << static_cast<const T&>(object);
    }
 
  protected:
    std::string __option;
    T           __custom;
  };
 
 
  /**
   * Auxiliary class to handle multiple boolean-like I/O.
   */
  struct JCounter {
    /**
     * Default constructor.
     */
    JCounter() :
      counter(0)
    {}
 
 
    /**
     * Get counter.
     *
     * \return               counter
     */
    int getCounter() const
    {
      return counter;
    }
 
 
    /**
     * Type conversion operator.
     *
     * \return               counter
     */
    operator int() const
    {
      return counter;
    }
 
 
    /** 
     * Set value.
     *
     * \param  value         value
     * \return               this object
     */
    const JCounter& operator=(const bool value)
    {
      counter = (value ? 1 : 0);
        
      return *this;
    }
 
 
    /**
     * Read option from input.
     *
     * Note that no value actually is read, only the internal counter is incremented. 
     *
     * \param  in            input stream
     * \param  object        option
     * \return               input stream
     */
    friend inline std::istream& operator>>(std::istream& in, JCounter& object)
    {
      ++object.counter;
 
      return in;
    }
 
 
    /**
     * Write options to output.
     *
     * \param  out           output stream
     * \param  object        option
     * \return               output stream
     */
    friend inline std::ostream& operator<<(std::ostream& out, const JCounter& object)
    {
      out << object.counter;
 
      return out;
    }
 
  protected:
    int counter;
  };
 
 
  /**
   * Interface for I/O of parser element.
   */
  class JParserElementInterface :
    public JStreamInput,
    public JStreamOutput
  {
  protected:
    /**
     * Constructor.
     *
     * \param  name        name of object
     * \param  help        help of object
     */
    JParserElementInterface(const std::string& name = "arg",
                            const std::string& help = "") :
      __name(name),
      __help(help)
    {}
 
 
  public:
    /**
     * Get name of parameter.
     *
     * \return             name
     */
    const std::string& getName() const
    { 
      return __name; 
    }
    
 
    /**
     * Get help of parameter.
     *
     * \return             help
     */
    const std::string& getHelp() const
    { 
      return __help; 
    }
 
    
    /**
     * Get status of parameter.
     *
     * \return             status
     */
    virtual bool getStatus() const = 0;
 
 
    /**
     * Get initialisation status of parameter.
     *
     * \return             status
     */
    virtual bool getInitialisationStatus() const = 0;
 
 
    /**
     * Set initialisation status of parameter.
     *
     * \param  value       initialisation status
     */
    virtual void setInitialiationStatus(const bool value) = 0;
 
 
    /**
     * Print.
     *
     * \param  out         output stream 
     */
    virtual void print(std::ostream& out) const 
    {
      using namespace std;
 
      out << "<" << getName() << ">"; 
 
      if (getStatus() && !getShortprint(out)) {
 
        int width = WIDTH - getName().length();
 
        if (width > 0) {
          out << setw(width) << " ";
        }
 
        out << " = ";
          
        write(out);
      }
 
      if (getLongprint(out) && getHelp() != "") {
        out << " \"" << getHelp() << "\""; 
      }
    }
 
    
    /**
     * Read counter.
     *
     * \return             true if at least one character to be read; else false
     */
    virtual bool gcount() const 
    {
      return true;
    }
 
 
  protected:
    std::string __name;
    std::string __help;
  };
 
 
  /**
   * Template class holder for I/O of parser element.
   * This class implements the JPARSER::JParserElementInterface interface.
   */
  template<class JType_t, bool has_eq = JComparisonAvailable<JType_t>::has_eq>
  class JParserTemplateElement;
  
 
  /**
   * Auxiliary class to assign the remainder of a sequence of Comma Separated Values.
   */
  template<class JType_t>
  class JCSV {
  public:
    /**
     * Constructor.
     *
     * \param  element     parser element
     */
    JCSV(JParserTemplateElement<JType_t>& element) :
      __element(element)
    {}
    
 
    /**
     * Type conversion operator.
     *
     * \return             parser element
     */
    operator const JParserTemplateElement<JType_t>&() const
    { 
      return __element;
    }
    
 
    /**
     * Parsing of additional possible values.
     *
     * \param  value       possible value
     * \return             this JCSV object
     */
    JCSV& operator,(JType_t value)
    {
      __element.possibleValues.push_back(value);
      
      return *this;
    }
 
 
    /** 
     * Parsing of additional possible values.
     *
     * \param  values      possible values
     * \return             this object
     */
    template<template<class, class> class JContainer_t, class JAllocator_t>
    JCSV& operator,(const JContainer_t<JType_t, JAllocator_t>& values)
    {
      for (typename JContainer_t<JType_t, JAllocator_t>::const_iterator i = values.begin(); i != values.end(); ++i) {
        __element.possibleValues.push_back(*i);
      }
 
      return *this;
    }    
 
 
    /** 
     * Parsing of additional possible values.
     *
     * \param  values      possible values
     * \return             this object
     */
    template<template<class, class, class> class JContainer_t, class JCompare_t, class JAllocator_t>
    JCSV& operator,(const JContainer_t<JType_t, JCompare_t, JAllocator_t>& values)
    {
      for (typename JContainer_t<JType_t, JCompare_t, JAllocator_t>::const_iterator i = values.begin(); i != values.end(); ++i) {
        __element.possibleValues.push_back(*i);
      }
 
      return *this;
    }
 
  private:
    JParserTemplateElement<JType_t>& __element;
  };
 
 
  /**
   * Template specialisation of JPARSER::JParserTemplateElement for data type without equal operator <tt>==</tt>.
   */
  template<class JType_t>
  class JParserTemplateElement<JType_t, false> : 
    public JParserElementInterface 
  {
  public:
    /**
     * Constructor.
     *
     * \param  object      reference to object
     * \param  name        name of object
     * \param  help        help of object
     */
    JParserTemplateElement(JType_t&           object,
                           const std::string& name   = "arg",
                           const std::string& help   = "") :
      JParserElementInterface(name, help),
      object(object),
      is_initialised(false)
    {}
 
 
    /** 
     * Set initialised status to true.
     *
     * \param  value       initialised object
     * \return             this object
     */
    const JParserTemplateElement<JType_t, false>& operator=(const initialised& value)
    {
      setInitialiationStatus(true);
 
      return *this;
    }
 
 
    /** 
     * Set initialised status to false.
     *
     * \param  value       initialised object
     * \return             this object
     */
    const JParserTemplateElement<JType_t, false>& operator=(const not_initialised& value)
    {
      setInitialiationStatus(false);
 
      return *this;
    }
 
 
    /** 
     * Assignment to a default value.
     *
     * \param  value       default value
     * \return             this object
     */
    const JParserTemplateElement<JType_t, false>& operator=(const JType_t& value)
    {
      object = value;
 
      setInitialiationStatus(true);
        
      return *this;
    }
 
 
    /**
     * Get status of object.
     *
     * \return             true if current value is ok, else false
     */
    virtual bool getStatus() const override 
    {
      return getInitialisationStatus(); 
    }
 
 
    /**
     * Get initialisation status of parameter.
     *
     * \return             status
     */
    virtual bool getInitialisationStatus() const override 
    {
      return is_initialised;
    }
 
 
    /**
     * Set initialisation status of parameter.
     *
     * \param  value       initialisation status
     */
    virtual void setInitialiationStatus(const bool value) override 
    {
      is_initialised = value;
    }
 
 
    /**
     * Stream input.
     *
     * \param  in          input stream
     * \return             input stream
     */
    virtual std::istream& read(std::istream& in) override 
    {
      if (in.peek() == EOF) {
        THROW(JParserException, "JParser: error no data for parameter " << getName());
      }
 
      readObject(in, object);
 
      if (fail(in)) {
        THROW(JParserException, "JParser: error reading parameter " << getName());
      }
 
      while (isspace(in.peek())) {
        in.get();
      }
 
      if (in.peek() != EOF) {
        THROW(JParserException, "JParser: pending data after reading parameter " << getName());
      }
 
      setInitialiationStatus(true);
 
      return in;
    }
 
 
    /**
     * Stream output.
     *
     * \param  out         output stream
     * \return             output stream
     */
    virtual std::ostream& write(std::ostream& out) const override 
    { 
      return writeObject(out, object);
    }
 
  protected:
    JType_t& object;
    bool     is_initialised;
  };
 
 
  /**
   * Template specialisation of JParserTemplateElement<std::string>::read to read complete line from stream input.
   *
   * \param  in          input stream
   * \return             input stream
   */
  template<>
  inline std::istream& JParserTemplateElement<std::string, false>::read(std::istream& in) 
  {
    std::getline(in, object);
    
    if (fail(in)) {
      THROW(JParserException, "JParser: error reading parameter " << getName());
    }
 
    if (in.peek() != EOF) {
      THROW(JParserException, "JParser: pending data after reading parameter " << getName());
    }
 
    setInitialiationStatus(true);
 
    return in;
  }
 
 
  /**
   * Template specialisation of JParserTemplateElement<std::string>::write to surround text with quotes.
   *
   * \param  out         output stream
   * \return             output stream
   */
  template<>
  inline std::ostream& JParserTemplateElement<std::string, false>::write(std::ostream& out) const
  {
    return writeObject(out, JLANG::double_quote(object));
  }
 
 
  /**
   * Auxiliary class for handling I/O of TString depending on its existence.\n
   * The result is identical to that of std::string.
   */
  template<bool option = JLANG::JResolve<TString>::value>
  struct TStringHelper;
 
  /**
   * Specialisation of TStringHelper if TString does not exist.
   */
  template<>
  struct TStringHelper<false>
  {
    /**
     * Read object from input stream.\n
     * This method thrown an error.
     *
     * \param  in          input stream
     * \param  object      object
     * \return             input stream
     */
    template<class T>
    static inline std::istream& read(std::istream& in, T& object)
    {
      THROW(JParserException, "JParser: invalid data type TString (include TString.h before JParser.hh)");
    }
 
    /**
     * Read std::vector of objects from input stream.\n
     * This method thrown an error.
     *
     * \param  in          input stream
     * \param  object      object
     * \return             input stream
     */
    template<class T>
    static inline std::istream& read(std::istream& in, std::vector<T>& object)
    {
      THROW(JParserException, "JParser: invalid data type TString (include TString.h before JParser.hh)");
    }
  };
 
  /**
   * Specialisation of TStringHelper if TString exists.
   */
  template<>
  struct TStringHelper<true>
  {
    /**
     * Read object from input stream.
     *
     * \param  in          input stream
     * \param  object      object
     * \return             input stream
     */
    template<class T>
    static inline std::istream& read(std::istream& in, T& object)
    {
      return object.ReadLine(in);
    }
 
    /**
     * Read std::vector of objects from input stream.
     *
     * \param  in          input stream
     * \param  object      object
     * \return             input stream
     */
    template<class T>
    static inline std::istream& read(std::istream& in, std::vector<T>& object)
    {
      for (std::string buffer; in >> buffer; ) {
        object.push_back(buffer.c_str());
      }
 
      return in;
    }
  };
 
 
  /**
   * Template specialisation of JParserTemplateElement<TString>::read to read complete line from stream input.
   *
   * \param  in          input stream
   * \return             input stream
   */
  template<>
  inline std::istream& JParserTemplateElement<TString, false>::read(std::istream& in)
  {
    TStringHelper<>::read(in, object);
 
    setInitialiationStatus(true);
 
    return in;
  }
 
 
  /**
   * Template specialisation of JParserTemplateElement< std::vector<TString> >::read to read tokens from stream input.
   *
   * \param  in          input stream
   * \return             input stream
   */
  template<>
  inline std::istream& JParserTemplateElement<std::vector<TString>, false>::read(std::istream& in) 
  {
    TStringHelper<>::read(in, object);
 
    setInitialiationStatus(true);
 
    return in;
  }
 
 
  /**
   * Template specialisation of JPARSER::JParserTemplateElement for data type with equal operator <tt>==</tt>.
   */
  template<class JType_t>
  class JParserTemplateElement<JType_t, true> : 
    public JParserTemplateElement<JType_t, false>
  {
  public:
 
    friend class JCSV<JType_t>;
 
    /**
     * Constructor.
     *
     * \param  object      reference to object
     * \param  name        name of object
     * \param  help        help of object
     */
    JParserTemplateElement(JType_t&           object,
                           const std::string& name   = "arg",
                           const std::string& help   = "") :
      JParserTemplateElement<JType_t, false>(object, name, help)
    {}
 
 
    /**
     * Constructor.
     *
     * \param  object      reference to object
     * \param  name        name of object
     * \param  __begin     begin of possible values
     * \param  __end       end   of possible values
     */
    template<class T>
    JParserTemplateElement(JType_t&           object,
                           const std::string& name,
                           T                  __begin,
                           T                  __end) : 
      JParserTemplateElement<JType_t, false>(object, name)
    {
      setPossibleValues(__begin, __end);
    }
    
 
    /**
     * Constructor.
     *
     * \param  object      reference to object
     * \param  name        name of object
     * \param  help        help of object
     * \param  __begin     begin of possible values
     * \param  __end       end   of possible values
     */
    template<class T>
    JParserTemplateElement(JType_t&           object,
                           const std::string& name,
                           const std::string& help,
                           T                  __begin,
                           T                  __end) : 
      JParserTemplateElement<JType_t, false>(object, name, help)
    {
      setPossibleValues(__begin, __end);
    }
 
 
    /** 
     * Set initialised status to true.
     *
     * \param  value       initialised object
     * \return             this object
     */
    const JParserTemplateElement<JType_t, true>& operator=(const initialised& value)
    {
      this->setInitialiationStatus(true);
 
      return *this;
    }
 
 
    /** 
     * Set initialised status to false.
     *
     * \param  value       initialised object
     * \return             this object
     */
    const JParserTemplateElement<JType_t, true>& operator=(const not_initialised& value)
    {
      this->setInitialiationStatus(false);
 
      return *this;
    }
 
 
    /** 
     * Assignment to a default value and possible other values.
     *
     * \param  value       default value
     * \return             comma separated values parser
     */
    JCSV<JType_t> operator=(const JType_t& value)
    {
      this->object = value;
 
      this->setInitialiationStatus(true);
 
      possibleValues.push_back(value);
        
      return JCSV<JType_t>(*this);
    }
 
 
    /** 
     * Assignment to a default value and possible other values.
     *
     * \param  values      default values
     * \return             this object
     */
    template<template<class, class> class JContainer_t, class JAllocator_t>
    JCSV<JType_t> operator=(const JContainer_t<JType_t, JAllocator_t>& values)
    {
      setPossibleValues(values.begin(), values.end());
 
      return JCSV<JType_t>(*this);
    }
 
 
    /** 
     * Assignment to a default value and possible other values.
     *
     * \param  values      default values
     * \return             this object
     */
    template<template<class, class, class> class JContainer_t, class JCompare_t, class JAllocator_t>
    JCSV<JType_t> operator=(const JContainer_t<JType_t, JCompare_t, JAllocator_t>& values)
    {
      setPossibleValues(values.begin(), values.end());
 
      return JCSV<JType_t>(*this);
    }
 
 
    /**
     * Get status of object.
     *
     * If more than one possible values are provided,
     * the current value should be equal to one of the possible values,
     * else a value should have been set by the user.
     *
     * \return             true if current value is ok, else false
     */
    virtual bool getStatus() const override 
    {
      if (possibleValues.size() > 1) {
 
        for (typename std::vector<JType_t>::const_iterator i = possibleValues.begin(); i != possibleValues.end(); ++i) {
          if (this->object == *i) {
            return true;
          }
        }
 
        return false;
 
      } else {
 
        return this->getInitialisationStatus(); 
      }
    }
 
    
    /**
     * Print.
     *
     * \param  out         output stream
     */
    virtual void print(std::ostream& out) const override 
    {
      JParserTemplateElement<JType_t, false>::print(out);
 
      if (possibleValues.size() > 1 && getLongprint(out)) {
        writeArray(out, " [", "]", ", ", possibleValues.begin(), possibleValues.end());
      }
    }
 
  protected:
    /**
     * Set possible values.
     *
     * \param  __begin     begin of possible values
     * \param  __end       end   of possible values
     */
    template<class T>
    void setPossibleValues(T __begin, T __end) 
    {
      if (__begin != __end) {
 
        this->object = *__begin;
 
        this->setInitialiationStatus(true);
 
        for (T i = __begin; i != __end; ++i) {
          possibleValues.push_back(*i);
        }
      }
    }
 
    std::vector<JType_t> possibleValues;
  };
  
 
  /**
   * Template specialisation of JPARSER::JParserTemplateElement for type <tt>bool</tt>.
   * The value is by default set to false and set to true in method read() without reading any data.
   * This makes it possible to parse mutiple options in one go (e.g.\ <tt>-abc</tt>).
   * This class implements the JPARSER::JParserElementInterface interface.
   */
  template<>
  class JParserTemplateElement<bool> : 
    public JParserElementInterface 
  {
  public:
    /**
     * Constructor.
     *
     * The constructor assigns the default value false to the referenced parameter.
     *
     * \param  object      reference to object
     * \param  name        name of object
     * \param  help        help of object
     */
    JParserTemplateElement(bool& object, const std::string& name = "arg", const std::string& help = "") : 
      JParserElementInterface(name, help),
      object(object)
    {
      this->object = false;
    }
 
 
    /**
     * Stream input.
     * This method sets the value to true, without reading any data.
     *
     * \param  in          input stream
     * \return             input stream
     */
    virtual std::istream& read(std::istream& in) override 
    {
      this->object = true;
      
      return in;
    }
 
 
    /**
     * Stream output.
     *
     * \param  out         output stream
     * \return             output stream
     */
    virtual std::ostream& write(std::ostream& out) const override 
    { 
      return out << object;
    }
 
 
    /**
     * Status of object.
     *
     * \return             true
     */
    virtual bool getStatus() const override 
    {
      return true;
    }
 
 
    /**
     * Get initialisation status of parameter.
     *
     * \return             true
     */
    virtual bool getInitialisationStatus() const override 
    {
      return true;
    }
 
 
    /**
     * Set initialisation status of parameter.
     * This implementation doesn't do anything.
     *
     * \param  value       initialisation status
     */
    virtual void setInitialiationStatus(const bool value) override 
    {}
 
    
    /**
     * Read counter.
     *
     * \return             true if at least one character to be read; else false
     */
    virtual bool gcount() const override 
    {
      return false;
    }
 
 
  private:
    bool& object;
  };
 
 
  /**
   * Template specialisation of JPARSER::JParserTemplateElement for type <tt>JCounter</tt>.
   * The value is by default set to zero and set incremented in method read() without reading any data.
   * This makes it possible to parse mutiple options in one go (e.g.\ <tt>-aaa</tt>).
   * This class implements the JPARSER::JParserElementInterface interface.
   */
  template<>
  class JParserTemplateElement<JCounter> : 
    public JParserElementInterface 
  {
  public:
    /**
     * Constructor.
     *
     * The constructor assigns the default value false to the referenced parameter.
     *
     * \param  object      reference to object
     * \param  name        name of object
     * \param  help        help of object
     */
    JParserTemplateElement(JCounter& object, const std::string& name, const std::string& help = "") : 
      JParserElementInterface(name, help),
      object(object)
    {
      this->object = JCounter();
    }
 
 
    /**
     * Stream input.
     * This method sets the value to true, without reading any data.
     *
     * \param  in          input stream
     * \return             input stream
     */
    virtual std::istream& read(std::istream& in) override 
    {
      return in >> object;
    }
 
 
    /**
     * Stream output.
     *
     * \param  out         output stream
     * \return             output stream
     */
    virtual std::ostream& write(std::ostream& out) const override 
    { 
      return out << object;
    }
 
 
    /**
     * Status of object.
     *
     * \return             true
     */
    virtual bool getStatus() const override 
    {
      return true;
    }
 
 
    /**
     * Get initialisation status of parameter.
     *
     * \return             true
     */
    virtual bool getInitialisationStatus() const override 
    {
      return true;
    }
 
 
    /**
     * Set initialisation status of parameter.
     * This implementation doesn't do anything.
     *
     * \param  value       initialisation status
     */
    virtual void setInitialiationStatus(const bool value) override 
    {}
 
    
    /**
     * Read counter.
     *
     * \return             true if at least one character to be read; else false
     */
    virtual bool gcount() const override 
    {
      return false;
    }
 
 
  private:
    JCounter& object;
  };
 
 
  /**
   * Auxiliary class to handle pointer to JPARSER::JParserElementInterface.
   */
  class JParserElement :
    public std::shared_ptr<JParserElementInterface>
  {
  public:
 
    typedef std::shared_ptr<JParserElementInterface>  shared_ptr_t;
 
    
    /**
     * Default constructor.
     */
    JParserElement() :
      shared_ptr_t()
    {}
    
 
    /**
     * Copy constructor.
     *
     * \param  value       reference to JParserElement
     */
    JParserElement(const JParserElement& value) :
      shared_ptr_t(static_cast<const shared_ptr_t&>(value))
    {}
 
    
    /**
     * Assignment operator.
     *
     * \param  value       reference to JParserElement
     * \return             this JParserElement
     */
    JParserElement& operator=(JParserElement& value)
    {
      shared_ptr_t::operator=(static_cast<shared_ptr_t&>(value));
 
      return *this;
    }
 
    
    /**
     * Assignment operator.
     *
     * \param  value       reference to unnamed data object
     * \return             corresponding new JParserTemplateElement object
     */
    template<class JType_t>
    JParserTemplateElement<JType_t>& operator=(JType_t& value)
    {
      JParserTemplateElement<JType_t>* __p = new JParserTemplateElement<JType_t>(value);
 
      reset(__p);
 
      return *__p;
    }
 
 
    /**
     * Assignment operator.
     *
     * \param  value       reference to JParserTemplateElement object
     * \return             corresponding new JParserTemplateElement object
     */
    template<class JType_t>
    JParserTemplateElement<JType_t>& operator=(const JParserTemplateElement<JType_t>& value)
    {
      JParserTemplateElement<JType_t>* __p = new JParserTemplateElement<JType_t>(value);
 
      reset(__p);
 
      return *__p;
    }
 
 
    /**
     * Assignment operator.
     *
     * \param  value       reference to a corresponding JCSV object
     * \return             corresponding new comma separated values parser
     */
    template<class JType_t>
    JCSV<JType_t> operator=(const JCSV<JType_t>& value)
    {
      JParserTemplateElement<JType_t>* __p = new JParserTemplateElement<JType_t>(value);
 
      reset(__p);
 
      return JCSV<JType_t>(*__p);
    }
 
 
    /** 
     * Set initialised status to true.
     *
     * \param  value       initialised object
     * \return             this object
     */
    const JParserElement& operator=(const initialised& value)
    {
      if (!is_valid())
        THROW(JParserException, "No parser object defined.");
      else
        (*this)->setInitialiationStatus(true);
 
      return *this;
    }
 
 
    /** 
     * Set initialised status to false.
     *
     * \param  value       initialised object
     * \return             this object
     */
    const JParserElement& operator=(const not_initialised& value)
    {
      (*this)->setInitialiationStatus(false);
 
      return *this;
    }
 
 
    /**
     * Check validity.
     *
     * \return             true if valid; else false
     */
    bool is_valid() const
    {
      return (bool) static_cast<const shared_ptr_t&>(*this);
    }
 
 
    /**
     * Stream input.
     *
     * \param  in          input stream
     * \param  value       parser element
     * \return             input stream
     */
    friend inline std::istream& operator>>(std::istream& in, JParserElement& value)
    {
      if (value.is_valid())
        return value->read(in);
      else
        return in;
    }
 
 
    /**
     * Stream output.
     *
     * \param  out         output stream
     * \param  value       parser element
     * \return             output stream
     */
    friend inline std::ostream& operator<<(std::ostream& out, const JParserElement& value)
    { 
      if (value.is_valid())
        return value->write(out);
      else
        return out;
    }
 
    
    /**
     * Print.
     *
     * \param  out         output stream
     */
    void print(std::ostream& out) const
    { 
      if (is_valid()) {
        return get()->print(out);
      }
    }
  };
 
 
  /**
   * Utility class to parse command line options.
   *
   * The mapping between a parameter (of any type) and a unique option 
   * has to be defined in the user's application, e.g. 
   * \code{.cpp}
 
   #include "Jeep/JParser.hh"
 
   int main(int argc, char**argv)
   {
   int    aap;
   bool   noot;
   bool   mies;
   
   try {
 
   JParser<> zap;
   
   zap['i'] = make_field(aap) = 123; // set default value
   zap['b'] = make_field(noot);      // default is false
   zap['B'] = make_field(mies);
   
   zap(argc, argv);
   }
   catch(const std::exception& error) {
   cerr << error.what() << endl;
   return 1;
   }
   }
   \endcode
   *
   * The behaviour of the parser is different for parameters of type <tt>bool</tt>. 
   * By default, its value is set to <tt>false</tt>; it is set to <tt>true</tt> 
   * when the corresponding option is parsed.
   * This implies that no data are read and that several options can be
   * parsed in sequence without repeating the '-' symbol.
   *
   *
   * The syntax for the command line is:
   *
   \verbatim
   program [-<option> <value> [-<option> <value>]]
   \endverbatim
   
   \verbatim
   program -h 
   \endverbatim
   * will print the usage specification including all existing options.
 
   \verbatim
   program --!
   \endverbatim
   * will terminate the parsing of options and print the actual setting of all options.
   *
   * After the command line has been parsed, it is checked whether 
   * each parameter has been assigned a value by default or at run time. 
   * If not, an exception is thrown.
   *
   * For a comparison between the parsing of command line options with JParser and boost,
   * see <a href="https://drive.google.com/file/d/1R62NPhYjc_R7FYTRu-tkgUEo4PGoJc_y/view?usp=sharing">internal note</a>
   * which is accessible for anyone with a %KM3NeT account.
   */
  template<class JKey_t = char>
  class JParser : 
    public std::map<JKey_t, JParserElement>,
    public JMessage< JParser<JKey_t> >
  {
  public:
 
    typedef JLANG::JParserException                             JParserException;
    typedef JKey_t                                              key_type;
    typedef typename std::map<key_type, JParserElement>         map_type;
 
    typedef typename map_type::iterator                         iterator;
    typedef typename map_type::const_iterator                   const_iterator;
 
    using JMessage< JParser<key_type> >::debug;
    
 
    /**
     * Default constructor.
     *
     * \param  debug             debug level
     */
    JParser(const int debug = 0) :
      help ()
    {
      this->debug = debug;
    }
 
 
    /**
     * Constructor.
     *
     * \param  message           message printed with option <tt>-h</tt>
     * \param  debug             debug level
     */
    JParser(const std::string& message,
            const int debug = 0) :
      help (message)
    {
      this->debug = debug;
    }
 
 
    /**
     * Join parser.
     *
     * \param  parser            parser
     * \return                   this parser
     */
    JParser& join(const JParser& parser)
    {
      this->insert(parser.begin(), parser.end());
 
      return *this;
    }
 
 
    /**
     * Print the possible command line options.
     *
     * \param  out         output stream
     */
    void print(std::ostream& out) const
    {
      using namespace std;
      using namespace JPP;
 
      if (help != "") {
        out << help << endl;
      }
 
      out << "usage: " << getFilename(pid) << endl;
 
      out << ' ' << START_OF_OPTION << HELP_OPTION     << ' '          << " \"help\""                                           << endl;
      out << ' ' << START_OF_OPTION << HELP_OPTION     << PRINT_OPTION << " \"help with print of default and possible values\"" << endl;
      out << ' ' << START_OF_OPTION << REVISION_OPTION << ' '          << " \"print revision\""                                 << endl;
      out << ' ' << START_OF_OPTION << END_OF_OPTIONS  << ' '          << " \"end of options; remainder will be discarded\""    << endl;
      out << ' ' << START_OF_OPTION << END_OF_OPTIONS  << PRINT_OPTION << " \"end of options with print of actual values\""     << endl;
 
      for (const_iterator i = this->begin(); i != this->end(); ++i) {
 
        out << ' ' << START_OF_OPTION << i->first << "  ";
 
        i->second.print(out);
 
        out << endl;
      }
 
      if (getURL() != "") {
        out << endl << "See also: " << getURL() << '#' << getFilename(pid) << endl;
      }
    }
 
 
    /**
     * Terminate.
     *
     * \param  status      exit status
     */
    virtual void terminate(const int status) 
    {
      exit(status);
    }
 
 
    /**
     * Parse the program's command line options.
     *
     * \param  argc        number of arguments
     * \param  argv        argument list
     * \return             argument list
     */
    JArgs operator()(const int argc, const char* const argv[])
    {
      return (*this)(JArgs(argc, argv));
    }
 
 
    /**
     * Parse the program's command line options.
     *
     * \param  args        argument list
     * \return             argument list
     */
    JArgs operator()(const JArgs& args)
    {
      using namespace std;
      using namespace JLANG;
      using namespace JEEP;
 
      pid = args.PID;
 
      istringstream is;
 
      // argument passing
 
      for (JArgs::const_iterator i = args.begin(); i != args.end(); ++i) {
 
        DEBUG("Processing option <" << *i << ">" << endl);
        
        is.clear();
        is.str(*i);
 
        for (int c; (c = is.get()) != EOF; ) {
 
          if (c == START_OF_OPTION) {
 
            if        (is.peek() == EOF) {                      // end-of-file
 
              THROW(JParserException, "stray " << START_OF_OPTION << " in <" << is.str() << ">  at " << JArgs("", i, args.end()));
 
            } else if (isspace(is.peek())) {                    // white space
 
              THROW(JParserException, "stray " << START_OF_OPTION << " in <" << is.str() << "> at " << JArgs("", i, args.end()));;
            }
 
            while (is.peek() != EOF) {                          // read option(s)
 
              if        (is.peek() == HELP_OPTION) {            // help
 
                is.get();
 
                setPrintOption(cout, SHORT_PRINT);
 
                if (is.peek() != EOF) {
 
                  if (is.get() == PRINT_OPTION) {
 
                    setPrintOption(cout, LONG_PRINT);
              
                  } else {
 
                    THROW(JParserException, "invalid option at <" << is.str() << ">");
                  }
                }
 
                print(cout);
 
                terminate(NORMAL_EXIT_CODE);
 
                return JArgs();
 
              } else if (is.peek() == REVISION_OPTION) {        // revision
 
                cout << "source:    " << getSource()     << endl;
                cout << "version:   " << getGITVersion() << endl;
                cout << "commit:    " << getGITCommit()  << endl;
                cout << "date:      " << getGITDate()    << endl;
                cout << "namespace: " << getNamespace()  << endl;
                
                terminate(NORMAL_EXIT_CODE);
 
                return JArgs();
 
              } else if (is.peek() == END_OF_OPTIONS) {         // end of options
 
                is.get();
 
                if (is.peek() != EOF) {
 
                  c = is.get();
                  
                  if        (c == PRINT_OPTION) {
                    
                    setPrintOption(cout, MEDIUM_PRINT);
                    
                    print(cout);
 
                  } else if (c == PID_OPTION) {
                    
                    if (is.peek() == EOF && i + 1 != args.end()) {
                      is.clear();
                      is.str(*++i);
                    }
 
                    string file_name;
 
                    getline(is, file_name);
                    
                    ofstream out(file_name.c_str());
 
                    out << getpid() << endl;
                
                    if (!out) {
                      THROW(JParserException, "invalid option at <" << is.str()  << ">");
                    }
 
                    out.close();
 
                  } else {                  
 
                    THROW(JParserException, "invalid option at <" << is.str()  << ">");
                  }
                }
              
                check_status();
 
                return JArgs(pid, ++i, args.end());
 
              } else {
                
                key_type option;
    
                is >> option;
 
                iterator p = this->find(option);
          
                DEBUG("Processing option <" << option << "> " << (p != this->end()) << endl);
 
                if (p != this->end()) {
 
                  if (p->second->gcount()) {
 
                    if (is.peek() == EOF && i + 1 != args.end()) {
                      is.clear();
                      is.str(*++i);
                    }
                  }
 
                  try {
                    is >> p->second;
                  }
                  catch(const exception& error) {
                    THROW(JParserException, "read error " << error.what() << " at <" << is.str() << ">");
                  }
 
                  if (fail(is)) {
                    THROW(JParserException, "read error at <" << is.str() << ">");
                  }
 
                } else {
 
                  THROW(JParserException, "unknown option <" << is.str() << "> at " << JArgs("", i, args.end()));
                }
              }
            }
 
          } else {
 
            THROW(JParserException, "illegal character <" << (char) c << "> at " << JArgs("", i, args.end()));
          }
        }
      }
 
      check_status();
 
      return JArgs();
    }
 
 
    /**
     * Parse the program's command line options.\n
     * This method is maintained for backward compatibility and will be deprecated.
     *
     * \param  argc        number of arguments
     * \param  argv        argument list
     * \return             0
     */
    int read(const int argc, const char* const argv[])
    {
      (*this)(argc, argv);
 
      return 0;
    }
 
 
    /**
     * Parse the program's command line options.\n
     * This method is maintained for backward compatibility and will be deprecated.
     *
     * \param  args        argument list
     * \return             0
     */
    int read(const JArgs& args)
    {
      (*this)(args);
 
      return 0;
    }
 
 
    /**
     * Print the current parameter values.
     *
     * \param  out         output stream
     * \return             output stream
     */
    std::ostream& write(std::ostream& out) const
    {
      for (const_iterator i = this->begin(); i != this->end(); ++i) {
        out << i->second->getName() << '=' << i->second << std::endl;
      }
 
      return out;
    }
 
 
    /** 
     * Stream output.
     *
     * \param  out           output stream
     * \param  parser        parser
     * \return               output stream
     */
    friend inline std::ostream& operator<<(std::ostream& out, const JParser<key_type>& parser)
    { 
      return parser.write(out); 
    }
 
 
  protected:
    /**
     * Check if all required options have been set.\n
     * This method throws an exception in case of a non-compliance.
     */
    void check_status() const
    {
      for (const_iterator p = this->begin(); p != this->end(); ++p) {
 
        if (!p->second->getInitialisationStatus()) {
          THROW(JParserException, pid << " option: " << START_OF_OPTION << p->first << " <" << p->second->getName() << ">" << " has no value");
        }
 
        if (!p->second->getStatus()) {
          THROW(JParserException, pid << " option: " << START_OF_OPTION << p->first << " <" << p->second->getName() << ">" << " has illegal value");
        }
      }
    }
 
    std::string help;         //!< help message
    std::string pid;          //!< process name
  };
 
 
  /**
   * Auxiliary method for creation of template parser element object
   *
   * \param  object      object
   * \param  name        name of object
   * \param  help        help of object
   * \return             parser element
   */
  template<class JType_t>
  inline JParserTemplateElement<JType_t> getOption(JType_t& object, const std::string& name, const std::string& help = "")
  {
    return JParserTemplateElement<JType_t>(object, name, help);
  }
 
 
  /**
   * Auxiliary method for creation of template parser element object
   *
   * \param  object      object
   * \param  name        name of object
   * \param  help        help of object
   * \param  __begin     begin of possible values
   * \param  __end       end   of possible values
   * \return             parser element
   */
  template<class JType_t, class T>
  inline JParserTemplateElement<JType_t> getOption(JType_t&           object,
                                                   const std::string& name,
                                                   const std::string& help,
                                                   T                  __begin,
                                                   T                  __end)
  {
    return JParserTemplateElement<JType_t>(object, name, help, __begin, __end);
  }
 
 
  /**
   * Auxiliary method for creation of template parser element object
   *
   * \param  object      object
   * \param  name        name of object
   * \param  __begin     begin of possible values
   * \param  __end       end   of possible values
   * \return             parser element
   */
  template<class JType_t, class T>
  inline JParserTemplateElement<JType_t> getOption(JType_t&           object,
                                                   const std::string& name,
                                                   T                  __begin,
                                                   T                  __end)
  {
    return getOption(object, name, "", __begin, __end);
  }
}
 
 
/**
 * Make string for variadic macro.
 *
 * When called,
 *  - first argument should correspond to a dummy value;
 *  - second to the ##__VA_ARGS__ macro; and
 *  - third to the fall back value (e.g.\ "");
 *
 * \param  A           dummy value
 * \param  B           ##__VA_ARGS__ macro
 * \return             std::string
 */
#define VARGS_STRING(A, B, ...) std::invoke( [&]() { std::ostringstream out; out << B; return out.str(); } )
 
/**
 * macro to convert parameter to JParserTemplateElement object
 */
#define make_field(A, ...)   JPARSER::getOption(A, #A, VARGS_STRING("", ##__VA_ARGS__, ""))
 
 
/**
 * macro to convert parameter to JParserTemplateElement object
 */
#define make_option(A, ...)  JPARSER::getOption(A, #A, VARGS_STRING("", ##__VA_ARGS__, ""))
 
 
using JPARSER::JParser;
using JPARSER::JProxy;
using JPARSER::JCounter;
using JPARSER::getOption;
using JPARSER::JArgs;
 
#endif