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