Subversion Repositories public

Rev

Rev 69 | Details | Compare with Previous | Last modification | View Log | RSS feed

Rev Author Line No. Line
69 luk 1
 
2
/// application arguments processor header
3
/**
4
 * \file appargs.h
5
 *
6
 * application arguments processor
7
 *
100 luk 8
 * Copyright (C) 2007, 2008 Lukas Jelinek, <lukas@aiken.cz>
69 luk 9
 *
10
 * This program is free software; you can redistribute it and/or
11
 * modify it under the terms of one of the following licenses:
12
 *
13
 * \li 1. X11-style license (see LICENSE-X11)
14
 * \li 2. GNU Lesser General Public License, version 2.1 (see LICENSE-LGPL)
15
 * \li 3. GNU General Public License, version 2  (see LICENSE-GPL)
16
 *
17
 * If you want to help with choosing the best license for you,
18
 * please visit http://www.gnu.org/licenses/license-list.html.
19
 *
20
 */
21
 
22
 
23
#ifndef APPARGS_H_
24
#define APPARGS_H_
25
 
100 luk 26
#include <cstring>
69 luk 27
#include <map>
28
#include <deque>
29
 
30
 
31
 
32
/// Option argument type
33
typedef enum
34
{
35
  AAT_NO_VALUE,       ///< no value needed
36
  AAT_OPTIONAL_VALUE, ///< optional value
37
  AAT_MANDATORY_VALUE ///< mandatory value
38
} AppArgType_t;
39
 
40
 
41
#define APPARGS_NOLIMIT 0x7fffffff ///< value count has no limit
42
 
43
/// Argument option type
44
typedef struct
45
{
46
  AppArgType_t type;  ///< argument type
47
  bool mand;          ///< mandatory yes/no
48
  bool found;         ///< found in argument vector
49
  std::string val;    ///< value
50
  bool hasVal;        ///< value is set 
51
} AppArgOption_t;
52
 
53
 
54
/// Mapping from long option name to option data
55
typedef std::map<std::string, AppArgOption_t*> AA_LONG_MAP;
56
 
57
/// Mapping from short option name to option data
58
typedef std::map<char, AppArgOption_t*> AA_SHORT_MAP;
59
 
60
/// Value list type
61
typedef std::deque<std::string> AA_VAL_LIST;
62
 
63
 
64
/// Application arguments
65
/**
66
 * This class is set-up for processing command line arguments.
67
 * Then it parses these arguments and builds data which
68
 * can be queried later.
69
 *
70
 * There are two categories of arguments:
71
 * \li options (a.k.a. switches)
72
 * \li values
73
 *
74
 * Options represent changeable parameters of the application.
75
 * Values are a kind of input data.
76
 *
77
 * Each option has one of the following types:
78
 * \li no value (two-state logic, e.g. running on foreground/background)
79
 * \li optional value (e.g. for logging: another file than default can be specified)
80
 * \li mandatory value (e.g. custom configuration file)
81
 *
82
 * Each option always have two forms - long one (introcuded by
83
 * two hyphens, e.g. --edit) and short one (introduced by one
84
 * hyphen, e.g. -e). These forms are functionally equivalent.
85
 *
86
 * Unknown options are silently ignored.
87
 */
88
class AppArgs
89
{
90
public:
91
  /// Initializes the processor.
92
  /**
93
   * \param[in] valMinCnt minimum count of values
94
   * \param[in] valMaxCnt maximum number of values (no effect if lower than valMinCnt)
95
   */
96
  static void Init(size_t valMinCnt = 0, size_t valMaxCnt = APPARGS_NOLIMIT);
97
 
98
  /// Releases resources allocated by the processor.
99
  /**
100
   * This method should be called if the argument values are
101
   * no longer needed.
102
   */
103
  static void Destroy();
104
 
105
  /// Parses arguments and builds the appropriate structure.
106
  /**
107
   * \param[in] argc argument count
108
   * \param[in] argv argument vector
109
   *
110
   * \attention All errors are silently ignored.
111
   */
112
  static void Parse(int argc, const char* const* argv);
113
 
114
  /// Checks whether the arguments have valid form.
115
  /**
116
   * Arguments are valid if:
117
   * \li all mandatory options are present
118
   * \li all options with mandatory values have their values
119
   * \li value count is between its minimum and maximum
120
   * \li there are no unknown options (if unknown options are not accepted)
121
   *
122
   * \return true = arguments valid, false = otherwise
123
   */
124
  static bool IsValid();
125
 
126
  /// Checks whether an option exists.
127
  /**
128
   * \param[in] rArg long option name
129
   * \return true = option exists, false = otherwise
130
   */
131
  static bool ExistsOption(const std::string& rArg);
132
 
133
  /// Extracts an option value.
134
  /**
135
   * \param[in] rArg long option name
136
   * \param[out] rVal option value
137
   * \return true = value extracted, false = option not found or has no value
138
   */
139
  static bool GetOption(const std::string& rArg, std::string& rVal);
140
 
141
  /// Adds an option.
142
  /**
143
   * This method is intended to be called between initilization
144
   * and parsing. It adds an option which may (or must) occur
145
   * inside the argument vector.
146
   *
147
   * \param[in] rName long option name
148
   * \param[in] cShort short (one-character) option name
149
   * \param[in] type argument type
150
   * \param[in] fMandatory option is mandatory yes/no
151
   * \return true = success, false = failure (e.g. option already exists)
152
   */  
153
  static bool AddOption(const std::string& rName, char cShort, AppArgType_t type, bool fMandatory);
154
 
155
  /// Returns the count of values.
156
  /**
157
   * \return count of values
158
   */
159
  static size_t GetValueCount();
160
 
161
  /// Extracts a value.
162
  /**
163
   * \param[in] index value index
164
   * \param[out] rVal extracted value
165
   * \return true = value extracted, false = otherwise
166
   */
167
  static bool GetValue(size_t index, std::string& rVal);
168
 
169
  /// Dumps information about options and value to STDERR.
170
  /**
171
   * \attention This method may be very slow.
172
   */
173
  static void Dump();  
174
 
175
protected:
176
  /// Checks whether a string is an option.
177
  /**
178
   * \param[in] pchStr text string
179
   * \return true = option, false = otherwise
180
   */
181
  static bool IsOption(const char* pchStr);
182
 
183
  /// Checks whether a string is a long option.
184
  /**
185
   * This methos assumes the string is an option
186
   * (if not the behavior is undefined).
187
   *
188
   * \param[in] pchStr text string
189
   * \return true = option, false = otherwise
190
   */
191
  static bool IsLongOption(const char* pchStr);
192
 
193
  /// Parses a string and attempts to treat it as a long option.
194
  /**
195
   * \param[in] pchStr text string
196
   * \param[out] rName option name
197
   * \param[out] rVal value string
198
   * \param[out] rfHasVal option has value yes/no
199
   * \return true = success, false = failure
200
   */
201
  static bool ParseLong(const char* pchStr, std::string& rName, std::string& rVal, bool& rfHasVal);
202
 
203
  /// Parses a string and attempts to treat it as a short option.
204
  /**
205
   * \param[in] pchStr text string
206
   * \param[out] rcName option name
207
   * \param[out] rVal value string
208
   * \param[out] rfHasVal option has value yes/no
209
   *
210
   * \attention This method assumes the string is a valid short option.
211
   */
212
  static void ParseShort(const char* pchStr, char& rcName, std::string& rVal, bool& rfHasVal);
213
 
214
  /// Dumps an option to STDERR.
215
  /**
216
   * \param[in] rName long option name
217
   * \param[in] cShort short option name
218
   * \param[in] pOpt option data
219
   */
220
  static void DumpOption(const std::string& rName, char cShort, AppArgOption_t* pOpt);
221
 
222
 
223
private:
224
  static size_t s_minCnt;         ///< minimum value count
225
  static size_t s_maxCnt;         ///< maximum value count
226
 
227
  static AA_LONG_MAP s_longMap;   ///< mapping from long names to data
228
  static AA_SHORT_MAP s_shortMap; ///< mapping from short names to data
229
  static AA_VAL_LIST s_valList;   ///< value list
230
 
231
};
232
 
233
 
234
#endif /*APPARGS_H_*/