1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
|
\input minim-doc.sty
This chapter describes the programming helper modules on which all the above
modules depend. It mainly concerns register allocation, callback management and
format file inclusion.
They can be loaded separately by saying ⟦\input minim-alloc⟧;
thereafter, you can use ⟦local M = require('minim-alloc')⟧ to access the lua
interface.
In this chapter, when discussing lua functions, you are assumed to have issued
the latter statement, so that the table ⟦M⟧ refers to the contents of this
module.
The callback-related code lives in a separate file that can and must be loaded
separately as ⟦local C = require('minim-callbacks')⟧. This is the only file in
this collection that does not itself depend on the minim-alloc module.
There is a large functional overlap between this module and the ltluatex
package. You can use both at the same time, however, and the order in which you
load both packages should not matter.
\section Format files
A major motivation for writing this module (and not, instead, depending on
⟦ltluatex.tex⟧) is the ability to write lua-heavy code that can be safely
included in format files.
For this purpose, the register allocation functions described below allow
ensuring that the allocation is made only once.
Apart from registers, you need only do two more things to make your code format
file safe. The first is saying ⟦*M.remember('your-file.lua')⟧ somewhere,
anywhere. This will mark your file for inclusion in the format. At the start of
every job, all remembered files will be executed (in order) and their return
values will be stored to be retrieved whenever you say ⟦require('your-file')⟧.
Note that while this feature does not improve speed in any meaningful way, it
will ensure the lua file used by the format is identical to the one used to
create it.
It does mean, however, that your file may be executed twice: once when building
the format and once when the format is used. In most cases (e.g. callback
registration) this is exactly what you want.
Sometimes however, you may need to store variable (configurable) data in the
format file.
You can do this by saying
⟦*local t = M.saved_table('identifier', default-table)⟧.
This will retrieve the table from the format file if possible; otherwise, it
will return ⟦default-table⟧ and mark it to be saved to the format. A missing
second argument is equivalent to an empty table.
Saved tables may only contain (arbitrary but non-cyclic nestings of) tables,
numbers and strings.
\section Register allocation
For allocating the new luatex registers, you can use the following:
⟦*\newfunction⟧,
⟦*\newattribute⟧,
⟦*\newwhatsit⟧,
⟦*\newluabytecode⟧,
⟦*\newluachunkname⟧,
⟦*\newcatcodetable⟧ and
⟦*\newuserrule⟧.
Note the one difference with ltluatex, which has ⟦\newluafunction⟧ instead.
(The reason for this is that ltluatex, instead of a more sensible method, uses
this macro for determining whether it has been read before.)
Internally, the very same counts are used for keeping track of register
allocation as in ltluatex.
Their effect should therefore be identical in all circumstances, with one
exception:
no bounds checking is performed on any allocation macro defined by minim.
Please do not go and use more than sixty five thousand different whatsits.
All the above and all traditional registers can be allocated from within lua as
well, using ⟦*M.new_count('name')⟧, ⟦*M.new_whatsit('name')⟧ etc. All return
the allocated number. The (optional) string ⟦name⟧ prevents the same allocation
from being made twice: if another register has been retrieved with the same
name, the number of that register will be returned. You will need this when you
want to allow your lua code to be included in a format file; it has nothing to
do with the tex-side ⟦\countdef⟧ and the like.
For the new allocation macros listed above and (as a special case) for
⟦\newbox⟧,
after saying ⟦\newwhatsit\name⟧, the call ⟦M.new_whatsit('name')⟧ will return
the number of ⟦\name⟧. For the other (older) allocation macros, this is not the
case. After all, because of the ⟦\countdef⟧ etc. included in ⟦\newcount⟧ etc.
you can already use ⟦tex.count['name']⟧ etc. for retrieving tex-side
allocations from lua. The exceptions to this are ⟦\newbox⟧, which is why it is
included with the new macros, and ⟦\newattribute⟧, for which you can use both
methods.
Besides ⟦\newluachunkname\name⟧, you can also use
⟦*\setluachunkname \name {actual name}⟧
to enter the value of the name directly.
Finally, for the registers for which etex defines a local allocation macro (and
for those only), you can use ⟦*M.local_count()⟧ etc. These allocation functions
take no parameters.
\section Callbacks
As noted at the beginning of this chapter, the callback functions are only
available after you say ⟦local C = require('minim-callbacks')⟧.
This module will override the primitive callback functions with its own
⟦*C.register⟧, ⟦*C.find⟧ and ⟦*C.list⟧; the original primitive functions can be
found in the ⟦*C.primitives⟧ table.
The simple function of this module is allowing multiple callbacks to co-exist.
Different callbacks call for different implementations, and some callbacks can
only contain a single function.
Any callbacks that are already assigned before loading this module will be
preserved; this includes the ltluatex callback mechanism if it has already been
installed.
You can create your own callbacks with ⟦*C.new_callback(name, type)⟧. The ⟦type⟧
should be one of the types mentioned below or ⟦'single'⟧ for callbacks that
allow only one function. If the ⟦name⟧ is that of a primitive callback, new
registrations will target your new callback.
You can call the new callback with ⟦*C.call_callback(name, ...)⟧, adding any
number of parameters.
Callbacks of type ⟦*node⟧ operate on a node list: for these, all registered
functions will be called in order, each function receiving the result of the
last.
After one function returns ⟦false⟧, no others will be called.
Callbacks of this type are
⟦pre_linebreak_filter⟧,
⟦post_linebreak_filter⟧,
⟦hpack_filter⟧,
⟦vpack_filter⟧,
⟦pre_output_filter⟧ and
⟦mlist_to_mlist⟧.
There is no way of unregistering callbacks of this type.
Similarly, for the ⟦*data⟧ callbacks
⟦process_input_buffer⟧,
⟦process_output_buffer⟧ and
⟦process_jobname⟧,
all registered functions will be called in order on the output of the previous.
Returning ⟦false⟧ will in this case result in the output of the previous
function passing to the next.
For ⟦*stack⟧ callbacks, a stack is kept and only the top function on the stack
will be called. These are
⟦mlist_to_hlist⟧,
⟦hpack_quality⟧,
⟦vpack_quality⟧,
⟦hyphenate⟧,
⟦linebreak_filter⟧,
⟦buildpage_filter⟧ and
⟦build_page_insert⟧.
Register ⟦nil⟧ at the callback to pop a function off the stack.
Finally, for the ⟦*simple⟧ callbacks
⟦contribute_filter⟧,
⟦pre_dump⟧,
⟦wrapup_run⟧,
⟦finish_pdffile⟧,
⟦finish_pdfpage⟧,
⟦insert_local_par⟧,
⟦ligaturing⟧,
⟦kerning⟧ and
⟦process_rule⟧.
all registered functions are called in order with the same arguments.
The new ⟦*mlist_to_mlist⟧ callback is called before ⟦mlist_to_hlist⟧ and should
not convert noads to nodes.
If you create a new callback with a number for a name, that callback will
replace the ⟦*process_rule⟧ callback when its number matches the index property
of the rule.
\section Miscellaneous functions
This section describes functions and macros that are internal to this package,
but might be of general usefulness.
For instance, you might find the function ⟦*M.table_to_text(table)⟧ useful when
debugging lua code.
The small functions
⟦*M.msg(...)⟧, ⟦*M.log(...)⟧ and ⟦*M.err(...)⟧
include a call to ⟦M.string.format⟧;
additionally,
⟦*M.amsg(...)⟧ and ⟦*M.alog(...)⟧
do not start a new line.
Very useful is ⟦*M.luadef('csname', function, ...)⟧ for defining primitive-like
tex macros from lua: ⟦function⟧ can be any function (it will be assigned a lua
function register) and at the place of the dots you may append ⟦'protected'⟧
and/or ⟦'global'⟧.
Both ⟦*M.unset⟧ and ⟦*\unset⟧ contain the value ⟦-0x7FFFFFFF⟧ that can be used
for clearing attributes.
On the tex side, ⟦*\voidbox⟧, ⟦*\ignore⟧, ⟦*\spacechar⟧, ⟦*\unbrace⟧,
⟦*\firstoftwo⟧ and ⟦*\secondoftwo⟧ should be self-explanatory and
uncontroversial additions. For looking ahead, you can use
⟦*\nextif \token {executed if present} {executed if not}⟧
or its siblings ⟦*\nextifx⟧ and ⟦*\nextifcat⟧.
For defining macros with optional arguments, ⟦*\withoptions[default]{code}⟧
will ensure something within square brackets follows ⟦code⟧.
Finally, ⟦*\splitcommalist {code} {list}⟧ will apply ⟦code⟧ to every nonempty
item on a comma-separated ⟦list⟧.
Items of the list will be re-tokenised and have surrounding spaces removed.
This macro is fully expandable.
Because of their usefulness and simplicity, these macros have been made
available without special characters in their names; I hope you can tolerate
their presence. Please let me know if their names clash with something
important.
\endinput
|