E-MailRelay

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