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 8.7KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191
  1. #ifndef cmPgmOpts_h
  2. #define cmPgmOpts_h
  3. //{
  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. kNoPoFlags = 0x000,
  65. kReqPoFl = 0x001, // this is a required parameter
  66. kBoolPoFl = 0x002, // this parameter takes a value
  67. kCharPoFl = 0x004, // parm. value is a character
  68. kIntPoFl = 0x008, // parm. value is a decimal int
  69. kUIntPoFl = 0x010, // parm. value is a decimal unsigned int
  70. kHexPoFl = 0x020, // parm. value is a hex. unsigned int
  71. kDblPoFl = 0x040, // parm. value is a decimal double
  72. kStrPoFl = 0x080, // parm. value is a string (default)
  73. kEnumPoFl = 0x100, // parm. valus is a enum type (automatically set by a non-zero enumId)
  74. kTypeMaskPoFl = 0x1f6
  75. };
  76. // Define a parameter.
  77. //
  78. // unsigned numId, - numeric id used to identify this parameter
  79. // const cmChar_t charId, - a character used to identify this parameter
  80. // const cmChar_t* wordId, - a label used to identify this parameter
  81. // unsigned flags, - kNoPoFlags | kReqPoFl (the type flags are automatically assigned)
  82. // unsigned enumId, - non-zero value used to group enumerated parameter values (ignored for non-enum types)
  83. // unsigned cnt, - count of times this parameter may repeated or 0 for an unlimited repetitions
  84. // const cmChar_t* helpStr - a textual description of this parameter
  85. //
  86. // Notes
  87. // 1) 'numId','charId', and 'wordId' must all be unique among all parameter definitions.
  88. // 2) If no parameter value type flag is given then the type is assumed to be of type bool.
  89. // 3) For all parameter value types except the string type arguments are automatically parsed to the
  90. // defined type. To avoid automatic parsing simply define the type as a string (using cmPgmOptInstallStr()).
  91. // 4) All expected parameters must be defined prior to calling cmPgmOptParse().
  92. // 5) One call to cmPgmOPtInstallEnum() is made for each possible enumeration value - where the 'enumId' gives the value.
  93. // A given set of associated enum values is grouped by giving a common 'numId'.
  94. // Example:
  95. // cmPgmOptInstallEnum(h,colorId,...,redId,...);
  96. // cmPgmOptInstallEnum(h,colorId,...,greenId,...);
  97. // cmPgmOptInstallEnum(h,colorId,...,blueId,...);
  98. //
  99. // 6) The following id's are used for built-in actions and are therefore restricted from use by the client:
  100. // a. -h --help Print the program usage information.
  101. // b. -v --version Print the program version informatoin.
  102. // c. -p --parms Print the program parameter values.
  103. //
  104. 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 );
  105. 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 );
  106. 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 );
  107. 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 );
  108. 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 );
  109. 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 );
  110. 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 );
  111. // Parse a set of command line arguments.
  112. cmPoRC_t cmPgmOptParse( cmPgmOptH_t h, unsigned argCnt, char* argArray[] );
  113. // Get the total count of arguments passed to cmPgmOptParse().
  114. unsigned cmPgmOptArgCount( cmPgmOptH_t h);
  115. // Get the numeric id associated with each argument.
  116. unsigned cmPgmOptNumId( cmPgmOptH_t h, unsigned argIdx );
  117. // Manually convert each argument string into the specified type.
  118. // These functions are useful if all of the parameters were defined using cmPgmOptInstallStr().
  119. // Use cmPgmOptRC() to check for errors.
  120. char cmPgmOptParseArgChar(cmPgmOptH_t h, unsigned argIdx );
  121. bool cmPgmOptParseArgBool(cmPgmOptH_t h, unsigned argIdx );
  122. int cmPgmOptParseArgInt( cmPgmOptH_t h, unsigned argIdx );
  123. unsigned cmPgmOptParseArgUInt(cmPgmOptH_t h, unsigned argIdx );
  124. double cmPgmOptParseArgDbl( cmPgmOptH_t h, unsigned argIdx );
  125. const char* cmPgmOptParseArgStr( cmPgmOptH_t h, unsigned argIdx );
  126. // Get the count of arg's for a given parameter.
  127. unsigned cmPgmOptParmArgCount( cmPgmOptH_t h, unsigned numId );
  128. // Get the value associated with each parsed argument.
  129. // If no argument was given for the requested parameter
  130. // (cmPgmOptParmArgCount(numId)==0) and 'instIdx' == 0 then the default value is returned.
  131. // Use cmPgOptRC() to check for errors.
  132. //
  133. // The parameter identified by numId must has been defined by an earlier call to
  134. // cmPgmOptInstallChar() or this function
  135. char cmPgmOptArgChar( cmPgmOptH_t h, unsigned numId, unsigned instIdx );
  136. // No matter the type of the parameter it will be converted to a bool.
  137. bool cmPgmOptArgBool( cmPgmOptH_t h, unsigned numId, unsigned instIdx );
  138. // All types, except strings, are converted to type int. Doubles are rounded.
  139. int cmPgmOptArgInt( cmPgmOptH_t h, unsigned numId, unsigned instIdx );
  140. // All types, except strings, are converted to type unsigned. Doubles are rounded.
  141. unsigned cmPgmOptArgUInt( cmPgmOptH_t h, unsigned numId, unsigned instIdx );
  142. // All types except strings, are converted to double.
  143. double cmPgmOptArgDbl( cmPgmOptH_t h, unsigned numId, unsigned instIdx );
  144. // If the parameter is not defined as a string then the arg. string value us returned.
  145. const char* cmPgmOptArgStr( cmPgmOptH_t h, unsigned numId, unsigned instIdx );
  146. // Get and set the current result code.
  147. cmPoRC_t cmPgmOptRC( cmPgmOptH_t h, cmPoRC_t rc );
  148. // Returns 'true' only if non- built-in options were selected
  149. bool cmPgmOptHandleBuiltInActions( cmPgmOptH_t h, cmRpt_t* rpt );
  150. void cmPgmOptPrintHelp( cmPgmOptH_t h, cmRpt_t* rpt );
  151. void cmPgmOptPrintVersion( cmPgmOptH_t h, cmRpt_t* rpt );
  152. void cmPgmOptPrintParms( cmPgmOptH_t h, cmRpt_t* rpt );
  153. //)
  154. //}
  155. #ifdef __cplusplus
  156. }
  157. #endif
  158. #endif