Debian Codegraph @

texmf-dist/doc/luatex/base/luatex-backend.tex

raw
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