CommandLineArguments.hxx.in 9.75 KB
Newer Older
1 2
/* Distributed under the OSI-approved BSD 3-Clause License.  See accompanying
   file Copyright.txt or https://cmake.org/licensing#kwsys for details.  */
3 4 5 6 7 8
#ifndef @KWSYS_NAMESPACE@_CommandLineArguments_hxx
#define @KWSYS_NAMESPACE@_CommandLineArguments_hxx

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

Brad King's avatar
Brad King committed
9 10
#include <string>
#include <vector>
11

12
namespace @KWSYS_NAMESPACE@ {
13 14

class CommandLineArgumentsInternal;
Andy Cedilnik's avatar
Andy Cedilnik committed
15
struct CommandLineArgumentsCallbackStructure;
16 17 18 19 20 21

/** \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
22 23 24 25 26 27 28 29 30 31
 *
 * 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
32
 * to the appropriate type. For boolean (NO_ARGUMENT), the value is "1".
Andy Cedilnik's avatar
Andy Cedilnik committed
33
 *
34
 * Both interfaces can be used at the same time.
Andy Cedilnik's avatar
Andy Cedilnik committed
35 36 37 38
 *
 * Possible argument types are:
 *   NO_ARGUMENT     - The argument takes no value             : --A
 *   CONCAT_ARGUMENT - The argument takes value after no space : --Aval
39
 *   SPACE_ARGUMENT  - The argument takes value after space    : --A val
Andy Cedilnik's avatar
Andy Cedilnik committed
40
 *   EQUAL_ARGUMENT  - The argument takes value after equal    : --A=val
41 42
 *   MULTI_ARGUMENT  - The argument takes values after space   : --A val1 val2
 * val3 ...
Andy Cedilnik's avatar
Andy Cedilnik committed
43 44 45 46 47 48
 *
 * Example use:
 *
 * kwsys::CommandLineArguments arg;
 * arg.Initialize(argc, argv);
 * typedef kwsys::CommandLineArguments argT;
49
 * arg.AddArgument("--something", argT::EQUAL_ARGUMENT, &some_variable,
Andy Cedilnik's avatar
Andy Cedilnik committed
50 51 52
 *                 "This is help string for --something");
 * if ( !arg.Parse() )
 *   {
53
 *   std::cerr << "Problem parsing arguments" << std::endl;
Andy Cedilnik's avatar
Andy Cedilnik committed
54 55
 *   res = 1;
 *   }
56
 *
57 58 59 60 61 62 63 64 65 66 67
 */

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

  /**
   * Various argument types.
   */
68 69
  enum ArgumentTypeEnum
  {
Andy Cedilnik's avatar
Andy Cedilnik committed
70 71 72
    NO_ARGUMENT,
    CONCAT_ARGUMENT,
    SPACE_ARGUMENT,
73 74
    EQUAL_ARGUMENT,
    MULTI_ARGUMENT
75 76 77
  };

  /**
Andy Cedilnik's avatar
Andy Cedilnik committed
78 79
   * Various variable types. When using the variable interface, this specifies
   * what type the variable is.
80
   */
81 82 83 84 85 86 87 88 89 90 91 92 93
  enum VariableTypeEnum
  {
    NO_VARIABLE_TYPE = 0,   // The variable is not specified
    INT_TYPE,               // The variable is integer (int)
    BOOL_TYPE,              // The variable is boolean (bool)
    DOUBLE_TYPE,            // The variable is float (double)
    STRING_TYPE,            // The variable is string (char*)
    STL_STRING_TYPE,        // The variable is string (char*)
    VECTOR_INT_TYPE,        // The variable is integer (int)
    VECTOR_BOOL_TYPE,       // The variable 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*)
94
    LAST_VARIABLE_TYPE
95 96 97 98 99
  };

  /**
   * Prototypes for callbacks for callback interface.
   */
100 101 102
  typedef int (*CallbackType)(const char* argument, const char* value,
                              void* call_data);
  typedef int (*ErrorCallbackType)(const char* argument, void* client_data);
103 104 105 106

  /**
   * Initialize internal data structures. This should be called before parsing.
   */
107
  void Initialize(int argc, const char* const argv[]);
Ken Martin's avatar
Ken Martin committed
108
  void Initialize(int argc, char* argv[]);
109 110 111

  /**
   * Initialize internal data structure and pass arguments one by one. This is
112
   * convenience method for use from scripting languages where argc and argv
113 114 115 116 117 118
   * are not available.
   */
  void Initialize();
  void ProcessArgument(const char* arg);

  /**
119
   * This method will parse arguments and call appropriate methods.
120 121 122 123 124 125 126 127 128
   */
  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.
   */
129 130
  void AddCallback(const char* argument, ArgumentTypeEnum type,
                   CallbackType callback, void* call_data, const char* help);
131 132 133

  /**
   * Add handler for argument which is going to set the variable to the
Andy Cedilnik's avatar
Andy Cedilnik committed
134
   * specified value. If the argument is specified, the option is casted to the
135
   * appropriate type.
136
   */
137 138 139 140
  void AddArgument(const char* argument, ArgumentTypeEnum type, bool* variable,
                   const char* help);
  void AddArgument(const char* argument, ArgumentTypeEnum type, int* variable,
                   const char* help);
141
  void AddArgument(const char* argument, ArgumentTypeEnum type,
142
                   double* variable, const char* help);
143
  void AddArgument(const char* argument, ArgumentTypeEnum type,
144
                   char** variable, const char* help);
Andy Cedilnik's avatar
Andy Cedilnik committed
145
  void AddArgument(const char* argument, ArgumentTypeEnum type,
146
                   std::string* variable, const char* help);
Andy Cedilnik's avatar
Andy Cedilnik committed
147

148 149 150
  /**
   * 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
151
   * appropriate type. This will handle the multi argument values.
152 153
   */
  void AddArgument(const char* argument, ArgumentTypeEnum type,
154 155 156
                   std::vector<bool>* variable, const char* help);
  void AddArgument(const char* argument, ArgumentTypeEnum type,
                   std::vector<int>* variable, const char* help);
157
  void AddArgument(const char* argument, ArgumentTypeEnum type,
158
                   std::vector<double>* variable, const char* help);
159
  void AddArgument(const char* argument, ArgumentTypeEnum type,
160 161 162
                   std::vector<char*>* variable, const char* help);
  void AddArgument(const char* argument, ArgumentTypeEnum type,
                   std::vector<std::string>* variable, const char* help);
163

Andy Cedilnik's avatar
Andy Cedilnik committed
164 165 166 167 168
  /**
   * 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.
   */
169 170 171 172 173 174 175 176 177 178
  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, std::string* variable,
                          const char* help);
179

180 181 182 183 184 185 186 187 188 189 190
  /**
   * 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);
191
  void DeleteRemainingArguments(int argc, char*** argv);
192

193 194 195 196 197 198 199 200
  /**
   * 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);

201 202 203 204 205 206 207 208
  /**
   * 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
209 210
   * Get / Set the help line length. This length is used when generating the
   * help page. Default length is 80.
211
   */
212
  void SetLineLength(unsigned int);
213 214
  unsigned int GetLineLength();

Andy Cedilnik's avatar
Andy Cedilnik committed
215
  /**
Andy Cedilnik's avatar
Andy Cedilnik committed
216 217
   * Get the executable name (argv0). This is only available when using
   * Initialize with argc/argv.
Andy Cedilnik's avatar
Andy Cedilnik committed
218 219 220
   */
  const char* GetArgv0();

221 222 223 224 225 226
  /**
   * 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();

227 228 229
protected:
  void GenerateHelp();

Andy Cedilnik's avatar
Andy Cedilnik committed
230 231
  //! This is internal method that registers variable with argument
  void AddArgument(const char* argument, ArgumentTypeEnum type,
232
                   VariableTypeEnum vtype, void* variable, const char* help);
Andy Cedilnik's avatar
Andy Cedilnik committed
233

Brad King's avatar
Brad King committed
234
  bool GetMatchedArguments(std::vector<std::string>* matches,
235
                           const std::string& arg);
236 237 238

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

  //! Populate individual variables of type ...
Brad King's avatar
Brad King committed
242 243 244 245 246 247 248
  void PopulateVariable(bool* variable, const std::string& value);
  void PopulateVariable(int* variable, const std::string& value);
  void PopulateVariable(double* variable, const std::string& value);
  void PopulateVariable(char** variable, const std::string& value);
  void PopulateVariable(std::string* variable, const std::string& value);
  void PopulateVariable(std::vector<bool>* variable, const std::string& value);
  void PopulateVariable(std::vector<int>* variable, const std::string& value);
249 250 251 252 253 254
  void PopulateVariable(std::vector<double>* variable,
                        const std::string& value);
  void PopulateVariable(std::vector<char*>* variable,
                        const std::string& value);
  void PopulateVariable(std::vector<std::string>* variable,
                        const std::string& value);
255

256 257
  typedef CommandLineArgumentsInternal Internal;
  Internal* Internals;
Brad King's avatar
Brad King committed
258
  std::string Help;
259 260

  unsigned int LineLength;
261 262

  bool StoreUnusedArgumentsFlag;
263 264 265 266 267
};

} // namespace @KWSYS_NAMESPACE@

#endif