1 /*****************************************************************************/ 2 /* Software Testing Automation Framework (STAF) */ 3 /* (C) Copyright IBM Corp. 2001 */ 4 /* */ 5 /* This software is licensed under the Eclipse Public License (EPL) V1.0. */ 6 /*****************************************************************************/ 7 8 #ifndef STAF_CommandParser 9 #define STAF_CommandParser 10 11 #include "STAFString.h" 12 13 #ifdef __cplusplus 14 extern "C" { 15 #endif 16 17 typedef struct STAFCommandParserImpl *STAFCommandParser_t; 18 typedef struct STAFCommandParseResultImpl *STAFCommandParseResult_t; 19 20 // XXX: Consider passing non-ptrs to the APIs that do not need ptr-ptr 21 // XXX: Also consider having a brief discussion about how to use parser 22 // XXX: for debug 23 24 class STAFCommandParser; 25 class STAFCommandParseResult; 26 void printParserInfo(STAFCommandParser &); 27 void printParseResultInfo(STAFCommandParseResult &); 28 void printParserInfo2(STAFCommandParserImpl &); 29 void printParseResultInfo2(STAFCommandParseResultImpl &); 30 31 typedef STAFRefPtr<STAFCommandParser> STAFCommandParserPtr; 32 33 /***********************************************************************/ 34 /* STAFCommandParserConstruct - Creates a STAF Command Parser */ 35 /* */ 36 /* Accepts: (Out) Pointer to a STAF Command Parser */ 37 /* (In) The maximum number of arguments allowed by the */ 38 /* parser */ 39 /* (In) Whether the parser is case sensitive (0 = No, */ 40 /* 1 = Yes) */ 41 /* (Out) Pointer to OS return code */ 42 /* */ 43 /* Returns: kSTAFOk, on success */ 44 /* other on error */ 45 /***********************************************************************/ 46 STAFRC_t STAFCommandParserConstruct(STAFCommandParser_t *pParser, 47 unsigned int maxArgs, unsigned int caseSensitive, unsigned int *osRC); 48 49 50 /***********************************************************************/ 51 /* STAFCommandParserAddOption - Adds an option to the parser */ 52 /* */ 53 /* Accepts: (In) Pointer to a STAF Command Parser */ 54 /* (In) The option name */ 55 /* (In) The number of times this option may be specified */ 56 /* (0 = Unlimited) */ 57 /* (In) Whether the option allows, requires, or may not have */ 58 /* a value associated with it. (0 = Not Allowed, */ 59 /* 1 = Allowed, 2 = Required) */ 60 /* (Out) Pointer to OS return code */ 61 /* */ 62 /* Returns: kSTAFOk, on success */ 63 /* other on error */ 64 /***********************************************************************/ 65 STAFRC_t STAFCommandParserAddOption(STAFCommandParser_t parser, 66 const STAFString_t optionName, unsigned int timesAllowed, 67 unsigned int valueRequirement, unsigned int *osRC); 68 69 70 /***********************************************************************/ 71 /* STAFCommandParserAddOptionGroup - Adds an option group to the */ 72 /* parser */ 73 /* */ 74 /* Accepts: (In) Pointer to a STAF Command Parser */ 75 /* (In) The list of option names in the group */ 76 /* (In) The minimum number of options that must be specified */ 77 /* (In) The maximum number of options that may be specified */ 78 /* (Out) Pointer to OS return code */ 79 /* */ 80 /* Returns: kSTAFOk, on success */ 81 /* other on error */ 82 /***********************************************************************/ 83 STAFRC_t STAFCommandParserAddOptionGroup(STAFCommandParser_t parser, 84 const STAFString_t optionGroup, unsigned int minOptions, 85 unsigned int maxOptions, unsigned int *osRC); 86 87 88 /***********************************************************************/ 89 /* STAFCommandParserAddOptionNeed - Adds an option need to the parser */ 90 /* */ 91 /* Accepts: (In) Pointer to a STAF Command Parser */ 92 /* (In) The list of needer option names */ 93 /* (In) The list of needee option names */ 94 /* (Out) Pointer to OS return code */ 95 /* */ 96 /* Returns: kSTAFOk, on success */ 97 /* other on error */ 98 /***********************************************************************/ 99 STAFRC_t STAFCommandParserAddOptionNeed(STAFCommandParser_t parser, 100 const STAFString_t optionNeeders, const STAFString_t optionNeedees, 101 unsigned int *osRC); 102 103 104 /***********************************************************************/ 105 /* STAFCommandParserParseString - Parses a string */ 106 /* */ 107 /* Note: On error, use STAFCommandParseResultGetErrorBuffer to get a */ 108 /* string containing a description of the error. */ 109 /* */ 110 /* Accepts: (In) Pointer to a STAF Command Parser */ 111 /* (In) The string to parse */ 112 /* (Out) Pointer to the STAFCommandParseResult_t */ 113 /* (Out) Pointer to the error buffer */ 114 /* (Out) Pointer to OS return code */ 115 /* */ 116 /* Returns: kSTAFOk, on success */ 117 /* other on error */ 118 /***********************************************************************/ 119 STAFRC_t STAFCommandParserParseString(STAFCommandParser_t parser, 120 const STAFString_t theString, STAFCommandParseResult_t *result, 121 STAFString_t *errorBuffer, unsigned int *osRC); 122 123 124 /***********************************************************************/ 125 /* STAFCommandParserDestruct - Destroys a STAF Command Parser */ 126 /* */ 127 /* Accepts: (In) Pointer to a STAF Command Parser */ 128 /* (Out) Pointer to OS return code */ 129 /* */ 130 /* Returns: kSTAFOk, on success */ 131 /* other on error */ 132 /***********************************************************************/ 133 STAFRC_t STAFCommandParserDestruct(STAFCommandParser_t *pParser, 134 unsigned int *osRC); 135 136 137 /***********************************************************************/ 138 /* STAFCommandParseResultGetErrorBuffer - Gets the result's error buf- */ 139 /* fer set on parsing errors */ 140 /* */ 141 /* Accepts: (In) Pointer to a STAF Command Parse Result */ 142 /* (Out) Pointer to a STAFString to contain the error buffer */ 143 /* (Out) Pointer to OS return code */ 144 /* */ 145 /* Returns: kSTAFOk, on success */ 146 /* other on error */ 147 /***********************************************************************/ 148 STAFRC_t STAFCommandParseResultGetErrorBuffer( 149 STAFCommandParseResult_t result, STAFString_t *theBuffer, 150 unsigned int *osRC); 151 152 153 /***********************************************************************/ 154 /* STAFCommandParseResultGetNumInstances - Gets the total number of */ 155 /* options specified by the */ 156 /* user in the parsed string */ 157 /* */ 158 /* Accepts: (In) Pointer to a STAF Command Parse Result */ 159 /* (Out) Pointer to the number of options */ 160 /* (Out) Pointer to OS return code */ 161 /* */ 162 /* Returns: kSTAFOk, on success */ 163 /* other on error */ 164 /***********************************************************************/ 165 STAFRC_t STAFCommandParseResultGetNumInstances( 166 STAFCommandParseResult_t result, unsigned int *numInstances, 167 unsigned int *osRC); 168 169 170 /***********************************************************************/ 171 /* STAFCommandParseResultGetInstanceName - Gets the name of the */ 172 /* specified option instance */ 173 /* */ 174 /* Accepts: (In) Pointer to a STAF Command Parse Result */ 175 /* (In) The option instance number */ 176 /* (Out) Pointer to the option name */ 177 /* (Out) Pointer to OS return code */ 178 /* */ 179 /* Returns: kSTAFOk, on success */ 180 /* other on error */ 181 /***********************************************************************/ 182 STAFRC_t STAFCommandParseResultGetInstanceName( 183 STAFCommandParseResult_t result, unsigned int instanceNum, 184 STAFString_t *instanceName, unsigned int *osRC); 185 186 187 /***********************************************************************/ 188 /* STAFCommandParseResultGetInstanceValue - Gets the value of the */ 189 /* specified option instance */ 190 /* */ 191 /* Accepts: (In) Pointer to a STAF Command Parse Result */ 192 /* (In) The option instance number */ 193 /* (Out) Pointer to the option value */ 194 /* (Out) Pointer to OS return code */ 195 /* */ 196 /* Returns: kSTAFOk, on success */ 197 /* other on error */ 198 /***********************************************************************/ 199 STAFRC_t STAFCommandParseResultGetInstanceValue( 200 STAFCommandParseResult_t result, unsigned int instanceNum, 201 STAFString_t *instanceValue, unsigned int *osRC); 202 203 204 /***********************************************************************/ 205 /* STAFCommandParseResultGetOptionTimes - Gets the number of times */ 206 /* a particular option was */ 207 /* specified by the user */ 208 /* */ 209 /* Accepts: (In) Pointer to a STAF Command Parse Result */ 210 /* (In) The option name */ 211 /* (Out) Pointer to the number of times the option was */ 212 /* specified */ 213 /* (Out) Pointer to OS return code */ 214 /* */ 215 /* Returns: kSTAFOk, on success */ 216 /* other on error */ 217 /***********************************************************************/ 218 STAFRC_t STAFCommandParseResultGetOptionTimes( 219 STAFCommandParseResult_t result, const STAFString_t optionName, 220 unsigned int *numTimes, unsigned int *osRC); 221 222 223 /***********************************************************************/ 224 /* STAFCommandParseResultGetOptionValue - Gets the value of a */ 225 /* particular instance of a */ 226 /* particular option */ 227 /* */ 228 /* Accepts: (In) Pointer to a STAF Command Parse Result */ 229 /* (In) The name of this option */ 230 /* (In) The number of the desired instance of this option */ 231 /* (Out) Pointer to the option value */ 232 /* (Out) Pointer to OS return code */ 233 /* */ 234 /* Returns: kSTAFOk, on success */ 235 /* other on error */ 236 /***********************************************************************/ 237 STAFRC_t STAFCommandParseResultGetOptionValue( 238 STAFCommandParseResult_t result, const STAFString_t optionName, 239 unsigned int optionIndex, STAFString_t *optionValue, 240 unsigned int *osRC); 241 242 243 /***********************************************************************/ 244 /* STAFCommandParseResultGetNumArgs - Gets the number of free-standing */ 245 /* arguments the user specified */ 246 /* */ 247 /* Accepts: (In) Pointer to a STAF Command Parse Result */ 248 /* (Out) Pointer to the number of arguments */ 249 /* (Out) Pointer to OS return code */ 250 /* */ 251 /* Returns: kSTAFOk, on success */ 252 /* other on error */ 253 /***********************************************************************/ 254 STAFRC_t STAFCommandParseResultGetNumArgs( 255 STAFCommandParseResult_t result, unsigned int *numArgs, 256 unsigned int *osRC); 257 258 259 /***********************************************************************/ 260 /* STAFCommandParseResultGetArgValue - Gets the value of a particular */ 261 /* argument */ 262 /* */ 263 /* Accepts: (In) Pointer to a STAF Command Parse Result */ 264 /* (In) The number of the desired argument */ 265 /* (Out) Pointer to the argument value */ 266 /* (Out) Pointer to OS return code */ 267 /* */ 268 /* Returns: kSTAFOk, on success */ 269 /* other on error */ 270 /***********************************************************************/ 271 STAFRC_t STAFCommandParseResultGetArgValue( 272 STAFCommandParseResult_t result, unsigned int argNum, 273 STAFString_t *argValue, unsigned int *osRC); 274 275 276 /* XXX: This function may not be required. We may not actually alloc 277 new memory */ 278 279 /***********************************************************************/ 280 /* STAFCommandParseResultFreeMemory - Frees the memory returned by */ 281 /* the STAF Command Parse Result */ 282 /* APIs */ 283 /* */ 284 /* Accepts: (In) Pointer to a STAF Command Parse Result */ 285 /* (In) Pointer to the memory to free */ 286 /* (Out) Pointer to OS return code */ 287 /* */ 288 /* Returns: kSTAFOk, on success */ 289 /* other on error */ 290 /***********************************************************************/ 291 STAFRC_t STAFCommandParseResultFreeMemory( 292 STAFCommandParseResult_t result, char *ptr, unsigned int *osRC); 293 294 295 /***********************************************************************/ 296 /* STAFCommandParseDestruct - Destroys a STAF Command Parse Result */ 297 /* object */ 298 /* */ 299 /* Accepts: (In) Pointer to a STAF Command Parse Result */ 300 /* (Out) Pointer to OS return code */ 301 /* */ 302 /* Returns: kSTAFOk, on success */ 303 /* other on error */ 304 /***********************************************************************/ 305 STAFRC_t STAFCommandParseResultDestruct( 306 STAFCommandParseResult_t *pResult, unsigned int *osRC); 307 308 #ifdef __cplusplus 309 } 310 311 #include "STAFException.h" 312 313 // STAFCommandParseResult - This class is returned from a STAFCommandParser. 314 // It represents the results of parsing a string via 315 // the STAFCommandParser. 316 317 class STAFCommandParseResult 318 { 319 public: 320 321 // The return code from the parse 322 STAFRC_t rc; 323 324 // The description of the error when rc != 0 325 STAFString errorBuffer; 326 327 // Returns the number of times an option was specified 328 unsigned int optionTimes(const STAFString &optionName); 329 330 331 // Returns the value of a given instance of a given option. 332 // Returns an empty string if no such option or instance exists. 333 STAFString optionValue(const STAFString &optionName, 334 unsigned int number = 1); 335 336 337 // Returns the total number of options specified in the string 338 unsigned int numInstances(); 339 340 341 // Returns the name of the given option instance 342 STAFString instanceName(unsigned int number); 343 344 345 // Returns the value of the given option instance 346 STAFString instanceValue(unsigned int number); 347 348 349 // Returns the number of extra arguments 350 unsigned int numArgs(); 351 352 353 // Returns a given argument. Returns an empty string if no such argument 354 // exists. 355 STAFString arg(unsigned int number); 356 357 ~STAFCommandParseResult(); 358 getImpl()359 STAFCommandParseResult_t getImpl() { return fResultImpl; } 360 361 private: 362 363 // Disallow copy construction and assignment 364 STAFCommandParseResult(const STAFCommandParseResult &); 365 STAFCommandParseResult &operator=(const STAFCommandParseResult &); 366 367 friend class STAFCommandParser; 368 STAFCommandParseResult(STAFCommandParseResult_t theResult,STAFRC_t theRC,const STAFString & theErrorBuffer)369 STAFCommandParseResult(STAFCommandParseResult_t theResult, 370 STAFRC_t theRC, const STAFString &theErrorBuffer) 371 : rc(theRC), errorBuffer(theErrorBuffer), fResultImpl(theResult) 372 { /* Do Nothing */ } 373 374 STAFCommandParseResult_t fResultImpl; 375 }; 376 377 typedef STAFRefPtr<STAFCommandParseResult> STAFCommandParseResultPtr; 378 379 380 // STAFCommandParser - This class provides a parsing interface for STAF, in 381 // particular, STAF services 382 383 class STAFCommandParser 384 { 385 public: 386 387 // This enum is used to determine if an option may, may not, or must 388 // have a value associated with it 389 390 enum ValueRequirement { kValueNotAllowed = 0, kValueAllowed = 1, 391 kValueRequired = 2}; 392 393 // The constructor accepts an array of options and a count of those 394 // options, along with an indication of case sensitivity to option names 395 396 STAFCommandParser(unsigned int maxArgs = 0, bool caseSensitive = false); 397 398 399 void addOption(const STAFString &option, unsigned int numAllowed, 400 ValueRequirement valueReq); 401 402 403 void addOptionGroup(const STAFString &group, unsigned int minAllowed, 404 unsigned int maxAllowed); 405 406 void addOptionNeed(const STAFString &needers, const STAFString &needees); 407 408 // Parses a given string. Returns 0, if successful, > 0, otherwise. 409 // ErrorBuffer will be set if unsuccessful. 410 411 STAFCommandParseResultPtr parse(const STAFString &parseString); 412 413 ~STAFCommandParser(); 414 getImpl()415 STAFCommandParser_t getImpl() { return fParserImpl; } 416 417 private: 418 419 // Disallow copy construction and assignment 420 STAFCommandParser(const STAFCommandParser &); 421 STAFCommandParser &operator=(const STAFCommandParser &); 422 423 STAFCommandParser_t fParserImpl; 424 }; 425 426 427 // Now include inline definitions 428 429 #ifndef STAF_NATIVE_COMPILER 430 #include "STAFCommandParserInlImpl.cpp" 431 #endif 432 433 // End C++ language definitions 434 435 // End #ifdef __cplusplus 436 #endif 437 438 #endif 439