E-MailRelay
ggetopt.h
Go to the documentation of this file.
1//
2// Copyright (C) 2001-2021 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
36namespace 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, G::Options, G::OptionMap, G::OptionParser
54///
56{
57public:
58 using size_type = std::string::size_type ;
59
60 GetOpt( const Arg & arg , const std::string & spec , std::size_t ignore_non_options = 0U ) ;
61 ///< Constructor taking a Arg object and a G::Options specification string.
62 ///< Parsing errors are reported via errorList().
63
64 GetOpt( const StringArray & arg , const std::string & spec , std::size_t ignore_non_options = 0U ) ;
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 GetOpt( const Arg & arg , const Options & spec , std::size_t ignore_non_options = 0U ) ;
70 ///< A constructor overload taking an Options object.
71
72 GetOpt( const StringArray & arg , const Options & spec , std::size_t ignore_non_options = 0U ) ;
73 ///< A constructor overload taking an Options object.
74
75 void reload( const StringArray & arg , std::size_t ignore_non_options = 0U ) ;
76 ///< Reinitialises the object with the given command-line arguments.
77 ///< The program name in the first position is expected but ignored.
78
79 void addOptionsFromFile( size_type n = 1U ,
80 const std::string & varkey = std::string() , const std::string & varvalue = std::string() ) ;
81 ///< Adds options from the config file named by the n'th non-option
82 ///< command-line argument (zero-based and allowing for the program
83 ///< name in argv0). The n'th argument is then removed. Does nothing
84 ///< if the n'th argument does not exists or if it is empty. Throws
85 ///< if the file is specified but cannot be opened. Parsing errors
86 ///< are added to errorList(). The optional trailing string parameters
87 ///< are used to perform leading sub-string substitution on the
88 ///< filename.
89
90 void addOptionsFromFile( const Path & file ) ;
91 ///< Adds options from the given config file. Throws if the file
92 ///< cannot be opened. Parsing errors are added to errorList().
93
94 const Options & options() const ;
95 ///< Returns a reference to the option specification sub-object.
96
97 const OptionMap & map() const ;
98 ///< Returns a reference to the OptionMap sub-object.
99
100 Arg args() const ;
101 ///< Returns the G::Arg command-line, excluding options.
102
103 StringArray errorList() const ;
104 ///< Returns the list of errors.
105
106 bool hasErrors() const ;
107 ///< Returns true if there are errors.
108
109 void showErrors( std::ostream & stream , const std::string & prefix_1 ,
110 const std::string & prefix_2 = std::string(": ") ) const ;
111 ///< A convenience function which streams out each errorList()
112 ///< item to the given stream, prefixed with the given
113 ///< prefix(es). The two prefixes are simply concatenated.
114
115 void showErrors( std::ostream & stream ) const ;
116 ///< An overload which has a sensible prefix.
117
118 bool contains( char option_letter ) const ;
119 ///< Returns true if the command-line contains the option identified by its
120 ///< short-form letter.
121
122 bool contains( const std::string & option_name ) const ;
123 ///< Returns true if the command-line contains the option identified by its
124 ///< long-form name.
125
126 std::size_t count( const std::string & option_name ) const ;
127 ///< Returns the option's repeat count.
128
129 std::string value( const std::string & option_name , const std::string & default_ = std::string() ) const ;
130 ///< Returns the value for the option identified by its long-form name.
131 ///< If the option is multi-valued then the returned value is a
132 ///< comma-separated list. If the option-value is 'on' then
133 ///< Str::positive() is returned; if the option-value is 'off'
134 ///< then the given default is returned.
135
136 std::string value( char option_letter , const std::string & default_ = std::string() ) const ;
137 ///< An overload that returns the value of the option identified
138 ///< by its short-form letter.
139 ///< Precondition: contains(option_letter)
140
141public:
142 ~GetOpt() = default ;
143 GetOpt( const GetOpt & ) = delete ;
144 GetOpt( GetOpt && ) = delete ;
145 void operator=( const GetOpt & ) = delete ;
146 void operator=( GetOpt && ) = delete ;
147
148private:
149 void parseArgs( std::size_t ) ;
150 static StringArray optionsFromFile( const Options & , const Path & ) ;
151
152private:
153 Options m_spec ;
154 Arg m_args ;
155 OptionMap m_map ;
156 StringArray m_errors ;
157} ;
158
159#endif
A class which holds a represention of the argc/argv command line array, and supports simple command-l...
Definition: garg.h:44
A command-line option parser.
Definition: ggetopt.h:56
const OptionMap & map() const
Returns a reference to the OptionMap sub-object.
Definition: ggetopt.cpp:118
void reload(const StringArray &arg, std::size_t ignore_non_options=0U)
Reinitialises the object with the given command-line arguments.
Definition: ggetopt.cpp:61
bool contains(char option_letter) const
Returns true if the command-line contains the option identified by its short-form letter.
Definition: ggetopt.cpp:128
const Options & options() const
Returns a reference to the option specification sub-object.
Definition: ggetopt.cpp:113
GetOpt(const Arg &arg, const std::string &spec, std::size_t ignore_non_options=0U)
Constructor taking a Arg object and a G::Options specification string.
Definition: ggetopt.cpp:33
void addOptionsFromFile(size_type n=1U, const std::string &varkey=std::string(), const std::string &varvalue=std::string())
Adds options from the config file named by the n'th non-option command-line argument (zero-based and ...
bool hasErrors() const
Returns true if there are errors.
Definition: ggetopt.cpp:159
std::size_t count(const std::string &option_name) const
Returns the option's repeat count.
Definition: ggetopt.cpp:138
Arg args() const
Returns the G::Arg command-line, excluding options.
Definition: ggetopt.cpp:154
void showErrors(std::ostream &stream, const std::string &prefix_1, const std::string &prefix_2=std::string(": ")) const
A convenience function which streams out each errorList() item to the given stream,...
Definition: ggetopt.cpp:169
StringArray errorList() const
Returns the list of errors.
Definition: ggetopt.cpp:123
std::string value(const std::string &option_name, const std::string &default_=std::string()) const
Returns the value for the option identified by its long-form name.
Definition: ggetopt.cpp:149
A multimap-like container for command-line options and their values.
Definition: goptionmap.h:42
A class to represent allowed command-line options and to provide command-line usage text.
Definition: goptions.h:66
A Path object represents a file system path.
Definition: gpath.h:72
Low-level classes.
Definition: galign.h:28
std::vector< std::string > StringArray
A std::vector of std::strings.
Definition: gstrings.h:31