E-MailRelay

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