manual/luatex-backend.tex

   1 % language=uk
   2
   3 \environment luatex-style
   4 \environment luatex-logos
   5
   6 \startcomponent luatex-backend
   7
   8 \startchapter[reference=backend,title={The backend libraries}]
   9
  10 \section{The \type {pdf} library}
  11
  12 This contains variables and functions that are related to the \PDF\ backend.
  13
  14 \subsection{\type {pdf.mapfile}, \type {pdf.mapline}}
  15
  16 \startfunctioncall
  17 pdf.mapfile(<string> map file)
  18 pdf.mapline(<string> map line)
  19 \stopfunctioncall
  20
  21 These two functions can be used to replace primitives \type {\pdfmapfile} and
  22 \type {\pdfmapline} from \PDFTEX. They expect a string as only parameter and have
  23 no return value.
  24
  25 The also functions replace the former variables \type {pdf.pdfmapfile} and
  26 \type {pdf.pdfmapline}.
  27
  28 \subsection{\type {pdf.catalog}, \type {pdf.info},\type {pdf.names},
  29     \type {pdf.trailer}}
  30
  31 These variables offer a read|-|write interface to the corresponding \PDFTEX\
  32 token lists. The value types are strings and they are written out to the \PDF\
  33 file directly after the \PDFTEX\ token registers.
  34
  35 The preferred interface is now \type {pdf.setcatalog}, \type {pdf.setinfo}
  36 \type {pdf.setnames} and \type {pdf.settrailer} for setting these properties
  37 and \type {pdf.getcatalog}, \type {pdf.getinfo} \type {pdf.getnames} and
  38 \type {pdf.gettrailer} for querying them,
  39
  40 The corresponding \quote {\type {pdf}} parameter names \type {pdf.pdfcatalog},
  41 \type {pdf.pdfinfo}, \type {pdf.pdfnames}, and \type {pdf.pdftrailer} are
  42 not available.
  43
  44 \subsection{\type {pdf.<set/get>pageattributes}, \type {pdf.<set/get>pageresources},
  45     \type {pdf.<set/get>pagesattributes}}
  46
  47 These variables offer a read|-|write interface to related token lists. The value
  48 types are strings. The variables have no interaction with the corresponding
  49 \PDFTEX\ token registers \type {\pdfpageattr}, \type {\pdfpageresources}, and \type
  50 {\pdfpagesattr}. They are written out to the \PDF\ file directly after the
  51 \PDFTEX\ token registers.
  52
  53 The preferred interface is now \type {pdf.setpageattributes}, \type
  54 {pdf.setpagesattributes} and \type {pdf.setpageresources} for setting these
  55 properties and \type {pdf.getpageattributes}, \type {pdf.getpageattributes}
  56 and \type {pdf.getpageresources} for querying them.
  57
  58 \subsection{\type {pdf.<set/get>xformattributes}, \type {pdf.<set/get>xformresources}}
  59
  60 These variables offer a read|-|write interface to related token lists. The value
  61 types are strings. The variables have no interaction with the corresponding
  62 \PDFTEX\ token registers \type {\pdfxformattr} and \type {\pdfxformresources}. They
  63 are written out to the \PDF\ file directly after the \PDFTEX\ token registers.
  64
  65 The preferred interface is now \type {pdf.setxformattributes} and \type
  66 {pdf.setxformattributes} for setting these properties and \type
  67 {pdf.getxformattributes} and \type {pdf.getxformresources} for querying them.
  68
  69 \subsection{\type {pdf.setcompresslevel} and \type {pdf.setobjcompresslevel}}
  70
  71 These two functions set the level of compression. The minimum valu sis~0,
  72 the maximum is~9.
  73
  74 \subsection{\type {pdf.setdecimaldigits} and \type {pdf.getdecimaldigits}}
  75
  76 These two functions set the accuracy of floats written to the \PDF file. You can
  77 set any value but the backend will not go below 3 and above 6.
  78
  79 \subsection{\type {pdf.setpkresolution} and \type {pdf.getpkresolution}}
  80
  81 These setter takes two arguments: the resolution and an optional zero or one that
  82 indicates if this is a fixed one. The getter returns these two values.
  83
  84 \subsection{\type {pdf.lastobj}, \type {pdf.lastlink}, \type {pdf.lastannot},
  85 and \type {pdf.retval}}
  86
  87 These status variables are similar to the ones traditionally used at the \TEX\
  88 end.
  89
  90 \subsection{\type {pdf.setorigin}, \type {pdf.getorigin}}
  91
  92 This one is used to set the horizonal and/or vertical offset (a traditional
  93 backend property).
  94
  95 \starttyping
  96 pdf.setorigin() -- sets both to 0pt
  97 pdf.setorigin(tex.sp("1in")) -- sets both to 1in
  98 pdf.setorigin(tex.sp("1in"),tex.sp("1in"))
  99 \stoptyping
 100
 101 The counterpart of this function returns two values.
 102
 103 \subsection{\type {pdf.setlinkmargin}, \type {pdf.getlinkmargin} \type
 104 {pdf.setdestmargin}, \type {pdf.getdestmargin} \type {pdf.setthreadmargin},
 105 \type {pdf.getthreadmargin} \type {pdf.setxformmargin}, \type
 106 {pdf.getxformmargin}}
 107
 108 These function can be used to set and retrieve the margins that are added to the
 109 natural bounding boxes of the respective objects.
 110
 111 \subsection{\type {pdf.h}, \type {pdf.v}}
 112
 113 These are the \type {h} and \type {v} values that define the current location on
 114 the output page, measured from its lower left corner. The values can be queried
 115 using scaled points as units.
 116
 117 \starttyping
 118 local h = pdf.h
 119 local v = pdf.v
 120 \stoptyping
 121
 122 \subsection{\type {pdf.getpos}, \type {pdf.gethpos}, \type {pdf.getvpos}}
 123
 124 These are the function variants of \type {pdf.h} and \type {pdf.v}. Sometimes
 125 using a function is preferred over a key so this saves wrapping. Also, these
 126 functions are faster then the key based access, as \type {h} and \type {v} keys
 127 are not real variables but looked up using a metatable call. The \type {getpos}
 128 function returns two values, the other return one.
 129
 130 \starttyping
 131 local h, v = pdf.getpos()
 132 \stoptyping
 133
 134 \subsection{\type {pdf.hasmatrix}, \type {pdf.getmatrix}}
 135
 136 The current matrix transformation is available via the \type {getmatrix} command,
 137 which returns 6 values: \type {sx}, \type {rx}, \type {ry}, \type {sy}, \type
 138 {tx}, and \type {ty}. The \type {hasmatrix} function returns \type {true} when a
 139 matrix is applied.
 140
 141 \starttyping
 142 if pdf.hasmatrix() then
 143     local sx, rx, ry, sy, tx, ty = pdf.getmatrix()
 144     -- do something useful or not
 145 end
 146 \stoptyping
 147
 148 \subsection{\type {pdf.print}}
 149
 150 A print function to write stuff to the \PDF\ document that can be used from
 151 within a \type {\latelua} argument. This function is not to be used inside
 152 \type {\directlua} unless you know {\it exactly} what you are doing.
 153
 154 \startfunctioncall
 155 pdf.print(<string> s)
 156 pdf.print(<string> type, <string> s)
 157 \stopfunctioncall
 158
 159 The optional parameter can be used to mimic the behavior of \type {\pdfliteral}:
 160 the \type {type} is \type {direct} or \type {page}.
 161
 162 \subsection{\type {pdf.immediateobj}}
 163
 164 This function creates a \PDF\ object and immediately writes it to the \PDF\ file.
 165 It is modelled after \PDFTEX's \type {\immediate} \type {\pdfobj} primitives. All
 166 function variants return the object number of the newly generated object.
 167
 168 \startfunctioncall
 169 <number> n = pdf.immediateobj(<string> objtext)
 170 <number> n = pdf.immediateobj("file", <string> filename)
 171 <number> n = pdf.immediateobj("stream", <string> streamtext, <string> attrtext)
 172 <number> n = pdf.immediateobj("streamfile", <string> filename, <string> attrtext)
 173 \stopfunctioncall
 174
 175 The first version puts the \type {objtext} raw into an object. Only the object
 176 wrapper is automatically generated, but any internal structure (like \type {<<
 177 >>} dictionary markers) needs to provided by the user. The second version with
 178 keyword \type {"file"} as 1st argument puts the contents of the file with name
 179 \type {filename} raw into the object. The third version with keyword \type
 180 {"stream"} creates a stream object and puts the \type {streamtext} raw into the
 181 stream. The stream length is automatically calculated. The optional \type
 182 {attrtext} goes into the dictionary of that object. The fourth version with
 183 keyword \type {"streamfile"} does the same as the 3rd one, it just reads the
 184 stream data raw from a file.
 185
 186 An optional first argument can be given to make the function use a previously
 187 reserved \PDF\ object.
 188
 189 \startfunctioncall
 190 <number> n = pdf.immediateobj(<integer> n, <string> objtext)
 191 <number> n = pdf.immediateobj(<integer> n, "file", <string> filename)
 192 <number> n = pdf.immediateobj(<integer> n, "stream", <string> streamtext, <string> attrtext)
 193 <number> n = pdf.immediateobj(<integer> n, "streamfile", <string> filename, <string> attrtext)
 194 \stopfunctioncall
 195
 196 \subsection{\type {pdf.obj}}
 197
 198 This function creates a \PDF\ object, which is written to the \PDF\ file only
 199 when referenced, e.g., by \type {pdf.refobj()}.
 200
 201 All function variants return the object number of the newly generated object, and
 202 there are two separate calling modes.
 203
 204 The first mode is modelled after \PDFTEX's \type {\pdfobj} primitive.
 205
 206 \startfunctioncall
 207 <number> n = pdf.obj(<string> objtext)
 208 <number> n = pdf.obj("file", <string> filename)
 209 <number> n = pdf.obj("stream", <string> streamtext, <string> attrtext)
 210 <number> n = pdf.obj("streamfile", <string> filename, <string> attrtext)
 211 \stopfunctioncall
 212
 213 An optional first argument can be given to make the function use a previously
 214 reserved \PDF\ object.
 215
 216 \startfunctioncall
 217 <number> n = pdf.obj(<integer> n, <string> objtext)
 218 <number> n = pdf.obj(<integer> n, "file", <string> filename)
 219 <number> n = pdf.obj(<integer> n, "stream", <string> streamtext, <string> attrtext)
 220 <number> n = pdf.obj(<integer> n, "streamfile", <string> filename, <string> attrtext)
 221 \stopfunctioncall
 222
 223 The second mode accepts a single argument table with key--value pairs.
 224
 225 \startfunctioncall
 226 <number> n = pdf.obj {
 227     type           = <string>,
 228     immmediate     = <boolean>,
 229     objnum         = <number>,
 230     attr           = <string>,
 231     compresslevel  = <number>,
 232     objcompression = <boolean>,
 233     file           = <string>,
 234     string         = <string>
 235 }
 236 \stopfunctioncall
 237
 238 The \type {type} field can have the values \type {raw} and \type {stream}, this
 239 field is required, the others are optional (within constraints).
 240
 241 Note: this mode makes \type {pdf.obj} look more flexible than it actually is: the
 242 constraints from the separate parameter version still apply, so for example you
 243 can't have both \type {string} and \type {file} at the same time.
 244
 245 \subsection{\type {pdf.refobj}}
 246
 247 This function, the \LUA\ version of the \type {\pdfrefobj} primitive, references an
 248 object by its object number, so that the object will be written out.
 249
 250 \startfunctioncall
 251 pdf.refobj(<integer> n)
 252 \stopfunctioncall
 253
 254 This function works in both the \type {\directlua} and \type {\latelua} environment.
 255 Inside \type {\directlua} a new whatsit node \quote {pdf_refobj} is created, which
 256 will be marked for flushing during page output and the object is then written
 257 directly after the page, when also the resources objects are written out. Inside
 258 \type {\latelua} the object will be marked for flushing.
 259
 260 This function has no return values.
 261
 262 \subsection{\type {pdf.reserveobj}}
 263
 264 This function creates an empty \PDF\ object and returns its number.
 265
 266 \startfunctioncall
 267 <number> n = pdf.reserveobj()
 268 <number> n = pdf.reserveobj("annot")
 269 \stopfunctioncall
 270
 271 \subsection{\type {pdf.registerannot}}
 272
 273 This function adds an object number to the \type {/Annots} array for the current
 274 page without doing anything else. This function can only be used from within
 275 \type {\latelua}.
 276
 277 \startfunctioncall
 278 pdf.registerannot (<number> objnum)
 279 \stopfunctioncall
 280
 281 \subsection{\type {pdf.newcolorstack}}
 282
 283 This function allocates a new color stack and returns it's id. The arguments
 284 are the same as for the similar backend extension primitive.
 285
 286 \startfunctioncall
 287 pdf.newcolorstack("0 g","page",true) -- page|direct|origin
 288 \stopfunctioncall
 289
 290 \section{The \type {pdfscanner} library}
 291
 292 The \type {pdfscanner} library allows interpretation of PDF content streams and
 293 \type {/ToUnicode} (cmap) streams. You can get those streams from the \type
 294 {epdf} library, as explained in an earlier section. There is only a single
 295 top|-|level function in this library:
 296
 297 \startfunctioncall
 298 pdfscanner.scan (<Object> stream, <table> operatortable, <table> info)
 299 \stopfunctioncall
 300
 301 The first argument, \type {stream}, should be either a PDF stream object, or a
 302 PDF array of PDF stream objects (those options comprise the possible return
 303 values of \type {<Page>:getContents()} and \type {<Object>:getStream()} in the
 304 \type {epdf} library).
 305
 306 The second argument, \type {operatortable}, should be a Lua table where the keys
 307 are PDF operator name strings and the values are Lua functions (defined by you)
 308 that are used to process those operators. The functions are called whenever the
 309 scanner finds one of these PDF operators in the content stream(s). The functions
 310 are called with two arguments: the \type {scanner} object itself, and the \type
 311 {info} table that was passed are the third argument to \type {pdfscanner.scan}.
 312
 313 Internally, \type {pdfscanner.scan} loops over the PDF operators in the
 314 stream(s), collecting operands on an internal stack until it finds a PDF
 315 operator. If that PDF operator's name exists in \type {operatortable}, then the
 316 associated function is executed. After the function has run (or when there is no
 317 function to execute) the internal operand stack is cleared in preparation for the
 318 next operator, and processing continues.
 319
 320 The \type {scanner} argument to the processing functions is needed because it
 321 offers various methods to get the actual operands from the internal operand
 322 stack.
 323
 324 A simple example of processing a PDF's document stream could look like this:
 325
 326 \starttyping
 327 function Do (scanner, info)
 328    local val       = scanner:pop()
 329    local name      = val[2] -- val[1] == 'name'
 330    local resources = info.resources
 331    local xobject   = resources:lookup("XObject"):getDict():lookup(name)
 332    print (info.space ..'Use XObject '.. name)
 333    if xobject and xobject:isStream() then
 334       local dict = xobject:getStream():getDict()
 335       if dict then
 336         local name = dict:lookup("Subtype")
 337         if name:getName() == "Form" then
 338           local newinfo =  {
 339             space = info.space .. "  " ,
 340             resources = dict:lookup("Resources"):getDict()
 341           }
 342           pdfscanner.scan(xobject, operatortable, newinfo)
 343         end
 344       end
 345    end
 346 end
 347
 348 operatortable = { Do = Do }
 349
 350 doc      = epdf.open(arg[1])
 351 pagenum  = 1
 352
 353 while pagenum <= doc:getNumPages() do
 354    local page = doc:getCatalog():getPage(pagenum)
 355    local info = {
 356      space     = "  " ,
 357      resources = page:getResourceDict()
 358    }
 359    print('Page ' .. pagenum)
 360    pdfscanner.scan(page:getContents(), operatortable, info)
 361    pagenum = pagenum + 1
 362 end
 363 \stoptyping
 364
 365 This example iterates over all the actual content in the PDF, and prints out the
 366 found XObject names. While the code demonstrates quite some of the \type {epdf}
 367 functions, let's focus on the type \type {pdfscanner} specific code instead.
 368
 369 From the bottom up, the line
 370
 371 \starttyping
 372    pdfscanner.scan(page:getContents(), operatortable, info)
 373 \stoptyping
 374
 375 runs the scanner with the PDF page's top-level content.
 376
 377 The third argument, \type {info}, contains two entries: \type {space} is used to
 378 indent the printed output, and \type {resources} is needed so that embedded \type
 379 {XForms} can find their own content.
 380
 381 The second argument, \type {operatortable} defines a processing function for a
 382 single PDF operator, \type {Do}.
 383
 384 The function \type {Do} prints the name of the current XObject, and then starts a
 385 new scanner for that object's content stream, under the condition that the
 386 XObject is in fact a \type {/Form}. That nested scanner is called with new \type
 387 {info} argument with an updated \type {space} value so that the indentation of
 388 the output nicely nests, and with an new \type {resources} field to help the next
 389 iteration down to properly process any other, embedded XObjects.
 390
 391 Of course, this is not a very useful example in practise, but for the purpose of
 392 demonstrating \type {pdfscanner}, it is just long enough. It makes use of only
 393 one \type {scanner} method: \type {scanner:pop()}. That function pops the top
 394 operand of the internal stack, and returns a \LUA\ table where the object at index
 395 one is a string representing the type of the operand, and object two is its
 396 value.
 397
 398 The list of possible operand types and associated \LUA\ value types is:
 399
 400 \starttabulate[|lT|p|]
 401 \NC integer  \NC <number>  \NC \NR
 402 \NC real     \NC <number>  \NC \NR
 403 \NC boolean  \NC <boolean> \NC \NR
 404 \NC name     \NC <string>  \NC \NR
 405 \NC operator \NC <string>  \NC \NR
 406 \NC string   \NC <string>  \NC \NR
 407 \NC array    \NC <table>   \NC \NR
 408 \NC dict     \NC <table>   \NC \NR
 409 \stoptabulate
 410
 411 In case of \type {integer} or \type {real}, the value is always a \LUA\ (floating
 412 point) number.
 413
 414 In case of \type {name}, the leading slash is always stripped.
 415
 416 In case of \type {string}, please bear in mind that PDF actually supports
 417 different types of strings (with different encodings) in different parts of the
 418 PDF document, so may need to reencode some of the results; \type {pdfscanner}
 419 always outputs the byte stream without reencoding anything. \type {pdfscanner}
 420 does not differentiate between literal strings and hexadecimal strings (the
 421 hexadecimal values are decoded), and it treats the stream data for inline images
 422 as a string that is the single operand for \type {EI}.
 423
 424 In case of \type {array}, the table content is a list of \type {pop} return
 425 values.
 426
 427 In case of \type {dict}, the table keys are PDF name strings and the values are
 428 \type {pop} return values.
 429
 430 \blank
 431
 432 There are few more methods defined that you can ask \type {scanner}:
 433
 434 \starttabulate[|lT|p|]
 435 \NC pop       \NC as explained above \NC \NR
 436 \NC popNumber \NC return only the value of a \type {real} or \type {integer} \NC \NR
 437 \NC popName   \NC return only the value of a \type {name} \NC \NR
 438 \NC popString \NC return only the value of a \type {string} \NC \NR
 439 \NC popArray  \NC return only the value of a \type {array} \NC \NR
 440 \NC popDict   \NC return only the value of a \type {dict} \NC \NR
 441 \NC popBool   \NC return only the value of a \type {boolean} \NC \NR
 442 \NC done      \NC abort further processing of this \type {scan()} call \NC \NR
 443 \stoptabulate
 444
 445 The \type {popXXX} are convenience functions, and come in handy when you know the
 446 type of the operands beforehand (which you usually do, in PDF). For example, the
 447 \type {Do} function could have used \type {local name = scanner:popName()}
 448 instead, because the single operand to the \type {Do} operator is always a PDF
 449 name object.
 450
 451 The \type {done} function allows you to abort processing of a stream once you
 452 have learned everything you want to learn. This comes in handy while parsing
 453 \type {/ToUnicode}, because there usually is trailing garbage that you are not
 454 interested in. Without \type {done}, processing only end at the end of the
 455 stream, possibly wasting CPU cycles.
 456
 457 \section{The \type {epdf} library}
 458
 459 The \type {epdf} library provides \LUA\ bindings to many \PDF\ access functions
 460 that are defined by the poppler \PDF\ viewer library (written in C$+{}+$ by
 461 Kristian H\o gsberg, based on xpdf by Derek Noonburg). Within \LUATEX\ (and
 462 \PDFTEX), xpdf functionality is being used since long time to embed \PDF\ files.
 463 The \type {epdf} library shall allow to scrutinize an external \PDF\ file. It
 464 gives access to its document structure: catalog, cross|-|reference table,
 465 individual pages, objects, annotations, info, and metadata. The \LUATEX\ team is
 466 evaluating the possibility of reducing the binding to a basic low level \PDF\
 467 primitives and delegate the complete set of functions to an external shared
 468 object module.
 469
 470 The \type {epdf} library is still in alpha state: \PDF\ access is currently
 471 read|-|only. Iit's not yet possible to alter a \PDF\ file or to assemble it from
 472 scratch, and many function bindings are still missing, and it is unlikely that we
 473 to support that at all. At some point we might also decide to limit the interface
 474 to a reasonable subset.
 475
 476 For a start, a \PDF\ file is opened by \type {epdf.open()} with file name, e.g.:
 477
 478 \starttyping
 479 doc = epdf.open("foo.pdf")
 480 \stoptyping
 481
 482 This normally returns a \type {PDFDoc} userdata variable; but if the file could
 483 not be opened successfully, instead of a fatal error just the value \type {nil} is
 484 returned.
 485
 486 All Lua functions in the \type {epdf} library are named after the poppler
 487 functions listed in the poppler header files for the various classes, e.g., files
 488 \type {PDFDoc.h}, \type {Dict.h}, and \type {Array.h}. These files can be found
 489 in the poppler subdirectory within the \LUATEX\ sources. Which functions are
 490 already implemented in the \type {epdf} library can be found in the \LUATEX\
 491 source file \type {lepdflib.cc}. For using the \type {epdf} library, knowledge of
 492 the \PDF\ file architecture is indispensable.
 493
 494 There are many different userdata types defined by the \type {epdf} library,
 495 currently these are \type {AnnotBorderStyle}, \type {AnnotBorder}, \type
 496 {Annots}, \type {Annot}, \type {Array}, \type {Attribute}, \type {Catalog}, \type
 497 {Dict}, \type {EmbFile}, \type {GString}, \type {LinkDest}, \type {Links}, \type
 498 {Link}, \type {ObjectStream}, \type {Object}, \type {PDFDoc}, \type
 499 {PDFRectangle}, \type {Page}, \type {Ref}, \type {Stream}, \type {StructElement},
 500 \type {StructTreeRoot} \type {TextSpan}, \type {XRefEntry} and \type {XRef}.
 501
 502 All these userdata names and the Lua access functions closely resemble the
 503 classes naming from the poppler header files, including the choice of mixed upper
 504 and lower case letters. The Lua function calls use object|-|oriented syntax,
 505 e.g., the following calls return the \type {Page} object for page~1:
 506
 507 \starttyping
 508 pageref = doc:getCatalog():getPageRef(1)
 509 pageobj = doc:getXRef():fetch(pageref.num, pageref.gen)
 510 \stoptyping
 511
 512 But writing such chained calls is risky, as an intermediate function may return
 513 \type {nil} on error; therefore between function calls there should be Lua type
 514 checks (e.g., against \type {nil}) done. If a non-object item is requested (e.g.,
 515 a \type {Dict} item by calling \type {page:getPieceInfo()}, cf.~\type {Page.h})
 516 but not available, the Lua functions return \type {nil} (without error). If a
 517 function should return an \type {Object}, but it's not existing, a \type {Null}
 518 object is returned instead (also without error; this is in|-|line with poppler
 519 behavior).
 520
 521 All library objects have a \type {__gc} metamethod for garbage collection. The
 522 \type {__tostring} metamethod gives the type name for each object.
 523
 524 All object constructors:
 525
 526 \startfunctioncall
 527 <PDFDoc>       = epdf.open(<string> PDF filename)
 528 <Annot>        = epdf.Annot(<XRef>, <Dict>, <Catalog>, <Ref>)
 529 <Annots>       = epdf.Annots(<XRef>, <Catalog>, <Object>)
 530 <Array>        = epdf.Array(<XRef>)
 531 <Attribute>    = epdf.Attribute(<Type>,<Object>)| epdf.Attribute(<string>, <int>, <Object>)
 532 <Dict>         = epdf.Dict(<XRef>)
 533 <Object>       = epdf.Object()
 534 <PDFRectangle> = epdf.PDFRectangle()
 535 \stopfunctioncall
 536
 537 The functions \type {StructElement_Type}, \type {Attribute_Type} and \type
 538 {AttributeOwner_Type} return a hash table \type {{<string>,<integer>}}.
 539
 540 \type {Annot} methods:
 541
 542 \startfunctioncall
 543 <boolean>     = <Annot>:isOK()
 544 <Object>      = <Annot>:getAppearance()
 545 <AnnotBorder> = <Annot>:getBorder()
 546 <boolean>     = <Annot>:match(<Ref>)
 547 \stopfunctioncall
 548
 549 \type {AnnotBorderStyle} methods:
 550
 551 \startfunctioncall
 552 <number> = <AnnotBorderStyle>:getWidth()
 553 \stopfunctioncall
 554
 555 \type {Annots} methods:
 556
 557 \startfunctioncall
 558 <integer> = <Annots>:getNumAnnots()
 559 <Annot>   = <Annots>:getAnnot(<integer>)
 560 \stopfunctioncall
 561
 562 \type {Array} methods:
 563
 564 \startfunctioncall
 565             <Array>:incRef()
 566             <Array>:decRef()
 567 <integer> = <Array>:getLength()
 568             <Array>:add(<Object>)
 569 <Object>  = <Array>:get(<integer>)
 570 <Object>  = <Array>:getNF(<integer>)
 571 <string>  = <Array>:getString(<integer>)
 572 \stopfunctioncall
 573
 574 \type {Attribute} methods:
 575
 576 \startfunctioncall
 577 <boolean>  = <Attribute>:isOk()
 578 <integer>  = <Attribute>:getType()
 579 <integer>  = <Attribute>:getOwner()
 580 <string>   = <Attribute>:getTypeName()
 581 <string>   = <Attribute>:getOwnerName()
 582 <Object>   = <Attribute>:getValue()
 583 <Object>   = <Attribute>:getDefaultValue
 584 <string>   = <Attribute>:getName()
 585 <integer>  = <Attribute>:getRevision()
 586              <Attribute>:setRevision(<unsigned integer>)
 587 <boolean>  = <Attribute>:istHidden()
 588              <Attribute>:setHidden(<boolean>)
 589 <string>   = <Attribute>:getFormattedValue()
 590 <string>   = <Attribute>:setFormattedValue(<string>)
 591 \stopfunctioncall
 592
 593 \type {Catalog} methods:
 594
 595 \startfunctioncall
 596 <boolean>  = <Catalog>:isOK()
 597 <integer>  = <Catalog>:getNumPages()
 598 <Page>     = <Catalog>:getPage(<integer>)
 599 <Ref>      = <Catalog>:getPageRef(<integer>)
 600 <string>   = <Catalog>:getBaseURI()
 601 <string>   = <Catalog>:readMetadata()
 602 <Object>   = <Catalog>:getStructTreeRoot()
 603 <integer>  = <Catalog>:findPage(<integer> object number, <integer> object generation)
 604 <LinkDest> = <Catalog>:findDest(<string> name)
 605 <Object>   = <Catalog>:getDests()
 606 <integer>  = <Catalog>:numEmbeddedFiles()
 607 <EmbFile>  = <Catalog>:embeddedFile(<integer>)
 608 <integer>  = <Catalog>:numJS()
 609 <string>   = <Catalog>:getJS(<integer>)
 610 <Object>   = <Catalog>:getOutline()
 611 <Object>   = <Catalog>:getAcroForm()
 612 \stopfunctioncall
 613
 614 \type {EmbFile} methods:
 615
 616 \startfunctioncall
 617 <string>   = <EmbFile>:name()
 618 <string>   = <EmbFile>:description()
 619 <integer>  = <EmbFile>:size()
 620 <string>   = <EmbFile>:modDate()
 621 <string>   = <EmbFile>:createDate()
 622 <string>   = <EmbFile>:checksum()
 623 <string>   = <EmbFile>:mimeType()
 624 <Object>   = <EmbFile>:streamObject()
 625 <boolean>  = <EmbFile>:isOk()
 626 \stopfunctioncall
 627
 628 \type {Dict} methods:
 629
 630 \startfunctioncall
 631             <Dict>:incRef()
 632             <Dict>:decRef()
 633 <integer> = <Dict>:getLength()
 634             <Dict>:add(<string>, <Object>)
 635             <Dict>:set(<string>, <Object>)
 636             <Dict>:remove(<string>)
 637 <boolean> = <Dict>:is(<string>)
 638 <Object>  = <Dict>:lookup(<string>)
 639 <Object>  = <Dict>:lookupNF(<string>)
 640 <integer> = <Dict>:lookupInt(<string>, <string>)
 641 <string>  = <Dict>:getKey(<integer>)
 642 <Object>  = <Dict>:getVal(<integer>)
 643 <Object>  = <Dict>:getValNF(<integer>)
 644 <boolean> = <Dict>:hasKey(<string>)
 645 \stopfunctioncall
 646
 647 \type {Link} methods:
 648
 649 \startfunctioncall
 650 <boolean>  = <Link>:isOK()
 651 <boolean>  = <Link>:inRect(<number>, <number>)
 652 \stopfunctioncall
 653
 654 \type {LinkDest} methods:
 655
 656 \startfunctioncall
 657 <boolean>  = <LinkDest>:isOK()
 658 <integer>  = <LinkDest>:getKind()
 659 <string>   = <LinkDest>:getKindName()
 660 <boolean>  = <LinkDest>:isPageRef()
 661 <integer>  = <LinkDest>:getPageNum()
 662 <Ref>      = <LinkDest>:getPageRef()
 663 <number>   = <LinkDest>:getLeft()
 664 <number>   = <LinkDest>:getBottom()
 665 <number>   = <LinkDest>:getRight()
 666 <number>   = <LinkDest>:getTop()
 667 <number>   = <LinkDest>:getZoom()
 668 <boolean>  = <LinkDest>:getChangeLeft()
 669 <boolean>  = <LinkDest>:getChangeTop()
 670 <boolean>  = <LinkDest>:getChangeZoom()
 671 \stopfunctioncall
 672
 673 \type {Links} methods:
 674
 675 \startfunctioncall
 676 <integer>  = <Links>:getNumLinks()
 677 <Link>     = <Links>:getLink(<integer>)
 678 \stopfunctioncall
 679
 680 \type {Object} methods:
 681
 682 \startfunctioncall
 683             <Object>:initBool(<boolean>)
 684             <Object>:initInt(<integer>)
 685             <Object>:initReal(<number>)
 686             <Object>:initString(<string>)
 687             <Object>:initName(<string>)
 688             <Object>:initNull()
 689             <Object>:initArray(<XRef>)
 690             <Object>:initDict(<XRef>)
 691             <Object>:initStream(<Stream>)
 692             <Object>:initRef(<integer> object number, <integer> object generation)
 693             <Object>:initCmd(<string>)
 694             <Object>:initError()
 695             <Object>:initEOF()
 696 <Object>  = <Object>:fetch(<XRef>)
 697 <integer> = <Object>:getType()
 698 <string>  = <Object>:getTypeName()
 699 <boolean> = <Object>:isBool()
 700 <boolean> = <Object>:isInt()
 701 <boolean> = <Object>:isReal()
 702 <boolean> = <Object>:isNum()
 703 <boolean> = <Object>:isString()
 704 <boolean> = <Object>:isName()
 705 <boolean> = <Object>:isNull()
 706 <boolean> = <Object>:isArray()
 707 <boolean> = <Object>:isDict()
 708 <boolean> = <Object>:isStream()
 709 <boolean> = <Object>:isRef()
 710 <boolean> = <Object>:isCmd()
 711 <boolean> = <Object>:isError()
 712 <boolean> = <Object>:isEOF()
 713 <boolean> = <Object>:isNone()
 714 <boolean> = <Object>:getBool()
 715 <integer> = <Object>:getInt()
 716 <number>  = <Object>:getReal()
 717 <number>  = <Object>:getNum()
 718 <string>  = <Object>:getString()
 719 <string>  = <Object>:getName()
 720 <Array>   = <Object>:getArray()
 721 <Dict>    = <Object>:getDict()
 722 <Stream>  = <Object>:getStream()
 723 <Ref>     = <Object>:getRef()
 724 <integer> = <Object>:getRefNum()
 725 <integer> = <Object>:getRefGen()
 726 <string>  = <Object>:getCmd()
 727 <integer> = <Object>:arrayGetLength()
 728           = <Object>:arrayAdd(<Object>)
 729 <Object>  = <Object>:arrayGet(<integer>)
 730 <Object>  = <Object>:arrayGetNF(<integer>)
 731 <integer> = <Object>:dictGetLength(<integer>)
 732           = <Object>:dictAdd(<string>, <Object>)
 733           = <Object>:dictSet(<string>, <Object>)
 734 <Object>  = <Object>:dictLookup(<string>)
 735 <Object>  = <Object>:dictLookupNF(<string>)
 736 <string>  = <Object>:dictgetKey(<integer>)
 737 <Object>  = <Object>:dictgetVal(<integer>)
 738 <Object>  = <Object>:dictgetValNF(<integer>)
 739 <boolean> = <Object>:streamIs(<string>)
 740           = <Object>:streamReset()
 741 <integer> = <Object>:streamGetChar()
 742 <integer> = <Object>:streamLookChar()
 743 <integer> = <Object>:streamGetPos()
 744           = <Object>:streamSetPos(<integer>)
 745 <Dict>    = <Object>:streamGetDict()
 746 \stopfunctioncall
 747
 748 \type {Page} methods:
 749
 750 \startfunctioncall
 751 <boolean>      = <Page>:isOk()
 752 <integer>      = <Page>:getNum()
 753 <PDFRectangle> = <Page>:getMediaBox()
 754 <PDFRectangle> = <Page>:getCropBox()
 755 <boolean>      = <Page>:isCropped()
 756 <number>       = <Page>:getMediaWidth()
 757 <number>       = <Page>:getMediaHeight()
 758 <number>       = <Page>:getCropWidth()
 759 <number>       = <Page>:getCropHeight()
 760 <PDFRectangle> = <Page>:getBleedBox()
 761 <PDFRectangle> = <Page>:getTrimBox()
 762 <PDFRectangle> = <Page>:getArtBox()
 763 <integer>      = <Page>:getRotate()
 764 <string>       = <Page>:getLastModified()
 765 <Dict>         = <Page>:getBoxColorInfo()
 766 <Dict>         = <Page>:getGroup()
 767 <Stream>       = <Page>:getMetadata()
 768 <Dict>         = <Page>:getPieceInfo()
 769 <Dict>         = <Page>:getSeparationInfo()
 770 <Dict>         = <Page>:getResourceDict()
 771 <Object>       = <Page>:getAnnots()
 772 <Links>        = <Page>:getLinks(<Catalog>)
 773 <Object>       = <Page>:getContents()
 774 \stopfunctioncall
 775
 776 \type {PDFDoc} methods:
 777
 778 \startfunctioncall
 779 <boolean>  = <PDFDoc>:isOk()
 780 <integer>  = <PDFDoc>:getErrorCode()
 781 <string>   = <PDFDoc>:getErrorCodeName()
 782 <string>   = <PDFDoc>:getFileName()
 783 <XRef>     = <PDFDoc>:getXRef()
 784 <Catalog>  = <PDFDoc>:getCatalog()
 785 <number>   = <PDFDoc>:getPageMediaWidth()
 786 <number>   = <PDFDoc>:getPageMediaHeight()
 787 <number>   = <PDFDoc>:getPageCropWidth()
 788 <number>   = <PDFDoc>:getPageCropHeight()
 789 <integer>  = <PDFDoc>:getNumPages()
 790 <string>   = <PDFDoc>:readMetadata()
 791 <Object>   = <PDFDoc>:getStructTreeRoot()
 792 <integer>  = <PDFDoc>:findPage(<integer> object number, <integer> object generation)
 793 <Links>    = <PDFDoc>:getLinks(<integer>)
 794 <LinkDest> = <PDFDoc>:findDest(<string>)
 795 <boolean>  = <PDFDoc>:isEncrypted()
 796 <boolean>  = <PDFDoc>:okToPrint()
 797 <boolean>  = <PDFDoc>:okToChange()
 798 <boolean>  = <PDFDoc>:okToCopy()
 799 <boolean>  = <PDFDoc>:okToAddNotes()
 800 <boolean>  = <PDFDoc>:isLinearized()
 801 <Object>   = <PDFDoc>:getDocInfo()
 802 <Object>   = <PDFDoc>:getDocInfoNF()
 803 <integer>  = <PDFDoc>:getPDFMajorVersion()
 804 <integer>  = <PDFDoc>:getPDFMinorVersion()
 805 \stopfunctioncall
 806
 807 \type {PDFRectangle} methods:
 808
 809 \startfunctioncall
 810 <boolean>  = <PDFRectangle>:isValid()
 811 \stopfunctioncall
 812
 813 %\type {Ref} methods:
 814 %
 815 %\startfunctioncall
 816 %\stopfunctioncall
 817
 818 \type {Stream} methods:
 819
 820 \startfunctioncall
 821 <integer>  = <Stream>:getKind()
 822 <string>   = <Stream>:getKindName()
 823            = <Stream>:reset()
 824            = <Stream>:close()
 825 <integer>  = <Stream>:getChar()
 826 <integer>  = <Stream>:lookChar()
 827 <integer>  = <Stream>:getRawChar()
 828 <integer>  = <Stream>:getUnfilteredChar()
 829            = <Stream>:unfilteredReset()
 830 <integer>  = <Stream>:getPos()
 831 <boolean>  = <Stream>:isBinary()
 832 <Stream>   = <Stream>:getUndecodedStream()
 833 <Dict>     = <Stream>:getDict()
 834 \stopfunctioncall
 835
 836 \type {StructElement} methods:
 837
 838 \startfunctioncall
 839 <string>         = <StructElement>:getTypeName()
 840 <integer>        = <StructElement>:getType()
 841 <boolean>        = <StructElement>:isOk()
 842 <boolean>        = <StructElement>:isBlock()
 843 <boolean>        = <StructElement>:isInline()
 844 <boolean>        = <StructElement>:isGrouping()
 845 <boolean>        = <StructElement>:isContent()
 846 <boolean>        = <StructElement>:isObjectRef()
 847 <integer>        = <StructElement>:getMCID()
 848 <Ref>            = <StructElement>:getObjectRef()
 849 <Ref>            = <StructElement>:getParentRef()
 850 <boolean>        = <StructElement>:hasPageRef()
 851 <Ref>            = <StructElement>:getPageRef()
 852 <StructTreeRoot> = <StructElement>:getStructTreeRoot()
 853 <string>         = <StructElement>:getID()
 854 <string>         = <StructElement>:getLanguage()
 855 <integer>        = <StructElement>:getRevision()
 856                    <StructElement>:setRevision(<unsigned integer>)
 857 <string>         = <StructElement>:getTitle()
 858 <string>         = <StructElement>:getExpandedAbbr()
 859 <integer>        = <StructElement>:getNumChildren()
 860 <StructElement>  = <StructElement>:getChild()
 861                  = <StructElement>:appendChild<StructElement>)
 862 <integer>        = <StructElement>:getNumAttributes()
 863 <Attribute>      = <StructElement>:geAttribute(<integer>)
 864 <string>         = <StructElement>:appendAttribute(<Attribute>)
 865 <Attribute>      = <StructElement>:findAttribute(<Attribute::Type>,boolean,Attribute::Owner)
 866 <string>         = <StructElement>:getAltText()
 867 <string>         = <StructElement>:getActualText()
 868 <string>         = <StructElement>:getText(<boolean>)
 869 <table>          = <StructElement>:getTextSpans()
 870 \stopfunctioncall
 871
 872 \type {StructTreeRoot} methods:
 873
 874 \startfunctioncall
 875 <StructElement> = <StructTreeRoot>:findParentElement
 876 <PDFDoc>        = <StructTreeRoot>:getDoc
 877 <Dict>          = <StructTreeRoot>:getRoleMap
 878 <Dict>          = <StructTreeRoot>:getClassMap
 879 <integer>       = <StructTreeRoot>:getNumChildren
 880 <StructElement> = <StructTreeRoot>:getChild
 881                   <StructTreeRoot>:appendChild
 882 <StructElement> = <StructTreeRoot>:findParentElement
 883 \stopfunctioncall
 884
 885 \type {TextSpan} han only one method:
 886
 887 \startfunctioncall
 888 <string> = <TestSpan>:getText()
 889 \stopfunctioncall
 890
 891 \type {XRef} methods:
 892
 893 \startfunctioncall
 894 <boolean>  = <XRef>:isOk()
 895 <integer>  = <XRef>:getErrorCode()
 896 <boolean>  = <XRef>:isEncrypted()
 897 <boolean>  = <XRef>:okToPrint()
 898 <boolean>  = <XRef>:okToPrintHighRes()
 899 <boolean>  = <XRef>:okToChange()
 900 <boolean>  = <XRef>:okToCopy()
 901 <boolean>  = <XRef>:okToAddNotes()
 902 <boolean>  = <XRef>:okToFillForm()
 903 <boolean>  = <XRef>:okToAccessibility()
 904 <boolean>  = <XRef>:okToAssemble()
 905 <Object>   = <XRef>:getCatalog()
 906 <Object>   = <XRef>:fetch(<integer> object number, <integer> object generation)
 907 <Object>   = <XRef>:getDocInfo()
 908 <Object>   = <XRef>:getDocInfoNF()
 909 <integer>  = <XRef>:getNumObjects()
 910 <integer>  = <XRef>:getRootNum()
 911 <integer>  = <XRef>:getRootGen()
 912 <integer>  = <XRef>:getSize()
 913 <Object>   = <XRef>:getTrailerDict()
 914 \stopfunctioncall
 915
 916 There is an experimental function \type {epdf.openMemStream} that takes three
 917 arguments:
 918
 919 \starttabulate
 920 \NC \type {stream}  \NC this is a (in low level \LUA\ speak) light userdata
 921                         object, i.e.\ a pointer to a sequence of bytes \NC \NR
 922 \NC \type {length}  \NC this is the length of the stream in bytes \NC \NR
 923 \NC \type {name}    \NC this is a unique identifier that us used for hashing the
 924                         stream, so that mulltiple doesn't use more memory \NC \NR
 925 \stoptabulate
 926
 927 Instead of a light userdata stream you can also pass a \LUA\ string, in which
 928 case the given length is (at most) the string length.
 929
 930 The returned object can be used in the \type {img} library instead of a filename.
 931 Both the memory stream and it's use in the image library is experimental and can
 932 change. In case you wonder where this can be used: when you use the swiglib
 933 library for \type {graphicmagick}, it can return such a userdata object. This
 934 permits conversion in memory and passing the result directly to the backend. This
 935 might save some runtime in one|-|pass workflows. This feature is currently not
 936 meant for production.
 937
 938 \stopchapter
 939
 940 \stopcomponent