1 /** 2 * \file 3 * \brief comfortable command-line parsing 4 * 5 * \date 2002 6 * \author Jork Loeser <jork.loeser@inf.tu-dresden.de> 7 */ 8 9 /* 10 * (c) 2003-2009 Author(s) 11 * economic rights: Technische Universität Dresden (Germany) 12 * This file is part of TUD:OS and distributed under the terms of the 13 * GNU Lesser General Public License 2.1. 14 * Please see the COPYING-LGPL-2.1 file for details. 15 */ 16 17 #ifndef __PARSE_CMD_H 18 #define __PARSE_CMD_H 19 20 #include <stdarg.h> 21 #include <l4/sys/compiler.h> 22 23 /** 24 * \defgroup l4util_parse_cmd Comfortable Command Line Parsing 25 * \ingroup l4util_api 26 */ 27 /*@{*/ 28 29 /** 30 * \brief Types for parsing 31 */ 32 enum parse_cmd_type { 33 PARSE_CMD_INT, 34 PARSE_CMD_SWITCH, 35 PARSE_CMD_STRING, 36 PARSE_CMD_FN, 37 PARSE_CMD_FN_ARG, 38 PARSE_CMD_INC, 39 PARSE_CMD_DEC, 40 }; 41 42 /** 43 * \brief Function type for PARSE_CMD_FN 44 */ 45 typedef L4_CV void (*parse_cmd_fn_t)(int); 46 47 /** 48 * \brief Function type for PARSE_CMD_FN_ARG 49 */ 50 typedef L4_CV void (*parse_cmd_fn_arg_t)(int, const char*, int); 51 52 EXTERN_C_BEGIN 53 54 /** Parse the command-line for specified arguments and store the values into 55 * variables. 56 * 57 * This Functions gets the command-line, and a list of 58 * command-descriptors. Then, the command-line is parsed according to 59 * the given descriptors, storing strings, switches and numeric 60 * arguments at given addresses, and possibly calling specified 61 * functions. A default help descriptor is added. Its purpose is to 62 * present a short command overview in the case the given command-line 63 * does not fit to the descriptors. 64 * 65 * Each command-descriptor has the following form: 66 * 67 * \e short \e option \e char, \e long \e option \e name, 68 * \e comment, \e type, \e val, \e addr. 69 * 70 * The \e short \e option \e char specifies the short form of the 71 * described option. The short form will be recognized after a single 72 * dash, or in a group of short options preceeded by a single dash. 73 * Specify ' ' if no short form should be used. 74 * 75 * The \e long \e option \e name specifies the long form of the 76 * described option. The long form will be recognized after two 77 * dashes. Specify 0 if no long form should be used for this option. 78 * 79 * The \e comment is a string that will be used when presenting the short 80 * command-line help. 81 * 82 * The \e type specifies, if the option should be recognized as 83 * - a number (\c PARSE_CMD_INT), 84 * - a switch (\c PARSE_CMD_SWITCH), 85 * - a string (\c PARSE_CMD_STRING), 86 * - a function call (\c PARSE_CMD_FN, \c PARSE_CMD_FN_ARG), 87 * - an increment/decrement operator (\c PARSE_CMD_INC, \c PARSE_CMD_DEC). 88 * 89 * If type is \c PARSE_CMD_INT, the option requires a second argument 90 * on the command-line after the option. This argument is parsed as a 91 * number. It can be preceeded by 0x to present a hex-value or by 0 to 92 * present an octal form. \e addr is interpreted as an int-pointer. 93 * The scanned argument from the command-line is stored in this 94 * pointer. 95 * 96 * If \e type is \c PARSE_CMD_SWITCH, \e addr must be a pointer to 97 * int, and the value from \e val is stored at this pointer. 98 * 99 * With \c PARSE_CMD_STRING, an additional argument is expected at the 100 * cmdline. \e addr must be a pointer to const char*, and a pointer to 101 * the argument on the command line is stored at this pointer. The 102 * value in \e val is a default value, which is stored at \e addr if 103 * the corresponding option is not given on the command line. 104 * 105 * With \c PARSE_CMD_FN_ARG, \e addr is interpreted as a function 106 * pointer of type #parse_cmd_fn_t. It will be called with \e val as 107 * argument if the corresponding option is found. 108 * 109 * If \e type is \c PARSE_CMD_FN_ARG, \e addr is as a function pointer 110 * of type #parse_cmd_fn_arg_t, and handled similar to 111 * \c PARSE_CMD_FN. An additional argument is expected at the command 112 * line, however. It is given to the called function as 2nd argument, 113 * and parsed as an integer as with \c PARSE_CMD_INT as a third 114 * argument. 115 * 116 * If \e type is \c PARSE_CMD_INC or \c PARSE_CMD_DEC, \e addr is 117 * interpreted as an int-pointer. The value of \e val is stored to 118 * this pointer first. For every occurence of the option in the 119 * command line, the integer referenced by \e addr is incremented or 120 * decremented, respectively. 121 * 122 * The list of command-descriptors is terminated by specifying a binary 0 for 123 * the short option char. 124 * 125 * Note: The short option char 'h' and the long option name "help" must not be 126 * specified. They are used for the default help descriptor and produce a short 127 * command-options help when specified on the command-line. 128 * 129 * \param argc pointer to number of command line parameters as passed to main 130 * \param argv pointer to array of command line parameters as passed to main 131 * \param arg0 format list describing the command line options to parse for 132 * \return 0 if the command-line was successfully parsed, otherwise: 133 * - -1 if the given descriptors are somehow wrong. 134 * - -2 if not enough memory was available to hold temporary structs. 135 * - -3 if the given command-line args did not meet the specified set. 136 * - -4 if the help-option was given. 137 * 138 * Upon return, argc and argv point to a list of arguments that were not 139 * scanned as arguments. See \c getoptlong for details on scanning. */ 140 L4_CV int parse_cmdline(int *argc, const char***argv, char arg0, ...); 141 L4_CV int parse_cmdlinev(int *argc, const char***argv, char arg0, va_list va); 142 L4_CV int parse_cmdline_extra(const char*argv0, const char*line, char delim, 143 char arg0,...); 144 145 EXTERN_C_END 146 /*@}*/ 147 148 #endif 149 150