libcm is a C development framework with an emphasis on audio signal processing applications.
Du kannst nicht mehr als 25 Themen auswählen Themen müssen mit entweder einem Buchstaben oder einer Ziffer beginnen. Sie können Bindestriche („-“) enthalten und bis zu 35 Zeichen lang sein.

cmPgmOpts.h 10KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215
  1. #ifndef cmPgmOpts_h
  2. #define cmPgmOpts_h
  3. //( { file_desc:"Command line argument description and parsing API." kw:[base]}
  4. //
  5. // Command line program option syntax:
  6. //
  7. //
  8. // '-'<charId>* <value>+ - a dash followed by one or more one character id's optionally followed by a parameter value.
  9. // '--'<wordId> <value>+ - a double dash followed by a word id optionally followed by a parameter value.
  10. //
  11. // A char id is a single character.
  12. // A word id is a string of characters with no intervening white space.
  13. //
  14. // Notes:
  15. // 1) There is no way to give multiple <values> without an intervening character or word id.
  16. // A <value> must therefore always be immediately preceded by an id.
  17. // 2) There must never be a space between the dash(es) and the characters forming the identifier.
  18. // 3) There must always be a space between the identifier and any subsequent <value>.
  19. // 4) See src/mas/src/main.c for a complete example.
  20. //
  21. // Terms:
  22. // Parameter - Description of the allowable types and constraints for a program option.
  23. // Argument - An instance of a parameter or the values associated with a parameter.
  24. //
  25. //)
  26. #ifdef __cplusplus
  27. extern "C" {
  28. #endif
  29. //(
  30. // cmPgmOpts Result Codes
  31. enum
  32. {
  33. kOkPoRC = cmOkRC,
  34. kSyntaxErrPoRC,
  35. kInvalidIdxPoRC,
  36. kParseFailPoRC,
  37. kNoReqArgPoRC,
  38. kDuplicateIdPoRC,
  39. kArgCntErrPoRC,
  40. kParmNotFoundPoRC,
  41. kInstNotFoundPoRC,
  42. kTypeErrPoRC
  43. };
  44. // cmPgmOpts parameter id's
  45. enum
  46. {
  47. kPrintHelpPoId,
  48. kVersionPoId,
  49. kPrintParmsPoId,
  50. kNoExecPoId,
  51. kBasePoId
  52. };
  53. typedef cmRC_t cmPoRC_t;
  54. typedef cmHandle_t cmPgmOptH_t;
  55. extern cmPgmOptH_t cmPgmOptNullHandle;
  56. // Initialize a program options parser.
  57. cmPoRC_t cmPgmOptInitialize(cmCtx_t* c, cmPgmOptH_t* hp, const cmChar_t* helpBegStr, const cmChar_t* helpEndStr );
  58. // Finalize a program options parser.
  59. cmPoRC_t cmPgmOptFinalize( cmPgmOptH_t* hp );
  60. // Return true if the program options parser was successfully initialized.
  61. bool cmPgmOptIsValid( cmPgmOptH_t h );
  62. // Flag used by the 'flags' arg. to cmPgmOptInstall().
  63. enum {
  64. kReqPoFl = 0x01, // this is a required parameter
  65. kHexPoFl = 0x02 // this integer must be given in hexidecimal or output an integer in hex.
  66. };
  67. // Define a parameter.
  68. //
  69. // unsigned numId, - Numeric id used to identify this parameter. The min. numId should be kPoBaseId.
  70. // const cmChar_t charId, - A character used to identify this parameter.
  71. // const cmChar_t* wordId, - A label used to identify this parameter.
  72. // unsigned flags, - kNoPoFlags | kReqPoFl (the type flags are automatically assigned)
  73. // unsigned enumId, - non-zero value used to group enumerated parameter values (ignored for non-enum types)
  74. // dfltVal - The default value for this parameter.
  75. // retValPtr- Optional pointer to a variable to receive the argument value for this parameter.
  76. // unsigned cnt, - count of times this parameter may repeated or 0 for an unlimited repetitions
  77. // const cmChar_t* helpStr - a textual description of this parameter
  78. //
  79. // Notes
  80. // 1) 'numId','charId', and 'wordId' must all be unique among all parameter definitions.
  81. // An error will be generated if they are not.
  82. // 2) For all parameter value types except the string type arguments are automatically parsed to the
  83. // defined type. To avoid automatic parsing simply define the type as a string (using cmPgmOptInstallStr()).
  84. // 3) All expected parameters must be defined prior to calling cmPgmOptParse().
  85. // 4) One call to cmPgmOptInstallEnum() is made for each possible enumeration value - where the 'enumId' gives the value.
  86. // A given set of associated enum values is grouped by giving a common 'numId'.
  87. // Include a master help string in one of the enumerated elements to give documentation
  88. // text for the entire set of values.
  89. // Example:
  90. // cmPgmOptInstallEnum(h,colorId,...,redId,...,"Red","Select a color");
  91. // cmPgmOptInstallEnum(h,colorId,...,greenId,..."Green",NULL);
  92. // cmPgmOptInstallEnum(h,colorId,...,blueId,...,"Blue",NULL);
  93. //
  94. // 5) The following id's are used for built-in actions and are therefore restricted from use by the client:
  95. // a. -h --help Print the program usage information.
  96. // b. -v --version Print the program version informatoin.
  97. // c. -p --parms Print the program parameter values.
  98. //
  99. // 6) If a retValPtr is specified then *retValPtr it is assigned 'dfltVal' as part of the
  100. // call to cmPgmOptInstXXX().
  101. //
  102. // 7) The default value of 'Flag' type parameters is always zero.
  103. // If the 'char' or 'word' id of the Flag parameter appears in the
  104. // actual argument list then the value of the argument is 'onValue'.
  105. // Unlike other parameters Flag parameters do not initialize *regValPtr.
  106. // If the retValPtr is given and the flag is set in the arg. list then
  107. // the retValPtr is set by bitwise assignment (i.e. *retValPtr |= dfltFlagValue).
  108. // This allows multiple Flag parameters to use the same retValPtr and
  109. // set independent bit fields in it.
  110. cmPoRC_t cmPgmOptInstallChar(cmPgmOptH_t h, unsigned numId, cmChar_t charId, const cmChar_t* worldId, unsigned flags, cmChar_t dfltVal, cmChar_t* retValPtr, unsigned cnt, const cmChar_t* helpStr );
  111. cmPoRC_t cmPgmOptInstallBool(cmPgmOptH_t h, unsigned numId, cmChar_t charId, const cmChar_t* worldId, unsigned flags, bool dfltVal, bool* retValPtr, unsigned cnt, const cmChar_t* helpStr );
  112. cmPoRC_t cmPgmOptInstallInt( cmPgmOptH_t h, unsigned numId, cmChar_t charId, const cmChar_t* worldId, unsigned flags, int dfltVal, int* retValPtr, unsigned cnt, const cmChar_t* helpStr );
  113. cmPoRC_t cmPgmOptInstallUInt(cmPgmOptH_t h, unsigned numId, cmChar_t charId, const cmChar_t* worldId, unsigned flags, unsigned dfltVal, unsigned* retValPtr, unsigned cnt, const cmChar_t* helpStr );
  114. cmPoRC_t cmPgmOptInstallDbl( cmPgmOptH_t h, unsigned numId, cmChar_t charId, const cmChar_t* worldId, unsigned flags, double dfltVal, double* retValPtr, unsigned cnt, const cmChar_t* helpStr );
  115. cmPoRC_t cmPgmOptInstallStr( cmPgmOptH_t h, unsigned numId, cmChar_t charId, const cmChar_t* worldId, unsigned flags, const cmChar_t* dfltVal, const cmChar_t** retValPtr, unsigned cnt, const cmChar_t* helpStr );
  116. cmPoRC_t cmPgmOptInstallEnum(cmPgmOptH_t h, unsigned numId, cmChar_t charId, const cmChar_t* worldId, unsigned flags, unsigned enumId, unsigned dfltVal, unsigned* retValPtr, unsigned cnt, const cmChar_t* helpStr, const cmChar_t* mstrHelpStr );
  117. cmPoRC_t cmPgmOptInstallFlag(cmPgmOptH_t h, unsigned numId, cmChar_t charId, const cmChar_t* worldId, unsigned flags, unsigned onValue, unsigned* retValPtr, unsigned cnt, const cmChar_t* helpStr );
  118. // Parse a set of command line arguments.
  119. //
  120. // 1) If only built-in parameters were specified then the NO check is done
  121. // to verify that required arguments were provided. However, if any non-built-in
  122. // arguments are provided then a check is performed to be sure that any
  123. // parameters specified with the kPoReqFl have associated argument values.
  124. //
  125. // 2) If a parameter was specified with a 'retValPtr' then *retValPtr is
  126. // set to the value of the last argument associated with the given parameter.
  127. // This means that 'retValPtr' is generally only useful when the
  128. // parameter instance count limit (the 'cnt' param to cmPgmOptInstallXXX())
  129. // was set to 1.
  130. //
  131. //
  132. cmPoRC_t cmPgmOptParse( cmPgmOptH_t h, unsigned argCnt, char* argArray[] );
  133. // Get the total count of arguments passed to cmPgmOptParse().
  134. unsigned cmPgmOptArgCount( cmPgmOptH_t h);
  135. // Get the numeric id associated with each argument.
  136. unsigned cmPgmOptNumId( cmPgmOptH_t h, unsigned argIdx );
  137. // Get the character id associated with this argument.
  138. unsigned cmPgmOptCharId( cmPgmOptH_t h, unsigned argIdx );
  139. // Get the word id associated with this argument.
  140. const cmChar_t* cmPgmOptWordId( cmPgmOptH_t h, unsigned argIdx );
  141. // Manually convert each argument string into the specified type.
  142. // These functions are useful if all of the parameters were defined using cmPgmOptInstallStr().
  143. // Use cmPgmOptRC() to check for errors.
  144. char cmPgmOptParseArgChar(cmPgmOptH_t h, unsigned argIdx );
  145. bool cmPgmOptParseArgBool(cmPgmOptH_t h, unsigned argIdx );
  146. int cmPgmOptParseArgInt( cmPgmOptH_t h, unsigned argIdx );
  147. unsigned cmPgmOptParseArgUInt(cmPgmOptH_t h, unsigned argIdx );
  148. double cmPgmOptParseArgDbl( cmPgmOptH_t h, unsigned argIdx );
  149. const char* cmPgmOptParseArgStr( cmPgmOptH_t h, unsigned argIdx );
  150. // Get the count of arg's for a given parameter.
  151. unsigned cmPgmOptParmArgCount( cmPgmOptH_t h, unsigned numId );
  152. // Get the value associated with each parsed argument.
  153. // If no argument was given for the requested parameter
  154. // (cmPgmOptParmArgCount(numId)==0) and 'instIdx' == 0 then the default value is returned.
  155. // Use cmPgOptRC() to check for errors.
  156. //
  157. // The parameter identified by numId must has been defined by an earlier call to
  158. // cmPgmOptInstallChar() or this function
  159. char cmPgmOptArgChar( cmPgmOptH_t h, unsigned numId, unsigned instIdx );
  160. // No matter the type of the parameter it will be converted to a bool.
  161. bool cmPgmOptArgBool( cmPgmOptH_t h, unsigned numId, unsigned instIdx );
  162. // All types, except strings, are converted to type int. Doubles are rounded.
  163. int cmPgmOptArgInt( cmPgmOptH_t h, unsigned numId, unsigned instIdx );
  164. // All types, except strings, are converted to type unsigned. Doubles are rounded.
  165. unsigned cmPgmOptArgUInt( cmPgmOptH_t h, unsigned numId, unsigned instIdx );
  166. // All types except strings, are converted to double.
  167. double cmPgmOptArgDbl( cmPgmOptH_t h, unsigned numId, unsigned instIdx );
  168. // If the parameter is not defined as a string then the arg. string value us returned.
  169. const char* cmPgmOptArgStr( cmPgmOptH_t h, unsigned numId, unsigned instIdx );
  170. // Get and set the current result code.
  171. cmPoRC_t cmPgmOptRC( cmPgmOptH_t h, cmPoRC_t rc );
  172. // Returns 'false' if only built-in options were selected otherwise returns true.
  173. bool cmPgmOptHandleBuiltInActions( cmPgmOptH_t h, cmRpt_t* rpt );
  174. void cmPgmOptPrintHelp( cmPgmOptH_t h, cmRpt_t* rpt );
  175. void cmPgmOptPrintVersion( cmPgmOptH_t h, cmRpt_t* rpt );
  176. void cmPgmOptPrintParms( cmPgmOptH_t h, cmRpt_t* rpt );
  177. //)
  178. #ifdef __cplusplus
  179. }
  180. #endif
  181. #endif