libcm is a C development framework with an emphasis on audio signal processing applications.
您最多选择25个主题 主题必须以字母或数字开头,可以包含连字符 (-),并且长度不得超过35个字符

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