manual/luatex-libraries.tex

   1 % language=uk
   2
   3 \environment luatex-style
   4 \environment luatex-logos
   5
   6 % HH: to be checked
   7
   8 \startcomponent luatex-libraries
   9
  10 \startchapter[reference=libraries,title={\LUATEX\ \LUA\ Libraries}]
  11
  12 The implied use of the built|-|in \LUA\ modules \type {epdf}, \type {fontloader},
  13 \type {mplib}, and \type {pdfscanner} is deprecated. If you want to use these,
  14 please start your source file with a proper \type {require} line. In the future,
  15 \LUATEX\ will switch to loading these modules on demand.
  16
  17 The interfacing between \TEX\ and \LUA\ is facilitated by a set of library
  18 modules. The \LUA\ libraries in this chapter are all defined and initialized by
  19 the \LUATEX\ executable. Together, they allow \LUA\ scripts to query and change a
  20 number of \TEX's internal variables, run various internal \TEX\ functions, and
  21 set up \LUATEX's hooks to execute \LUA\ code.
  22
  23 The following sections are in alphabetical order. For any callback (and
  24 manipulation of nodes) the following is true: you have a lot of freedom which
  25 also means that you can mess up the node lists and nodes themselves. So, a bit of
  26 defensive programming doesn't hurt. A crash can happen when you spoil things or
  27 when \LUATEX\ can recognize the issue, a panic exit will happen. Don't bother the
  28 team with such issues.
  29
  30 \section{The \type {callback} library}
  31
  32 This library has functions that register, find and list callbacks. Callbacks are
  33 \LUA\ functions that are called in well defined places. There are two kind of
  34 callbacks: those that mix with existing functionality, and those that (when
  35 enabled) replace functionality. In mosty cases the second category is expected to
  36 behave similar to the built in functionality because in a next step specific
  37 data is expected. For instance, you can replace the hyphenation routine. The
  38 function gets a list that can be hyphenated (or not). The final list should be
  39 valid and is (normally) used for constructing a paragraph. Another function can
  40 replace the ligature builder and|/|or kerner. Doing something else is possible
  41 but in the end might not give the user the expected outcome.
  42
  43 The first thing you need to do is registering a callback:
  44
  45 \startfunctioncall
  46 id, error = callback.register (<string> callback_name, <function> func)
  47 id, error = callback.register (<string> callback_name, nil)
  48 id, error = callback.register (<string> callback_name, false)
  49 \stopfunctioncall
  50
  51 Here the \syntax {callback_name} is a predefined callback name, see below. The
  52 function returns the internal \type {id} of the callback or \type {nil}, if the
  53 callback could not be registered. In the latter case, \type {error} contains an
  54 error message, otherwise it is \type {nil}.
  55
  56 \LUATEX\ internalizes the callback function in such a way that it does not matter
  57 if you redefine a function accidentally.
  58
  59 Callback assignments are always global. You can use the special value \type {nil}
  60 instead of a function for clearing the callback.
  61
  62 For some minor speed gain, you can assign the boolean \type {false} to the
  63 non|-|file related callbacks, doing so will prevent \LUATEX\ from executing
  64 whatever it would execute by default (when no callback function is registered at
  65 all). Be warned: this may cause all sorts of grief unless you know {\em exactly}
  66 what you are doing!
  67
  68 \startfunctioncall
  69 <table> info = callback.list()
  70 \stopfunctioncall
  71
  72 The keys in the table are the known callback names, the value is a boolean where
  73 \type {true} means that the callback is currently set (active).
  74
  75 \startfunctioncall
  76 <function> f = callback.find (callback_name)
  77 \stopfunctioncall
  78
  79 If the callback is not set, \type {callback.find} returns \type {nil}.
  80
  81 \subsection{File discovery callbacks}
  82
  83 The behaviour documented in this subsection is considered stable in the sense that
  84 there will not be backward|-|incompatible changes any more.
  85
  86 \subsubsection{\type {find_read_file} and \type {find_write_file}}
  87
  88 Your callback function should have the following conventions:
  89
  90 \startfunctioncall
  91 <string> actual_name = function (<number> id_number, <string> asked_name)
  92 \stopfunctioncall
  93
  94 Arguments:
  95
  96 \startitemize
  97
  98 \sym{id_number}
  99
 100 This number is zero for the log or \type {\input} files. For \TEX's \type {\read}
 101 or \type {\write} the number is incremented by one, so \type {\read0} becomes~1.
 102
 103 \sym{asked_name}
 104
 105 This is the user|-|supplied filename, as found by \type {\input}, \type {\openin}
 106 or \type {\openout}.
 107
 108 \stopitemize
 109
 110 Return value:
 111
 112 \startitemize
 113
 114 \sym{actual_name}
 115
 116 This is the filename used. For the very first file that is read in by \TEX, you
 117 have to make sure you return an \type {actual_name} that has an extension and
 118 that is suitable for use as \type {jobname}. If you don't, you will have to
 119 manually fix the name of the log file and output file after \LUATEX\ is finished,
 120 and an eventual format filename will become mangled. That is because these file
 121 names depend on the jobname.
 122
 123 You have to return \type {nil} if the file cannot be found.
 124
 125 \stopitemize
 126
 127 \subsubsection{\type {find_font_file}}
 128
 129 Your callback function should have the following conventions:
 130
 131 \startfunctioncall
 132 <string> actual_name = function (<string> asked_name)
 133 \stopfunctioncall
 134
 135 The \type {asked_name} is an \OTF\ or \TFM\ font metrics file.
 136
 137 Return \type {nil} if the file cannot be found.
 138
 139 \subsubsection{\type {find_output_file}}
 140
 141 Your callback function should have the following conventions:
 142
 143 \startfunctioncall
 144 <string> actual_name = function (<string> asked_name)
 145 \stopfunctioncall
 146
 147 The \type {asked_name} is the \PDF\ or \DVI\ file for writing.
 148
 149 \subsubsection{\type {find_format_file}}
 150
 151 Your callback function should have the following conventions:
 152
 153 \startfunctioncall
 154 <string> actual_name = function (<string> asked_name)
 155 \stopfunctioncall
 156
 157 The \type {asked_name} is a format file for reading (the format file for writing
 158 is always opened in the current directory).
 159
 160 \subsubsection{\type {find_vf_file}}
 161
 162 Like \type {find_font_file}, but for virtual fonts. This applies to both \ALEPH's
 163 \OVF\ files and traditional Knuthian \VF\ files.
 164
 165 \subsubsection{\type {find_map_file}}
 166
 167 Like \type {find_font_file}, but for map files.
 168
 169 \subsubsection{\type {find_enc_file}}
 170
 171 Like \type {find_font_file}, but for enc files.
 172
 173 \subsubsection{\type {find_sfd_file}}
 174
 175 Like \type {find_font_file}, but for subfont definition files.
 176
 177 \subsubsection{\type {find_pk_file}}
 178
 179 Like \type {find_font_file}, but for pk bitmap files. This callback takes two
 180 arguments: \type {name} and \type {dpi}. In your callback you can decide to
 181 look for:
 182
 183 \starttyping
 184 <base res>dpi/<fontname>.<actual res>pk
 185 \stoptyping
 186
 187 but other strategies are possible. It is up to you to find a \quote {reasonable}
 188 bitmap file to go with that specification.
 189
 190 \subsubsection{\type {find_data_file}}
 191
 192 Like \type {find_font_file}, but for embedded files (\type {\pdfobj file '...'}).
 193
 194 \subsubsection{\type {find_opentype_file}}
 195
 196 Like \type {find_font_file}, but for \OPENTYPE\ font files.
 197
 198 \subsubsection{\type {find_truetype_file} and \type {find_type1_file}}
 199
 200 Your callback function should have the following conventions:
 201
 202 \startfunctioncall
 203 <string> actual_name = function (<string> asked_name)
 204 \stopfunctioncall
 205
 206 The \type {asked_name} is a font file. This callback is called while \LUATEX\ is
 207 building its internal list of needed font files, so the actual timing may
 208 surprise you. Your return value is later fed back into the matching \type
 209 {read_file} callback.
 210
 211 Strangely enough, \type {find_type1_file} is also used for \OPENTYPE\ (\OTF)
 212 fonts.
 213
 214 \subsubsection{\type {find_image_file}}
 215
 216 Your callback function should have the following conventions:
 217
 218 \startfunctioncall
 219 <string> actual_name = function (<string> asked_name)
 220 \stopfunctioncall
 221
 222 The \type {asked_name} is an image file. Your return value is used to open a file
 223 from the hard disk, so make sure you return something that is considered the name
 224 of a valid file by your operating system.
 225
 226 \subsection[iocallback]{File reading callbacks}
 227
 228 The behavior documented in this subsection is considered stable in the sense that
 229 there will not be backward-incompatible changes any more.
 230
 231 \subsubsection{\type {open_read_file}}
 232
 233 Your callback function should have the following conventions:
 234
 235 \startfunctioncall
 236 <table> env = function (<string> file_name)
 237 \stopfunctioncall
 238
 239 Argument:
 240
 241 \startitemize
 242
 243 \sym{file_name}
 244
 245 The filename returned by a previous \type {find_read_file} or the return value of
 246 \type {kpse.find_file()} if there was no such callback defined.
 247
 248 \stopitemize
 249
 250 Return value:
 251
 252 \startitemize
 253
 254 \sym{env}
 255
 256 This is a table containing at least one required and one optional callback
 257 function for this file. The required field is \type {reader} and the associated
 258 function will be called once for each new line to be read, the optional one is
 259 \type {close} that will be called once when \LUATEX\ is done with the file.
 260
 261 \LUATEX\ never looks at the rest of the table, so you can use it to store your
 262 private per|-|file data. Both the callback functions will receive the table as
 263 their only argument.
 264
 265 \stopitemize
 266
 267 \subsubsubsection{\type {reader}}
 268
 269 \LUATEX\ will run this function whenever it needs a new input line from the file.
 270
 271 \startfunctioncall
 272 function(<table> env)
 273     return <string> line
 274 end
 275 \stopfunctioncall
 276
 277 Your function should return either a string or \type {nil}. The value \type {nil}
 278 signals that the end of file has occurred, and will make \TEX\ call the optional
 279 \type {close} function next.
 280
 281 \subsubsubsection{\type {close}}
 282
 283 \LUATEX\ will run this optional function when it decides to close the file.
 284
 285 \startfunctioncall
 286 function(<table> env)
 287 end
 288 \stopfunctioncall
 289
 290 Your function should not return any value.
 291
 292 \subsubsection{General file readers}
 293
 294 There is a set of callbacks for the loading of binary data files. These all use
 295 the same interface:
 296
 297 \startfunctioncall
 298 function(<string> name)
 299     return <boolean> success, <string> data, <number> data_size
 300 end
 301 \stopfunctioncall
 302
 303 The \type {name} will normally be a full path name as it is returned by either
 304 one of the file discovery callbacks or the internal version of \type
 305 {kpse.find_file()}.
 306
 307 \startitemize
 308
 309 \sym{success}
 310
 311 Return \type {false} when a fatal error occurred (e.g.\ when the file cannot be
 312 found, after all).
 313
 314 \sym{data}
 315
 316 The bytes comprising the file.
 317
 318 \sym{data_size}
 319
 320 The length of the \type {data}, in bytes.
 321
 322 \stopitemize
 323
 324 Return an empty string and zero if the file was found but there was a
 325 reading problem.
 326
 327 The list of functions is as follows:
 328
 329 \starttabulate[|l|p|]
 330 \NC \type {read_font_file}     \NC ofm or tfm files \NC \NR
 331 \NC \type {read_vf_file}       \NC virtual fonts \NC \NR
 332 \NC \type {read_map_file}      \NC map files \NC \NR
 333 \NC \type {read_enc_file}      \NC encoding files \NC \NR
 334 \NC \type {read_sfd_file}      \NC subfont definition files \NC \NR
 335 \NC \type {read_pk_file}       \NC pk bitmap files \NC \NR
 336 \NC \type {read_data_file}     \NC embedded files (\type {\pdfobj file ...}) \NC \NR
 337 \NC \type {read_truetype_file} \NC \TRUETYPE\ font files \NC \NR
 338 \NC \type {read_type1_file}    \NC \TYPEONE\ font files \NC \NR
 339 \NC \type {read_opentype_file} \NC \OPENTYPE\ font files \NC \NR
 340 \stoptabulate
 341
 342 \subsection{Data processing callbacks}
 343
 344 \subsubsection{\type {process_input_buffer}}
 345
 346 This callback allows you to change the contents of the line input buffer just
 347 before \LUATEX\ actually starts looking at it.
 348
 349 \startfunctioncall
 350 function(<string> buffer)
 351     return <string> adjusted_buffer
 352 end
 353 \stopfunctioncall
 354
 355 If you return \type {nil}, \LUATEX\ will pretend like your callback never
 356 happened. You can gain a small amount of processing time from that. This callback
 357 does not replace any internal code.
 358
 359 \subsubsection{\type {process_output_buffer}}
 360
 361 This callback allows you to change the contents of the line output buffer just
 362 before \LUATEX\ actually starts writing it to a file as the result of a \type
 363 {\write} command. It is only called for output to an actual file (that is,
 364 excluding the log, the terminal, and \type {\write18} calls).
 365
 366 \startfunctioncall
 367 function(<string> buffer)
 368     return <string> adjusted_buffer
 369 end
 370 \stopfunctioncall
 371
 372 If you return \type {nil}, \LUATEX\ will pretend like your callback never
 373 happened. You can gain a small amount of processing time from that. This callback
 374 does not replace any internal code.
 375
 376 \subsubsection{\type {process_jobname}}
 377
 378 This callback allows you to change the jobname given by \type {\jobname} in \TEX\
 379 and \type {tex.jobname} in Lua. It does not affect the internal job name or the
 380 name of the output or log files.
 381
 382 \startfunctioncall
 383 function(<string> jobname)
 384     return <string> adjusted_jobname
 385 end
 386 \stopfunctioncall
 387
 388 The only argument is the actual job name; you should not use \type {tex.jobname}
 389 inside this function or infinite recursion may occur. If you return \type {nil},
 390 \LUATEX\ will pretend your callback never happened. This callback does not
 391 replace any internal code.
 392
 393 \subsection{Node list processing callbacks}
 394
 395 The description of nodes and node lists is in~\in{chapter}[nodes].
 396
 397 \subsubsection{\type {contribute_filter}}
 398
 399 This callback is called when \LUATEX\ adds contents to list:
 400
 401 \startfunctioncall
 402 function(<string> extrainfo)
 403 end
 404 \stopfunctioncall
 405
 406 The string reports the group code. From this you can deduce from
 407 what list you can give a treat.
 408
 409 \starttabulate
 410 \NC \bf group codes        \NC \bf pointer \NC \NR
 411 \HL
 412 \NC\type {pre_box}         \NC \type {contrib_head}    \NC \NR
 413 \NC\type {pre_adjust_tail} \NC \type {pre_adjust_head} \NC \NR
 414 \NC\type {just}            \NC \type {just_box}        \NC \NR
 415 \NC\type {adjust_tail}     \NC \type {adjust_head}     \NC \NR
 416 \stoptabulate
 417
 418 \subsubsection{\type {buildpage_filter} and \type {contribute_filter}}
 419
 420 This callback is called whenever \LUATEX\ is ready to move stuff to the main
 421 vertical list. You can use this callback to do specialized manipulation of the
 422 page building stage like imposition or column balancing.
 423
 424 \startfunctioncall
 425 function(<string> extrainfo)
 426 end
 427 \stopfunctioncall
 428
 429 The string \type {extrainfo} gives some additional information about what \TEX's
 430 state is with respect to the \quote {current page}. The possible values for the
 431 \type {buildpage_filter} callback are:
 432
 433 \starttabulate[|lT|p|]
 434 \NC \ssbf value     \NC \bf explanation                           \NC \NR
 435 \NC alignment       \NC a (partial) alignment is being added      \NC \NR
 436 \NC after_output    \NC an output routine has just finished       \NC \NR
 437 \NC new_graf        \NC the beginning of a new paragraph          \NC \NR
 438 \NC vmode_par       \NC \type {\par} was found in vertical mode   \NC \NR
 439 \NC hmode_par       \NC \type {\par} was found in horizontal mode \NC \NR
 440 \NC insert          \NC an insert is added                        \NC \NR
 441 \NC penalty         \NC a penalty (in vertical mode)              \NC \NR
 442 \NC before_display  \NC immediately before a display starts       \NC \NR
 443 \NC after_display   \NC a display is finished                     \NC \NR
 444 \NC end             \NC \LUATEX\ is terminating (it's all over)   \NC \NR
 445 \stoptabulate
 446
 447 And for the \type {contribute_filter} called in the post line break handler
 448 we have four cases (three are only called when there is a need for it).
 449
 450 \starttabulate[|lT|p|]
 451 \NC \ssbf value     \NC \bf explanation                              \NC \NR
 452 \NC pre_box         \NC interline material is being added            \NC \NR
 453 \NC pre_adjust      \NC \type {\vadjust} material is being added     \NC \NR
 454 \NC box             \NC a typeset box is being added (always called) \NC \NR
 455 \NC adjust          \NC \type {\vadjust} material is being added     \NC \NR
 456 \stoptabulate
 457
 458 Just before the \type {box} related call we have a callout to the \type
 459 {append_to_vlist_filter}.
 460
 461 These callbacks do not replace any internal code.
 462
 463 % pre_box pre_adjust box adjust
 464
 465 \subsubsection{\type {pre_linebreak_filter}}
 466
 467 This callback is called just before \LUATEX\ starts converting a list of nodes
 468 into a stack of \type {\hbox}es, after the addition of \type {\parfillskip}.
 469
 470 \startfunctioncall
 471 function(<node> head, <string> groupcode)
 472     return true | false | <node> newhead
 473 end
 474 \stopfunctioncall
 475
 476 The string called \type {groupcode} identifies the nodelist's context within
 477 \TEX's processing. The range of possibilities is given in the table below, but
 478 not all of those can actually appear in \type {pre_linebreak_filter}, some are
 479 for the \type {hpack_filter} and \type {vpack_filter} callbacks that will be
 480 explained in the next two paragraphs.
 481
 482 \starttabulate[|lT|p|]
 483 \NC \ssbf value   \NC \bf explanation                                 \NC \NR
 484 \NC <empty>       \NC main vertical list                              \NC \NR
 485 \NC hbox          \NC \type {\hbox} in horizontal mode                \NC \NR
 486 \NC adjusted_hbox \NC \type {\hbox} in vertical mode                  \NC \NR
 487 \NC vbox          \NC \type {\vbox}                                   \NC \NR
 488 \NC vtop          \NC \type {\vtop}                                   \NC \NR
 489 \NC align         \NC \type {\halign} or \type {\valign}              \NC \NR
 490 \NC disc          \NC discretionaries                                 \NC \NR
 491 \NC insert        \NC packaging an insert                             \NC \NR
 492 \NC vcenter       \NC \type {\vcenter}                                \NC \NR
 493 \NC local_box     \NC \type {\localleftbox} or \type {\localrightbox} \NC \NR
 494 \NC split_off     \NC top of a \type {\vsplit}                        \NC \NR
 495 \NC split_keep    \NC remainder of a \type {\vsplit}                  \NC \NR
 496 \NC align_set     \NC alignment cell                                  \NC \NR
 497 \NC fin_row       \NC alignment row                                   \NC \NR
 498 \stoptabulate
 499
 500 As for all the callbacks that deal with nodes, the return value can be one of
 501 three things:
 502
 503 \startitemize
 504 \startitem
 505     boolean \type {true} signals successful processing
 506 \stopitem
 507 \startitem
 508     \type {<node>} signals that the \quote {head} node should be replaced by the
 509     returned node
 510 \stopitem
 511 \startitem
 512     boolean \type {false} signals that the \quote {head} node list should be
 513     ignored and flushed from memory
 514 \stopitem
 515 \stopitemize
 516
 517 This callback does not replace any internal code.
 518
 519 \subsubsection{\type {linebreak_filter}}
 520
 521 This callback replaces \LUATEX's line breaking algorithm.
 522
 523 \startfunctioncall
 524 function(<node> head, <boolean> is_display)
 525     return <node> newhead
 526 end
 527 \stopfunctioncall
 528
 529 The returned node is the head of the list that will be added to the main vertical
 530 list, the boolean argument is true if this paragraph is interrupted by a
 531 following math display.
 532
 533 If you return something that is not a \type {<node>}, \LUATEX\ will apply the
 534 internal linebreak algorithm on the list that starts at \type {<head>}.
 535 Otherwise, the \type {<node>} you return is supposed to be the head of a list of
 536 nodes that are all allowed in vertical mode, and at least one of those has to
 537 represent a hbox. Failure to do so will result in a fatal error.
 538
 539 Setting this callback to \type {false} is possible, but dangerous, because it is
 540 possible you will end up in an unfixable \quote {deadcycles loop}.
 541
 542 \subsubsection{\type {append_to_vlist_filter}}
 543
 544 This callback is called whenever \LUATEX\ adds a box to a vertical list:
 545
 546 \startfunctioncall
 547 function(<node> box, <string> locationcode, <number prevdepth>,
 548     <boolean> mirrored)
 549     return list, prevdepth
 550 end
 551 \stopfunctioncall
 552
 553 It is ok to return nothing in which case you also need to flush the box or deal
 554 with it yourself. The prevdepth is also optional. Locations are \type {box},
 555 \type {alignment}, \type {equation}, \type {equation_number} and \type
 556 {post_linebreak}.
 557
 558 \subsubsection{\type {post_linebreak_filter}}
 559
 560 This callback is called just after \LUATEX\ has converted a list of nodes into a
 561 stack of \type {\hbox}es.
 562
 563 \startfunctioncall
 564 function(<node> head, <string> groupcode)
 565     return true | false | <node> newhead
 566 end
 567 \stopfunctioncall
 568
 569 This callback does not replace any internal code.
 570
 571 \subsubsection{\type {hpack_filter}}
 572
 573 This callback is called when \TEX\ is ready to start boxing some horizontal mode
 574 material. Math items and line boxes are ignored at the moment.
 575
 576 \startfunctioncall
 577 function(<node> head, <string> groupcode, <number> size,
 578          <string> packtype [, <string> direction] [, <node> attributelist])
 579     return true | false | <node> newhead
 580 end
 581 \stopfunctioncall
 582
 583 The \type {packtype} is either \type {additional} or \type {exactly}. If \type
 584 {additional}, then the \type {size} is a \type {\hbox spread ...} argument. If
 585 \type {exactly}, then the \type {size} is a \type {\hbox to ...}. In both cases,
 586 the number is in scaled points.
 587
 588 The \type {direction} is either one of the three-letter direction specifier
 589 strings, or \type {nil}.
 590
 591 This callback does not replace any internal code.
 592
 593 \subsubsection{\type {vpack_filter}}
 594
 595 This callback is called when \TEX\ is ready to start boxing some vertical mode
 596 material. Math displays are ignored at the moment.
 597
 598 This function is very similar to the \type {hpack_filter}. Besides the fact
 599 that it is called at different moments, there is an extra variable that matches
 600 \TEX's \type {\maxdepth} setting.
 601
 602 \startfunctioncall
 603 function(<node> head, <string> groupcode, <number> size, <string> packtype,
 604         <number> maxdepth [, <string> direction] [, <node> attributelist]))
 605     return true | false | <node> newhead
 606 end
 607 \stopfunctioncall
 608
 609 This callback does not replace any internal code.
 610
 611 \subsubsection{\type {hpack_quality}}
 612
 613 This callback can be used to intercept the overfull messages that can result from
 614 packing a horizontal list (as happens in the par builder). The function takes a
 615 few arguments:
 616
 617 \startfunctioncall
 618 function(<string> incident, <number> detail, <node> head, <number> first,
 619          <number> last)
 620     return <node> whatever
 621 end
 622 \stopfunctioncall
 623
 624 The incident is one of \type {overfull}, \type {underfull}, \type {loose} or
 625 \type {tight}. The detail is either the amount of overflow in case of \type
 626 {overfull}, or the badness otherwise. The head is the list that is constructed
 627 (when protrusion or expansion is enabled, this is an intermediate list).
 628 Optionally you can return a node, for instance an overfull rule indicator. That
 629 node will be appended to the list (just like \TEX's own rule would).
 630
 631 \subsubsection{\type {vpack_quality}}
 632
 633 This callback can be used to intercept the overfull messages that can result from
 634 packing a vertical list (as happens in the page builder). The function takes a
 635 few arguments:
 636
 637 \startfunctioncall
 638 function(<string> incident, <number> detail, <node> head, <number> first,
 639          <number> last)
 640 end
 641 \stopfunctioncall
 642
 643 The incident is one of \type {overfull}, \type {underfull}, \type {loose} or
 644 \type {tight}. The detail is either the amount of overflow in case of \type
 645 {overfull}, or the badness otherwise. The head is the list that is constructed.
 646
 647 \subsubsection{\type {process_rule}}
 648
 649 This is an experimental callback. It can be used with rules of subtype~4
 650 (user). The callback gets three arguments: the node, the width and the
 651 height. The callback can use \type {pdf.print} to write code to the \PDF\
 652 file but beware of not messing up the final result. No checking is done.
 653
 654 \subsubsection{\type {pre_output_filter}}
 655
 656 This callback is called when \TEX\ is ready to start boxing the box 255 for \type
 657 {\output}.
 658
 659 \startfunctioncall
 660 function(<node> head, <string> groupcode, <number> size, <string> packtype,
 661         <number> maxdepth [, <string> direction])
 662     return true | false | <node> newhead
 663 end
 664 \stopfunctioncall
 665
 666 This callback does not replace any internal code.
 667
 668 \subsubsection{\type {hyphenate}}
 669
 670 \startfunctioncall
 671 function(<node> head, <node> tail)
 672 end
 673 \stopfunctioncall
 674
 675 No return values. This callback has to insert discretionary nodes in the node
 676 list it receives.
 677
 678 Setting this callback to \type {false} will prevent the internal discretionary
 679 insertion pass.
 680
 681 \subsubsection{\type {ligaturing}}
 682
 683 \startfunctioncall
 684 function(<node> head, <node> tail)
 685 end
 686 \stopfunctioncall
 687
 688 No return values. This callback has to apply ligaturing to the node list it
 689 receives.
 690
 691 You don't have to worry about return values because the \type {head} node that is
 692 passed on to the callback is guaranteed not to be a glyph_node (if need be, a
 693 temporary node will be prepended), and therefore it cannot be affected by the
 694 mutations that take place. After the callback, the internal value of the \quote
 695 {tail of the list} will be recalculated.
 696
 697 The \type {next} of \type {head} is guaranteed to be non-nil.
 698
 699 The \type {next} of \type {tail} is guaranteed to be nil, and therefore the
 700 second callback argument can often be ignored. It is provided for orthogonality,
 701 and because it can sometimes be handy when special processing has to take place.
 702
 703 Setting this callback to \type {false} will prevent the internal ligature
 704 creation pass.
 705
 706 You must not ruin the node list. For instance, the head normally is a local par node,
 707 and the tail a glue. Messing too much can push \LUATEX\ into panic mode.
 708
 709 \subsubsection{\type {kerning}}
 710
 711 \startfunctioncall
 712 function(<node> head, <node> tail)
 713 end
 714 \stopfunctioncall
 715
 716 No return values. This callback has to apply kerning between the nodes in the
 717 node list it receives. See \type {ligaturing} for calling conventions.
 718
 719 Setting this callback to \type {false} will prevent the internal kern insertion
 720 pass.
 721
 722 You must not ruin the node list. For instance, the head normally is a local par node,
 723 and the tail a glue. Messing too much can push \LUATEX\ into panic mode.
 724
 725 \subsubsection{\type {insert_local_par}}
 726
 727 Each paragraph starts with a local par node that keeps track of for instance
 728 the direction. You can hook a callback into the creator:
 729
 730 \startfunctioncall
 731 function(<node> local_par, <string> location)
 732 end
 733 \stopfunctioncall
 734
 735 There is no return value and you should make sure that the node stays valid
 736 as otherwise \TEX\ can get confused.
 737
 738 \subsubsection{\type {mlist_to_hlist}}
 739
 740 This callback replaces \LUATEX's math list to node list conversion algorithm.
 741
 742 \startfunctioncall
 743 function(<node> head, <string> display_type, <boolean> need_penalties)
 744     return <node> newhead
 745 end
 746 \stopfunctioncall
 747
 748 The returned node is the head of the list that will be added to the vertical or
 749 horizontal list, the string argument is either \quote {text} or \quote {display}
 750 depending on the current math mode, the boolean argument is \type {true} if
 751 penalties have to be inserted in this list, \type {false} otherwise.
 752
 753 Setting this callback to \type {false} is bad, it will almost certainly result in
 754 an endless loop.
 755
 756 \subsection{Information reporting callbacks}
 757
 758 \subsubsection{\type {pre_dump}}
 759
 760 \startfunctioncall
 761 function()
 762 end
 763 \stopfunctioncall
 764
 765 This function is called just before dumping to a format file starts. It does not
 766 replace any code and there are neither arguments nor return values.
 767
 768 \subsubsection{\type {start_run}}
 769
 770 \startfunctioncall
 771 function()
 772 end
 773 \stopfunctioncall
 774
 775 This callback replaces the code that prints \LUATEX's banner. Note that for
 776 successful use, this callback has to be set in the \LUA\ initialization script,
 777 otherwise it will be seen only after the run has already started.
 778
 779 \subsubsection{\type {stop_run}}
 780
 781 \startfunctioncall
 782 function()
 783 end
 784 \stopfunctioncall
 785
 786 This callback replaces the code that prints \LUATEX's statistics and \quote
 787 {output written to} messages.
 788
 789 \subsubsection{\type {start_page_number}}
 790
 791 \startfunctioncall
 792 function()
 793 end
 794 \stopfunctioncall
 795
 796 Replaces the code that prints the \type {[} and the page number at the begin of
 797 \type {\shipout}. This callback will also override the printing of box information
 798 that normally takes place when \type {\tracingoutput} is positive.
 799
 800 \subsubsection{\type {stop_page_number}}
 801
 802 \startfunctioncall
 803 function()
 804 end
 805 \stopfunctioncall
 806
 807 Replaces the code that prints the \type {]} at the end of \type {\shipout}.
 808
 809 \subsubsection{\type {show_error_hook}}
 810
 811 \startfunctioncall
 812 function()
 813 end
 814 \stopfunctioncall
 815
 816 This callback is run from inside the \TEX\ error function, and the idea is to
 817 allow you to do some extra reporting on top of what \TEX\ already does (none of
 818 the normal actions are removed). You may find some of the values in the \type
 819 {status} table useful. This callback does not replace any internal code.
 820
 821 \subsubsection{\type {show_error_message}}
 822
 823 \startfunctioncall
 824 function()
 825 end
 826 \stopfunctioncall
 827
 828 This callback replaces the code that prints the error message. The usual
 829 interaction after the message is not affected.
 830
 831 \subsubsection{\type {show_lua_error_hook}}
 832
 833 \startfunctioncall
 834 function()
 835 end
 836 \stopfunctioncall
 837
 838 This callback replaces the code that prints the extra \LUA\ error message.
 839
 840 \subsubsection{\type {start_file}}
 841
 842 \startfunctioncall
 843 function(category,filename)
 844 end
 845 \stopfunctioncall
 846
 847 This callback replaces the code that prints \LUATEX's when a file is opened like
 848 \type {(filename} for regular files. The category is a number:
 849
 850 \starttabulate[|||]
 851 \NC 1 \NC a normal data file, like a \TEX\ source \NC \NR
 852 \NC 2 \NC a font map coupling font names to resources \NC \NR
 853 \NC 3 \NC an image file (\type {png}, \type {pdf}, etc) \NC \NR
 854 \NC 4 \NC an embedded font subset \NC \NR
 855 \NC 5 \NC a fully embedded font \NC \NR
 856 \stoptabulate
 857
 858 \subsubsection{\type {stop_file}}
 859
 860 \startfunctioncall
 861 function(category)
 862 end
 863 \stopfunctioncall
 864
 865 This callback replaces the code that prints \LUATEX's when a file is closed like
 866 the \type {)} for regular files.
 867
 868 \subsection{PDF-related callbacks}
 869
 870 \subsubsection{\type {finish_pdffile}}
 871
 872 \startfunctioncall
 873 function()
 874 end
 875 \stopfunctioncall
 876
 877 This callback is called when all document pages are already written to the \PDF\
 878 file and \LUATEX\ is about to finalize the output document structure. Its
 879 intended use is final update of \PDF\ dictionaries such as \type {/Catalog} or
 880 \type {/Info}. The callback does not replace any code. There are neither
 881 arguments nor return values.
 882
 883 \subsubsection{\type {finish_pdfpage}}
 884
 885 \startfunctioncall
 886 function(shippingout)
 887 end
 888 \stopfunctioncall
 889
 890 This callback is called after the \PDF\ page stream has been assembled and before
 891 the page object gets finalized.
 892
 893 \subsection{Font-related callbacks}
 894
 895 \subsubsection{\type {define_font}}
 896
 897 \startfunctioncall
 898 function(<string> name, <number> size, <number> id)
 899     return <table> font | <number> id
 900 end
 901 \stopfunctioncall
 902
 903 The string \type {name} is the filename part of the font specification, as given
 904 by the user.
 905
 906 The number \type {size} is a bit special:
 907
 908 \startitemize[packed]
 909 \startitem
 910     If it is positive, it specifies an \quote{at size} in scaled points.
 911 \stopitem
 912 \startitem
 913     If it is negative, its absolute value represents a \quote {scaled} setting
 914     relative to the designsize of the font.
 915 \stopitem
 916 \stopitemize
 917
 918 The \type {id} is the internal number assigned to the font.
 919
 920 The internal structure of the \type {font} table that is to be returned is
 921 explained in \in {chapter} [fonts]. That table is saved internally, so you can
 922 put extra fields in the table for your later \LUA\ code to use. In alternative,
 923 \type {retval} can be a previously defined fontid. This is useful if a previous
 924 definition can be reused instead of creating a whole new font structure.
 925
 926 Setting this callback to \type {false} is pointless as it will prevent font
 927 loading completely but will nevertheless generate errors.
 928
 929 \section{The \type {epdf} library}
 930
 931 The \type {epdf} library provides \LUA\ bindings to many \PDF\ access functions
 932 that are defined by the poppler \PDF\ viewer library (written in C$+{}+$ by
 933 Kristian H\o gsberg, based on xpdf by Derek Noonburg). Within \LUATEX\ (and
 934 \PDFTEX), xpdf functionality is being used since long time to embed \PDF\ files.
 935 The \type {epdf} library shall allow to scrutinize an external \PDF\ file. It
 936 gives access to its document structure: catalog, cross|-|reference table,
 937 individual pages, objects, annotations, info, and metadata. The \LUATEX\ team is
 938 evaluating the possibility of reducing the binding to a basic low level \PDF\
 939 primitives and delegate the complete set of functions to an external shared
 940 object module.
 941
 942 The \type {epdf} library is still in alpha state: \PDF\ access is currently
 943 read|-|only. Iit's not yet possible to alter a \PDF\ file or to assemble it from
 944 scratch, and many function bindings are still missing, and it is unlikely that we
 945 to support that at all. At some point we might also decide to limit the interface
 946 to a reasonable subset.
 947
 948 For a start, a \PDF\ file is opened by \type {epdf.open()} with file name, e.g.:
 949
 950 \starttyping
 951 doc = epdf.open("foo.pdf")
 952 \stoptyping
 953
 954 This normally returns a \type {PDFDoc} userdata variable; but if the file could
 955 not be opened successfully, instead of a fatal error just the value \type {nil} is
 956 returned.
 957
 958 All Lua functions in the \type {epdf} library are named after the poppler
 959 functions listed in the poppler header files for the various classes, e.g., files
 960 \type {PDFDoc.h}, \type {Dict.h}, and \type {Array.h}. These files can be found
 961 in the poppler subdirectory within the \LUATEX\ sources. Which functions are
 962 already implemented in the \type {epdf} library can be found in the \LUATEX\
 963 source file \type {lepdflib.cc}. For using the \type {epdf} library, knowledge of
 964 the \PDF\ file architecture is indispensable.
 965
 966 There are many different userdata types defined by the \type {epdf} library,
 967 currently these are \type {AnnotBorderStyle}, \type {AnnotBorder}, \type
 968 {Annots}, \type {Annot}, \type {Array}, \type {Attribute}, \type {Catalog}, \type
 969 {Dict}, \type {EmbFile}, \type {GString}, \type {LinkDest}, \type {Links}, \type
 970 {Link}, \type {ObjectStream}, \type {Object}, \type {PDFDoc}, \type
 971 {PDFRectangle}, \type {Page}, \type {Ref}, \type {Stream}, \type {StructElement},
 972 \type {StructTreeRoot} \type {TextSpan}, \type {XRefEntry} and \type {XRef}.
 973
 974 All these userdata names and the Lua access functions closely resemble the
 975 classes naming from the poppler header files, including the choice of mixed upper
 976 and lower case letters. The Lua function calls use object|-|oriented syntax,
 977 e.g., the following calls return the \type {Page} object for page~1:
 978
 979 \starttyping
 980 pageref = doc:getCatalog():getPageRef(1)
 981 pageobj = doc:getXRef():fetch(pageref.num, pageref.gen)
 982 \stoptyping
 983
 984 But writing such chained calls is risky, as an intermediate function may return
 985 \type {nil} on error; therefore between function calls there should be Lua type
 986 checks (e.g., against \type {nil}) done. If a non-object item is requested (e.g.,
 987 a \type {Dict} item by calling \type {page:getPieceInfo()}, cf.~\type {Page.h})
 988 but not available, the Lua functions return \type {nil} (without error). If a
 989 function should return an \type {Object}, but it's not existing, a \type {Null}
 990 object is returned instead (also without error; this is in|-|line with poppler
 991 behavior).
 992
 993 All library objects have a \type {__gc} metamethod for garbage collection. The
 994 \type {__tostring} metamethod gives the type name for each object.
 995
 996 All object constructors:
 997
 998 \startfunctioncall
 999 <PDFDoc>       = epdf.open(<string> PDF filename)
1000 <Annot>        = epdf.Annot(<XRef>, <Dict>, <Catalog>, <Ref>)
1001 <Annots>       = epdf.Annots(<XRef>, <Catalog>, <Object>)
1002 <Array>        = epdf.Array(<XRef>)
1003 <Attribute>    = epdf.Attribute(<Type>,<Object>)| epdf.Attribute(<string>, <int>, <Object>)
1004 <Dict>         = epdf.Dict(<XRef>)
1005 <Object>       = epdf.Object()
1006 <PDFRectangle> = epdf.PDFRectangle()
1007 \stopfunctioncall
1008
1009 The functions \type {StructElement_Type}, \type {Attribute_Type} and \type
1010 {AttributeOwner_Type} return a hash table \type {{<string>,<integer>}}.
1011
1012 \type {Annot} methods:
1013
1014 \startfunctioncall
1015 <boolean>     = <Annot>:isOK()
1016 <Object>      = <Annot>:getAppearance()
1017 <AnnotBorder> = <Annot>:getBorder()
1018 <boolean>     = <Annot>:match(<Ref>)
1019 \stopfunctioncall
1020
1021 \type {AnnotBorderStyle} methods:
1022
1023 \startfunctioncall
1024 <number> = <AnnotBorderStyle>:getWidth()
1025 \stopfunctioncall
1026
1027 \type {Annots} methods:
1028
1029 \startfunctioncall
1030 <integer> = <Annots>:getNumAnnots()
1031 <Annot>   = <Annots>:getAnnot(<integer>)
1032 \stopfunctioncall
1033
1034 \type {Array} methods:
1035
1036 \startfunctioncall
1037             <Array>:incRef()
1038             <Array>:decRef()
1039 <integer> = <Array>:getLength()
1040             <Array>:add(<Object>)
1041 <Object>  = <Array>:get(<integer>)
1042 <Object>  = <Array>:getNF(<integer>)
1043 <string>  = <Array>:getString(<integer>)
1044 \stopfunctioncall
1045
1046 \type {Attribute} methods:
1047
1048 \startfunctioncall
1049 <boolean>  = <Attribute>:isOk()
1050 <integer>  = <Attribute>:getType()
1051 <integer>  = <Attribute>:getOwner()
1052 <string>   = <Attribute>:getTypeName()
1053 <string>   = <Attribute>:getOwnerName()
1054 <Object>   = <Attribute>:getValue()
1055 <Object>   = <Attribute>:getDefaultValue
1056 <string>   = <Attribute>:getName()
1057 <integer>  = <Attribute>:getRevision()
1058              <Attribute>:setRevision(<unsigned integer>)
1059 <boolean>  = <Attribute>:istHidden()
1060              <Attribute>:setHidden(<boolean>)
1061 <string>   = <Attribute>:getFormattedValue()
1062 <string>   = <Attribute>:setFormattedValue(<string>)
1063 \stopfunctioncall
1064
1065 \type {Catalog} methods:
1066
1067 \startfunctioncall
1068 <boolean>  = <Catalog>:isOK()
1069 <integer>  = <Catalog>:getNumPages()
1070 <Page>     = <Catalog>:getPage(<integer>)
1071 <Ref>      = <Catalog>:getPageRef(<integer>)
1072 <string>   = <Catalog>:getBaseURI()
1073 <string>   = <Catalog>:readMetadata()
1074 <Object>   = <Catalog>:getStructTreeRoot()
1075 <integer>  = <Catalog>:findPage(<integer> object number, <integer> object generation)
1076 <LinkDest> = <Catalog>:findDest(<string> name)
1077 <Object>   = <Catalog>:getDests()
1078 <integer>  = <Catalog>:numEmbeddedFiles()
1079 <EmbFile>  = <Catalog>:embeddedFile(<integer>)
1080 <integer>  = <Catalog>:numJS()
1081 <string>   = <Catalog>:getJS(<integer>)
1082 <Object>   = <Catalog>:getOutline()
1083 <Object>   = <Catalog>:getAcroForm()
1084 \stopfunctioncall
1085
1086 \type {EmbFile} methods:
1087
1088 \startfunctioncall
1089 <string>   = <EmbFile>:name()
1090 <string>   = <EmbFile>:description()
1091 <integer>  = <EmbFile>:size()
1092 <string>   = <EmbFile>:modDate()
1093 <string>   = <EmbFile>:createDate()
1094 <string>   = <EmbFile>:checksum()
1095 <string>   = <EmbFile>:mimeType()
1096 <Object>   = <EmbFile>:streamObject()
1097 <boolean>  = <EmbFile>:isOk()
1098 \stopfunctioncall
1099
1100 \type {Dict} methods:
1101
1102 \startfunctioncall
1103             <Dict>:incRef()
1104             <Dict>:decRef()
1105 <integer> = <Dict>:getLength()
1106             <Dict>:add(<string>, <Object>)
1107             <Dict>:set(<string>, <Object>)
1108             <Dict>:remove(<string>)
1109 <boolean> = <Dict>:is(<string>)
1110 <Object>  = <Dict>:lookup(<string>)
1111 <Object>  = <Dict>:lookupNF(<string>)
1112 <integer> = <Dict>:lookupInt(<string>, <string>)
1113 <string>  = <Dict>:getKey(<integer>)
1114 <Object>  = <Dict>:getVal(<integer>)
1115 <Object>  = <Dict>:getValNF(<integer>)
1116 <boolean> = <Dict>:hasKey(<string>)
1117 \stopfunctioncall
1118
1119 \type {Link} methods:
1120
1121 \startfunctioncall
1122 <boolean>  = <Link>:isOK()
1123 <boolean>  = <Link>:inRect(<number>, <number>)
1124 \stopfunctioncall
1125
1126 \type {LinkDest} methods:
1127
1128 \startfunctioncall
1129 <boolean>  = <LinkDest>:isOK()
1130 <integer>  = <LinkDest>:getKind()
1131 <string>   = <LinkDest>:getKindName()
1132 <boolean>  = <LinkDest>:isPageRef()
1133 <integer>  = <LinkDest>:getPageNum()
1134 <Ref>      = <LinkDest>:getPageRef()
1135 <number>   = <LinkDest>:getLeft()
1136 <number>   = <LinkDest>:getBottom()
1137 <number>   = <LinkDest>:getRight()
1138 <number>   = <LinkDest>:getTop()
1139 <number>   = <LinkDest>:getZoom()
1140 <boolean>  = <LinkDest>:getChangeLeft()
1141 <boolean>  = <LinkDest>:getChangeTop()
1142 <boolean>  = <LinkDest>:getChangeZoom()
1143 \stopfunctioncall
1144
1145 \type {Links} methods:
1146
1147 \startfunctioncall
1148 <integer>  = <Links>:getNumLinks()
1149 <Link>     = <Links>:getLink(<integer>)
1150 \stopfunctioncall
1151
1152 \type {Object} methods:
1153
1154 \startfunctioncall
1155             <Object>:initBool(<boolean>)
1156             <Object>:initInt(<integer>)
1157             <Object>:initReal(<number>)
1158             <Object>:initString(<string>)
1159             <Object>:initName(<string>)
1160             <Object>:initNull()
1161             <Object>:initArray(<XRef>)
1162             <Object>:initDict(<XRef>)
1163             <Object>:initStream(<Stream>)
1164             <Object>:initRef(<integer> object number, <integer> object generation)
1165             <Object>:initCmd(<string>)
1166             <Object>:initError()
1167             <Object>:initEOF()
1168 <Object>  = <Object>:fetch(<XRef>)
1169 <integer> = <Object>:getType()
1170 <string>  = <Object>:getTypeName()
1171 <boolean> = <Object>:isBool()
1172 <boolean> = <Object>:isInt()
1173 <boolean> = <Object>:isReal()
1174 <boolean> = <Object>:isNum()
1175 <boolean> = <Object>:isString()
1176 <boolean> = <Object>:isName()
1177 <boolean> = <Object>:isNull()
1178 <boolean> = <Object>:isArray()
1179 <boolean> = <Object>:isDict()
1180 <boolean> = <Object>:isStream()
1181 <boolean> = <Object>:isRef()
1182 <boolean> = <Object>:isCmd()
1183 <boolean> = <Object>:isError()
1184 <boolean> = <Object>:isEOF()
1185 <boolean> = <Object>:isNone()
1186 <boolean> = <Object>:getBool()
1187 <integer> = <Object>:getInt()
1188 <number>  = <Object>:getReal()
1189 <number>  = <Object>:getNum()
1190 <string>  = <Object>:getString()
1191 <string>  = <Object>:getName()
1192 <Array>   = <Object>:getArray()
1193 <Dict>    = <Object>:getDict()
1194 <Stream>  = <Object>:getStream()
1195 <Ref>     = <Object>:getRef()
1196 <integer> = <Object>:getRefNum()
1197 <integer> = <Object>:getRefGen()
1198 <string>  = <Object>:getCmd()
1199 <integer> = <Object>:arrayGetLength()
1200           = <Object>:arrayAdd(<Object>)
1201 <Object>  = <Object>:arrayGet(<integer>)
1202 <Object>  = <Object>:arrayGetNF(<integer>)
1203 <integer> = <Object>:dictGetLength(<integer>)
1204           = <Object>:dictAdd(<string>, <Object>)
1205           = <Object>:dictSet(<string>, <Object>)
1206 <Object>  = <Object>:dictLookup(<string>)
1207 <Object>  = <Object>:dictLookupNF(<string>)
1208 <string>  = <Object>:dictgetKey(<integer>)
1209 <Object>  = <Object>:dictgetVal(<integer>)
1210 <Object>  = <Object>:dictgetValNF(<integer>)
1211 <boolean> = <Object>:streamIs(<string>)
1212           = <Object>:streamReset()
1213 <integer> = <Object>:streamGetChar()
1214 <integer> = <Object>:streamLookChar()
1215 <integer> = <Object>:streamGetPos()
1216           = <Object>:streamSetPos(<integer>)
1217 <Dict>    = <Object>:streamGetDict()
1218 \stopfunctioncall
1219
1220 \type {Page} methods:
1221
1222 \startfunctioncall
1223 <boolean>      = <Page>:isOk()
1224 <integer>      = <Page>:getNum()
1225 <PDFRectangle> = <Page>:getMediaBox()
1226 <PDFRectangle> = <Page>:getCropBox()
1227 <boolean>      = <Page>:isCropped()
1228 <number>       = <Page>:getMediaWidth()
1229 <number>       = <Page>:getMediaHeight()
1230 <number>       = <Page>:getCropWidth()
1231 <number>       = <Page>:getCropHeight()
1232 <PDFRectangle> = <Page>:getBleedBox()
1233 <PDFRectangle> = <Page>:getTrimBox()
1234 <PDFRectangle> = <Page>:getArtBox()
1235 <integer>      = <Page>:getRotate()
1236 <string>       = <Page>:getLastModified()
1237 <Dict>         = <Page>:getBoxColorInfo()
1238 <Dict>         = <Page>:getGroup()
1239 <Stream>       = <Page>:getMetadata()
1240 <Dict>         = <Page>:getPieceInfo()
1241 <Dict>         = <Page>:getSeparationInfo()
1242 <Dict>         = <Page>:getResourceDict()
1243 <Object>       = <Page>:getAnnots()
1244 <Links>        = <Page>:getLinks(<Catalog>)
1245 <Object>       = <Page>:getContents()
1246 \stopfunctioncall
1247
1248 \type {PDFDoc} methods:
1249
1250 \startfunctioncall
1251 <boolean>  = <PDFDoc>:isOk()
1252 <integer>  = <PDFDoc>:getErrorCode()
1253 <string>   = <PDFDoc>:getErrorCodeName()
1254 <string>   = <PDFDoc>:getFileName()
1255 <XRef>     = <PDFDoc>:getXRef()
1256 <Catalog>  = <PDFDoc>:getCatalog()
1257 <number>   = <PDFDoc>:getPageMediaWidth()
1258 <number>   = <PDFDoc>:getPageMediaHeight()
1259 <number>   = <PDFDoc>:getPageCropWidth()
1260 <number>   = <PDFDoc>:getPageCropHeight()
1261 <integer>  = <PDFDoc>:getNumPages()
1262 <string>   = <PDFDoc>:readMetadata()
1263 <Object>   = <PDFDoc>:getStructTreeRoot()
1264 <integer>  = <PDFDoc>:findPage(<integer> object number, <integer> object generation)
1265 <Links>    = <PDFDoc>:getLinks(<integer>)
1266 <LinkDest> = <PDFDoc>:findDest(<string>)
1267 <boolean>  = <PDFDoc>:isEncrypted()
1268 <boolean>  = <PDFDoc>:okToPrint()
1269 <boolean>  = <PDFDoc>:okToChange()
1270 <boolean>  = <PDFDoc>:okToCopy()
1271 <boolean>  = <PDFDoc>:okToAddNotes()
1272 <boolean>  = <PDFDoc>:isLinearized()
1273 <Object>   = <PDFDoc>:getDocInfo()
1274 <Object>   = <PDFDoc>:getDocInfoNF()
1275 <integer>  = <PDFDoc>:getPDFMajorVersion()
1276 <integer>  = <PDFDoc>:getPDFMinorVersion()
1277 \stopfunctioncall
1278
1279 \type {PDFRectangle} methods:
1280
1281 \startfunctioncall
1282 <boolean>  = <PDFRectangle>:isValid()
1283 \stopfunctioncall
1284
1285 %\type {Ref} methods:
1286 %
1287 %\startfunctioncall
1288 %\stopfunctioncall
1289
1290 \type {Stream} methods:
1291
1292 \startfunctioncall
1293 <integer>  = <Stream>:getKind()
1294 <string>   = <Stream>:getKindName()
1295            = <Stream>:reset()
1296            = <Stream>:close()
1297 <integer>  = <Stream>:getChar()
1298 <integer>  = <Stream>:lookChar()
1299 <integer>  = <Stream>:getRawChar()
1300 <integer>  = <Stream>:getUnfilteredChar()
1301            = <Stream>:unfilteredReset()
1302 <integer>  = <Stream>:getPos()
1303 <boolean>  = <Stream>:isBinary()
1304 <Stream>   = <Stream>:getUndecodedStream()
1305 <Dict>     = <Stream>:getDict()
1306 \stopfunctioncall
1307
1308 \type {StructElement} methods:
1309
1310 \startfunctioncall
1311 <string>         = <StructElement>:getTypeName()
1312 <integer>        = <StructElement>:getType()
1313 <boolean>        = <StructElement>:isOk()
1314 <boolean>        = <StructElement>:isBlock()
1315 <boolean>        = <StructElement>:isInline()
1316 <boolean>        = <StructElement>:isGrouping()
1317 <boolean>        = <StructElement>:isContent()
1318 <boolean>        = <StructElement>:isObjectRef()
1319 <integer>        = <StructElement>:getMCID()
1320 <Ref>            = <StructElement>:getObjectRef()
1321 <Ref>            = <StructElement>:getParentRef()
1322 <boolean>        = <StructElement>:hasPageRef()
1323 <Ref>            = <StructElement>:getPageRef()
1324 <StructTreeRoot> = <StructElement>:getStructTreeRoot()
1325 <string>         = <StructElement>:getID()
1326 <string>         = <StructElement>:getLanguage()
1327 <integer>        = <StructElement>:getRevision()
1328                    <StructElement>:setRevision(<unsigned integer>)
1329 <string>         = <StructElement>:getTitle()
1330 <string>         = <StructElement>:getExpandedAbbr()
1331 <integer>        = <StructElement>:getNumChildren()
1332 <StructElement>  = <StructElement>:getChild()
1333                  = <StructElement>:appendChild<StructElement>)
1334 <integer>        = <StructElement>:getNumAttributes()
1335 <Attribute>      = <StructElement>:geAttribute(<integer>)
1336 <string>         = <StructElement>:appendAttribute(<Attribute>)
1337 <Attribute>      = <StructElement>:findAttribute(<Attribute::Type>,boolean,Attribute::Owner)
1338 <string>         = <StructElement>:getAltText()
1339 <string>         = <StructElement>:getActualText()
1340 <string>         = <StructElement>:getText(<boolean>)
1341 <table>          = <StructElement>:getTextSpans()
1342 \stopfunctioncall
1343
1344 \type {StructTreeRoot} methods:
1345
1346 \startfunctioncall
1347 <StructElement> = <StructTreeRoot>:findParentElement
1348 <PDFDoc>        = <StructTreeRoot>:getDoc
1349 <Dict>          = <StructTreeRoot>:getRoleMap
1350 <Dict>          = <StructTreeRoot>:getClassMap
1351 <integer>       = <StructTreeRoot>:getNumChildren
1352 <StructElement> = <StructTreeRoot>:getChild
1353                   <StructTreeRoot>:appendChild
1354 <StructElement> = <StructTreeRoot>:findParentElement
1355 \stopfunctioncall
1356
1357 \type {TextSpan} han only one method:
1358
1359 \startfunctioncall
1360 <string> = <TestSpan>:getText()
1361 \stopfunctioncall
1362
1363 \type {XRef} methods:
1364
1365 \startfunctioncall
1366 <boolean>  = <XRef>:isOk()
1367 <integer>  = <XRef>:getErrorCode()
1368 <boolean>  = <XRef>:isEncrypted()
1369 <boolean>  = <XRef>:okToPrint()
1370 <boolean>  = <XRef>:okToPrintHighRes()
1371 <boolean>  = <XRef>:okToChange()
1372 <boolean>  = <XRef>:okToCopy()
1373 <boolean>  = <XRef>:okToAddNotes()
1374 <boolean>  = <XRef>:okToFillForm()
1375 <boolean>  = <XRef>:okToAccessibility()
1376 <boolean>  = <XRef>:okToAssemble()
1377 <Object>   = <XRef>:getCatalog()
1378 <Object>   = <XRef>:fetch(<integer> object number, <integer> object generation)
1379 <Object>   = <XRef>:getDocInfo()
1380 <Object>   = <XRef>:getDocInfoNF()
1381 <integer>  = <XRef>:getNumObjects()
1382 <integer>  = <XRef>:getRootNum()
1383 <integer>  = <XRef>:getRootGen()
1384 <integer>  = <XRef>:getSize()
1385 <Object>   = <XRef>:getTrailerDict()
1386 \stopfunctioncall
1387
1388 There is an experimental function \type {epdf.openMemStream} that takes three
1389 arguments:
1390
1391 \starttabulate
1392 \NC \type {stream}  \NC this is a (in low level \LUA\ speak) light userdata
1393                         object, i.e.\ a pointer to a sequence of bytes \NC \NR
1394 \NC \type {length}  \NC this is the length of the stream in bytes \NC \NR
1395 \NC \type {name}    \NC this is a unique identifier that us used for hashing the
1396                         stream, so that mulltiple doesn't use more memory \NC \NR
1397 \stoptabulate
1398
1399 Instead of a light userdata stream you can also pass a \LUA\ string, in which
1400 case the given length is (at most) the string length.
1401
1402 The returned object can be used in the \type {img} library instead of a filename.
1403 Both the memory stream and it's use in the image library is experimental and can
1404 change. In case you wonder where this can be used: when you use the swiglib
1405 library for \type {graphicmagick}, it can return such a userdata object. This
1406 permits conversion in memory and passing the result directly to the backend. This
1407 might save some runtime in one|-|pass workflows. This feature is currently not
1408 meant for production.
1409
1410 \section{The \type {font} library}
1411
1412 The font library provides the interface into the internals of the font system,
1413 and also it contains helper functions to load traditional \TEX\ font metrics
1414 formats. Other font loading functionality is provided by the \type {fontloader}
1415 library that will be discussed in the next section.
1416
1417 \subsection{Loading a \TFM\ file}
1418
1419 The behavior documented in this subsection is considered stable in the sense that
1420 there will not be backward-incompatible changes any more.
1421
1422 \startfunctioncall
1423 <table> fnt = font.read_tfm(<string> name, <number> s)
1424 \stopfunctioncall
1425
1426 The number is a bit special:
1427
1428 \startitemize
1429 \startitem
1430     If it is positive, it specifies an \quote {at size} in scaled points.
1431 \stopitem
1432 \startitem
1433     If it is negative, its absolute value represents a \quote {scaled}
1434     setting relative to the designsize of the font.
1435 \stopitem
1436 \stopitemize
1437
1438 The internal structure of the metrics font table that is returned is explained in
1439 \in {chapter} [fonts].
1440
1441 \subsection{Loading a \VF\ file}
1442
1443 The behavior documented in this subsection is considered stable in the sense that
1444 there will not be backward-incompatible changes any more.
1445
1446 \startfunctioncall
1447 <table> vf_fnt = font.read_vf(<string> name, <number> s)
1448 \stopfunctioncall
1449
1450 The meaning of the number \type {s} and the format of the returned table are
1451 similar to the ones in the \type {read_tfm()} function.
1452
1453 \subsection{The fonts array}
1454
1455 The whole table of \TEX\ fonts is accessible from \LUA\ using a virtual array.
1456
1457 \starttyping
1458 font.fonts[n] = { ... }
1459 <table> f = font.fonts[n]
1460 \stoptyping
1461
1462 See \in {chapter} [fonts] for the structure of the tables. Because this is a
1463 virtual array, you cannot call \type {pairs} on it, but see below for the \type
1464 {font.each} iterator.
1465
1466 The two metatable functions implementing the virtual array are:
1467
1468 \startfunctioncall
1469 <table> f = font.getfont(<number> n)
1470 font.setfont(<number> n, <table> f)
1471 \stopfunctioncall
1472
1473 Note that at the moment, each access to the \type {font.fonts} or call to \type
1474 {font.getfont} creates a \LUA\ table for the whole font. This process can be quite
1475 slow. In a later version of \LUATEX, this interface will change (it will start
1476 using userdata objects instead of actual tables).
1477
1478 Also note the following: assignments can only be made to fonts that have already
1479 been defined in \TEX, but have not been accessed {\it at all\/} since that
1480 definition. This limits the usability of the write access to \type {font.fonts}
1481 quite a lot, a less stringent ruleset will likely be implemented later.
1482
1483 \subsection{Checking a font's status}
1484
1485 You can test for the status of a font by calling this function:
1486
1487 \startfunctioncall
1488 <boolean> f = font.frozen(<number> n)
1489 \stopfunctioncall
1490
1491 The return value is one of \type {true} (unassignable), \type {false} (can be
1492 changed) or \type {nil} (not a valid font at all).
1493
1494 \subsection{Defining a font directly}
1495
1496 You can define your own font into \type {font.fonts} by calling this function:
1497
1498 \startfunctioncall
1499 <number> i = font.define(<table> f)
1500 \stopfunctioncall
1501
1502 The return value is the internal id number of the defined font (the index into
1503 \type {font.fonts}). If the font creation fails, an error is raised. The table
1504 is a font structure, as explained in \in {chapter} [fonts].
1505
1506 \subsection{Projected next font id}
1507
1508 \startfunctioncall
1509 <number> i = font.nextid()
1510 \stopfunctioncall
1511
1512 This returns the font id number that would be returned by a \type {font.define}
1513 call if it was executed at this spot in the code flow. This is useful for virtual
1514 fonts that need to reference themselves.
1515
1516 \subsection{Font id}
1517
1518 \startfunctioncall
1519 <number> i = font.id(<string> csname)
1520 \stopfunctioncall
1521
1522 This returns the font id associated with \type {csname} string, or $-1$ if \type
1523 {csname} is not defined.
1524
1525 \subsection{Currently active font}
1526
1527 \startfunctioncall
1528 <number> i = font.current()
1529 font.current(<number> i)
1530 \stopfunctioncall
1531
1532 This gets or sets the currently used font number.
1533
1534 \subsection{Maximum font id}
1535
1536 \startfunctioncall
1537 <number> i = font.max()
1538 \stopfunctioncall
1539
1540 This is the largest used index in \type {font.fonts}.
1541
1542 \subsection{Iterating over all fonts}
1543
1544 \startfunctioncall
1545 for i,v in font.each() do
1546   ...
1547 end
1548 \stopfunctioncall
1549
1550 This is an iterator over each of the defined \TEX\ fonts. The first returned
1551 value is the index in \type {font.fonts}, the second the font itself, as a \LUA\
1552 table. The indices are listed incrementally, but they do not always form an array
1553 of consecutive numbers: in some cases there can be holes in the sequence.
1554
1555 \section{The \type {fontloader} library}
1556
1557 \subsection{Getting quick information on a font}
1558
1559 \startfunctioncall
1560 <table> info = fontloader.info(<string> filename)
1561 \stopfunctioncall
1562
1563 This function returns either \type {nil}, or a \type {table}, or an array of
1564 small tables (in the case of a \TRUETYPE\ collection). The returned table(s) will
1565 contain some fairly interesting information items from the font(s) defined by the
1566 file:
1567
1568 \starttabulate[|lT|l|p|]
1569 \NC \ssbf key    \NC \bf type \NC \bf explanation \NC \NR
1570 \NC fontname     \NC string   \NC the \POSTSCRIPT\ name of the font\NC \NR
1571 \NC fullname     \NC string   \NC the formal name of the font\NC \NR
1572 \NC familyname   \NC string   \NC the family name this font belongs to\NC \NR
1573 \NC weight       \NC string   \NC a string indicating the color value of the font\NC \NR
1574 \NC version      \NC string   \NC the internal font version\NC \NR
1575 \NC italicangle  \NC float    \NC the slant angle\NC \NR
1576 \NC units_per_em \NC number   \NC 1000 for \POSTSCRIPT-based fonts, usually 2048 for \TRUETYPE\NC \NR
1577 \NC pfminfo      \NC table    \NC (see \in{section}[fontloaderpfminfotable])\NC \NR
1578 \stoptabulate
1579
1580 Getting information through this function is (sometimes much) more efficient than
1581 loading the font properly, and is therefore handy when you want to create a
1582 dictionary of available fonts based on a directory contents.
1583
1584 \subsection{Loading an \OPENTYPE\ or \TRUETYPE\ file}
1585 If you want to use an \OPENTYPE\ font, you have to get the metric information
1586 from somewhere. Using the \type {fontloader} library, the simplest way to get
1587 that information is thus:
1588
1589 \starttyping
1590 function load_font (filename)
1591   local metrics = nil
1592   local font = fontloader.open(filename)
1593   if font then
1594      metrics = fontloader.to_table(font)
1595      fontloader.close(font)
1596   end
1597   return metrics
1598 end
1599
1600 myfont = load_font('/opt/tex/texmf/fonts/data/arial.ttf')
1601 \stoptyping
1602
1603 The main function call is
1604
1605 \startfunctioncall
1606 <userdata> f, <table> w = fontloader.open(<string> filename)
1607 <userdata> f, <table> w = fontloader.open(<string> filename, <string> fontname)
1608 \stopfunctioncall
1609
1610 The first return value is a userdata representation of the font. The second
1611 return value is a table containing any warnings and errors reported by fontloader
1612 while opening the font. In normal typesetting, you would probably ignore the
1613 second argument, but it can be useful for debugging purposes.
1614
1615 For \TRUETYPE\ collections (when filename ends in 'ttc') and \DFONT\ collections,
1616 you have to use a second string argument to specify which font you want from the
1617 collection. Use the \type {fontname} strings that are returned by \type
1618 {fontloader.info} for that.
1619
1620 To turn the font into a table, \type {fontloader.to_table} is used on the font
1621 returned by \type {fontloader.open}.
1622
1623 \startfunctioncall
1624 <table> f = fontloader.to_table(<userdata> font)
1625 \stopfunctioncall
1626
1627 This table cannot be used directly by \LUATEX\ and should be turned into another
1628 one as described in~\in {chapter} [fonts]. Do not forget to store the \type
1629 {fontname} value in the \type {psname} field of the metrics table to be returned
1630 to \LUATEX, otherwise the font inclusion backend will not be able to find the
1631 correct font in the collection.
1632
1633 See \in {section} [fontloadertables] for details on the userdata object returned
1634 by \type {fontloader.open()} and the layout of the \type {metrics} table returned
1635 by \type {fontloader.to_table()}.
1636
1637 The font file is parsed and partially interpreted by the font loading routines
1638 from \FONTFORGE. The file format can be \OPENTYPE, \TRUETYPE, \TRUETYPE\
1639 Collection, \CFF, or \TYPEONE.
1640
1641 There are a few advantages to this approach compared to reading the actual font
1642 file ourselves:
1643
1644 \startitemize
1645
1646 \startitem
1647     The font is automatically re|-|encoded, so that the \type {metrics} table for
1648     \TRUETYPE\ and \OPENTYPE\ fonts is using \UNICODE\ for the character indices.
1649 \stopitem
1650
1651 \startitem
1652     Many features are pre|-|processed into a format that is easier to handle than
1653     just the bare tables would be.
1654 \stopitem
1655
1656 \startitem
1657     \POSTSCRIPT|-|based \OPENTYPE\ fonts do not store the character height and
1658     depth in the font file, so the character boundingbox has to be calculated in
1659     some way.
1660 \stopitem
1661
1662 \startitem
1663     In the future, it may be interesting to allow \LUA\ scripts access to
1664     the font program itself, perhaps even creating or changing the font.
1665 \stopitem
1666
1667 \stopitemize
1668
1669 A loaded font is discarded with:
1670
1671 \startfunctioncall
1672 fontloader.close(<userdata> font)
1673 \stopfunctioncall
1674
1675 \subsection{Applying a \quote{feature file}}
1676
1677 You can apply a \quote{feature file} to a loaded font:
1678
1679 \startfunctioncall
1680 <table> errors = fontloader.apply_featurefile(<userdata> font, <string> filename)
1681 \stopfunctioncall
1682
1683 A \quote {feature file} is a textual representation of the features in an
1684 \OPENTYPE\ font. See
1685
1686 \starttyping
1687 http://www.adobe.com/devnet/opentype/afdko/topic_feature_file_syntax.html
1688 \stoptyping
1689
1690 and
1691
1692 \starttyping
1693 http://fontforge.sourceforge.net/featurefile.html
1694 \stoptyping
1695
1696 for a more detailed description of feature files.
1697
1698 If the function fails, the return value is a table containing any errors reported
1699 by fontloader while applying the feature file. On success, \type {nil} is
1700 returned.
1701
1702 \subsection{Applying an \quote{\AFM\ file}}
1703
1704 You can apply an \quote {\AFM\ file} to a loaded font:
1705
1706 \startfunctioncall
1707 <table> errors = fontloader.apply_afmfile(<userdata> font, <string> filename)
1708 \stopfunctioncall
1709
1710 An \AFM\ file is a textual representation of (some of) the meta information
1711 in a \TYPEONE\ font. See
1712
1713 \starttyping
1714 ftp://ftp.math.utah.edu/u/ma/hohn/linux/postscript/5004.AFM_Spec.pdf
1715 \stoptyping
1716
1717 for more information about \AFM\ files.
1718
1719 Note: If you \type {fontloader.open()} a \TYPEONE\ file named \type {font.pfb},
1720 the library will automatically search for and apply \type {font.afm} if it exists
1721 in the same directory as the file \type {font.pfb}. In that case, there is no
1722 need for an explicit call to \type {apply_afmfile()}.
1723
1724 If the function fails, the return value is a table containing any errors reported
1725 by fontloader while applying the AFM file. On success, \type {nil} is returned.
1726
1727 \subsection[fontloadertables]{Fontloader font tables}
1728
1729 As mentioned earlier, the return value of \type {fontloader.open()} is a userdata
1730 object. One way to have access to the actual metrics is to call \type
1731 {fontloader.to_table()} on this object, returning the table structure that is
1732 explained in the following subsections.
1733
1734 However, it turns out that the result from \type {fontloader.to_table()}
1735 sometimes needs very large amounts of memory (depending on the font's complexity
1736 and size) so it is possible to access the userdata object directly.
1737
1738 \startitemize
1739 \startitem
1740     All top|-|level keys that would be returned by \type {to_table()}
1741     can also be accessed directly.
1742 \stopitem
1743 \startitem
1744 \startitem
1745     The top|-|level key \quote {glyphs} returns a {\it virtual\/} array that
1746     allows indices from \type {f.glyphmin} to (\type {f.glyphmax}).
1747 \stopitem
1748 \startitem
1749     The items in that virtual array (the actual glyphs) are themselves also
1750     userdata objects, and each has accessors for all of the keys explained in the
1751     section \quote {Glyph items} below.
1752 \stopitem
1753     The top|-|level key \quote {subfonts} returns an {\it actual} array of userdata
1754     objects, one for each of the subfonts (or nil, if there are no subfonts).
1755 \stopitem
1756 \stopitemize
1757
1758 A short example may be helpful. This code generates a printout of all
1759 the glyph names in the font \type {PunkNova.kern.otf}:
1760
1761 \starttyping
1762 local f = fontloader.open('PunkNova.kern.otf')
1763 print (f.fontname)
1764 local i = 0
1765 if f.glyphcnt > 0 then
1766     for i=f.glyphmin,f.glyphmax do
1767        local g = f.glyphs[i]
1768        if g then
1769           print(g.name)
1770        end
1771        i = i + 1
1772     end
1773 end
1774 fontloader.close(f)
1775 \stoptyping
1776
1777 In this case, the \LUATEX\ memory requirement stays below 100MB on the test
1778 computer, while the internal structure generated by \type {to_table()} needs more
1779 than 2GB of memory (the font itself is 6.9MB in disk size).
1780
1781 Only the top|-|level font, the subfont table entries, and the glyphs are virtual
1782 objects, everything else still produces normal \LUA\ values and tables.
1783
1784 If you want to know the valid fields in a font or glyph structure, call the \type
1785 {fields} function on an object of a particular type (either glyph or font):
1786
1787 \startfunctioncall
1788 <table> fields = fontloader.fields(<userdata> font)
1789 <table> fields = fontloader.fields(<userdata> font_glyph)
1790 \stopfunctioncall
1791
1792 For instance:
1793
1794 \startfunctioncall
1795 local fields = fontloader.fields(f)
1796 local fields = fontloader.fields(f.glyphs[0])
1797 \stopfunctioncall
1798
1799 \subsubsection{Table types}
1800
1801 \subsubsubsection{Top-level}
1802
1803 The top|-|level keys in the returned table are (the explanations in this part of
1804 the documentation are not yet finished):
1805
1806 \starttabulate[|lT|l|p|]
1807 \NC \ssbf key                    \NC \bf type \NC \bf explanation \NC \NR
1808 \NC table_version                \NC number   \NC indicates the metrics version (currently~0.3)\NC \NR
1809 \NC fontname                     \NC string   \NC \POSTSCRIPT\ font name\NC \NR
1810 \NC fullname                     \NC string   \NC official (human-oriented) font name\NC \NR
1811 \NC familyname                   \NC string   \NC family name\NC \NR
1812 \NC weight                       \NC string   \NC weight indicator\NC \NR
1813 \NC copyright                    \NC string   \NC copyright information\NC \NR
1814 \NC filename                     \NC string   \NC the file name\NC \NR
1815 \NC version                      \NC string   \NC font version\NC \NR
1816 \NC italicangle                  \NC float    \NC slant angle\NC \NR
1817 \NC units_per_em                 \NC number   \NC 1000 for \POSTSCRIPT-based fonts, usually 2048 for \TRUETYPE\NC \NR
1818 \NC ascent                       \NC number   \NC height of ascender in \type {units_per_em}\NC \NR
1819 \NC descent                      \NC number   \NC depth of descender in \type {units_per_em}\NC \NR
1820 \NC upos                         \NC float    \NC \NC \NR
1821 \NC uwidth                       \NC float    \NC \NC \NR
1822 \NC uniqueid                     \NC number   \NC \NC \NR
1823 \NC glyphs                       \NC array    \NC \NC \NR
1824 \NC glyphcnt                     \NC number   \NC number of included glyphs\NC \NR
1825 \NC glyphmax                     \NC number   \NC maximum used index the glyphs array\NC \NR
1826 \NC glyphmin                     \NC number   \NC minimum used index the glyphs array\NC \NR
1827 \NC notdef_loc                   \NC number   \NC location of the \type {.notdef} glyph
1828                                                   or \type {-1} when not present \NC \NR
1829 \NC hasvmetrics                  \NC number   \NC \NC \NR
1830 \NC onlybitmaps                  \NC number   \NC \NC \NR
1831 \NC serifcheck                   \NC number   \NC \NC \NR
1832 \NC isserif                      \NC number   \NC \NC \NR
1833 \NC issans                       \NC number   \NC \NC \NR
1834 \NC encodingchanged              \NC number   \NC \NC \NR
1835 \NC strokedfont                  \NC number   \NC \NC \NR
1836 \NC use_typo_metrics             \NC number   \NC \NC \NR
1837 \NC weight_width_slope_only      \NC number   \NC \NC \NR
1838 \NC head_optimized_for_cleartype \NC number   \NC \NC \NR
1839 \NC uni_interp                   \NC enum     \NC \type {unset}, \type {none}, \type {adobe},
1840                                                   \type {greek}, \type {japanese}, \type {trad_chinese},
1841                                                   \type {simp_chinese}, \type {korean}, \type {ams}\NC \NR
1842 \NC origname                     \NC string   \NC the file name, as supplied by the user\NC \NR
1843 \NC map                          \NC table    \NC \NC \NR
1844 \NC private                      \NC table    \NC \NC \NR
1845 \NC xuid                         \NC string   \NC \NC \NR
1846 \NC pfminfo                      \NC table    \NC \NC \NR
1847 \NC names                        \NC table    \NC \NC \NR
1848 \NC cidinfo                      \NC table    \NC \NC \NR
1849 \NC subfonts                     \NC array    \NC \NC \NR
1850 \NC commments                    \NC string   \NC \NC \NR
1851 \NC fontlog                      \NC string   \NC \NC \NR
1852 \NC cvt_names                    \NC string   \NC \NC \NR
1853 \NC anchor_classes               \NC table    \NC \NC \NR
1854 \NC ttf_tables                   \NC table    \NC \NC \NR
1855 \NC ttf_tab_saved                \NC table    \NC \NC \NR
1856 \NC kerns                        \NC table    \NC \NC \NR
1857 \NC vkerns                       \NC table    \NC \NC \NR
1858 \NC texdata                      \NC table    \NC \NC \NR
1859 \NC lookups                      \NC table    \NC \NC \NR
1860 \NC gpos                         \NC table    \NC \NC \NR
1861 \NC gsub                         \NC table    \NC \NC \NR
1862 \NC mm                           \NC table    \NC \NC \NR
1863 \NC chosenname                   \NC string   \NC \NC \NR
1864 \NC macstyle                     \NC number   \NC \NC \NR
1865 \NC fondname                     \NC string   \NC \NC \NR
1866 %NC design_size                  \NC number   \NC \NC \NR
1867 \NC fontstyle_id                 \NC number   \NC \NC \NR
1868 \NC fontstyle_name               \NC table    \NC \NC \NR
1869 %NC design_range_bottom          \NC number   \NC \NC \NR
1870 %NC design_range_top             \NC number   \NC \NC \NR
1871 \NC strokewidth                  \NC float    \NC \NC \NR
1872 \NC mark_classes                 \NC table    \NC \NC \NR
1873 \NC creationtime                 \NC number   \NC \NC \NR
1874 \NC modificationtime             \NC number   \NC \NC \NR
1875 \NC os2_version                  \NC number   \NC \NC \NR
1876 \NC sfd_version                  \NC number   \NC \NC \NR
1877 \NC math                         \NC table    \NC \NC \NR
1878 \NC validation_state             \NC table    \NC \NC \NR
1879 \NC horiz_base                   \NC table    \NC \NC \NR
1880 \NC vert_base                    \NC table    \NC \NC \NR
1881 \NC extrema_bound                \NC number   \NC \NC \NR
1882 \NC truetype                     \NC boolean  \NC signals a \TRUETYPE\ font \NC \NR
1883 \stoptabulate
1884
1885 \subsubsubsection{Glyph items}
1886
1887 The \type {glyphs} is an array containing the per|-|character
1888 information (quite a few of these are only present if nonzero).
1889
1890 \starttabulate[|lT|l|p|]
1891 \NC \ssbf key         \NC \bf type \NC \bf explanation \NC \NR
1892 \NC name              \NC string   \NC the glyph name \NC \NR
1893 \NC unicode           \NC number   \NC unicode code point, or -1 \NC \NR
1894 \NC boundingbox       \NC array    \NC array of four numbers, see note below \NC \NR
1895 \NC width             \NC number   \NC only for horizontal fonts \NC \NR
1896 \NC vwidth            \NC number   \NC only for vertical fonts \NC \NR
1897 \NC tsidebearing      \NC number   \NC only for vertical ttf/otf fonts, and only if nonzero \NC \NR
1898 \NC lsidebearing      \NC number   \NC only if nonzero and not equal to boundingbox[1] \NC \NR
1899 \NC class             \NC string   \NC one of "none", "base", "ligature", "mark", "component"
1900                                        (if not present, the glyph class is \quote {automatic}) \NC \NR
1901 \NC kerns             \NC array    \NC only for horizontal fonts, if set \NC \NR
1902 \NC vkerns            \NC array    \NC only for vertical fonts, if set \NC \NR
1903 \NC dependents        \NC array    \NC linear array of glyph name strings, only if nonempty\NC \NR
1904 \NC lookups           \NC table    \NC only if nonempty \NC \NR
1905 \NC ligatures         \NC table    \NC only if nonempty \NC \NR
1906 \NC anchors           \NC table    \NC only if set \NC \NR
1907 \NC comment           \NC string   \NC only if set \NC \NR
1908 \NC tex_height        \NC number   \NC only if set \NC \NR
1909 \NC tex_depth         \NC number   \NC only if set \NC \NR
1910 \NC italic_correction \NC number   \NC only if set \NC \NR
1911 \NC top_accent        \NC number   \NC only if set \NC \NR
1912 \NC is_extended_shape \NC number   \NC only if this character is part of a math extension list \NC \NR
1913 \NC altuni            \NC table    \NC alternate \UNICODE\ items \NC \NR
1914 \NC vert_variants     \NC table    \NC \NC \NR
1915 \NC horiz_variants    \NC table    \NC \NC \NR
1916 \NC mathkern          \NC table    \NC \NC \NR
1917 \stoptabulate
1918
1919 On \type {boundingbox}: The boundingbox information for \TRUETYPE\ fonts and
1920 \TRUETYPE-based \OTF\ fonts is read directly from the font file.
1921 \POSTSCRIPT-based fonts do not have this information, so the boundingbox of
1922 traditional \POSTSCRIPT\ fonts is generated by interpreting the actual bezier
1923 curves to find the exact boundingbox. This can be a slow process, so the
1924 boundingboxes of \POSTSCRIPT-based \OTF\ fonts (and raw \CFF\ fonts) are
1925 calculated using an approximation of the glyph shape based on the actual glyph
1926 points only, instead of taking the whole curve into account. This means that
1927 glyphs that have missing points at extrema will have a too|-|tight boundingbox,
1928 but the processing is so much faster that in our opinion the tradeoff is worth
1929 it.
1930
1931 The \type {kerns} and \type {vkerns} are linear arrays of small hashes:
1932
1933 \starttabulate[|lT|l|p|]
1934 \NC \ssbf key \NC \bf type \NC \bf explanation \NC \NR
1935 \NC char      \NC string   \NC \NC \NR
1936 \NC off       \NC number   \NC \NC \NR
1937 \NC lookup    \NC string   \NC \NC \NR
1938 \stoptabulate
1939
1940 The \type {lookups} is a hash, based on lookup subtable names, with
1941 the value of each key inside that a linear array of small hashes:
1942
1943 % TODO: fix this description
1944 \starttabulate[|lT|l|p|]
1945 \NC \ssbf key     \NC \bf type \NC \bf explanation \NC \NR
1946 \NC type          \NC enum     \NC \type {position}, \type {pair}, \type
1947                                    {substitution}, \type {alternate}, \type
1948                                    {multiple}, \type {ligature}, \type {lcaret},
1949                                    \type {kerning}, \type {vkerning}, \type
1950                                    {anchors}, \type {contextpos}, \type
1951                                    {contextsub}, \type {chainpos}, \type
1952                                    {chainsub}, \type {reversesub}, \type {max},
1953                                    \type {kernback}, \type {vkernback} \NC \NR
1954 \NC specification \NC table    \NC extra data \NC \NR
1955 \stoptabulate
1956
1957 For the first seven values of \type {type}, there can be additional
1958 sub|-|information, stored in the sub-table \type {specification}:
1959
1960 \starttabulate[|lT|l|p|]
1961 \NC \ssbf value  \NC \bf type \NC \bf explanation \NC \NR
1962 \NC position     \NC table    \NC a table of the \type {offset_specs} type \NC \NR
1963 \NC pair         \NC table    \NC one string: \type {paired}, and an array of one
1964                                   or two \type {offset_specs} tables: \type
1965                                   {offsets} \NC \NR
1966 \NC substitution \NC table    \NC one string: \type {variant} \NC \NR
1967 \NC alternate    \NC table    \NC one string: \type {components} \NC \NR
1968 \NC multiple     \NC table    \NC one string: \type {components} \NC \NR
1969 \NC ligature     \NC table    \NC two strings: \type {components}, \type {char} \NC \NR
1970 \NC lcaret       \NC array    \NC linear array of numbers \NC \NR
1971 \stoptabulate
1972
1973 Tables for \type {offset_specs} contain up to four number|-|valued fields: \type
1974 {x} (a horizontal offset), \type {y} (a vertical offset), \type {h} (an advance
1975 width correction) and \type {v} (an advance height correction).
1976
1977 The \type {ligatures} is a linear array of small hashes:
1978
1979 \starttabulate[|lT|l|p|]
1980 \NC \ssbf key  \NC \bf type \NC \bf explanation \NC \NR
1981 \NC lig        \NC table    \NC uses the same substructure as a single item in
1982                                 the \type {lookups} table explained above \NC \NR
1983 \NC char       \NC string   \NC \NC \NR
1984 \NC components \NC array    \NC linear array of named components \NC \NR
1985 \NC ccnt       \NC number   \NC \NC \NR
1986 \stoptabulate
1987
1988 The \type {anchor} table is indexed by a string signifying the anchor type, which
1989 is one of
1990
1991 \starttabulate[|lT|l|p|]
1992 \NC \ssbf key \NC \bf type \NC \bf explanation \NC \NR
1993 \NC mark      \NC table    \NC placement mark \NC \NR
1994 \NC basechar  \NC table    \NC mark for attaching combining items to a base char \NC \NR
1995 \NC baselig   \NC table    \NC mark for attaching combining items to a ligature \NC \NR
1996 \NC basemark  \NC table    \NC generic mark for attaching combining items to connect to \NC \NR
1997 \NC centry    \NC table    \NC cursive entry point \NC \NR
1998 \NC cexit     \NC table    \NC cursive exit point \NC \NR
1999 \stoptabulate
2000
2001 The content of these is a short array of defined anchors, with the
2002 entry keys being the anchor names. For all except \type {baselig}, the
2003 value is a single table with this definition:
2004
2005 \starttabulate[|lT|l|p|]
2006 \NC \ssbf key    \NC \bf type \NC \bf explanation \NC \NR
2007 \NC x            \NC number   \NC x location \NC \NR
2008 \NC y            \NC number   \NC y location \NC \NR
2009 \NC ttf_pt_index \NC number   \NC truetype point index, only if given \NC \NR
2010 \stoptabulate
2011
2012 For \type {baselig}, the value is a small array of such anchor sets sets, one for
2013 each constituent item of the ligature.
2014
2015 For clarification, an anchor table could for example look like this :
2016
2017 \starttyping
2018 ['anchor'] = {
2019     ['basemark'] = {
2020         ['Anchor-7'] = { ['x']=170, ['y']=1080 }
2021     },
2022     ['mark'] ={
2023         ['Anchor-1'] = { ['x']=160, ['y']=810 },
2024         ['Anchor-4'] = { ['x']=160, ['y']=800 }
2025     },
2026     ['baselig'] = {
2027         [1] = { ['Anchor-2'] = { ['x']=160, ['y']=650 } },
2028         [2] = { ['Anchor-2'] = { ['x']=460, ['y']=640 } }
2029         }
2030     }
2031 \stoptyping
2032
2033 Note: The \type {baselig} table can be sparse!
2034
2035 \subsubsubsection{map table}
2036
2037 The top|-|level map is a list of encoding mappings. Each of those is a table
2038 itself.
2039
2040 \starttabulate[|lT|l|p|]
2041 \NC \ssbf key \NC \bf type \NC \bf explanation \NC \NR
2042 \NC enccount  \NC number   \NC \NC \NR
2043 \NC encmax    \NC number   \NC \NC \NR
2044 \NC backmax   \NC number   \NC \NC \NR
2045 \NC remap     \NC table    \NC \NC \NR
2046 \NC map       \NC array    \NC non|-|linear array of mappings\NC \NR
2047 \NC backmap   \NC array    \NC non|-|linear array of backward mappings\NC \NR
2048 \NC enc       \NC table    \NC \NC \NR
2049 \stoptabulate
2050
2051 The \type {remap} table is very small:
2052
2053 \starttabulate[|lT|l|p|]
2054 \NC \ssbf key \NC \bf type \NC \bf explanation \NC \NR
2055 \NC firstenc  \NC number   \NC \NC \NR
2056 \NC lastenc   \NC number   \NC \NC \NR
2057 \NC infont    \NC number   \NC \NC \NR
2058 \stoptabulate
2059
2060 The \type {enc} table is a bit more verbose:
2061
2062 \starttabulate[|lT|l|p|]
2063 \NC \ssbf key        \NC \bf type \NC \bf explanation \NC \NR
2064 \NC enc_name         \NC string   \NC \NC \NR
2065 \NC char_cnt         \NC number   \NC \NC \NR
2066 \NC char_max         \NC number   \NC \NC \NR
2067 \NC unicode          \NC array    \NC of \UNICODE\ position numbers\NC \NR
2068 \NC psnames          \NC array    \NC of \POSTSCRIPT\ glyph names\NC \NR
2069 \NC builtin          \NC number   \NC \NC \NR
2070 \NC hidden           \NC number   \NC \NC \NR
2071 \NC only_1byte       \NC number   \NC \NC \NR
2072 \NC has_1byte        \NC number   \NC \NC \NR
2073 \NC has_2byte        \NC number   \NC \NC \NR
2074 \NC is_unicodebmp    \NC number   \NC only if nonzero\NC \NR
2075 \NC is_unicodefull   \NC number   \NC only if nonzero\NC \NR
2076 \NC is_custom        \NC number   \NC only if nonzero\NC \NR
2077 \NC is_original      \NC number   \NC only if nonzero\NC \NR
2078 \NC is_compact       \NC number   \NC only if nonzero\NC \NR
2079 \NC is_japanese      \NC number   \NC only if nonzero\NC \NR
2080 \NC is_korean        \NC number   \NC only if nonzero\NC \NR
2081 \NC is_tradchinese   \NC number   \NC only if nonzero [name?]\NC \NR
2082 \NC is_simplechinese \NC number   \NC only if nonzero\NC \NR
2083 \NC low_page         \NC number   \NC \NC \NR
2084 \NC high_page        \NC number   \NC \NC \NR
2085 \NC iconv_name       \NC string   \NC \NC \NR
2086 \NC iso_2022_escape  \NC string   \NC \NC \NR
2087 \stoptabulate
2088
2089 \subsubsubsection{private table}
2090
2091 This is the font's private \POSTSCRIPT\ dictionary, if any. Keys and values are
2092 both strings.
2093
2094 \subsubsubsection{cidinfo table}
2095
2096 \starttabulate[|lT|l|p|]
2097 \NC \ssbf key  \NC \bf type \NC \bf explanation \NC \NR
2098 \NC registry   \NC string   \NC \NC \NR
2099 \NC ordering   \NC string   \NC \NC \NR
2100 \NC supplement \NC number   \NC \NC \NR
2101 \NC version    \NC number   \NC \NC \NR
2102 \stoptabulate
2103
2104 \subsubsubsection[fontloaderpfminfotable]{pfminfo table}
2105
2106 The \type {pfminfo} table contains most of the OS/2 information:
2107
2108 \starttabulate[|lT|l|p|]
2109 \NC \ssbf key        \NC \bf type \NC \bf explanation \NC \NR
2110 \NC pfmset           \NC number   \NC \NC \NR
2111 \NC winascent_add    \NC number   \NC \NC \NR
2112 \NC windescent_add   \NC number   \NC \NC \NR
2113 \NC hheadascent_add  \NC number   \NC \NC \NR
2114 \NC hheaddescent_add \NC number   \NC \NC \NR
2115 \NC typoascent_add   \NC number   \NC \NC \NR
2116 \NC typodescent_add  \NC number   \NC \NC \NR
2117 \NC subsuper_set     \NC number   \NC \NC \NR
2118 \NC panose_set       \NC number   \NC \NC \NR
2119 \NC hheadset         \NC number   \NC \NC \NR
2120 \NC vheadset         \NC number   \NC \NC \NR
2121 \NC pfmfamily        \NC number   \NC \NC \NR
2122 \NC weight           \NC number   \NC \NC \NR
2123 \NC width            \NC number   \NC \NC \NR
2124 \NC avgwidth         \NC number   \NC \NC \NR
2125 \NC firstchar        \NC number   \NC \NC \NR
2126 \NC lastchar         \NC number   \NC \NC \NR
2127 \NC fstype           \NC number   \NC \NC \NR
2128 \NC linegap          \NC number   \NC \NC \NR
2129 \NC vlinegap         \NC number   \NC \NC \NR
2130 \NC hhead_ascent     \NC number   \NC \NC \NR
2131 \NC hhead_descent    \NC number   \NC \NC \NR
2132 \NC os2_typoascent   \NC number   \NC \NC \NR
2133 \NC os2_typodescent  \NC number   \NC \NC \NR
2134 \NC os2_typolinegap  \NC number   \NC \NC \NR
2135 \NC os2_winascent    \NC number   \NC \NC \NR
2136 \NC os2_windescent   \NC number   \NC \NC \NR
2137 \NC os2_subxsize     \NC number   \NC \NC \NR
2138 \NC os2_subysize     \NC number   \NC \NC \NR
2139 \NC os2_subxoff      \NC number   \NC \NC \NR
2140 \NC os2_subyoff      \NC number   \NC \NC \NR
2141 \NC os2_supxsize     \NC number   \NC \NC \NR
2142 \NC os2_supysize     \NC number   \NC \NC \NR
2143 \NC os2_supxoff      \NC number   \NC \NC \NR
2144 \NC os2_supyoff      \NC number   \NC \NC \NR
2145 \NC os2_strikeysize  \NC number   \NC \NC \NR
2146 \NC os2_strikeypos   \NC number   \NC \NC \NR
2147 \NC os2_family_class \NC number   \NC \NC \NR
2148 \NC os2_xheight      \NC number   \NC \NC \NR
2149 \NC os2_capheight    \NC number   \NC \NC \NR
2150 \NC os2_defaultchar  \NC number   \NC \NC \NR
2151 \NC os2_breakchar    \NC number   \NC \NC \NR
2152 \NC os2_vendor       \NC string   \NC \NC \NR
2153 \NC codepages        \NC table    \NC A two-number array of encoded code pages\NC \NR
2154 \NC unicoderages     \NC table    \NC A four-number array of encoded unicode ranges\NC \NR
2155 \NC panose           \NC table    \NC \NC \NR
2156 \stoptabulate
2157
2158 The \type {panose} subtable has exactly 10 string keys:
2159
2160 \starttabulate[|lT|l|p|]
2161 \NC \ssbf key       \NC \bf type \NC \bf explanation \NC \NR
2162 \NC familytype      \NC string   \NC Values as in the \OPENTYPE\ font
2163                                      specification: \type {Any}, \type {No Fit},
2164                                      \type {Text and Display}, \type {Script},
2165                                      \type {Decorative}, \type {Pictorial} \NC
2166                                      \NR
2167 \NC serifstyle      \NC string   \NC See the \OPENTYPE\ font specification for
2168                                      values \NC \NR
2169 \NC weight          \NC string   \NC id. \NC \NR
2170 \NC proportion      \NC string   \NC id. \NC \NR
2171 \NC contrast        \NC string   \NC id. \NC \NR
2172 \NC strokevariation \NC string   \NC id. \NC \NR
2173 \NC armstyle        \NC string   \NC id. \NC \NR
2174 \NC letterform      \NC string   \NC id. \NC \NR
2175 \NC midline         \NC string   \NC id. \NC \NR
2176 \NC xheight         \NC string   \NC id. \NC \NR
2177 \stoptabulate
2178
2179 \subsubsubsection[fontloadernamestable]{names table}
2180
2181 Each item has two top|-|level keys:
2182
2183 \starttabulate[|lT|l|p|]
2184 \NC \ssbf key \NC \bf type \NC \bf explanation \NC \NR
2185 \NC lang      \NC string   \NC language for this entry \NC \NR
2186 \NC names     \NC table    \NC \NC \NR
2187 \stoptabulate
2188
2189 The \type {names} keys are the actual \TRUETYPE\ name strings. The possible keys
2190 are:
2191
2192 \starttabulate[|lT|p|]
2193 \NC \ssbf key       \NC \bf explanation \NC \NR
2194 \NC copyright       \NC \NC \NR
2195 \NC family          \NC \NC \NR
2196 \NC subfamily       \NC \NC \NR
2197 \NC uniqueid        \NC \NC \NR
2198 \NC fullname        \NC \NC \NR
2199 \NC version         \NC \NC \NR
2200 \NC postscriptname  \NC \NC \NR
2201 \NC trademark       \NC \NC \NR
2202 \NC manufacturer    \NC \NC \NR
2203 \NC designer        \NC \NC \NR
2204 \NC descriptor      \NC \NC \NR
2205 \NC venderurl       \NC \NC \NR
2206 \NC designerurl     \NC \NC \NR
2207 \NC license         \NC \NC \NR
2208 \NC licenseurl      \NC \NC \NR
2209 \NC idontknow       \NC \NC \NR
2210 \NC preffamilyname  \NC \NC \NR
2211 \NC prefmodifiers   \NC \NC \NR
2212 \NC compatfull      \NC \NC \NR
2213 \NC sampletext      \NC \NC \NR
2214 \NC cidfindfontname \NC \NC \NR
2215 \NC wwsfamily       \NC \NC \NR
2216 \NC wwssubfamily    \NC \NC \NR
2217 \stoptabulate
2218
2219 \subsubsubsection{anchor_classes table}
2220
2221 The anchor_classes classes:
2222
2223 \starttabulate[|lT|l|p|]
2224 \NC \ssbf key \NC \bf type \NC \bf explanation \NC \NR
2225 \NC name      \NC string   \NC a descriptive id of this anchor class\NC \NR
2226 \NC lookup    \NC string   \NC \NC \NR
2227 \NC type      \NC string   \NC one of \type {mark}, \type {mkmk}, \type {curs}, \type {mklg} \NC \NR
2228 \stoptabulate
2229
2230 % type is actually a lookup subtype, not a feature name. Officially, these
2231 % strings should be gpos_mark2mark etc.
2232
2233 \subsubsubsection{gpos table}
2234
2235 The \type {gpos} table has one array entry for each lookup. (The \type {gpos_}
2236 prefix is somewhat redundant.)
2237
2238 \starttabulate[|lT|l|p|]
2239 \NC \ssbf key \NC \bf type \NC \bf explanation \NC \NR
2240 \NC type      \NC string   \NC one of \type {gpos_single}, \type {gpos_pair},
2241                                \type {gpos_cursive}, \type {gpos_mark2base},\crlf
2242                                \type {gpos_mark2ligature}, \type
2243                                {gpos_mark2mark}, \type {gpos_context},\crlf \type
2244                                {gpos_contextchain} \NC \NR
2245 \NC flags     \NC table    \NC \NC \NR
2246 \NC name      \NC string   \NC \NC \NR
2247 \NC features  \NC array    \NC \NC \NR
2248 \NC subtables \NC array    \NC \NC \NR
2249 \stoptabulate
2250
2251 The flags table has a true value for each of the lookup flags that is actually
2252 set:
2253
2254 \starttabulate[|lT|l|p|]
2255 \NC \ssbf key            \NC \bf type \NC \bf explanation \NC \NR
2256 \NC r2l                  \NC boolean  \NC \NC \NR
2257 \NC ignorebaseglyphs     \NC boolean  \NC \NC \NR
2258 \NC ignoreligatures      \NC boolean  \NC \NC \NR
2259 \NC ignorecombiningmarks \NC boolean  \NC \NC \NR
2260 \NC mark_class           \NC string   \NC \NC \NR
2261 \stoptabulate
2262
2263 The features subtable items of gpos have:
2264
2265 \starttabulate[|lT|l|p|]
2266 \NC \ssbf key \NC \bf type \NC \bf explanation \NC \NR
2267 \NC tag       \NC string   \NC \NC \NR
2268 \NC scripts   \NC table    \NC \NC \NR
2269 \stoptabulate
2270
2271 The scripts table within features has:
2272
2273 \starttabulate[|lT|l|p|]
2274 \NC \ssbf key \NC \bf type         \NC \bf explanation \NC \NR
2275 \NC script    \NC string           \NC \NC \NR
2276 \NC langs     \NC array of strings \NC \NC \NR
2277 \stoptabulate
2278
2279 The subtables table has:
2280
2281 \starttabulate[|lT|l|p|]
2282 \NC \ssbf key        \NC \bf type \NC \bf explanation \NC \NR
2283 \NC name             \NC string   \NC \NC \NR
2284 \NC suffix           \NC string   \NC (only if used)\NC \NR % used by gpos_single to get a default
2285 \NC anchor_classes   \NC number   \NC (only if used)\NC \NR
2286 \NC vertical_kerning \NC number   \NC (only if used)\NC \NR
2287 \NC kernclass        \NC table    \NC (only if used)\NC \NR
2288 \stoptabulate
2289
2290 The kernclass with subtables table has:
2291
2292 \starttabulate[|lT|l|p|]
2293 \NC \ssbf key \NC \bf type \NC \bf explanation \NC \NR
2294 \NC firsts    \NC array of strings  \NC \NC \NR
2295 \NC seconds   \NC array of strings   \NC \NC \NR
2296 \NC lookup    \NC string or array \NC associated lookup(s) \NC \NR
2297 \NC offsets   \NC array of numbers  \NC \NC \NR
2298 \stoptabulate
2299
2300 Note: the kernclass (as far as we can see) always has one entry so it could be one level
2301 deep instead. Also the seconds start at \type {[2]} which is close to the fontforge
2302 internals so we keep that too.
2303
2304 \subsubsubsection{gsub table}
2305
2306 This has identical layout to the \type {gpos} table, except for the
2307 type:
2308
2309 \starttabulate[|lT|l|p|]
2310 \NC \ssbf key \NC \bf type \NC \bf explanation \NC \NR
2311 \NC type      \NC string   \NC one of \type {gsub_single}, \type {gsub_multiple},
2312                                \type {gsub_alternate}, \type
2313                                {gsub_ligature},\crlf \type {gsub_context}, \type
2314                                {gsub_contextchain}, \type
2315                                {gsub_reversecontextchain} \NC \NR
2316 \stoptabulate
2317
2318 \subsubsubsection{ttf_tables and ttf_tab_saved tables}
2319
2320 \starttabulate[|lT|l|p|]
2321 \NC \ssbf key \NC \bf type \NC \bf explanation \NC \NR
2322 \NC tag       \NC string   \NC \NC \NR
2323 \NC len       \NC number   \NC \NC \NR
2324 \NC maxlen    \NC number   \NC \NC \NR
2325 \NC data      \NC number   \NC \NC \NR
2326 \stoptabulate
2327
2328 \subsubsubsection{mm table}
2329
2330 \starttabulate[|lT|l|p|]
2331 \NC \ssbf key      \NC \bf type \NC \bf explanation \NC \NR
2332 \NC axes           \NC table    \NC array of axis names \NC \NR
2333 \NC instance_count \NC number   \NC \NC \NR
2334 \NC positions      \NC table    \NC array of instance positions
2335                                     (\#axes * instances )\NC \NR
2336 \NC defweights     \NC table    \NC array of default weights for instances \NC \NR
2337 \NC cdv            \NC string   \NC \NC \NR
2338 \NC ndv            \NC string   \NC \NC \NR
2339 \NC axismaps       \NC table    \NC \NC \NR
2340 \stoptabulate
2341
2342 The \type {axismaps}:
2343
2344 \starttabulate[|lT|l|p|]
2345 \NC \ssbf key            \NC \bf type \NC \bf explanation \NC \NR
2346 \NC blends               \NC table     \NC an array of blend points \NC \NR
2347 \NC designs              \NC table     \NC an array of design values \NC \NR
2348 \NC min                  \NC number   \NC \NC \NR
2349 \NC def                  \NC number   \NC \NC \NR
2350 \NC max                  \NC number   \NC \NC \NR
2351 \stoptabulate
2352
2353 \subsubsubsection{mark_classes table}
2354
2355 The keys in this table are mark class names, and the values are a
2356 space|-|separated string of glyph names in this class.
2357
2358 \subsubsubsection{math table}
2359
2360 \starttabulate[|lT|p|]
2361 \NC ScriptPercentScaleDown                   \NC \NC \NR
2362 \NC ScriptScriptPercentScaleDown             \NC \NC \NR
2363 \NC DelimitedSubFormulaMinHeight             \NC \NC \NR
2364 \NC DisplayOperatorMinHeight                 \NC \NC \NR
2365 \NC MathLeading                              \NC \NC \NR
2366 \NC AxisHeight                               \NC \NC \NR
2367 \NC AccentBaseHeight                         \NC \NC \NR
2368 \NC FlattenedAccentBaseHeight                \NC \NC \NR
2369 \NC SubscriptShiftDown                       \NC \NC \NR
2370 \NC SubscriptTopMax                          \NC \NC \NR
2371 \NC SubscriptBaselineDropMin                 \NC \NC \NR
2372 \NC SuperscriptShiftUp                       \NC \NC \NR
2373 \NC SuperscriptShiftUpCramped                \NC \NC \NR
2374 \NC SuperscriptBottomMin                     \NC \NC \NR
2375 \NC SuperscriptBaselineDropMax               \NC \NC \NR
2376 \NC SubSuperscriptGapMin                     \NC \NC \NR
2377 \NC SuperscriptBottomMaxWithSubscript        \NC \NC \NR
2378 \NC SpaceAfterScript                         \NC \NC \NR
2379 \NC UpperLimitGapMin                         \NC \NC \NR
2380 \NC UpperLimitBaselineRiseMin                \NC \NC \NR
2381 \NC LowerLimitGapMin                         \NC \NC \NR
2382 \NC LowerLimitBaselineDropMin                \NC \NC \NR
2383 \NC StackTopShiftUp                          \NC \NC \NR
2384 \NC StackTopDisplayStyleShiftUp              \NC \NC \NR
2385 \NC StackBottomShiftDown                     \NC \NC \NR
2386 \NC StackBottomDisplayStyleShiftDown         \NC \NC \NR
2387 \NC StackGapMin                              \NC \NC \NR
2388 \NC StackDisplayStyleGapMin                  \NC \NC \NR
2389 \NC StretchStackTopShiftUp                   \NC \NC \NR
2390 \NC StretchStackBottomShiftDown              \NC \NC \NR
2391 \NC StretchStackGapAboveMin                  \NC \NC \NR
2392 \NC StretchStackGapBelowMin                  \NC \NC \NR
2393 \NC FractionNumeratorShiftUp                 \NC \NC \NR
2394 \NC FractionNumeratorDisplayStyleShiftUp     \NC \NC \NR
2395 \NC FractionDenominatorShiftDown             \NC \NC \NR
2396 \NC FractionDenominatorDisplayStyleShiftDown \NC \NC \NR
2397 \NC FractionNumeratorGapMin                  \NC \NC \NR
2398 \NC FractionNumeratorDisplayStyleGapMin      \NC \NC \NR
2399 \NC FractionRuleThickness                    \NC \NC \NR
2400 \NC FractionDenominatorGapMin                \NC \NC \NR
2401 \NC FractionDenominatorDisplayStyleGapMin    \NC \NC \NR
2402 \NC SkewedFractionHorizontalGap              \NC \NC \NR
2403 \NC SkewedFractionVerticalGap                \NC \NC \NR
2404 \NC OverbarVerticalGap                       \NC \NC \NR
2405 \NC OverbarRuleThickness                     \NC \NC \NR
2406 \NC OverbarExtraAscender                     \NC \NC \NR
2407 \NC UnderbarVerticalGap                      \NC \NC \NR
2408 \NC UnderbarRuleThickness                    \NC \NC \NR
2409 \NC UnderbarExtraDescender                   \NC \NC \NR
2410 \NC RadicalVerticalGap                       \NC \NC \NR
2411 \NC RadicalDisplayStyleVerticalGap           \NC \NC \NR
2412 \NC RadicalRuleThickness                     \NC \NC \NR
2413 \NC RadicalExtraAscender                     \NC \NC \NR
2414 \NC RadicalKernBeforeDegree                  \NC \NC \NR
2415 \NC RadicalKernAfterDegree                   \NC \NC \NR
2416 \NC RadicalDegreeBottomRaisePercent          \NC \NC \NR
2417 \NC MinConnectorOverlap                      \NC \NC \NR
2418 \NC FractionDelimiterSize                    \NC \NC \NR
2419 \NC FractionDelimiterDisplayStyleSize        \NC \NC \NR
2420 \stoptabulate
2421
2422 \subsubsubsection{validation_state table}
2423
2424 \starttabulate[|lT|p|]
2425 \NC \ssbf key         \NC \bf explanation \NC \NR
2426 \NC bad_ps_fontname   \NC \NC \NR
2427 \NC bad_glyph_table   \NC \NC \NR
2428 \NC bad_cff_table     \NC \NC \NR
2429 \NC bad_metrics_table \NC \NC \NR
2430 \NC bad_cmap_table    \NC \NC \NR
2431 \NC bad_bitmaps_table \NC \NC \NR
2432 \NC bad_gx_table      \NC \NC \NR
2433 \NC bad_ot_table      \NC \NC \NR
2434 \NC bad_os2_version   \NC \NC \NR
2435 \NC bad_sfnt_header   \NC \NC \NR
2436 \stoptabulate
2437
2438 \subsubsubsection{horiz_base and vert_base table}
2439
2440 \starttabulate[|lT|l|p|]
2441 \NC \ssbf key \NC \bf type \NC \bf explanation \NC \NR
2442 \NC tags      \NC table    \NC an array of script list tags\NC \NR
2443 \NC scripts   \NC table    \NC \NC \NR
2444 \stoptabulate
2445
2446 The \type {scripts} subtable:
2447
2448 \starttabulate[|lT|l|p|]
2449 \NC \ssbf key        \NC \bf type \NC \bf explanation \NC \NR
2450 \NC baseline         \NC table   \NC \NC \NR
2451 \NC default_baseline \NC number  \NC \NC \NR
2452 \NC lang             \NC table   \NC \NC \NR
2453 \stoptabulate
2454
2455
2456 The \type {lang} subtable:
2457
2458 \starttabulate[|lT|l|p|]
2459 \NC \ssbf key \NC \bf type \NC \bf explanation \NC \NR
2460 \NC tag       \NC string   \NC a script tag \NC \NR
2461 \NC ascent    \NC number   \NC \NC \NR
2462 \NC descent   \NC number   \NC \NC \NR
2463 \NC features  \NC table    \NC \NC \NR
2464 \stoptabulate
2465
2466 The \type {features} points to an array of tables with the same layout except
2467 that in those nested tables, the tag represents a language.
2468
2469 \subsubsubsection{altuni table}
2470
2471 An array of alternate \UNICODE\ values. Inside that array are hashes with:
2472
2473 \starttabulate[|lT|l|p|]
2474 \NC \ssbf key \NC \bf type \NC \bf explanation \NC \NR
2475 \NC unicode   \NC number   \NC this glyph is also used for this unicode \NC \NR
2476 \NC variant   \NC number   \NC the alternative is driven by this unicode selector \NC \NR
2477 \stoptabulate
2478
2479 \subsubsubsection{vert_variants and horiz_variants table}
2480
2481 \starttabulate[|lT|l|p|]
2482 \NC \ssbf key         \NC \bf type \NC \bf explanation \NC \NR
2483 \NC variants          \NC string   \NC \NC \NR
2484 \NC italic_correction \NC number   \NC \NC \NR
2485 \NC parts             \NC table    \NC \NC \NR
2486 \stoptabulate
2487
2488 The \type {parts} table is an array of smaller tables:
2489
2490 \starttabulate[|lT|l|p|]
2491 \NC \ssbf key \NC \bf type \NC \bf explanation \NC \NR
2492 \NC component \NC string   \NC \NC \NR
2493 \NC extender  \NC number   \NC \NC \NR
2494 \NC start     \NC number   \NC \NC \NR
2495 \NC end       \NC number   \NC \NC \NR
2496 \NC advance   \NC number   \NC \NC \NR
2497 \stoptabulate
2498
2499
2500 \subsubsubsection{mathkern table}
2501
2502 \starttabulate[|lT|l|p|]
2503 \NC \ssbf key    \NC \bf type \NC \bf explanation \NC \NR
2504 \NC top_right    \NC table    \NC \NC \NR
2505 \NC bottom_right \NC table    \NC \NC \NR
2506 \NC top_left     \NC table    \NC \NC \NR
2507 \NC bottom_left  \NC table    \NC \NC \NR
2508 \stoptabulate
2509
2510 Each of the subtables is an array of small hashes with two keys:
2511
2512 \starttabulate[|lT|l|p|]
2513 \NC \ssbf key \NC \bf type \NC \bf explanation \NC \NR
2514 \NC height    \NC number   \NC \NC \NR
2515 \NC kern      \NC number   \NC \NC \NR
2516 \stoptabulate
2517
2518 \subsubsubsection{kerns table}
2519
2520 Substructure is identical to the per|-|glyph subtable.
2521
2522 \subsubsubsection{vkerns table}
2523
2524 Substructure is identical to the per|-|glyph subtable.
2525
2526 \subsubsubsection{texdata table}
2527
2528 \starttabulate[|lT|l|p|]
2529 \NC \ssbf key \NC \bf type \NC \bf explanation \NC \NR
2530 \NC type      \NC string   \NC \type {unset}, \type {text}, \type {math}, \type {mathext} \NC \NR
2531 \NC params    \NC array    \NC 22 font numeric parameters \NC \NR
2532 \stoptabulate
2533
2534 \subsubsubsection{lookups table}
2535
2536 Top|-|level \type {lookups} is quite different from the ones at character level.
2537 The keys in this hash are strings, the values the actual lookups, represented as
2538 dictionary tables.
2539
2540 \starttabulate[|lT|l|p|]
2541 \NC \ssbf key     \NC \bf type \NC \bf explanation \NC \NR
2542 \NC type          \NC string   \NC \NC \NR
2543 \NC format        \NC enum     \NC one of \type {glyphs}, \type {class}, \type {coverage}, \type {reversecoverage} \NC \NR
2544 \NC tag           \NC string   \NC \NC \NR
2545 \NC current_class \NC array    \NC \NC \NR
2546 \NC before_class  \NC array    \NC \NC \NR
2547 \NC after_class   \NC array    \NC \NC \NR
2548 \NC rules         \NC array    \NC an array of rule items\NC \NR
2549 \stoptabulate
2550
2551 Rule items have one common item and one specialized item:
2552
2553 \starttabulate[|lT|l|p|]
2554 \NC \ssbf key       \NC \bf type \NC \bf explanation \NC \NR
2555 \NC lookups         \NC array    \NC a linear array of lookup names\NC \NR
2556 \NC glyphs          \NC array    \NC only if the parent's format is \type {glyphs}\NC \NR
2557 \NC class           \NC array    \NC only if the parent's format is \type {class}\NC \NR
2558 \NC coverage        \NC array    \NC only if the parent's format is \type {coverage}\NC \NR
2559 \NC reversecoverage \NC array    \NC only if the parent's format is \type {reversecoverage}\NC \NR
2560 \stoptabulate
2561
2562 A glyph table is:
2563
2564 \starttabulate[|lT|l|p|]
2565 \NC \ssbf key \NC \bf type \NC \bf explanation \NC \NR
2566 \NC names     \NC string   \NC \NC \NR
2567 \NC back      \NC string   \NC \NC \NR
2568 \NC fore      \NC string   \NC \NC \NR
2569 \stoptabulate
2570
2571 A class table is:
2572
2573 \starttabulate[|lT|l|p|]
2574 \NC \ssbf key \NC \bf type \NC \bf explanation \NC \NR
2575 \NC current   \NC array    \NC of numbers \NC \NR
2576 \NC before    \NC array    \NC of numbers  \NC \NR
2577 \NC after     \NC array    \NC of numbers  \NC \NR
2578 \stoptabulate
2579
2580 coverage:
2581
2582 \starttabulate[|lT|l|p|]
2583 \NC \ssbf key \NC \bf type \NC \bf explanation \NC \NR
2584 \NC current   \NC array    \NC of strings \NC \NR
2585 \NC before    \NC array    \NC of strings\NC \NR
2586 \NC after     \NC array    \NC of strings \NC \NR
2587 \stoptabulate
2588
2589 reversecoverage:
2590
2591 \starttabulate[|lT|l|p|]
2592 \NC \ssbf key    \NC \bf type \NC \bf explanation \NC \NR
2593 \NC current      \NC array    \NC of strings \NC \NR
2594 \NC before       \NC array    \NC of strings\NC \NR
2595 \NC after        \NC array    \NC of strings \NC \NR
2596 \NC replacements \NC string   \NC \NC \NR
2597 \stoptabulate
2598
2599 \section{The \type {img} library}
2600
2601 The \type {img} library can be used as an alternative to \type {\pdfximage} and
2602 \type {\pdfrefximage}, and the associated \quote {satellite} commands like \type
2603 {\pdfximagebbox}. Image objects can also be used within virtual fonts via the
2604 \type {image} command listed in~\in {section} [virtualfonts].
2605
2606 \subsection{\type {img.new}}
2607
2608 \startfunctioncall
2609 <image> var = img.new()
2610 <image> var = img.new(<table> image_spec)
2611 \stopfunctioncall
2612
2613 This function creates a userdata object of type \quote {image}. The \type
2614 {image_spec} argument is optional. If it is given, it must be a table, and that
2615 table must contain a \type {filename} key. A number of other keys can also be
2616 useful, these are explained below.
2617
2618 You can either say
2619
2620 \starttyping
2621 a = img.new()
2622 \stoptyping
2623
2624 followed by
2625
2626 \starttyping
2627 a.filename = "foo.png"
2628 \stoptyping
2629
2630 or you can put the file name (and some or all of the other keys) into a table
2631 directly, like so:
2632
2633 \starttyping
2634 a = img.new({filename='foo.pdf', page=1})
2635 \stoptyping
2636
2637 The generated \type {<image>} userdata object allows access to a set of
2638 user|-|specified values as well as a set of values that are normally filled in
2639 and updated automatically by \LUATEX\ itself. Some of those are derived from the
2640 actual image file, others are updated to reflect the \PDF\ output status of the
2641 object.
2642
2643 There is one required user-specified field: the file name (\type {filename}). It
2644 can optionally be augmented by the requested image dimensions (\type {width},
2645 \type {depth}, \type {height}), user|-|specified image attributes (\type {attr}),
2646 the requested \PDF\ page identifier (\type {page}), the requested boundingbox
2647 (\type {pagebox}) for \PDF\ inclusion, the requested color space object (\type
2648 {colorspace}).
2649
2650 The function \type {img.new} does not access the actual image file, it just
2651 creates the \type {<image>} userdata object and initializes some memory
2652 structures. The \type {<image>} object and its internal structures are
2653 automatically garbage collected.
2654
2655 Once the image is scanned, all the values in the \type {<image>} except \type
2656 {width}, \type {height} and \type {depth}, become frozen, and you cannot change
2657 them any more.
2658
2659 You can use \type {pdf.setignoreunknownimages(1)} (or at the \TEX\ end the \type
2660 {\pdfvariable} \type {ignoreunknownimages}) to get around a quit when no known
2661 image type is found (based on name or preamble). Beware: this will not catch
2662 invalid images and we cannot guarantee side effects. A zero dimension image is
2663 still included when requested. No special flags are set. A proper workflow will
2664 not rely in such a catch but make sure that images are valid.
2665
2666 \subsection{\type {img.keys}}
2667
2668 \startfunctioncall
2669 <table> keys = img.keys()
2670 \stopfunctioncall
2671
2672 This function returns a list of all the possible \type {image_spec} keys, both
2673 user-supplied and automatic ones.
2674
2675 % hahe: i need to add r/w ro column...
2676 \starttabulate[|l|l|p|]
2677 \NC \bf field name \NC \bf type \NC description \NC \NR
2678 \NC attr           \NC string   \NC the image attributes for \LUATEX \NC \NR
2679 \NC bbox           \NC table    \NC table with 4 boundingbox dimensions
2680                                     \type {llx}, \type {lly}, \type {urx},
2681                                     and \type {ury} overruling the \type {pagebox}
2682                                     entry\NC \NR
2683 \NC colordepth     \NC number   \NC the number of bits used by the color space\NC \NR
2684 \NC colorspace     \NC number   \NC the color space object number \NC \NR
2685 \NC depth          \NC number   \NC the image depth for \LUATEX\
2686                                     (in scaled points)\NC \NR
2687 \NC filename       \NC string   \NC the image file name \NC \NR
2688 \NC filepath       \NC string   \NC the full (expanded) file name of the image\NC \NR
2689 \NC height         \NC number   \NC the image height for \LUATEX\
2690                                     (in scaled points)\NC \NR
2691 \NC imagetype      \NC string   \NC one of \type {pdf}, \type {png}, \type {jpg}, \type {jp2},
2692                                     \type {jbig2}, or \type {nil} \NC \NR
2693 \NC index          \NC number   \NC the \PDF\ image name suffix \NC \NR
2694 \NC objnum         \NC number   \NC the \PDF\ image object number \NC \NR
2695 \NC page           \NC ??       \NC the identifier for the requested image page
2696                                     (type is number or string,
2697                                     default is the number 1)\NC \NR
2698 \NC pagebox        \NC string   \NC the requested bounding box, one of
2699                                     \type {none}, \type {media}, \type {crop},
2700                                     \type {bleed}, \type {trim}, \type {art} \NC \NR
2701 \NC pages          \NC number   \NC the total number of available pages \NC \NR
2702 \NC rotation       \NC number   \NC the image rotation from included \PDF\ file,
2703                                     in multiples of 90~deg. \NC \NR
2704 \NC stream         \NC string   \NC the raw stream data for an \type {/Xobject}
2705                                     \type {/Form} object\NC \NR
2706 \NC transform      \NC number   \NC the image transform, integer number 0..7\NC \NR
2707 \NC width          \NC number   \NC the image width for \LUATEX\
2708                                     (in scaled points)\NC \NR
2709 \NC xres           \NC number   \NC the horizontal natural image resolution
2710                                     (in \DPI) \NC \NR
2711 \NC xsize          \NC number   \NC the natural image width \NC \NR
2712 \NC yres           \NC number   \NC the vertical natural image resolution
2713                                     (in \DPI) \NC \NR
2714 \NC ysize          \NC number   \NC the natural image height \NC \NR
2715 \NC visiblefileame \NC string   \NC when set, this name will find its way in the
2716                                     \PDF\ file as \type {PTEX} specification; when
2717                                     an empty string is assigned nothing is written
2718                                     to file, otherwise the natural filename is taken \NC \NR
2719 \stoptabulate
2720
2721 A running (undefined) dimension in \type {width}, \type {height}, or \type
2722 {depth} is represented as \type {nil} in \LUA, so if you want to load an image at
2723 its \quote {natural} size, you do not have to specify any of those three fields.
2724
2725 The \type {stream} parameter allows to fabricate an \type {/XObject} \type
2726 {/Form} object from a string giving the stream contents, e.g., for a filled
2727 rectangle:
2728
2729 \startfunctioncall
2730 a.stream = "0 0 20 10 re f"
2731 \stopfunctioncall
2732
2733 When writing the image, an \type {/Xobject} \type {/Form} object is created, like
2734 with embedded \PDF\ file writing. The object is written out only once. The \type
2735 {stream} key requires that also the \type {bbox} table is given. The \type
2736 {stream} key conflicts with the \type {filename} key. The \type {transform} key
2737 works as usual also with \type {stream}.
2738
2739 The \type {bbox} key needs a table with four boundingbox values, e.g.:
2740
2741 \startfunctioncall
2742 a.bbox = {"30bp", 0, "225bp", "200bp"}
2743 \stopfunctioncall
2744
2745 This replaces and overrules any given \type {pagebox} value; with given \type
2746 {bbox} the box dimensions coming with an embedded \PDF\ file are ignored. The
2747 \type {xsize} and \type {ysize} dimensions are set accordingly, when the image is
2748 scaled. The \type {bbox} parameter is ignored for non-\PDF\ images.
2749
2750 The \type {transform} allows to mirror and rotate the image in steps of 90~deg.
2751 The default value~$0$ gives an unmirrored, unrotated image. Values $1-3$ give
2752 counterclockwise rotation by $90$, $180$, or $270$~degrees, whereas with values
2753 $4-7$ the image is first mirrored and then rotated counterclockwise by $90$,
2754 $180$, or $270$~degrees. The \type {transform} operation gives the same visual
2755 result as if you would externally preprocess the image by a graphics tool and
2756 then use it by \LUATEX. If a \PDF\ file to be embedded already contains a \type
2757 {/Rotate} specification, the rotation result is the combination of the \type
2758 {/Rotate} rotation followed by the \type {transform} operation.
2759
2760 \subsection{\type {img.scan}}
2761
2762 \startfunctioncall
2763 <image> var = img.scan(<image> var)
2764 <image> var = img.scan(<table> image_spec)
2765 \stopfunctioncall
2766
2767 When you say \type {img.scan(a)} for a new image, the file is scanned, and
2768 variables such as \type {xsize}, \type {ysize}, image \type {type}, number of
2769 \type {pages}, and the resolution are extracted. Each of the \type {width}, \type
2770 {height}, \type {depth} fields are set up according to the image dimensions, if
2771 they were not given an explicit value already. An image file will never be
2772 scanned more than once for a given image variable. With all subsequent \type
2773 {img.scan(a)} calls only the dimensions are again set up (if they have been
2774 changed by the user in the meantime).
2775
2776 For ease of use, you can do right-away a
2777
2778 \starttyping
2779 <image> a = img.scan ({ filename = "foo.png" })
2780 \stoptyping
2781
2782 without a prior \type {img.new}.
2783
2784 Nothing is written yet at this point, so you can do \type {a=img.scan}, retrieve
2785 the available info like image width and height, and then throw away \type {a}
2786 again by saying \type {a=nil}. In that case no image object will be reserved in
2787 the PDF, and the used memory will be cleaned up automatically.
2788
2789 \subsection{\type {img.copy}}
2790
2791 \startfunctioncall
2792 <image> var = img.copy(<image> var)
2793 <image> var = img.copy(<table> image_spec)
2794 \stopfunctioncall
2795
2796 If you say \type {a = b}, then both variables point to the same \type {<image>}
2797 object. if you want to write out an image with different sizes, you can do a
2798 \type {b=img.copy(a)}.
2799
2800 Afterwards, \type {a} and \type {b} still reference the same actual image
2801 dictionary, but the dimensions for \type {b} can now be changed from their
2802 initial values that were just copies from \type {a}.
2803
2804 \subsection{\type {img.write}}
2805
2806 \startfunctioncall
2807 <image> var = img.write(<image> var)
2808 <image> var = img.write(<table> image_spec)
2809 \stopfunctioncall
2810
2811 By \type {img.write(a)} a \PDF\ object number is allocated, and a whatsit node of
2812 subtype \type {pdf_refximage} is generated and put into the output list. By this
2813 the image \type {a} is placed into the page stream, and the image file is written
2814 out into an image stream object after the shipping of the current page is
2815 finished.
2816
2817 Again you can do a terse call like
2818
2819 \starttyping
2820 img.write ({ filename = "foo.png" })
2821 \stoptyping
2822
2823 The \type {<image>} variable is returned in case you want it for later
2824 processing.
2825
2826 \subsection{\type {img.immediatewrite}}
2827
2828 \startfunctioncall
2829 <image> var = img.immediatewrite(<image> var)
2830 <image> var = img.immediatewrite(<table> image_spec)
2831 \stopfunctioncall
2832
2833 By \type {img.immediatewrite(a)} a \PDF\ object number is allocated, and the
2834 image file for image \type {a} is written out immediately into the \PDF\ file as
2835 an image stream object (like with \type {\immediate}\type {\pdfximage}). The object
2836 number of the image stream dictionary is then available by the \type {objnum}
2837 key. No \type {pdf_refximage} whatsit node is generated. You will need an
2838 \type {img.write(a)} or \type {img.node(a)} call to let the image appear on the
2839 page, or reference it by another trick; else you will have a dangling image
2840 object in the \PDF\ file.
2841
2842 Also here you can do a terse call like
2843
2844 \starttyping
2845 a = img.immediatewrite ({ filename = "foo.png" })
2846 \stoptyping
2847
2848 The \type {<image>} variable is returned and you will most likely need it.
2849
2850 \subsection{\type {img.node}}
2851
2852 \startfunctioncall
2853 <node> n = img.node(<image> var)
2854 <node> n = img.node(<table> image_spec)
2855 \stopfunctioncall
2856
2857 This function allocates a \PDF\ object number and returns a whatsit node of
2858 subtype \type {pdf_refximage}, filled with the image parameters \type {width},
2859 \type {height}, \type {depth}, and \type {objnum}. Also here you can do a terse
2860 call like:
2861
2862 \starttyping
2863 n = img.node ({ filename = "foo.png" })
2864 \stoptyping
2865
2866 This example outputs an image:
2867
2868 \starttyping
2869 node.write(img.node{filename="foo.png"})
2870 \stoptyping
2871
2872 \subsection{\type {img.types}}
2873
2874 \startfunctioncall
2875 <table> types = img.types()
2876 \stopfunctioncall
2877
2878 This function returns a list with the supported image file type names, currently
2879 these are \type {pdf}, \type {png}, \type {jpg}, \type {jp2} (JPEG~2000), and
2880 \type {jbig2}.
2881
2882 \subsection{\type {img.boxes}}
2883
2884 \startfunctioncall
2885 <table> boxes = img.boxes()
2886 \stopfunctioncall
2887
2888 This function returns a list with the supported \PDF\ page box names, currently
2889 these are \type {media}, \type {crop}, \type {bleed}, \type {trim}, and \type
2890 {art} (all in lowercase letters).
2891
2892 \section{The \type {kpse} library}
2893
2894 This library provides two separate, but nearly identical interfaces to the
2895 \KPATHSEA\ file search functionality: there is a \quote {normal} procedural
2896 interface that shares its kpathsea instance with \LUATEX\ itself, and an object
2897 oriented interface that is completely on its own.
2898
2899 \subsection{\type {kpse.set_program_name} and \type {kpse.new}}
2900
2901 Before the search library can be used at all, its database has to be initialized.
2902 There are three possibilities, two of which belong to the procedural interface.
2903
2904 First, when \LUATEX\ is used to typeset documents, this initialization happens
2905 automatically and the \KPATHSEA\ executable and program names are set to \type
2906 {luatex} (that is, unless explicitly prohibited by the user's startup script.
2907 See~\in {section} [init] for more details).
2908
2909 Second, in \TEXLUA\ mode, the initialization has to be done explicitly via the
2910 \type {kpse.set_program_name} function, which sets the \KPATHSEA\ executable
2911 (and optionally program) name.
2912
2913 \startfunctioncall
2914 kpse.set_program_name(<string> name)
2915 kpse.set_program_name(<string> name, <string> progname)
2916 \stopfunctioncall
2917
2918 The second argument controls the use of the \quote {dotted} values in the \type
2919 {texmf.cnf} configuration file, and defaults to the first argument.
2920
2921 Third, if you prefer the object oriented interface, you have to call a different
2922 function. It has the same arguments, but it returns a userdata variable.
2923
2924 \startfunctioncall
2925 local kpathsea = kpse.new(<string> name)
2926 local kpathsea = kpse.new(<string> name, <string> progname)
2927 \stopfunctioncall
2928
2929 Apart from these two functions, the calling conventions of the interfaces are
2930 identical. Depending on the chosen interface, you either call \type
2931 {kpse.find_file()} or \type {kpathsea:find_file()}, with identical arguments and
2932 return vales.
2933
2934 \subsection{\type {find_file}}
2935
2936 The most often used function in the library is find_file:
2937
2938 \startfunctioncall
2939 <string> f = kpse.find_file(<string> filename)
2940 <string> f = kpse.find_file(<string> filename, <string> ftype)
2941 <string> f = kpse.find_file(<string> filename, <boolean> mustexist)
2942 <string> f = kpse.find_file(<string> filename, <string> ftype, <boolean> mustexist)
2943 <string> f = kpse.find_file(<string> filename, <string> ftype, <number> dpi)
2944 \stopfunctioncall
2945
2946 Arguments:
2947 \startitemize[intro]
2948
2949 \sym{filename}
2950
2951 the name of the file you want to find, with or without extension.
2952
2953 \sym{ftype}
2954
2955 maps to the \type {-format} argument of \KPSEWHICH. The supported \type {ftype}
2956 values are the same as the ones supported by the standalone \type {kpsewhich}
2957 program:
2958
2959 \startsimplecolumns
2960 \starttyping
2961 gf
2962 pk
2963 bitmap font
2964 tfm
2965 afm
2966 base
2967 bib
2968 bst
2969 cnf
2970 ls-R
2971 fmt
2972 map
2973 mem
2974 mf
2975 mfpool
2976 mft
2977 mp
2978 mppool
2979 MetaPost support
2980 ocp
2981 ofm
2982 opl
2983 otp
2984 ovf
2985 ovp
2986 graphic/figure
2987 tex
2988 TeX system documentation
2989 texpool
2990 TeX system sources
2991 PostScript header
2992 Troff fonts
2993 type1 fonts
2994 vf
2995 dvips config
2996 ist
2997 truetype fonts
2998 type42 fonts
2999 web2c files
3000 other text files
3001 other binary files
3002 misc fonts
3003 web
3004 cweb
3005 enc files
3006 cmap files
3007 subfont definition files
3008 opentype fonts
3009 pdftex config
3010 lig files
3011 texmfscripts
3012 lua
3013 font feature files
3014 cid maps
3015 mlbib
3016 mlbst
3017 clua
3018 \stoptyping
3019 \stopsimplecolumns
3020
3021 The default type is \type {tex}. Note: this is different from \KPSEWHICH, which
3022 tries to deduce the file type itself from looking at the supplied extension.
3023
3024 \sym{mustexist}
3025
3026 is similar to \KPSEWHICH's \type {-must-exist}, and the default is \type {false}.
3027 If you specify \type {true} (or a non|-|zero integer), then the \KPSE\ library
3028 will search the disk as well as the \type {ls-R} databases.
3029
3030 \sym{dpi}
3031
3032 This is used for the size argument of the formats \type {pk}, \type {gf}, and
3033 \type {bitmap font}. \stopitemize
3034
3035
3036 \subsection{\type {lookup}}
3037
3038 A more powerful (but slower) generic method for finding files is also available.
3039 It returns a string for each found file.
3040
3041 \startfunctioncall
3042 <string> f, ... = kpse.lookup(<string> filename, <table> options)
3043 \stopfunctioncall
3044
3045 The options match commandline arguments from \type {kpsewhich}:
3046
3047 \starttabulate[|l|l|p|]
3048 \NC \ssbf key \NC \ssbf type \NC \ssbf description \NC \NR
3049 \NC debug     \NC number     \NC set debugging flags for this lookup\NC     \NR
3050 \NC format    \NC string     \NC use specific file type (see list above)\NC \NR
3051 \NC dpi       \NC number     \NC use this resolution for this lookup; default 600\NC \NR
3052 \NC path      \NC string     \NC search in the given path\NC \NR
3053 \NC all       \NC boolean    \NC output all matches, not just the first\NC \NR
3054 \NC mustexist \NC boolean    \NC search the disk as well as ls-R if necessary\NC \NR
3055 \NC mktexpk   \NC boolean    \NC disable/enable mktexpk generation for this lookup\NC \NR
3056 \NC mktextex  \NC boolean    \NC disable/enable mktextex generation for this lookup\NC \NR
3057 \NC mktexmf   \NC boolean    \NC disable/enable mktexmf generation for this lookup\NC \NR
3058 \NC mktextfm  \NC boolean    \NC disable/enable mktextfm generation for this lookup\NC \NR
3059 \NC subdir    \NC string
3060                   or table   \NC only output matches whose directory part
3061                                  ends with the given string(s) \NC \NR
3062 \stoptabulate
3063
3064 \subsection{\type {init_prog}}
3065
3066 Extra initialization for programs that need to generate bitmap fonts.
3067
3068 \startfunctioncall
3069 kpse.init_prog(<string> prefix, <number> base_dpi, <string> mfmode)
3070 kpse.init_prog(<string> prefix, <number> base_dpi, <string> mfmode, <string> fallback)
3071 \stopfunctioncall
3072
3073 \subsection{\type {readable_file}}
3074
3075 Test if an (absolute) file name is a readable file.
3076
3077 \startfunctioncall
3078 <string> f = kpse.readable_file(<string> name)
3079 \stopfunctioncall
3080
3081 The return value is the actual absolute filename you should use, because the disk
3082 name is not always the same as the requested name, due to aliases and
3083 system|-|specific handling under e.g.\ \MSDOS. Returns \type {nil} if the file
3084 does not exist or is not readable.
3085
3086 \subsection{\type {expand_path}}
3087
3088 Like kpsewhich's \type {-expand-path}:
3089
3090 \startfunctioncall
3091 <string> r = kpse.expand_path(<string> s)
3092 \stopfunctioncall
3093
3094 \subsection{\type {expand_var}}
3095
3096 Like kpsewhich's  \type {-expand-var}:
3097
3098 \startfunctioncall
3099 <string> r = kpse.expand_var(<string> s)
3100 \stopfunctioncall
3101
3102 \subsection{\type {expand_braces}}
3103
3104 Like kpsewhich's \type {-expand-braces}:
3105
3106 \startfunctioncall
3107 <string> r = kpse.expand_braces(<string> s)
3108 \stopfunctioncall
3109
3110 \subsection{\type {show_path}}
3111
3112 Like kpsewhich's \type {-show-path}:
3113
3114 \startfunctioncall
3115 <string> r = kpse.show_path(<string> ftype)
3116 \stopfunctioncall
3117
3118
3119 \subsection{\type {var_value}}
3120
3121 Like kpsewhich's \type {-var-value}:
3122
3123 \startfunctioncall
3124 <string> r = kpse.var_value(<string> s)
3125 \stopfunctioncall
3126
3127 \subsection{\type {version}}
3128
3129 Returns the kpathsea version string.
3130
3131 \startfunctioncall
3132 <string> r = kpse.version()
3133 \stopfunctioncall
3134
3135
3136 \section{The \type {lang} library}
3137
3138 This library provides the interface to \LUATEX's structure
3139 representing a language, and the associated functions.
3140
3141 \startfunctioncall
3142 <language> l = lang.new()
3143 <language> l = lang.new(<number> id)
3144 \stopfunctioncall
3145
3146 This function creates a new userdata object. An object of type \type {<language>}
3147 is the first argument to most of the other functions in the \type {lang}
3148 library. These functions can also be used as if they were object methods, using
3149 the colon syntax.
3150
3151 Without an argument, the next available internal id number will be assigned to
3152 this object. With argument, an object will be created that links to the internal
3153 language with that id number.
3154
3155 \startfunctioncall
3156 <number> n = lang.id(<language> l)
3157 \stopfunctioncall
3158
3159 returns the internal \type {\language} id number this object refers to.
3160
3161 \startfunctioncall
3162 <string> n = lang.hyphenation(<language> l)
3163 lang.hyphenation(<language> l, <string> n)
3164 \stopfunctioncall
3165
3166 Either returns the current hyphenation exceptions for this language, or adds new
3167 ones. The syntax of the string is explained in~\in {section}
3168 [patternsexceptions].
3169
3170 \startfunctioncall
3171 lang.clear_hyphenation(<language> l)
3172 \stopfunctioncall
3173
3174 Clears the exception dictionary (string) for this language.
3175
3176 \startfunctioncall
3177 <string> n = lang.clean(<language> l, <string> o)
3178 <string> n = lang.clean(<string> o)
3179 \stopfunctioncall
3180
3181 Creates a hyphenation key from the supplied hyphenation value. The syntax of the
3182 argument string is explained in~\in {section} [patternsexceptions]. This function
3183 is useful if you want to do something else based on the words in a dictionary
3184 file, like spell|-|checking.
3185
3186 \startfunctioncall
3187 <string> n = lang.patterns(<language> l)
3188 lang.patterns(<language> l, <string> n)
3189 \stopfunctioncall
3190
3191 Adds additional patterns for this language object, or returns the current set.
3192 The syntax of this string is explained in~\in {section} [patternsexceptions].
3193
3194 \startfunctioncall
3195 lang.clear_patterns(<language> l)
3196 \stopfunctioncall
3197
3198 Clears the pattern dictionary for this language.
3199
3200 \startfunctioncall
3201 <number> n = lang.prehyphenchar(<language> l)
3202 lang.prehyphenchar(<language> l, <number> n)
3203 \stopfunctioncall
3204
3205 Gets or sets the \quote {pre|-|break} hyphen character for implicit hyphenation
3206 in this language (initially the hyphen, decimal 45).
3207
3208 \startfunctioncall
3209 <number> n = lang.posthyphenchar(<language> l)
3210 lang.posthyphenchar(<language> l, <number> n)
3211 \stopfunctioncall
3212
3213 Gets or sets the \quote {post|-|break} hyphen character for implicit hyphenation
3214 in this language (initially null, decimal~0, indicating emptiness).
3215
3216 \startfunctioncall
3217 <number> n = lang.preexhyphenchar(<language> l)
3218 lang.preexhyphenchar(<language> l, <number> n)
3219 \stopfunctioncall
3220
3221 Gets or sets the \quote {pre|-|break} hyphen character for explicit hyphenation
3222 in this language (initially null, decimal~0, indicating emptiness).
3223
3224 \startfunctioncall
3225 <number> n = lang.postexhyphenchar(<language> l)
3226 lang.postexhyphenchar(<language> l, <number> n)
3227 \stopfunctioncall
3228
3229 Gets or sets the \quote {post|-|break} hyphen character for explicit hyphenation
3230 in this language (initially null, decimal~0, indicating emptiness).
3231
3232 \startfunctioncall
3233 <boolean> success = lang.hyphenate(<node> head)
3234 <boolean> success = lang.hyphenate(<node> head, <node> tail)
3235 \stopfunctioncall
3236
3237 Inserts hyphenation points (discretionary nodes) in a node list. If \type {tail}
3238 is given as argument, processing stops on that node. Currently, \type {success}
3239 is always true if \type {head} (and \type {tail}, if specified) are proper nodes,
3240 regardless of possible other errors.
3241
3242 Hyphenation works only on \quote {characters}, a special subtype of all the glyph
3243 nodes with the node subtype having the value \type {1}. Glyph modes with
3244 different subtypes are not processed. See \in {section~} [charsandglyphs] for
3245 more details.
3246
3247 The following two commands can be used to set or query hj codes:
3248
3249 \startfunctioncall
3250 lang.sethjcode(<language> l, <number> char, <number> usedchar)
3251 <number> usedchar = lang.gethjcode(<language> l, <number> char)
3252 \stopfunctioncall
3253
3254 When you set a hjcode the current sets get initialized unless the set was already
3255 initialized due to \type {\savinghyphcodes} being larger than zero.
3256
3257 \section{The \type {lua} library}
3258
3259 This library contains one read|-|only  item:
3260
3261 \starttyping
3262 <string> s = lua.version
3263 \stoptyping
3264
3265 This returns the \LUA\ version identifier string. The value is currently
3266 \directlua {tex.print(lua.version)}.
3267
3268 \subsection{\LUA\ bytecode registers}
3269
3270 \LUA\ registers can be used to communicate \LUA\ functions across \LUA\ chunks.
3271 The accepted values for assignments are functions and \type {nil}. Likewise, the
3272 retrieved value is either a function or \type {nil}.
3273
3274 \starttyping
3275 lua.bytecode[<number> n] = <function> f
3276 lua.bytecode[<number> n]()
3277 \stoptyping
3278
3279 The contents of the \type {lua.bytecode} array is stored inside the format file
3280 as actual \LUA\ bytecode, so it can also be used to preload \LUA\ code.
3281
3282 Note: The function must not contain any upvalues. Currently, functions containing
3283 upvalues can be stored (and their upvalues are set to \type {nil}), but this is
3284 an artifact of the current \LUA\ implementation and thus subject to change.
3285
3286 The associated function calls are
3287
3288 \startfunctioncall
3289 <function> f = lua.getbytecode(<number> n)
3290 lua.setbytecode(<number> n, <function> f)
3291 \stopfunctioncall
3292
3293 Note: Since a \LUA\ file loaded using \type {loadfile(filename)} is essentially
3294 an anonymous function, a complete file can be stored in a bytecode register like
3295 this:
3296
3297 \startfunctioncall
3298 lua.bytecode[n] = loadfile(filename)
3299 \stopfunctioncall
3300
3301 Now all definitions (functions, variables) contained in the file can be
3302 created by executing this bytecode register:
3303
3304 \startfunctioncall
3305 lua.bytecode[n]()
3306 \stopfunctioncall
3307
3308 Note that the path of the file is stored in the \LUA\ bytecode to be used in
3309 stack backtraces and therefore dumped into the format file if the above code is
3310 used in \INITEX. If it contains private information, i.e. the user name, this
3311 information is then contained in the format file as well. This should be kept in
3312 mind when preloading files into a bytecode register in \INITEX.
3313
3314 \subsection{\LUA\ chunk name registers}
3315
3316 There is an array of 65536 (0--65535) potential chunk names for use with the
3317 \type {\directlua} and \type {\latelua} primitives.
3318
3319 \startfunctioncall
3320 lua.name[<number> n] = <string> s
3321 <string> s = lua.name[<number> n]
3322 \stopfunctioncall
3323
3324 If you want to unset a \LUA\ name, you can assign \type {nil} to it.
3325
3326 \section{The \type {mplib} library}
3327
3328 The \MP\ library interface registers itself in the table \type {mplib}. It is
3329 based on \MPLIB\ version \ctxlua {context(mplib.version())}.
3330
3331 \subsection{\type {mplib.new}}
3332
3333 To create a new \METAPOST\ instance, call
3334
3335 \startfunctioncall
3336 <mpinstance> mp = mplib.new({...})
3337 \stopfunctioncall
3338
3339 This creates the \type {mp} instance object. The argument hash can have a number
3340 of different fields, as follows:
3341
3342 \starttabulate[|lT|l|p|p|]
3343 \NC \ssbf name  \NC \bf type \NC \bf description          \NC \bf default       \NC \NR
3344 \NC error_line  \NC number   \NC error line width         \NC 79                \NC \NR
3345 \NC print_line  \NC number   \NC line length in ps output \NC 100               \NC \NR
3346 \NC random_seed \NC number   \NC the initial random seed  \NC variable          \NC \NR
3347 \NC interaction \NC string   \NC the interaction mode,
3348                                  one of
3349                                  \type {batch},
3350                                  \type {nonstop},
3351                                  \type {scroll},
3352                                  \type {errorstop}        \NC \type {errorstop} \NC \NR
3353 \NC job_name    \NC string   \NC \type {--jobname}        \NC \type {mpout}     \NC \NR
3354 \NC find_file   \NC function \NC a function to find files \NC only local files  \NC \NR
3355 \stoptabulate
3356
3357 The \type {find_file} function should be of this form:
3358
3359 \starttyping
3360 <string> found = finder (<string> name, <string> mode, <string> type)
3361 \stoptyping
3362
3363 with:
3364
3365 \starttabulate[|lT|l|p|]
3366 \NC \bf name \NC \bf the requested file \NC \NR
3367 \NC mode     \NC the file mode: \type {r} or \type {w} \NC \NR
3368 \NC type     \NC the kind of file, one of: \type {mp}, \type {tfm}, \type {map},
3369                  \type {pfb}, \type {enc} \NC \NR
3370 \stoptabulate
3371
3372 Return either the full path name of the found file, or \type {nil} if the file
3373 cannot be found.
3374
3375 Note that the new version of \MPLIB\ no longer uses binary mem files, so the way
3376 to preload a set of macros is simply to start off with an \type {input} command
3377 in the first \type {mp:execute()} call.
3378
3379 \subsection{\type {mp:statistics}}
3380
3381 You can request statistics with:
3382
3383 \startfunctioncall
3384 <table> stats = mp:statistics()
3385 \stopfunctioncall
3386
3387 This function returns the vital statistics for an \MPLIB\ instance. There are
3388 four fields, giving the maximum number of used items in each of four allocated
3389 object classes:
3390
3391 \starttabulate[|lT|l|p|]
3392 \NC main_memory \NC number \NC memory size \NC \NR
3393 \NC hash_size   \NC number \NC hash size\NC \NR
3394 \NC param_size  \NC number \NC simultaneous macro parameters\NC \NR
3395 \NC max_in_open \NC number \NC input file nesting levels\NC \NR
3396 \stoptabulate
3397
3398 Note that in the new version of \MPLIB, this is informational only. The objects
3399 are all allocated dynamically, so there is no chance of running out of space
3400 unless the available system memory is exhausted.
3401
3402 \subsection{\type {mp:execute}}
3403
3404 You can ask the \METAPOST\ interpreter to run a chunk of code by calling
3405
3406 \startfunctioncall
3407 <table> rettable = mp:execute('metapost language chunk')
3408 \stopfunctioncall
3409
3410 for various bits of \METAPOST\ language input. Be sure to check the \type
3411 {rettable.status} (see below) because when a fatal \METAPOST\ error occurs the
3412 \MPLIB\ instance will become unusable thereafter.
3413
3414 Generally speaking, it is best to keep your chunks small, but beware that all
3415 chunks have to obey proper syntax, like each of them is a small file. For
3416 instance, you cannot split a single statement over multiple chunks.
3417
3418 In contrast with the normal stand alone \type {mpost} command, there is {\em no}
3419 implied \quote{input} at the start of the first chunk.
3420
3421 \subsection{\type {mp:finish}}
3422
3423 \startfunctioncall
3424 <table> rettable = mp:finish()
3425 \stopfunctioncall
3426
3427 If for some reason you want to stop using an \MPLIB\ instance while processing is
3428 not yet actually done, you can call \type {mp:finish}. Eventually, used memory
3429 will be freed and open files will be closed by the \LUA\ garbage collector, but
3430 an explicit \type {mp:finish} is the only way to capture the final part of the
3431 output streams.
3432
3433 \subsection{Result table}
3434
3435 The return value of \type {mp:execute} and \type {mp:finish} is a table with a
3436 few possible keys (only \type {status} is always guaranteed to be present).
3437
3438 \starttabulate[|l|l|p|]
3439 \NC log    \NC string \NC output to the \quote {log} stream \NC \NR
3440 \NC term   \NC string \NC output to the \quote {term} stream \NC \NR
3441 \NC error  \NC string \NC output to the \quote {error} stream
3442                           (only used for \quote {out of memory}) \NC \NR
3443 \NC status \NC number \NC the return value:
3444                           \type {0} = good,
3445                           \type {1} = warning,
3446                           \type {2} = errors,
3447                           \type {3} = fatal error \NC \NR
3448 \NC fig    \NC table  \NC an array of generated figures (if any) \NC \NR
3449 \stoptabulate
3450
3451 When \type {status} equals~3, you should stop using this \MPLIB\ instance
3452 immediately, it is no longer capable of processing input.
3453
3454 If it is present, each of the entries in the \type {fig} array is a userdata
3455 representing a figure object, and each of those has a number of object methods
3456 you can call:
3457
3458 \starttabulate[|l|l|p|]
3459 \NC boundingbox  \NC function \NC returns the bounding box, as an array of 4
3460                                   values\NC \NR
3461 \NC postscript   \NC function \NC returns a string that is the ps output of the
3462                                   \type {fig}. this function accepts two optional
3463                                   integer arguments for specifying the values of
3464                                   \type {prologues} (first argument) and \type
3465                                   {procset} (second argument)\NC \NR
3466 \NC svg          \NC function \NC returns a string that is the svg output of the
3467                                   \type {fig}. This function accepts an optional
3468                                   integer argument for specifying the value of
3469                                   \type {prologues}\NC \NR
3470 \NC objects      \NC function \NC returns the actual array of graphic objects in
3471                                   this \type {fig} \NC \NR
3472 \NC copy_objects \NC function \NC returns a deep copy of the array of graphic
3473                                   objects in this \type {fig} \NC \NR
3474 \NC filename     \NC function \NC the filename this \type {fig}'s \POSTSCRIPT\
3475                                   output would have written to in stand alone
3476                                   mode \NC \NR
3477 \NC width        \NC function \NC the \type {fontcharwd} value \NC \NR
3478 \NC height       \NC function \NC the \type {fontcharht} value \NC \NR
3479 \NC depth        \NC function \NC the \type {fontchardp} value \NC \NR
3480 \NC italcorr     \NC function \NC the \type {fontcharit} value \NC \NR
3481 \NC charcode     \NC function \NC the (rounded) \type {charcode} value \NC \NR
3482 \stoptabulate
3483
3484 Note: you can call \type {fig:objects()} only once for any one \type {fig}
3485 object!
3486
3487 When the boundingbox represents a \quote {negated rectangle}, i.e.\ when the
3488 first set of coordinates is larger than the second set, the picture is empty.
3489
3490 Graphical objects come in various types that each has a different list of
3491 accessible values. The types are: \type {fill}, \type {outline}, \type {text},
3492 \type {start_clip}, \type {stop_clip}, \type {start_bounds}, \type {stop_bounds},
3493 \type {special}.
3494
3495 There is helper function (\type {mplib.fields(obj)}) to get the list of
3496 accessible values for a particular object, but you can just as easily use the
3497 tables given below.
3498
3499 All graphical objects have a field \type {type} that gives the object type as a
3500 string value; it is not explicit mentioned in the following tables. In the
3501 following, \type {number}s are \POSTSCRIPT\ points represented as a floating
3502 point number, unless stated otherwise. Field values that are of type \type
3503 {table} are explained in the next section.
3504
3505 \subsubsection{fill}
3506
3507 \starttabulate[|l|l|p|]
3508 \NC path       \NC table  \NC the list of knots \NC \NR
3509 \NC htap       \NC table  \NC the list of knots for the reversed trajectory \NC \NR
3510 \NC pen        \NC table  \NC knots of the pen \NC \NR
3511 \NC color      \NC table  \NC the object's color \NC \NR
3512 \NC linejoin   \NC number \NC line join style (bare number)\NC \NR
3513 \NC miterlimit \NC number \NC miterlimit\NC \NR
3514 \NC prescript  \NC string \NC the prescript text \NC \NR
3515 \NC postscript \NC string \NC the postscript text \NC \NR
3516 \stoptabulate
3517
3518 The entries \type {htap} and \type {pen} are optional.
3519
3520 There is helper function (\type {mplib.pen_info(obj)}) that returns a table
3521 containing a bunch of vital characteristics of the used pen (all values are
3522 floats):
3523
3524 \starttabulate[|l|l|p|]
3525 \NC width \NC number \NC width of the pen \NC \NR
3526 \NC sx    \NC number \NC $x$ scale        \NC \NR
3527 \NC rx    \NC number \NC $xy$ multiplier  \NC \NR
3528 \NC ry    \NC number \NC $yx$ multiplier  \NC \NR
3529 \NC sy    \NC number \NC $y$ scale        \NC \NR
3530 \NC tx    \NC number \NC $x$ offset       \NC \NR
3531 \NC ty    \NC number \NC $y$ offset       \NC \NR
3532 \stoptabulate
3533
3534 \subsubsection{outline}
3535
3536 \starttabulate[|l|l|p|]
3537 \NC path       \NC table  \NC the list of knots \NC \NR
3538 \NC pen        \NC table  \NC knots of the pen \NC \NR
3539 \NC color      \NC table  \NC the object's color \NC \NR
3540 \NC linejoin   \NC number \NC line join style (bare number) \NC \NR
3541 \NC miterlimit \NC number \NC miterlimit \NC \NR
3542 \NC linecap    \NC number \NC line cap style (bare number) \NC \NR
3543 \NC dash       \NC table  \NC representation of a dash list \NC \NR
3544 \NC prescript  \NC string \NC the prescript text \NC \NR
3545 \NC postscript \NC string \NC the postscript text \NC \NR
3546 \stoptabulate
3547
3548 The entry \type {dash} is optional.
3549
3550 \subsubsection{text}
3551
3552 \starttabulate[|l|l|p|]
3553 \NC text       \NC string \NC the text \NC \NR
3554 \NC font       \NC string \NC font tfm name \NC \NR
3555 \NC dsize      \NC number \NC font size \NC \NR
3556 \NC color      \NC table  \NC the object's color \NC \NR
3557 \NC width      \NC number \NC \NC \NR
3558 \NC height     \NC number \NC \NC \NR
3559 \NC depth      \NC number \NC \NC \NR
3560 \NC transform  \NC table  \NC a text transformation \NC \NR
3561 \NC prescript  \NC string \NC the prescript text \NC \NR
3562 \NC postscript \NC string \NC the postscript text \NC \NR
3563 \stoptabulate
3564
3565 \subsubsection{special}
3566
3567 \starttabulate[|l|l|p|]
3568 \NC prescript \NC string \NC special text \NC \NR
3569 \stoptabulate
3570
3571 \subsubsection{start_bounds, start_clip}
3572
3573 \starttabulate[|l|l|p|]
3574 \NC path \NC table \NC the list of knots \NC \NR
3575 \stoptabulate
3576
3577 \subsubsection{stop_bounds, stop_clip}
3578
3579 Here are no fields available.
3580
3581 \subsection{Subsidiary table formats}
3582
3583 \subsubsection{Paths and pens}
3584
3585 Paths and pens (that are really just a special type of paths as far as \MPLIB\ is
3586 concerned) are represented by an array where each entry is a table that
3587 represents a knot.
3588
3589 \starttabulate[|lT|l|p|]
3590 \NC left_type   \NC string \NC when present: endpoint, but usually absent \NC \NR
3591 \NC right_type  \NC string \NC like \type {left_type} \NC \NR
3592 \NC x_coord     \NC number \NC X coordinate of this knot \NC \NR
3593 \NC y_coord     \NC number \NC Y coordinate of this knot \NC \NR
3594 \NC left_x      \NC number \NC X coordinate of the precontrol point of this knot \NC \NR
3595 \NC left_y      \NC number \NC Y coordinate of the precontrol point of this knot \NC \NR
3596 \NC right_x     \NC number \NC X coordinate of the postcontrol point of this knot \NC \NR
3597 \NC right_y     \NC number \NC Y coordinate of the postcontrol point of this knot \NC \NR
3598 \stoptabulate
3599
3600 There is one special case: pens that are (possibly transformed) ellipses have an
3601 extra string-valued key \type {type} with value \type {elliptical} besides the
3602 array part containing the knot list.
3603
3604 \subsubsection{Colors}
3605
3606 A color is an integer array with 0, 1, 3 or 4 values:
3607
3608 \starttabulate[|l|l|p|]
3609 \NC 0 \NC marking only \NC no values                                                     \NC \NR
3610 \NC 1 \NC greyscale    \NC one value in the range $(0,1)$, \quote {black} is $0$         \NC \NR
3611 \NC 3 \NC \RGB         \NC three values in the range $(0,1)$, \quote {black} is $0,0,0$  \NC \NR
3612 \NC 4 \NC \CMYK        \NC four values in the range $(0,1)$, \quote {black} is $0,0,0,1$ \NC \NR
3613 \stoptabulate
3614
3615 If the color model of the internal object was \type {uninitialized}, then it was
3616 initialized to the values representing \quote {black} in the colorspace \type
3617 {defaultcolormodel} that was in effect at the time of the \type {shipout}.
3618
3619 \subsubsection{Transforms}
3620
3621 Each transform is a six|-|item array.
3622
3623 \starttabulate[|l|l|p|]
3624 \NC 1 \NC number \NC represents x  \NC \NR
3625 \NC 2 \NC number \NC represents y  \NC \NR
3626 \NC 3 \NC number \NC represents xx \NC \NR
3627 \NC 4 \NC number \NC represents yx \NC \NR
3628 \NC 5 \NC number \NC represents xy \NC \NR
3629 \NC 6 \NC number \NC represents yy \NC \NR
3630 \stoptabulate
3631
3632 Note that the translation (index 1 and 2) comes first. This differs from the
3633 ordering in \POSTSCRIPT, where the translation comes last.
3634
3635 \subsubsection{Dashes}
3636
3637 Each \type {dash} is two-item hash, using the same model as \POSTSCRIPT\ for the
3638 representation of the dashlist. \type {dashes} is an array of \quote {on} and
3639 \quote {off}, values, and \type {offset} is the phase of the pattern.
3640
3641 \starttabulate[|l|l|p|]
3642 \NC dashes \NC hash   \NC an array of on-off numbers \NC \NR
3643 \NC offset \NC number \NC the starting offset value  \NC \NR
3644 \stoptabulate
3645
3646 \subsection{Character size information}
3647
3648 These functions find the size of a glyph in a defined font. The \type {fontname}
3649 is the same name as the argument to \type {infont}; the \type {char} is a glyph
3650 id in the range 0 to 255; the returned \type {w} is in AFM units.
3651
3652 \subsubsection{\type {mp:char_width}}
3653
3654 \startfunctioncall
3655 <number> w = mp:char_width(<string> fontname, <number> char)
3656 \stopfunctioncall
3657
3658 \subsubsection{\type {mp:char_height}}
3659
3660 \startfunctioncall
3661 <number> w = mp:char_height(<string> fontname, <number> char)
3662 \stopfunctioncall
3663
3664 \subsubsection{\type {mp:char_depth}}
3665
3666 \startfunctioncall
3667 <number> w = mp:char_depth(<string> fontname, <number> char)
3668 \stopfunctioncall
3669
3670 \section{The \type {node} library}
3671
3672 The \type {node} library contains functions that facilitate dealing with (lists
3673 of) nodes and their values. They allow you to create, alter, copy, delete, and
3674 insert \LUATEX\ node objects, the core objects within the typesetter.
3675
3676 \LUATEX\ nodes are represented in \LUA\ as userdata with the metadata type
3677 \type {luatex.node}. The various parts within a node can be accessed using
3678 named fields.
3679
3680 Each node has at least the three fields \type {next}, \type {id}, and \type
3681 {subtype}:
3682
3683 \startitemize[intro]
3684
3685 \startitem
3686     The \type {next} field returns the userdata object for the next node in a
3687     linked list of nodes, or \type {nil}, if there is no next node.
3688 \stopitem
3689
3690 \startitem
3691     The \type {id} indicates \TEX's \quote{node type}. The field \type {id} has a
3692     numeric value for efficiency reasons, but some of the library functions also
3693     accept a string value instead of \type {id}.
3694 \stopitem
3695
3696 \startitem
3697     The \type {subtype} is another number. It often gives further information
3698     about a node of a particular \type {id}, but it is most important when
3699     dealing with \quote {whatsits}, because they are differentiated solely based
3700     on their \type {subtype}.
3701 \stopitem
3702
3703 \stopitemize
3704
3705 The other available fields depend on the \type {id} (and for \quote {whatsits},
3706 the \type {subtype}) of the node. Further details on the various fields and their
3707 meanings are given in~\in{chapter}[nodes].
3708
3709 Support for \type {unset} (alignment) nodes is partial: they can be queried and
3710 modified from \LUA\ code, but not created.
3711
3712 Nodes can be compared to each other, but: you are actually comparing indices into
3713 the node memory. This means that equality tests can only be trusted under very
3714 limited conditions. It will not work correctly in any situation where one of the
3715 two nodes has been freed and|/|or reallocated: in that case, there will be false
3716 positives.
3717
3718 At the moment, memory management of nodes should still be done explicitly by the
3719 user. Nodes are not \quote {seen} by the \LUA\ garbage collector, so you have to
3720 call the node freeing functions yourself when you are no longer in need of a node
3721 (list). Nodes form linked lists without reference counting, so you have to be
3722 careful that when control returns back to \LUATEX\ itself, you have not deleted
3723 nodes that are still referenced from a \type {next} pointer elsewhere, and that
3724 you did not create nodes that are referenced more than once.
3725
3726 There are statistics available with regards to the allocated node memory, which
3727 can be handy for tracing.
3728
3729 \subsection{Node handling functions}
3730
3731 \subsubsection{\type {node.is_node}}
3732
3733 \startfunctioncall
3734 <boolean> t = node.is_node(<any> item)
3735 \stopfunctioncall
3736
3737 This function returns true if the argument is a userdata object of
3738 type \type {<node>}.
3739
3740 \subsubsection{\type {node.types}}
3741
3742 \startfunctioncall
3743 <table> t = node.types()
3744 \stopfunctioncall
3745
3746 This function returns an array that maps node id numbers to node type strings,
3747 providing an overview of the possible top|-|level \type {id} types.
3748
3749 \subsubsection{\type {node.whatsits}}
3750
3751 \startfunctioncall
3752 <table> t = node.whatsits()
3753 \stopfunctioncall
3754
3755 \TEX's \quote{whatsits} all have the same \type {id}. The various subtypes are
3756 defined by their \type {subtype} fields. The function is much like \type
3757 {node.types}, except that it provides an array of \type {subtype} mappings.
3758
3759 \subsubsection{\type {node.id}}
3760
3761 \startfunctioncall
3762 <number> id = node.id(<string> type)
3763 \stopfunctioncall
3764
3765 This converts a single type name to its internal numeric representation.
3766
3767 \subsubsection{\type {node.subtype}}
3768
3769 \startfunctioncall
3770 <number> subtype = node.subtype(<string> type)
3771 \stopfunctioncall
3772
3773 This converts a single whatsit name to its internal numeric representation (\type
3774 {subtype}).
3775
3776 \subsubsection{\type {node.type}}
3777
3778 \startfunctioncall
3779 <string> type = node.type(<any> n)
3780 \stopfunctioncall
3781
3782 In the argument is a number, then this function converts an internal numeric
3783 representation to an external string representation. Otherwise, it will return
3784 the string \type {node} if the object represents a node, and \type {nil}
3785 otherwise.
3786
3787 \subsubsection{\type {node.fields}}
3788
3789 \startfunctioncall
3790 <table> t = node.fields(<number> id)
3791 <table> t = node.fields(<number> id, <number> subtype)
3792 \stopfunctioncall
3793
3794 This function returns an array of valid field names for a particular type of
3795 node. If you want to get the valid fields for a \quote {whatsit}, you have to
3796 supply the second argument also. In other cases, any given second argument will
3797 be silently ignored.
3798
3799 This function accepts string \type {id} and \type {subtype} values as well.
3800
3801 \subsubsection{\type {node.has_field}}
3802
3803 \startfunctioncall
3804 <boolean> t = node.has_field(<node> n, <string> field)
3805 \stopfunctioncall
3806
3807 This function returns a boolean that is only true if \type {n} is
3808 actually a node, and it has the field.
3809
3810 \subsubsection{\type {node.new}}
3811
3812 \startfunctioncall
3813 <node> n = node.new(<number> id)
3814 <node> n = node.new(<number> id, <number> subtype)
3815 \stopfunctioncall
3816
3817 Creates a new node. All of the new node's fields are initialized to either zero
3818 or \type {nil} except for \type {id} and \type {subtype} (if supplied). If you
3819 want to create a new whatsit, then the second argument is required, otherwise it
3820 need not be present. As with all node functions, this function creates a node on
3821 the \TEX\ level.
3822
3823 This function accepts string \type {id} and \type {subtype} values as well.
3824
3825 \subsubsection{\type {node.free}}
3826
3827 \startfunctioncall
3828 node.free(<node> n)
3829 \stopfunctioncall
3830
3831 Removes the node \type {n} from \TEX's memory. Be careful: no checks are done on
3832 whether this node is still pointed to from a register or some \type {next} field:
3833 it is up to you to make sure that the internal data structures remain correct.
3834
3835 \subsubsection{\type {node.flush_list}}
3836
3837 \startfunctioncall
3838 node.flush_list(<node> n)
3839 \stopfunctioncall
3840
3841 Removes the node list \type {n} and the complete node list following \type {n}
3842 from \TEX's memory. Be careful: no checks are done on whether any of these nodes
3843 is still pointed to from a register or some \type {next} field: it is up to you
3844 to make sure that the internal data structures remain correct.
3845
3846 \subsubsection{\type {node.copy}}
3847
3848 \startfunctioncall
3849 <node> m = node.copy(<node> n)
3850 \stopfunctioncall
3851
3852 Creates a deep copy of node \type {n}, including all nested lists as in the case
3853 of a hlist or vlist node. Only the \type {next} field is not copied.
3854
3855 \subsubsection{\type {node.copy_list}}
3856
3857 \startfunctioncall
3858 <node> m = node.copy_list(<node> n)
3859 <node> m = node.copy_list(<node> n, <node> m)
3860 \stopfunctioncall
3861
3862 Creates a deep copy of the node list that starts at \type {n}. If \type {m} is
3863 also given, the copy stops just before node \type {m}.
3864
3865 Note that you cannot copy attribute lists this way, specialized functions for
3866 dealing with attribute lists will be provided later but are not there yet.
3867 However, there is normally no need to copy attribute lists as when you do
3868 assignments to the \type {attr} field or make changes to specific attributes, the
3869 needed copying and freeing takes place automatically.
3870
3871 \subsubsection{\type {node.next}}
3872
3873 \startfunctioncall
3874 <node> m = node.next(<node> n)
3875 \stopfunctioncall
3876
3877 Returns the node following this node, or \type {nil} if there is no such node.
3878
3879 \subsubsection{\type {node.prev}}
3880
3881 \startfunctioncall
3882 <node> m = node.prev(<node> n)
3883 \stopfunctioncall
3884
3885 Returns the node preceding this node, or \type {nil} if there is no such node.
3886
3887 \subsubsection{\type {node.current_attr}}
3888
3889 \startfunctioncall
3890 <node> m = node.current_attr()
3891 \stopfunctioncall
3892
3893 Returns the currently active list of attributes, if there is one.
3894
3895 The intended usage of \type {current_attr} is as follows:
3896
3897 \starttyping
3898 local x1 = node.new("glyph")
3899 x1.attr = node.current_attr()
3900 local x2 = node.new("glyph")
3901 x2.attr = node.current_attr()
3902 \stoptyping
3903
3904 or:
3905
3906 \starttyping
3907 local x1 = node.new("glyph")
3908 local x2 = node.new("glyph")
3909 local ca = node.current_attr()
3910 x1.attr = ca
3911 x2.attr = ca
3912 \stoptyping
3913
3914 The attribute lists are ref counted and the assignment takes care of incrementing
3915 the refcount. You cannot expect the value \type {ca} to be valid any more when
3916 you assign attributes (using \type {tex.setattribute}) or when control has been
3917 passed back to \TEX.
3918
3919 Note: this function is somewhat experimental, and it returns the {\it actual}
3920 attribute list, not a copy thereof. Therefore, changing any of the attributes in
3921 the list will change these values for all nodes that have the current attribute
3922 list assigned to them.
3923
3924 \subsubsection{\type {node.hpack}}
3925
3926 \startfunctioncall
3927 <node> h, <number> b = node.hpack(<node> n)
3928 <node> h, <number> b = node.hpack(<node> n, <number> w, <string> info)
3929 <node> h, <number> b = node.hpack(<node> n, <number> w, <string> info, <string> dir)
3930 \stopfunctioncall
3931
3932 This function creates a new hlist by packaging the list that begins at node \type
3933 {n} into a horizontal box. With only a single argument, this box is created using
3934 the natural width of its components. In the three argument form, \type {info}
3935 must be either \type {additional} or \type {exactly}, and \type {w} is the
3936 additional (\type {\hbox spread}) or exact (\type {\hbox to}) width to be used. The
3937 second return value is the badness of the generated box.
3938
3939 Caveat: at this moment, there can be unexpected side|-|effects to this function,
3940 like updating some of the \type {\marks} and \type {\inserts}. Also note that the
3941 content of \type {h} is the original node list \type {n}: if you call \type
3942 {node.free(h)} you will also free the node list itself, unless you explicitly set
3943 the \type {list} field to \type {nil} beforehand. And in a similar way, calling
3944 \type {node.free(n)} will invalidate \type {h} as well!
3945
3946 \subsubsection{\type {node.vpack}}
3947
3948 \startfunctioncall
3949 <node> h, <number> b = node.vpack(<node> n)
3950 <node> h, <number> b = node.vpack(<node> n, <number> w, <string> info)
3951 <node> h, <number> b = node.vpack(<node> n, <number> w, <string> info, <string> dir)
3952 \stopfunctioncall
3953
3954 This function creates a new vlist by packaging the list that begins at node \type
3955 {n} into a vertical box. With only a single argument, this box is created using
3956 the natural height of its components. In the three argument form, \type {info}
3957 must be either \type {additional} or \type {exactly}, and \type {w} is the
3958 additional (\type {\vbox spread}) or exact (\type {\vbox to}) height to be used.
3959
3960 The second return value is the badness of the generated box.
3961
3962 See the description of \type {node.hpack()} for a few memory allocation caveats.
3963
3964 \subsubsection{\type {node.dimensions}}
3965
3966 \startfunctioncall
3967 <number> w, <number> h, <number> d  = node.dimensions(<node> n)
3968 <number> w, <number> h, <number> d  = node.dimensions(<node> n, <string> dir)
3969 <number> w, <number> h, <number> d  = node.dimensions(<node> n, <node> t)
3970 <number> w, <number> h, <number> d  = node.dimensions(<node> n, <node> t, <string> dir)
3971 \stopfunctioncall
3972
3973 This function calculates the natural in-line dimensions of the node list starting
3974 at node \type {n} and terminating just before node \type {t} (or the end of the
3975 list, if there is no second argument). The return values are scaled points. An
3976 alternative format that starts with glue parameters as the first three arguments
3977 is also possible:
3978
3979 \startfunctioncall
3980 <number> w, <number> h, <number> d  =
3981   node.dimensions(<number> glue_set, <number> glue_sign,
3982                  <number> glue_order, <node> n)
3983 <number> w, <number> h, <number> d  =
3984   node.dimensions(<number> glue_set, <number> glue_sign,
3985                  <number> glue_order, <node> n, <string> dir)
3986 <number> w, <number> h, <number> d  =
3987   node.dimensions(<number> glue_set, <number> glue_sign,
3988                  <number> glue_order, <node> n, <node> t)
3989 <number> w, <number> h, <number> d  =
3990   node.dimensions(<number> glue_set, <number> glue_sign,
3991                  <number> glue_order, <node> n, <node> t, <string> dir)
3992 \stopfunctioncall
3993
3994 This calling method takes glue settings into account and is especially useful for
3995 finding the actual width of a sublist of nodes that are already boxed, for
3996 example in code like this, which prints the width of the space in between the
3997 \type {a} and \type {b} as it would be if \type {\box0} was used as-is:
3998
3999 \starttyping
4000 \setbox0 = \hbox to 20pt {a b}
4001
4002 \directlua{print (node.dimensions(
4003     tex.box[0].glue_set,
4004     tex.box[0].glue_sign,
4005     tex.box[0].glue_order,
4006     tex.box[0].head.next,
4007     node.tail(tex.box[0].head)
4008 )) }
4009 \stoptyping
4010
4011 \subsubsection{\type {node.mlist_to_hlist}}
4012
4013 \startfunctioncall
4014 <node> h = node.mlist_to_hlist(<node> n,
4015              <string> display_type, <boolean> penalties)
4016 \stopfunctioncall
4017
4018 This runs the internal mlist to hlist conversion, converting the math list in
4019 \type {n} into the horizontal list \type {h}. The interface is exactly the same
4020 as for the callback \type {mlist_to_hlist}.
4021
4022 \subsubsection{\type {node.slide}}
4023
4024 \startfunctioncall
4025 <node> m = node.slide(<node> n)
4026 \stopfunctioncall
4027
4028 Returns the last node of the node list that starts at \type {n}. As a
4029 side|-|effect, it also creates a reverse chain of \type {prev} pointers between
4030 nodes.
4031
4032 \subsubsection{\type {node.tail}}
4033
4034 \startfunctioncall
4035 <node> m = node.tail(<node> n)
4036 \stopfunctioncall
4037
4038 Returns the last node of the node list that starts at \type {n}.
4039
4040 \subsubsection{\type {node.length}}
4041
4042 \startfunctioncall
4043 <number> i = node.length(<node> n)
4044 <number> i = node.length(<node> n, <node> m)
4045 \stopfunctioncall
4046
4047 Returns the number of nodes contained in the node list that starts at \type {n}.
4048 If \type {m} is also supplied it stops at \type {m} instead of at the end of the
4049 list. The node \type {m} is not counted.
4050
4051 \subsubsection{\type {node.count}}
4052
4053 \startfunctioncall
4054 <number> i = node.count(<number> id, <node> n)
4055 <number> i = node.count(<number> id, <node> n, <node> m)
4056 \stopfunctioncall
4057
4058 Returns the number of nodes contained in the node list that starts at \type {n}
4059 that have a matching \type {id} field. If \type {m} is also supplied, counting
4060 stops at \type {m} instead of at the end of the list. The node \type {m} is not
4061 counted.
4062
4063 This function also accept string \type {id}'s.
4064
4065 \subsubsection{\type {node.traverse}}
4066
4067 \startfunctioncall
4068 <node> t = node.traverse(<node> n)
4069 \stopfunctioncall
4070
4071 This is a \LUA\ iterator that loops over the node list that starts at \type {n}.
4072 Typically code looks like this:
4073
4074 \starttyping
4075 for n in node.traverse(head) do
4076    ...
4077 end
4078 \stoptyping
4079
4080 is functionally equivalent to:
4081
4082 \starttyping
4083 do
4084   local n
4085   local function f (head,var)
4086     local t
4087     if var == nil then
4088        t = head
4089     else
4090        t = var.next
4091     end
4092     return t
4093   end
4094   while true do
4095     n = f (head, n)
4096     if n == nil then break end
4097     ...
4098   end
4099 end
4100 \stoptyping
4101
4102 It should be clear from the definition of the function \type {f} that even though
4103 it is possible to add or remove nodes from the node list while traversing, you
4104 have to take great care to make sure all the \type {next} (and \type {prev})
4105 pointers remain valid.
4106
4107 If the above is unclear to you, see the section \quote {For Statement} in the
4108 \LUA\ Reference Manual.
4109
4110 \subsubsection{\type {node.traverse_id}}
4111
4112 \startfunctioncall
4113 <node> t = node.traverse_id(<number> id, <node> n)
4114 \stopfunctioncall
4115
4116 This is an iterator that loops over all the nodes in the list that starts at
4117 \type {n} that have a matching \type {id} field.
4118
4119 See the previous section for details. The change is in the local function \type
4120 {f}, which now does an extra while loop checking against the upvalue \type {id}:
4121
4122 \starttyping
4123  local function f(head,var)
4124    local t
4125    if var == nil then
4126       t = head
4127    else
4128       t = var.next
4129    end
4130    while not t.id == id do
4131       t = t.next
4132    end
4133    return t
4134  end
4135 \stoptyping
4136
4137 \subsubsection{\type {node.end_of_math}}
4138
4139 \startfunctioncall
4140 <node> t = node.end_of_math(<node> start)
4141 \stopfunctioncall
4142
4143 Looks for and returns the next \type {math_node} following the \type {start}. If
4144 the given node is a math endnode this helper return that node, else it follows
4145 the list and return the next math endnote. If no such node is found nil is
4146 returned.
4147
4148 \subsubsection{\type {node.remove}}
4149
4150 \startfunctioncall
4151 <node> head, current = node.remove(<node> head, <node> current)
4152 \stopfunctioncall
4153
4154 This function removes the node \type {current} from the list following \type
4155 {head}. It is your responsibility to make sure it is really part of that list.
4156 The return values are the new \type {head} and \type {current} nodes. The
4157 returned \type {current} is the node following the \type {current} in the calling
4158 argument, and is only passed back as a convenience (or \type {nil}, if there is
4159 no such node). The returned \type {head} is more important, because if the
4160 function is called with \type {current} equal to \type {head}, it will be
4161 changed.
4162
4163 \subsubsection{\type {node.insert_before}}
4164
4165 \startfunctioncall
4166 <node> head, new = node.insert_before(<node> head, <node> current, <node> new)
4167 \stopfunctioncall
4168
4169 This function inserts the node \type {new} before \type {current} into the list
4170 following \type {head}. It is your responsibility to make sure that \type
4171 {current} is really part of that list. The return values are the (potentially
4172 mutated) \type {head} and the node \type {new}, set up to be part of the list
4173 (with correct \type {next} field). If \type {head} is initially \type {nil}, it
4174 will become \type {new}.
4175
4176 \subsubsection{\type {node.insert_after}}
4177
4178 \startfunctioncall
4179 <node> head, new = node.insert_after(<node> head, <node> current, <node> new)
4180 \stopfunctioncall
4181
4182 This function inserts the node \type {new} after \type {current} into the list
4183 following \type {head}. It is your responsibility to make sure that \type
4184 {current} is really part of that list. The return values are the \type {head} and
4185 the node \type {new}, set up to be part of the list (with correct \type {next}
4186 field). If \type {head} is initially \type {nil}, it will become \type {new}.
4187
4188 \subsubsection{\type {node.first_glyph}}
4189
4190 \startfunctioncall
4191 <node> n = node.first_glyph(<node> n)
4192 <node> n = node.first_glyph(<node> n, <node> m)
4193 \stopfunctioncall
4194
4195 Returns the first node in the list starting at \type {n} that is a glyph node
4196 with a subtype indicating it is a glyph, or \type {nil}. If \type {m} is given,
4197 processing stops at (but including) that node, otherwise processing stops at the
4198 end of the list.
4199
4200 \subsubsection{\type {node.ligaturing}}
4201
4202 \startfunctioncall
4203 <node> h, <node> t, <boolean> success = node.ligaturing(<node> n)
4204 <node> h, <node> t, <boolean> success = node.ligaturing(<node> n, <node> m)
4205 \stopfunctioncall
4206
4207 Apply \TEX-style ligaturing to the specified nodelist. The tail node \type {m} is
4208 optional. The two returned nodes \type {h} and \type {t} are the new head and
4209 tail (both \type {n} and \type {m} can change into a new ligature).
4210
4211 \subsubsection{\type {node.kerning}}
4212
4213 \startfunctioncall
4214 <node> h, <node> t, <boolean> success = node.kerning(<node> n)
4215 <node> h, <node> t, <boolean> success = node.kerning(<node> n, <node> m)
4216 \stopfunctioncall
4217
4218 Apply \TEX|-|style kerning to the specified node list. The tail node \type {m} is
4219 optional. The two returned nodes \type {h} and \type {t} are the head and tail
4220 (either one of these can be an inserted kern node, because special kernings with
4221 word boundaries are possible).
4222
4223 \subsubsection{\type {node.unprotect_glyphs}}
4224
4225 \startfunctioncall
4226 node.unprotect_glyphs(<node> n)
4227 \stopfunctioncall
4228
4229 Subtracts 256 from all glyph node subtypes. This and the next function are
4230 helpers to convert from \type {characters} to \type {glyphs} during node
4231 processing.
4232
4233 \subsubsection{\type {node.protect_glyphs}}
4234
4235 \startfunctioncall
4236 node.protect_glyphs(<node> n)
4237 \stopfunctioncall
4238
4239 Adds 256 to all glyph node subtypes in the node list starting at \type {n},
4240 except that if the value is 1, it adds only 255. The special handling of 1 means
4241 that \type {characters} will become \type {glyphs} after subtraction of 256.
4242
4243 \subsubsection{\type {node.last_node}}
4244
4245 \startfunctioncall
4246 <node> n = node.last_node()
4247 \stopfunctioncall
4248
4249 This function pops the last node from \TEX's \quote{current list}. It returns
4250 that node, or \type {nil} if the current list is empty.
4251
4252 \subsubsection{\type {node.write}}
4253
4254 \startfunctioncall
4255 node.write(<node> n)
4256 \stopfunctioncall
4257
4258 This is an experimental function that will append a node list to \TEX's \quote
4259 {current list} The node list is not deep|-|copied! There is no error checking
4260 either!
4261
4262 \subsubsection{\type {node.protrusion_skippable}}
4263
4264 \startfunctioncall
4265 <boolean> skippable = node.protrusion_skippable(<node> n)
4266 \stopfunctioncall
4267
4268 Returns \type {true} if, for the purpose of line boundary discovery when
4269 character protrusion is active, this node can be skipped.
4270
4271 \subsection{Glue handling}
4272
4273 \subsubsection{\type {node.setglue}}
4274
4275 You can set the properties of a glue in one go. If you pass no values, the glue
4276 will become a zero glue.
4277
4278 \startfunctioncall
4279 node.setglue(<node> n)
4280 node.setglue(<node> n,width,stretch,shrink,stretch_order,shrink_order)
4281 \stopfunctioncall
4282
4283 When you pass values, only arguments that are numbers
4284 are assigned so
4285
4286 \starttyping
4287 node.setglue(n,655360,false,65536)
4288 \stoptyping
4289
4290 will only adapt the width and shrink.
4291
4292 \subsubsection{\type {node.getglue}}
4293
4294 The next call will return 5 values (or northing when no glue is passed).
4295
4296 \startfunctioncall
4297 <integer> width, <integer> stretch, <integer> shrink, <integer> stretch_order,
4298     <integer> shrink_order = node.getglue(<node> n)
4299 \stopfunctioncall
4300
4301 \subsubsection{\type {node.is_zero_glue}}
4302
4303 This function returns \type {true} when the width, stretch and shrink properties
4304 are zero.
4305
4306 \startfunctioncall
4307 <boolean> isglue = node.is_zero_glue(<node> n)
4308 \stopfunctioncall
4309
4310 \subsection{Attribute handling}
4311
4312 Attributes appear as linked list of userdata objects in the \type {attr} field of
4313 individual nodes. They can be handled individually, but it is much safer and more
4314 efficient to use the dedicated functions associated with them.
4315
4316 \subsubsection{\type {node.has_attribute}}
4317
4318 \startfunctioncall
4319 <number> v = node.has_attribute(<node> n, <number> id)
4320 <number> v = node.has_attribute(<node> n, <number> id, <number> val)
4321 \stopfunctioncall
4322
4323 Tests if a node has the attribute with number \type {id} set. If \type {val} is
4324 also supplied, also tests if the value matches \type {val}. It returns the value,
4325 or, if no match is found, \type {nil}.
4326
4327 \subsubsection{\type {node.set_attribute}}
4328
4329 \startfunctioncall
4330 node.set_attribute(<node> n, <number> id, <number> val)
4331 \stopfunctioncall
4332
4333 Sets the attribute with number \type {id} to the value \type {val}. Duplicate
4334 assignments are ignored. {\em [needs explanation]}
4335
4336 \subsubsection{\type {node.unset_attribute}}
4337
4338 \startfunctioncall
4339 <number> v = node.unset_attribute(<node> n, <number> id)
4340 <number> v = node.unset_attribute(<node> n, <number> id, <number> val)
4341 \stopfunctioncall
4342
4343 Unsets the attribute with number \type {id}. If \type {val} is also supplied, it
4344 will only perform this operation if the value matches \type {val}. Missing
4345 attributes or attribute|-|value pairs are ignored.
4346
4347 If the attribute was actually deleted, returns its old value. Otherwise, returns
4348 \type {nil}.
4349
4350 \section{The \type {pdf} library}
4351
4352 This contains variables and functions that are related to the \PDF\ backend.
4353
4354 \subsection{\type {pdf.mapfile}, \type {pdf.mapline}}
4355
4356 \startfunctioncall
4357 pdf.mapfile(<string> map file)
4358 pdf.mapline(<string> map line)
4359 \stopfunctioncall
4360
4361 These two functions can be used to replace primitives \type {\pdfmapfile} and
4362 \type {\pdfmapline} from \PDFTEX. They expect a string as only parameter and have
4363 no return value.
4364
4365 The also functions replace the former variables \type {pdf.pdfmapfile} and
4366 \type {pdf.pdfmapline}.
4367
4368 \subsection{\type {pdf.catalog}, \type {pdf.info},\type {pdf.names},
4369     \type {pdf.trailer}}
4370
4371 These variables offer a read|-|write interface to the corresponding \PDFTEX\
4372 token lists. The value types are strings and they are written out to the \PDF\
4373 file directly after the \PDFTEX\ token registers.
4374
4375 The preferred interface is now \type {pdf.setcatalog}, \type {pdf.setinfo}
4376 \type {pdf.setnames} and \type {pdf.settrailer} for setting these properties
4377 and \type {pdf.getcatalog}, \type {pdf.getinfo} \type {pdf.getnames} and
4378 \type {pdf.gettrailer} for querying them,
4379
4380 The corresponding \quote {\type {pdf}} parameter names \type {pdf.pdfcatalog},
4381 \type {pdf.pdfinfo}, \type {pdf.pdfnames}, and \type {pdf.pdftrailer} are
4382 not available.
4383
4384 \subsection{\type {pdf.<set/get>pageattributes}, \type {pdf.<set/get>pageresources},
4385     \type {pdf.<set/get>pagesattributes}}
4386
4387 These variables offer a read|-|write interface to related token lists. The value
4388 types are strings. The variables have no interaction with the corresponding
4389 \PDFTEX\ token registers \type {\pdfpageattr}, \type {\pdfpageresources}, and \type
4390 {\pdfpagesattr}. They are written out to the \PDF\ file directly after the
4391 \PDFTEX\ token registers.
4392
4393 The preferred interface is now \type {pdf.setpageattributes}, \type
4394 {pdf.setpagesattributes} and \type {pdf.setpageresources} for setting these
4395 properties and \type {pdf.getpageattributes}, \type {pdf.getpageattributes}
4396 and \type {pdf.getpageresources} for querying them.
4397
4398 \subsection{\type {pdf.<set/get>xformattributes}, \type {pdf.<set/get>xformresources}}
4399
4400 These variables offer a read|-|write interface to related token lists. The value
4401 types are strings. The variables have no interaction with the corresponding
4402 \PDFTEX\ token registers \type {\pdfxformattr} and \type {\pdfxformresources}. They
4403 are written out to the \PDF\ file directly after the \PDFTEX\ token registers.
4404
4405 The preferred interface is now \type {pdf.setxformattributes} and \type
4406 {pdf.setxformattributes} for setting these properties and \type
4407 {pdf.getxformattributes} and \type {pdf.getxformresources} for querying them.
4408
4409 \subsection{\type {pdf.setcompresslevel} and \type {pdf.setobjcompresslevel}}
4410
4411 These two functions set the level of compression. The minimum valu sis~0,
4412 the maximum is~9.
4413
4414 \subsection{\type {pdf.setdecimaldigits} and \type {pdf.getdecimaldigits}}
4415
4416 These two functions set the accuracy of floats written to the \PDF file. You can
4417 set any value but the backend will not go below 3 and above 6.
4418
4419 \subsection{\type {pdf.setpkresolution} and \type {pdf.getpkresolution}}
4420
4421 These setter takes two arguments: the resolution and an optional zero or one that
4422 indicates if this is a fixed one. The getter returns these two values.
4423
4424 \subsection{\type {pdf.lastobj}, \type {pdf.lastlink}, \type {pdf.lastannot},
4425 and \type {pdf.retval}}
4426
4427 These status variables are similar to the ones traditionally used at the \TEX\
4428 end.
4429
4430 \subsection{\type {pdf.setorigin}, \type {pdf.getorigin}}
4431
4432 This one is used to set the horizonal and/or vertical offset (a traditional
4433 backend property).
4434
4435 \starttyping
4436 pdf.setorigin() -- sets both to 0pt
4437 pdf.setorigin(tex.sp("1in")) -- sets both to 1in
4438 pdf.setorigin(tex.sp("1in"),tex.sp("1in"))
4439 \stoptyping
4440
4441 The counterpart of this function returns two values.
4442
4443 \subsection{\type {pdf.setlinkmargin}, \type {pdf.getlinkmargin} \type
4444 {pdf.setdestmargin}, \type {pdf.getdestmargin} \type {pdf.setthreadmargin},
4445 \type {pdf.getthreadmargin} \type {pdf.setxformmargin}, \type
4446 {pdf.getxformmargin}}
4447
4448 These function can be used to set and retrieve the margins that are added to the
4449 natural bounding boxes of the respective objects.
4450
4451 \subsection{\type {pdf.h}, \type {pdf.v}}
4452
4453 These are the \type {h} and \type {v} values that define the current location on
4454 the output page, measured from its lower left corner. The values can be queried
4455 using scaled points as units.
4456
4457 \starttyping
4458 local h = pdf.h
4459 local v = pdf.v
4460 \stoptyping
4461
4462 \subsection{\type {pdf.getpos}, \type {pdf.gethpos}, \type {pdf.getvpos}}
4463
4464 These are the function variants of \type {pdf.h} and \type {pdf.v}. Sometimes
4465 using a function is preferred over a key so this saves wrapping. Also, these
4466 functions are faster then the key based access, as \type {h} and \type {v} keys
4467 are not real variables but looked up using a metatable call. The \type {getpos}
4468 function returns two values, the other return one.
4469
4470 \starttyping
4471 local h, v = pdf.getpos()
4472 \stoptyping
4473
4474 \subsection{\type {pdf.hasmatrix}, \type {pdf.getmatrix}}
4475
4476 The current matrix transformation is available via the \type {getmatrix} command,
4477 which returns 6 values: \type {sx}, \type {rx}, \type {ry}, \type {sy}, \type
4478 {tx}, and \type {ty}. The \type {hasmatrix} function returns \type {true} when a
4479 matrix is applied.
4480
4481 \starttyping
4482 if pdf.hasmatrix() then
4483     local sx, rx, ry, sy, tx, ty = pdf.getmatrix()
4484     -- do something useful or not
4485 end
4486 \stoptyping
4487
4488 \subsection{\type {pdf.print}}
4489
4490 A print function to write stuff to the \PDF\ document that can be used from
4491 within a \type {\latelua} argument. This function is not to be used inside
4492 \type {\directlua} unless you know {\it exactly} what you are doing.
4493
4494 \startfunctioncall
4495 pdf.print(<string> s)
4496 pdf.print(<string> type, <string> s)
4497 \stopfunctioncall
4498
4499 The optional parameter can be used to mimic the behavior of \type {\pdfliteral}:
4500 the \type {type} is \type {direct} or \type {page}.
4501
4502 \subsection{\type {pdf.immediateobj}}
4503
4504 This function creates a \PDF\ object and immediately writes it to the \PDF\ file.
4505 It is modelled after \PDFTEX's \type {\immediate} \type {\pdfobj} primitives. All
4506 function variants return the object number of the newly generated object.
4507
4508 \startfunctioncall
4509 <number> n = pdf.immediateobj(<string> objtext)
4510 <number> n = pdf.immediateobj("file", <string> filename)
4511 <number> n = pdf.immediateobj("stream", <string> streamtext, <string> attrtext)
4512 <number> n = pdf.immediateobj("streamfile", <string> filename, <string> attrtext)
4513 \stopfunctioncall
4514
4515 The first version puts the \type {objtext} raw into an object. Only the object
4516 wrapper is automatically generated, but any internal structure (like \type {<<
4517 >>} dictionary markers) needs to provided by the user. The second version with
4518 keyword \type {"file"} as 1st argument puts the contents of the file with name
4519 \type {filename} raw into the object. The third version with keyword \type
4520 {"stream"} creates a stream object and puts the \type {streamtext} raw into the
4521 stream. The stream length is automatically calculated. The optional \type
4522 {attrtext} goes into the dictionary of that object. The fourth version with
4523 keyword \type {"streamfile"} does the same as the 3rd one, it just reads the
4524 stream data raw from a file.
4525
4526 An optional first argument can be given to make the function use a previously
4527 reserved \PDF\ object.
4528
4529 \startfunctioncall
4530 <number> n = pdf.immediateobj(<integer> n, <string> objtext)
4531 <number> n = pdf.immediateobj(<integer> n, "file", <string> filename)
4532 <number> n = pdf.immediateobj(<integer> n, "stream", <string> streamtext, <string> attrtext)
4533 <number> n = pdf.immediateobj(<integer> n, "streamfile", <string> filename, <string> attrtext)
4534 \stopfunctioncall
4535
4536 \subsection{\type {pdf.obj}}
4537
4538 This function creates a \PDF\ object, which is written to the \PDF\ file only
4539 when referenced, e.g., by \type {pdf.refobj()}.
4540
4541 All function variants return the object number of the newly generated object, and
4542 there are two separate calling modes.
4543
4544 The first mode is modelled after \PDFTEX's \type {\pdfobj} primitive.
4545
4546 \startfunctioncall
4547 <number> n = pdf.obj(<string> objtext)
4548 <number> n = pdf.obj("file", <string> filename)
4549 <number> n = pdf.obj("stream", <string> streamtext, <string> attrtext)
4550 <number> n = pdf.obj("streamfile", <string> filename, <string> attrtext)
4551 \stopfunctioncall
4552
4553 An optional first argument can be given to make the function use a previously
4554 reserved \PDF\ object.
4555
4556 \startfunctioncall
4557 <number> n = pdf.obj(<integer> n, <string> objtext)
4558 <number> n = pdf.obj(<integer> n, "file", <string> filename)
4559 <number> n = pdf.obj(<integer> n, "stream", <string> streamtext, <string> attrtext)
4560 <number> n = pdf.obj(<integer> n, "streamfile", <string> filename, <string> attrtext)
4561 \stopfunctioncall
4562
4563 The second mode accepts a single argument table with key--value pairs.
4564
4565 \startfunctioncall
4566 <number> n = pdf.obj {
4567     type           = <string>,
4568     immmediate     = <boolean>,
4569     objnum         = <number>,
4570     attr           = <string>,
4571     compresslevel  = <number>,
4572     objcompression = <boolean>,
4573     file           = <string>,
4574     string         = <string>
4575 }
4576 \stopfunctioncall
4577
4578 The \type {type} field can have the values \type {raw} and \type {stream}, this
4579 field is required, the others are optional (within constraints).
4580
4581 Note: this mode makes \type {pdf.obj} look more flexible than it actually is: the
4582 constraints from the separate parameter version still apply, so for example you
4583 can't have both \type {string} and \type {file} at the same time.
4584
4585 \subsection{\type {pdf.refobj}}
4586
4587 This function, the \LUA\ version of the \type {\pdfrefobj} primitive, references an
4588 object by its object number, so that the object will be written out.
4589
4590 \startfunctioncall
4591 pdf.refobj(<integer> n)
4592 \stopfunctioncall
4593
4594 This function works in both the \type {\directlua} and \type {\latelua} environment.
4595 Inside \type {\directlua} a new whatsit node \quote {pdf_refobj} is created, which
4596 will be marked for flushing during page output and the object is then written
4597 directly after the page, when also the resources objects are written out. Inside
4598 \type {\latelua} the object will be marked for flushing.
4599
4600 This function has no return values.
4601
4602 \subsection{\type {pdf.reserveobj}}
4603
4604 This function creates an empty \PDF\ object and returns its number.
4605
4606 \startfunctioncall
4607 <number> n = pdf.reserveobj()
4608 <number> n = pdf.reserveobj("annot")
4609 \stopfunctioncall
4610
4611 \subsection{\type {pdf.registerannot}}
4612
4613 This function adds an object number to the \type {/Annots} array for the current
4614 page without doing anything else. This function can only be used from within
4615 \type {\latelua}.
4616
4617 \startfunctioncall
4618 pdf.registerannot (<number> objnum)
4619 \stopfunctioncall
4620
4621 \subsection{\type {pdf.newcolorstack}}
4622
4623 This function allocates a new color stack and returns it's id. The arguments
4624 are the same as for the similar backend extension primitive.
4625
4626 \startfunctioncall
4627 pdf.newcolorstack("0 g","page",true) -- page|direct|origin
4628 \stopfunctioncall
4629
4630 \section{The \type {pdfscanner} library}
4631
4632 The \type {pdfscanner} library allows interpretation of PDF content streams and
4633 \type {/ToUnicode} (cmap) streams. You can get those streams from the \type
4634 {epdf} library, as explained in an earlier section. There is only a single
4635 top|-|level function in this library:
4636
4637 \startfunctioncall
4638 pdfscanner.scan (<Object> stream, <table> operatortable, <table> info)
4639 \stopfunctioncall
4640
4641 The first argument, \type {stream}, should be either a PDF stream object, or a
4642 PDF array of PDF stream objects (those options comprise the possible return
4643 values of \type {<Page>:getContents()} and \type {<Object>:getStream()} in the
4644 \type {epdf} library).
4645
4646 The second argument, \type {operatortable}, should be a Lua table where the keys
4647 are PDF operator name strings and the values are Lua functions (defined by you)
4648 that are used to process those operators. The functions are called whenever the
4649 scanner finds one of these PDF operators in the content stream(s). The functions
4650 are called with two arguments: the \type {scanner} object itself, and the \type
4651 {info} table that was passed are the third argument to \type {pdfscanner.scan}.
4652
4653 Internally, \type {pdfscanner.scan} loops over the PDF operators in the
4654 stream(s), collecting operands on an internal stack until it finds a PDF
4655 operator. If that PDF operator's name exists in \type {operatortable}, then the
4656 associated function is executed. After the function has run (or when there is no
4657 function to execute) the internal operand stack is cleared in preparation for the
4658 next operator, and processing continues.
4659
4660 The \type {scanner} argument to the processing functions is needed because it
4661 offers various methods to get the actual operands from the internal operand
4662 stack.
4663
4664 A simple example of processing a PDF's document stream could look like this:
4665
4666 \starttyping
4667 function Do (scanner, info)
4668    local val       = scanner:pop()
4669    local name      = val[2] -- val[1] == 'name'
4670    local resources = info.resources
4671    local xobject   = resources:lookup("XObject"):getDict():lookup(name)
4672    print (info.space ..'Use XObject '.. name)
4673    if xobject and xobject:isStream() then
4674       local dict = xobject:getStream():getDict()
4675       if dict then
4676         local name = dict:lookup("Subtype")
4677         if name:getName() == "Form" then
4678           local newinfo =  {
4679             space = info.space .. "  " ,
4680             resources = dict:lookup("Resources"):getDict()
4681           }
4682           pdfscanner.scan(xobject, operatortable, newinfo)
4683         end
4684       end
4685    end
4686 end
4687
4688 operatortable = { Do = Do }
4689
4690 doc      = epdf.open(arg[1])
4691 pagenum  = 1
4692
4693 while pagenum <= doc:getNumPages() do
4694    local page = doc:getCatalog():getPage(pagenum)
4695    local info = {
4696      space     = "  " ,
4697      resources = page:getResourceDict()
4698    }
4699    print('Page ' .. pagenum)
4700    pdfscanner.scan(page:getContents(), operatortable, info)
4701    pagenum = pagenum + 1
4702 end
4703 \stoptyping
4704
4705 This example iterates over all the actual content in the PDF, and prints out the
4706 found XObject names. While the code demonstrates quite some of the \type {epdf}
4707 functions, let's focus on the type \type {pdfscanner} specific code instead.
4708
4709 From the bottom up, the line
4710
4711 \starttyping
4712    pdfscanner.scan(page:getContents(), operatortable, info)
4713 \stoptyping
4714
4715 runs the scanner with the PDF page's top-level content.
4716
4717 The third argument, \type {info}, contains two entries: \type {space} is used to
4718 indent the printed output, and \type {resources} is needed so that embedded \type
4719 {XForms} can find their own content.
4720
4721 The second argument, \type {operatortable} defines a processing function for a
4722 single PDF operator, \type {Do}.
4723
4724 The function \type {Do} prints the name of the current XObject, and then starts a
4725 new scanner for that object's content stream, under the condition that the
4726 XObject is in fact a \type {/Form}. That nested scanner is called with new \type
4727 {info} argument with an updated \type {space} value so that the indentation of
4728 the output nicely nests, and with an new \type {resources} field to help the next
4729 iteration down to properly process any other, embedded XObjects.
4730
4731 Of course, this is not a very useful example in practise, but for the purpose of
4732 demonstrating \type {pdfscanner}, it is just long enough. It makes use of only
4733 one \type {scanner} method: \type {scanner:pop()}. That function pops the top
4734 operand of the internal stack, and returns a \LUA\ table where the object at index
4735 one is a string representing the type of the operand, and object two is its
4736 value.
4737
4738 The list of possible operand types and associated \LUA\ value types is:
4739
4740 \starttabulate[|lT|p|]
4741 \NC integer  \NC <number>  \NC \NR
4742 \NC real     \NC <number>  \NC \NR
4743 \NC boolean  \NC <boolean> \NC \NR
4744 \NC name     \NC <string>  \NC \NR
4745 \NC operator \NC <string>  \NC \NR
4746 \NC string   \NC <string>  \NC \NR
4747 \NC array    \NC <table>   \NC \NR
4748 \NC dict     \NC <table>   \NC \NR
4749 \stoptabulate
4750
4751 In case of \type {integer} or \type {real}, the value is always a \LUA\ (floating
4752 point) number.
4753
4754 In case of \type {name}, the leading slash is always stripped.
4755
4756 In case of \type {string}, please bear in mind that PDF actually supports
4757 different types of strings (with different encodings) in different parts of the
4758 PDF document, so may need to reencode some of the results; \type {pdfscanner}
4759 always outputs the byte stream without reencoding anything. \type {pdfscanner}
4760 does not differentiate between literal strings and hexadecimal strings (the
4761 hexadecimal values are decoded), and it treats the stream data for inline images
4762 as a string that is the single operand for \type {EI}.
4763
4764 In case of \type {array}, the table content is a list of \type {pop} return
4765 values.
4766
4767 In case of \type {dict}, the table keys are PDF name strings and the values are
4768 \type {pop} return values.
4769
4770 \blank
4771
4772 There are few more methods defined that you can ask \type {scanner}:
4773
4774 \starttabulate[|lT|p|]
4775 \NC pop       \NC as explained above \NC \NR
4776 \NC popNumber \NC return only the value of a \type {real} or \type {integer} \NC \NR
4777 \NC popName   \NC return only the value of a \type {name} \NC \NR
4778 \NC popString \NC return only the value of a \type {string} \NC \NR
4779 \NC popArray  \NC return only the value of a \type {array} \NC \NR
4780 \NC popDict   \NC return only the value of a \type {dict} \NC \NR
4781 \NC popBool   \NC return only the value of a \type {boolean} \NC \NR
4782 \NC done      \NC abort further processing of this \type {scan()} call \NC \NR
4783 \stoptabulate
4784
4785 The \type {popXXX} are convenience functions, and come in handy when you know the
4786 type of the operands beforehand (which you usually do, in PDF). For example, the
4787 \type {Do} function could have used \type {local name = scanner:popName()}
4788 instead, because the single operand to the \type {Do} operator is always a PDF
4789 name object.
4790
4791 The \type {done} function allows you to abort processing of a stream once you
4792 have learned everything you want to learn. This comes in handy while parsing
4793 \type {/ToUnicode}, because there usually is trailing garbage that you are not
4794 interested in. Without \type {done}, processing only end at the end of the
4795 stream, possibly wasting CPU cycles.
4796
4797 \section{The \type {status} library}
4798
4799 This contains a number of run|-|time configuration items that you may find useful
4800 in message reporting, as well as an iterator function that gets all of the names
4801 and values as a table.
4802
4803 \startfunctioncall
4804 <table> info = status.list()
4805 \stopfunctioncall
4806
4807 The keys in the table are the known items, the value is the current value. Almost
4808 all of the values in \type {status} are fetched through a metatable at run|-|time
4809 whenever they are accessed, so you cannot use \type {pairs} on \type {status},
4810 but you {\it can\/} use \type {pairs} on \type {info}, of course. If you do not
4811 need the full list, you can also ask for a single item by using its name as an
4812 index into \type {status}.
4813
4814 The current list is:
4815
4816 \starttabulate[|lT|p|]
4817 \NC \ssbf key          \NC \bf explanation \NC \NR
4818 \NC pdf_gone           \NC written \PDF\ bytes \NC \NR
4819 \NC pdf_ptr            \NC not yet written \PDF\ bytes \NC \NR
4820 \NC dvi_gone           \NC written \DVI\ bytes \NC \NR
4821 \NC dvi_ptr            \NC not yet written \DVI\ bytes \NC \NR
4822 \NC total_pages        \NC number of written pages \NC \NR
4823 \NC output_file_name   \NC name of the \PDF\ or \DVI\ file \NC \NR
4824 \NC log_name           \NC name of the log file \NC \NR
4825 \NC banner             \NC terminal display banner \NC \NR
4826 \NC var_used           \NC variable (one|-|word) memory in use \NC \NR
4827 \NC dyn_used           \NC token (multi|-|word) memory in use  \NC \NR
4828 \NC str_ptr            \NC number of strings \NC \NR
4829 \NC init_str_ptr       \NC number of \INITEX\ strings \NC \NR
4830 \NC max_strings        \NC maximum allowed strings \NC \NR
4831 \NC pool_ptr           \NC string pool index \NC \NR
4832 \NC init_pool_ptr      \NC \INITEX\ string pool index \NC \NR
4833 \NC pool_size          \NC current size allocated for string characters \NC \NR
4834 \NC node_mem_usage     \NC a string giving insight into currently used nodes \NC \NR
4835 \NC var_mem_max        \NC number of allocated words for nodes \NC \NR
4836 \NC fix_mem_max        \NC number of allocated words for tokens \NC \NR
4837 \NC fix_mem_end        \NC maximum number of used tokens \NC \NR
4838 \NC cs_count           \NC number of control sequences \NC \NR
4839 \NC hash_size          \NC size of hash \NC \NR
4840 \NC hash_extra         \NC extra allowed hash \NC \NR
4841 \NC font_ptr           \NC number of active fonts \NC \NR
4842 \NC input_ptr          \NC th elevel of input we're at \NC \NR
4843 \NC max_in_stack       \NC max used input stack entries \NC \NR
4844 \NC max_nest_stack     \NC max used nesting stack entries \NC \NR
4845 \NC max_param_stack    \NC max used parameter stack entries \NC \NR
4846 \NC max_buf_stack      \NC max used buffer position \NC \NR
4847 \NC max_save_stack     \NC max used save stack entries \NC \NR
4848 \NC stack_size         \NC input stack size \NC \NR
4849 \NC nest_size          \NC nesting stack size \NC \NR
4850 \NC param_size         \NC parameter stack size \NC \NR
4851 \NC buf_size           \NC current allocated size of the line buffer \NC \NR
4852 \NC save_size          \NC save stack size \NC \NR
4853 \NC obj_ptr            \NC max \PDF\ object pointer \NC \NR
4854 \NC obj_tab_size       \NC \PDF\ object table size \NC \NR
4855 \NC pdf_os_cntr        \NC max \PDF\ object stream pointer \NC \NR
4856 \NC pdf_os_objidx      \NC \PDF\ object stream index \NC \NR
4857 \NC pdf_dest_names_ptr \NC max \PDF\ destination pointer \NC \NR
4858 \NC dest_names_size    \NC \PDF\ destination table size \NC \NR
4859 \NC pdf_mem_ptr        \NC max \PDF\ memory used \NC \NR
4860 \NC pdf_mem_size       \NC \PDF\ memory size \NC \NR
4861 \NC largest_used_mark  \NC max referenced marks class \NC \NR
4862 \NC filename           \NC name of the current input file \NC \NR
4863 \NC inputid            \NC numeric id of the current input \NC \NR
4864 \NC linenumber         \NC location in the current input file \NC \NR
4865 \NC lasterrorstring    \NC last \TEX\ error string \NC \NR
4866 \NC lastluaerrorstring \NC last \LUA\ error string \NC \NR
4867 \NC lastwarningtag     \NC last warning string\NC \NR
4868 \NC lastwarningstring  \NC last warning tag, normally an indication of in what part\NC \NR
4869 \NC lasterrorcontext   \NC last error context string (with newlines) \NC \NR
4870 \NC luabytecodes       \NC number of active \LUA\ bytecode registers \NC \NR
4871 \NC luabytecode_bytes  \NC number of bytes in \LUA\ bytecode registers \NC \NR
4872 \NC luastate_bytes     \NC number of bytes in use by \LUA\ interpreters \NC \NR
4873 \NC output_active      \NC \type {true} if the \type {\output} routine is active \NC \NR
4874 \NC callbacks          \NC total number of executed callbacks so far \NC \NR
4875 \NC indirect_callbacks \NC number of those that were themselves
4876                            a result of other callbacks (e.g. file readers) \NC \NR
4877 \NC luatex_version     \NC the \LUATEX\ version number \NC \NR
4878 \NC luatex_revision    \NC the \LUATEX\ revision string \NC \NR
4879 \NC ini_version        \NC \type {true} if this is an \INITEX\ run \NC \NR
4880 \NC shell_escape       \NC \type {0} means disabled, \type {1} is restricted and
4881                            \type {2} means anything is permitted \NC \NR
4882 \stoptabulate
4883
4884 The error and warning messages can be wiped with the \type {resetmessages}
4885 function.
4886
4887 \section{The \type {tex} library}
4888
4889 The \type {tex} table contains a large list of virtual internal \TEX\
4890 parameters that are partially writable.
4891
4892 The designation \quote {virtual} means that these items are not properly defined
4893 in \LUA, but are only front\-ends that are handled by a metatable that operates
4894 on the actual \TEX\ values. As a result, most of the \LUA\ table operators (like
4895 \type {pairs} and \type {#}) do not work on such items.
4896
4897 At the moment, it is possible to access almost every parameter that has these
4898 characteristics:
4899
4900 \startitemize[packed]
4901 \item You can use it after \type {\the}
4902 \item It is a single token.
4903 \item Some special others, see the list below
4904 \stopitemize
4905
4906 This excludes parameters that need extra arguments, like \type {\the\scriptfont}.
4907
4908 The subset comprising simple integer and dimension registers are
4909 writable as well as readable (stuff like \type {\tracingcommands} and
4910 \type {\parindent}).
4911
4912 \subsection{Internal parameter values}
4913
4914 For all the parameters in this section, it is possible to access them directly
4915 using their names as index in the \type {tex} table, or by using one of the
4916 functions \type {tex.get} and \type {tex.set}. If you created aliasses,
4917 you can use accessors like \type {tex.getdimen} as these also understand
4918 names of built|-|in variables.
4919
4920 The exact parameters and return values differ depending on the actual parameter,
4921 and so does whether \type {tex.set} has any effect. For the parameters that {\it
4922 can\/} be set, it is possible to use \type {global} as the first argument to
4923 \type {tex.set}; this makes the assignment global instead of local.
4924
4925 \startfunctioncall
4926 tex.set (<string> n, ...)
4927 tex.set ("global", <string> n, ...)
4928 ... = tex.get (<string> n)
4929 \stopfunctioncall
4930
4931 There are also dedicated setters, getters and checkers:
4932
4933 \startfunctioncall
4934 local d = tex.getdimen("foo")
4935 if tex.isdimen("bar") then
4936     tex.setdimen("bar",d)
4937 end
4938 \stopfunctioncall
4939
4940 There are such helpers for \type {dimen}, \type {count}, \type {skip}, \type
4941 {box} and \type {attribute} registers.
4942
4943 \subsubsection{Integer parameters}
4944
4945 The integer parameters accept and return \LUA\ numbers.
4946
4947 Read|-|write:
4948
4949 \starttwocolumns
4950 \starttyping
4951 tex.adjdemerits
4952 tex.binoppenalty
4953 tex.brokenpenalty
4954 tex.catcodetable
4955 tex.clubpenalty
4956 tex.day
4957 tex.defaulthyphenchar
4958 tex.defaultskewchar
4959 tex.delimiterfactor
4960 tex.displaywidowpenalty
4961 tex.doublehyphendemerits
4962 tex.endlinechar
4963 tex.errorcontextlines
4964 tex.escapechar
4965 tex.exhyphenpenalty
4966 tex.fam
4967 tex.finalhyphendemerits
4968 tex.floatingpenalty
4969 tex.globaldefs
4970 tex.hangafter
4971 tex.hbadness
4972 tex.holdinginserts
4973 tex.hyphenpenalty
4974 tex.interlinepenalty
4975 tex.language
4976 tex.lastlinefit
4977 tex.lefthyphenmin
4978 tex.linepenalty
4979 tex.localbrokenpenalty
4980 tex.localinterlinepenalty
4981 tex.looseness
4982 tex.mag
4983 tex.maxdeadcycles
4984 tex.month
4985 tex.newlinechar
4986 tex.outputpenalty
4987 tex.pausing
4988 tex.postdisplaypenalty
4989 tex.predisplaydirection
4990 tex.predisplaypenalty
4991 tex.pretolerance
4992 tex.relpenalty
4993 tex.righthyphenmin
4994 tex.savinghyphcodes
4995 tex.savingvdiscards
4996 tex.showboxbreadth
4997 tex.showboxdepth
4998 tex.time
4999 tex.tolerance
5000 tex.tracingassigns
5001 tex.tracingcommands
5002 tex.tracinggroups
5003 tex.tracingifs
5004 tex.tracinglostchars
5005 tex.tracingmacros
5006 tex.tracingnesting
5007 tex.tracingonline
5008 tex.tracingoutput
5009 tex.tracingpages
5010 tex.tracingparagraphs
5011 tex.tracingrestores
5012 tex.tracingscantokens
5013 tex.tracingstats
5014 tex.uchyph
5015 tex.vbadness
5016 tex.widowpenalty
5017 tex.year
5018 \stoptyping
5019 \stoptwocolumns
5020
5021 Read|-|only:
5022
5023 \startthreecolumns
5024 \starttyping
5025 tex.deadcycles
5026 tex.insertpenalties
5027 tex.parshape
5028 tex.prevgraf
5029 tex.spacefactor
5030 \stoptyping
5031 \stopthreecolumns
5032
5033 \subsubsection{Dimension parameters}
5034
5035 The dimension parameters accept \LUA\ numbers (signifying scaled points) or
5036 strings (with included dimension). The result is always a number in scaled
5037 points.
5038
5039 Read|-|write:
5040
5041 \startthreecolumns
5042 \starttyping
5043 tex.boxmaxdepth
5044 tex.delimitershortfall
5045 tex.displayindent
5046 tex.displaywidth
5047 tex.emergencystretch
5048 tex.hangindent
5049 tex.hfuzz
5050 tex.hoffset
5051 tex.hsize
5052 tex.lineskiplimit
5053 tex.mathsurround
5054 tex.maxdepth
5055 tex.nulldelimiterspace
5056 tex.overfullrule
5057 tex.pagebottomoffset
5058 tex.pageheight
5059 tex.pageleftoffset
5060 tex.pagerightoffset
5061 tex.pagetopoffset
5062 tex.pagewidth
5063 tex.parindent
5064 tex.predisplaysize
5065 tex.scriptspace
5066 tex.splitmaxdepth
5067 tex.vfuzz
5068 tex.voffset
5069 tex.vsize
5070 tex.prevdepth
5071 tex.prevgraf
5072 tex.spacefactor
5073 \stoptyping
5074 \stopthreecolumns
5075
5076 Read|-|only:
5077
5078 \startthreecolumns
5079 \starttyping
5080 tex.pagedepth
5081 tex.pagefilllstretch
5082 tex.pagefillstretch
5083 tex.pagefilstretch
5084 tex.pagegoal
5085 tex.pageshrink
5086 tex.pagestretch
5087 tex.pagetotal
5088 \stoptyping
5089 \stopthreecolumns
5090
5091 Beware: as with all \LUA\ tables you can add values to them. So, the following is valid:
5092
5093 \starttyping
5094 tex.foo = 123
5095 \stoptyping
5096
5097 When you access a \TEX\ parameter a look up takes place. For read||only variables
5098 that means that you will get something back, but when you set them you create a
5099 new entry in the table thereby making the original invisible.
5100
5101 There are a few special cases that we make an exception for: \type {prevdepth},
5102 \type {prevgraf} and \type {spacefactor}. These normally are accessed via the
5103 \type {tex.nest} table:
5104
5105 \starttyping
5106 tex.nest[tex.nest.ptr].prevdepth   = p
5107 tex.nest[tex.nest.ptr].spacefactor = s
5108 \stoptyping
5109
5110 However, the following also works:
5111
5112 \starttyping
5113 tex.prevdepth   = p
5114 tex.spacefactor = s
5115 \stoptyping
5116
5117 Keep in mind that when you mess with node lists directly at the \LUA\ end you
5118 might need to update the top of the nesting stack's \type {prevdepth} explicitly
5119 as there is no way \LUATEX\ can guess your intentions. By using the accessor in
5120 the \type {tex} tables, you get and set the values atthe top of the nest stack.
5121
5122 \subsubsection{Direction parameters}
5123
5124 The direction parameters are read|-|only and return a \LUA\ string.
5125
5126 \startthreecolumns
5127 \starttyping
5128 tex.bodydir
5129 tex.mathdir
5130 tex.pagedir
5131 tex.pardir
5132 tex.textdir
5133 \stoptyping
5134 \stopthreecolumns
5135
5136 \subsubsection{Glue parameters}
5137
5138 The glue parameters accept and return a userdata object that represents a \type
5139 {glue_spec} node.
5140
5141 \startthreecolumns
5142 \starttyping
5143 tex.abovedisplayshortskip
5144 tex.abovedisplayskip
5145 tex.baselineskip
5146 tex.belowdisplayshortskip
5147 tex.belowdisplayskip
5148 tex.leftskip
5149 tex.lineskip
5150 tex.parfillskip
5151 tex.parskip
5152 tex.rightskip
5153 tex.spaceskip
5154 tex.splittopskip
5155 tex.tabskip
5156 tex.topskip
5157 tex.xspaceskip
5158 \stoptyping
5159 \stopthreecolumns
5160
5161 \subsubsection{Muglue parameters}
5162
5163 All muglue parameters are to be used read|-|only and return a \LUA\ string.
5164
5165 \startthreecolumns
5166 \starttyping
5167 tex.medmuskip
5168 tex.thickmuskip
5169 tex.thinmuskip
5170 \stoptyping
5171 \stopthreecolumns
5172
5173 \subsubsection{Tokenlist parameters}
5174
5175 The tokenlist parameters accept and return \LUA\ strings. \LUA\ strings are
5176 converted to and from token lists using \type {\the} \type {\toks} style expansion:
5177 all category codes are either space (10) or other (12). It follows that assigning
5178 to some of these, like \quote {tex.output}, is actually useless, but it feels bad
5179 to make exceptions in view of a coming extension that will accept full|-|blown
5180 token strings.
5181
5182 \startthreecolumns
5183 \starttyping
5184 tex.errhelp
5185 tex.everycr
5186 tex.everydisplay
5187 tex.everyeof
5188 tex.everyhbox
5189 tex.everyjob
5190 tex.everymath
5191 tex.everypar
5192 tex.everyvbox
5193 tex.output
5194 tex.pdfpageattr
5195 tex.pdfpageresources
5196 tex.pdfpagesattr
5197 tex.pdfpkmode
5198 \stoptyping
5199 \stopthreecolumns
5200
5201 \subsection{Convert commands}
5202
5203 All \quote {convert} commands are read|-|only and return a \LUA\ string. The
5204 supported commands at this moment are:
5205
5206 \starttwocolumns
5207 \starttyping
5208 tex.eTeXVersion
5209 tex.eTeXrevision
5210 tex.formatname
5211 tex.jobname
5212 tex.luatexbanner
5213 tex.luatexrevision
5214 tex.pdfnormaldeviate
5215 tex.fontname(number)
5216 tex.pdffontname(number)
5217 tex.pdffontobjnum(number)
5218 tex.pdffontsize(number)
5219 tex.uniformdeviate(number)
5220 tex.number(number)
5221 tex.romannumeral(number)
5222 tex.pdfpageref(number)
5223 tex.pdfxformname(number)
5224 tex.fontidentifier(number)
5225 \stoptyping
5226 \stoptwocolumns
5227
5228 If you are wondering why this list looks haphazard; these are all the cases of
5229 the \quote {convert} internal command that do not require an argument, as well as
5230 the ones that require only a simple numeric value.
5231
5232 The special (lua-only) case of \type {tex.fontidentifier} returns the \type
5233 {csname} string that matches a font id number (if there is one).
5234
5235 if these are really needed in a macro package.
5236
5237 \subsection{Last item commands}
5238
5239 All \quote {last item} commands are read|-|only and return a number.
5240
5241 The supported commands at this moment are:
5242
5243 \startthreecolumns
5244 \starttyping
5245 tex.lastpenalty
5246 tex.lastkern
5247 tex.lastskip
5248 tex.lastnodetype
5249 tex.inputlineno
5250 tex.pdflastobj
5251 tex.pdflastxform
5252 tex.pdflastximage
5253 tex.pdflastximagepages
5254 tex.pdflastannot
5255 tex.pdflastxpos
5256 tex.pdflastypos
5257 tex.pdfrandomseed
5258 tex.pdflastlink
5259 tex.luatexversion
5260 tex.eTeXminorversion
5261 tex.eTeXversion
5262 tex.currentgrouplevel
5263 tex.currentgrouptype
5264 tex.currentiflevel
5265 tex.currentiftype
5266 tex.currentifbranch
5267 tex.pdflastximagecolordepth
5268 \stoptyping
5269 \stopthreecolumns
5270
5271 \subsection{Attribute, count, dimension, skip and token registers}
5272
5273 \TEX's attributes (\type {\attribute}), counters (\type {\count}), dimensions (\type
5274 {\dimen}), skips (\type {\skip}) and token (\type {\toks}) registers can be accessed
5275 and written to using two times five virtual sub|-|tables of the \type {tex}
5276 table:
5277
5278 \startthreecolumns
5279 \starttyping
5280 tex.attribute
5281 tex.count
5282 tex.dimen
5283 tex.skip
5284 tex.toks
5285 \stoptyping
5286 \stopthreecolumns
5287
5288 It is possible to use the names of relevant \type {\attributedef}, \type {\countdef},
5289 \type {\dimendef}, \type {\skipdef}, or \type {\toksdef} control sequences as indices
5290 to these tables:
5291
5292 \starttyping
5293 tex.count.scratchcounter = 0
5294 enormous = tex.dimen['maxdimen']
5295 \stoptyping
5296
5297 In this case, \LUATEX\ looks up the value for you on the fly. You have to use a
5298 valid \type {\countdef} (or \type {\attributedef}, or \type {\dimendef}, or \type
5299 {\skipdef}, or \type {\toksdef}), anything else will generate an error (the intent
5300 is to eventually also allow \type {<chardef tokens>} and even macros that expand
5301 into a number).
5302
5303 The attribute and count registers accept and return \LUA\ numbers.
5304
5305 The dimension registers accept \LUA\ numbers (in scaled points) or strings (with
5306 an included absolute dimension; \type {em} and \type {ex} and \type {px} are
5307 forbidden). The result is always a number in scaled points.
5308
5309 The token registers accept and return \LUA\ strings. \LUA\ strings are converted
5310 to and from token lists using \type {\the} \type {\toks} style expansion: all
5311 category codes are either space (10) or other (12).
5312
5313 The skip registers accept and return \type {glue_spec} userdata node objects (see
5314 the description of the node interface elsewhere in this manual).
5315
5316 As an alternative to array addressing, there are also accessor functions defined
5317 for all cases, for example, here is the set of possibilities for \type {\skip}
5318 registers:
5319
5320 \startfunctioncall
5321 tex.setskip (<number> n, <node> s)
5322 tex.setskip (<string> s, <node> s)
5323 tex.setskip ("global",<number> n, <node> s)
5324 tex.setskip ("global",<string> s, <node> s)
5325 <node> s = tex.getskip (<number> n)
5326 <node> s = tex.getskip (<string> s)
5327 \stopfunctioncall
5328
5329 We have similar setters for \type {count}, \type {dimen}, \type {muskip}, and
5330 \type {toks}. Counters and dimen are represented by numbers, skips and muskips by
5331 nodes, and toks by strings. For tokens registers we have an alternative where a
5332 catcode table is specified:
5333
5334 \startfunctioncall
5335 tex.scantoks(0,3,"$e=mc^2$")
5336 tex.scantoks("global",0,"$\int\limits^1_2$")
5337 \stopfunctioncall
5338
5339 In the function-based interface, it is possible to define values globally by
5340 using the string \type {global} as the first function argument.
5341
5342 There are four extra skip related helpers:
5343
5344 \startfunctioncall
5345 tex.setglue (<number> n, width, stretch, shrink, stretch_order, shrink_order)
5346 tex.setglue (<string> s, width, stretch, shrink, stretch_order, shrink_order)
5347 tex.setglue ("global",<number> n, width, stretch, shrink, stretch_order, shrink_order)
5348 tex.setglue ("global",<string> s, width, stretch, shrink, stretch_order, shrink_order)
5349 width, stretch, shrink, stretch_order, shrink_order = tex.getglue (<number> n)
5350 width, stretch, shrink, stretch_order, shrink_order = tex.getglue (<string> s)
5351 \stopfunctioncall
5352
5353 The other two are \type {tex.setmuglue} and \type {tex.getmuglue}.
5354
5355 \subsection{Character code registers}
5356
5357 \TEX's character code tables (\type {\lccode}, \type {\uccode}, \type {\sfcode}, \type
5358 {\catcode}, \type {\mathcode}, \type {\delcode}) can be accessed and written to using
5359 six virtual subtables of the \type {tex} table
5360
5361 \startthreecolumns
5362 \starttyping
5363 tex.lccode
5364 tex.uccode
5365 tex.sfcode
5366 tex.catcode
5367 tex.mathcode
5368 tex.delcode
5369 \stoptyping
5370 \stopthreecolumns
5371
5372 The function call interfaces are roughly as above, but there are a few twists.
5373 \type {sfcode}s are the simple ones:
5374
5375 \startfunctioncall
5376 tex.setsfcode (<number> n, <number> s)
5377 tex.setsfcode ('global', <number> n, <number> s)
5378 <number> s = tex.getsfcode (<number> n)
5379 \stopfunctioncall
5380
5381 The function call interface for \type {lccode} and \type {uccode} additionally
5382 allows you to set the associated sibling at the same time:
5383
5384 \startfunctioncall
5385 tex.setlccode (['global'], <number> n, <number> lc)
5386 tex.setlccode (['global'], <number> n, <number> lc, <number> uc)
5387 <number> lc = tex.getlccode (<number> n)
5388 tex.setuccode (['global'], <number> n, <number> uc)
5389 tex.setuccode (['global'], <number> n, <number> uc, <number> lc)
5390 <number> uc = tex.getuccode (<number> n)
5391 \stopfunctioncall
5392
5393 The function call interface for \type {catcode} also allows you to specify a
5394 category table to use on assignment or on query (default in both cases is the
5395 current one):
5396
5397 \startfunctioncall
5398 tex.setcatcode (['global'], <number> n, <number> c)
5399 tex.setcatcode (['global'], <number> cattable, <number> n, <number> c)
5400 <number> lc = tex.getcatcode (<number> n)
5401 <number> lc = tex.getcatcode (<number> cattable, <number> n)
5402 \stopfunctioncall
5403
5404 The interfaces for \type {delcode} and \type {mathcode} use small array tables to
5405 set and retrieve values:
5406
5407 \startfunctioncall
5408 tex.setmathcode (['global'], <number> n, <table> mval )
5409 <table> mval = tex.getmathcode (<number> n)
5410 tex.setdelcode (['global'], <number> n, <table> dval )
5411 <table> dval = tex.getdelcode (<number> n)
5412 \stopfunctioncall
5413
5414 Where the table for \type {mathcode} is an array of 3 numbers, like this:
5415
5416 \starttyping
5417 {<number> mathclass, <number> family, <number> character}
5418 \stoptyping
5419
5420 And the table for \type {delcode} is an array with 4 numbers, like this:
5421
5422 \starttyping
5423 {<number> small_fam, <number> small_char, <number> large_fam, <number> large_char}
5424 \stoptyping
5425
5426 You can also avoid the table:
5427
5428 \startfunctioncall
5429 class, family, char = tex.getmathcodes (<number> n)
5430 smallfam, smallchar, largefam, largechar = tex.getdelcodes (<number> n)
5431 \stopfunctioncall
5432
5433 Normally, the third and fourth values in a delimiter code assignment will be zero
5434 according to \type {\Udelcode} usage, but the returned table can have values there
5435 (if the delimiter code was set using \type {\delcode}, for example). Unset \type
5436 {delcode}'s can be recognized because \type {dval[1]} is $-1$.
5437
5438 \subsection{Box registers}
5439
5440 It is possible to set and query actual boxes, using the node interface as defined
5441 in the \type {node} library:
5442
5443 \starttyping
5444 tex.box
5445 \stoptyping
5446
5447 for array access, or
5448
5449 \starttyping
5450 tex.setbox(<number> n, <node> s)
5451 tex.setbox(<string> cs, <node> s)
5452 tex.setbox('global', <number> n, <node> s)
5453 tex.setbox('global', <string> cs, <node> s)
5454 <node> n = tex.getbox(<number> n)
5455 <node> n = tex.getbox(<string> cs)
5456 \stoptyping
5457
5458 for function|-|based access. In the function-based interface, it is possible to
5459 define values globally by using the string \type {global} as the first function
5460 argument.
5461
5462 Be warned that an assignment like
5463
5464 \starttyping
5465 tex.box[0] = tex.box[2]
5466 \stoptyping
5467
5468 does not copy the node list, it just duplicates a node pointer. If \type {\box2}
5469 will be cleared by \TEX\ commands later on, the contents of \type {\box0} becomes
5470 invalid as well. To prevent this from happening, always use \type
5471 {node.copy_list()} unless you are assigning to a temporary variable:
5472
5473 \starttyping
5474 tex.box[0] = node.copy_list(tex.box[2])
5475 \stoptyping
5476
5477 The following function will register a box for reuse (this is modelled after so
5478 called xforms in \PDF). You can (re)use the box with \type {\useboxresource} or
5479 by creating a rule node with subtype~2.
5480
5481 \starttyping
5482 local index = tex.saveboxresource(n,attributes,resources,immediate)
5483 \stoptyping
5484
5485 The optional second and third arguments are strings, the fourth is a boolean.
5486
5487 You can generate the reference (a rule type) with:
5488
5489 \starttyping
5490 local reused = tex.useboxresource(n,wd,ht,dp)
5491 \stoptyping
5492
5493 The dimensions are optional and the final ones are returned as extra values. The
5494 following is just a bonus (no dimensions returned means that the resource is
5495 unknown):
5496
5497 \starttyping
5498 local w, h, d = tex.getboxresourcedimensions(n)
5499 \stoptyping
5500
5501 You can split a box:
5502
5503 \starttyping
5504 local vlist = tex.splitbox(n,height,mode)
5505 \stoptyping
5506
5507 The remainder is kept in the original box and a packaged vlist is returned. This
5508 operation is comparable to the \type {\vsplit} operation. The mode can be \type
5509 {additional} or \type {exactly} and concerns the split off box.
5510
5511 \subsection{Math parameters}
5512
5513 It is possible to set and query the internal math parameters using:
5514
5515 \startfunctioncall
5516 tex.setmath(<string> n, <string> t, <number> n)
5517 tex.setmath('global', <string> n, <string> t, <number> n)
5518 <number> n = tex.getmath(<string> n, <string> t)
5519 \stopfunctioncall
5520
5521 As before an optional first parameter \type {global} indicates a global
5522 assignment.
5523
5524 The first string is the parameter name minus the leading \quote {Umath}, and the
5525 second string is the style name minus the trailing \quote {style}.
5526
5527 Just to be complete, the values for the math parameter name are:
5528
5529 \starttyping
5530 quad                axis                operatorsize
5531 overbarkern         overbarrule         overbarvgap
5532 underbarkern        underbarrule        underbarvgap
5533 radicalkern         radicalrule         radicalvgap
5534 radicaldegreebefore radicaldegreeafter  radicaldegreeraise
5535 stackvgap           stacknumup          stackdenomdown
5536 fractionrule        fractionnumvgap     fractionnumup
5537 fractiondenomvgap   fractiondenomdown   fractiondelsize
5538 limitabovevgap      limitabovebgap      limitabovekern
5539 limitbelowvgap      limitbelowbgap      limitbelowkern
5540 underdelimitervgap  underdelimiterbgap
5541 overdelimitervgap   overdelimiterbgap
5542 subshiftdrop        supshiftdrop        subshiftdown
5543 subsupshiftdown     subtopmax           supshiftup
5544 supbottommin        supsubbottommax     subsupvgap
5545 spaceafterscript    connectoroverlapmin
5546 ordordspacing       ordopspacing        ordbinspacing     ordrelspacing
5547 ordopenspacing      ordclosespacing     ordpunctspacing   ordinnerspacing
5548 opordspacing        opopspacing         opbinspacing      oprelspacing
5549 opopenspacing       opclosespacing      oppunctspacing    opinnerspacing
5550 binordspacing       binopspacing        binbinspacing     binrelspacing
5551 binopenspacing      binclosespacing     binpunctspacing   bininnerspacing
5552 relordspacing       relopspacing        relbinspacing     relrelspacing
5553 relopenspacing      relclosespacing     relpunctspacing   relinnerspacing
5554 openordspacing      openopspacing       openbinspacing    openrelspacing
5555 openopenspacing     openclosespacing    openpunctspacing  openinnerspacing
5556 closeordspacing     closeopspacing      closebinspacing   closerelspacing
5557 closeopenspacing    closeclosespacing   closepunctspacing closeinnerspacing
5558 punctordspacing     punctopspacing      punctbinspacing   punctrelspacing
5559 punctopenspacing    punctclosespacing   punctpunctspacing punctinnerspacing
5560 innerordspacing     inneropspacing      innerbinspacing   innerrelspacing
5561 inneropenspacing    innerclosespacing   innerpunctspacing innerinnerspacing
5562 \stoptyping
5563
5564 The values for the style parameter name are:
5565
5566 \starttyping
5567 display       crampeddisplay
5568 text          crampedtext
5569 script        crampedscript
5570 scriptscript  crampedscriptscript
5571 \stoptyping
5572
5573 The value is either a number (representing a dimension or number) or a glue spec
5574 node representing a muskip for \type {ordordspacing} and similar spacing
5575 parameters.
5576
5577 \subsection{Special list heads}
5578
5579 The virtual table \type {tex.lists} contains the set of internal registers that
5580 keep track of building page lists.
5581
5582 \starttabulate[|lT|p|]
5583 \NC \bf field           \NC \bf description \NC \NR
5584 \NC page_ins_head       \NC circular list of pending insertions \NC \NR
5585 \NC contrib_head        \NC the recent contributions \NC \NR
5586 \NC page_head           \NC the current page content \NC \NR
5587 %NC temp_head           \NC \NC \NR
5588 \NC hold_head           \NC used for held-over items for next page \NC \NR
5589 \NC adjust_head         \NC head of the current \type {\vadjust} list \NC \NR
5590 \NC pre_adjust_head     \NC head of the current \type {\vadjust pre} list \NC \NR
5591 %NC align_head          \NC \NC \NR
5592 \NC page_discards_head  \NC head of the discarded items of a page break \NC \NR
5593 \NC split_discards_head \NC head of the discarded items in a vsplit \NC \NR
5594 \stoptabulate
5595
5596 \subsection{Semantic nest levels}
5597
5598 The virtual table \type {tex.nest} contains the currently active
5599 semantic nesting state. It has two main parts: a zero-based array of userdata for
5600 the semantic nest itself, and the numerical value \type {tex.nest.ptr}, which
5601 gives the highest available index. Neither the array items in \type {tex.nest[]}
5602 nor \type {tex.nest.ptr} can be assigned to (as this would confuse the
5603 typesetting engine beyond repair), but you can assign to the individual values
5604 inside the array items, e.g.\ \type {tex.nest[tex.nest.ptr].prevdepth}.
5605
5606 \type {tex.nest[tex.nest.ptr]} is the current nest state, \type {tex.nest[0]} the
5607 outermost (main vertical list) level.
5608
5609 The known fields are:
5610
5611 \starttabulate[|lT|l|l|p|]
5612 \NC \ssbf key   \NC \bf type \NC \bf modes \NC \bf explanation \NC \NR
5613 \NC mode        \NC number   \NC all       \NC The current mode. This is a number representing the
5614                                                main mode at this level:\crlf
5615                                                \type {0} == no mode (this happens during \type {\write})\crlf
5616                                                \type {1} == vertical,\crlf
5617                                                \type {127} = horizontal,\crlf
5618                                                \type {253} = display math.\crlf
5619                                                \type {-1} == internal vertical,\crlf
5620                                                \type {-127} = restricted horizontal,\crlf
5621                                                \type {-253} = inline math. \NC \NR
5622 \NC modeline    \NC number   \NC all       \NC source input line where this mode was entered in,
5623                                                negative inside the output routine \NC \NR
5624 \NC head        \NC node     \NC all       \NC the head of the current list \NC \NR
5625 \NC tail        \NC node     \NC all       \NC the tail of the current list \NC \NR
5626 \NC prevgraf    \NC number   \NC vmode     \NC number of lines in the previous paragraph \NC \NR
5627 \NC prevdepth   \NC number   \NC vmode     \NC depth of the previous paragraph (equal to \type {\pdfignoreddimen}
5628                                                when it is to be ignored) \NC \NR
5629 \NC spacefactor \NC number   \NC hmode     \NC the current space factor \NC \NR
5630 \NC dirs        \NC node     \NC hmode     \NC used for temporary storage by the line break algorithm\NC \NR
5631 \NC noad        \NC node     \NC mmode     \NC used for temporary storage of a pending fraction numerator,
5632                                                for \type {\over} etc. \NC \NR
5633 \NC delimptr    \NC node     \NC mmode     \NC used for temporary storage of the previous math delimiter,
5634                                                for \type {\middle} \NC \NR
5635 \NC mathdir     \NC boolean  \NC mmode     \NC true when during math processing the \type {\mathdir} is not
5636                                                the same as the surrounding \type {\textdir} \NC \NR
5637 \NC mathstyle   \NC number   \NC mmode     \NC the current \type {\mathstyle} \NC \NR
5638 \stoptabulate
5639
5640 \subsection[sec:luaprint]{Print functions}
5641
5642 The \type {tex} table also contains the three print functions that are the
5643 major interface from \LUA\ scripting to \TEX.
5644
5645 The arguments to these three functions are all stored in an in|-|memory virtual
5646 file that is fed to the \TEX\ scanner as the result of the expansion of
5647 \type {\directlua}.
5648
5649 The total amount of returnable text from a \type {\directlua} command is only
5650 limited by available system \RAM. However, each separate printed string has to
5651 fit completely in \TEX's input buffer.
5652
5653 The result of using these functions from inside callbacks is undefined
5654 at the moment.
5655
5656 \subsubsection{\type {tex.print}}
5657
5658 \startfunctioncall
5659 tex.print(<string> s, ...)
5660 tex.print(<number> n, <string> s, ...)
5661 tex.print(<table> t)
5662 tex.print(<number> n, <table> t)
5663 \stopfunctioncall
5664
5665 Each string argument is treated by \TEX\ as a separate input line. If there is a
5666 table argument instead of a list of strings, this has to be a consecutive array
5667 of strings to print (the first non-string value will stop the printing process).
5668
5669 The optional parameter can be used to print the strings using the catcode regime
5670 defined by \type {\catcodetable}~\type {n}. If \type {n} is $-1$, the currently
5671 active catcode regime is used. If \type {n} is $-2$, the resulting catcodes are
5672 the result of \type {\the} \type {\toks}: all category codes are 12 (other) except for
5673 the space character, that has category code 10 (space). Otherwise, if \type {n}
5674 is not a valid catcode table, then it is ignored, and the currently active
5675 catcode regime is used instead.
5676
5677 The very last string of the very last \type {tex.print()} command in a \type
5678 {\directlua} will not have the \type {\endlinechar} appended, all others do.
5679
5680 \subsubsection{\type {tex.sprint}}
5681
5682 \startfunctioncall
5683 tex.sprint(<string> s, ...)
5684 tex.sprint(<number> n, <string> s, ...)
5685 tex.sprint(<table> t)
5686 tex.sprint(<number> n, <table> t)
5687 \stopfunctioncall
5688
5689 Each string argument is treated by \TEX\ as a special kind of input line that
5690 makes it suitable for use as a partial line input mechanism:
5691
5692 \startitemize[packed]
5693 \startitem
5694     \TEX\ does not switch to the \quote {new line} state, so that leading spaces
5695     are not ignored.
5696 \stopitem
5697 \startitem
5698     No \type {\endlinechar} is inserted.
5699 \stopitem
5700 \startitem
5701     Trailing spaces are not removed.
5702
5703     Note that this does not prevent \TEX\ itself from eating spaces as result of
5704     interpreting the line. For example, in
5705
5706 \starttyping
5707 before\directlua{tex.sprint("\\relax")tex.sprint(" inbetween")}after
5708 \stoptyping
5709     the space before \type {in between} will be gobbled as a result of the \quote
5710     {normal} scanning of \type {\relax}.
5711 \stopitem
5712 \stopitemize
5713
5714 If there is a table argument instead of a list of strings, this has to
5715 be a consecutive array of strings to print (the first non-string value
5716 will stop the printing process).
5717
5718 The optional argument sets the catcode regime, as with \type {tex.print()}.
5719
5720 \subsubsection{\type {tex.tprint}}
5721
5722 \startfunctioncall
5723 tex.tprint({<number> n, <string> s, ...}, {...})
5724 \stopfunctioncall
5725
5726 This function is basically a shortcut for repeated calls to \type
5727 {tex.sprint(<number> n, <string> s, ...)}, once for each of the supplied argument
5728 tables.
5729
5730 \subsubsection{\type {tex.cprint}}
5731
5732 This function takes a number indicating the to be used catcode, plus either a
5733 table of strings or an argument list of strings that will be pushed into the
5734 input stream.
5735
5736 \startfunctioncall
5737 tex.cprint( 1," 1: $&{\\foo}") tex.print("\\par") -- a lot of \bgroup s
5738 tex.cprint( 2," 2: $&{\\foo}") tex.print("\\par") -- matching \egroup s
5739 tex.cprint( 9," 9: $&{\\foo}") tex.print("\\par") -- all get ignored
5740 tex.cprint(10,"10: $&{\\foo}") tex.print("\\par") -- all become spaces
5741 tex.cprint(11,"11: $&{\\foo}") tex.print("\\par") -- letters
5742 tex.cprint(12,"12: $&{\\foo}") tex.print("\\par") -- other characters
5743 tex.cprint(14,"12: $&{\\foo}") tex.print("\\par") -- comment triggers
5744 \stopfunctioncall
5745
5746 \subsubsection{\type {tex.write}}
5747
5748 \startfunctioncall
5749 tex.write(<string> s, ...)
5750 tex.write(<table> t)
5751 \stopfunctioncall
5752
5753 Each string argument is treated by \TEX\ as a special kind of input line that
5754 makes it suitable for use as a quick way to dump information:
5755
5756 \startitemize
5757 \item All catcodes on that line are either \quote{space} (for '~') or
5758      \quote{character} (for all others).
5759 \item There is no \type {\endlinechar} appended.
5760 \stopitemize
5761
5762 If there is a table argument instead of a list of strings, this has to be a
5763 consecutive array of strings to print (the first non-string value will stop the
5764 printing process).
5765
5766 \subsection{Helper functions}
5767
5768 \subsubsection{\type {tex.round}}
5769
5770 \startfunctioncall
5771 <number> n = tex.round(<number> o)
5772 \stopfunctioncall
5773
5774 Rounds \LUA\ number \type {o}, and returns a number that is in the range of a
5775 valid \TEX\ register value. If the number starts out of range, it generates a
5776 \quote {number to big} error as well.
5777
5778 \subsubsection{\type {tex.scale}}
5779
5780 \startfunctioncall
5781 <number> n = tex.scale(<number> o, <number> delta)
5782 <table> n = tex.scale(table o, <number> delta)
5783 \stopfunctioncall
5784
5785 Multiplies the \LUA\ numbers \type {o} and \type {delta}, and returns a rounded
5786 number that is in the range of a valid \TEX\ register value. In the table
5787 version, it creates a copy of the table with all numeric top||level values scaled
5788 in that manner. If the multiplied number(s) are of range, it generates
5789 \quote{number to big} error(s) as well.
5790
5791 Note: the precision of the output of this function will depend on your computer's
5792 architecture and operating system, so use with care! An interface to \LUATEX's
5793 internal, 100\% portable scale function will be added at a later date.
5794
5795 \subsubsection{\type {tex.sp}}
5796
5797 \startfunctioncall
5798 <number> n = tex.sp(<number> o)
5799 <number> n = tex.sp(<string> s)
5800 \stopfunctioncall
5801
5802 Converts the number \type {o} or a string \type {s} that represents an explicit
5803 dimension into an integer number of scaled points.
5804
5805 For parsing the string, the same scanning and conversion rules are used that
5806 \LUATEX\ would use if it was scanning a dimension specifier in its \TEX|-|like
5807 input language (this includes generating errors for bad values), expect for the
5808 following:
5809
5810 \startitemize[n]
5811 \startitem
5812     only explicit values are allowed, control sequences are not handled
5813 \stopitem
5814 \startitem
5815     infinite dimension units (\type {fil...}) are forbidden
5816 \stopitem
5817 \startitem
5818     \type {mu} units do not generate an error (but may not be useful either)
5819 \stopitem
5820 \stopitemize
5821
5822 \subsubsection{\type {tex.definefont}}
5823
5824 \startfunctioncall
5825 tex.definefont(<string> csname, <number> fontid)
5826 tex.definefont(<boolean> global, <string> csname, <number> fontid)
5827 \stopfunctioncall
5828
5829 Associates \type {csname} with the internal font number \type {fontid}. The
5830 definition is global if (and only if) \type {global} is specified and true (the
5831 setting of \type {globaldefs} is not taken into account).
5832
5833 \subsubsection{\type {tex.getlinenumber} and \type {tex.setlinenumber}}
5834
5835 You can mess with the current line number:
5836
5837 \startfunctioncall
5838 local n = tex.getlinenumber()
5839 tex.setlinenumber(n+10)
5840 \stopfunctioncall
5841
5842 which can be shortcut to:
5843
5844 \startfunctioncall
5845 tex.setlinenumber(10,true)
5846 \stopfunctioncall
5847
5848 This might be handy when you have a callback that read numbers from a file and
5849 combines them in one line (in which case an error message probably has to refer
5850 to the original line). Interference with \TEX's internal handling of numbers is
5851 of course possible.
5852
5853 \subsubsection{\type {tex.error}}
5854
5855 \startfunctioncall
5856 tex.error(<string> s)
5857 tex.error(<string> s, <table> help)
5858 \stopfunctioncall
5859
5860 This creates an error somewhat like the combination of \type {\errhelp} and \type
5861 {\errmessage} would. During this error, deletions are disabled.
5862
5863 The array part of the \type {help} table has to contain strings, one for each
5864 line of error help.
5865
5866 \subsubsection{\type {tex.hashtokens}}
5867
5868 \startfunctioncall
5869 for i,v in pairs (tex.hashtokens()) do ... end
5870 \stopfunctioncall
5871
5872 Returns a name and token table pair (see~\in {section} [luatokens] about token
5873 tables) iterator for every non-zero entry in the hash table. This can be useful
5874 for debugging, but note that this also reports control sequences that may be
5875 unreachable at this moment due to local redefinitions: it is strictly a dump of
5876 the hash table.
5877
5878 \subsection[luaprimitives]{Functions for dealing with primitives }
5879
5880 \subsubsection{\type {tex.enableprimitives}}
5881
5882 \startfunctioncall
5883 tex.enableprimitives(<string> prefix, <table> primitive names)
5884 \stopfunctioncall
5885
5886 This function accepts a prefix string and an array of primitive names.
5887
5888 For each combination of \quote {prefix} and \quote {name}, the \type
5889 {tex.enableprimitives} first verifies that \quote {name} is an actual primitive
5890 (it must be returned by one of the \type {tex.extraprimitives()} calls explained
5891 below, or part of \TEX82, or \type {\directlua}). If it is not, \type
5892 {tex.enableprimitives} does nothing and skips to the next pair.
5893
5894 But if it is, then it will construct a csname variable by concatenating the
5895 \quote {prefix} and \quote {name}, unless the \quote {prefix} is already the
5896 actual prefix of \quote {name}. In the latter case, it will discard the \quote
5897 {prefix}, and just use \quote {name}.
5898
5899 Then it will check for the existence of the constructed csname. If the csname is
5900 currently undefined (note: that is not the same as \type {\relax}), it will
5901 globally define the csname to have the meaning: run code belonging to the
5902 primitive \quote {name}. If for some reason the csname is already defined, it
5903 does nothing and tries the next pair.
5904
5905 An example:
5906
5907 \starttyping
5908   tex.enableprimitives('LuaTeX', {'formatname'})
5909 \stoptyping
5910
5911 will define \type {\LuaTeXformatname} with the same intrinsic meaning as the
5912 documented primitive \type {\formatname}, provided that the control sequences \type
5913 {\LuaTeXformatname} is currently undefined.
5914
5915 When \LUATEX\ is run with \type {--ini} only the \TEX82 primitives and \type
5916 {\directlua} are available, so no extra primitives {\bf at all}.
5917
5918 If you want to have all the new functionality available using their default
5919 names, as it is now, you will have to add
5920
5921 \starttyping
5922   \ifx\directlua\undefined \else
5923      \directlua {tex.enableprimitives('',tex.extraprimitives ())}
5924   \fi
5925 \stoptyping
5926
5927 near the beginning of your format generation file. Or you can choose different
5928 prefixes for different subsets, as you see fit.
5929
5930 Calling some form of \type {tex.enableprimitives()} is highly important though,
5931 because if you do not, you will end up with a \TEX82-lookalike that can run \LUA\
5932 code but not do much else. The defined csnames are (of course) saved in the
5933 format and will be available at runtime.
5934
5935 \subsubsection{\type {tex.extraprimitives}}
5936
5937 \startfunctioncall
5938 <table> t = tex.extraprimitives(<string> s, ...)
5939 \stopfunctioncall
5940
5941 This function returns a list of the primitives that originate from the engine(s)
5942 given by the requested string value(s). The possible values and their (current)
5943 return values are:
5944
5945 \startluacode
5946 function document.showprimitives(tag)
5947     for k, v in table.sortedpairs(tex.extraprimitives(tag)) do
5948         if v == ' ' then
5949             v = '\\normalcontrolspace'
5950         end
5951         context.type(v)
5952         context.space()
5953     end
5954 end
5955 \stopluacode
5956
5957 \starttabulate[|l|pl|]
5958 \NC \bf name\NC \bf values \NC \NR
5959 \NC tex     \NC \ctxlua{document.showprimitives('tex')    } \NC \NR
5960 \NC core    \NC \ctxlua{document.showprimitives('core')   } \NC \NR
5961 \NC etex    \NC \ctxlua{document.showprimitives('etex')   } \NC \NR
5962 \NC luatex  \NC \ctxlua{document.showprimitives('luatex') } \NC \NR
5963 \stoptabulate
5964
5965 Note that \type {'luatex'} does not contain \type {directlua}, as that is
5966 considered to be a core primitive, along with all the \TEX82 primitives, so it is
5967 part of the list that is returned from \type {'core'}.
5968
5969 % \type {'umath'} is a subset of \type {'luatex'} that covers the Unicode math
5970 % primitives as it might be desired to handle the prefixing of that subset
5971 % differently.
5972
5973 Running \type {tex.extraprimitives()} will give you the complete list of
5974 primitives \type {-ini} startup. It is exactly equivalent to \type
5975 {tex.extraprimitives('etex' and 'luatex')}.
5976
5977 \subsubsection{\type {tex.primitives}}
5978
5979 \startfunctioncall
5980 <table> t = tex.primitives()
5981 \stopfunctioncall
5982
5983 This function returns a hash table listing all primitives that \LUATEX\ knows
5984 about. The keys in the hash are primitives names, the values are tables
5985 representing tokens (see~\in{section }[luatokens]). The third value is always
5986 zero.
5987
5988 {\em In the beginning we had \type {omega} and \type {pdftex} subsets but in the
5989 meantime relevant primitives ave been promoted (either or not adapted) to the
5990 \type {luatex} set when found useful, or removed when considered to be of no use.
5991 Originally we had two sets of math definition primitives but the \OMEGA\ ones
5992 have been removed, so we no longer have a subset for math either.}
5993
5994 \subsection{Core functionality interfaces}
5995
5996 \subsubsection{\type {tex.badness}}
5997
5998 \startfunctioncall
5999 <number> b = tex.badness(<number> t, <number> s)
6000 \stopfunctioncall
6001
6002 This helper function is useful during linebreak calculations. \type {t} and \type
6003 {s} are scaled values; the function returns the badness for when total \type {t}
6004 is supposed to be made from amounts that sum to \type {s}. The returned number is
6005 a reasonable approximation of $100(t/s)^3$;
6006
6007 \subsubsection{\type {tex.resetparagraph}}
6008
6009 This function resets the parameters that \TEX\ normally resets when a new paragraph
6010 is seen.
6011
6012 \subsubsection{\type {tex.linebreak}}
6013
6014 \startfunctioncall
6015 local <node> nodelist, <table> info =
6016        tex.linebreak(<node> listhead, <table> parameters)
6017 \stopfunctioncall
6018
6019 The understood parameters are as follows:
6020
6021 \starttabulate[|l|l|p|]
6022 \NC \bf name                 \NC \bf type        \NC \bf description \NC \NR
6023 \NC pardir                   \NC string          \NC \NC \NR
6024 \NC pretolerance             \NC number          \NC \NC \NR
6025 \NC tracingparagraphs        \NC number          \NC \NC \NR
6026 \NC tolerance                \NC number          \NC \NC \NR
6027 \NC looseness                \NC number          \NC \NC \NR
6028 \NC hyphenpenalty            \NC number          \NC \NC \NR
6029 \NC exhyphenpenalty          \NC number          \NC \NC \NR
6030 \NC pdfadjustspacing         \NC number          \NC \NC \NR
6031 \NC adjdemerits              \NC number          \NC \NC \NR
6032 \NC pdfprotrudechars         \NC number          \NC \NC \NR
6033 \NC linepenalty              \NC number          \NC \NC \NR
6034 \NC lastlinefit              \NC number          \NC \NC \NR
6035 \NC doublehyphendemerits     \NC number          \NC \NC \NR
6036 \NC finalhyphendemerits      \NC number          \NC \NC \NR
6037 \NC hangafter                \NC number          \NC \NC \NR
6038 \NC interlinepenalty         \NC number or table \NC if a table, then it is an array like \type {\interlinepenalties} \NC \NR
6039 \NC clubpenalty              \NC number or table \NC if a table, then it is an array like \type {\clubpenalties} \NC \NR
6040 \NC widowpenalty             \NC number or table \NC if a table, then it is an array like \type {\widowpenalties} \NC \NR
6041 \NC brokenpenalty            \NC number          \NC \NC \NR
6042 \NC emergencystretch         \NC number          \NC in scaled points \NC \NR
6043 \NC hangindent               \NC number          \NC in scaled points \NC \NR
6044 \NC hsize                    \NC number          \NC in scaled points \NC \NR
6045 \NC leftskip                 \NC glue_spec node  \NC \NC \NR
6046 \NC rightskip                \NC glue_spec node  \NC \NC \NR
6047 \NC pdfignoreddimen          \NC number          \NC in scaled points \NC \NR
6048 \NC parshape                 \NC table           \NC \NC \NR
6049 \stoptabulate
6050
6051 Note that there is no interface for \type {\displaywidowpenalties}, you have to
6052 pass the right choice for \type {widowpenalties} yourself.
6053
6054 The meaning of the various keys should be fairly obvious from the table (the
6055 names match the \TEX\ and \PDFTEX\ primitives) except for the last 5 entries. The
6056 four \type {pdf...line...} keys are ignored if their value equals \type
6057 {pdfignoreddimen}.
6058
6059 It is your own job to make sure that \type {listhead} is a proper paragraph list:
6060 this function does not add any nodes to it. To be exact, if you want to replace
6061 the core line breaking, you may have to do the following (when you are not
6062 actually working in the \type {pre_linebreak_filter} or \type {linebreak_filter}
6063 callbacks, or when the original list starting at listhead was generated in
6064 horizontal mode):
6065
6066 \startitemize
6067 \startitem
6068     add an \quote {indent box} and perhaps a \type {local_par} node at the start
6069     (only if you need them)
6070 \stopitem
6071 \startitem
6072     replace any found final glue by an infinite penalty (or add such a penalty,
6073     if the last node is not a glue)
6074 \stopitem
6075 \startitem
6076     add a glue node for the \type {\parfillskip} after that penalty node
6077 \stopitem
6078 \startitem
6079     make sure all the \type {prev} pointers are OK
6080 \stopitem
6081 \stopitemize
6082
6083 The result is a node list, it still needs to be vpacked if you want to assign it
6084 to a \type {\vbox}.
6085
6086 The returned \type {info} table contains four values that are all numbers:
6087
6088 \starttabulate[|l|p|]
6089 \NC prevdepth \NC depth of the last line in the broken paragraph \NC \NR
6090 \NC prevgraf  \NC number of lines in the broken paragraph \NC \NR
6091 \NC looseness \NC the actual looseness value in the broken paragraph \NC \NR
6092 \NC demerits  \NC the total demerits of the chosen solution  \NC \NR
6093 \stoptabulate
6094
6095 Note there are a few things you cannot interface using this function: You cannot
6096 influence font expansion other than via \type {pdfadjustspacing}, because the
6097 settings for that take place elsewhere. The same is true for hbadness and hfuzz
6098 etc. All these are in the \type {hpack()} routine, and that fetches its own
6099 variables via globals.
6100
6101 \subsubsection{\type {tex.shipout}}
6102
6103 \startfunctioncall
6104 tex.shipout(<number> n)
6105 \stopfunctioncall
6106
6107 Ships out box number \type {n} to the output file, and clears the box register.
6108
6109 \section[texconfig]{The \type {texconfig} table}
6110
6111 This is a table that is created empty. A startup \LUA\ script could
6112 fill this table with a number of settings that are read out by
6113 the executable after loading and executing the startup file.
6114
6115 \starttabulate[|lT|l|l|p|]
6116 \NC \ssbf key             \NC \bf type \NC \bf default \NC \bf explanation \NC \NR
6117 \NC kpse_init             \NC boolean  \NC true
6118 \NC
6119     \type {false} totally disables \KPATHSEA\ initialisation, and enables
6120     interpretation of the following numeric key--value pairs. (only ever unset
6121     this if you implement {\it all\/} file find callbacks!)
6122 \NC \NR
6123 \NC
6124     shell_escape          \NC string   \NC \type {'f'} \NC
6125     Use \type {'y'} or \type {'t'} or \type {'1'} to enable \type {\write18}
6126     unconditionally, \type {'p'} to enable the commands that are listed in \type
6127     {shell_escape_commands}
6128 \NC \NR
6129 \NC
6130     shell_escape_commands \NC string \NC \NC Comma-separated list of command
6131     names that may be executed by \type {\write18} even if \type {shell_escape}
6132     is set to \type {'p'}. Do {\it not\/} use spaces around commas, separate any
6133     required command arguments by using a space, and use the \ASCII\ double quote
6134     (\type {"}) for any needed argument or path quoting
6135 \NC \NR
6136
6137 \NC string_vacancies      \NC number   \NC  75000  \NC cf.\ web2c docs \NC \NR
6138 \NC pool_free             \NC number   \NC   5000  \NC cf.\ web2c docs \NC \NR
6139 \NC max_strings           \NC number   \NC  15000  \NC cf.\ web2c docs \NC \NR
6140 \NC strings_free          \NC number   \NC    100  \NC cf.\ web2c docs \NC \NR
6141 \NC nest_size             \NC number   \NC     50  \NC cf.\ web2c docs \NC \NR
6142 \NC max_in_open           \NC number   \NC     15  \NC cf.\ web2c docs \NC \NR
6143 \NC param_size            \NC number   \NC     60  \NC cf.\ web2c docs \NC \NR
6144 \NC save_size             \NC number   \NC   4000  \NC cf.\ web2c docs \NC \NR
6145 \NC stack_size            \NC number   \NC    300  \NC cf.\ web2c docs \NC \NR
6146 \NC dvi_buf_size          \NC number   \NC  16384  \NC cf.\ web2c docs \NC \NR
6147 \NC error_line            \NC number   \NC     79  \NC cf.\ web2c docs \NC \NR
6148 \NC half_error_line       \NC number   \NC     50  \NC cf.\ web2c docs \NC \NR
6149 \NC max_print_line        \NC number   \NC     79  \NC cf.\ web2c docs \NC \NR
6150 \NC hash_extra            \NC number   \NC      0  \NC cf.\ web2c docs \NC \NR
6151 \NC pk_dpi                \NC number   \NC     72  \NC cf.\ web2c docs \NC \NR
6152 \NC trace_file_names      \NC boolean  \NC true
6153 \NC
6154     \type {false} disables \TEX's normal file open|-|close feedback (the
6155     assumption is that callbacks will take care of that)
6156 \NC \NR
6157 \NC file_line_error       \NC boolean  \NC false
6158 \NC
6159     do \type {file:line} style error messages
6160 \NC \NR
6161 \NC halt_on_error         \NC boolean  \NC false
6162 \NC
6163     abort run on the first encountered error
6164 \NC \NR
6165 \NC formatname            \NC string   \NC
6166 \NC
6167     if no format name was given on the command line, this key will be tested first
6168     instead of simply quitting
6169 \NC \NR
6170 \NC jobname               \NC string   \NC
6171 \NC
6172     if no input file name was given on the command line, this key will be tested
6173     first instead of simply giving up
6174 \NC \NR
6175 \stoptabulate
6176
6177 Note: the numeric values that match web2c parameters are only used if \type
6178 {kpse_init} is explicitly set to \type {false}. In all other cases, the normal
6179 values from \type {texmf.cnf} are used.
6180
6181 \section{The \type {texio} library}
6182
6183 This library takes care of the low|-|level I/O interface.
6184
6185 \subsection{Printing functions}
6186
6187 \subsubsection{\type {texio.write}}
6188
6189 \startfunctioncall
6190 texio.write(<string> target, <string> s, ...)
6191 texio.write(<string> s, ...)
6192 \stopfunctioncall
6193
6194 Without the \type {target} argument, writes all given strings to the same
6195 location(s) \TEX\ writes messages to at this moment. If \type {\batchmode} is in
6196 effect, it writes only to the log, otherwise it writes to the log and the
6197 terminal. The optional \type {target} can be one of three possibilities: \type
6198 {term}, \type {log} or \type {term and log}.
6199
6200 Note: If several strings are given, and if the first of these strings is or might
6201 be one of the targets above, the \type {target} must be specified explicitly to
6202 prevent \LUA\ from interpreting the first string as the target.
6203
6204 \subsubsection{\type {texio.write_nl}}
6205
6206 \startfunctioncall
6207 texio.write_nl(<string> target, <string> s, ...)
6208 texio.write_nl(<string> s, ...)
6209 \stopfunctioncall
6210
6211 This function behaves like \type {texio.write}, but make sure that the given
6212 strings will appear at the beginning of a new line. You can pass a single empty
6213 string if you only want to move to the next line.
6214
6215 \subsubsection{\type {texio.setescape}}
6216
6217 You can disable \type {^^} escaping of control characters by passing a value of
6218 zero.
6219
6220 \subsection{The \type {token} libray}
6221
6222 The current \type {token} library will be replaced by a new one that is more
6223 flexible and powerful. The transition takes place in steps. In version 0.80 we
6224 have \type {token} and in version 0.85 the old lib will be replaced
6225 completely. So if you use this new mechanism in production code you need to be
6226 aware of incompatible updates between 0.80 and 0.90. Because the related in- and
6227 output code will also be cleaned up and rewritten you should be aware of
6228 incompatible logging and error reporting too.
6229
6230 The old library presents tokens as triplets or numbers, the new library presents
6231 a userdata object. The old library used a callback to intercept tokens in the
6232 input but the new library provides a basic scanner infrastructure that can be
6233 used to write macros that accept a wide range of arguments. This interface is on
6234 purpose kept general and as performance is quite ok one can build additional
6235 parsers without too much overhead. It's up to macro package writers to see how
6236 they can benefit from this as the main principle behind \LUATEX\ is to provide a
6237 minimal set of tools and no solutions.
6238
6239 The current functions in the \type {token} namespace are given in the next
6240 table:
6241
6242 \starttabulate[|lT|lT|p|]
6243 \NC \bf function \NC \bf argument       \NC \bf result \NC \NR
6244 \HL
6245 \NC is_token     \NC token              \NC checks if the given argument is a token userdatum \NC \NR
6246 \NC get_next     \NC                    \NC returns the next token in the input \NC \NR
6247 \NC scan_keyword \NC string             \NC returns true if the given keyword is gobbled \NC \NR
6248 \NC scan_int     \NC                    \NC returns a number \NC \NR
6249 \NC scan_dimen   \NC infinity, mu-units \NC returns a number representing a dimension and or two numbers being the filler and order \NC \NR
6250 \NC scan_glue    \NC mu-units           \NC returns a glue spec node \NC \NR
6251 \NC scan_toks    \NC definer, expand    \NC returns a table of tokens token list (this can become a linked list in later releases) \NC \NR
6252 \NC scan_code    \NC bitset             \NC returns a character if its category is in the given bitset (representing catcodes) \NC \NR
6253 \NC scan_string  \NC                    \NC returns a string given between \type {{}}, as \type {\macro} or as sequence of characters with catcode 11 or 12 \NC \NR
6254 \NC scan_word    \NC                    \NC returns a sequence of characters with catcode 11 or 12 as string \NC \NR
6255 \NC scan_csname  \NC                    \NC returns \type {foo} after scanning \type {\foo} \NC \NR
6256 \NC set_macro    \NC see below          \NC assign a macro \NC \NR
6257 \NC create       \NC                    \NC returns a userdata token object of the given control sequence name (or character); this interface can change  \NC \NR
6258 \stoptabulate
6259
6260 The scanners can be considered stable apart from the one scanning for a token.
6261 This is because futures releases can return a linked list instead of a table (as
6262 with nodes). The \type {scan_code} function takes an optional number, the \type
6263 {keyword} function a normal \LUA\ string. The \type {infinity} boolean signals
6264 that we also permit \type {fill} as dimension and the \type {mu-units} flags the
6265 scanner that we expect math units. When scanning tokens we can indicate that we
6266 are defining a macro, in which case the result will also provide information
6267 about what arguments are expected and in the result this is separated from the
6268 meaning by a separator token. The \type {expand} flag determines if the list will
6269 be expanded.
6270
6271 The string scanner scans for something between curly braces and expands on the
6272 way, or when it sees a control sequence it will return its meaning. Otherwise it
6273 will scan characters with catcode \type {letter} or \type {other}. So, given the
6274 following definition:
6275
6276 \startbuffer
6277 \def\bar{bar}
6278 \def\foo{foo-\bar}
6279 \stopbuffer
6280
6281 \typebuffer \getbuffer
6282
6283 we get:
6284
6285 \starttabulate[|l|Tl|l|]
6286 \NC \type {\directlua{token.scan_string()}{foo}} \NC \directlua{context("{\\red\\type {"..token.scan_string().."}}")} {foo} \NC full expansion \NR
6287 \NC \type {\directlua{token.scan_string()}foo}   \NC \directlua{context("{\\red\\type {"..token.scan_string().."}}")} foo   \NC letters and others \NR
6288 \NC \type {\directlua{token.scan_string()}\foo}  \NC \directlua{context("{\\red\\type {"..token.scan_string().."}}")}\foo   \NC meaning \NR
6289 \stoptabulate
6290
6291 The \type {\foo} case only gives the meaning, but one can pass an already
6292 expanded definition (\type {\edef}'d). In the case of the braced variant one can of
6293 course use the \type {\detokenize} and \type {\unexpanded} primitives as there we
6294 do expand.
6295
6296 The \type {scan_word} scanner can be used to implement for instance a number scanner:
6297
6298 \starttyping
6299 function token.scan_number(base)
6300     return tonumber(token.scan_word(),base)
6301 end
6302 \stoptyping
6303
6304 This scanner accepts any valid \LUA\ number so it is a way to pick up floats
6305 in the input.
6306
6307 The creator function can be used as follows:
6308
6309 \starttyping
6310 local t = token.create("relax")
6311 \stoptyping
6312
6313 This gives back a token object that has the properties of the \type {\relax}
6314 primitive. The possible properties of tokens are:
6315
6316 \starttabulate[|lT|p|]
6317 \NC command    \NC a number representing the internal command number \NC \NR
6318 \NC cmdname    \NC the type of the command (for instance the catcode in case of a
6319                    character or the classifier that determines the internal
6320                    treatment \NC \NR
6321 \NC csname     \NC the associated control sequence (if applicable) \NC \NR
6322 \NC id         \NC the unique id of the token \NC \NR
6323 %NC tok        \NC \NC \NR % might change
6324 \NC active     \NC a boolean indicating the active state of the token \NC \NR
6325 \NC expandable \NC a boolean indicating if the token (macro) is expandable \NC \NR
6326 \NC protected  \NC a boolean indicating if the token (macro) is protected \NC \NR
6327 \stoptabulate
6328
6329 The numbers that represent a catcode are the same as in \TEX\ itself, so using
6330 this information assumes that you know a bit about \TEX's internals. The other
6331 numbers and names are used consistently but are not frozen. So, when you use them
6332 for comparing you can best query a known primitive or character first to see the
6333 values.
6334
6335 More interesting are the scanners. You can use the \LUA\ interface as follows:
6336
6337 \starttyping
6338 \directlua {
6339     function mymacro(n)
6340         ...
6341     end
6342 }
6343
6344 \def\mymacro#1{%
6345     \directlua {
6346         mymacro(\number\dimexpr#1)
6347     }%
6348 }
6349
6350 \mymacro{12pt}
6351 \mymacro{\dimen0}
6352 \stoptyping
6353
6354 You can also do this:
6355
6356 \starttyping
6357 \directlua {
6358     function mymacro()
6359         local d = token.scan_dimen()
6360         ...
6361     end
6362 }
6363
6364 \def\mymacro{%
6365     \directlua {
6366         mymacro()
6367     }%
6368 }
6369
6370 \mymacro 12pt
6371 \mymacro \dimen0
6372 \stoptyping
6373
6374 It is quite clear from looking at the code what the first method needs as
6375 argument(s). For the second method you need to look at the \LUA\ code to see what
6376 gets picked up. Instead of passing from \TEX\ to \LUA\ we let \LUA\ fetch from
6377 the input stream.
6378
6379 In the first case the input is tokenized and then turned into a string when it's
6380 passed to \LUA\ where it gets interpreted. In the second case only a function
6381 call gets interpreted but then the input is picked up by explicitly calling the
6382 scanner functions. These return proper \LUA\ variables so no further conversion
6383 has to be done. This is more efficient but in practice (given what \TEX\ has to
6384 do) this effect should not be overestimated. For numbers and dimensions it saves a
6385 bit but for passing strings conversion to and from tokens has to be done anyway
6386 (although we can probably speed up the process in later versions if needed).
6387
6388 When the interface is stable and has replaced the old one completely we will add
6389 some more information here. By that time the internals have been cleaned up a bit
6390 more so we know then what will stay and go. A positive side effect of this
6391 transition is that we can simplify the input part because we no longer need to
6392 intercept using callbacks.
6393
6394 The \type {set_macro} function can get upto 4 arguments:
6395
6396 \starttyping
6397 setmacro("csname","content")
6398 setmacro("csname","content","global")
6399 setmacro("csname")
6400 \stoptyping
6401
6402 You can pass a catcodetable identifier as first argument:
6403
6404 \starttyping
6405 setmacro(catcodetable,"csname","content")
6406 setmacro(catcodetable,"csname","content","global")
6407 setmacro(catcodetable,"csname")
6408 \stoptyping
6409
6410 The results are like:
6411
6412 \starttyping
6413  \def\csname{content}
6414 \gdef\csname{content}
6415  \def\csname{}
6416 \stoptyping
6417
6418 There is a (for now) experimental putter:
6419
6420 \starttyping
6421 local t1 = token.get_next()
6422 local t2 = token.get_next()
6423 local t3 = token.get_next()
6424 local t4 = token.get_next()
6425 -- watch out, we flush in sequence
6426 token.put_next { t1, t2 }
6427 -- but this one gets pushed in front
6428 token.put_next ( t3, t4 )
6429 \stoptyping
6430
6431 When we scan \type {wxyz!} we get \type {yzwx!} back. The argument is either a table
6432 with tokens or a list of tokens.
6433
6434 \stopchapter
6435
6436 \stopcomponent