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

Member Typedef Documentation

◆ JParserException

template<class JKey_t = char>

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

Definition at line 1701 of file JParser.hh.

◆ key_type

template<class JKey_t = char>

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

Definition at line 1702 of file JParser.hh.

◆ map_type

template<class JKey_t = char>

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

Definition at line 1703 of file JParser.hh.

◆ iterator

template<class JKey_t = char>

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

Definition at line 1705 of file JParser.hh.

◆ const_iterator

template<class JKey_t = char>

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

Definition at line 1706 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 1716 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 1729 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 1743 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 1756 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 1793 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 1806 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 1818 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 1992 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 2007 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 2021 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 2049 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 Function 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 2038 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 2063 of file JParser.hh.

◆ pid

template<class JKey_t = char>

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

protected

process name

Definition at line 2064 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

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

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 Function Documentation

◆ operator<<

Member Data Documentation

◆ help

◆ pid

◆ debug

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