1 /*---------------------------------------------------------------------------* 2 | PDFlib - A library for generating PDF on the fly | 3 +---------------------------------------------------------------------------+ 4 | Copyright (c) 1997-2006 Thomas Merz and PDFlib GmbH. All rights reserved. | 5 +---------------------------------------------------------------------------+ 6 | | 7 | This software is subject to the PDFlib license. It is NOT in the | 8 | public domain. Extended versions and commercial licenses are | 9 | available, please check http://www.pdflib.com. | 10 | | 11 *---------------------------------------------------------------------------*/ 12 13 /* $Id: pc_optparse.h,v 1.80.2.8 2009/03/16 14:01:12 kurt Exp $ 14 * 15 * Definitions for option parser routines 16 * 17 */ 18 19 #ifndef PC_OPTPARSE_H 20 #define PC_OPTPARSE_H 21 22 /* 23 * Optlist 24 * ------- 25 * An optlist is a string containing pairs of the form 26 * "optionname optionvalue(s)". The separator characters 27 * are "\f\n\r\t\v =". 28 * 29 * There are options of different types (see pdc_opttype): 30 * 31 * Boolean (pdc_booleanlist) 32 * Strings (pdc_stringlist) 33 * Keywords (pdc_keywordlist) 34 * Integers (pdc_integerlist) 35 * Floats (pdc_floatlist) 36 * Doubles (pdc_doublelist) 37 * Scalars (pdc_scalarlist) 38 * Unichars (pdc_unicharlist) 39 * Polylinelist (pdc_polylinelist) 40 * Handles (pdc_colorhandle ...) 41 * 42 * An option can have one or more values. Boolean options can be 43 * provided without any value. If an option has more than one value, 44 * then these values have to be set in braces. Examples: 45 * 46 * dasharray {11 22 33} 47 * 48 * Strings with white spaces have to be set in braces too. 49 * Examples: 50 * 51 * fullname {Ludwig Wittgenstein} 52 * composers {{Gustav Mahler}} 53 * comment {} 54 * 55 * The allowed option names and the limitations of their values 56 * must be defined in an array of enumeration type pdc_defopt 57 * (see below). Such an option definition specifies (in brackets 58 * the member name in the pdc_defopt struct) 59 * 60 * - the name of the option (name) 61 * - the type of the option (type) 62 * - value restrictions by bit flags (flags) 63 * - the minimal and maximal permitted number of values 64 * (minnum, maxnum) 65 * - the minimal and maximal permitted value, or string 66 * length resp. (minval, maxval) 67 * - the permitted keywords in a keyword list (is required) or 68 * the permitted integer numbers in a integer list (is optional), 69 * resp. (keylist) 70 * 71 * Remarks: 72 * 73 * - minnum = maxnum = 1: The program expects a single value, 74 * otherwise an array. If an array consists of only one value 75 * the braces can be omitted - but not in the case of strings 76 * with white spaces (see example above). 77 * - Boolean options have the values "true" or "false". A shorter 78 * equivalent notation is "name" or "noname". for "name true" 79 * or "name false", resp. 80 * - White spaces in strings can be forbidden by the flag 81 * PDC_OPT_NOSPACES. 82 * - It's only possible to specify a single number interval (minval, 83 * maxval) which must contain the number. The flag PDC_OPT_NOZERO 84 * can forbid zero additionally. 85 * - Keywords will always be converted to integer numbers (keycodes) 86 * according to the specified pdc_keyconn array. 87 * - It is possible to specify keywords for integers, floats and 88 * doubles additionally by an optional keylist entry. For integers 89 * it is possible to specify the allowed integer values by an optional 90 * keylist and by the flag PDC_OPT_INTLIST. 91 * - If more than one keyword is permitted, then the flag 92 * PDC_OPT_BUILDOR decides, whether a bit pattern must be 93 * built by or-ing the single keycodes or not. 94 * 95 * Program run: 96 * 97 * An optlist is parsed by the function "pdc_parse_optionlist". 98 * After successfully parsing this function returns a pointer to the 99 * allocated "pdc_resopt" structures containing the option values. 100 * These structures must be freed by the function "pdc_cleanup_optionlist". 101 * 102 * Values can be fetched by the function "pdc_get_optvalues". This can 103 * be achieved by specifying a variable pointer (lvalues) or by a pointer 104 * to a pointer (mvalues). In the first case the variable must be large 105 * enough to hold the values. In the second case the pointer is the pointer 106 * to the allocated array with the option values. This pointer will be 107 * freed in "pdc_cleanup_optionlist". To avoid this you can call the function 108 * "pdc_save_lastopt" after the call of "pdc_get_optvalues". Function 109 * "pdc_save_lastopt" returns the pointer which is protected now against 110 * freeing in "pdc_cleanup_optionlist". In the special case of type = 111 * pdc_stringlist, you can protect only the first element in the string 112 * list by calling "pdc_save_lastopt" with the flag PDC_OPT_SAVE1ELEM. 113 * Flag = PDC_OPT_SAVEALL defines the general case. The caller has the 114 * responsibility to free the protected pointers after use. 115 * 116 * pdc_stringlist: 117 * maxnum = 1: lvalues: char s[maxval+1] (defined char array) 118 * maxnum > 1: lvalues: char *s[maxnum] (defined char pointer array) 119 * mvalues: char **s (pointer to a char pointer array) 120 * 121 */ 122 123 typedef struct pdc_keyconn_s pdc_keyconn; 124 typedef struct pdc_clientdata_s pdc_clientdata; 125 typedef struct pdc_defopt_s pdc_defopt; 126 typedef struct pdc_resopt_s pdc_resopt; 127 128 /* types of option values */ 129 typedef enum 130 { 131 pdc_booleanlist = 0, 132 pdc_stringlist, 133 pdc_keywordlist, 134 pdc_integerlist, 135 pdc_floatlist, 136 pdc_doublelist, 137 pdc_scalarlist, 138 pdc_unicharlist, 139 pdc_polylinelist, 140 141 /* correspondig member of pdc_clientdata_s must be specified */ 142 pdc_3ddatahandle, 143 pdc_3dviewhandle, 144 pdc_actionhandle, 145 pdc_bookmarkhandle, 146 pdc_colorhandle, 147 pdc_documenthandle, 148 pdc_fonthandle, 149 pdc_gstatehandle, 150 pdc_iccprofilehandle, 151 pdc_imagehandle, 152 pdc_layerhandle, 153 pdc_pagehandle, 154 pdc_patternhandle, 155 pdc_shadinghandle, 156 pdc_tablehandle, 157 pdc_templatehandle, 158 pdc_textflowhandle, 159 pdc_stringhandle 160 } 161 pdc_opttype; 162 163 /* keyword - keycode */ 164 struct pdc_keyconn_s 165 { 166 char *word; 167 int code; 168 }; 169 170 /* client data */ 171 struct pdc_clientdata_s 172 { 173 int compatibility; 174 int max3ddata; 175 int max3dview; 176 int maxaction; 177 int maxbookmark; 178 int maxcolor; 179 int maxdocument; 180 int maxfont; 181 int maxgstate; 182 int maxiccprofile; 183 int maximage; 184 int maxlayer; 185 int maxpage; 186 int maxpattern; 187 int maxshading; 188 int maxtable; 189 int maxtemplate; 190 int maxtextflow; 191 int maxstring; 192 }; 193 194 /* definition of an option */ 195 struct pdc_defopt_s 196 { 197 const char *name; /* name of option keyword */ 198 pdc_opttype type; /* type of option */ 199 unsigned int flags; /* flags (see below) */ 200 int minnum; /* permitted minimal number of values */ 201 int maxnum; /* permitted maximal number of values */ 202 double minval; /* minimal permitted value / length of string */ 203 double maxval; /* maximal permitted value / length of string */ 204 const pdc_keyconn *keylist; /* list of permitted keywords - keycodes */ 205 }; 206 207 #define PDC_OPT_TERMINATE \ 208 {NULL, pdc_booleanlist, 0L, 0, 0, 0.0, 0.0, NULL} 209 210 #define PDC_OPT_NONE (0) /* no flag specified */ 211 #define PDC_OPT_NOZERO (1U<<0) /* zero value not allowed */ 212 #define PDC_OPT_NOSPACES (1U<<1) /* white spaces in strings not allowed */ 213 #define PDC_OPT_REQUIRED (1U<<2) /* option is required */ 214 #define PDC_OPT_BUILDOR (1U<<3) /* build an OR bit pattern by keycodes */ 215 #define PDC_OPT_INTLIST (1U<<4) /* keylist is list of allowed integers */ 216 #define PDC_OPT_IGNOREIF1 (1U<<5) /* option is ignored if previous option is 217 * specified */ 218 #define PDC_OPT_IGNOREIF2 (1U<<6) /* option is ignored if either of 219 * previous two options is specified */ 220 #define PDC_OPT_UNSUPP (1U<<8) /* option is not supported in this 221 * configuration */ 222 #define PDC_OPT_REQUIRIF1 (1U<<9) /* option is required if previous option is 223 * specified */ 224 #define PDC_OPT_REQUIRIF2 (1U<<10) /* option is required if either of 225 * previous two options is specified */ 226 #define PDC_OPT_EVENNUM (1U<<11) /* array has even number of elements */ 227 #define PDC_OPT_ODDNUM (1U<<12) /* array has odd number of elements */ 228 229 /* member "compatibility" of pdc_clientdata_s must be specified (1U<<13) ... */ 230 #define PDC_OPT_PDC_1_3 (1U<<PDC_1_3) /* compatibility PDC_1_3 */ 231 #define PDC_OPT_PDC_1_4 (1U<<PDC_1_4) /* compatibility PDC_1_4 */ 232 #define PDC_OPT_PDC_1_5 (1U<<PDC_1_5) /* compatibility PDC_1_5 */ 233 #define PDC_OPT_PDC_1_6 (1U<<PDC_1_6) /* compatibility PDC_1_6 */ 234 #define PDC_OPT_PDC_1_7 (1U<<PDC_1_7) /* compatibility PDC_1_7 */ 235 236 #define PDC_OPT_CASESENS (1U<<20) /* case-sensitive keywords */ 237 #define PDC_OPT_PERCENT (1U<<21) /* number maybe with percent sign (123%) */ 238 #define PDC_OPT_DUPORIGVAL (1U<<22) /* duplicate original value */ 239 #define PDC_OPT_SUBOPTLIST (1U<<23) /* string list is a suboptlist */ 240 #define PDC_OPT_CONVUTF8 (1U<<24) /* string has to be converted to UTF-8 */ 241 #define PDC_OPT_ISBOX (1U<<25) /* polyline is a box (four coordinates) */ 242 #define PDC_OPT_PERCRANGE (1U<<26) /* number only in the range 0% - 100% */ 243 244 #define PDC_OPT_KEYLIST1 (1U<<27) /* use key list only for first element */ 245 #define PDC_OPT_CLOSEPOLY (1U<<28) /* close polyline, minimal vertices = 3 */ 246 247 #define PDC_OPT_PDFLIB_7 (1U<<31) /* deprecated since PDFlib 7 */ 248 249 /* flags for single result */ 250 #define PDC_OPT_SAVEALL (1U<<0) /* save all pointers */ 251 #define PDC_OPT_SAVE1ELEM (1U<<1) /* save only first string list element */ 252 #define PDC_OPT_SAVEORIG (1U<<2) /* save original value string */ 253 254 /* flag for UTF-8 value */ 255 #define PDC_OPT_ISUTF8 (1U<<9) /* string[list] is UTF-8 */ 256 257 /* key word not found */ 258 #define PDC_KEY_NOTFOUND -1234567890 259 260 /* key word abbreviation not unique */ 261 #define PDC_KEY_NOTUNIQUE -1234567891 262 263 /* separator signs in option lists */ 264 #define PDC_OPT_LISTSEPS "\f\n\r\t\v =" 265 266 /* pc_optparse.c */ 267 int pdc_get_keycode(const char *keyword, const pdc_keyconn *keyconn); 268 int pdc_get_keycode_ci(const char *keyword, const pdc_keyconn *keyconn); 269 int pdc_get_keycode_unique(const char *keyword, const pdc_keyconn *keyconn); 270 int pdc_get_keymask_ci(pdc_core *pdc, const char *option, 271 const char *keywordlist, const pdc_keyconn *keyconn); 272 int pdc_get_keycode_num(pdc_core *pdc, const char *option, 273 const char *i_keyword, int flags, const pdc_keyconn *keyconn, 274 int *o_num); 275 const char *pdc_get_keyword(int keycode, const pdc_keyconn *keyconn); 276 const char *pdc_get_int_keyword(const char *keyword, 277 const pdc_keyconn *keyconn); 278 pdc_resopt *pdc_parse_optionlist(pdc_core *pdc, const char *optlist, 279 const pdc_defopt *defopt, const pdc_clientdata *clientdata, 280 pdc_bool verbose); 281 int pdc_get_optvalues(const char *keyword, pdc_resopt *resopt, 282 void *lvalues, char ***mvalues); 283 void *pdc_save_lastopt(pdc_resopt *resopt, int flags); 284 int pdc_get_lastopt_index(pdc_resopt *resopt); 285 pdc_bool pdc_is_lastopt_percent(pdc_resopt *resopt, int ind); 286 pdc_bool pdc_is_lastopt_utf8(pdc_resopt *resopt); 287 int pdc_get_opt_utf8strings(pdc_core *pdc, const char *keyword, 288 pdc_resopt *resopt, int flags, char ***strings); 289 const char *pdc_get_opt_filename(pdc_core *pdc, const char *keyword, 290 pdc_resopt *resopts); 291 void pdc_cleanup_optionlist(pdc_core *pdc, pdc_resopt *resopt); 292 void pdc_cleanup_optstringlist(pdc_core *pdc, char **stringlist, int ns); 293 const char *pdc_get_handletype(pdc_opttype type); 294 295 #endif /* PC_OPTPARSE_H */ 296 297