JPARSER::JParser< JKey_t > Class Template Reference

Utility class to parse command line options. More...

#include <JParser.hh>

Inheritance diagram for JPARSER::JParser< JKey_t >:

Public Types
typedef JLANG::JParserException	JParserException
typedef JKey_t	key_type
typedef std::map< key_type, JParserElement >	map_type
typedef map_type::iterator	iterator
typedef map_type::const_iterator	const_iterator

Public Member Functions
	JParser (const int debug=0)
	Default constructor. More...
	JParser (const std::string &message, const int debug=0)
	Constructor. More...
JParser &	join (const JParser &parser)
	Join parser. More...
void	print (std::ostream &out) const
	Print the possible command line options. More...
virtual void	terminate (const int status)
	Terminate. More...
JArgs	operator() (const int argc, const char *const argv[])
	Parse the program's command line options. More...
JArgs	operator() (const JArgs &args)
	Parse the program's command line options. More...
int	read (const int argc, const char *const argv[])
	Parse the program's command line options. More...
int	read (const JArgs &args)
	Parse the program's command line options. More...
std::ostream &	write (std::ostream &out) const
	Print the current parameter values. More...

Static Public Attributes
static int	debug = 0
	debug level (default is off). More...

Protected Member Functions
void	check_status () const
	Check if all required options have been set. More...

Protected Attributes
std::string	help
	help message More...
std::string	pid
	process name More...

Friends
std::ostream &	operator<< (std::ostream &out, const JParser< key_type > &parser)
	Stream output. More...

Detailed Description

template<class JKey_t = char>
class JPARSER::JParser< JKey_t >

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.

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

The behaviour of the parser is different for parameters of type bool. By default, its value is set to false; it is set to true 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:

program [-<option> <value> [-<option> <value>]]

program -h 

will print the usage specification including all existing options.

program --!

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 internal note which is accessible for anyone with a KM3NeT account.

Definition at line 1517 of file JParser.hh.

Member Typedef Documentation

template<class JKey_t = char>

typedef JLANG::JParserException JPARSER::JParser< JKey_t >::JParserException

Definition at line 1523 of file JParser.hh.

template<class JKey_t = char>

typedef JKey_t JPARSER::JParser< JKey_t >::key_type

Definition at line 1524 of file JParser.hh.

template<class JKey_t = char>

typedef std::map<key_type, JParserElement> JPARSER::JParser< JKey_t >::map_type

Definition at line 1525 of file JParser.hh.

template<class JKey_t = char>

typedef map_type::iterator JPARSER::JParser< JKey_t >::iterator

Definition at line 1527 of file JParser.hh.

template<class JKey_t = char>

typedef map_type::const_iterator JPARSER::JParser< JKey_t >::const_iterator

Definition at line 1528 of file JParser.hh.

Constructor & Destructor Documentation

template<class JKey_t = char>

JPARSER::JParser< JKey_t >::JParser ( const int  debug = 0 )

inline

Default constructor.

Parameters

debug

debug level

Definition at line 1538 of file JParser.hh.

                                 :
      help ()
    {
      this->debug = debug;
    }

template<class JKey_t = char>

JPARSER::JParser< JKey_t >::JParser ( const std::string &  message, const int  debug = 0  )

inline

Constructor.

Parameters

message	message printed with option -h
debug	debug level

Definition at line 1551 of file JParser.hh.

                                 :
      help (message)
    {
      this->debug = debug;
    }

Member Function Documentation

template<class JKey_t = char>

JParser& JPARSER::JParser< JKey_t >::join ( const JParser< JKey_t > &  parser )

inline

Join parser.

Parameters

parser

parser

Returns

this parser

Definition at line 1565 of file JParser.hh.

    {
      this->insert(parser.begin(), parser.end());

      return *this;
    }

template<class JKey_t = char>

void JPARSER::JParser< JKey_t >::print ( std::ostream &  out ) const

inline

Print the possible command line options.

Parameters

out	output stream

Returns

output stream

Definition at line 1579 of file JParser.hh.

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

template<class JKey_t = char>

virtual void JPARSER::JParser< JKey_t >::terminate ( const int  status )

inlinevirtual

Terminate.

Parameters

status

exit status

Definition at line 1616 of file JParser.hh.

    {
      exit(status);
    }

template<class JKey_t = char>

JArgs JPARSER::JParser< JKey_t >::operator() ( const int  argc, const char *const  argv[]  )

inline

Parse the program's command line options.

Parameters

argc	number of arguments
argv	argument list

Returns

argument list

Definition at line 1629 of file JParser.hh.

    {
      return (*this)(JArgs(argc, argv));
    }

template<class JKey_t = char>

JArgs JPARSER::JParser< JKey_t >::operator() ( const JArgs &  args )

inline

Parse the program's command line options.

Parameters

args	argument list

Returns

argument list

Definition at line 1641 of file JParser.hh.

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

template<class JKey_t = char>

int JPARSER::JParser< JKey_t >::read ( const int  argc, const char *const  argv[]  )

inline

Parse the program's command line options.

This method is maintained for backward compatibility and will be deprecated.

Parameters

argc	number of arguments
argv	argument list

Returns

0

Definition at line 1815 of file JParser.hh.

    {
      (*this)(argc, argv);

      return 0;
    }

template<class JKey_t = char>

int JPARSER::JParser< JKey_t >::read ( const JArgs &  args )

inline

Parse the program's command line options.

This method is maintained for backward compatibility and will be deprecated.

Parameters

args	argument list

Returns

0

Definition at line 1830 of file JParser.hh.

    {
      (*this)(args);

      return 0;
    }

template<class JKey_t = char>

std::ostream& JPARSER::JParser< JKey_t >::write ( std::ostream &  out ) const

inline

Print the current parameter values.

Parameters

out	output stream

Returns

output stream

Definition at line 1844 of file JParser.hh.

    {
      for (const_iterator i = this->begin(); i != this->end(); ++i) {
        out << i->second->getName() << '=' << i->second << std::endl;
      }

      return out;
    }

template<class JKey_t = char>

void JPARSER::JParser< JKey_t >::check_status ( ) const

inlineprotected

Check if all required options have been set.

This method throws an exception in case of a non-compliance.

Definition at line 1872 of file JParser.hh.

    {
      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");
        }
      }
    }

Friends And Related Function Documentation

template<class JKey_t = char>

std::ostream& operator<< ( std::ostream &  out, const JParser< key_type > &  parser  )

friend

Stream output.

Parameters

out	output stream
parser	parser

Returns

output stream

Definition at line 1861 of file JParser.hh.

    { 
      return parser.write(out); 
    }

Member Data Documentation

template<class JKey_t = char>

std::string JPARSER::JParser< JKey_t >::help

protected

help message

Definition at line 1886 of file JParser.hh.

template<class JKey_t = char>

std::string JPARSER::JParser< JKey_t >::pid

protected

process name

Definition at line 1887 of file JParser.hh.

template<class T>

int JEEP::JMessage< T >::debug = 0

staticinherited

debug level (default is off).

Definition at line 45 of file JMessage.hh.

---

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

• JParser.hh