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.

	JParser (const std::string &message, const int debug=0)
	Constructor.

JParser &	join (const JParser &parser)
	Join parser.

void	print (std::ostream &out) const
	Print the possible command line options.

virtual void	terminate (const int status)
	Terminate.

JArgs	operator() (const int argc, const char *const argv[])
	Parse the program's command line options.

JArgs	operator() (const JArgs &args)
	Parse the program's command line options.

int	read (const int argc, const char *const argv[])
	Parse the program's command line options.

int	read (const JArgs &args)
	Parse the program's command line options.

std::ostream &	write (std::ostream &out) const
	Print the current parameter values.

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

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

Protected Attributes
std::string	help
	help message

std::string	pid
	process name

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

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 1661 of file JParser.hh.

Member Typedef Documentation

◆ JParserException

template<class JKey_t = char>

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

Definition at line 1667 of file JParser.hh.

◆ key_type

template<class JKey_t = char>

JKey_t JPARSER::JParser< JKey_t >::key_type

Definition at line 1668 of file JParser.hh.

◆ map_type

template<class JKey_t = char>

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

Definition at line 1669 of file JParser.hh.

◆ iterator

template<class JKey_t = char>

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

Definition at line 1671 of file JParser.hh.

◆ const_iterator

template<class JKey_t = char>

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

Definition at line 1672 of file JParser.hh.

Constructor & Destructor Documentation

◆ JParser() [1/2]

template<class JKey_t = char>

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

inline

Default constructor.

Parameters

debug debug level

Definition at line 1682 of file JParser.hh.

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

◆ JParser() [2/2]

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 1695 of file JParser.hh.

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

Member Function Documentation

◆ join()

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 1709 of file JParser.hh.

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

◆ print()

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

Definition at line 1722 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;
      }
    }

◆ terminate()

template<class JKey_t = char>

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

inlinevirtual

Terminate.

Parameters

status exit status

Definition at line 1759 of file JParser.hh.

    {
      exit(status);
    }

◆ operator()() [1/2]

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 1772 of file JParser.hh.

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

◆ operator()() [2/2]

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

◆ read() [1/2]

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 1958 of file JParser.hh.

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

◆ read() [2/2]

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 1973 of file JParser.hh.

    {
      (*this)(args);
 
      return 0;
    }

◆ write()

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 1987 of file JParser.hh.

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

◆ check_status()

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 2015 of file JParser.hh.

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

Friends And Related Symbol Documentation

◆ operator<<

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 2004 of file JParser.hh.

    { 
      return parser.write(out); 
    }

Member Data Documentation

◆ help

template<class JKey_t = char>

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

protected

help message

Definition at line 2029 of file JParser.hh.

◆ pid

template<class JKey_t = char>

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

protected

process name

Definition at line 2030 of file JParser.hh.

◆ debug

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

Public Types

Public Member Functions

Static Public Attributes

Protected Member Functions

Protected Attributes

Friends

Detailed Description

Member Typedef Documentation

◆ JParserException

◆ key_type

◆ map_type

◆ iterator

◆ const_iterator

Constructor & Destructor Documentation

◆ JParser() [1/2]

◆ JParser() [2/2]

Member Function Documentation

◆ join()

◆ print()

◆ terminate()

◆ operator()() [1/2]

◆ operator()() [2/2]

◆ read() [1/2]

◆ read() [2/2]

◆ write()

◆ check_status()

Friends And Related Symbol Documentation

◆ operator<<

Member Data Documentation

◆ help

◆ pid

◆ debug