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 "JLang/Jpp.hh"
#include "JLang/JAbstractIO.hh"
#include "JLang/JException.hh"
#include "JLang/JSharedPointer.hh"
#include "JLang/JAbstractObjectStatus.hh"
#include "JLang/JComparable.hh"
#include "JLang/JComparisonAvailable.hh"
#include "JLang/JBool.hh"
#include "JLang/JResolve.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
 */
namespace JPARSER {}
namespace JPP { using namespace JPARSER; }

class TString;   //<! Forward declaration of ROOT class

namespace JPARSER {

  using JLANG::JStreamInput;
  using JLANG::JStreamOutput;
  using JLANG::JParserException;
  using JLANG::JSharedPointer;
  using JLANG::JAbstractObjectStatus;
  using JLANG::JComparable;
  using JLANG::JComparisonAvailable;
  using JLANG::JBool;

  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


  /**
   * 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 handle optional I/O.
   */
  template<class T>
  class JOption {
  public:
    /**
     * Default constructor.
     */
    JOption() :
      __status(false),
      __value()
    {}


    /**
     * Constructor.
     */
    JOption(const T& value) :
      __status(false),
      __value(value)
    {}


    /**
     * Get status.
     *
     * \return               status
     */
    bool getStatus() const
    {
      return __status;
    }
    

    /**
     * Type conversion operator.
     *
     * \return               object
     */
    operator const T&() const
    {
      return __value;
    }


    /** 
     * Assignment to a value.
     *
     * \param  value         value
     * \return               this object
     */
    const JOption<T>& operator=(const T& value)
    {
      __status = true;
      __value  = value;
        
      return *this;
    }


    /**
     * Get clone of this object.
     *
     * \return               pointer to newly created object if status is okay; else NULL
     */
    T* clone() const
    {
      if (__status)
        return new T(__value);
      else
        return NULL;
    }


    /**
     * Read option from input.
     *
     * \param  in            input stream
     * \param  object        option
     * \return               input stream
     */
    friend inline std::istream& operator>>(std::istream& in, JOption& object)
    {
      object.__status = true;

      if (!(in >> object.__value)) {
        in.clear();
      }

      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 JOption& object)
    {
      if (object.__status) {
        out << object.__value;
      }

      return out;
    }

  protected:
    bool __status;
    T    __value;
  };


  /**
   * Auxiliary class to handle multiple boolean-like I/O.
   */
  class JCounter :
    public JAbstractObjectStatus,
    public JComparable<JCounter, int>
  {
  public:
    /**
     * Default constructor.
     */
    JCounter() :
      counter(0)
    {}


    /**
     * Get status of this counter.
     *
     * \return               true if counter not zero; else false
     */
    virtual bool getStatus() const
    {
      return (this->counter != 0);
    }
    
  
    /**
     * Compare value.
     *
     * \param  value         value
     * \return               true if this counter is less than given value; else false
     */
    inline bool less(const JCounter& value) const
    {
      return this->counter < value.counter;
    }
    
  
    /**
     * Compare value.
     *
     * \param  value         value
     * \return               true if this counter is less than given value; else false
     */
    inline bool less(const int value) const
    {
      return this->counter < value;
    }


    /**
     * Compare value.
     *
     * \param  value         value
     * \return               true if this counter is more than given value; else false
     */
    inline bool more(const int value) const
    {
      return this->counter > value;
    }


    /**
     * Get counter.
     *
     * \return               counter
     */
    int getCounter() const
    {
      return counter;
    }


    /** 
     * Set value.
     *
     * Note that no assignment actually takes place but the internal counter is set to one.
     *
     * \param  value         value
     * \return               this object
     */
    const JCounter& operator=(const bool value)
    {
      counter = 1;
        
      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 
     * \return             output stream
     */
    virtual void print(std::ostream& out) const
    {
      out << "<" << getName() << ">"; 

      if (getStatus() && !getShortprint(out)) {

        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 
    {
      return getInitialisationStatus(); 
    }


    /**
     * Get initialisation status of parameter.
     *
     * \return             status
     */
    virtual bool getInitialisationStatus() const 
    {
      return is_initialised;
    }


    /**
     * Set initialisation status of parameter.
     *
     * \param  value       initialisation status
     */
    virtual void setInitialiationStatus(const bool value) 
    {
      is_initialised = value;
    }

 
    /**
     * Stream input.
     *
     * \param  in          input stream
     * \return             input stream
     */
    virtual std::istream& read(std::istream& in) 
    {
      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 
    { 
      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;
  }


  /**
   * Auxiliary method for reading if TString does not exist.
   *
   * \param  in          input stream
   * \param  object      object
   * \param              option
   * \return             input stream
   */
  template<template<class, class> class JContainer_t, class JAllocator_t>
  inline std::istream& read(std::istream& in, JContainer_t<TString, JAllocator_t>& object, const JBool<false>& option) 
  {
    THROW(JParserException, "JParser: invalid data type TString (include TString.h before JParser.hh)");
  }


  /**
   * Auxiliary method for reading if TString exists.
   *
   * \param  in          input stream
   * \param  object      object
   * \param              option
   * \return             input stream
   */
  template<template<class, class> class JContainer_t, class JAllocator_t>
  inline std::istream& read(std::istream& in, JContainer_t<TString, JAllocator_t>& object, const JBool<true>& option) 
  {
    for (std::string buffer; in >> buffer; ) {
      object.push_back(TString(buffer.c_str()));
    }

    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) 
  {
    using namespace JPP;

    JPARSER::read(in, object, JBool<JResolve<TString>::value>());

    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 
    {
      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
     * \return             output stream
     */
    virtual void print(std::ostream& out) const
    {
      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) 
    {
      this->object = true;
      
      return in;
    }


    /**
     * Stream output.
     *
     * \param  out         output stream
     * \return             output stream
     */
    virtual std::ostream& write(std::ostream& out) const 
    { 
      return out << object;
    }


    /**
     * Status of object.
     *
     * \return             true
     */
    virtual bool getStatus() const 
    {
      return true;
    }


    /**
     * Get initialisation status of parameter.
     *
     * \return             true
     */
    virtual bool getInitialisationStatus() const 
    {
      return true;
    }


    /**
     * Set initialisation status of parameter.
     * This implementation doesn't do anything.
     *
     * \param  value       initialisation status
     */
    virtual void setInitialiationStatus(const bool value) 
    {}

    
    /**
     * Read counter.
     *
     * \return             true if at least one character to be read; else false
     */
    virtual bool gcount() const 
    {
      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) 
    {
      return in >> object;
    }


    /**
     * Stream output.
     *
     * \param  out         output stream
     * \return             output stream
     */
    virtual std::ostream& write(std::ostream& out) const 
    { 
      return out << object;
    }


    /**
     * Status of object.
     *
     * \return             true
     */
    virtual bool getStatus() const 
    {
      return true;
    }


    /**
     * Get initialisation status of parameter.
     *
     * \return             true
     */
    virtual bool getInitialisationStatus() const 
    {
      return true;
    }


    /**
     * Set initialisation status of parameter.
     * This implementation doesn't do anything.
     *
     * \param  value       initialisation status
     */
    virtual void setInitialiationStatus(const bool value) 
    {}

    
    /**
     * Read counter.
     *
     * \return             true if at least one character to be read; else false
     */
    virtual bool gcount() const 
    {
      return false;
    }


  private:
    JCounter& object;
  };


  /**
   * Auxiliary class to handle pointer to JPARSER::JParserElementInterface.
   */
  class JParserElement :
    public JSharedPointer<JParserElementInterface>
  {
  public:

    typedef JSharedPointer<JParserElementInterface>  JSharedPointer_t;

    
    /**
     * Default constructor.
     */
    JParserElement() :
      JSharedPointer_t()
    {}
    

    /**
     * Copy constructor.
     *
     * \param  value       reference to JParserElement
     */
    JParserElement(const JParserElement& value) :
      JSharedPointer_t(static_cast<const JSharedPointer_t&>(value))
    {}

    
    /**
     * Assignment operator.
     *
     * \param  value       reference to JParserElement
     * \return             this JParserElement
     */
    JParserElement& operator=(JParserElement& value)
    {
      JSharedPointer_t::operator=(static_cast<JSharedPointer_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;
    }


    /**
     * 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
     * \return             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.
   */
  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;
    }


    /**
     * Print the possible command line options.
     *
     * \param  out         output stream
     * \return             output stream
     */
    void print(std::ostream& out) const
    {
      using namespace std;

      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;
      }
    }


    /**
     * 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(cerr, SHORT_PRINT);

                if (is.peek() != EOF) {

                  if (is.get() == PRINT_OPTION) {

                    setPrintOption(cerr, LONG_PRINT);
              
                  } else {

                    THROW(JParserException, "invalid option at <" << is.str() << ">");
                  }
                }

                print(cerr);

                exit(NORMAL_EXIT_CODE);

              } else if (is.peek() == REVISION_OPTION) {        // revision

                cerr << "version:   " << getGITVersion() << endl;
                cerr << "commit:    " << getGITCommit()  << endl;
                cerr << "date:      " << getGITDate()    << endl;
                cerr << "namespace: " << getNamespace()  << endl;
                
                exit(NORMAL_EXIT_CODE);

              } else if (is.peek() == END_OF_OPTIONS) {         // end of options

                is.get();

                if (is.peek() != EOF) {

                  c = is.get();
                  
                  if        (c == PRINT_OPTION) {
                    
                    setPrintOption(cerr, MEDIUM_PRINT);
                    
                    print(cerr);

                  } 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, "option: " << START_OF_OPTION << p->first << " <" << p->second->getName() << ">" << " has no value");
        }

        if (!p->second->getStatus()) {
          THROW(JParserException, "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
   */
  inline JParserTemplateElement<bool> getOption(bool& object, const std::string& name, const std::string& help = "")
  {
    return JParserTemplateElement<bool>(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
   * \return             parser element
   */
  inline JParserTemplateElement<JCounter> getOption(JCounter& object, const std::string& name, const std::string& help = "")
  {
    return JParserTemplateElement<JCounter>(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
   * \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);
  }
}


/**
 * macro to convert parameter to JParserTemplateElement object
 */
#define make_field(A, ...)   JPARSER::getOption(A, #A, ##__VA_ARGS__)


/**
 * macro to convert parameter to JParserTemplateElement object
 */
#define gmake_option(A, ...) JPARSER::getOption(A, #A, ##__VA_ARGS__)


using JPARSER::JParser;
using JPARSER::JOption;
using JPARSER::JCounter;
using JPARSER::getOption;
using JPARSER::JArgs;

#endif