Debian Codegraph @

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

raw
1 % language=uk
2
3 \environment luatex-style
4
5 \startcomponent luatex-callbacks
6
7 \startchapter[reference=callbacks,title={\LUA\ callbacks}]
8
9 \startsection[title={Registering callbacks}][library=callback]
10
11 \topicindex{callbacks}
12
13 \libindex{register}
14 \libindex{list}
15 \libindex{find}
16
17 This library has functions that register, find and list callbacks. Callbacks are
18 \LUA\ functions that are called in well defined places. There are two kind of
19 callbacks: those that mix with existing functionality, and those that (when
20 enabled) replace functionality. In mosty cases the second category is expected to
21 behave similar to the built in functionality because in a next step specific
22 data is expected. For instance, you can replace the hyphenation routine. The
23 function gets a list that can be hyphenated (or not). The final list should be
24 valid and is (normally) used for constructing a paragraph. Another function can
25 replace the ligature builder and|/|or kerner. Doing something else is possible
26 but in the end might not give the user the expected outcome.
27
28 The first thing you need to do is registering a callback:
29
30 \startfunctioncall
31 id, error =
32 callback.register(<string> callback_name, <function> func)
33 id, error =
34 callback.register(<string> callback_name, nil)
35 id, error =
36 callback.register(<string> callback_name, false)
37 \stopfunctioncall
38
39 Here the \syntax {callback_name} is a predefined callback name, see below. The
40 function returns the internal \type {id} of the callback or \type {nil}, if the
41 callback could not be registered. In the latter case, \type {error} contains an
42 error message, otherwise it is \type {nil}.
43
44 \LUATEX\ internalizes the callback function in such a way that it does not matter
45 if you redefine a function accidentally.
46
47 Callback assignments are always global. You can use the special value \type {nil}
48 instead of a function for clearing the callback.
49
50 For some minor speed gain, you can assign the boolean \type {false} to the
51 non|-|file related callbacks, doing so will prevent \LUATEX\ from executing
52 whatever it would execute by default (when no callback function is registered at
53 all). Be warned: this may cause all sorts of grief unless you know \notabene
54 {exactly} what you are doing!
55
56 \startfunctioncall
57 <table> info =
58 callback.list()
59 \stopfunctioncall
60
61 The keys in the table are the known callback names, the value is a boolean where
62 \type {true} means that the callback is currently set (active).
63
64 \startfunctioncall
65 <function> f = callback.find(callback_name)
66 \stopfunctioncall
67
68 If the callback is not set, \type {find} returns \type {nil}.
69
70 \stopsection
71
72 \startsection[title={File discovery callbacks}][library=callback]
73
74 The behaviour documented in this subsection is considered stable in the sense that
75 there will not be backward|-|incompatible changes any more.
76
77 \subsection{\cbk {find_read_file} and \cbk {find_write_file}}
78
79 Your callback function should have the following conventions:
80
81 \startfunctioncall
82 <string> actual_name =
83 function (<number> id_number, <string> asked_name)
84 \stopfunctioncall
85
86 Arguments:
87
88 \startitemize
89
90 \sym{id_number}
91
92 This number is zero for the log or \prm {input} files. For \TEX's \prm {read}
93 or \prm {write} the number is incremented by one, so \type {\read0} becomes~1.
94
95 \sym{asked_name}
96
97 This is the user|-|supplied filename, as found by \prm {input}, \prm {openin}
98 or \prm {openout}.
99
100 \stopitemize
101
102 Return value:
103
104 \startitemize
105
106 \sym{actual_name}
107
108 This is the filename used. For the very first file that is read in by \TEX, you
109 have to make sure you return an \type {actual_name} that has an extension and
110 that is suitable for use as \type {jobname}. If you don't, you will have to
111 manually fix the name of the log file and output file after \LUATEX\ is finished,
112 and an eventual format filename will become mangled. That is because these file
113 names depend on the jobname.
114
115 You have to return \type {nil} if the file cannot be found.
116
117 \stopitemize
118
119 \subsection{\cbk {find_font_file}}
120
121 \topicindex{callbacks+font files}
122
123 Your callback function should have the following conventions:
124
125 \startfunctioncall
126 <string> actual_name =
127 function (<string> asked_name)
128 \stopfunctioncall
129
130 The \type {asked_name} is an \OTF\ or \TFM\ font metrics file.
131
132 Return \type {nil} if the file cannot be found.
133
134 \subsection{\cbk {find_output_file}}
135
136 \topicindex{callbacks+output file}
137
138 Your callback function should have the following conventions:
139
140 \startfunctioncall
141 <string> actual_name =
142 function (<string> asked_name)
143 \stopfunctioncall
144
145 The \type {asked_name} is the \PDF\ or \DVI\ file for writing.
146
147 \subsection{\cbk {find_format_file}}
148
149 \topicindex{callbacks+format file}
150
151 Your callback function should have the following conventions:
152
153 \startfunctioncall
154 <string> actual_name =
155 function (<string> asked_name)
156 \stopfunctioncall
157
158 The \type {asked_name} is a format file for reading (the format file for writing
159 is always opened in the current directory).
160
161 \subsection{\cbk {find_vf_file}}
162
163 \topicindex{callbacks+font files}
164
165 Like \cbk {find_font_file}, but for virtual fonts. This applies to both \ALEPH's
166 \OVF\ files and traditional Knuthian \VF\ files.
167
168 \subsection{\cbk {find_map_file}}
169
170 \topicindex{callbacks+font files}
171
172 Like \cbk {find_font_file}, but for map files.
173
174 \subsection{\cbk {find_enc_file}}
175
176 \topicindex{callbacks+font files}
177
178 Like \cbk {find_font_file}, but for enc files.
179
180 \subsection{\cbk {find_pk_file}}
181
182 \topicindex{callbacks+font files}
183
184 Like \cbk {find_font_file}, but for pk bitmap files. This callback takes two
185 arguments: \type {name} and \type {dpi}. In your callback you can decide to
186 look for:
187
188 \starttyping
189 <base res>dpi/<fontname>.<actual res>pk
190 \stoptyping
191
192 but other strategies are possible. It is up to you to find a \quote {reasonable}
193 bitmap file to go with that specification.
194
195 \subsection{\cbk {find_data_file}}
196
197 \topicindex{callbacks+data files}
198
199 Like \cbk {find_font_file}, but for embedded files (\type {\pdfobj file '...'}).
200
201 \subsection{\cbk {find_opentype_file}}
202
203 \topicindex{callbacks+font files}
204
205 Like \cbk {find_font_file}, but for \OPENTYPE\ font files.
206
207 \subsection{\cbk {find_truetype_file} and \cbk {find_type1_file}}
208
209 \topicindex{callbacks+font files}
210
211 Your callback function should have the following conventions:
212
213 \startfunctioncall
214 <string> actual_name =
215 function (<string> asked_name)
216 \stopfunctioncall
217
218 The \type {asked_name} is a font file. This callback is called while \LUATEX\ is
219 building its internal list of needed font files, so the actual timing may
220 surprise you. Your return value is later fed back into the matching \type
221 {read_file} callback.
222
223 Strangely enough, \cbk {find_type1_file} is also used for \OPENTYPE\ (\OTF)
224 fonts.
225
226 \subsection{\cbk {find_image_file}}
227
228 \topicindex{callbacks+image files}
229
230 Your callback function should have the following conventions:
231
232 \startfunctioncall
233 <string> actual_name =
234 function (<string> asked_name)
235 \stopfunctioncall
236
237 The \type {asked_name} is an image file. Your return value is used to open a file
238 from the hard disk, so make sure you return something that is considered the name
239 of a valid file by your operating system.
240
241 \stopsection
242
243 \startsection[reference=iocallback,title={File reading callbacks}]
244
245 The behavior documented in this subsection is considered stable in the sense that
246 there will not be backward-incompatible changes any more.
247
248 \subsection{\cbk {open_read_file}}
249
250 \topicindex{callbacks+opening files}
251
252 Your callback function should have the following conventions:
253
254 \startfunctioncall
255 <table> env =
256 function (<string> file_name)
257 \stopfunctioncall
258
259 Argument:
260
261 \startitemize
262
263 \sym{file_name}
264
265 The filename returned by a previous \cbk {find_read_file} or the return value of
266 \type {kpse.find_file()} if there was no such callback defined.
267
268 \stopitemize
269
270 Return value:
271
272 \startitemize
273
274 \sym{env}
275
276 This is a table containing at least one required and one optional callback
277 function for this file. The required field is \type {reader} and the associated
278 function will be called once for each new line to be read, the optional one is
279 \type {close} that will be called once when \LUATEX\ is done with the file.
280
281 \LUATEX\ never looks at the rest of the table, so you can use it to store your
282 private per|-|file data. Both the callback functions will receive the table as
283 their only argument.
284
285 \stopitemize
286
287 \subsubsection{\type {reader}}
288
289 \topicindex{callbacks+reader}
290
291 \LUATEX\ will run this function whenever it needs a new input line from the file.
292
293 \startfunctioncall
294 function(<table> env)
295 return <string> line
296 end
297 \stopfunctioncall
298
299 Your function should return either a string or \type {nil}. The value \type {nil}
300 signals that the end of file has occurred, and will make \TEX\ call the optional
301 \type {close} function next.
302
303 \subsubsection{\type {close}}
304
305 \topicindex{callbacks+closing files}
306
307 \LUATEX\ will run this optional function when it decides to close the file.
308
309 \startfunctioncall
310 function(<table> env)
311 end
312 \stopfunctioncall
313
314 Your function should not return any value.
315
316 \subsection{General file readers}
317
318 \topicindex{callbacks+readers}
319
320 There is a set of callbacks for the loading of binary data files. These all use
321 the same interface:
322
323 \startfunctioncall
324 function(<string> name)
325 return <boolean> success, <string> data, <number> data_size
326 end
327 \stopfunctioncall
328
329 The \type {name} will normally be a full path name as it is returned by either
330 one of the file discovery callbacks or the internal version of \type
331 {kpse.find_file()}.
332
333 \startitemize
334
335 \sym{success}
336
337 Return \type {false} when a fatal error occurred (e.g.\ when the file cannot be
338 found, after all).
339
340 \sym{data}
341
342 The bytes comprising the file.
343
344 \sym{data_size}
345
346 The length of the \type {data}, in bytes.
347
348 \stopitemize
349
350 Return an empty string and zero if the file was found but there was a
351 reading problem.
352
353 The list of functions is:
354
355 \starttabulate[|l|p|]
356 \DB function \BC usage \NC \NR
357 \TB
358 \NC \type{read_font_file} \NC ofm or tfm files \NC \NR
359 \NC \type{read_vf_file} \NC virtual fonts \NC \NR
360 \NC \type{read_map_file} \NC map files \NC \NR
361 \NC \type{read_enc_file} \NC encoding files \NC \NR
362 \NC \type{read_pk_file} \NC pk bitmap files \NC \NR
363 \NC \type{read_data_file} \NC embedded files (as is possible with \PDF\ objects) \NC \NR
364 \NC \type{read_truetype_file} \NC \TRUETYPE\ font files \NC \NR
365 \NC \type{read_type1_file} \NC \TYPEONE\ font files \NC \NR
366 \NC \type{read_opentype_file} \NC \OPENTYPE\ font files \NC \NR
367 \LL
368 \stoptabulate
369
370 \stopsection
371
372 \startsection[title={Data processing callbacks}][library=callback]
373
374 \subsection{\cbk {process_input_buffer}}
375
376 \topicindex{callbacks+input buffer}
377
378 This callback allows you to change the contents of the line input buffer just
379 before \LUATEX\ actually starts looking at it.
380
381 \startfunctioncall
382 function(<string> buffer)
383 return <string> adjusted_buffer
384 end
385 \stopfunctioncall
386
387 If you return \type {nil}, \LUATEX\ will pretend like your callback never
388 happened. You can gain a small amount of processing time from that. This callback
389 does not replace any internal code.
390
391 \subsection{\cbk {process_output_buffer}}
392
393 \topicindex{callbacks+output buffer}
394
395 This callback allows you to change the contents of the line output buffer just
396 before \LUATEX\ actually starts writing it to a file as the result of a \prm
397 {write} command. It is only called for output to an actual file (that is,
398 excluding the log, the terminal, and so called \prm {write} 18 calls).
399
400 \startfunctioncall
401 function(<string> buffer)
402 return <string> adjusted_buffer
403 end
404 \stopfunctioncall
405
406 If you return \type {nil}, \LUATEX\ will pretend like your callback never
407 happened. You can gain a small amount of processing time from that. This callback
408 does not replace any internal code.
409
410 \subsection{\cbk {process_jobname}}
411
412 \topicindex{callbacks+jobname}
413
414 This callback allows you to change the jobname given by \prm {jobname} in \TEX\
415 and \type {tex.jobname} in Lua. It does not affect the internal job name or the
416 name of the output or log files.
417
418 \startfunctioncall
419 function(<string> jobname)
420 return <string> adjusted_jobname
421 end
422 \stopfunctioncall
423
424 The only argument is the actual job name; you should not use \type {tex.jobname}
425 inside this function or infinite recursion may occur. If you return \type {nil},
426 \LUATEX\ will pretend your callback never happened. This callback does not
427 replace any internal code.
428
429 \stopsection
430
431 \startsection[title={Node list processing callbacks}][library=callback]
432
433 The description of nodes and node lists is in~\in{chapter}[nodes].
434
435 \subsection{\cbk {contribute_filter}}
436
437 \topicindex{callbacks+contributions}
438
439 This callback is called when \LUATEX\ adds contents to list:
440
441 \startfunctioncall
442 function(<string> extrainfo)
443 end
444 \stopfunctioncall
445
446 The string reports the group code. From this you can deduce from
447 what list you can give a treat.
448
449 \starttabulate[|l|p|]
450 \DB value \BC explanation \NC \NR
451 \TB
452 \NC \type{pre_box} \NC interline material is being added \NC \NR
453 \NC \type{pre_adjust} \NC \prm {vadjust} material is being added \NC \NR
454 \NC \type{box} \NC a typeset box is being added (always called) \NC \NR
455 \NC \type{adjust} \NC \prm {vadjust} material is being added \NC \NR
456 \LL
457 \stoptabulate
458
459 \subsection{\cbk {buildpage_filter}}
460
461 \topicindex{callbacks+building pages}
462
463 This callback is called whenever \LUATEX\ is ready to move stuff to the main
464 vertical list. You can use this callback to do specialized manipulation of the
465 page building stage like imposition or column balancing.
466
467 \startfunctioncall
468 function(<string> extrainfo)
469 end
470 \stopfunctioncall
471
472 The string \type {extrainfo} gives some additional information about what \TEX's
473 state is with respect to the \quote {current page}. The possible values for the
474 \cbk {buildpage_filter} callback are:
475
476 \starttabulate[|l|p|]
477 \DB value \BC explanation \NC \NR
478 \TB
479 \NC \type{alignment} \NC a (partial) alignment is being added \NC \NR
480 \NC \type{after_output} \NC an output routine has just finished \NC \NR
481 \NC \type{new_graf} \NC the beginning of a new paragraph \NC \NR
482 \NC \type{vmode_par} \NC \prm {par} was found in vertical mode \NC \NR
483 \NC \type{hmode_par} \NC \prm {par} was found in horizontal mode \NC \NR
484 \NC \type{insert} \NC an insert is added \NC \NR
485 \NC \type{penalty} \NC a penalty (in vertical mode) \NC \NR
486 \NC \type{before_display} \NC immediately before a display starts \NC \NR
487 \NC \type{after_display} \NC a display is finished \NC \NR
488 \NC \type{end} \NC \LUATEX\ is terminating (it's all over) \NC \NR
489 \LL
490 \stoptabulate
491
492 \subsection{\cbk {build_page_insert}}
493
494 \topicindex{callbacks+inserts}
495
496 This callback is called when the pagebuilder adds an insert. There is not much
497 control over this mechanism but this callback permits some last minute
498 manipulations of the spacing before an insert, something that might be handy when
499 for instance multiple inserts (types) are appended in a row.
500
501 \startfunctioncall
502 function(<number> n, <number> i)
503 return <number> register
504 end
505 \stopfunctioncall
506
507 with
508
509 \starttabulate[|l|p|]
510 \DB value \BC explanation \NC \NR
511 \TB
512 \NC \type{n} \NC the insert class \NC \NR
513 \NC \type{i} \NC the order of the insert \NC \NR
514 \LL
515 \stoptabulate
516
517 The return value is a number indicating the skip register to use for the
518 prepended spacing. This permits for instance a different top space (when \type
519 {i} equals one) and intermediate space (when \type {i} is larger than one). Of
520 course you can mess with the insert box but you need to make sure that \LUATEX\
521 is happy afterwards.
522
523 \subsection{\cbk {pre_linebreak_filter}}
524
525 \topicindex{callbacks+linebreaks}
526
527 This callback is called just before \LUATEX\ starts converting a list of nodes
528 into a stack of \prm {hbox}es, after the addition of \prm {parfillskip}.
529
530 \startfunctioncall
531 function(<node> head, <string> groupcode)
532 return true | false | <node> newhead
533 end
534 \stopfunctioncall
535
536 The string called \type {groupcode} identifies the nodelist's context within
537 \TEX's processing. The range of possibilities is given in the table below, but
538 not all of those can actually appear in \cbk {pre_linebreak_filter}, some are
539 for the \cbk {hpack_filter} and \cbk {vpack_filter} callbacks that will be
540 explained in the next two paragraphs.
541
542 \starttabulate[|l|p|]
543 \DB value \BC explanation \NC \NR
544 \TB
545 \NC \type{<empty>} \NC main vertical list \NC \NR
546 \NC \type{hbox} \NC \prm {hbox} in horizontal mode \NC \NR
547 \NC \type{adjusted_hbox} \NC \prm {hbox} in vertical mode \NC \NR
548 \NC \type{vbox} \NC \prm {vbox} \NC \NR
549 \NC \type{vtop} \NC \prm {vtop} \NC \NR
550 \NC \type{align} \NC \prm {halign} or \prm {valign} \NC \NR
551 \NC \type{disc} \NC discretionaries \NC \NR
552 \NC \type{insert} \NC packaging an insert \NC \NR
553 \NC \type{vcenter} \NC \prm {vcenter} \NC \NR
554 \NC \type{local_box} \NC \lpr {localleftbox} or \lpr {localrightbox} \NC \NR
555 \NC \type{split_off} \NC top of a \prm {vsplit} \NC \NR
556 \NC \type{split_keep} \NC remainder of a \prm {vsplit} \NC \NR
557 \NC \type{align_set} \NC alignment cell \NC \NR
558 \NC \type{fin_row} \NC alignment row \NC \NR
559 \LL
560 \stoptabulate
561
562 As for all the callbacks that deal with nodes, the return value can be one of
563 three things:
564
565 \startitemize
566 \startitem
567 boolean \type {true} signals successful processing
568 \stopitem
569 \startitem
570 \type {<node>} signals that the \quote {head} node should be replaced by the
571 returned node
572 \stopitem
573 \startitem
574 boolean \type {false} signals that the \quote {head} node list should be
575 ignored and flushed from memory
576 \stopitem
577 \stopitemize
578
579 This callback does not replace any internal code.
580
581 \subsection{\cbk {linebreak_filter}}
582
583 \topicindex{callbacks+linebreaks}
584
585 This callback replaces \LUATEX's line breaking algorithm.
586
587 \startfunctioncall
588 function(<node> head, <boolean> is_display)
589 return <node> newhead
590 end
591 \stopfunctioncall
592
593 The returned node is the head of the list that will be added to the main vertical
594 list, the boolean argument is true if this paragraph is interrupted by a
595 following math display.
596
597 If you return something that is not a \type {<node>}, \LUATEX\ will apply the
598 internal linebreak algorithm on the list that starts at \type {<head>}.
599 Otherwise, the \type {<node>} you return is supposed to be the head of a list of
600 nodes that are all allowed in vertical mode, and at least one of those has to
601 represent a hbox. Failure to do so will result in a fatal error.
602
603 Setting this callback to \type {false} is possible, but dangerous, because it is
604 possible you will end up in an unfixable \quote {deadcycles loop}.
605
606 \subsection{\type {append_to_vlist_filter}}
607
608 \topicindex{callbacks+contributions}
609
610 This callback is called whenever \LUATEX\ adds a box to a vertical list:
611
612 \startfunctioncall
613 function(<node> box, <string> locationcode, <number prevdepth>,
614 <boolean> mirrored)
615 return list, prevdepth
616 end
617 \stopfunctioncall
618
619 It is ok to return nothing in which case you also need to flush the box or deal
620 with it yourself. The prevdepth is also optional. Locations are \type {box},
621 \type {alignment}, \type {equation}, \type {equation_number} and \type
622 {post_linebreak}. You can pass \type {nil} instead of a node.
623
624 \subsection{\cbk {post_linebreak_filter}}
625
626 \topicindex{callbacks+linebreaks}
627
628 This callback is called just after \LUATEX\ has converted a list of nodes into a
629 stack of \prm {hbox}es.
630
631 \startfunctioncall
632 function(<node> head, <string> groupcode)
633 return true | false | <node> newhead
634 end
635 \stopfunctioncall
636
637 This callback does not replace any internal code.
638
639 \subsection{\cbk {hpack_filter}}
640
641 \topicindex{callbacks+packing}
642
643 This callback is called when \TEX\ is ready to start boxing some horizontal mode
644 material. Math items and line boxes are ignored at the moment.
645
646 \startfunctioncall
647 function(<node> head, <string> groupcode, <number> size,
648 <string> packtype [, <string> direction] [, <node> attributelist])
649 return true | false | <node> newhead
650 end
651 \stopfunctioncall
652
653 The \type {packtype} is either \type {additional} or \type {exactly}. If \type
654 {additional}, then the \type {size} is a \type {\hbox spread ...} argument. If
655 \type {exactly}, then the \type {size} is a \type {\hbox to ...}. In both cases,
656 the number is in scaled points.
657
658 The \type {direction} is either one of the three-letter direction specifier
659 strings, or \type {nil}.
660
661 This callback does not replace any internal code.
662
663 \subsection{\cbk {vpack_filter}}
664
665 \topicindex{callbacks+packing}
666
667 This callback is called when \TEX\ is ready to start boxing some vertical mode
668 material. Math displays are ignored at the moment.
669
670 This function is very similar to the \cbk {hpack_filter}. Besides the fact
671 that it is called at different moments, there is an extra variable that matches
672 \TEX's \prm {maxdepth} setting.
673
674 \startfunctioncall
675 function(<node> head, <string> groupcode, <number> size, <string> packtype,
676 <number> maxdepth [, <string> direction] [, <node> attributelist]))
677 return true | false | <node> newhead
678 end
679 \stopfunctioncall
680
681 This callback does not replace any internal code.
682
683 \subsection{\type {hpack_quality}}
684
685 \topicindex{callbacks+packing}
686
687 This callback can be used to intercept the overfull messages that can result from
688 packing a horizontal list (as happens in the par builder). The function takes a
689 few arguments:
690
691 \startfunctioncall
692 function(<string> incident, <number> detail, <node> head, <number> first,
693 <number> last)
694 return <node> whatever
695 end
696 \stopfunctioncall
697
698 The incident is one of \type {overfull}, \type {underfull}, \type {loose} or
699 \type {tight}. The detail is either the amount of overflow in case of \type
700 {overfull}, or the badness otherwise. The head is the list that is constructed
701 (when protrusion or expansion is enabled, this is an intermediate list).
702 Optionally you can return a node, for instance an overfull rule indicator. That
703 node will be appended to the list (just like \TEX's own rule would).
704
705 \subsection{\type {vpack_quality}}
706
707 \topicindex{callbacks+packing}
708
709 This callback can be used to intercept the overfull messages that can result from
710 packing a vertical list (as happens in the page builder). The function takes a
711 few arguments:
712
713 \startfunctioncall
714 function(<string> incident, <number> detail, <node> head, <number> first,
715 <number> last)
716 end
717 \stopfunctioncall
718
719 The incident is one of \type {overfull}, \type {underfull}, \type {loose} or
720 \type {tight}. The detail is either the amount of overflow in case of \type
721 {overfull}, or the badness otherwise. The head is the list that is constructed.
722
723 \subsection{\cbk {process_rule}}
724
725 \topicindex{callbacks+rules}
726
727 This is an experimental callback. It can be used with rules of subtype~4
728 (user). The callback gets three arguments: the node, the width and the
729 height. The callback can use \type {pdf.print} to write code to the \PDF\
730 file but beware of not messing up the final result. No checking is done.
731
732 \subsection{\type {pre_output_filter}}
733
734 \topicindex{callbacks+output}
735
736 This callback is called when \TEX\ is ready to start boxing the box 255 for \prm
737 {output}.
738
739 \startfunctioncall
740 function(<node> head, <string> groupcode, <number> size, <string> packtype,
741 <number> maxdepth [, <string> direction])
742 return true | false | <node> newhead
743 end
744 \stopfunctioncall
745
746 This callback does not replace any internal code.
747
748 \subsection{\cbk {hyphenate}}
749
750 \topicindex{callbacks+hyphenation}
751
752 \startfunctioncall
753 function(<node> head, <node> tail)
754 end
755 \stopfunctioncall
756
757 No return values. This callback has to insert discretionary nodes in the node
758 list it receives.
759
760 Setting this callback to \type {false} will prevent the internal discretionary
761 insertion pass.
762
763 \subsection{\cbk {ligaturing}}
764
765 \topicindex{callbacks+ligature building}
766
767 \startfunctioncall
768 function(<node> head, <node> tail)
769 end
770 \stopfunctioncall
771
772 No return values. This callback has to apply ligaturing to the node list it
773 receives.
774
775 You don't have to worry about return values because the \type {head} node that is
776 passed on to the callback is guaranteed not to be a glyph_node (if need be, a
777 temporary node will be prepended), and therefore it cannot be affected by the
778 mutations that take place. After the callback, the internal value of the \quote
779 {tail of the list} will be recalculated.
780
781 The \type {next} of \type {head} is guaranteed to be non-nil.
782
783 The \type {next} of \type {tail} is guaranteed to be nil, and therefore the
784 second callback argument can often be ignored. It is provided for orthogonality,
785 and because it can sometimes be handy when special processing has to take place.
786
787 Setting this callback to \type {false} will prevent the internal ligature
788 creation pass.
789
790 You must not ruin the node list. For instance, the head normally is a local par node,
791 and the tail a glue. Messing too much can push \LUATEX\ into panic mode.
792
793 \subsection{\cbk {kerning}}
794
795 \topicindex{callbacks+kerning}
796
797 \startfunctioncall
798 function(<node> head, <node> tail)
799 end
800 \stopfunctioncall
801
802 No return values. This callback has to apply kerning between the nodes in the
803 node list it receives. See \cbk {ligaturing} for calling conventions.
804
805 Setting this callback to \type {false} will prevent the internal kern insertion
806 pass.
807
808 You must not ruin the node list. For instance, the head normally is a local par node,
809 and the tail a glue. Messing too much can push \LUATEX\ into panic mode.
810
811 \subsection{\type {insert_local_par}}
812
813 Each paragraph starts with a local par node that keeps track of for instance
814 the direction. You can hook a callback into the creator:
815
816 \startfunctioncall
817 function(<node> local_par, <string> location)
818 end
819 \stopfunctioncall
820
821 There is no return value and you should make sure that the node stays valid
822 as otherwise \TEX\ can get confused.
823
824 \subsection{\cbk {mlist_to_hlist}}
825
826 \topicindex{callbacks+math}
827
828 This callback replaces \LUATEX's math list to node list conversion algorithm.
829
830 \startfunctioncall
831 function(<node> head, <string> display_type, <boolean> need_penalties)
832 return <node> newhead
833 end
834 \stopfunctioncall
835
836 The returned node is the head of the list that will be added to the vertical or
837 horizontal list, the string argument is either \quote {text} or \quote {display}
838 depending on the current math mode, the boolean argument is \type {true} if
839 penalties have to be inserted in this list, \type {false} otherwise.
840
841 Setting this callback to \type {false} is bad, it will almost certainly result in
842 an endless loop.
843
844 \stopsection
845
846 \startsection[title={Information reporting callbacks}][library=callback]
847
848 \subsection{\cbk {pre_dump}}
849
850 \topicindex{callbacks+dump}
851
852 \startfunctioncall
853 function()
854 end
855 \stopfunctioncall
856
857 This function is called just before dumping to a format file starts. It does not
858 replace any code and there are neither arguments nor return values.
859
860 \subsection{\cbk {start_run}}
861
862 \topicindex{callbacks+job run}
863
864 \startfunctioncall
865 function()
866 end
867 \stopfunctioncall
868
869 This callback replaces the code that prints \LUATEX's banner. Note that for
870 successful use, this callback has to be set in the \LUA\ initialization script,
871 otherwise it will be seen only after the run has already started.
872
873 \subsection{\cbk {stop_run}}
874
875 \topicindex{callbacks+job run}
876
877 \startfunctioncall
878 function()
879 end
880 \stopfunctioncall
881
882 This callback replaces the code that prints \LUATEX's statistics and \quote
883 {output written to} messages. The engine can still do housekeeping and therefore
884 you should not rely on this hook for postprocessing the \PDF\ or log file.
885
886 \subsection{\cbk {start_page_number}}
887
888 \topicindex{callbacks+pages}
889
890 \startfunctioncall
891 function()
892 end
893 \stopfunctioncall
894
895 Replaces the code that prints the \type {[} and the page number at the begin of
896 \prm {shipout}. This callback will also override the printing of box information
897 that normally takes place when \prm {tracingoutput} is positive.
898
899 \subsection{\cbk {stop_page_number}}
900
901 \topicindex{callbacks+pages}
902
903 \startfunctioncall
904 function()
905 end
906 \stopfunctioncall
907
908 Replaces the code that prints the \type {]} at the end of \prm {shipout}.
909
910 \subsection{\cbk {show_error_hook}}
911
912 \topicindex{callbacks+errors}
913
914 \startfunctioncall
915 function()
916 end
917 \stopfunctioncall
918
919 This callback is run from inside the \TEX\ error function, and the idea is to
920 allow you to do some extra reporting on top of what \TEX\ already does (none of
921 the normal actions are removed). You may find some of the values in the \type
922 {status} table useful. This callback does not replace any internal code.
923
924 \subsection{\cbk {show_error_message}}
925
926 \topicindex{callbacks+errors}
927
928 \startfunctioncall
929 function()
930 end
931 \stopfunctioncall
932
933 This callback replaces the code that prints the error message. The usual
934 interaction after the message is not affected.
935
936 \subsection{\cbk {show_ignored_error_message}}
937
938 \topicindex{callbacks+errors}
939
940 \startfunctioncall
941 function()
942 end
943 \stopfunctioncall
944
945 This callback replaces the code that prints the error message
946 when \prm {ignoreprimitiveerror} is enabled.
947 As before, the usual
948 interaction after the message is not affected.
949
950
951 \subsection{\cbk {show_lua_error_hook}}
952
953 \topicindex{callbacks+errors}
954
955 \startfunctioncall
956 function()
957 end
958 \stopfunctioncall
959
960 This callback replaces the code that prints the extra \LUA\ error message.
961
962 \subsection{\cbk {start_file}}
963
964 \topicindex{callbacks+files}
965
966 \startfunctioncall
967 function(category,filename)
968 end
969 \stopfunctioncall
970
971 This callback replaces the code that prints \LUATEX's when a file is opened like
972 \type {(filename} for regular files. The category is a number:
973
974 \starttabulate[|c|l|]
975 \DB value \BC meaning \NC \NR
976 \TB
977 \NC 1 \NC a normal data file, like a \TEX\ source \NC \NR
978 \NC 2 \NC a font map coupling font names to resources \NC \NR
979 \NC 3 \NC an image file (\type {png}, \type {pdf}, etc) \NC \NR
980 \NC 4 \NC an embedded font subset \NC \NR
981 \NC 5 \NC a fully embedded font \NC \NR
982 \LL
983 \stoptabulate
984
985 \subsection{\cbk {stop_file}}
986
987 \topicindex{callbacks+files}
988
989 \startfunctioncall
990 function(category)
991 end
992 \stopfunctioncall
993
994 This callback replaces the code that prints \LUATEX's when a file is closed like
995 the \type {)} for regular files.
996
997 \subsection{\cbk {call_edit}}
998
999 \topicindex{callbacks+editing}
1000
1001 \startfunctioncall
1002 function(filename,linenumber)
1003 end
1004 \stopfunctioncall
1005
1006 This callback replaces the call to an external editor when \quote{E} is pressed
1007 in reply to an error message. Processing will end immediately after the callback
1008 returns control to the main program.
1009
1010 \subsection{\cbk {finish_synctex}}
1011
1012 \topicindex{callbacks+synctex}
1013
1014 This callback can be used to wrap up alternative synctex methods. It kicks in
1015 after the normal synctex finalizer (that happens to remove the synctex files
1016 after a run when native synctex is not enabled).
1017
1018 \subsection{\cbk {wrapup_run}}
1019
1020 \topicindex{callbacks+wrapping up}
1021
1022 This callback is called after the \PDF\ and log files are closed. Use it at your own
1023 risk.
1024
1025 \stopsection
1026
1027 \startsection[title={\PDF\ related callbacks}][library=callback]
1028
1029 \subsection{\cbk {finish_pdffile}}
1030
1031 \topicindex{callbacks+\PDF\ file}
1032
1033 \startfunctioncall
1034 function()
1035 end
1036 \stopfunctioncall
1037
1038 This callback is called when all document pages are already written to the \PDF\
1039 file and \LUATEX\ is about to finalize the output document structure. Its
1040 intended use is final update of \PDF\ dictionaries such as \type {/Catalog} or
1041 \type {/Info}. The callback does not replace any code. There are neither
1042 arguments nor return values.
1043
1044 \subsection{\cbk {finish_pdfpage}}
1045
1046 \topicindex{callbacks+\PDF\ file}
1047
1048 \startfunctioncall
1049 function(shippingout)
1050 end
1051 \stopfunctioncall
1052
1053 This callback is called after the \PDF\ page stream has been assembled and before
1054 the page object gets finalized.
1055
1056 \subsection{\cbk {page_order_index}}
1057
1058 \topicindex{callbacks+\PDF\ file}
1059
1060 This is one that experts can use to juggle the page tree, a data structure
1061 that determines the order in a \PDF\ file:
1062
1063 \startfunctioncall
1064 function(pagenumber)
1065 return pagenumber
1066 end
1067 \stopfunctioncall
1068
1069 Say that we have 12 pages, then we can do this:
1070
1071 \starttyping
1072 callback.register("page_order_index",function(page)
1073 if page == 1 then return 12
1074 elseif page == 2 then return 11
1075 elseif page == 11 then return 2
1076 elseif page == 12 then return 1
1077 else return page
1078 end
1079 end)
1080 \stoptyping
1081
1082 This will swap the first two and last two pages. You need to know the number of
1083 pages which is a side effect of the implementation. When you mess things up
1084 \unknown\ don't complain.
1085
1086 \subsection{\cbk {process_pdf_image_content}}
1087
1088 \topicindex{callbacks+image content}
1089
1090 When a page from a \PDF\ file is embedded its page stream as well as related
1091 objects are copied to the target file. However, it can be that the page stream
1092 has operators that assume additional resources, for instance marked text. You can
1093 decide to filter that for which \LUATEX\ provides a callback. Here is a simple
1094 demonstration of use:
1095
1096 \starttyping
1097 pdf.setrecompress(1)
1098
1099 callback.register("process_pdf_image_content",function(s)
1100 print(s)
1101 return s
1102 end)
1103 \stoptyping
1104
1105 You need to explicitly enable recompression because otherwise the content stream
1106 gets just passed on in its original compressed form.
1107
1108 \stopsection
1109
1110 \startsection[title={Font-related callbacks}][library=callback]
1111
1112 \subsection{\cbk {define_font}}
1113
1114 \topicindex{callbacks+fonts}
1115
1116 \startfunctioncall
1117 function(<string> name, <number> size, <number> id)
1118 return <table> font | <number> id
1119 end
1120 \stopfunctioncall
1121
1122 The string \type {name} is the filename part of the font specification, as given
1123 by the user.
1124
1125 The number \type {size} is a bit special:
1126
1127 \startitemize[packed]
1128 \startitem
1129 If it is positive, it specifies an \quote{at size} in scaled points.
1130 \stopitem
1131 \startitem
1132 If it is negative, its absolute value represents a \quote {scaled} setting
1133 relative to the designsize of the font.
1134 \stopitem
1135 \stopitemize
1136
1137 The \type {id} is the internal number assigned to the font.
1138
1139 The internal structure of the \type {font} table that is to be returned is
1140 explained in \in {chapter} [fonts]. That table is saved internally, so you can
1141 put extra fields in the table for your later \LUA\ code to use. In alternative,
1142 \type {retval} can be a previously defined fontid. This is useful if a previous
1143 definition can be reused instead of creating a whole new font structure.
1144
1145 Setting this callback to \type {false} is pointless as it will prevent font
1146 loading completely but will nevertheless generate errors.
1147
1148 \subsection{\cbk {glyph_not_found} and \cbk {glyph_info}}
1149
1150 \topicindex{callbacks+fonts}
1151
1152 The \type {glyph_not_found} callback, when set, kicks in when the backend cannot
1153 insert a glyph. When no callback is defined a message is written to the log.
1154
1155 \startfunctioncall
1156 function(<number> id, <number> char)
1157 -- do something with font id and char code
1158 end
1159 \stopfunctioncall
1160
1161 The \type {glyph_info} callback can be set to report a useful representation of a
1162 glyph.
1163
1164 \startfunctioncall
1165 function(<node> g)
1166 -- return a string or nil
1167 end
1168 \stopfunctioncall
1169
1170 When \type {nil} is returned the character code is printed, otherwise the
1171 returned string is used. By default the \UTF\ representation is shown which is
1172 not always that useful, especially when there is no real representation. Keep in
1173 mind that setting this callback can change the log in an incompatible way.
1174
1175 \subsection{\cbk {provide_charproc_data}}
1176
1177 \topicindex{callbacks+fonts}
1178
1179 The \type {provide_charproc_data} callback is triggered when the backend is
1180 writing out a user-defined Type~3 font:
1181
1182 \startfunctioncall
1183 function(<number> mode, <number> id, <number> char)
1184 if mode == 1 then
1185 -- preroll
1186 return
1187 elseif mode == 2 then
1188 -- write out the glyph contents
1189 return <number> stream, <number> width
1190 elseif mode == 3 then
1191 -- the overall font scale
1192 return <number> scale
1193 end
1194 end
1195 \stopfunctioncall
1196
1197 To make a user-defined Type~3 font, you need to set \type {encodingbytes = 0}
1198 and \type {psname = "none"} at the top-level when defining the font. From the
1199 \type {glyph_not_found} callback, you should return the overall font scale
1200 (conventionally 0.001) in mode~3, and the index of a \PDF\ stream (where the
1201 first operator is either \type {d0} or \type {d1}) and the width of the glyph
1202 (in sp's) in mode~2. You can generally ignore mode~1.
1203
1204
1205 \stopsection
1206
1207 \stopchapter
1208
1209 \stopcomponent