E-MailRelay
ggetopt.h
Go to the documentation of this file.
1 //
2 // Copyright (C) 2001-2018 Graeme Walker <graeme_walker@users.sourceforge.net>
3 //
4 // This program is free software: you can redistribute it and/or modify
5 // it under the terms of the GNU General Public License as published by
6 // the Free Software Foundation, either version 3 of the License, or
7 // (at your option) any later version.
8 //
9 // This program is distributed in the hope that it will be useful,
10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 // GNU General Public License for more details.
13 //
14 // You should have received a copy of the GNU General Public License
15 // along with this program. If not, see <http://www.gnu.org/licenses/>.
16 // ===
17 ///
18 /// \file ggetopt.h
19 ///
20 
21 #ifndef G_GETOPT_H
22 #define G_GETOPT_H
23 
24 #include "gdef.h"
25 #include "goptions.h"
26 #include "goptionvalue.h"
27 #include "goptionparser.h"
28 #include "garg.h"
29 #include "gpath.h"
30 #include "gstrings.h"
31 #include "gexception.h"
32 #include <string>
33 #include <list>
34 #include <map>
35 
36 namespace G
37 {
38  class GetOpt ;
39 }
40 
41 /// \class G::GetOpt
42 /// A command line option parser.
43 ///
44 /// Usage:
45 /// \code
46 /// G::Arg arg( argc , argv ) ;
47 /// G::GetOpt opt( arg , "e!extra!does something! extra!1!something!1" "|" "h!help!shows help!!0!!1" ) ;
48 /// if( opt.hasErrors() ) { opt.showErrors( std::cerr ) ; exit( 2 ) ; }
49 /// if( opt.contains("help") ) { opt.options().showUsage( std::cout , arg.prefix() , " [<more>]" ) ; exit( 0 ) ; }
50 /// run( opt.args() , opt.contains("extra") ? opt.value("extra") : std::string() ) ;
51 /// \endcode
52 ///
53 /// \see G::Arg
54 ///
55 class G::GetOpt
56 {
57 public:
58  typedef std::string::size_type size_type ;
59 
60  GetOpt( const Arg & arg , const std::string & spec ) ;
61  ///< Constructor taking a Arg reference and a G::Options specification string.
62  ///< Parsing errors are reported via errorList().
63 
64  GetOpt( const StringArray & arg , const std::string & spec ) ;
65  ///< An overload taking a vector of command-line arguments.
66  ///< The program name in the first argument is expected but
67  ///< ignored.
68 
69  void reload( const StringArray & arg ) ;
70  ///< Reinitialises the object with the given command-line arguments.
71  ///< The program name in the first position is expected but ignored.
72 
73  void addOptionsFromFile( size_type n = 1U ) ;
74  ///< Adds options from the config file named by the n'th non-option
75  ///< command-line argument (zero-based but allowing for the program
76  ///< name in argv0). The n'th argument is then removed. Does nothing
77  ///< if the n'th argument does not exists or if it is empty. Throws
78  ///< if the file is specified but cannot be opened. Parsing errors
79  ///< are added to errorList().
80 
81  void addOptionsFromFile( const Path & file ) ;
82  ///< Adds options from the given config file. Throws if the file
83  ///< cannot be opened. Parsing errors are added to errorList().
84 
85  const Options & options() const ;
86  ///< Returns a reference to the option specification sub-object.
87 
88  const OptionMap & map() const ;
89  ///< Returns a reference to the OptionMap sub-object.
90 
91  Arg args() const ;
92  ///< Returns all the non-option command-line arguments.
93 
94  StringArray errorList() const ;
95  ///< Returns the list of errors.
96 
97  bool hasErrors() const ;
98  ///< Returns true if there are errors.
99 
100  void showErrors( std::ostream & stream , std::string prefix_1 ,
101  std::string prefix_2 = std::string(": ") ) const ;
102  ///< A convenience function which streams out each errorList()
103  ///< item to the given stream, prefixed with the given
104  ///< prefix(es). The two prefixes are simply concatenated.
105 
106  void showErrors( std::ostream & stream ) const ;
107  ///< An overload which has a sensible prefix.
108 
109  bool contains( char option_letter ) const ;
110  ///< Returns true if the command line contains the option identified by its
111  ///< short-form letter.
112 
113  bool contains( const std::string & option_name ) const ;
114  ///< Returns true if the command line contains the option identified by its
115  ///< long-form name.
116 
117  size_t count( const std::string & option_name ) const ;
118  ///< Returns the number of times the option was supplied.
119 
120  std::string value( const std::string & option_name , const std::string & default_ = std::string() ) const ;
121  ///< Returns the value related to the option identified by its long-form name.
122  ///< Returns a string that is a comma-separated list if multi-valued.
123 
124  std::string value( char option_letter , const std::string & default_ = std::string() ) const ;
125  ///< Returns the value related to the option identified by its short-form letter.
126  ///< Returns a string that is a comma-separated list if multi-valued.
127  ///< Precondition: contains(option_letter)
128 
129 
130 private:
131  void operator=( const GetOpt & ) ;
132  GetOpt( const GetOpt & ) ;
133  void parseArgs( Arg & ) ;
134  StringArray optionsFromFile( const G::Path & ) const ;
135 
136 private:
137  Options m_spec ;
138  Arg m_args ;
139  OptionMap m_map ;
140  StringArray m_errors ;
141  OptionParser m_parser ; // order dependency -- last
142 } ;
143 
144 #endif
void showErrors(std::ostream &stream, std::string prefix_1, std::string prefix_2=std::string(": ")) const
A convenience function which streams out each errorList() item to the given stream, prefixed with the given prefix(es).
Definition: ggetopt.cpp:159
size_t count(const std::string &option_name) const
Returns the number of times the option was supplied.
Definition: ggetopt.cpp:128
StringArray errorList() const
Returns the list of errors.
Definition: ggetopt.cpp:113
bool hasErrors() const
Returns true if there are errors.
Definition: ggetopt.cpp:149
std::vector< std::string > StringArray
A std::vector of std::strings.
Definition: gstrings.h:33
A parser for command-line arguments that operates according to an Options specification and returns a...
Definition: goptionparser.h:42
const OptionMap & map() const
Returns a reference to the OptionMap sub-object.
Definition: ggetopt.cpp:108
A multimap-like container for command-line options and their values.
Definition: goptionmap.h:39
void addOptionsFromFile(size_type n=1U)
Adds options from the config file named by the n'th non-option command-line argument (zero-based but ...
A command line option parser.
Definition: ggetopt.h:55
Arg args() const
Returns all the non-option command-line arguments.
Definition: ggetopt.cpp:144
Low-level classes.
Definition: garg.h:29
const Options & options() const
Returns a reference to the option specification sub-object.
Definition: ggetopt.cpp:103
GetOpt(const Arg &arg, const std::string &spec)
Constructor taking a Arg reference and a G::Options specification string.
Definition: ggetopt.cpp:33
std::string value(const std::string &option_name, const std::string &default_=std::string()) const
Returns the value related to the option identified by its long-form name.
Definition: ggetopt.cpp:139
A class which holds a represention of the argc/argv command line array, and supports simple command-l...
Definition: garg.h:43
bool contains(char option_letter) const
Returns true if the command line contains the option identified by its short-form letter...
Definition: ggetopt.cpp:118
void reload(const StringArray &arg)
Reinitialises the object with the given command-line arguments.
Definition: ggetopt.cpp:49
A class to represent allowed command-line options and to provide command-line usage text...
Definition: goptions.h:65
A Path object represents a file system path.
Definition: gpath.h:72