ucmd.h

00001 #ifndef UCMD_H
00002 #define UCMD_H
00003 
00004 #include <stdarg.h>
00005 #include <stddef.h>
00006 
00007 /* Sets the size of the command buffer when using
00008    the command-line application framework. All
00009    entered commands must have a size equal to or
00010    less than this buffer's size. */
00011 #ifndef ucCmdLineApp_CMD_STR_SIZE
00012 #define ucCmdLineApp_CMD_STR_SIZE 200
00013 #endif
00014 
00015 /* Sets the size of the command response buffer.
00016    All response strings must have a size equal to
00017    or less than the size of this buffer to avoid
00018    truncation. */
00019 #ifndef ucCmdLine_RESPONSE_SIZE
00020 #define ucCmdLine_RESPONSE_SIZE 200
00021 #endif
00022 
00023 /* Sets the number of available command options.
00024    The number of created command options must be
00025    equal to or less than this number. */
00026 #ifndef ucCmdLineOpt_COUNT
00027 #define ucCmdLineOpt_COUNT 10
00028 #endif
00029 
00030 /* Sets the number of available switch options.
00031    The number of created switch options must be
00032    equal to or less than this number. */
00033 #ifndef ucSwitchOpt_COUNT
00034 #define ucSwitchOpt_COUNT 50
00035 #endif
00036 
00037 /* Sets the number of available argument options.
00038    This is the total number of options available
00039    to commands and switches, combined. */
00040 #ifndef ucArgOpt_COUNT
00041 #define ucArgOpt_COUNT 50
00042 #endif
00043 
00044 /* Sets the maximum expected length of a single
00045    token in a command line. */
00046 #ifndef ucTok_LENGTH_MAX
00047 #define ucTok_LENGTH_MAX ucCmdLineApp_CMD_STR_SIZE
00048 #endif
00049 
00050 #ifndef ucTok_BOOLEAN_TRUE
00051 #define ucTok_BOOLEAN_TRUE "1", "on", "yes", "true"
00052 #endif
00053 
00054 #ifndef ucTok_BOOLEAN_FALSE
00055 #define ucTok_BOOLEAN_FALSE "0", "off", "no", "false"
00056 #endif
00057 
00058 /* Sets the numeric type of numeric argument
00059    options. */
00060 #ifndef ucArgOpt_NUMERIC_TYPE
00061 #define ucArgOpt_NUMERIC_TYPE double
00062 #endif
00063 
00064 /* Include this def when using the library with another
00065    program on Windows.
00066    Exported functions will be decorated with dllimport
00067    to make them available to external programs. */
00068 #ifdef uc_DECLSPEC_DLLIMPORT
00069 #define uc_EXPORTED uc_EXTERN_C __declspec(dllimport)
00070 #endif
00071 
00072 /* Include this def when compiling this program on
00073    Windows.
00074    Exported functions will be decorated with dllexport
00075    to make them available to external programs. */
00076 #ifdef uc_DECLSPEC_DLLEXPORT
00077 #define uc_EXPORTED uc_EXTERN_C __declspec(dllexport)
00078 #endif
00079 
00080 /* Prepend extern "C" if we're in a C++
00081    compiler. */
00082 #ifdef __cplusplus
00083 #define uc_EXTERN_C extern "C"
00084 #else
00085 #define uc_EXTERN_C
00086 #endif
00087 
00088 /* Default to setting uc_EXPORTED to the result
00089    of our extern "C" check. */
00090 #ifndef uc_EXPORTED
00091 #define uc_EXPORTED uc_EXTERN_C
00092 #endif
00093 
00094 /* Define NULL, if it hasn't been defined. */
00095 #ifndef NULL
00096 #define NULL ((void*)0)
00097 #endif
00098 
00099 /* 
00100  * Summary:
00101  *   Definition for the type returned
00102  *   by functions that use an error code. 
00103  */
00104 typedef int ucErr;
00105 
00106 /* 
00107  * Summary:
00108  *   Defines the value that represents no error.
00109  */
00110 #define ucErr_NONE 0
00111 
00112 /*
00113  * Summary:
00114  *   Boolean type definition. This definition is used
00115  *   to increase the readability of the source by replacing
00116  *   integer representations of boolean values with the
00117  *   more familiar "true" and "false" values.
00118  */
00119 typedef enum ucBool {
00120     ucBool_FALSE = 0,
00121     ucBool_TRUE = !ucBool_FALSE
00122 } ucBool;
00123 
00124 /*
00125  * Summary:
00126  *   Base structure for tokenized values in a command.
00127  */
00128 typedef const char ucTok;
00129 
00130 /*
00131  * Summary:
00132  *   Gets the length of the token.
00133  * Returns:
00134  *   The number of characters in the token.
00135  */
00136 uc_EXPORTED int ucTok_get_length(ucTok*);
00137 
00138 /*
00139  * Summary:
00140  *   Determines whether or not the given token equals the value.
00141  * Parameters:
00142  *   value: The value against which the token is checked for equality.
00143  * Returns:
00144  *   ucBool_TRUE if the token value equals the given value. Otherwise, ucBool_FALSE.
00145  */
00146 uc_EXPORTED ucBool ucTok_equals(ucTok*, const char *value);
00147 
00148 /*
00149  * Summary:
00150  *   Determines whether or not the given token is considered numeric.
00151  * Returns:
00152  *   ucBool_TRUE if the token is considered numeric. Otherwise, ucBool_FALSE.
00153  */
00154 uc_EXPORTED ucBool ucTok_is_numeric(ucTok*);
00155 uc_EXPORTED ucBool ucTok_try_parse_numeric(ucTok*, double *value);
00156 uc_EXPORTED double ucTok_parse_numeric(ucTok*);
00157 uc_EXPORTED ucBool ucTok_is_boolean(ucTok*);
00158 uc_EXPORTED ucBool ucTok_try_parse_boolean(ucTok*, ucBool *value);
00159 uc_EXPORTED ucBool ucTok_parse_boolean(ucTok*);
00160 
00161 /*
00162  * Summary:
00163  *   Determines whether or not the given token is considered a switch.
00164  * Returns:
00165  *   ucBool_TRUE if the token is a switch. Otherwise, ucBool_FALSE.
00166  */
00167 uc_EXPORTED ucBool ucTok_is_switch(ucTok*);
00168 
00169 /*
00170  * Summary:
00171  *   Gets the next token in the list.
00172  * Returns:
00173  *   A pointer to the token that comes next in the list, or NULL
00174  *   if no further tokens exist.
00175  */
00176 uc_EXPORTED ucTok *ucTok_get_next(ucTok*);
00177 
00178 /*
00179  * Summary:
00180  *   Counts the number of tokens in the linked list.
00181  * Returns:
00182  *   The number of tokens in the list.
00183  */
00184 uc_EXPORTED int ucTok_count(ucTok*);
00185 
00186 /*
00187  * Summary:
00188  *   Gets the value of the token.
00189  * Returns:
00190  *   The string value of the token.
00191  */
00192 uc_EXPORTED const char *ucTok_get_value(ucTok*);
00193 
00194 /*
00195  * Summary:
00196  *   An argument token. This type is a child of the
00197  *   base token type. All functions that take an 
00198  *   instance of the base type can be used with an 
00199  *   instance of this type.
00200  */
00201 typedef const char ucArgTok;
00202 
00203 /*
00204  * Summary:
00205  *   Gets the next argument after the given argument.
00206  * Returns:
00207  *   The next argument in the list.
00208  */
00209 uc_EXPORTED ucArgTok *ucArgTok_get_next(ucArgTok*);
00210 
00211 /*
00212  * Summary:
00213  *   Counts the number of arguments in the linked list.
00214  * Returns:
00215  *   The number of arguments in the list.
00216  */
00217 uc_EXPORTED int ucArgTok_count(ucArgTok*);
00218 
00219 /*
00220  * Summary:
00221  *   Finds the argument in the list with the specified value.
00222  * Parameters:
00223  *   arg_value: The value of the argument to find.
00224  * Returns:
00225  *   The argument with the specified value, or NULL if none exists.
00226  */
00227 uc_EXPORTED ucArgTok *ucArgTok_find(ucArgTok*, const char *arg_value);
00228 
00229 /*
00230  * Summary:
00231  *   Gets a value indicating whether or not the value exists in
00232  *   the argument list.
00233  * Parameters:
00234  *   arg_value: The value of the argument to be found.
00235  * Returns:
00236  *   ucBool_TRUE if an argument token with the given value is found.
00237  *   Otherwise, ucBool_FALSE.
00238  */
00239 uc_EXPORTED ucBool ucArgTok_contains(ucArgTok*, const char *arg_value);
00240 
00241 /*
00242  * Summary:
00243  *   Type definition for tokens (i.e. switch and command tokens)
00244  *   that contain arguments. This type is a child of the base
00245  *   token type. All functions that take an instance of the base
00246  *   type can be used with an instance of this type.
00247  */
00248 typedef const char ucArgTokOwner;
00249 
00250 /*
00251  * Summary
00252  *   Gets the first argument that belongs to the given owner.
00253  * Returns:
00254  *   The first argument that belongs to the owner, or NULL if
00255  *   no arguments exist.
00256  */
00257 uc_EXPORTED ucArgTok *ucArgTokOwner_get_arg(ucArgTokOwner*);
00258 
00259 /*
00260  * Summary:
00261  *   A switch token. This type is a child of the
00262  *   base token type. All functions that take an 
00263  *   instance of the base type can be used with an 
00264  *   instance of this type.
00265  */
00266 typedef const char ucSwitchTok;
00267 
00268 /*
00269  * Summary:
00270  *   Gets the next switch token after the given token.
00271  * Returns:
00272  *   The next switch token after the given token.
00273  */
00274 uc_EXPORTED ucSwitchTok *ucSwitchTok_get_next(ucSwitchTok*);
00275 
00276 /*
00277  * Summary:
00278  *   Counts the number of switches in the linked list.
00279  * Returns:
00280  *   The number of switches in the list.
00281  */
00282 uc_EXPORTED int ucSwitchTok_count(ucSwitchTok*);
00283 
00284 /*
00285  * Summary:
00286  *   Finds the switch with the specified value.
00287  * Parameters:
00288  *   switch_value: The value of the switch to be found.
00289  * Returns:
00290  *   The switch with the specified value, or NULL if none exist.
00291  */
00292 uc_EXPORTED ucSwitchTok *ucSwitchTok_find(ucSwitchTok*, const char *switch_value);
00293 
00294 /*
00295  * Summary:
00296  *   Gets a value indicating whether or not a value exists in the switch list.
00297  * Parameters:
00298  *   switch_value: The value of the switch to be found.
00299  * Returns:
00300  *   ucBool_TRUE if a switch with the given value was found in the list. Otherwise,
00301  *   ucBool_FALSE.
00302  */
00303 uc_EXPORTED ucBool ucSwitchTok_contains(ucSwitchTok*, const char *switch_value);
00304 
00305 /*
00306  * Summary:
00307  *   Gets the first argument token of the switch.
00308  * Returns:
00309  *   A pointer to the first argument of the switch, or NULL
00310  *   if no arguments exist.
00311  */
00312 uc_EXPORTED ucArgTok *ucSwitchTok_get_arg(ucSwitchTok*);
00313 
00314 /*
00315  * Summary:
00316  *   Type definition for a command token. This is
00317  *   the first token (the command part) in a list
00318  *   of tokens. This type is a child of the base
00319  *   token type. All functions that take an instance
00320  *   of the base type can be used with an instance
00321  *   of this type.
00322  */
00323 typedef const char ucCmdTok;
00324 
00325 /*
00326  * Summary:
00327  *   Gets the first argument of the command.
00328  * Returns:
00329  *   A pointer to the first argument token, or NULL if no arguments
00330  *   exist for the command.
00331  */
00332 uc_EXPORTED ucArgTok *ucCmdTok_get_arg(ucCmdTok*);
00333 
00334 /*
00335  * Summary:
00336  *   Gets the first switch of the command.
00337  * Returns:
00338  *   A pointer to the first switch token of the command, or NULL
00339  *   if no switches exist.
00340  */
00341 uc_EXPORTED ucSwitchTok *ucCmdTok_get_switch(ucCmdTok*);
00342 
00343 /*
00344  * Summary:
00345  *   A group of tokens that represent the first
00346  *   of each token type in a command.
00347  */
00348 typedef struct ucCmdLineToks {
00349 
00350     /*
00351      * Summary:
00352      *   The command token of the command. This token's
00353      *   value is the invoked command.
00354      */
00355     ucCmdTok *cmd_tok;
00356 
00357     /*
00358      * Summary:
00359      *   The command's first argument token, or
00360      *   NULL if no arguments exist.
00361      */
00362     ucArgTok *arg_tok;
00363 
00364     /*
00365      * Summary:
00366      *   The command's first switch token, or
00367      *   NULL if no switches exist.
00368      */
00369     ucSwitchTok *switch_tok;
00370 
00371 } ucCmdLineToks;
00372 
00373 /*
00374  * Summary:
00375  *   Gets the command token of the command. This token's
00376  *   value is the invoked command.
00377  * Returns:
00378  *   A pointer to the command token.
00379  */
00380 uc_EXPORTED ucCmdTok *ucCmdLineToks_get_cmd_tok(ucCmdLineToks*);
00381 
00382 /*
00383  * Summary:
00384  *   The command's first argument token, or
00385  *   NULL if no arguments exist.
00386  * Returns:
00387  *   A pointer to the argument token, or NULL if no argument
00388  *   tokens exist.
00389  */
00390 uc_EXPORTED ucArgTok *ucCmdLineToks_get_arg_tok(ucCmdLineToks*);
00391 
00392 /*
00393  * Summary:
00394  *   The command's first switch token, or
00395  *   NULL if no switches exist.
00396  * Returns:
00397  *   A pointer to the switch token, or NULL if no switch tokens exist.
00398  */
00399 uc_EXPORTED ucSwitchTok *ucCmdLineToks_get_switch_tok(ucCmdLineToks*);
00400 
00401 /*
00402  * Summary:
00403  *   A command structure. This structure consists
00404  *   of the parsed command and the ability to respond.
00405  */
00406 typedef struct ucCmdLine ucCmdLine;
00407 
00408 /*
00409  * Summary:
00410  *   The type of function used by a command structure
00411  *   to transmit responses.
00412  * Parameters:
00413  *   response: The string to be transmitted.
00414  *   state: A stateful object.
00415  */
00416 typedef void (ucCmdLine_TransmitFunc)(const char *response, void *state);
00417 
00418 /*
00419  * Summary:
00420  *   The type of function used by a command structure
00421  *   to determine whether or not the command is canceled.
00422  * Parameters:
00423  *   state: A stateful object.
00424  * Returns:
00425  *   ucBool_TRUE if the command has been canceled. Otherwise, ucBool_FALSE.
00426  */
00427 typedef ucBool (ucCmdLine_IsCanceledFunc)(void *state);
00428 
00429 /*
00430  * Summary:
00431  *   The type of the function that is invoked when an
00432  *   invalid command is encountered. An invalid command
00433  *   is one that does not exist in the list of command
00434  *   options.
00435  * Parameters:
00436  *   invalid_command: The invalid command string that was encountered.
00437  *   state: The stateful object for this callback.
00438  * Returns:
00439  *   ucBool_TRUE if the invalid command was handeled. Otherwise, ucBool_FALSE.
00440  */
00441 typedef ucBool (ucCmdLine_HandleInvalidCommandFunc)(const char *invalid_command, void *state);
00442 
00443 /*
00444  * Summary:
00445  *   Gets the command token from the command structure.
00446  * Returns:
00447  *   A pointer to the command token of the structure.
00448  */
00449 uc_EXPORTED ucCmdTok *ucCmdLine_get_cmd_tok(ucCmdLine*);
00450 
00451 /*
00452  * Summary:
00453  *   Sets the command token for the structure.
00454  * Parameters:
00455  *   value: The command token.
00456  */
00457 uc_EXPORTED void ucCmdLine_set_cmd_tok(ucCmdLine*, ucCmdTok *value);
00458 
00459 /*
00460  * Summary:
00461  *   Fills the buffer with the specified tokens of the command structure.
00462  * Parameters:
00463  *   buffer: A pointer to the token structure whose properties will be set per the command.
00464  * Returns:
00465  *   A pointer to the buffer.
00466  */
00467 uc_EXPORTED ucCmdLineToks *ucCmdLine_get_cmd_toks(ucCmdLine*, ucCmdLineToks *buffer);
00468 
00469 /*
00470  * Summary:
00471  *   Sets the function used by the command structure to transmit responses.
00472  * Parameters:
00473  *   value: A pointer to the function used to transmit responses.
00474  */
00475 uc_EXPORTED void ucCmdLine_set_transmit(ucCmdLine*, ucCmdLine_TransmitFunc *value);
00476 
00477 /*
00478  * Summary:
00479  *   Gets the function used by the command structure to transmit responses.
00480  * Returns:
00481  *   A pointer to the function used by the structure to transmit responses.
00482  */
00483 uc_EXPORTED ucCmdLine_TransmitFunc *ucCmdLine_get_transmit(ucCmdLine*);
00484 
00485 /*
00486  * Summary:
00487  *   Gets the stateful object passed to the command's transmit function.
00488  * Returns:
00489  *   A pointer to the stateful object passed to the command's transmit function.
00490  */
00491 uc_EXPORTED void *ucCmdLine_get_transmit_state(ucCmdLine*);
00492 
00493 /*
00494  * Summary:
00495  *   Sets the stateful object passed to the command's transmit function.
00496  * Parameters:
00497  *   value: A pointer to the stateful object that is passed to the command's transmit function.
00498  */
00499 uc_EXPORTED void ucCmdLine_set_transmit_state(ucCmdLine*, void *value);
00500 
00501 /*
00502  * Summary:
00503  *   Determines whether or not the command has been canceled.
00504  * Returns:
00505  *   ucBool_TRUE if the command has been canceled. Otherwise, ucBool_FALSE.
00506  */
00507 uc_EXPORTED ucBool ucCmdLine_is_canceled(ucCmdLine*);
00508 
00509 /*
00510  * Summary:
00511  *   Sets the function used by the command structure to check for cancellation.
00512  * Parameters:
00513  *   value: A pointer to the function used to check for cancellation.
00514  */
00515 uc_EXPORTED void ucCmdLine_set_is_canceled(ucCmdLine*, ucCmdLine_IsCanceledFunc *value);
00516 
00517 /*
00518  * Summary:
00519  *   Gets the function used by the command structure to check for cancellation.
00520  * Returns:
00521  *   A pointer to the function used to check for cancellation.
00522  */
00523 uc_EXPORTED ucCmdLine_IsCanceledFunc *ucCmdLine_get_is_canceled(ucCmdLine*);
00524 
00525 /*
00526  * Summary:
00527  *   Gets the stateful object passed to the command's cancellation function.
00528  * Returns:
00529  *   A pointer to the stateful object passed to the command's cancellation function.
00530  */
00531 uc_EXPORTED void *ucCmdLine_get_is_canceled_state(ucCmdLine*);
00532 
00533 /*
00534  * Summary:
00535  *   Sets the stateful object passed to the command's cancellation function.
00536  * Parameters:
00537  *   value: The stateful object passed to the command's cancellation function.
00538  */
00539 uc_EXPORTED void ucCmdLine_set_is_canceled_state(ucCmdLine*, void *value);
00540 
00541 uc_EXPORTED void ucCmdLine_set_handle_invalid_command(ucCmdLine*, ucCmdLine_HandleInvalidCommandFunc *value);
00542 
00543 uc_EXPORTED ucCmdLine_HandleInvalidCommandFunc *ucCmdLine_get_handle_invalid_command(ucCmdLine*);
00544 
00545 uc_EXPORTED void ucCmdLine_set_handle_invalid_command_state(ucCmdLine*, void *value);
00546 
00547 uc_EXPORTED void *ucCmdLine_get_handle_invalid_command_state(ucCmdLine*);
00548 
00549 uc_EXPORTED size_t ucCmdLine_get_response_size_max(ucCmdLine*);
00550 
00551 /*
00552  * Summary:
00553  *   Gets a static, default instance of the command structure.
00554  * Returns:
00555  *   The static, default instance of the command structure.
00556  */
00557 uc_EXPORTED ucCmdLine *ucCmdLine_get_instance(void);
00558 
00559 /*
00560  * Summary:
00561  *   Formats the command's response using the given parameters.
00562  * Parameters:
00563  *   format: The format string.
00564  *   ...: Parameters to the format string.
00565  * Returns:
00566  *   The formatted string.
00567  */
00568 uc_EXPORTED const char *ucCmdLine_format_response(ucCmdLine*, const char *format, ...);
00569 
00570 /*
00571  * Summary:
00572  *   Formats the command's response using the given parameters.
00573  * Parameters:
00574  *   format: The format string.
00575  *   arg_list: A variable length argument list with parameters to the format string.
00576  * Returns:
00577  *   The formatted string.
00578  */
00579 uc_EXPORTED const char *ucCmdLine_format_response_va(ucCmdLine*, const char *format, va_list arg_list);
00580 
00581 /*
00582  * Summary
00583  *   Responds to the command.
00584  * Parameters:
00585  *   response: The response string.
00586  */
00587 uc_EXPORTED void ucCmdLine_respond(ucCmdLine*, const char *response);
00588 
00589 /*
00590  * Summary:
00591  *   Sets whether or not the command structure is quiet, meaning no response
00592  *   strings will be sent.
00593  * Parameters:
00594  *   value: A boolean true value if the command structure should not send
00595  *          any response strings. Otherwise, false.
00596  */
00597 uc_EXPORTED void ucCmdLine_set_is_quiet(ucCmdLine*, ucBool value);
00598 
00599 /*
00600  * Summary:
00601  *   Gets a flag that indicates whether or not the command structure is quiet,
00602  *   meaning no response strings are sent.
00603  * Returns:
00604  *   A boolean true value if the command structure is not sending any
00605  *   response strings. Otherwise, false.
00606  */
00607 uc_EXPORTED ucBool ucCmdLine_get_is_quiet(ucCmdLine*);
00608 
00609 uc_EXPORTED void            ucCmdLine_acknowledge_command(ucCmdLine*);
00610 uc_EXPORTED const char*     ucCmdLine_get_command_acknowledgment(ucCmdLine*);
00611 uc_EXPORTED const char*     ucCmdLine_get_response_terminator(ucCmdLine*);
00612 uc_EXPORTED void            ucCmdLine_set_response_terminator(ucCmdLine*, const char *value);
00613 uc_EXPORTED void            ucCmdLine_set_command_acknowledgment(ucCmdLine*, const char *value);
00614 uc_EXPORTED void            ucCmdLine_terminate_response(ucCmdLine*);
00615 
00616 /*
00617  * Summary:
00618  *   Base type for command, argument, and switch options.
00619  */
00620 typedef struct ucOpt ucOpt;
00621 
00622 /*
00623  * Summary:
00624  *   Gets the name of the option.
00625  * Returns:
00626  *   The name of the option.
00627  */
00628 uc_EXPORTED const char* ucOpt_get_name(ucOpt*);
00629 
00630 /*
00631  * Summary:
00632  *   Gets the description of the option.
00633  * Returns:
00634  *   The description of the option.
00635  */
00636 uc_EXPORTED const char *ucOpt_get_desc(ucOpt*);
00637 
00638 /*
00639  * Summary:
00640  *   Gets a flag that indicates whether or not the option
00641  *   is required.
00642  * Returns:
00643  *   ucBool_TRUE if the option is required. Otherwise, ucBool_FALSE.
00644  */
00645 uc_EXPORTED ucBool ucOpt_is_required(ucOpt*);
00646 
00647 /*
00648  * Summary:
00649  *   Uses the provided command structure to send help information
00650  *   for this option.
00651  * Parameters:
00652  *   cmd: A pointer to the command structure used to respond
00653  *        with the help information.
00654  *   prefix: A string used to prefix the help information.
00655  */
00656 uc_EXPORTED void ucOpt_send_help(ucOpt*, ucCmdLine *cmd, const char *prefix);
00657 
00658 /*
00659  * Summary:
00660  *   An argument option. This type is a child
00661  *   of the base option type.
00662  */
00663 typedef struct ucArgOpt ucArgOpt;
00664 
00665 /*
00666  * Summary:
00667  *   Gets the minimum allowed token count of the argument option.
00668  * Returns:
00669  *   The minimum number of argument tokens allowed for this option.
00670  */
00671 uc_EXPORTED int ucArgOpt_get_min_tok_count(ucArgOpt*);
00672 
00673 /*
00674  * Summary:
00675  *   Gets the maximum allowed token count of the argument option.
00676  * Returns:
00677  *   The maximum number of argument tokens allowed for this option.
00678  */
00679 uc_EXPORTED int ucArgOpt_get_max_tok_count(ucArgOpt*);
00680 
00681 uc_EXPORTED ucBool ucArgOpt_is_boolean(ucArgOpt*);
00682 
00683 /*
00684  * Summary:
00685  *   Gets a flag that indicates whether or not this argument option
00686  *   is numeric.
00687  * Returns:
00688  *   ucBool_TRUE if the argument is numeric. Otherwise, ucBool_FALSE.
00689  */
00690 uc_EXPORTED ucBool ucArgOpt_is_numeric(ucArgOpt*);
00691 
00692 /*
00693  * Summary:
00694  *   Gets the minimum value if this argument option is numeric.
00695  * Returns:
00696  *   The minimum numeric value of the argument.
00697  */
00698 uc_EXPORTED ucArgOpt_NUMERIC_TYPE ucArgOpt_get_numeric_min(ucArgOpt*);
00699 
00700 /*
00701  * Summary:
00702  *   Gets the maximum value if this argument is numeric.
00703  * Returns:
00704  *   The maximum numeric value of the argument.
00705  */
00706 uc_EXPORTED ucArgOpt_NUMERIC_TYPE ucArgOpt_get_numeric_max(ucArgOpt*);
00707 
00708 /*
00709  * Summary:
00710  *   Creates a new argument option.
00711  * Parameters:
00712  *   name: The name of the option.
00713  *   desc: The description of the option.
00714  *   next: The next option in the chain that the created option precedes,
00715  *         or NULL if the created option is the last.
00716  * Returns:
00717  *   A pointer to the newly created argument option.
00718  */
00719 uc_EXPORTED ucArgOpt *ucArgOpt_create(const char *name, const char *desc, ucArgOpt *next);
00720 
00721 /*
00722  * Summary:
00723  *   Creates a new argument option that allows multiple tokens.
00724  * Parameters:
00725  *   name: The name of the option.
00726  *   desc: The description of the option.
00727  *   min_tok_count: The minimum number of argument tokens allowed for this option.
00728  *   max_tok_count: The maximum number of argument tokens allowed for this option.
00729  * Returns:
00730  *   A pointer to the newly created argument option.
00731  */
00732 uc_EXPORTED ucArgOpt *ucArgOpt_create_multiple(const char *name, const char *desc, int min_tok_count, int max_tok_count);
00733 
00734 /*
00735  * Summary:
00736  *   Creates a new, required argument option.
00737  * Parameters:
00738  *   name: The name of the option.
00739  *   desc: The description of the option.
00740  *   next: The next option in the chain that the created option precedes,
00741  *         or NULL if the created option is the last.
00742  * Returns:
00743  *   A pointer to the newly created argument option. The option will have its
00744  *   'required' property set to true.
00745  */
00746 uc_EXPORTED ucArgOpt *ucArgOpt_create_required(const char *name, const char *desc, ucArgOpt *next);
00747 
00748 uc_EXPORTED ucArgOpt *ucArgOpt_create_boolean(const char *desc, ucArgOpt *next);
00749 uc_EXPORTED ucArgOpt *ucArgOpt_create_required_boolean(const char *desc, ucArgOpt *next);
00750 
00751 /*
00752  * Summary:
00753  *   Creates a new, numeric argument option.
00754  * Parameters:
00755  *   desc: The description of the argument.
00756  *   numeric_min: The minimum value of the argument.
00757  *   numeric_max: The maximum value of the argument.
00758  *   next: A pointer to the next option in the chain that the created option precedes,
00759  *         or NULL if the created option is the last.
00760  * Returns:
00761  *   A pointer to the newly created argument option.
00762  */
00763 uc_EXPORTED ucArgOpt *ucArgOpt_create_numeric(const char *desc, ucArgOpt_NUMERIC_TYPE numeric_min, ucArgOpt_NUMERIC_TYPE numeric_max, ucArgOpt *next);
00764 
00765 /*
00766  * Summary:
00767  *   Creates a new, numeric argument option that accepts multiple argument tokens.
00768  * Parameters:
00769  *   desc: The description of the argument.
00770  *   min_tok_count: The minimum number of allowed argument tokens.
00771  *   max_tok_count: The maximum number of allowed argument tokens.
00772  *   numeric_min: The minimum value of the argument.
00773  *   numeric_max: The maximum value of the argument.
00774  * Returns:
00775  *   A pointer to the newly created argument option.
00776  */
00777 uc_EXPORTED ucArgOpt *ucArgOpt_create_multiple_numeric(const char *desc, int min_tok_count, int max_tok_count, ucArgOpt_NUMERIC_TYPE numeric_min, ucArgOpt_NUMERIC_TYPE numeric_max);
00778 
00779 /*
00780  * Summary:
00781  *   Creates a new, numeric, required argument option.
00782  * Parameters:
00783  *   desc: The description of the argument.
00784  *   numeric_min: The minimum value of the argument.
00785  *   numeric_max: The maximum value of the argument.
00786  *   next: A pointer to the next option in the chain that the created option precedes,
00787  *         or NULL if the created option is the last.
00788  * Returns:
00789  *   A pointer to the newly created argument option. The option will have its
00790  *   'required' property set to true.
00791  */
00792 uc_EXPORTED ucArgOpt *ucArgOpt_create_required_numeric(const char *desc, ucArgOpt_NUMERIC_TYPE numeric_min, ucArgOpt_NUMERIC_TYPE numeric_max, ucArgOpt *next);
00793 
00794 /*
00795  * Summary:
00796  *   Gets the next argument option after the given option.
00797  * Returns:
00798  *   A pointer to the option that the given option precedes,
00799  *   or NULL of no further options exist.
00800  */
00801 uc_EXPORTED ucArgOpt *ucArgOpt_get_next(ucArgOpt*);
00802 
00803 /*
00804  * Summary:
00805  *   Releases memory used by the argument option.
00806  */
00807 uc_EXPORTED void ucArgOpt_destroy(ucArgOpt*);
00808 
00809 /*
00810  * Summary:
00811  *   Releases memory used by the argument option
00812  *   and all proceeding options in the list.
00813  */
00814 uc_EXPORTED void ucArgOpt_destroy_chain(ucArgOpt*);
00815 
00816 /*
00817  * Summary:
00818  *   Base structure for options (switches and commands)
00819  *   that contain argument options. This type is a child
00820  *   of the base option type.
00821  */
00822 typedef struct ucArgOptOwner ucArgOptOwner;
00823 
00824 /*
00825  * Summary:
00826  *   Gets the first argument option of the given option owner.
00827  * Returns:
00828  *   A pointer to the first argument option of the given option owner.
00829  */
00830 uc_EXPORTED ucArgOpt *ucArgOptOwner_get_arg_opt(ucArgOptOwner*);
00831 
00832 /*
00833  * Summary:
00834  *   A command switch option. This type is a child
00835  *   of the base option type.
00836  */
00837 typedef struct ucSwitchOpt ucSwitchOpt;
00838 
00839 /*
00840  * Summary:
00841  *   Creates a new switch option.
00842  * Parameters:
00843  *   name: The name of the switch.
00844  *   desc: A description of the switch.
00845  *   arg_opt: The first argument option of the switch.
00846  *   next: The switch option that the created option precedes,
00847  *         or NULL if no further switch options exist.
00848  * Returns:
00849  *   A pointer to the newly created switch option.
00850  */
00851 uc_EXPORTED ucSwitchOpt *ucSwitchOpt_create(const char *name, const char *desc, ucArgOpt *arg_opt, ucSwitchOpt *next);
00852 
00853 /*
00854  * Summary:
00855  *   Creates a new, required switch option.
00856  * Parameters:
00857  *   name: The name of the switch.
00858  *   desc: A description of the switch.
00859  *   arg_opt: The first argument option of the switch.
00860  *   next: The switch option that the created option precedes,
00861  *         or NULL if no further switch options exist.
00862  * Returns:
00863  *   A pointer to the newly created switch option. The option's
00864  *   'required' property will be set to true.
00865  */
00866 uc_EXPORTED ucSwitchOpt *ucSwitchOpt_create_required(const char *name, const char *desc, ucArgOpt *arg_opt, ucSwitchOpt *next);
00867 
00868 /*
00869  * Summary:
00870  *   Gets the first argument option of the given switch.
00871  * Returns:
00872  *   A pointer to the first argument option of the switch, or NULL
00873  *   if no argument options exist.
00874  */
00875 uc_EXPORTED ucArgOpt *ucSwitchOpt_get_arg_opt(ucSwitchOpt*);
00876 
00877 /*
00878  * Summary:
00879  *   Finds the switch option in the linked list with the given name.
00880  * Parameters:
00881  *   name: The name of the switch option to be found.
00882  * Returns:
00883  *   The switch option with the given name, or NULL if
00884  *   no switch option is found.
00885  */
00886 uc_EXPORTED ucSwitchOpt *ucSwitchOpt_find(ucSwitchOpt*, const char *name);
00887 
00888 /*
00889  * Summary:
00890  *   Gets the next switch option.
00891  * Returns:
00892  *   A pointer to the next switch option in the list, or NULL
00893  *   if no further options exist.
00894  */
00895 uc_EXPORTED ucSwitchOpt *ucSwitchOpt_get_next(ucSwitchOpt*);
00896 
00897 /*
00898  * Summary:
00899  *   Releases memory used by the switch option.
00900  */
00901 uc_EXPORTED void ucSwitchOpt_destroy(ucSwitchOpt*);
00902 
00903 /*
00904  * Summary:
00905  *   Releases memory used by the switch option and all
00906  *   proceeding options in the list. All memory used by
00907  *   any argument options belonging to the switches in
00908  *   the list is also released.
00909  */
00910 uc_EXPORTED void ucSwitchOpt_destroy_chain(ucSwitchOpt*);
00911 
00912 /*
00913  * Summary:
00914  *   Type that can be used to parse command lines.
00915  *   The result of the parse can be used as the command
00916  *   token for a command structure.
00917  */
00918 typedef struct ucCmdParser ucCmdParser;
00919 
00920 /*
00921  * Summary:
00922  *   Gets a static, default instance of the parser.
00923  * Returns:
00924  *   The static, default instance of the parser, or NULL
00925  *   if an error occurred.
00926  */
00927 uc_EXPORTED ucCmdParser *ucCmdParser_get_instance(void);
00928 
00929 /*
00930  * Summary:
00931  *   Parses a command so that it can be used as a command token.
00932  * Parameters:
00933  *   cmd: The command string to be parsed. This string is mutated.
00934  * Returns:
00935  *   A pointer to the command token that was parsed, or NULL if an
00936  *   error occurred.
00937  */
00938 uc_EXPORTED ucCmdTok *ucCmdParser_parse(ucCmdParser*, char *cmd);
00939 
00940 /*
00941  * Summary:
00942  *   A command option. This type is a child of the
00943  *   base option type.
00944  */
00945 typedef struct ucCmdLineOpt ucCmdLineOpt;
00946 
00947 /*
00948  * Summary:
00949  *   Defines the signature of the function called when a command option is processed.
00950  * Parameters:
00951  *   cmd: The parsed command structure that represents the function parameters.
00952  *   state: The state pointer with which the command option was created.
00953  * Returns:
00954  *   A message that can be used to respond to the command.
00955  */
00956 typedef const char *(ucCmdLineOpt_Func)(ucCmdLine *cmd, void *state);
00957 
00958 /*
00959  * Summary:
00960  *   Creates a new command option.
00961  * Parameters:
00962  *   func: A pointer to the function that is called when this command is invoked or selected.
00963  *   state: A pointer that gets passed to the function to maintain state.
00964  *   name: The name of the command.
00965  *   desc: The description of the command.
00966  *   arg_opt: The argument options available to the command.
00967  *   switch_opt: The switch options available to the command.
00968  *   next: The next command that the created command precedes, or NULL if no further commands exist.
00969  * Returns:
00970  *   A pointer to the newly created command option.
00971  */
00972 uc_EXPORTED ucCmdLineOpt *ucCmdLineOpt_create(ucCmdLineOpt_Func *func, void *state, const char *name, const char *desc, ucArgOpt *arg_opt, ucSwitchOpt *switch_opt, ucCmdLineOpt* next);
00973 
00974 /*
00975  * Summary:
00976  *   Gets the next command option after the given option.
00977  * Returns:
00978  *   A pointer to the next command option.
00979  */
00980 uc_EXPORTED ucCmdLineOpt *ucCmdLineOpt_get_next(ucCmdLineOpt*);
00981 
00982 /*
00983  * Summary:
00984  *   Gets the first argument option of the command.
00985  * Returns:
00986  *   A pointer to the first argument option of the command,
00987  *   or NULL if no argument options exist.
00988  */
00989 uc_EXPORTED ucArgOpt *ucCmdLineOpt_get_arg_opt(ucCmdLineOpt*);
00990 
00991 /*
00992  * Summary:
00993  *   Gets the first switch option of the command option.
00994  * Returns:
00995  *   A pointer to the first switch option of the command option,
00996  *   or NULL if no switch options exist.
00997  */
00998 uc_EXPORTED ucSwitchOpt *ucCmdLineOpt_get_switch_opt(ucCmdLineOpt*);
00999 
01000 /*
01001  * Summary:
01002  *   Finds the command option that matches the given name.
01003  * Parameters:
01004  *   name: The name of the command whose option is to be found.
01005  * Returns:
01006  *   A pointer to the command option that matches the given name, or NULL
01007  *   if no option is found.
01008  */
01009 uc_EXPORTED ucCmdLineOpt *ucCmdLineOpt_find_by_name(ucCmdLineOpt*, const char *name);
01010 
01011 /*
01012  * Summary:
01013  *   Gets the pointer to the function invoked when the command option
01014  *   is processed.
01015  * Returns:
01016  *   A pointer to the function invoked when the command option is processed.
01017  */
01018 uc_EXPORTED ucCmdLineOpt_Func *ucCmdLineOpt_get_func(ucCmdLineOpt*);
01019 
01020 /*
01021  * Summary:
01022  *   Gets the state pointer that is passed to the command option's function
01023  *   when it is invoked.
01024  * Returns:
01025  *   A pointer to the command option's state.
01026  */
01027 uc_EXPORTED void *ucCmdLineOpt_get_state(ucCmdLineOpt*);
01028 
01029 /*
01030  * Summary:
01031  *   Releases memory used by the command option.
01032  */
01033 uc_EXPORTED void ucCmdLineOpt_destroy(ucCmdLineOpt*);
01034 
01035 /*
01036  * Summary:
01037  *   Releases memory used by the command option and all proceeding options
01038  *   in the list. All memory used by any argument options, switch options,
01039  *   and switch-argument options is also released.
01040  */
01041 uc_EXPORTED void ucCmdLineOpt_destroy_chain(ucCmdLineOpt*);
01042 
01043 /*
01044  * Summary:
01045  *   Invokes the function of the command option that matches the command structure.
01046  * Parameters:
01047  *   cmd: The command structure whose option is invoked.
01048  * Returns:
01049  *   The response to the command.
01050  */
01051 uc_EXPORTED const char *ucCmdLineOpt_process(ucCmdLineOpt*, ucCmdLine *cmd);
01052 
01053 /*
01054  * Summary:
01055  *   Uses the provided command structure to respond with a usage string 
01056  *   for this command option.
01057  * Parameters:
01058  *   cmd: The command structure used to respond with the usage string.
01059  */
01060 uc_EXPORTED void ucCmdLineOpt_send_usage(ucCmdLineOpt*, ucCmdLine *cmd);
01061 
01062 /*
01063  * Summary:
01064  *   Uses the provided command structure to respond with help information
01065  *   for the this command option.
01066  * Parameters:
01067  *   cmd: The command structure used to respond with the help information.
01068  */
01069 uc_EXPORTED void ucCmdLineOpt_send_help(ucCmdLineOpt*, ucCmdLine *cmd);
01070 
01071 /*
01072  * Summary:
01073  *   An application that runs with a set of command options.
01074  */
01075 typedef struct ucCmdLineApp ucCmdLineApp;
01076 
01077 /*
01078  * Summary:
01079  *   The type of the function used by an application to
01080  *   receive data.
01081  * Parameters:
01082  *   buf: A string buffer that can be used to store the data received.
01083  *   buf_size: The size of the string buffer used to store received data.
01084  *   state: A stateful object.
01085  * Returns:
01086  *   The data that was received.
01087  */
01088 typedef char *(ucCmdLineApp_ReceiveFunc)(char *buf, size_t buf_size, void *state);
01089 
01090 /*
01091  * Summary:
01092  *   Sets the escape string that will cause the app to exit.
01093  * Parameters:
01094  *   value: The escape string that, when returned in a response,
01095  *          causes the app to exit.
01096  */
01097 uc_EXPORTED void ucCmdLineApp_set_escape_response(ucCmdLineApp*, const char *value);
01098 
01099 /*
01100  * Summary:
01101  *   Gets the escape string that causes the app to exit.
01102  * Returns:
01103  *   The escape string that, when returned in a response,
01104  *   causes the app to exit.
01105  */
01106 uc_EXPORTED const char *ucCmdLineApp_get_escape_response(ucCmdLineApp*);
01107 
01108 /*
01109  * Summary:
01110  *   Runs the application with the given options.
01111  * Parameters:
01112  *   cmd_opt: A pointer to the first command option for the app.
01113  * Returns:
01114  *   An error code, if one occurred.
01115  */ 
01116 uc_EXPORTED ucErr ucCmdLineApp_run(ucCmdLineApp*, ucCmdLineOpt *cmd_opt);
01117 
01118 /*
01119  * Summary:
01120  *   Gets a static, default instance of the application.
01121  * Returns:
01122  *   The static, default instance of the application.
01123  */
01124 uc_EXPORTED ucCmdLineApp *ucCmdLineApp_get_instance(void);
01125 
01126 /*
01127  * Summary:
01128  *   Sets the function that the app uses to receive data.
01129  * Parameters:
01130  *   value: A pointer to the function used to receive data.
01131  */
01132 uc_EXPORTED void ucCmdLineApp_set_receive(ucCmdLineApp*, ucCmdLineApp_ReceiveFunc *value);
01133 
01134 /*
01135  * Summary:
01136  *   Gets the function that the app uses to receive data.
01137  * Returns:
01138  *   A pointer to the function used to receive data.
01139  */ 
01140 uc_EXPORTED ucCmdLineApp_ReceiveFunc *ucCmdLineApp_get_receive(ucCmdLineApp*);
01141 
01142 /*
01143  * Summary:
01144  *   Gets the stateful object passed to the application's receive function.
01145  * Returns:
01146  *   A pointer to the stateful object passed to the application's receive function.
01147  */
01148 uc_EXPORTED void *ucCmdLineApp_get_receive_state(ucCmdLineApp*);
01149 
01150 /*
01151  * Summary:
01152  *   Sets the stateful object passed to the application's receive function.
01153  * Parameters:
01154  *   value: The stateful object passed to the application's receive function.
01155  */
01156 uc_EXPORTED void ucCmdLineApp_set_receive_state(ucCmdLineApp*, void *value);
01157 
01158 /*
01159  * Summary:
01160  *   Sets the command used to quit the application.
01161  * Parameters:
01162  *   value: The value of the command that quits the application.
01163  */
01164 uc_EXPORTED void ucCmdLineApp_set_quit_command(ucCmdLineApp*, const char *value);
01165 
01166 /*
01167  * Summary:
01168  *   Gets the value of the command that quits the application.
01169  * Returns:
01170  *   The value of the command that quits the application.
01171  */
01172 uc_EXPORTED const char *ucCmdLineApp_get_quit_command(ucCmdLineApp*);
01173 
01174 /*
01175  * Summary:
01176  *   Sets the value of the command that shows help information.
01177  * Parameters:
01178  *   value: The value of the command that shows help information.
01179  */
01180 uc_EXPORTED void ucCmdLineApp_set_help_command(ucCmdLineApp*, const char *value);
01181 
01182 /*
01183  * Summary:
01184  *   Gets the value of the command that shows help information.
01185  * Returns:
01186  *   The value of the command that shows help information.
01187  */
01188 uc_EXPORTED const char *ucCmdLineApp_get_help_command(ucCmdLineApp*);
01189 
01190 /*
01191  * Summary:
01192  *   Sets the command structure that the application uses.
01193  * Parameters:
01194  *   value: The command structure to be used by the application.
01195  */
01196 uc_EXPORTED void ucCmdLineApp_set_cmd(ucCmdLineApp*, ucCmdLine *value);
01197 
01198 /*
01199  * Summary:
01200  *   Gets the command structure used by the application.
01201  * Returns:
01202  *   A pointer to the command structure used by the application.
01203  */
01204 uc_EXPORTED ucCmdLine *ucCmdLineApp_get_cmd(ucCmdLineApp*);
01205 
01206 /*
01207  * Summary:
01208  *   Gets the command parser used by the application.
01209  * Returns:
01210  *   A pointer to the command parser used by the application.
01211  */
01212 uc_EXPORTED ucCmdParser *ucCmdLineApp_get_cmd_parser(ucCmdLineApp*);
01213 
01214 /*
01215  * Summary:
01216  *   Gets the size of the application's command-string buffer.
01217  * Returns:
01218  *   The size of the command-string buffer.
01219  */
01220 uc_EXPORTED size_t ucCmdLineApp_get_cmd_str_size_max(ucCmdLineApp *p);
01221 
01222 #endif
01223