Source Browser ?

1% language=us runpath=texruns:manuals/luametatex
2
3\environment luametatex-style
4
5\startcomponent luametatex-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\libindex{known}
17
18{\em The callbacks are a moving target. Don't bother me with questions about
19them. Some are new and/or experimental and therefore not yet documented. In
20\CONTEXT\ we can easily adapt interfaces so changes in these have no real effect
21on users. Of course in due time all will be official and documented.}
22
23This library has functions that register, find and list callbacks. Callbacks are
24\LUA\ functions that are called in well defined places. There are two kinds of
25callbacks: those that mix with existing functionality, and those that (when
26enabled) replace functionality. In most cases the second category is expected to
27behave similar to the built in functionality because in a next step specific data
28is expected. For instance, you can replace the hyphenation routine. The function
29gets a list that can be hyphenated (or not). The final list should be valid and
30is (normally) used for constructing a paragraph. Another function can replace the
31ligature builder and|/|or kern routine. Doing something else is possible but in
32the end might not give the user the expected outcome.
33
34The first thing you need to do is registering a callback:
35
36\startfunctioncall
37id = callback.register(<string> callback_name, <function> func)
38id = callback.register(<string> callback_name, nil)
39id = callback.register(<string> callback_name, false)
40\stopfunctioncall
41
42Here the \syntax {callback_name} is a predefined callback name, see below. The
43function returns the internal \type {id} of the callback or \type {nil}, if the
44callback could not be registered.
45
46\LUATEX\ internalizes the callback function in such a way that it does not matter
47if you redefine a function accidentally.
48
49Callback assignments are always global. You can use the special value \type {nil}
50instead of a function for clearing the callback.
51
52For some minor speed gain, you can assign the boolean \type {false} to the
53non|-|file related callbacks, doing so will prevent \LUATEX\ from executing
54whatever it would execute by default (when no callback function is registered at
55all). Be warned: this may cause all sorts of grief unless you know \notabene
56{exactly} what you are doing!
57
58\startfunctioncall
59<table> info =
60    callback.list()
61\stopfunctioncall
62
63The keys in the table are the known callback names, the value is a boolean where
64\type {true} means that the callback is currently set (active).
65
66\startfunctioncall
67<function> f = callback.find(callback_name)
68\stopfunctioncall
69
70If the callback is not set, \type {find} returns \type {nil}. The \type {known}
71function can be used to check if a callback is supported.
72
73\startfunctioncall
74if callback.known("foo") then ... end
75\stopfunctioncall
76
77\stopsection
78
79\startsection[title={File related callbacks},reference=iocallback][library=callback]
80
81\startsubsection[title={\cbk {find_format_file} and \cbk {find_log_file}}]
82
83\topicindex{callbacks+format file}
84\topicindex{callbacks+log file}
85
86These callbacks are called as:
87
88\startfunctioncall
89<string> actualname =
90    function (<string> askedname)
91\stopfunctioncall
92
93The \type {askedname} is a format file for reading (the format file for writing
94is always opened in the current directory) or a log file for writing.
95
96\stopsubsection
97
98\startsubsection[title={\cbk {open_data_file}}]
99
100\topicindex{callbacks+opening files}
101
102This callback function gets a filename passed:
103
104\startfunctioncall
105<table> env = function (<string> filename)
106\stopfunctioncall
107
108The return value is either the boolean value false or a table with two functions.
109A mandate \type {reader} function fill be called once for each new line to be
110read, the optional \type {close} function will be called once \LUATEX\ is done
111with the file.
112
113\LUATEX\ never looks at the rest of the table, so you can use it to store your
114private per|-|file data. Both the callback functions will receive the table as
115their only argument.
116
117% No longer needed anyway.
118%
119% \subsection{\cbk {if_end_of_file}}
120%
121% \topicindex{callbacks+checking files}
122%
123% This callback has no arguments and your function should return true or false. The
124% callback is triggered by \type {\ifeof}. It's up to the macro package to come up
125% with a reasonable implementation. By default the test is always true.
126%
127% \startfunctioncall
128% <boolean> eof =
129%     function ()
130% \stopfunctioncall
131
132\stopsubsection
133
134\stopsection
135
136\startsection[title={Data processing callbacks}][library=callback]
137
138\startsubsection[title={\cbk {process_jobname}}]
139
140\topicindex{callbacks+jobname}
141
142This callback allows you to change the jobname given by \prm {jobname} in \TEX\
143and \type {tex.jobname} in Lua. It does not affect the internal job name or the
144name of the output or log files.
145
146\startfunctioncall
147function(<string> jobname)
148    return <string> adjusted_jobname
149end
150\stopfunctioncall
151
152The only argument is the actual job name; you should not use \type {tex.jobname}
153inside this function or infinite recursion may occur. If you return \type {nil},
154\LUATEX\ will pretend your callback never happened. This callback does not
155replace any internal code.
156
157\stopsubsection
158
159\stopsection
160
161\startsection[title={Node list processing callbacks}][library=callback]
162
163The description of nodes and node lists is in~\in{chapter}[nodes].
164
165\startsubsection[title={\cbk {contribute_filter}}]
166
167\topicindex{callbacks+contributions}
168
169This callback is called when \LUATEX\ adds contents to list:
170
171\startfunctioncall
172function(<string> extrainfo)
173end
174\stopfunctioncall
175
176The string reports the group code. From this you can deduce from
177what list you can give a treat.
178
179\starttabulate[|l|p|]
180\DB value             \BC explanation                                  \NC \NR
181\TB
182\NC \type{pre_box}    \NC interline material is being added            \NC \NR
183\NC \type{pre_adjust} \NC \prm {vadjust} material is being added       \NC \NR
184\NC \type{box}        \NC a typeset box is being added (always called) \NC \NR
185\NC \type{adjust}     \NC \prm {vadjust} material is being added       \NC \NR
186\LL
187\stoptabulate
188
189\stopsubsection
190
191\startsubsection[title={\cbk {buildpage_filter}}]
192
193\topicindex{callbacks+building pages}
194
195This callback is called whenever \LUATEX\ is ready to move stuff to the main
196vertical list. You can use this callback to do specialized manipulation of the
197page building stage like imposition or column balancing.
198
199\startfunctioncall
200function(<string> extrainfo)
201end
202\stopfunctioncall
203
204The string \type {extrainfo} gives some additional information about what \TEX's
205state is with respect to the \quote {current page}. The possible values for the
206\cbk {buildpage_filter} callback are:
207
208\starttabulate[|l|p|]
209\DB value                  \BC explanation                             \NC \NR
210\TB
211\NC \type{alignment}       \NC a (partial) alignment is being added    \NC \NR
212\NC \type{after_output}    \NC an output routine has just finished     \NC \NR
213\NC \type{new_graf}        \NC the beginning of a new paragraph        \NC \NR
214\NC \type{vmode_par}       \NC \prm {par} was found in vertical mode   \NC \NR
215\NC \type{hmode_par}       \NC \prm {par} was found in horizontal mode \NC \NR
216\NC \type{insert}          \NC an insert is added                      \NC \NR
217\NC \type{penalty}         \NC a penalty (in vertical mode)            \NC \NR
218\NC \type{before_display}  \NC immediately before a display starts     \NC \NR
219\NC \type{after_display}   \NC a display is finished                   \NC \NR
220\NC \type{end}             \NC \LUATEX\ is terminating (it's all over) \NC \NR
221\LL
222\stoptabulate
223
224\stopsubsection
225
226\startsubsection[title={\cbk {insert_distance}}]
227
228\topicindex{callbacks+inserts}
229
230This callback is called when the page builder adds an insert. There is not much
231control over this mechanism but this callback permits some last minute
232manipulations of the spacing before an insert, something that might be handy when
233for instance multiple inserts (types) are appended in a row.
234
235\startfunctioncall
236function(<number> n, <number> i)
237    return <number> register
238end
239\stopfunctioncall
240
241with
242
243\starttabulate[|l|p|]
244\DB value    \BC explanation             \NC \NR
245\TB
246\NC \type{n} \NC the insert class        \NC \NR
247\NC \type{i} \NC the order of the insert \NC \NR
248\LL
249\stoptabulate
250
251The return value is a number indicating the skip register to use for the
252prepended spacing. This permits for instance a different top space (when \type
253{i} equals one) and intermediate space (when \type {i} is larger than one). Of
254course you can mess with the insert box but you need to make sure that \LUATEX\
255is happy afterwards.
256
257\stopsubsection
258
259\startsubsection[title={\cbk {pre_linebreak_filter}}]
260
261\topicindex{callbacks+linebreaks}
262
263This callback is called just before \LUATEX\ starts converting a list of nodes
264into a stack of \prm {hbox}es, after the addition of \prm {parfillskip}.
265
266\startfunctioncall
267function(<node> head, <string> groupcode)
268    return <node> newhead
269end
270\stopfunctioncall
271
272The string called \type {groupcode} identifies the nodelist's context within
273\TEX's processing. The range of possibilities is given in the table below, but
274not all of those can actually appear in \cbk {pre_linebreak_filter}, some are
275for the \cbk {hpack_filter} and \cbk {vpack_filter} callbacks that will be
276explained in the next two paragraphs.
277
278\starttabulate[|l|p|]
279\DB value                \BC explanation                                 \NC \NR
280\TB
281\NC \type{<empty>}       \NC main vertical list                          \NC \NR
282\NC \type{hbox}          \NC \prm {hbox} in horizontal mode              \NC \NR
283\NC \type{adjusted_hbox} \NC \prm {hbox} in vertical mode                \NC \NR
284\NC \type{vbox}          \NC \prm {vbox}                                 \NC \NR
285\NC \type{vtop}          \NC \prm {vtop}                                 \NC \NR
286\NC \type{align}         \NC \prm {halign} or \prm {valign}              \NC \NR
287\NC \type{disc}          \NC discretionaries                             \NC \NR
288\NC \type{insert}        \NC packaging an insert                         \NC \NR
289\NC \type{vcenter}       \NC \prm {vcenter}                              \NC \NR
290\NC \type{local_box}     \NC \prm {localleftbox} or \prm {localrightbox} \NC \NR
291\NC \type{split_off}     \NC top of a \prm {vsplit}                      \NC \NR
292\NC \type{split_keep}    \NC remainder of a \prm {vsplit}                \NC \NR
293\NC \type{align_set}     \NC alignment cell                              \NC \NR
294\NC \type{fin_row}       \NC alignment row                               \NC \NR
295\LL
296\stoptabulate
297
298As for all the callbacks that deal with nodes, the return value can be one of
299three things:
300
301\startitemize
302\startitem
303    boolean \type {true} signals successful processing
304\stopitem
305\startitem
306    \type {<node>} signals that the \quote {head} node should be replaced by the
307    returned node
308\stopitem
309\startitem
310    boolean \type {false} signals that the \quote {head} node list should be
311    ignored and flushed from memory
312\stopitem
313\stopitemize
314
315This callback does not replace any internal code.
316
317\stopsubsection
318
319\startsubsection[title={\cbk {linebreak_filter}}]
320
321\topicindex{callbacks+linebreaks}
322
323This callback replaces \LUATEX's line breaking algorithm.
324
325\startfunctioncall
326function(<node> head, <boolean> is_display)
327    return <node> newhead
328end
329\stopfunctioncall
330
331The returned node is the head of the list that will be added to the main vertical
332list, the boolean argument is true if this paragraph is interrupted by a
333following math display.
334
335If you return something that is not a \type {<node>}, \LUATEX\ will apply the
336internal linebreak algorithm on the list that starts at \type {<head>}.
337Otherwise, the \type {<node>} you return is supposed to be the head of a list of
338nodes that are all allowed in vertical mode, and at least one of those has to
339represent an \prm {hbox}. Failure to do so will result in a fatal error.
340
341Setting this callback to \type {false} is possible, but dangerous, because it is
342possible you will end up in an unfixable \quote {deadcycles loop}.
343
344\stopsubsection
345
346\startsubsection[title={\type {append_to_vlist_filter}}]
347
348\topicindex{callbacks+contributions}
349
350This callback is called whenever \LUATEX\ adds a box to a vertical list (the
351\type {mirrored} argument is obsolete):
352
353\startfunctioncall
354function(<node> box, <string> locationcode, <number> prevdepth)
355    return list [, prevdepth [, checkdepth ] ]
356end
357\stopfunctioncall
358
359It is ok to return nothing or \type {nil} in which case you also need to flush
360the box or deal with it yourself. The prevdepth is also optional. Locations are
361\type {box}, \type {alignment}, \type {equation}, \type {equation_number} and
362\type {post_linebreak}. When the third argument returned is \type {true} the
363normal prevdepth correction will be applied, based on the first node.
364
365\stopsubsection
366
367\startsubsection[title={\cbk {post_linebreak_filter}}]
368
369\topicindex{callbacks+linebreaks}
370
371This callback is called just after \LUATEX\ has converted a list of nodes into a
372stack of \prm {hbox}es.
373
374\startfunctioncall
375function(<node> head, <string> groupcode)
376    return <node> newhead
377end
378\stopfunctioncall
379
380This callback does not replace any internal code.
381
382\stopsubsection
383
384\startsubsection[title={\cbk {glyph_run}}]
385
386\topicindex{callbacks+fonts}
387\topicindex{callbacks+hyphenation}
388\topicindex{callbacks+kerning}
389\topicindex{callbacks+ligature building}
390
391When set this callback is triggered when \TEX\ normally handles the ligaturing
392and kerning. In \LUATEX\ you use the \typ {hpack_filter} and \typ
393{per_linebreak_filter} callbacks for that (where each passes different
394arguments). This callback doesn't get triggered when there are no glyphs (in
395\LUATEX\ this optimization is controlled by a a variable).
396
397\startfunctioncall
398function(<node> head, <string> groupcode, <number> direction])
399    return <node> newhead
400end
401\stopfunctioncall
402
403The traditional \TEX\ font processing is bypassed so you need to take care of that
404with the helpers. (For the moment we keep the ligaturing and kerning callbacks but
405they are kind of obsolete.)
406
407\stopsubsection
408
409\startsubsection[title={\cbk {hpack_filter}}]
410
411\topicindex{callbacks+packing}
412
413This callback is called when \TEX\ is ready to start boxing some horizontal mode
414material. Math items and line boxes are ignored at the moment.
415
416\startfunctioncall
417function(<node> head, <string> groupcode, <number> size,
418         <string> packtype [, <number> direction] [, <node> attributelist])
419    return <node> newhead
420end
421\stopfunctioncall
422
423The \type {packtype} is either \type {additional} or \type {exactly}. If \type
424{additional}, then the \type {size} is a \type {\hbox spread ...} argument. If
425\type {exactly}, then the \type {size} is a \type {\hbox to ...}. In both cases,
426the number is in scaled points.
427
428This callback does not replace any internal code.
429
430\stopsubsection
431
432\startsubsection[title={\cbk {vpack_filter}}]
433
434\topicindex{callbacks+packing}
435
436This callback is called when \TEX\ is ready to start boxing some vertical mode
437material. Math displays are ignored at the moment.
438
439This function is very similar to the \cbk {hpack_filter}. Besides the fact
440that it is called at different moments, there is an extra variable that matches
441\TEX's \prm {maxdepth} setting.
442
443\startfunctioncall
444function(<node> head, <string> groupcode, <number> size, <string> packtype,
445        <number> maxdepth [, <number> direction] [, <node> attributelist]))
446    return <node> newhead
447end
448\stopfunctioncall
449
450This callback does not replace any internal code.
451
452\stopsubsection
453
454\startsubsection[title={\cbk {packed_vbox_filter}}]
455
456\topicindex{callbacks+packing}
457
458After the \cbk {vpack_filter} callback (see previous section) is triggered the
459box get packed and after that this callback can be configured to kick in.
460
461\startfunctioncall
462function(<node> head, <string> groupcode)
463    return <node> newhead
464end
465\stopfunctioncall
466
467This callback does not replace any internal code.
468
469\stopsubsection
470
471\startsubsection[title={\cbk {alignment_filter}}]
472
473\topicindex{callbacks+alignments}
474
475This is an experimental callback that when set is called several times during the
476construction of an alignment. The context values are available in \typ
477{tex.getalignmentcontextvalues()}.
478
479\startfunctioncall
480function(<node> head, <string> context, <node> attributes, <node> preamble)
481    -- no return values
482end
483\stopfunctioncall
484
485There are no sanity checks so if a user messes up the passed node lists the results
486can be unpredictable and, as with other node related callbacks, crash the engine.
487
488\stopsubsection
489
490\startsubsection[title={\cbk {localbox_filter}}]
491
492\topicindex{callbacks+local boxes}
493
494Local boxes are a somewhat tricky and error prone feature so use this callback
495with care because the paragraph is easily messed up. A line can have a left,
496right and middle box where the middle one has no width. The callback gets quite
497some parameters passed:
498
499\startfunctioncall
500function(<node> linebox, <node> leftbox, <node> rightbox, <node> middlebox,
501    <number> linenumber,
502    <number> leftskip, <number> rightskip, <number> lefthang, <number> righthang,
503    <number> indentation, <number> parinitleftskip, <number> parinitrightskip,
504    <number> parfillleftskip, <number> parfillrightskip,
505    <number> overshoot)
506    -- no return values
507end
508\stopfunctioncall
509
510This is an experimental callback that will be tested in different \CONTEXT\
511mechanisms before it will be declared stable.
512
513\stopsubsection
514
515\startsubsection[title={\cbk {process_rule}}]
516
517\topicindex{callbacks+rules}
518
519This is an experimental callback. It can be used with rules of subtype~4
520(user). The callback gets three arguments: the node, the width and the
521height. The callback can use \type {pdf.print} to write code to the \PDF\
522file but beware of not messing up the final result. No checking is done.
523
524\stopsubsection
525
526\startsubsection[title={\type {pre_output_filter}}]
527
528\topicindex{callbacks+output}
529
530This callback is called when \TEX\ is ready to start boxing the box 255 for \prm
531{output}.
532
533\startfunctioncall
534function(<node> head, <string> groupcode, <number> size, <string> packtype,
535        <number> maxdepth [, <number> direction])
536    return <node> newhead
537end
538\stopfunctioncall
539
540This callback does not replace any internal code.
541
542\stopsubsection
543
544\startsubsection[title={\cbk {hyphenate}}]
545
546\topicindex{callbacks+hyphenation}
547
548This callback is supposed to insert discretionary nodes in the node list it
549receives.
550
551\startfunctioncall
552function(<node> head, <node> tail)
553    -- no return values
554end
555\stopfunctioncall
556
557Setting this callback to \type {false} will prevent the internal discretionary
558insertion pass.
559
560\stopsubsection
561
562\startsubsection[title={\cbk {ligaturing}}]
563
564\topicindex{callbacks+ligature building}
565
566This callback, which expects no return values, has to apply ligaturing to the
567node list it receives.
568
569\startfunctioncall
570function(<node> head, <node> tail)
571    -- no return values
572end
573\stopfunctioncall
574
575You don't have to worry about return values because the \type {head} node that is
576passed on to the callback is guaranteed not to be a glyph_node (if need be, a
577temporary node will be prepended), and therefore it cannot be affected by the
578mutations that take place. After the callback, the internal value of the \quote
579{tail of the list} will be recalculated.
580
581The \type {next} of \type {head} is guaranteed to be non-nil. The \type {next} of
582\type {tail} is guaranteed to be nil, and therefore the second callback argument
583can often be ignored. It is provided for orthogonality, and because it can
584sometimes be handy when special processing has to take place.
585
586Setting this callback to \type {false} will prevent the internal ligature
587creation pass. You must not ruin the node list. For instance, the head normally
588is a local par node, and the tail a glue. Messing too much can push \LUATEX\ into
589panic mode.
590
591\stopsubsection
592
593\startsubsection[title={\cbk {kerning}}]
594
595\topicindex{callbacks+kerning}
596
597This callback has to apply kerning between the nodes in the node list it
598receives. See \cbk {ligaturing} for calling conventions.
599
600\startfunctioncall
601function(<node> head, <node> tail)
602    -- no return values
603end
604\stopfunctioncall
605
606Setting this callback to \type {false} will prevent the internal kern insertion
607pass. You must not ruin the node list. For instance, the head normally is a local
608par node, and the tail a glue. Messing too much can push \LUATEX\ into panic
609mode.
610
611\stopsubsection
612
613\startsubsection[title={\cbk {append_line_filter}}]
614
615\topicindex{callbacks+lines}
616
617Every time a line is added this callback is triggered, when set. migrated
618material and adjusts also qualify as such and the detail relates to the adjust
619index.
620
621\startfunctioncall
622function(<node> head, <node> tail, <string> context, <number> detail)
623    return <node> newhead
624end
625\stopfunctioncall
626
627A list of possible context values can be queried with \typ
628{tex.getappendlinecontextvalues()}.
629
630\stopsubsection
631
632\stopsection
633
634\startsection[title={Paragraph callbacks}]
635
636\startsubsection[title={\type {insert_par}}]
637
638\topicindex{callbacks+paragraphs}
639
640Each paragraph starts with a local par node that keeps track of for instance
641the direction. You can hook a callback into the creator:
642
643\startfunctioncall
644function(<node> par, <string> location)
645    -- no return values
646end
647\stopfunctioncall
648
649There is no return value and you should make sure that the node stays valid
650as otherwise \TEX\ can get confused.
651
652\stopsubsection
653
654\startsubsection[title={\cbk {begin_paragraph}}]
655
656\topicindex{callbacks+paragraphs}
657
658{\em todo}
659
660\stopsubsection
661
662\startsubsection[title={\cbk {paragraph_context}}]
663
664\topicindex{callbacks+paragraphs}
665
666{\em todo}
667
668\stopsubsection
669
670\startsection[title={Math related callbacks}]
671
672\startsubsection[title={\cbk {mlist_to_hlist}}]
673
674\topicindex{callbacks+math}
675
676This callback replaces \LUATEX's math list to node list conversion algorithm.
677
678\startfunctioncall
679function(<node> head, <string> display_type, <boolean> need_penalties)
680    return <node> newhead
681end
682\stopfunctioncall
683
684The returned node is the head of the list that will be added to the vertical or
685horizontal list, the string argument is either \quote {text} or \quote {display}
686depending on the current math mode, the boolean argument is \type {true} if
687penalties have to be inserted in this list, \type {false} otherwise.
688
689Setting this callback to \type {false} is bad, it will almost certainly result in
690an endless loop.
691
692\stopsubsection
693
694\startsubsection[title={\cbk {math_rule}}]
695
696\topicindex{callbacks+math}
697\topicindex{callbacks+ruled}
698
699{\em todo}
700
701\stopsubsection
702
703\startsubsection[title={\cbk {make_extensible}}]
704
705\topicindex{callbacks+math}
706\topicindex{callbacks+fonts}
707
708{\em todo}
709
710\stopsubsection
711
712\startsubsection[title={\cbk {register_extensible}}]
713
714\topicindex{callbacks+math}
715\topicindex{callbacks+fonts}
716
717{\em todo}
718
719\stopsubsection
720
721\stopsection
722
723\startsection[title={Information reporting callbacks}][library=callback]
724
725\startsubsection[title={\cbk {pre_dump}}]
726
727\topicindex{callbacks+dump}
728
729\startfunctioncall
730function()
731    -- no return values
732end
733\stopfunctioncall
734
735This function is called just before dumping to a format file starts. It does not
736replace any code and there are neither arguments nor return values.
737
738\stopsubsection
739
740\startsubsection[title={\cbk {start_run}}]
741
742\topicindex{callbacks+job run}
743
744\startfunctioncall
745function()
746    -- no return values
747end
748\stopfunctioncall
749
750This callback replaces the code that prints \LUATEX's banner. Note that for
751successful use, this callback has to be set in the \LUA\ initialization script,
752otherwise it will be seen only after the run has already started.
753
754\stopsubsection
755
756\startsubsection[title={\cbk {stop_run}}]
757
758\topicindex{callbacks+job run}
759
760\startfunctioncall
761function()
762end
763\stopfunctioncall
764
765This callback replaces the code that prints \LUATEX's statistics and \quote
766{output written to} messages. The engine can still do housekeeping and therefore
767you should not rely on this hook for postprocessing the \PDF\ or log file.
768
769\stopsubsection
770
771\startsubsection[title={\cbk {intercept_tex_error}, \cbk {intercept_lua_error}}]
772
773\topicindex{callbacks+errors}
774
775\startfunctioncall
776function()
777    -- no return values
778end
779\stopfunctioncall
780
781This callback is run from inside the \TEX\ error function, and the idea is to
782allow you to do some extra reporting on top of what \TEX\ already does (none of
783the normal actions are removed). You may find some of the values in the \type
784{status} table useful. The \TEX\ related callback gets two arguments: the current
785processing mode and a boolean indicating if there was a runaway.
786
787\stopsubsection
788
789\startsubsection[title={\cbk {show_error_message} and \cbk {show_warning_message}}]
790
791\topicindex{callbacks+errors}
792\topicindex{callbacks+warnings}
793
794\startfunctioncall
795function()
796    -- no return values
797end
798\stopfunctioncall
799
800These callback replaces the code that prints the error message. The usual
801interaction after the message is not affected.
802
803\stopsubsection
804
805\startsubsection[title={\cbk {start_file}}]
806
807\topicindex{callbacks+files}
808
809\startfunctioncall
810function(category,filename)
811    -- no return values
812end
813\stopfunctioncall
814
815This callback replaces the code that \LUATEX\ prints when a file is opened like
816\type {(filename} for regular files. The category is a number:
817
818\starttabulate[|c|l|]
819\DB value  \BC meaning \NC \NR
820\TB
821\NC 1 \NC a normal data file, like a \TEX\ source \NC \NR
822\NC 2 \NC a font map coupling font names to resources \NC \NR
823\NC 3 \NC an image file (\type {png}, \type {pdf}, etc) \NC \NR
824\NC 4 \NC an embedded font subset \NC \NR
825\NC 5 \NC a fully embedded font \NC \NR
826\LL
827\stoptabulate
828
829\stopsubsection
830
831\startsubsection[title={\cbk {stop_file}}]
832
833\topicindex{callbacks+files}
834
835\startfunctioncall
836function(category)
837    -- no return values
838end
839\stopfunctioncall
840
841This callback replaces the code that \LUATEX\ prints when a file is closed like
842the \type {)} for regular files.
843
844\stopsubsection
845
846\startsubsection[title={\cbk {wrapup_run}}]
847
848\topicindex{callbacks+wrapping up}
849
850This callback is called after the \PDF\ and log files are closed. Use it at your own
851risk.
852
853\stopsubsection
854
855\stopsection
856
857\startsection[title={Font-related callbacks}][library=callback]
858
859\startsubsection[title={\cbk {define_font}}]
860
861\topicindex{callbacks+fonts}
862
863\startfunctioncall
864function(<string> name, <number> size)
865    return <number> id
866end
867\stopfunctioncall
868
869The string \type {name} is the filename part of the font specification, as given
870by the user.
871
872The number \type {size} is a bit special:
873
874\startitemize[packed]
875\startitem
876    If it is positive, it specifies an \quote{at size} in scaled points.
877\stopitem
878\startitem
879    If it is negative, its absolute value represents a \quote {scaled} setting
880    relative to the design size of the font.
881\stopitem
882\stopitemize
883
884The font can be defined with \type {font.define} which returns a font identifier
885that can be returned in the callback. So, contrary to \LUATEX, in \LUAMETATEX\
886we only accept a number.
887
888The internal structure of the \type {font} table that is passed to \type
889{font.define} is explained in \in {chapter} [fonts]. That table is saved
890internally, so you can put extra fields in the table for your later \LUA\ code to
891use. In alternative, \type {retval} can be a previously defined fontid. This is
892useful if a previous definition can be reused instead of creating a whole new
893font structure.
894
895Setting this callback to \type {false} is pointless as it will prevent font
896loading completely but will nevertheless generate errors.
897
898\stopsubsection
899
900\startsubsection[title={\cbk {missing_character} and \cbk {process_character}}]
901
902\topicindex{callbacks+fonts}
903\topicindex{callbacks+characters}
904
905This callback is triggered when a character node is created and the font doesn't
906have the requested character.
907
908\startfunctioncall
909function(<node> glyph, <number> font, <number> character)
910    -- no return value
911end
912\stopfunctioncall
913
914The \type {process_character} callback is experimental and gets called when a
915glyph node is created and the callback field in a character is set.
916
917\startfunctioncall
918function(<number> font, <number> character)
919    -- no return value
920end
921\stopfunctioncall
922
923\stopsubsection
924
925\stopsection
926
927\startsection[title=Reporting]
928
929\startsubsection[title={\cbk {show_whatsit}}]
930
931\topicindex{callbacks+whatsits}
932
933Because we only have a generic whatsit it is up to the macro package to provide
934details when tracing them.
935
936\startfunctioncall
937function(<node> whatsit, <number> indentation,
938    <number> tracinglevel, <number> currentlevel, <number> inputlevel)
939    -- no return value
940end
941\stopfunctioncall
942
943The indentation tells how many periods are to be typeset if you want to be
944compatible with the rest of tracing. The tracinglevels indicates if the current
945level and\|/or input level are shown cf. \prm {tracinglevels}. Of course one
946is free to show whatever in whatever way suits the whatsit best.
947
948\stopsubsection
949
950\startsubsection[title={\cbk {get_attribute}}]
951
952\topicindex{callbacks+attributes}
953
954Because attributes are abstract pairs of indices and values the reported
955properties makes not much sense and are very macro package (and user) dependent.
956This callback permits more verbose reporting by the engine when tracing is
957enabled.
958
959\startfunctioncall
960function(<number> index, <number> value)
961    return <string>, <string>
962end
963\stopfunctioncall
964
965\stopsubsection
966
967\startsubsection[title={\cbk {get_noad_class}}]
968
969\topicindex{callbacks+classes}
970
971We have built|-|in math classes but there can also be user defined ones. This
972callback can be used to report more meaningful strings instead of numbers when
973tracing.
974
975\startfunctioncall
976function(<number> class)
977    return <string>
978end
979\stopfunctioncall
980
981\stopsubsection
982
983\startsubsection[title={\cbk {trace_memory}}]
984
985When the engine starts all kind of memory is pre|-|allocated> depending on the
986configuration more gets allocated when a category runs out of memory. The
987\LUAMETATEX\ engine is more dynamic than \LUATEX. If this callback is set it will
988get called as follows:
989
990\startfunctioncall
991function(<string> category, <boolean> success)
992    -- no return value
993end
994\stopfunctioncall
995
996The boolean indicates if the allocation has been successful. One can best quit
997the run when this one is \type {false}, if the engine doesn't already do that.
998
999\stopsubsection
1000
1001\startsubsection[title={\type {hpack_quality}}]
1002
1003\topicindex{callbacks+packing}
1004
1005This callback can be used to intercept the overfull messages that can result from
1006packing a horizontal list (as happens in the par builder). The function takes a
1007few arguments:
1008
1009\startfunctioncall
1010function(<string> incident, <number> detail, <node> head, <number> first,
1011         <number> last)
1012    return <node> whatever
1013end
1014\stopfunctioncall
1015
1016The incident is one of \type {overfull}, \type {underfull}, \type {loose} or
1017\type {tight}. The detail is either the amount of overflow in case of \type
1018{overfull}, or the badness otherwise. The head is the list that is constructed
1019(when protrusion or expansion is enabled, this is an intermediate list).
1020Optionally you can return a node, for instance an overfull rule indicator. That
1021node will be appended to the list (just like \TEX's own rule would).
1022
1023\stopsubsection
1024
1025\startsubsection[title={\type {vpack_quality}}]
1026
1027\topicindex{callbacks+packing}
1028
1029This callback can be used to intercept the overfull messages that can result from
1030packing a vertical list (as happens in the page builder). The function takes a
1031few arguments:
1032
1033\startfunctioncall
1034function(<string> incident, <number> detail, <node> head, <number> first,
1035    <number> last)
1036end
1037\stopfunctioncall
1038
1039The incident is one of \type {overfull}, \type {underfull}, \type {loose} or
1040\type {tight}. The detail is either the amount of overflow in case of \type
1041{overfull}, or the badness otherwise. The head is the list that is constructed.
1042
1043\stopsubsection
1044
1045\startsubsection[title={\type {show_lua_call}}]
1046
1047\topicindex{callbacks+lua}
1048
1049This one can be used to help reporting definitions that relate to \LUA\ calls to
1050be more meaningful when tracing.
1051
1052\startfunctioncall
1053function(<string> name, <number> index)
1054    return <string>
1055end
1056\stopfunctioncall
1057
1058\stopsubsection
1059
1060\startsubsection[title={\type {handle_overload}}]
1061
1062\topicindex{callbacks+overload}
1063
1064This is one of the few callbacks that is aimed at \CONTEXT: it relates to overload
1065protection of macros and other variables.
1066
1067\startfunctioncall
1068function(<boolean> error, <number> overload, <string> csname, <number> flags)
1069    -- no return values
1070end
1071\stopfunctioncall
1072
1073The overload is determined by:
1074
1075\starttabulate[|c|l|c|c|c|c|c|]
1076\DB   \BC         \BC immutable \BC permanent \BC primitive \BC frozen \BC instance \NC \NR
1077\TB
1078\NC 1 \NC warning \NC \star     \NC \star     \NC \star     \NC        \NC          \NC \NR
1079\NC 2 \NC error   \NC \star     \NC \star     \NC \star     \NC        \NC          \NC \NR
1080\NC 3 \NC warning \NC \star     \NC \star     \NC \star     \NC \star  \NC          \NC \NR
1081\NC 4 \NC error   \NC \star     \NC \star     \NC \star     \NC \star  \NC          \NC \NR
1082\NC 5 \NC warning \NC \star     \NC \star     \NC \star     \NC \star  \NC \star    \NC \NR
1083\NC 6 \NC error   \NC \star     \NC \star     \NC \star     \NC \star  \NC \star    \NC \NR
1084\LL
1085\stoptabulate
1086
1087This relates to the optional prefixed that can be used when defining and setting
1088quantities and is therefore also a bit of a playground. All macros and aliases in
1089\CONTEXT\ are classified this way.
1090
1091\stopsection
1092
1093\stopchapter
1094
1095\stopcomponent
1096