E-MailRelay

goptions.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 goptions.h
19///
20
21#ifndef G_OPTIONS_H
22#define G_OPTIONS_H
23
24#include "gdef.h"
25#include "gstringarray.h"
26#include "gexception.h"
27#include "goption.h"
28#include <string>
29
30 namespace G
31{
32 class Options ;
33}
34
35//| \class G::Options
36/// A class to assemble a list of command-line options and provide access
37/// by name.
38///
39 class G::Options
40{
41 public:
42 G_EXCEPTION( InvalidSpecification , tx("invalid options specification string") )
43
44 explicit Options( const std::string & spec , char sep_major = '|' , char sep_minor = '!' , char escape = '^' ) ;
45 ///< Constructor taking a specification string.
46 ///<
47 ///< Uses specifications like
48 ///< "p!port!the port! for listening!1!port!1|v!verbose!more logging! and help!0!!1!tag1!tag2"
49 ///< made up of (1) an optional single-character-option-letter,
50 ///< (2) a multi-character-option-name (3) an option-description,
51 ///< (4) optional option-description-extra text, (5) a value-type
52 ///< (with '0' for unvalued, '1' for a single value, '2' for a
53 ///< comma-separated list (possibly multiple times), or '01'
54 ///< for a defaultable single value) or (6) a value-description
55 ///< (unless unvalued), (7) a level enumeration, and optional
56 ///< trailing tags.
57 ///<
58 ///< Typically mainstream options are given a level of 1, and
59 ///< obscure ones level 2 and above. If the option-description
60 ///< field is empty or if the level is zero then the option
61 ///< is hidden.
62 ///<
63 ///< The first tag (if any) is the main tag, corresponding to a
64 ///< sub-heading when generating documentation.
65
66 Options() ;
67 ///< Default constructor for no options.
68
69 static void add( Options & , char c , const char * name , const char * text ,
70 const char * more , Option::Multiplicity m , const char * argname ,
71 unsigned int level , unsigned int main_tag_bit , unsigned int tag_bits = 0U ) ;
72 ///< A convenience function that constructs an Option object with
73 ///< the trailing arguments and then calls add(Option) on the
74 ///< given Options object. The 'text' string is passed through
75 ///< G::gettext() and should therefore normally be marked
76 ///< for translation with G::tx(). The tag parameters
77 ///< are both bit-masks, with only one bit set in the
78 ///< main tag.
79
80 void add( const Option & , char sep = '!' , char escape = '\\' ) ;
81 ///< Adds one component of the specification. If the 'description'
82 ///< contains the unescaped 'sep' character then it is split
83 ///< into two parts and the second part replaces the
84 ///< 'description_extra', which must be empty.
85
86 const std::vector<Option> & list() const ;
87 ///< Returns the sorted list of option structures.
88
89 std::string lookup( char c ) const ;
90 ///< Converts from short-form option character to the corresponding
91 ///< long-form name. Returns the empty string if none.
92
93 bool valid( const std::string & ) const ;
94 ///< Returns true if the long-form option name is valid.
95
96 const Option * find( const std::string & ) const ;
97 ///< Returns a pointer to the option with a matching
98 ///< long-form name. Returns nullptr if none.
99
100 bool visible( const std::string & name , unsigned int level , bool level_exact = false ) const ;
101 ///< Returns true if the option is visible at the given level.
102 ///< Deliberately hidden options at level zero are never
103 ///< visible(). Returns false if not a valid() name .
104
105 bool visible( const std::string & name ) const ;
106 ///< Returns true if the option is visible. Returns false if
107 ///< the option is hidden or the name is not valid().
108
109 bool valued( char ) const ;
110 ///< Returns true if the given short-form option takes a value,
111 ///< Returns true if the short-form option character is valued,
112 ///< including multivalued() and defaulting().
113 ///< Returns false if not valid().
114
115 bool valued( const std::string & ) const ;
116 ///< Returns true if the given long-form option takes a value,
117 ///< including multivalued() and defaulting(). Returns false
118 ///< if not valid().
119
120 bool multivalued( char ) const ;
121 ///< Returns true if the short-form option can have multiple values.
122 ///< Returns false if not valid().
123
124 bool multivalued( const std::string & ) const ;
125 ///< Returns true if the long-form option can have multiple values.
126 ///< Returns false if not valid().
127
128 bool unvalued( const std::string & ) const ;
129 ///< Returns true if the given option name is valid and
130 ///< takes no value. Returns false if not valid().
131
132 bool defaulting( const std::string & ) const ;
133 ///< Returns true if the given long-form single-valued() option
134 ///< can optionally have no explicit value, so "--foo=" and "--foo"
135 ///< are equivalent, having an empty value, and "--foo=bar" has
136 ///< a value of 'bar' but "--foo bar" is interpreted as 'foo'
137 ///< taking its default (empty) value followed by a separate
138 ///< argument 'bar'.
139
140 bool defaulting( char ) const ;
141 ///< Returns defaulting(lookup()) even though defaulting options
142 ///< can never take a value when short-form.
143
144 private:
145 using List = std::vector<Option> ;
146 void parseSpec( const std::string & spec , char , char , char ) ;
147 void addOption( Option , char , char ) ;
148
149 private:
150 List m_list ;
151} ;
152
153#endif
G::Options
A class to assemble a list of command-line options and provide access by name.
Definition: goptions.h:40
G::Options::lookup
std::string lookup(char c) const
Converts from short-form option character to the corresponding long-form name.
Definition: goptions.cpp:165
G::Options::unvalued
bool unvalued(const std::string &) const
Returns true if the given option name is valid and takes no value.
Definition: goptions.cpp:133
G::Options::add
static void add(Options &, char c, const char *name, const char *text, const char *more, Option::Multiplicity m, const char *argname, unsigned int level, unsigned int main_tag_bit, unsigned int tag_bits=0U)
A convenience function that constructs an Option object with the trailing arguments and then calls ad...
Definition: goptions.cpp:69
G::Options::visible
bool visible(const std::string &name, unsigned int level, bool level_exact=false) const
Returns true if the option is visible at the given level.
Definition: goptions.cpp:149
G::Options::defaulting
bool defaulting(const std::string &) const
Returns true if the given long-form single-valued() option can optionally have no explicit value,...
Definition: goptions.cpp:116
G::Options::valid
bool valid(const std::string &) const
Returns true if the long-form option name is valid.
Definition: goptions.cpp:160
G::Options::multivalued
bool multivalued(char) const
Returns true if the short-form option can have multiple values.
Definition: goptions.cpp:138
G::Options::valued
bool valued(char) const
Returns true if the given short-form option takes a value, Returns true if the short-form option char...
Definition: goptions.cpp:122
G::Options::find
const Option * find(const std::string &) const
Returns a pointer to the option with a matching long-form name.
Definition: goptions.cpp:175
G::Options::Options
Options()
Default constructor for no options.
G::Options::list
const std::vector< Option > & list() const
Returns the sorted list of option structures.
Definition: goptions.cpp:185
gexception.h
goption.h
gstringarray.h
G
Low-level classes.
Definition: garg.h:36
G::tx
constexpr const char * tx(const char *p) noexcept
A briefer alternative to G::gettext_noop().
Definition: ggettext.h:84
G::Option
A structure representing a G::Options command-line option.
Definition: goption.h:38