summaryrefslogtreecommitdiff
path: root/macros/luatex/generic/minim/minim-alloc.doc
blob: fa08988bf4334f0447456c966c251992e0c2895c (plain)
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