| 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 */ |