E-MailRelay
ggetopt.h
Go to the documentation of this file.
1//
2// Copyright (C) 2001-2023 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 "goption.h"
26#include "goptions.h"
27#include "goptionvalue.h"
28#include "goptionparser.h"
29#include "goptional.h"
30#include "garg.h"
31#include "gpath.h"
32#include "gstringview.h"
33#include "gstringarray.h"
34#include "gexception.h"
35#include <string>
36#include <list>
37
38namespace G
39{
40 class GetOpt ;
41}
42
43//| \class G::GetOpt
44/// A command-line option parser.
45///
46/// Usage:
47/// \code
48/// G::Arg arg( argc , argv ) ;
49/// G::GetOpt opt( arg , "e!extra!does something! extra!1!something!1" "|" "h!help!shows help!!0!!1" ) ;
50/// if( opt.hasErrors() ) { opt.showErrors( std::cerr ) ; exit( 2 ) ; }
51/// if( opt.contains("help") ) { G::OptionsUsage usage( opt.options() ) ;
52/// usage.output( {} , std::cout , arg.prefix() , " [<more>]" ) ;
53/// exit( 0 ) ; }
54/// run( opt.args() , opt.value("extra","default") ) ;
55/// \endcode
56///
57/// This class is a thin layer over G::Options, G::OptionMap, G::OptionParser etc,
58/// but also adding file loading. The G::OptionsOutput class is kept separate in
59/// order to minimise dependencies.
60///
62{
63public:
64 GetOpt( const Arg & arg , const std::string & spec , std::size_t ignore_non_options = 0U ) ;
65 ///< Constructor taking a Arg object and a G::Options specification string.
66 ///< Parsing errors are reported via errorList().
67
68 GetOpt( const StringArray & arg , const std::string & spec , std::size_t ignore_non_options = 0U ) ;
69 ///< An overload taking a vector of command-line arguments.
70 ///< The program name in the first argument is expected but
71 ///< ignored.
72
73 GetOpt( const Arg & arg , const Options & spec , std::size_t ignore_non_options = 0U ) ;
74 ///< A constructor overload taking an Options object.
75
76 GetOpt( const StringArray & arg , const Options & spec , std::size_t ignore_non_options = 0U ) ;
77 ///< A constructor overload taking an Options object.
78
79 void reload( const StringArray & arg , std::size_t ignore_non_options = 0U ) ;
80 ///< Reinitialises the object with the given command-line arguments.
81 ///< The program name in the first position is expected but ignored.
82
83 void addOptionsFromFile( std::size_t n = 1U ,
84 const std::string & varkey = {} , const std::string & varvalue = {} ) ;
85 ///< Adds options from the config file named by the n'th non-option
86 ///< command-line argument (zero-based and allowing for the program
87 ///< name in argv0). The n'th argument is then removed. Does nothing
88 ///< if the n'th argument does not exist or if it is empty. Throws
89 ///< if the file is specified but cannot be opened. Parsing errors
90 ///< are added to errorList(). The optional trailing string parameters
91 ///< are used to perform leading sub-string substitution on the
92 ///< filename.
93
94 bool addOptionsFromFile( size_t n , const StringArray & extension_blocklist ) ;
95 ///< Adds options from the config file named by the n'th non-option
96 ///< argument, but not if the file extension matches any in the block
97 ///< list. Returns false if blocked.
98
99 void addOptionsFromFile( const Path & file ) ;
100 ///< Adds options from the given config file. Throws if the file
101 ///< cannot be opened. Parsing errors are added to errorList().
102
103 const std::vector<Option> & options() const ;
104 ///< Returns the list of option specification objects.
105
106 const OptionMap & map() const ;
107 ///< Returns the map of option-values.
108
109 Arg args() const ;
110 ///< Returns the G::Arg command-line, excluding options.
111
112 StringArray errorList() const ;
113 ///< Returns the list of errors.
114
115 bool hasErrors() const ;
116 ///< Returns true if there are errors.
117
118 void showErrors( std::ostream & stream , const std::string & prefix_1 ,
119 const std::string & prefix_2 = std::string(": ") ) const ;
120 ///< A convenience function which streams out each errorList()
121 ///< item to the given stream, prefixed with the given
122 ///< prefix(es). The two prefixes are simply concatenated.
123
124 void showErrors( std::ostream & stream ) const ;
125 ///< An overload which has a sensible prefix.
126
127 bool contains( char option_letter ) const ;
128 ///< Returns true if the command-line contains the option identified by its
129 ///< short-form letter.
130
131 bool contains( string_view option_name ) const ;
132 ///< Returns true if the command-line contains the option identified by its
133 ///< long-form name.
134
135 std::size_t count( string_view option_name ) const ;
136 ///< Returns the option's repeat count.
137
138 std::string value( string_view option_name , string_view default_ = {} ) const ;
139 ///< Returns the value for the option identified by its long-form name.
140 ///< If the option is multi-valued then the returned value is a
141 ///< comma-separated list. If the option-value is 'on' then
142 ///< Str::positive() is returned; if the option-value is 'off'
143 ///< then the given default is returned.
144
145 std::string value( char option_letter , string_view default_ = {} ) const ;
146 ///< An overload that returns the value of the option identified
147 ///< by its short-form letter.
148 ///< Precondition: contains(option_letter)
149
150 G::optional<std::string> optional( string_view option_name ) const ;
151 ///< Returns an optional value identified by its long-form name.
152
153 static StringArray readOptionsFromFile( const Path & ) ;
154 ///< Reads options from file as a list of strings like "--foo=bar".
155 ///< Throws on error.
156
157private:
158 void parseArgs( std::size_t ) ;
159
160private:
161 Options m_spec ;
162 Arg m_args ;
163 OptionMap m_map ;
164 StringArray m_errors ;
165} ;
166
167#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:62
const OptionMap & map() const
Returns the map of option-values.
Definition: ggetopt.cpp:136
std::size_t count(string_view option_name) const
Returns the option's repeat count.
Definition: ggetopt.cpp:162
void reload(const StringArray &arg, std::size_t ignore_non_options=0U)
Reinitialises the object with the given command-line arguments.
Definition: ggetopt.cpp:71
bool contains(char option_letter) const
Returns true if the command-line contains the option identified by its short-form letter.
Definition: ggetopt.cpp:150
std::string value(string_view option_name, string_view default_={}) const
Returns the value for the option identified by its long-form name.
Definition: ggetopt.cpp:176
const std::vector< Option > & options() const
Returns the list of option specification objects.
Definition: ggetopt.cpp:130
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:37
G::optional< std::string > optional(string_view option_name) const
Returns an optional value identified by its long-form name.
Definition: ggetopt.cpp:181
static StringArray readOptionsFromFile(const Path &)
Reads options from file as a list of strings like "--foo=bar".
Definition: ggetopt.cpp:120
bool hasErrors() const
Returns true if there are errors.
Definition: ggetopt.cpp:191
void addOptionsFromFile(std::size_t n=1U, const std::string &varkey={}, const std::string &varvalue={})
Adds options from the config file named by the n'th non-option command-line argument (zero-based and ...
Definition: ggetopt.cpp:103
bool addOptionsFromFile(size_t n, const StringArray &extension_blocklist)
Adds options from the config file named by the n'th non-option argument, but not if the file extensio...
Arg args() const
Returns the G::Arg command-line, excluding options.
Definition: ggetopt.cpp:186
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:201
StringArray errorList() const
Returns the list of errors.
Definition: ggetopt.cpp:143
A multimap-like container for command-line options and their values.
Definition: goptionmap.h:43
A class to assemble a list of command-line options and provide access by name.
Definition: goptions.h:40
A Path object represents a file system path.
Definition: gpath.h:73
A class like c++17's std::string_view.
Definition: gstringview.h:51
Low-level classes.
Definition: garg.h:30
std::vector< std::string > StringArray
A std::vector of std::strings.
Definition: gstringarray.h:30