Debian Codegraph @

podofo/3rdparty/adobe/afdko/include/pstoken.h

raw
1 /* Copyright 2014 Adobe Systems Incorporated (http://www.adobe.com/). All Rights Reserved.
2 This software is licensed as OpenSource, under the Apache License, Version 2.0.
3 This license is available at: http://opensource.org/licenses/Apache-2.0. */
4
5 #ifndef PSTOKEN_H
6 #define PSTOKEN_H
7
8 #include "ctlshare.h"
9
10 #define PST_VERSION CTL_MAKE_VERSION(2, 0, 11)
11
12 #ifdef __cplusplus
13 extern "C" {
14 #endif
15
16 /* PostScript Tokenizer Library
17 ============================
18 The PostScript tokenizer library parses a PostScript input stream into
19 top-level PostScript tokens. Top-level means that the parser doesn't descend
20 into compound objects but rather treats them as single tokens. The compound
21 objects are listed below:
22
23 Object Delimiters
24 ------ ----------
25 string ( )
26 hex-encoded string < >
27 ASCII85-encoded string <~ ~>
28 dictionary << >>
29 array [ ]
30 procedure { }
31
32 Whitespace and comments (except the first one if it begins with %!) are
33 skipped by the tokenizer.
34
35 This library is initialized with a single call to pstNew() which allocates a
36 opaque context (pstCtx) which is passed to subsequent functions and is
37 destroyed by a single call to pstFree(). Thus, multiple contexts may be
38 concurrently allocated permitting operation in a multi-threaded environment.
39
40 Once a context has been allocated a client may begin the parse by calling
41 pstBegParse() which will open the source stream. The client may then call
42 the the pstGetToken() or pstFindToken() functions to tokenize the source
43 stream. Tokens are returned to the client as a type and a value
44 (length-delimited string). The value is not persistent and should be copied
45 by the client before the next token is read if it is needed later. The
46 client may call the pstConv*() functions to convert a token to a more usable
47 form when needed. Finally, the pstEndParse() function should be called to
48 close the input stream.
49
50 Memory management and data input are implemented by two sets of
51 client-supplied callback functions passed to pstNew().
52
53 Multiple PostScript streams may be parsed serially by opening and closing
54 new streams with calls pstBegParse() and pstEndParse(). */
55
56 typedef struct pstCtx_ *pstCtx;
57 pstCtx pstNew(ctlMemoryCallbacks *mem_cb, ctlStreamCallbacks *stm_cb,
58 int src_stream_id, CTL_CHECK_ARGS_DCL);
59
60 #define PST_CHECK_ARGS CTL_CHECK_ARGS_CALL(PST_VERSION)
61
62 /* pstNew() initializes the library and returns an opaque context (pstCtx) that
63 is subsequently passed to all the other library functions. It must be the
64 first function in the library to be called by the client. The client passes
65 sets of memory and stream callback functions (described in ctlshare.h) to
66 the library via the "mem_cb" and "stm_cb" parameters.
67
68 The PostScript source stream is identified by the "src_stream_id" parameter
69 which is passed back to the client when the source stream is opened.
70
71 The PST_CHECK_ARGS macro is passed as the last parameter to pstNew() in
72 order to perform a client/library compatibility check. pstNew() returns NULL
73 if it could not be initialized. */
74
75 int pstBegParse(pstCtx h, long origin);
76
77 /* pstBegParse() begins a new parse by opening the PostScript source stream
78 with the "src_stream_id" parameter that was passed to pstNew() and
79 positioning the stream at the offset specified by the "origin" parameter.
80 This stream is subsequently closed by calling pstBegParse(). This function
81 returns 0 if successful or an error code otherwise. */
82
83 int pstEndParse(pstCtx h);
84
85 /* pstEndParse() ends a parse begun with pstBegParse() by closing the
86 PostScript source stream. The client may serially parse multiple streams
87 with a sequence of pstBegParse() and pstEndParse() calls. This function
88 returns 0 if successful or an error code otherwise. */
89
90 int pstSetDecrypt(pstCtx h);
91
92 /* pstSetDecrypt() inserts an eexec decryption filter into the input stream so
93 that eexec encrypted PostScript tokens may be parsed. This would normally be
94 called after reading the operator token sequence "currentfile eexec". The
95 decryption filter may be removed by calling pstSetPlain(). This function
96 returns 0 if successful or an error code otherwise.
97
98 Note: calling this function inappropriately will result in garbage input
99 data being presented to the parser. */
100
101 int pstSetPlain(pstCtx h);
102
103 /* pstSetPlain() removes the decryption filter inserted by pstSetDecrypt(). It
104 is normally called after reading the operator token sequence "currentfile
105 closefile". The decryption sequence may be reinstalled by calling
106 pstSetDecrypt(). This function returns 0 if successful or an error code
107 otherwise. */
108
109 int pstRead(pstCtx h, size_t count, char **ptr);
110
111 /* pstRead() reads a number of bytes specified by the "count" parameter from
112 the source stream without interpreting stream as PostScript tokens. Bytes
113 are counted AFTER the decryption filter, if any, has been applied to the
114 source stream. This function is normally used to read binary data sections
115 in the input stream, charstrings, for example. This function returns 0 if
116 successful or an error code otherwise. */
117
118 typedef enum {
119 pstInteger, /* Integer number */
120 pstReal, /* Real number */
121 pstLiteral, /* /... */
122 pstImmediate, /* / /... */ /* really double slash - space between for cpplint */
123 pstString, /* ( ... ) */
124 pstHexString, /* < ... > */
125 pstASCII85, /* <~ ... ~> */
126 pstDictionary, /* << ... >> */
127 pstArray, /* [ ... ] */
128 pstProcedure, /* { ... } */
129 pstOperator, /* Executable name, i.e. not one of the above */
130 pstDocType, /* %!... (first line only) */
131 pstTokenCnt
132 } pstType;
133
134 /* Input token */
135 typedef struct
136 {
137 pstType type;
138 long length;
139 char *value;
140 } pstToken;
141
142 /* Several functions use the pstToken data type to describe a single PostScript
143 token. A token has a type, specified by the type field, which holds one of
144 the pstType enumerations, and a value, specified by the value and length
145 fields, including self-delimiting characters, if any.
146
147 The pstDocType token can only be returned if the first comment encountered
148 in the stream begins with "%!". The client can parse the token value in
149 order to determine the PostScript document type. */
150
151 int pstGetToken(pstCtx h, pstToken *token);
152
153 /* pstGetToken() reads the next token from the input stream. The token's value
154 field isn't guaranteed to be persistent and should be copied by the client
155 if its value is needed beyond the next pstGetToken() call. This function
156 returns 0 if successful or an error code otherwise. */
157
158 int pstFindToken(pstCtx h, pstToken *token, char *value);
159
160 /* pstFindToken() returns the next token in the input stream that matches the
161 token specified by the "value" parameter. If the matching token is found 0
162 is returned otherwise an error code is returned (most likely pstEndStream).
163 The value parameter is specified as a null-terminated string. */
164
165 int pstMatch(pstCtx h, pstToken *token, char *value);
166
167 /* pstMatchValue() returns 1 if the "token" parameter's value field matches the
168 null-terminated string specified by the "value" parameter, otherwise it
169 returns 0. The value parameter is specified as a null-terminated string. */
170
171 int32_t pstConvInteger(pstCtx h, pstToken *token);
172
173 /* pstConvInteger() converts the integer "token" parameter to an integer
174 number. If the token isn't an integer, 0 is returned. Integers requiring
175 more than 32 bits of precision may overflow on certain platforms. */
176
177 double pstConvReal(pstCtx h, pstToken *token);
178
179 /* pstConvReal() converts the real "token" parameter to a real number. If the
180 token isn't a real 0.0 is returned. See the strtod() standard C library
181 function for a description of the values returned on overflow or
182 underflow conditions. */
183
184 char *pstConvString(pstCtx h, pstToken *token, long *length);
185
186 /* pstConvString() forms a new string by removing the delimiters from the
187 string "token" parameter and returns a new pointer and length accordingly.
188 If the token isn't a string, NULL is returned. */
189
190 char *pstConvLiteral(pstCtx h, pstToken *token, long *length);
191
192 /* pstConvLiteral() forms a new string by removing the leading / from the
193 literal "token" parameter and returns a new pointer and length accordingly.
194 If the token isn't a literal, NULL is returned. */
195
196 uint32_t pstConvHexString(pstCtx h, pstToken *token);
197
198 /* pstConvHexString() converts the hexadecimal string "token" parameter to an
199 integer number. If the token isn't a hexadecimal string 0 is returned.
200 Converted hexadecimal strings requiring more than 32 bits of precision may
201 overflow on certain platforms. */
202
203 int pstGetHexLength(pstCtx h, pstToken *token);
204
205 /* pstGetHexLength() counts the number of hexadecimal digits in the hexadecimal
206 string "token" parameter. If the token isn't a hexadecimal string 0 is
207 returned. */
208
209 void *pstHijackStream(pstCtx h, long *offset);
210
211 /* pstHijackStream() returns the source stream and the current stream offset
212 via the "offset" parameter to the client. This permits the client to regain
213 control of the parsing process by directly reading bytes from the stream,
214 abandoning the tokenizing services offered by the library. Tokenizing of
215 the stream cannot be resumed after calling this function and therefore the
216 client can only call pstEndParse() when finished. NULL is returned if a
217 stream error is encountered.
218
219 This function is useful for handling CID-keyed fonts which begin with a
220 PostScript section followed by a large binary section. */
221
222 void pstSetDumpLevel(pstCtx h, int level);
223
224 /* pstSetDumpLevel() permits the client to control the dumping of PostScript
225 tokens to stdout as they are parsed via the "level" parameter. Setting a
226 "level" of 1 enables dumping and 0 disables dumping. */
227
228 void pstDumpToken(pstToken *token);
229
230 /* pstDumpToken() permits the client to print token type and value from the
231 "token" parameter on stdout. */
232
233 int pstFree(pstCtx h);
234
235 /* pstFree() destroys the library context and all the resources allocated to
236 it. It must be the last function called by a client of the library. */
237
238 enum {
239 #undef CTL_DCL_ERR
240 #define CTL_DCL_ERR(name, string) name,
241 #include "psterr.h"
242 pstErrCount
243 };
244
245 /* Library functions return either 0 to indicate success or a positive non-zero
246 error code that is defined in the above enumeration that is built from
247 psterr.h. */
248
249 char *pstErrStr(int err_code);
250
251 /* pstErrStr() maps the "err_code" parameter to a null-terminated error
252 string. */
253
254 void pstGetVersion(ctlVersionCallbacks *cb);
255
256 /* pstGetVersion() returns the library version number and name via the client
257 callbacks passed with the "cb" parameter (see ctlshare.h). */
258
259 #ifdef __cplusplus
260 }
261 #endif
262
263 #endif /* PSTOKEN_H */