1/*---------------------------------------------------------------------------*
2 |              PDFlib - A library for generating PDF on the fly             |
3 +---------------------------------------------------------------------------+
4 | Copyright (c) 1997-2004 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 14574 2005-10-29 16:27:43Z bonefish $
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 *      Handles   (pdc_colorhandle ...)
38 *
39 *  An option can have one or more values. Boolean options can be
40 *  provided without any value. If an option has more than one value,
41 *  then these values have to be set in braces. Examples:
42 *
43 *      dasharray {11 22 33}
44 *
45 *  Strings with white spaces have to be set in braces too.
46 *  Examples:
47 *
48 *      fullname {Ludwig Wittgenstein}
49 *      composers {{Gustav Mahler}}
50 *      comment {}
51 *
52 *  The allowed option names and the limitations of their values
53 *  must be defined in an array of enumeration type pdc_defopt
54 *  (see below). Such an option definition specifies (in brackets
55 *  the member name in the pdc_defopt struct)
56 *
57 *      - the name of the option (name)
58 *      - the type of the option (type)
59 *      - value restrictions by bit flags (flags)
60 *      - the minimal and maximal permitted number of values
61 *        (minnum, maxnum)
62 *      - the minimal and maximal permitted value, or string
63 *        length resp. (minval, maxval)
64 *      - the permitted keywords in a keyword list (is required) or
65 *        the permitted integer numbers in a integer list (is optional),
66 *        resp. (keylist)
67 *      - the number of default values and the default values
68 *        themselves (defnum, defval)
69 *
70 *  Remarks:
71 *
72 *      - minnum = maxnum = 1: The program expects a single value,
73 *        otherwise an array. If an array consists of only one value
74 *        the braces can be omitted - but not in the case of strings
75 *        with white spaces (see example above).
76 *      - Boolean options have the values "true" or "false". A shorter
77 *        equivalent notation is "+name" or "-name". for "name true"
78 *        or "name false", resp.
79 *      - White spaces in strings can be forbidden by the flag
80 *        PDC_OPT_NOSPACES.
81 *      - It's only possible to specify a single number interval (minval,
82 *        maxval) which must contain the number. The flag PDC_OPT_NOZERO
83 *        can forbid zero additionally.
84 *      - Keywords will always be converted to integer numbers (keycodes)
85 *        according to the specified pdc_keyconn array.
86 *      - It is possible to specify keywords for integers, floats and
87 *        doubles additionally by an optional keylist entry. For integers
88 *        it is possible to specify the allowed integer values by an optional
89 *        keylist and by the flag PDC_OPT_INTLIST.
90 *      - If more than one keyword is permitted, then the flag
91 *        PDC_OPT_BUILDOR decides, whether a bit pattern must be
92 *        built by or-ing the single keycodes or not.
93 *
94 *  Program run:
95 *
96 *  An optlist will be parsed by the function pdc_parse_optionlist.
97 *  After successfully parsing this function returns a pointer to the
98 *  allocated pdc_resopt structures containing the option values.
99 *  These structures must be freed by the function pdc_cleanup_optionlist.
100 *
101 *  Values must be fetched by the function pdc_get_optvalues. This can
102 *  be achieved by specifying a variable pointer (lvalues) or by a pointer
103 *  to a pointer (mvalues). In the first case the variable must be large
104 *  enough to hold the values. In the second case the pointer is the pointer
105 *  to the allocated array with the option values. If such a pointer is
106 *  specified in a call of pdc_get_optvalues the pointer will not be freed
107 *  in pdc_cleanup_optionlist, but the caller has the responsibility to
108 *  free it after use.
109 *
110 *  pdc_stringlist:
111 *  maxnum = 1: lvalues: char s[maxval+1]  (defined char array)
112 *  maxnum > 1: lvalues: char *s[maxnum]   (defined char pointer rarray)
113 *              mvalues: char **s          (pointer to a char pointer array)
114 *
115 */
116
117typedef struct pdc_keyconn_s pdc_keyconn;
118typedef struct pdc_clientdata_s pdc_clientdata;
119typedef struct pdc_defopt_s pdc_defopt;
120typedef struct pdc_resopt_s pdc_resopt;
121
122/* types of option values */
123typedef enum
124{
125    pdc_booleanlist = 0,
126    pdc_stringlist,
127    pdc_keywordlist,
128    pdc_integerlist,
129    pdc_floatlist,
130    pdc_doublelist,
131
132    /* correspondig member of pdc_clientdata_s must be specified */
133    pdc_colorhandle,
134    pdc_documenthandle,
135    pdc_fonthandle,
136    pdc_gstatehandle,
137    pdc_iccprofilehandle,
138    pdc_imagehandle,
139    pdc_pagehandle,
140    pdc_patternhandle,
141    pdc_shadinghandle
142}
143pdc_opttype;
144
145/* keyword - keycode */
146struct pdc_keyconn_s
147{
148    char *word;
149    int  code;
150};
151
152/* client data */
153struct pdc_clientdata_s
154{
155    int compatibility;
156    int maxcolor;
157    int maxdocument;
158    int maxfont;
159    int maxgstate;
160    int maxiccprofile;
161    int maximage;
162    int maxpage;
163    int maxpattern;
164    int maxshading;
165    pdc_bool hastobepos;
166};
167
168/* definition of an option */
169struct pdc_defopt_s
170{
171    const char        *name;    /* name of option keyword */
172    pdc_opttype        type;    /* type of option */
173    int                flags;   /* flags (see below) */
174    int                minnum;  /* permitted minimal number of values */
175    int                maxnum;  /* permitted maximal number of values */
176    double             minval;  /* minimal permitted value / length of string */
177    double             maxval;  /* maximal permitted value / length of string */
178    const pdc_keyconn *keylist; /* list of permitted keywords - keycodes */
179};
180
181#define PDC_OPT_TERMINATE \
182    {NULL, pdc_booleanlist, 0L, 0, 0, 0.0, 0.0, NULL}
183
184#define PDC_OPT_NONE       (0)      /* no flag specified */
185#define PDC_OPT_NOZERO     (1L<<0)  /* zero value not allowed */
186#define PDC_OPT_NOSPACES   (1L<<1)  /* white spaces in strings not allowed */
187#define PDC_OPT_REQUIRED   (1L<<2)  /* option is required */
188#define PDC_OPT_BUILDOR    (1L<<3)  /* build an OR bit pattern by keycodes */
189#define PDC_OPT_INTLIST    (1L<<4)  /* keylist is list of allowed integers */
190#define PDC_OPT_IGNOREIF1  (1L<<5)  /* option is ignored if previous option is
191                                     * specified */
192#define PDC_OPT_IGNOREIF2  (1L<<6)  /* option is ignored if either of
193                                     * previous two options is specified */
194#define PDC_OPT_UNSUPP     (1L<<8)  /* option is not supported in this
195                                     * configuration */
196#define PDC_OPT_REQUIRIF1  (1L<<9)  /* option is require if previous option is
197                                     * specified */
198#define PDC_OPT_REQUIRIF2  (1L<<10) /* option is require if either of
199                                     * previous two options is specified */
200
201/* member "compatibility" of pdc_clientdata_s must be specified (1L<<12) ... */
202#define PDC_OPT_PDC_1_3   (1L<<PDC_1_3) /* compatibility PDC_1_3 */
203#define PDC_OPT_PDC_1_4   (1L<<PDC_1_4) /* compatibility PDC_1_4 */
204#define PDC_OPT_PDC_1_5   (1L<<PDC_1_5) /* compatibility PDC_1_5 */
205
206/* key word not found */
207#define PDC_KEY_NOTFOUND  -1234567890
208
209/* pc_optparse.c */
210int pdc_get_keycode(const char *keyword, const pdc_keyconn *keyconn);
211int pdc_get_keycode_ci(const char *keyword, const pdc_keyconn *keyconn);
212const char *pdc_get_keyword(int keycode, const pdc_keyconn *keyconn);
213const char *pdc_get_int_keyword(char *keyword, const pdc_keyconn *keyconn);
214pdc_resopt *pdc_parse_optionlist(pdc_core *pdc, const char *optlist,
215                                 const pdc_defopt *defopt,
216                                 const pdc_clientdata *clientdata,
217                                 pdc_bool verbose);
218int pdc_get_optvalues(pdc_core *pdc, const char *keyword,
219                      pdc_resopt *resopt, void *lvalues, void **mvalues);
220void pdc_cleanup_optionlist(pdc_core *pdc, pdc_resopt *resopt);
221void pdc_cleanup_optstringlist(pdc_core *pdc, char **stringlist, int ns);
222const char *pdc_get_handletype(pdc_opttype type);
223
224#endif  /* PC_OPTPARSE_H */
225