E-MailRelay
garg.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 garg.h
19///
20
21#ifndef G_ARG_H
22#define G_ARG_H
23
24#include "gdef.h"
25#include "gstringarray.h"
26#include "gstringview.h"
27#include "gpath.h"
28#ifdef G_WINDOWS
29#include "gnowide.h"
30#endif
31#include <vector>
32#include <string>
33#include <new>
34
35namespace G
36{
37 class Arg ;
38}
39
40//| \class G::Arg
41/// A class which holds a represention of the argc/argv command line array,
42/// and supports simple command-line parsing.
43///
44/// A copy of argv[0] is squirrelled away and made accessible via a static
45/// method.
46///
47/// \see G::GetOpt
48///
49class G::Arg
50{
51public:
52 Arg( int argc , char ** argv ) ;
53 ///< Constructor taking argc/argv directly from main().
54 ///< Sets the v0() path and captures the cwd.
55
56 explicit Arg( const G::StringArray & ) ;
57 ///< Constructor taking an array of command-line arguments. The
58 ///< program name in the first position is expected but may be
59 ///< ignored.
60
61 explicit Arg( const std::string & full_command_line ) ;
62 ///< Constructor taking a full command-line.
63
64 Arg( const Path & exe , const std::string & command_line_tail ) ;
65 ///< Constructor taking argv0 and a command-line tail.
66 ///< The first parameter is typically exe().
67
68 static Arg windows() ;
69 ///< Factory function for Windows using GetCommandLineW().
70 ///< Also sets the v0() path and captures the cwd.
71
72 static Path v0() ;
73 ///< Returns a copy of argv[0] from the first call to the
74 ///< argc/argv constructor overload or windows(). Returns
75 ///< the empty path if those methods have never been
76 ///< called successfully. See also exe().
77
78 static Path exe() ;
79 ///< Returns Process::exe() or in exceptional circumstances an
80 ///< absolute path constructed from v0() and the captured cwd.
81 ///< Throws on error. See also v0().
82
83 static Path exe( std::nothrow_t ) ;
84 ///< Returns Process::exe() or in exceptional circumstances an
85 ///< absolute path constructed from v0() and the captured cwd.
86 ///< Returns the empty path on error. See also v0().
87
88 std::size_t c() const ;
89 ///< Returns the number of tokens in the command line, including the
90 ///< program name.
91
92 std::string v( std::size_t i ) const ;
93 ///< Returns the i'th argument.
94 ///< Precondition: i < c()
95
96 std::string v( std::size_t i , const std::string & default_ ) const ;
97 ///< Returns the i'th argument or the default if out of range.
98
99 std::string prefix() const ;
100 ///< Returns the basename of v(0) without any extension. Typically used
101 ///< as a prefix in error messages.
102
103 static const char * prefix( char ** argv ) noexcept ;
104 ///< An exception-free version of prefix() which can be used in
105 ///< main() outside of the outermost try block.
106
107 bool contains( std::string_view option , std::size_t option_args = 0U , bool case_sensitive = true ) const ;
108 ///< Returns true if the command line contains the given option
109 ///< with enough command line arguments left to satisfy the required
110 ///< number of option arguments. (By convention an option starts
111 ///< with a dash, but that is not required here; it's just a string
112 ///< that is matched against command-line arguments.)
113
114 std::size_t count( std::string_view option ) const ;
115 ///< Returns the number of times the given string appears in the
116 ///< list of arguments.
117
118 std::size_t index( std::string_view option , std::size_t option_args = 0U ,
119 std::size_t default_ = 0U ) const ;
120 ///< Returns the index of the given option. Returns zero
121 ///< (or the given default) if not present.
122
123 std::size_t match( const std::string & prefix ) const ;
124 ///< Returns the index of the first argument that matches the
125 ///< given prefix. Returns zero if none.
126
127 bool remove( std::string_view option , std::size_t option_args = 0U ) ;
128 ///< Removes the given option and its arguments. Returns false if
129 ///< the option does not exist.
130
131 std::string removeValue( std::string_view option , const std::string & default_ = {} ) ;
132 ///< Removes the given single-valued option and its value. Returns
133 ///< the option value or the default if the option does not exist.
134
135 std::string removeAt( std::size_t option_index , std::size_t option_args = 0U ) ;
136 ///< Removes the given argument and the following 'option_args' ones.
137 ///< Returns v(option_index+(option_args?1:0),""). Does nothing and
138 ///< returns the empty string if the index is zero or out of range.
139
140 StringArray array( unsigned int shift = 0U ) const ;
141 ///< Returns the arguments as a string array, with an optional shift.
142 ///< A shift of one will remove the program name.
143
144 StringArray::const_iterator cbegin() const ;
145 ///< Returns a begin iterator, advanced to exclude argv0.
146
147 StringArray::const_iterator cend() const ;
148 ///< Returns the end iterator.
149
150private:
151 struct Windows {} ;
152 explicit Arg( Windows ) ;
153 std::size_t find( bool , std::string_view , std::size_t , std::size_t * ) const ;
154 static bool strmatch( bool , std::string_view , std::string_view ) ;
155 void parseImp( const std::string & ) ;
156 static Path exeImp( bool do_throw ) ;
157 void osinit( int , char ** ) ;
158 void split( const std::string & ) ;
159
160private:
161 StringArray m_array ;
162 static Path m_v0 ;
163 static Path m_cwd ;
164} ;
165
166inline G::Arg::Arg( Windows )
167{
168 #ifdef G_WINDOWS
169 parseImp( nowide::getCommandLine() ) ;
170 #endif
171}
172
173namespace G
174{
175 inline G::StringArray::const_iterator begin( const G::Arg & arg ) { return arg.cbegin() ; }
176 inline G::StringArray::const_iterator end( const G::Arg & arg ) { return arg.cend() ; }
177}
178
179#endif
A class which holds a represention of the argc/argv command line array, and supports simple command-l...
Definition: garg.h:50
std::size_t c() const
Returns the number of tokens in the command line, including the program name.
Definition: garg.cpp:182
static Arg windows()
Factory function for Windows using GetCommandLineW().
Definition: garg.cpp:70
std::size_t match(const std::string &prefix) const
Returns the index of the first argument that matches the given prefix.
Definition: garg.cpp:125
std::string v(std::size_t i) const
Returns the i'th argument.
Definition: garg.cpp:187
std::size_t index(std::string_view option, std::size_t option_args=0U, std::size_t default_=0U) const
Returns the index of the given option.
Definition: garg.cpp:174
Arg(int argc, char **argv)
Constructor taking argc/argv directly from main().
Definition: garg.cpp:34
std::size_t count(std::string_view option) const
Returns the number of times the given string appears in the list of arguments.
Definition: garg.cpp:102
std::string removeAt(std::size_t option_index, std::size_t option_args=0U)
Removes the given argument and the following 'option_args' ones.
Definition: garg.cpp:159
StringArray::const_iterator cend() const
Returns the end iterator.
Definition: garg.cpp:273
std::string prefix() const
Returns the basename of v(0) without any extension.
Definition: garg.cpp:198
std::string removeValue(std::string_view option, const std::string &default_={})
Removes the given single-valued option and its value.
Definition: garg.cpp:151
StringArray array(unsigned int shift=0U) const
Returns the arguments as a string array, with an optional shift.
Definition: garg.cpp:88
bool remove(std::string_view option, std::size_t option_args=0U)
Removes the given option and its arguments.
Definition: garg.cpp:142
static Path exe()
Returns Process::exe() or in exceptional circumstances an absolute path constructed from v0() and the...
Definition: garg.cpp:228
bool contains(std::string_view option, std::size_t option_args=0U, bool case_sensitive=true) const
Returns true if the command line contains the given option with enough command line arguments left to...
Definition: garg.cpp:96
StringArray::const_iterator cbegin() const
Returns a begin iterator, advanced to exclude argv0.
Definition: garg.cpp:267
static Path v0()
Returns a copy of argv[0] from the first call to the argc/argv constructor overload or windows().
Definition: garg.cpp:82
A Path object represents a file system path.
Definition: gpath.h:82
Contains inline functions that convert to and from UTF-8 strings in order to call wide-character "W()...
Low-level classes.
Definition: garg.h:36
std::vector< std::string > StringArray
A std::vector of std::strings.
Definition: gstringarray.h:30