| 1 |
% language=us engine=luatex runpath=texruns:manuals/luatex |
| 2 |
|
| 3 |
\environment luatex-style |
| 4 |
|
| 5 |
\startcomponent luatex-backend |
| 6 |
|
| 7 |
\startchapter[reference=backend,title={The backend libraries}] |
| 8 |
|
| 9 |
\startsection[title={The \type {pdf} library}][library=pdf] |
| 10 |
|
| 11 |
\topicindex{backend} |
| 12 |
\topicindex{\PDF} |
| 13 |
|
| 14 |
This library contains variables and functions that are related to the \PDF\ |
| 15 |
backend. You can find more details about the expected values to setters in \in |
| 16 |
{section} [backendprimitives]. |
| 17 |
|
| 18 |
\startsubsection[title={\type {mapfile}, \type {mapline}}] |
| 19 |
|
| 20 |
\topicindex{map files} |
| 21 |
\topicindex{files+map} |
| 22 |
|
| 23 |
\startfunctioncall |
| 24 |
pdf.mapfile(<string> map file) |
| 25 |
pdf.mapline(<string> map line) |
| 26 |
\stopfunctioncall |
| 27 |
|
| 28 |
These two functions can be used to replace primitives \orm {pdfmapfile} and |
| 29 |
\orm {pdfmapline} inherited from \PDFTEX. They expect a string as only |
| 30 |
parameter and have no return value. The first character in a map line can be |
| 31 |
\type {-}, \type {+} or \type {=} which means as much as remove, add or replace |
| 32 |
this line. They are not state setters but act immediately. |
| 33 |
|
| 34 |
\stopsubsection |
| 35 |
|
| 36 |
\startsubsection[title={\type {[set|get][catalog|info|names|trailer]}}] |
| 37 |
|
| 38 |
\topicindex{\PDF+trailer} |
| 39 |
\topicindex{\PDF+catalog} |
| 40 |
\topicindex{\PDF+info} |
| 41 |
|
| 42 |
\libindex{setcatalog} \libindex{getcatalog} |
| 43 |
\libindex{setinfo} \libindex{getinfo} |
| 44 |
\libindex{setnames} \libindex{getnames} |
| 45 |
\libindex{settrailer} \libindex{gettrailer} |
| 46 |
|
| 47 |
These functions complement the corresponding \PDF\ backend token lists dealing |
| 48 |
with metadata. The value types are strings and they are written to the \PDF\ |
| 49 |
file directly after the token registers set at the \TEX\ end are written. |
| 50 |
|
| 51 |
\stopsubsection |
| 52 |
|
| 53 |
\startsubsection[title={\type {[set|get][pageattributes|pageresources|pagesattributes]}}] |
| 54 |
|
| 55 |
\libindex{setpageattributes} \libindex{getpageattributes} |
| 56 |
\libindex{setpageresources} \libindex{getpageresources} |
| 57 |
\libindex{setpagesattributes} \libindex{getpagesattributes} |
| 58 |
|
| 59 |
\topicindex{\PDF+page attributes} |
| 60 |
\topicindex{\PDF+page resources} |
| 61 |
|
| 62 |
These functions complement the corresponding \PDF\ backend token lists dealing |
| 63 |
with page resources. The variables have no interaction with the corresponding \PDF\ |
| 64 |
backend token register. They are written to the \PDF\ file directly after the |
| 65 |
token registers set at the \TEX\ end are written. |
| 66 |
|
| 67 |
\stopsubsection |
| 68 |
|
| 69 |
\startsubsection[title={\type {[set|get][xformattributes|xformresources]}}] |
| 70 |
|
| 71 |
\libindex{setxformattributes} \libindex{getxformattributes} |
| 72 |
\libindex{setxformresources} \libindex{getxformresources} |
| 73 |
|
| 74 |
\topicindex{\PDF+xform attributes} |
| 75 |
\topicindex{\PDF+xform resources} |
| 76 |
|
| 77 |
These functions complement the corresponding \PDF\ backend token lists dealing |
| 78 |
with reuseable boxes and images. The variables have no interaction with the |
| 79 |
corresponding \PDF\ backend token register. They are written to the \PDF\ |
| 80 |
file directly after the token registers set at the \TEX\ end are written. |
| 81 |
|
| 82 |
\stopsubsection |
| 83 |
|
| 84 |
\startsubsection[title={\type {[set|get][major|minor]version}}] |
| 85 |
|
| 86 |
\topicindex{\PDF+version} |
| 87 |
|
| 88 |
\libindex{getmajorversion} \libindex{setmajorversion} |
| 89 |
\libindex{getminorversion} \libindex{setminorversion} |
| 90 |
|
| 91 |
You can set both the major and minor version of the output. The major version is |
| 92 |
normally~1 but when set to~2 some data will not be written to the file in order |
| 93 |
to comply with the standard. What minor version you set depends on what \PDF\ |
| 94 |
features you use. This is out of control of \LUATEX. |
| 95 |
|
| 96 |
One can set the major version number to~2 but we cannot guarantee that the engine |
| 97 |
adapts itself correctly, because there is no public and free specification that |
| 98 |
we know of. Also, user constructed annotations are not checked and just passed |
| 99 |
to the file. On the other hand, the \PDF\ that the engine generated is rather |
| 100 |
simple and not that version depending. |
| 101 |
|
| 102 |
\stopsubsection |
| 103 |
|
| 104 |
\startsubsection[title={\type {getcreationdate}}] |
| 105 |
|
| 106 |
\topicindex{\PDF+date} |
| 107 |
|
| 108 |
\libindex{getcreationdate} |
| 109 |
|
| 110 |
This function returns a string with the date in the format that ends up in the |
| 111 |
\PDF\ file, in this case it's: {\tttf \cldcontext{pdf.getcreationdate()}}. |
| 112 |
|
| 113 |
\stopsubsection |
| 114 |
|
| 115 |
\startsubsection[title={\type {[set|get]inclusionerrorlevel} and \type {[set|get]ignoreunknownimages}}] |
| 116 |
|
| 117 |
\topicindex{\PDF+options} |
| 118 |
|
| 119 |
\libindex{getinclusionerrorlevel} \libindex{setinclusionerrorlevel} |
| 120 |
\libindex{getignoreunknownimages} \libindex{setignoreunknownimages} |
| 121 |
|
| 122 |
These variable control how error in included image are treated. They are modeled |
| 123 |
after the \PDFTEX\ equivalents. |
| 124 |
|
| 125 |
\stopsubsection |
| 126 |
|
| 127 |
\startsubsection[title={\type {[set|get]suppressoptionalinfo}, \type {[set|get]trailerid}, |
| 128 |
\type {[set|get]omitcidset}, \type {[set|get]omitinfo}, \type {[set|get]omitmediabox}, |
| 129 |
\type {[set|get]omitprocset}, \type {[set|get]ptexprefix}} ] |
| 130 |
|
| 131 |
\topicindex{\PDF+options} |
| 132 |
\topicindex{\PDF+trailer} |
| 133 |
|
| 134 |
\libindex{getsuppressoptionalinfo} \libindex{setsuppressoptionalinfo} |
| 135 |
\libindex{gettrailerid} \libindex{settrailerid} |
| 136 |
\libindex{getomitcidset} \libindex{setomitcidset} |
| 137 |
\libindex{getomitcharset} \libindex{setomitcharset} |
| 138 |
\libindex{getomitinfo} \libindex{setomitinfo} |
| 139 |
\libindex{getomitmediabox} \libindex{setomitmediabox} |
| 140 |
\libindex{getomitprocset} \libindex{setomitprocset} |
| 141 |
\libindex{getptexprefix} \libindex{setptexprefix} |
| 142 |
|
| 143 |
The optional info bitset (a number) determines what kind of info gets flushed. |
| 144 |
By default we flush all. See \in {section} [sec:pdfextensions] for more details. |
| 145 |
|
| 146 |
You can set your own trailer id. This has to be string containing valid \PDF\ |
| 147 |
array content with checksums. |
| 148 |
|
| 149 |
The cidset, charset and info flags (numbers) disables inclusion of a so called |
| 150 |
\type {CIDSet} and \type {CharSet} entries, which can be handy when aiming at |
| 151 |
some of the many \PDF\ substandards. The same is true for the \type {ProcSet} and |
| 152 |
\type {PTEX} prefix where setting this flag will force the use of a \type {_} |
| 153 |
instead if a \type {.}. \footnote {In the info dictionary a period is valid pre |
| 154 |
version 2, but the underscore has to be used elsewhere. The prefix dates from the |
| 155 |
early days of \PDFTEX\ and at that time using a period was considered okay. Later |
| 156 |
specifications clarified this.} |
| 157 |
|
| 158 |
When it is omitted, one should provide the \type {MediaBox} via the page attribute |
| 159 |
options, because it is a mandate field. No checking is done. |
| 160 |
|
| 161 |
\stopsubsection |
| 162 |
|
| 163 |
\startsubsection[title={\type {[set|get][obj|]compresslevel} and \type {[set|get]recompress}}] |
| 164 |
|
| 165 |
\topicindex{\PDF+compression} |
| 166 |
|
| 167 |
\libindex{getcompresslevel} \libindex{setcompresslevel} |
| 168 |
\libindex{getobjcompresslevel} \libindex{setobjcompresslevel} |
| 169 |
\libindex{getrecompress} \libindex{setrecompress} |
| 170 |
|
| 171 |
These functions set the level stream compression. When object compression is |
| 172 |
enabled multiple objects will be packed in a compressed stream which saves space. |
| 173 |
The minimum values are~0, the maxima are~9. |
| 174 |
|
| 175 |
When recompression is to~1 compressed objects will be decompressed and when |
| 176 |
compresslevel is larger than zero they will then be recompressed. This is mostly |
| 177 |
a debugging feature and should not be relied upon. |
| 178 |
|
| 179 |
\stopsubsection |
| 180 |
|
| 181 |
\startsubsection[title={\type {[set|get]gentounicode}}] |
| 182 |
|
| 183 |
\topicindex{\PDF+unicode} |
| 184 |
|
| 185 |
\libindex{getgentounicode} \libindex{setgentounicode} |
| 186 |
|
| 187 |
This flag enables tounicode generation (like in \PDFTEX). Normally the values are |
| 188 |
provided by the font loader. |
| 189 |
|
| 190 |
\stopsubsection |
| 191 |
|
| 192 |
\startsubsection[title={\type {[set|get]decimaldigits}}] |
| 193 |
|
| 194 |
\topicindex{\PDF+precision} |
| 195 |
|
| 196 |
\libindex{getdecimaldigits} \libindex{setdecimaldigits} |
| 197 |
|
| 198 |
These two functions set the accuracy of floats written to the \PDF file. You can |
| 199 |
set any value but the backend will not go below~3 and above~6. |
| 200 |
|
| 201 |
\stopsubsection |
| 202 |
|
| 203 |
\startsubsection[title={\type {[set|get]pkresolution}}] |
| 204 |
|
| 205 |
\topicindex{\PDF+resolution} |
| 206 |
|
| 207 |
\libindex{getpkresolution} \libindex{setpkresolution} |
| 208 |
|
| 209 |
These setter takes two arguments: the resolution and an optional zero or one that |
| 210 |
indicates if this is a fixed one. The getter returns these two values. |
| 211 |
|
| 212 |
\stopsubsection |
| 213 |
|
| 214 |
\startsubsection[title={\type {getlast[obj|link|annot]} and \type {getretval}}] |
| 215 |
|
| 216 |
\topicindex{\PDF+objects} |
| 217 |
\topicindex{\PDF+annotations} |
| 218 |
|
| 219 |
\libindex{getlastobj} \libindex{setlastobj} |
| 220 |
\libindex{getlastlink} \libindex{setlastlink} |
| 221 |
\libindex{getlastannot} \libindex{setlastannot} |
| 222 |
\libindex{getretval} |
| 223 |
|
| 224 |
These status variables are similar to the ones traditionally used in the backend |
| 225 |
interface at the \TEX\ end. |
| 226 |
|
| 227 |
\stopsubsection |
| 228 |
|
| 229 |
\startsubsection[title={\type {getmaxobjnum} and \type {getobjtype}, \type {getfontname}, |
| 230 |
\type {getfontobjnum}, \type {getfontsize}, \type {getxformname}}] |
| 231 |
|
| 232 |
\libindex{getmaxobjnum} |
| 233 |
\libindex{getobjtype} |
| 234 |
\libindex{getfontname} |
| 235 |
\libindex{getfontobjnum} |
| 236 |
\libindex{getfontsize} |
| 237 |
\libindex{getxformname} |
| 238 |
|
| 239 |
These introspective helpers are mostly used when you construct \PDF\ objects |
| 240 |
yourself and need for instance information about a (to be) embedded font. |
| 241 |
|
| 242 |
\stopsubsection |
| 243 |
|
| 244 |
\startsubsection[title={\type {[set|get]origin}}] |
| 245 |
|
| 246 |
\topicindex{\PDF+positioning} |
| 247 |
|
| 248 |
\libindex{setorigin} \libindex{getorigin} |
| 249 |
|
| 250 |
This one is used to set the horizonal and|/|or vertical offset, a traditional |
| 251 |
backend property. |
| 252 |
|
| 253 |
\starttyping |
| 254 |
pdf.setorigin() -- sets both to 0pt |
| 255 |
pdf.setorigin(tex.sp("1in")) -- sets both to 1in |
| 256 |
pdf.setorigin(tex.sp("1in"),tex.sp("1in")) |
| 257 |
\stoptyping |
| 258 |
|
| 259 |
The counterpart of this function returns two values. |
| 260 |
|
| 261 |
\stopsubsection |
| 262 |
|
| 263 |
\startsubsection[title={\type {[set|get]imageresolution}}] |
| 264 |
|
| 265 |
\topicindex{\PDF+resolution} |
| 266 |
|
| 267 |
\libindex{setimageresolution} \libindex{getimageresolution} |
| 268 |
|
| 269 |
These two functions relate to the imageresolution that is used when the image |
| 270 |
itself doesn't provide a non|-|zero x or y resolution. |
| 271 |
|
| 272 |
\stopsubsection |
| 273 |
|
| 274 |
\startsubsection[title={\type {[set|get][link|dest|thread|xform]margin}}] |
| 275 |
|
| 276 |
\topicindex{\PDF+margins} |
| 277 |
|
| 278 |
\libindex{getlinkmargin} \libindex{setlinkmargin} |
| 279 |
\libindex{getdestmargin} \libindex{setdestmargin} |
| 280 |
\libindex{getthreadmargin} \libindex{setthreadmargin} |
| 281 |
\libindex{getxformmargin} \libindex{setxformmargin} |
| 282 |
\libindex{getmarginmargin} \libindex{setmarginmargin} |
| 283 |
|
| 284 |
These functions can be used to set and retrieve the margins that are added to the |
| 285 |
natural bounding boxes of the respective objects. |
| 286 |
|
| 287 |
\stopsubsection |
| 288 |
|
| 289 |
\startsubsection[title={\type {get[pos|hpos|vpos]}}] |
| 290 |
|
| 291 |
\topicindex{\PDF+positions} |
| 292 |
|
| 293 |
\libindex{getpos} |
| 294 |
\libindex{gethpos} |
| 295 |
\libindex{getvpos} |
| 296 |
|
| 297 |
These functions get current location on the output page, measured from its lower |
| 298 |
left corner. The values return scaled points as units. |
| 299 |
|
| 300 |
\starttyping |
| 301 |
local h, v = pdf.getpos() |
| 302 |
\stoptyping |
| 303 |
|
| 304 |
\stopsubsection |
| 305 |
|
| 306 |
\startsubsection[title={\type {[has|get]matrix}}] |
| 307 |
|
| 308 |
\topicindex{\PDF+matrix} |
| 309 |
|
| 310 |
\libindex{getmatrix} \libindex{hasmatrix} |
| 311 |
|
| 312 |
The current matrix transformation is available via the \type {getmatrix} command, |
| 313 |
which returns 6 values: \type {sx}, \type {rx}, \type {ry}, \type {sy}, \type |
| 314 |
{tx}, and \type {ty}. The \type {hasmatrix} function returns \type {true} when a |
| 315 |
matrix is applied. |
| 316 |
|
| 317 |
\starttyping |
| 318 |
if pdf.hasmatrix() then |
| 319 |
local sx, rx, ry, sy, tx, ty = pdf.getmatrix() |
| 320 |
-- do something useful or not |
| 321 |
end |
| 322 |
\stoptyping |
| 323 |
|
| 324 |
\stopsubsection |
| 325 |
|
| 326 |
\startsubsection[title={\type {print}}] |
| 327 |
|
| 328 |
\topicindex{\PDF+print to} |
| 329 |
|
| 330 |
\libindex{print} |
| 331 |
|
| 332 |
You can print a string to the \PDF\ document from within a \lpr {latelua} call. |
| 333 |
This function is not to be used inside \prm {directlua} unless you know {\it |
| 334 |
exactly} what you are doing. |
| 335 |
|
| 336 |
\startfunctioncall |
| 337 |
pdf.print(<string> s) |
| 338 |
pdf.print(<string> type, <string> s) |
| 339 |
\stopfunctioncall |
| 340 |
|
| 341 |
The optional parameter can be used to mimic the behavior of \PDF\ literals: the |
| 342 |
\type {type} is \type {direct} or \type {page}. |
| 343 |
|
| 344 |
\stopsubsection |
| 345 |
|
| 346 |
\startsubsection[title={\type {immediateobj}}] |
| 347 |
|
| 348 |
\topicindex{\PDF+objects} |
| 349 |
|
| 350 |
\libindex{immediateobj} |
| 351 |
|
| 352 |
This function creates a \PDF\ object and immediately writes it to the \PDF\ file. |
| 353 |
It is modelled after \PDFTEX's \prm {immediate} \orm {pdfobj} primitives. All |
| 354 |
function variants return the object number of the newly generated object. |
| 355 |
|
| 356 |
\startfunctioncall |
| 357 |
<number> n = |
| 358 |
pdf.immediateobj(<string> objtext) |
| 359 |
<number> n = |
| 360 |
pdf.immediateobj("file", <string> filename) |
| 361 |
<number> n = |
| 362 |
pdf.immediateobj("stream", <string> streamtext, <string> attrtext) |
| 363 |
<number> n = |
| 364 |
pdf.immediateobj("streamfile", <string> filename, <string> attrtext) |
| 365 |
\stopfunctioncall |
| 366 |
|
| 367 |
The first version puts the \type {objtext} raw into an object. Only the object |
| 368 |
wrapper is automatically generated, but any internal structure (like \type {<< |
| 369 |
>>} dictionary markers) needs to be provided by the user. The second version with |
| 370 |
keyword \type {file} as first argument puts the contents of the file with name |
| 371 |
\type {filename} raw into the object. The third version with keyword \type |
| 372 |
{stream} creates a stream object and puts the \type {streamtext} raw into the |
| 373 |
stream. The stream length is automatically calculated. The optional \type |
| 374 |
{attrtext} goes into the dictionary of that object. The fourth version with |
| 375 |
keyword \type {streamfile} does the same as the third one, it just reads the |
| 376 |
stream data raw from a file. |
| 377 |
|
| 378 |
An optional first argument can be given to make the function use a previously |
| 379 |
reserved \PDF\ object. |
| 380 |
|
| 381 |
\startfunctioncall |
| 382 |
<number> n = |
| 383 |
pdf.immediateobj(<integer> n, <string> objtext) |
| 384 |
<number> n = |
| 385 |
pdf.immediateobj(<integer> n, "file", <string> filename) |
| 386 |
<number> n = |
| 387 |
pdf.immediateobj(<integer> n, "stream", <string> streamtext, <string> attrtext) |
| 388 |
<number> n = |
| 389 |
pdf.immediateobj(<integer> n, "streamfile", <string> filename, <string> attrtext) |
| 390 |
\stopfunctioncall |
| 391 |
|
| 392 |
\stopsubsection |
| 393 |
|
| 394 |
\startsubsection[title={\type{obj}}] |
| 395 |
|
| 396 |
\topicindex{\PDF+objects} |
| 397 |
|
| 398 |
\libindex{obj} |
| 399 |
|
| 400 |
This function creates a \PDF\ object, which is written to the \PDF\ file only |
| 401 |
when referenced, e.g., by \type {refobj()}. |
| 402 |
|
| 403 |
All function variants return the object number of the newly generated object, and |
| 404 |
there are two separate calling modes. The first mode is modelled after \PDFTEX's |
| 405 |
\orm {pdfobj} primitive. |
| 406 |
|
| 407 |
\startfunctioncall |
| 408 |
<number> n = |
| 409 |
pdf.obj(<string> objtext) |
| 410 |
<number> n = |
| 411 |
pdf.obj("file", <string> filename) |
| 412 |
<number> n = |
| 413 |
pdf.obj("stream", <string> streamtext, <string> attrtext) |
| 414 |
<number> n = |
| 415 |
pdf.obj("streamfile", <string> filename, <string> attrtext) |
| 416 |
\stopfunctioncall |
| 417 |
|
| 418 |
An optional first argument can be given to make the function use a previously |
| 419 |
reserved \PDF\ object. |
| 420 |
|
| 421 |
\startfunctioncall |
| 422 |
<number> n = |
| 423 |
pdf.obj(<integer> n, <string> objtext) |
| 424 |
<number> n = |
| 425 |
pdf.obj(<integer> n, "file", <string> filename) |
| 426 |
<number> n = |
| 427 |
pdf.obj(<integer> n, "stream", <string> streamtext, <string> attrtext) |
| 428 |
<number> n = |
| 429 |
pdf.obj(<integer> n, "streamfile", <string> filename, <string> attrtext) |
| 430 |
\stopfunctioncall |
| 431 |
|
| 432 |
The second mode accepts a single argument table with key--value pairs. |
| 433 |
|
| 434 |
\startfunctioncall |
| 435 |
<number> n = pdf.obj { |
| 436 |
type = <string>, |
| 437 |
immediate = <boolean>, |
| 438 |
objnum = <number>, |
| 439 |
attr = <string>, |
| 440 |
compresslevel = <number>, |
| 441 |
objcompression = <boolean>, |
| 442 |
file = <string>, |
| 443 |
string = <string>, |
| 444 |
nolength = <boolean>, |
| 445 |
} |
| 446 |
\stopfunctioncall |
| 447 |
|
| 448 |
The \type {type} field can have the values \type {raw} and \type {stream}, this |
| 449 |
field is required, the others are optional (within constraints). When \type |
| 450 |
{nolength} is set, there will be no \type {/Length} entry added to the |
| 451 |
dictionary. |
| 452 |
|
| 453 |
Note: this mode makes \type{obj} look more flexible than it actually is: the |
| 454 |
constraints from the separate parameter version still apply, so for example you |
| 455 |
can't have both \type {string} and \type {file} at the same time. |
| 456 |
|
| 457 |
\stopsubsection |
| 458 |
|
| 459 |
\startsubsection[title={\type {refobj}}] |
| 460 |
|
| 461 |
\topicindex{\PDF+objects} |
| 462 |
|
| 463 |
\libindex{refobj} |
| 464 |
|
| 465 |
This function, the \LUA\ version of the \orm {pdfrefobj} primitive, references an |
| 466 |
object by its object number, so that the object will be written to the \PDF\ file. |
| 467 |
|
| 468 |
\startfunctioncall |
| 469 |
pdf.refobj(<integer> n) |
| 470 |
\stopfunctioncall |
| 471 |
|
| 472 |
This function works in both the \prm {directlua} and \lpr {latelua} environment. |
| 473 |
Inside \prm {directlua} a new whatsit node \quote {pdf_refobj} is created, which |
| 474 |
will be marked for flushing during page output and the object is then written |
| 475 |
directly after the page, when also the resources objects are written to the \PDF\ |
| 476 |
file. Inside \lpr {latelua} the object will be marked for flushing. |
| 477 |
|
| 478 |
This function has no return values. |
| 479 |
|
| 480 |
\stopsubsection |
| 481 |
|
| 482 |
\startsubsection[title={\type {reserveobj}}] |
| 483 |
|
| 484 |
\topicindex{\PDF+objects} |
| 485 |
|
| 486 |
\libindex{reserveobj} |
| 487 |
|
| 488 |
This function creates an empty \PDF\ object and returns its number. |
| 489 |
|
| 490 |
\startfunctioncall |
| 491 |
<number> n = pdf.reserveobj() |
| 492 |
<number> n = pdf.reserveobj("annot") |
| 493 |
\stopfunctioncall |
| 494 |
|
| 495 |
\stopsubsection |
| 496 |
|
| 497 |
\startsubsection[title={\type {getpageref}}] |
| 498 |
|
| 499 |
\topicindex{\PDF+pages} |
| 500 |
|
| 501 |
\libindex{getpageref} |
| 502 |
|
| 503 |
The object number of a page can be fetched with this function. This can be a |
| 504 |
forward reference so when you ask for a future page, you do get a number back. |
| 505 |
|
| 506 |
\startfunctioncall |
| 507 |
<number> n = pdf.getpageref(123) |
| 508 |
\stopfunctioncall |
| 509 |
|
| 510 |
\stopsubsection |
| 511 |
|
| 512 |
\startsubsection[title={\type {registerannot}}] |
| 513 |
|
| 514 |
\topicindex{\PDF+annotations} |
| 515 |
|
| 516 |
\libindex{registerannot} |
| 517 |
|
| 518 |
This function adds an object number to the \type {/Annots} array for the current |
| 519 |
page without doing anything else. This function can only be used from within |
| 520 |
\lpr {latelua}. |
| 521 |
|
| 522 |
\startfunctioncall |
| 523 |
pdf.registerannot (<number> objnum) |
| 524 |
\stopfunctioncall |
| 525 |
|
| 526 |
\stopsubsection |
| 527 |
|
| 528 |
\startsubsection[title={\type {newcolorstack}}] |
| 529 |
|
| 530 |
\topicindex{\PDF+color stack} |
| 531 |
|
| 532 |
\libindex{newcolorstack} |
| 533 |
|
| 534 |
This function allocates a new color stack and returns it's id. The arguments |
| 535 |
are the same as for the similar backend extension primitive. |
| 536 |
|
| 537 |
\startfunctioncall |
| 538 |
pdf.newcolorstack("0 g","page",true) -- page|direct|origin |
| 539 |
\stopfunctioncall |
| 540 |
|
| 541 |
\stopsubsection |
| 542 |
|
| 543 |
\startsubsection[title={\type {setfontattributes}}] |
| 544 |
|
| 545 |
\topicindex{\PDF+fonts} |
| 546 |
|
| 547 |
\libindex{setfontattributes} |
| 548 |
|
| 549 |
This function will force some additional code into the font resource. It can for |
| 550 |
instance be used to add a custom \type {ToUnicode} vector to a bitmap file. |
| 551 |
|
| 552 |
\startfunctioncall |
| 553 |
pdf.setfontattributes(<number> font id, <string> pdf code) |
| 554 |
\stopfunctioncall |
| 555 |
|
| 556 |
\stopsubsection |
| 557 |
|
| 558 |
\stopsection |
| 559 |
|
| 560 |
\startsection[title={The \type {pdfe} library}][library=pdfe] |
| 561 |
|
| 562 |
\startsubsection[title={Introduction}] |
| 563 |
|
| 564 |
\topicindex{\PDF+objects} |
| 565 |
|
| 566 |
\topicindex{\PDF+analyze} |
| 567 |
\topicindex{\PDF+\type{pdfe}} |
| 568 |
|
| 569 |
The \type {pdfe} library replaces the \type {epdf} library and provides an |
| 570 |
interface to \PDF\ files. It uses the same code as is used for \PDF\ image |
| 571 |
inclusion. The \type {pplib} library by Paweł Jackowski replaces the \type |
| 572 |
{poppler} (derived from \type {xpdf}) library. |
| 573 |
|
| 574 |
A \PDF\ file is basically a tree of objects and one descends into the tree via |
| 575 |
dictionaries (key/value) and arrays (index/value). There are a few topmost |
| 576 |
dictionaries that start at root that are accessed more directly. |
| 577 |
|
| 578 |
Although everything in \PDF\ is basically an object we only wrap a few in so |
| 579 |
called userdata \LUA\ objects. |
| 580 |
|
| 581 |
\starttabulate |
| 582 |
\BC \PDF \BC \LUA \NC \NR |
| 583 |
\NC null \NC nil \NC \NR |
| 584 |
\NC boolean \NC boolean \NC \NR |
| 585 |
\NC integer \NC integer \NC \NR |
| 586 |
\NC float \NC number \NC \NR |
| 587 |
\NC name \NC string \NC \NR |
| 588 |
\NC string \NC string \NC \NR |
| 589 |
\NC array \NC array userdatum \NC \NR |
| 590 |
\NC dictionary \NC dictionary userdatum \NC \NR |
| 591 |
\NC stream \NC stream userdatum (with related dictionary) \NC \NR |
| 592 |
\NC reference \NC reference userdatum \NC \NR |
| 593 |
\stoptabulate |
| 594 |
|
| 595 |
The regular getters return these \LUA\ data types but one can also get more |
| 596 |
detailed information. |
| 597 |
|
| 598 |
\stopsubsection |
| 599 |
|
| 600 |
\startsubsection[title={\type {open}, \type {new}, \type {getstatus}, \type {close}, \type {unencrypt}}] |
| 601 |
|
| 602 |
\libindex {open} |
| 603 |
\libindex {new} |
| 604 |
\libindex {new} |
| 605 |
\libindex {getstatus} |
| 606 |
\libindex {close} |
| 607 |
\libindex {unencrypt} |
| 608 |
|
| 609 |
A document is loaded from a file or string |
| 610 |
|
| 611 |
\starttyping |
| 612 |
<pdfe document> = pdfe.open(filename) |
| 613 |
<pdfe document> = pdfe.new(somestring,somelength) |
| 614 |
\stoptyping |
| 615 |
|
| 616 |
Such a document is closed with: |
| 617 |
|
| 618 |
\starttyping |
| 619 |
pdfe.close(<pdfe document>) |
| 620 |
\stoptyping |
| 621 |
|
| 622 |
You can check if a document opened well by: |
| 623 |
|
| 624 |
\starttyping |
| 625 |
pdfe.getstatus(<pdfe document>) |
| 626 |
\stoptyping |
| 627 |
|
| 628 |
The returned codes are: |
| 629 |
|
| 630 |
\starttabulate[|c|l|] |
| 631 |
\DB value \BC explanation \NC \NR |
| 632 |
\TB |
| 633 |
\NC \type {-2} \NC the document is (still) protected \NC \NR |
| 634 |
\NC \type {-1} \NC the document failed to open \NC \NR |
| 635 |
\NC \type {0} \NC the document is not encrypted \NC \NR |
| 636 |
\NC \type {1} \NC the document has been unencrypted \NC \NR |
| 637 |
\LL |
| 638 |
\stoptabulate |
| 639 |
|
| 640 |
An encrypted document can be unencrypted by the next command where instead of |
| 641 |
either password you can give \type {nil}: |
| 642 |
|
| 643 |
\starttyping |
| 644 |
pdfe.unencrypt(<pdfe document>,userpassword,ownerpassword) |
| 645 |
\stoptyping |
| 646 |
|
| 647 |
\stopsubsection |
| 648 |
|
| 649 |
\startsubsection[title={\type {getsize}, \type {getversion}, \type {getnofobjects}, \type {getnofpages}, \type{getmemoryusage}}] |
| 650 |
|
| 651 |
\libindex {getsize} |
| 652 |
\libindex {getversion} |
| 653 |
\libindex {getnofobjects} |
| 654 |
\libindex {getnofpages} |
| 655 |
\libindex {getmemoryusage} |
| 656 |
|
| 657 |
A successfully opened document can provide some information: |
| 658 |
|
| 659 |
\starttyping |
| 660 |
bytes = getsize(<pdfe document>) |
| 661 |
major, minor = getversion(<pdfe document>) |
| 662 |
n = getnofobjects(<pdfe document>) |
| 663 |
n = getnofpages(<pdfe document>) |
| 664 |
bytes, waste = getmemoryusage(<pdfe document>) |
| 665 |
\stoptyping |
| 666 |
|
| 667 |
\stopsubsection |
| 668 |
|
| 669 |
\startsubsection[title={\type {get[catalog|trailer|info]}}] |
| 670 |
|
| 671 |
\libindex {getcatalog} |
| 672 |
\libindex {gettrailer} |
| 673 |
\libindex {getinfo} |
| 674 |
|
| 675 |
For accessing the document structure you start with the so called catalog, a |
| 676 |
dictionary: |
| 677 |
|
| 678 |
\starttyping |
| 679 |
<pdfe dictionary> = pdfe.getcatalog(<pdfe document>) |
| 680 |
\stoptyping |
| 681 |
|
| 682 |
The other two root dictionaries are accessed with: |
| 683 |
|
| 684 |
\starttyping |
| 685 |
<pdfe dictionary> = pdfe.gettrailer(<pdfe document>) |
| 686 |
<pdfe dictionary> = pdfe.getinfo(<pdfe document>) |
| 687 |
\stoptyping |
| 688 |
|
| 689 |
\stopsubsection |
| 690 |
|
| 691 |
\startsubsection[title={\type {getpage}, \type {getbox}}] |
| 692 |
|
| 693 |
\libindex {getpage} |
| 694 |
\libindex {getbox} |
| 695 |
|
| 696 |
A specific page can conveniently be reached with the next command, which |
| 697 |
returns a dictionary. The first argument is to be a page dictionary. |
| 698 |
|
| 699 |
\starttyping |
| 700 |
<pdfe dictionary> = pdfe.getpage(<pdfe document>,pagenumber) |
| 701 |
\stoptyping |
| 702 |
|
| 703 |
Another convenience command gives you the (bounding) box of a (normally page) |
| 704 |
which can be inherited from the document itself. An example of a valid box name |
| 705 |
is \type {MediaBox}. |
| 706 |
|
| 707 |
\starttyping |
| 708 |
box_dimens <array> = pdfe.getbox(<pdfe dictionary>,boxname) |
| 709 |
\stoptyping |
| 710 |
|
| 711 |
\stopsubsection |
| 712 |
|
| 713 |
\startsubsection[title={\type {get[string|integer|number|boolean|name]}, \type{type}}] |
| 714 |
|
| 715 |
\libindex {getstring} |
| 716 |
\libindex {getinteger} |
| 717 |
\libindex {getnumber} |
| 718 |
\libindex {getboolean} |
| 719 |
\libindex {getname} |
| 720 |
\libindex {type} |
| 721 |
|
| 722 |
Common values in dictionaries and arrays are strings, integers, floats, booleans |
| 723 |
and names (which are also strings) and these are also normal \LUA\ objects: |
| 724 |
|
| 725 |
\starttyping |
| 726 |
s = getstring (<pdfe array|dictionary>,index|key) |
| 727 |
i = getinteger(<pdfe array|dictionary>,index|key) |
| 728 |
n = getnumber (<pdfe array|dictionary>,index|key) |
| 729 |
b = getboolean(<pdfe array|dictionary>,index|key) |
| 730 |
n = getname (<pdfe array|dictionary>,index|key) |
| 731 |
s = type (<pdfe array|dictionary|document|reference|stream) |
| 732 |
\stoptyping |
| 733 |
|
| 734 |
The \type {type} returns a string describing the type of the object, |
| 735 |
i.e. "pdfe.array", "pdfe.dictionary", "pdfe", |
| 736 |
"pdfe.reference", "pdfe.stream". |
| 737 |
|
| 738 |
The \type {getstring} function has two extra variants: |
| 739 |
|
| 740 |
\starttyping |
| 741 |
s, h = getstring (<pdfe array|dictionary>,index|key,false) |
| 742 |
s = getstring (<pdfe array|dictionary>,index|key,true) |
| 743 |
\stoptyping |
| 744 |
|
| 745 |
The first call returns the original string plus a boolean indicating if the |
| 746 |
string is hex encoded. The second call returns the unencoded string. |
| 747 |
|
| 748 |
\stopsubsection |
| 749 |
|
| 750 |
\startsubsection[title={\type {get[from][dictionary|array|stream]}}] |
| 751 |
|
| 752 |
\libindex {getdictionary} \libindex {getfromdictionary} |
| 753 |
\libindex {getarray} \libindex {getfromarray} |
| 754 |
\libindex {getstream} \libindex {getfromstream} |
| 755 |
|
| 756 |
Normally you will use an index in an array and key in a dictionary but dictionaries |
| 757 |
also accept an index. The size of an array or dictionary is available with the |
| 758 |
usual \type {#} operator. |
| 759 |
|
| 760 |
\starttyping |
| 761 |
<pdfe dictionary> = getdictionary(<pdfe array|dictionary>,index|key) |
| 762 |
<pdfe array> = getarray (<pdfe array|dictionary>,index|key) |
| 763 |
<pdfe stream>, |
| 764 |
<pdfe dictionary> = getstream (<pdfe array|dictionary>,index|key) |
| 765 |
\stoptyping |
| 766 |
|
| 767 |
These commands return dictionaries, arrays and streams, which are dictionaries |
| 768 |
with a blob of data attached. |
| 769 |
|
| 770 |
Before we come to an alternative access mode, we mention that the objects provide |
| 771 |
access in a different way too, for instance this is valid: |
| 772 |
|
| 773 |
\starttyping |
| 774 |
print(pdfe.open("foo.pdf").Catalog.Type) |
| 775 |
\stoptyping |
| 776 |
|
| 777 |
At the topmost level there are \type {Catalog}, \type {Info}, \type {Trailer} |
| 778 |
and \type {Pages}, so this is also okay: |
| 779 |
|
| 780 |
\starttyping |
| 781 |
print(pdfe.open("foo.pdf").Pages[1]) |
| 782 |
\stoptyping |
| 783 |
|
| 784 |
\stopsubsection |
| 785 |
|
| 786 |
\startsubsection[title={\type {[open|close|readfrom|whole|]stream}}] |
| 787 |
|
| 788 |
\libindex {openstream} |
| 789 |
\libindex {closestream} |
| 790 |
\libindex {readfromstream} |
| 791 |
\libindex {readfromwholestream} |
| 792 |
|
| 793 |
Streams are sort of special. When your index or key hits a stream you get back a |
| 794 |
stream object and dictionary object. The dictionary you can access in the usual |
| 795 |
way and for the stream there are the following methods: |
| 796 |
|
| 797 |
\starttyping |
| 798 |
okay = openstream(<pdfe stream>,[decode]) |
| 799 |
closestream(<pdfe stream>) |
| 800 |
str, n = readfromstream(<pdfe stream>) |
| 801 |
str, n = readwholestream(<pdfe stream>,[decode]) |
| 802 |
\stoptyping |
| 803 |
|
| 804 |
You either read in chunks, or you ask for the whole. When reading in chunks, you |
| 805 |
need to open and close the stream yourself. The \type {n} value indicates the |
| 806 |
length read. The \type {decode} parameter controls if the stream data gets |
| 807 |
uncompressed. |
| 808 |
|
| 809 |
As with dictionaries, you can access fields in a stream dictionary in the usual |
| 810 |
\LUA\ way too. You get the content when you \quote {call} the stream. You can |
| 811 |
pass a boolean that indicates if the stream has to be decompressed. |
| 812 |
|
| 813 |
% pdfe.objectcodes = objectcodes |
| 814 |
% pdfe.stringcodes = stringcodes |
| 815 |
% pdfe.encryptioncodes = encryptioncodes |
| 816 |
|
| 817 |
\stopsubsection |
| 818 |
|
| 819 |
\startsubsection[title={\type {getfrom[dictionary|array]}}] |
| 820 |
|
| 821 |
\libindex {getfromdictionary} |
| 822 |
\libindex {getfromarray} |
| 823 |
|
| 824 |
In addition to the interface described before, there is also a bit lower level |
| 825 |
interface available. |
| 826 |
|
| 827 |
\starttyping |
| 828 |
key, type, value, detail = getfromdictionary(<pdfe dictionary>,index) |
| 829 |
type, value, detail = getfromarray(<pdfe array>,index) |
| 830 |
\stoptyping |
| 831 |
|
| 832 |
\starttabulate[|c|l|l|l|] |
| 833 |
\DB type \BC meaning \BC value \BC detail \NC \NR |
| 834 |
\NC \type {0} \NC none \NC nil \NC \NC \NR |
| 835 |
\NC \type {1} \NC null \NC nil \NC \NC \NR |
| 836 |
\NC \type {2} \NC boolean \NC boolean \NC \NC \NR |
| 837 |
\NC \type {3} \NC integer \NC integer \NC \NC \NR |
| 838 |
\NC \type {4} \NC number \NC float \NC \NC \NR |
| 839 |
\NC \type {5} \NC name \NC string \NC \NC \NR |
| 840 |
\NC \type {6} \NC string \NC string \NC hex \NC \NR |
| 841 |
\NC \type {7} \NC array \NC arrayobject \NC size \NC \NR |
| 842 |
\NC \type {8} \NC dictionary \NC dictionaryobject \NC size \NC \NR |
| 843 |
\NC \type {9} \NC stream \NC streamobject \NC dictionary size \NC \NR |
| 844 |
\NC \type {10} \NC reference \NC integer \NC \NC \NR |
| 845 |
\LL |
| 846 |
\stoptabulate |
| 847 |
|
| 848 |
A \type {hex} string is (in the \PDF\ file) surrounded by \type {<>} while plain |
| 849 |
strings are bounded by \type {<>}. |
| 850 |
|
| 851 |
\stopsubsection |
| 852 |
|
| 853 |
\startsubsection[title={\type {[dictionary|array]totable}}] |
| 854 |
|
| 855 |
\libindex {dictionarytotable} |
| 856 |
\libindex {arraytotable} |
| 857 |
|
| 858 |
All entries in a dictionary or table can be fetched with the following commands |
| 859 |
where the return values are a hashed or indexed table. |
| 860 |
|
| 861 |
\starttyping |
| 862 |
hash = dictionarytotable(<pdfe dictionary>) |
| 863 |
list = arraytotable(<pdfe array>) |
| 864 |
\stoptyping |
| 865 |
|
| 866 |
You can get a list of pages with: |
| 867 |
|
| 868 |
\starttyping |
| 869 |
{ { <pdfe dictionary>, size, objnum }, ... } = pagestotable(<pdfe document>) |
| 870 |
\stoptyping |
| 871 |
|
| 872 |
\stopsubsection |
| 873 |
|
| 874 |
\startsubsection[title={\type {getfromreference}}] |
| 875 |
|
| 876 |
\libindex {getfromreference} |
| 877 |
|
| 878 |
Because you can have unresolved references, a reference object can be resolved |
| 879 |
with: |
| 880 |
|
| 881 |
\starttyping |
| 882 |
type, <pdfe dictionary|array|stream>, detail = getfromreference(<pdfe reference>) |
| 883 |
\stoptyping |
| 884 |
|
| 885 |
So, as second value you get back a new \type {pdfe} userdata object that you can |
| 886 |
query. |
| 887 |
|
| 888 |
\stopsubsection |
| 889 |
|
| 890 |
\stopsection |
| 891 |
|
| 892 |
\startsection[title={Memory streams}][library=pdfe] |
| 893 |
|
| 894 |
\topicindex{\PDF+memory streams} |
| 895 |
|
| 896 |
\libindex {new} |
| 897 |
|
| 898 |
The \type {pdfe.new} that takes three arguments: |
| 899 |
|
| 900 |
\starttabulate |
| 901 |
\DB value \BC explanation \NC \NR |
| 902 |
\TB |
| 903 |
\NC \type {stream} \NC this is a (in low level \LUA\ speak) light userdata |
| 904 |
object, i.e.\ a pointer to a sequence of bytes \NC \NR |
| 905 |
\NC \type {length} \NC this is the length of the stream in bytes (the stream can |
| 906 |
have embedded zeros) \NC \NR |
| 907 |
\NC \type {name} \NC optional, this is a unique identifier that is used for |
| 908 |
hashing the stream, so that multiple doesn't use more |
| 909 |
memory \NC \NR |
| 910 |
\LL |
| 911 |
\stoptabulate |
| 912 |
|
| 913 |
The third argument is optional. When it is not given the function will return an |
| 914 |
\type {pdfe} document object as with a regular file, otherwise it will return a |
| 915 |
filename that can be used elsewhere (e.g.\ in the image library) to reference the |
| 916 |
stream as pseudo file. |
| 917 |
|
| 918 |
Instead of a light userdata stream (which is actually fragile but handy when you |
| 919 |
come from a library) you can also pass a \LUA\ string, in which case the given |
| 920 |
length is (at most) the string length. |
| 921 |
|
| 922 |
The function returns an \type {pdfe} object and a string. The string can be used in |
| 923 |
the \type {img} library instead of a filename. You need to prevent garbage |
| 924 |
collection of the object when you use it as image (for instance by storing it |
| 925 |
somewhere). |
| 926 |
|
| 927 |
Both the memory stream and it's use in the image library is experimental and can |
| 928 |
change. In case you wonder where this can be used: when you use the swiglib |
| 929 |
library for \type {graphicmagick}, it can return such a userdata object. This |
| 930 |
permits conversion in memory and passing the result directly to the backend. This |
| 931 |
might save some runtime in one|-|pass workflows. This feature is currently not |
| 932 |
meant for production and we might come up with a better implementation. |
| 933 |
|
| 934 |
\stopsection |
| 935 |
|
| 936 |
\startsection[title={The \type {pdfscanner} library}][library=pdfscanner] |
| 937 |
|
| 938 |
\topicindex{\PDF+scanner} |
| 939 |
|
| 940 |
\libindex {scan} |
| 941 |
|
| 942 |
The \type {pdfscanner} library allows interpretation of \PDF\ content streams and |
| 943 |
\type {/ToUnicode} (cmap) streams. You can get those streams from the \type |
| 944 |
{pdfe} library, as explained in an earlier section. There is only a single |
| 945 |
top|-|level function in this library: |
| 946 |
|
| 947 |
\startfunctioncall |
| 948 |
pdfscanner.scan (<pdfe stream>, <table> operatortable, <table> info) |
| 949 |
pdfscanner.scan (<pdfe array>, <table> operatortable, <table> info) |
| 950 |
pdfscanner.scan (<string>, <table> operatortable, <table> info) |
| 951 |
\stopfunctioncall |
| 952 |
|
| 953 |
The first argument should be a \LUA\ string or a stream or array object coming |
| 954 |
from the \type {pdfe} library. The second argument, \type {operatortable}, should |
| 955 |
be a \LUA\ table where the keys are \PDF\ operator name strings and the values |
| 956 |
are \LUA\ functions (defined by you) that are used to process those operators. |
| 957 |
The functions are called whenever the scanner finds one of these \PDF\ operators |
| 958 |
in the content stream(s). The functions are called with two arguments: the \type |
| 959 |
{scanner} object itself, and the \type {info} table that was passed are the third |
| 960 |
argument to \type {pdfscanner.scan}. |
| 961 |
|
| 962 |
Internally, \type {pdfscanner.scan} loops over the \PDF\ operators in the |
| 963 |
stream(s), collecting operands on an internal stack until it finds a \PDF\ |
| 964 |
operator. If that \PDF\ operator's name exists in \type {operatortable}, then the |
| 965 |
associated function is executed. After the function has run (or when there is no |
| 966 |
function to execute) the internal operand stack is cleared in preparation for the |
| 967 |
next operator, and processing continues. |
| 968 |
|
| 969 |
The \type {scanner} argument to the processing functions is needed because it |
| 970 |
offers various methods to get the actual operands from the internal operand |
| 971 |
stack. |
| 972 |
|
| 973 |
A simple example of processing a \PDF's document stream could look like this: |
| 974 |
|
| 975 |
\starttyping |
| 976 |
local operatortable = { } |
| 977 |
|
| 978 |
operatortable.Do = function(scanner,info) |
| 979 |
local resources = info.resources |
| 980 |
if resources then |
| 981 |
local val = scanner:pop() |
| 982 |
local name = val[2] |
| 983 |
local xobject = resources.XObject |
| 984 |
print(info.space .. "Uses XObject " .. name) |
| 985 |
local resources = xobject.Resources |
| 986 |
if resources then |
| 987 |
local newinfo = { |
| 988 |
space = info.space .. " ", |
| 989 |
resources = resources, |
| 990 |
} |
| 991 |
pdfscanner.scan(entry, operatortable, newinfo) |
| 992 |
end |
| 993 |
end |
| 994 |
end |
| 995 |
|
| 996 |
local function Analyze(filename) |
| 997 |
local doc = pdfe.open(filename) |
| 998 |
if doc then |
| 999 |
local pages = doc.Pages |
| 1000 |
for i=1,#pages do |
| 1001 |
local page = pages[i] |
| 1002 |
local info = { |
| 1003 |
space = " " , |
| 1004 |
resources = page.Resources, |
| 1005 |
} |
| 1006 |
print("Page " .. i) |
| 1007 |
-- pdfscanner.scan(page.Contents,operatortable,info) |
| 1008 |
pdfscanner.scan(page.Contents(),operatortable,info) |
| 1009 |
end |
| 1010 |
end |
| 1011 |
end |
| 1012 |
|
| 1013 |
Analyze("foo.pdf") |
| 1014 |
\stoptyping |
| 1015 |
|
| 1016 |
This example iterates over all the actual content in the \PDF, and prints out the |
| 1017 |
found \type {XObject} names. While the code demonstrates quite some of the \type |
| 1018 |
{pdfe} functions, let's focus on the type \type {pdfscanner} specific code |
| 1019 |
instead. |
| 1020 |
|
| 1021 |
From the bottom up, the following line runs the scanner with the \PDF\ page's |
| 1022 |
top|-|level content given in the first argument. |
| 1023 |
|
| 1024 |
The third argument, \type {info}, contains two entries: \type {space} is used to |
| 1025 |
indent the printed output, and \type {resources} is needed so that embedded \type |
| 1026 |
{XForms} can find their own content. |
| 1027 |
|
| 1028 |
The second argument, \type {operatortable} defines a processing function for a |
| 1029 |
single \PDF\ operator, \type {Do}. |
| 1030 |
|
| 1031 |
The function \type {Do} prints the name of the current \type {XObject}, and then |
| 1032 |
starts a new scanner for that object's content stream, under the condition that |
| 1033 |
the \type {XObject} is in fact a \type {/Form}. That nested scanner is called |
| 1034 |
with new \type {info} argument with an updated \type {space} value so that the |
| 1035 |
indentation of the output nicely nests, and with a new \type {resources} field |
| 1036 |
to help the next iteration down to properly process any other, embedded \type |
| 1037 |
{XObject}s. |
| 1038 |
|
| 1039 |
Of course, this is not a very useful example in practice, but for the purpose of |
| 1040 |
demonstrating \type {pdfscanner}, it is just long enough. It makes use of only |
| 1041 |
one \type {scanner} method: \type {scanner:pop()}. That function pops the top |
| 1042 |
operand of the internal stack, and returns a \LUA\ table where the object at index |
| 1043 |
one is a string representing the type of the operand, and object two is its |
| 1044 |
value. |
| 1045 |
|
| 1046 |
The list of possible operand types and associated \LUA\ value types is: |
| 1047 |
|
| 1048 |
\starttabulate[|l|l|] |
| 1049 |
\DB types \BC type \NC \NR |
| 1050 |
\TB |
| 1051 |
\NC \type{integer} \NC <number> \NC \NR |
| 1052 |
\NC \type{real} \NC <number> \NC \NR |
| 1053 |
\NC \type{boolean} \NC <boolean> \NC \NR |
| 1054 |
\NC \type{name} \NC <string> \NC \NR |
| 1055 |
\NC \type{operator} \NC <string> \NC \NR |
| 1056 |
\NC \type{string} \NC <string> \NC \NR |
| 1057 |
\NC \type{array} \NC <table> \NC \NR |
| 1058 |
\NC \type{dict} \NC <table> \NC \NR |
| 1059 |
\LL |
| 1060 |
\stoptabulate |
| 1061 |
|
| 1062 |
In case of \type {integer} or \type {real}, the value is always a \LUA\ (floating |
| 1063 |
point) number. In case of \type {name}, the leading slash is always stripped. |
| 1064 |
|
| 1065 |
In case of \type {string}, please bear in mind that \PDF\ actually supports |
| 1066 |
different types of strings (with different encodings) in different parts of the |
| 1067 |
\PDF\ document, so you may need to reencode some of the results; \type {pdfscanner} |
| 1068 |
always outputs the byte stream without reencoding anything. \type {pdfscanner} |
| 1069 |
does not differentiate between literal strings and hexadecimal strings (the |
| 1070 |
hexadecimal values are decoded), and it treats the stream data for inline images |
| 1071 |
as a string that is the single operand for \type {EI}. |
| 1072 |
|
| 1073 |
In case of \type {array}, the table content is a list of \type {pop} return |
| 1074 |
values and in case of \type {dict}, the table keys are \PDF\ name strings and the |
| 1075 |
values are \type {pop} return values. |
| 1076 |
|
| 1077 |
\libindex{pop} |
| 1078 |
\libindex{popnumber} |
| 1079 |
\libindex{popname} |
| 1080 |
\libindex{popstring} |
| 1081 |
\libindex{poparray} |
| 1082 |
\libindex{popdictionary} |
| 1083 |
\libindex{popboolean} |
| 1084 |
\libindex{done} |
| 1085 |
|
| 1086 |
There are a few more methods defined that you can ask \type {scanner}: |
| 1087 |
|
| 1088 |
\starttabulate[|l|p|] |
| 1089 |
\DB method \BC explanation \NC \NR |
| 1090 |
\TB |
| 1091 |
\NC \type{pop} \NC see above \NC \NR |
| 1092 |
\NC \type{popnumber} \NC return only the value of a \type {real} or \type {integer} \NC \NR |
| 1093 |
\NC \type{popname} \NC return only the value of a \type {name} \NC \NR |
| 1094 |
\NC \type{popstring} \NC return only the value of a \type {string} \NC \NR |
| 1095 |
\NC \type{poparray} \NC return only the value of a \type {array} \NC \NR |
| 1096 |
\NC \type{popdictionary} \NC return only the value of a \type {dict} \NC \NR |
| 1097 |
\NC \type{popboolean} \NC return only the value of a \type {boolean} \NC \NR |
| 1098 |
\NC \type{done} \NC abort further processing of this \type {scan()} call \NC \NR |
| 1099 |
\LL |
| 1100 |
\stoptabulate |
| 1101 |
|
| 1102 |
The \type {pop*} are convenience functions, and come in handy when you know the |
| 1103 |
type of the operands beforehand (which you usually do, in \PDF). For example, the |
| 1104 |
\type {Do} function could have used \type {local name = scanner:popname()} |
| 1105 |
instead, because the single operand to the \type {Do} operator is always a \PDF\ |
| 1106 |
name object. |
| 1107 |
|
| 1108 |
The \type {done} function allows you to abort processing of a stream once you |
| 1109 |
have learned everything you want to learn. This comes in handy while parsing |
| 1110 |
\type {/ToUnicode}, because there usually is trailing garbage that you are not |
| 1111 |
interested in. Without \type {done}, processing only ends at the end of the |
| 1112 |
stream, possibly wasting \CPU\ cycles. |
| 1113 |
|
| 1114 |
{\em We keep the older names \type {popNumber}, \type {popName}, \type |
| 1115 |
{popString}, \type {popArray}, \type {popDict} and \type {popBool} around.} |
| 1116 |
|
| 1117 |
\stopsection |
| 1118 |
|
| 1119 |
\stopchapter |
| 1120 |
|
| 1121 |
\stopcomponent |