E-MailRelay

goptionparser.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 goptionparser.h
19///
20
21#ifndef G_OPTION_PARSER_H
22#define G_OPTION_PARSER_H
23
24#include "gdef.h"
25#include "gstringarray.h"
26#include "goptions.h"
27#include "goptionvalue.h"
28#include "goptionmap.h"
29#include "gpath.h"
30#include <string>
31#include <functional>
32
33 namespace G
34{
35 class OptionParser ;
36}
37
38//| \class G::OptionParser
39/// A parser for command-line arguments that operates according to an Options
40/// specification and returns an OptionValue multimap.
41/// \see G::Options, G::OptionValue
42///
43 class G::OptionParser
44{
45 public:
46 OptionParser( const Options & spec , OptionMap & values_out , StringArray & errors_out ) ;
47 ///< Constructor. All references are kept (including the const
48 ///< reference). The output map is a multimap, but with methods
49 ///< that also allow it to be used as a simple map with multi-valued
50 ///< options concatenated into a comma-separated list.
51
52 OptionParser( const Options & spec , OptionMap & values_out , StringArray * errors_out = nullptr ) ;
53 ///< Constructor overload taking an optional errors-out parameter.
54
55 StringArray parse( const StringArray & args_in , std::size_t start_position = 1U ,
56 std::size_t ignore_non_options = 0U ,
57 std::function<std::string(const std::string&,bool)> callback_fn = {} ) ;
58 ///< Parses the given command-line arguments into the value map and/or
59 ///< error list defined by the constructor. This can be called
60 ///< more than once, with options accumulating in the internal
61 ///< OptionMap.
62 ///<
63 ///< By default the program name is expected to be the first item in
64 ///< the array and it is ignored, although the 'start-position' parameter
65 ///< can be used to change this. See also G::Arg::array().
66 ///<
67 ///< Parsing stops at the first non-option or at "--" and the
68 ///< remaining non-options are returned. Optionally some number of
69 ///< non-options are tolerated without stopping the parsing if
70 ///< 'ignore_non_options' is non-zero. This is to allow for
71 ///< sub-commands like "exe subcmd --opt arg".
72 ///<
73 ///< Individual arguments can be in short-form like "-c", or long-form
74 ///< like "--foo" or "--foo=bar". Long-form arguments can be passed in
75 ///< two separate arguments, eg. "--foo" followed by "bar". Short-form
76 ///< options can be grouped (eg. "-abc"). Boolean options can be enabled
77 ///< by (eg.) "--verbose" or "--verbose=yes", and disabled by "--verbose=no".
78 ///< Boolean options cannot use two separate arguments (eg. "--verbose"
79 ///< followed by "yes").
80 ///<
81 ///< Entries in the output map are keyed by the option's long name,
82 ///< even if supplied in short-form.
83 ///<
84 ///< Errors are appended to the caller's error list.
85 ///<
86 ///< The optional callback function can be used to modify the parsing
87 ///< of each option. For a double-dash option the callback is passed
88 ///< the string after the double-dash (with false) and it should return
89 ///< the option name to be used for parsing, with an optional leading
90 ///< '-' character to indicate that the parsing results should be
91 ///< discarded. For single-dash options the option letter is looked up
92 ///< in the Options spec first and the long name is passed to the
93 ///< callback (with true).
94 ///<
95 ///< Returns the non-option arguments.
96
97 void errorDuplicate( const std::string & ) ;
98 ///< Adds a 'duplicate' error in the constructor's error list
99 ///< for the given option.
100
101 static StringArray parse( const StringArray & args_in , const Options & spec ,
102 OptionMap & values_out , StringArray * errors_out = nullptr ,
103 std::size_t start_position = 1U , std::size_t ignore_non_options = 0U ,
104 std::function<std::string(const std::string&,bool)> callback_fn = {} ) ;
105 ///< A static function to contruct an OptionParser object
106 ///< and call its parse() method. Returns the residual
107 ///< non-option arguments. Throws on error.
108
109 public:
110 ~OptionParser() = default ;
111 OptionParser( const OptionParser & ) = delete ;
112 OptionParser( OptionParser && ) = delete ;
113 OptionParser & operator=( const OptionParser & ) = delete ;
114 OptionParser & operator=( OptionParser && ) = delete ;
115
116 private:
117 bool haveSeen( const std::string & ) const ;
118 bool haveSeenSame( const std::string & , const std::string & ) const ;
119 static std::string::size_type eqPos( const std::string & ) ;
120 static std::string eqValue( const std::string & , std::string::size_type ) ;
121 void processOptionOn( char c ) ;
122 void processOption( char c , const std::string & value ) ;
123 void processOptionOn( const std::string & s ) ;
124 void processOptionOff( const std::string & s ) ;
125 void processOption( const std::string & s , const std::string & value , bool ) ;
126 void errorNoValue( char ) ;
127 void errorNoValue( const std::string & ) ;
128 void errorUnknownOption( char ) ;
129 void errorUnknownOption( const std::string & ) ;
130 void errorDubiousValue( const std::string & , const std::string & ) ;
131 void errorDuplicate( char ) ;
132 void errorExtraValue( char , const std::string & ) ;
133 void errorExtraValue( const std::string & , const std::string & ) ;
134 void errorConflict( const std::string & ) ;
135 void error( const std::string & ) ;
136 bool haveSeenOn( const std::string & name ) const ;
137 bool haveSeenOff( const std::string & name ) const ;
138 static bool isOldOption( const std::string & ) ;
139 static bool isNewOption( const std::string & ) ;
140 static bool isAnOptionSet( const std::string & ) ;
141 static std::size_t valueCount( const std::string & ) ;
142
143 private:
144 const Options & m_spec ;
145 OptionMap & m_map ;
146 StringArray * m_errors ;
147} ;
148
149#endif
G::OptionMap
A multimap-like container for command-line options and their values.
Definition: goptionmap.h:44
G::OptionParser
A parser for command-line arguments that operates according to an Options specification and returns a...
Definition: goptionparser.h:44
G::OptionParser::errorDuplicate
void errorDuplicate(const std::string &)
Adds a 'duplicate' error in the constructor's error list for the given option.
Definition: goptionparser.cpp:258
G::OptionParser::parse
StringArray parse(const StringArray &args_in, std::size_t start_position=1U, std::size_t ignore_non_options=0U, std::function< std::string(const std::string &, bool)> callback_fn={})
Parses the given command-line arguments into the value map and/or error list defined by the construct...
Definition: goptionparser.cpp:56
G::OptionParser::OptionParser
OptionParser(const Options &spec, OptionMap &values_out, StringArray &errors_out)
Constructor.
Definition: goptionparser.cpp:33
G::Options
A class to assemble a list of command-line options and provide access by name.
Definition: goptions.h:40
goptionmap.h
goptions.h
goptionvalue.h
gpath.h
gstringarray.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