E-MailRelay

- Main Page
- Namespaces
- Classes
- Files

- File List
- File Members

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
G::GetOpt::showErrors
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
G::GetOpt::count
size_t count(const std::string &option_name) const
Returns the number of times the option was supplied.
Definition: ggetopt.cpp:128
goptions.h
gstrings.h
G::GetOpt::errorList
StringArray errorList() const
Returns the list of errors.
Definition: ggetopt.cpp:113
G::GetOpt::hasErrors
bool hasErrors() const
Returns true if there are errors.
Definition: ggetopt.cpp:149
G::StringArray
std::vector< std::string > StringArray
A std::vector of std::strings.
Definition: gstrings.h:33
G::OptionParser
A parser for command-line arguments that operates according to an Options specification and returns a...
Definition: goptionparser.h:42
G::GetOpt::map
const OptionMap & map() const
Returns a reference to the OptionMap sub-object.
Definition: ggetopt.cpp:108
goptionvalue.h
garg.h
G::OptionMap
A multimap-like container for command-line options and their values.
Definition: goptionmap.h:39
G::GetOpt::addOptionsFromFile
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 ...
G::GetOpt
A command line option parser.
Definition: ggetopt.h:55
G::GetOpt::args
Arg args() const
Returns all the non-option command-line arguments.
Definition: ggetopt.cpp:144
G
Low-level classes.
Definition: garg.h:29
G::GetOpt::options
const Options & options() const
Returns a reference to the option specification sub-object.
Definition: ggetopt.cpp:103
G::GetOpt::GetOpt
GetOpt(const Arg &arg, const std::string &spec)
Constructor taking a Arg reference and a G::Options specification string.
Definition: ggetopt.cpp:33
gexception.h
G::GetOpt::value
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
gpath.h
goptionparser.h
G::Arg
A class which holds a represention of the argc/argv command line array, and supports simple command-l...
Definition: garg.h:43
G::GetOpt::contains
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
G::GetOpt::reload
void reload(const StringArray &arg)
Reinitialises the object with the given command-line arguments.
Definition: ggetopt.cpp:49
G::Options
A class to represent allowed command-line options and to provide command-line usage text...
Definition: goptions.h:65
G::Path
A Path object represents a file system path.
Definition: gpath.h:72