CommandLineArguments.hxx.in 10.3 KB
Newer Older
1
2
3
/*============================================================================
  KWSys - Kitware System Library
  Copyright 2000-2009 Kitware, Inc., Insight Software Consortium
4

5
6
  Distributed under the OSI-approved BSD License (the "License");
  see accompanying file Copyright.txt for details.
7

8
9
10
11
  This software is distributed WITHOUT ANY WARRANTY; without even the
  implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
  See the License for more information.
============================================================================*/
12
13
14
15
16
17
18
#ifndef @KWSYS_NAMESPACE@_CommandLineArguments_hxx
#define @KWSYS_NAMESPACE@_CommandLineArguments_hxx

#include <@KWSYS_NAMESPACE@/Configure.h>
#include <@KWSYS_NAMESPACE@/Configure.hxx>

#include <@KWSYS_NAMESPACE@/stl/string>
19
#include <@KWSYS_NAMESPACE@/stl/vector>
20
21
22
23
24
25
26
27
28
29

/* Define this macro temporarily to keep the code readable.  */
#if !defined (KWSYS_NAMESPACE) && !@KWSYS_NAMESPACE@_NAME_IS_KWSYS
# define kwsys_stl @KWSYS_NAMESPACE@_stl
#endif

namespace @KWSYS_NAMESPACE@
{

class CommandLineArgumentsInternal;
Andy Cedilnik's avatar
Andy Cedilnik committed
30
struct CommandLineArgumentsCallbackStructure;
31
32
33
34
35
36

/** \class CommandLineArguments
 * \brief Command line arguments processing code.
 *
 * Find specified arguments with optional options and execute specified methods
 * or set given variables.
Andy Cedilnik's avatar
Andy Cedilnik committed
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
 *
 * The two interfaces it knows are callback based and variable based. For
 * callback based, you have to register callback for particular argument using
 * AddCallback method. When that argument is passed, the callback will be
 * called with argument, value, and call data. For boolean (NO_ARGUMENT)
 * arguments, the value is "1". If the callback returns 0 the argument parsing
 * will stop with an error.
 *
 * For the variable interface you associate variable with each argument. When
 * the argument is specified, the variable is set to the specified value casted
 * to the apropriate type. For boolean (NO_ARGUMENT), the value is "1".
 *
 * Both interfaces can be used at the same time. 
 *
 * Possible argument types are:
 *   NO_ARGUMENT     - The argument takes no value             : --A
 *   CONCAT_ARGUMENT - The argument takes value after no space : --Aval
 *   SPACE_ARGUMENT  - The argument takes value after space    : --A val 
 *   EQUAL_ARGUMENT  - The argument takes value after equal    : --A=val
56
 *   MULTI_ARGUMENT  - The argument takes values after space   : --A val1 val2 val3 ...
Andy Cedilnik's avatar
Andy Cedilnik committed
57
58
59
60
61
62
63
64
65
66
67
68
69
70
 *
 * Example use:
 *
 * kwsys::CommandLineArguments arg;
 * arg.Initialize(argc, argv);
 * typedef kwsys::CommandLineArguments argT;
 * arg.AddArgument("--something", argT::EQUAL_ARGUMENT, &some_variable, 
 *                 "This is help string for --something");
 * if ( !arg.Parse() )
 *   {
 *   kwsys_ios::cerr << "Problem parsing arguments" << kwsys_ios::endl;
 *   res = 1;
 *   }
 * 
71
72
73
74
75
76
77
78
79
80
81
82
 */

class @KWSYS_NAMESPACE@_EXPORT CommandLineArguments
{
public:
  CommandLineArguments();
  ~CommandLineArguments();

  /**
   * Various argument types.
   */
  enum ArgumentTypeEnum { 
Andy Cedilnik's avatar
Andy Cedilnik committed
83
84
85
    NO_ARGUMENT,
    CONCAT_ARGUMENT,
    SPACE_ARGUMENT,
86
87
    EQUAL_ARGUMENT,
    MULTI_ARGUMENT
88
89
90
  };

  /**
Andy Cedilnik's avatar
Andy Cedilnik committed
91
92
   * Various variable types. When using the variable interface, this specifies
   * what type the variable is.
93
94
95
96
   */
  enum VariableTypeEnum {
    NO_VARIABLE_TYPE = 0, // The variable is not specified
    INT_TYPE,             // The variable is integer (int)
Alexander Neundorf's avatar
 
Alexander Neundorf committed
97
    BOOL_TYPE,            // The variable is boolean (bool)
98
99
    DOUBLE_TYPE,          // The variable is float (double)
    STRING_TYPE,          // The variable is string (char*)
100
101
102
103
104
105
106
    STL_STRING_TYPE,      // The variable is string (char*)
    VECTOR_INT_TYPE,             // The variable is integer (int)
    VECTOR_BOOL_TYPE,            // The vairable is boolean (bool)
    VECTOR_DOUBLE_TYPE,          // The variable is float (double)
    VECTOR_STRING_TYPE,          // The variable is string (char*)
    VECTOR_STL_STRING_TYPE,      // The variable is string (char*)
    LAST_VARIABLE_TYPE
107
108
109
110
111
112
113
114
115
116
117
118
  };

  /**
   * Prototypes for callbacks for callback interface.
   */
  typedef int(*CallbackType)(const char* argument, const char* value, 
    void* call_data);
  typedef int(*ErrorCallbackType)(const char* argument, void* client_data);

  /**
   * Initialize internal data structures. This should be called before parsing.
   */
119
  void Initialize(int argc, const char* const argv[]);
Ken Martin's avatar
Ken Martin committed
120
  void Initialize(int argc, char* argv[]);
121
122
123

  /**
   * Initialize internal data structure and pass arguments one by one. This is
124
   * convenience method for use from scripting languages where argc and argv
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
   * are not available.
   */
  void Initialize();
  void ProcessArgument(const char* arg);

  /**
   * This method will parse arguments and call apropriate methods. 
   */
  int Parse();

  /**
   * This method will add a callback for a specific argument. The arguments to
   * it are argument, argument type, callback method, and call data. The
   * argument help specifies the help string used with this option. The
   * callback and call_data can be skipped.
   */
Andy Cedilnik's avatar
Andy Cedilnik committed
141
142
  void AddCallback(const char* argument, ArgumentTypeEnum type, 
    CallbackType callback, void* call_data, const char* help);
143
144
145

  /**
   * Add handler for argument which is going to set the variable to the
Andy Cedilnik's avatar
Andy Cedilnik committed
146
147
   * specified value. If the argument is specified, the option is casted to the
   * apropriate type.
148
   */
149
150
151
152
  void AddArgument(const char* argument, ArgumentTypeEnum type,
    bool* variable, const char* help);
  void AddArgument(const char* argument, ArgumentTypeEnum type,
    int* variable, const char* help);
Andy Cedilnik's avatar
Andy Cedilnik committed
153
154
155
156
157
158
159
  void AddArgument(const char* argument, ArgumentTypeEnum type, 
    double* variable, const char* help);
  void AddArgument(const char* argument, ArgumentTypeEnum type, 
    char** variable, const char* help);
  void AddArgument(const char* argument, ArgumentTypeEnum type,
    kwsys_stl::string* variable, const char* help);

160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
  /**
   * Add handler for argument which is going to set the variable to the
   * specified value. If the argument is specified, the option is casted to the
   * apropriate type. This will handle the multi argument values.
   */
  void AddArgument(const char* argument, ArgumentTypeEnum type,
    kwsys_stl::vector<bool>* variable, const char* help);
  void AddArgument(const char* argument, ArgumentTypeEnum type,
    kwsys_stl::vector<int>* variable, const char* help);
  void AddArgument(const char* argument, ArgumentTypeEnum type, 
    kwsys_stl::vector<double>* variable, const char* help);
  void AddArgument(const char* argument, ArgumentTypeEnum type, 
    kwsys_stl::vector<char*>* variable, const char* help);
  void AddArgument(const char* argument, ArgumentTypeEnum type,
    kwsys_stl::vector<kwsys_stl::string>* variable, const char* help);

Andy Cedilnik's avatar
Andy Cedilnik committed
176
177
178
179
180
  /**
   * Add handler for boolean argument. The argument does not take any option
   * and if it is specified, the value of the variable is true/1, otherwise it
   * is false/0.
   */
181
182
183
184
185
186
187
188
189
190
191
  void AddBooleanArgument(const char* argument,
    bool* variable, const char* help);
  void AddBooleanArgument(const char* argument,
    int* variable, const char* help);
  void AddBooleanArgument(const char* argument,
    double* variable, const char* help);
  void AddBooleanArgument(const char* argument,
    char** variable, const char* help);
  void AddBooleanArgument(const char* argument,
    kwsys_stl::string* variable, const char* help);

192
193
194
195
196
197
198
199
200
201
202
  /**
   * Set the callbacks for error handling.
   */
  void SetClientData(void* client_data);
  void SetUnknownArgumentCallback(ErrorCallbackType callback);

  /**
   * Get remaining arguments. It allocates space for argv, so you have to call
   * delete[] on it.
   */
  void GetRemainingArguments(int* argc, char*** argv);
203
  void DeleteRemainingArguments(int argc, char*** argv);
204

205
206
207
208
209
210
211
212
  /**
   * If StoreUnusedArguments is set to true, then all unknown arguments will be
   * stored and the user can access the modified argc, argv without known
   * arguments.
   */
  void StoreUnusedArguments(bool val) { this->StoreUnusedArgumentsFlag = val; }
  void GetUnusedArguments(int* argc, char*** argv);

213
214
215
216
217
218
219
220
  /**
   * Return string containing help. If the argument is specified, only return
   * help for that argument.
   */
  const char* GetHelp() { return this->Help.c_str(); }
  const char* GetHelp(const char* arg);

  /**
Andy Cedilnik's avatar
Andy Cedilnik committed
221
222
   * Get / Set the help line length. This length is used when generating the
   * help page. Default length is 80.
223
   */
224
  void SetLineLength(unsigned int);
225
226
  unsigned int GetLineLength();

Andy Cedilnik's avatar
Andy Cedilnik committed
227
  /**
Andy Cedilnik's avatar
Andy Cedilnik committed
228
229
   * Get the executable name (argv0). This is only available when using
   * Initialize with argc/argv.
Andy Cedilnik's avatar
Andy Cedilnik committed
230
231
232
   */
  const char* GetArgv0();

233
234
235
236
237
238
  /**
   * Get index of the last argument parsed. This is the last argument that was
   * parsed ok in the original argc/argv list.
   */
  unsigned int GetLastArgument();

239
240
241
protected:
  void GenerateHelp();

Andy Cedilnik's avatar
Andy Cedilnik committed
242
243
244
245
  //! This is internal method that registers variable with argument
  void AddArgument(const char* argument, ArgumentTypeEnum type,
    VariableTypeEnum vtype, void* variable, const char* help);

246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
  bool GetMatchedArguments(kwsys_stl::vector<kwsys_stl::string>* matches,
    const kwsys_stl::string& arg);

  //! Populate individual variables
  bool PopulateVariable(CommandLineArgumentsCallbackStructure* cs,
    const char* value);

  //! Populate individual variables of type ...
  void PopulateVariable(bool* variable, const kwsys_stl::string& value);
  void PopulateVariable(int* variable, const kwsys_stl::string& value);
  void PopulateVariable(double* variable, const kwsys_stl::string& value);
  void PopulateVariable(char** variable, const kwsys_stl::string& value);
  void PopulateVariable(kwsys_stl::string* variable, const kwsys_stl::string& value);
  void PopulateVariable(kwsys_stl::vector<bool>* variable, const kwsys_stl::string& value);
  void PopulateVariable(kwsys_stl::vector<int>* variable, const kwsys_stl::string& value);
  void PopulateVariable(kwsys_stl::vector<double>* variable, const kwsys_stl::string& value);
  void PopulateVariable(kwsys_stl::vector<char*>* variable, const kwsys_stl::string& value);
  void PopulateVariable(kwsys_stl::vector<kwsys_stl::string>* variable, const kwsys_stl::string& value);

265
266
267
268
269
  typedef CommandLineArgumentsInternal Internal;
  Internal* Internals;
  kwsys_stl::string Help;

  unsigned int LineLength;
270
271

  bool StoreUnusedArgumentsFlag;
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
};

} // namespace @KWSYS_NAMESPACE@

/* Undefine temporary macro.  */
#if !defined (KWSYS_NAMESPACE) && !@KWSYS_NAMESPACE@_NAME_IS_KWSYS
# undef kwsys_stl
#endif

#endif