Debian Codegraph @

texmf-dist/doc/luatex/minim/minim-alloc.doc

raw
1
2 \input minim-doc.sty
3
4 \chapter Programming macros
5
6 This chapter describes the programming helper modules on which all the above
7 modules depend. It mainly concerns register allocation, callback management and
8 format file inclusion.
9
10 They can be loaded separately by saying ⟦\input minim-alloc⟧;
11 thereafter, you can use ⟦local M = require('minim-alloc')⟧ to access the lua
12 interface.
13 In this chapter, when discussing lua functions, you are assumed to have issued
14 the latter statement, so that the table ⟦M⟧ refers to the contents of this
15 module.
16
17 The callback-related code lives in a separate file that can and must be loaded
18 separately as ⟦local C = require('minim-callbacks')⟧. This is the only file in
19 this collection that does not itself depend on the minim-alloc module.
20
21 There is a large functional overlap between this module and the ltluatex
22 package. You can use both at the same time, however, and the order in which you
23 load both packages should not matter.
24
25 \section Format files
26
27 A major motivation for writing this module (and not, instead, depending on
28 ltluatex) is the ability to write lua-heavy code that can be safely
29 included in format files.
30 For this purpose, the register allocation functions described below allow
31 ensuring that the allocation is made only once.
32
33 Apart from registers, you need only do two more things to make your code format
34 file safe. The first is saying ⟦*M.remember('your-file.lua')⟧ somewhere,
35 anywhere. This will mark your file for inclusion in the format. At the start of
36 every job, all remembered files will be executed (in order) and their return
37 values will be stored to be retrieved whenever you say ⟦require('your-file')⟧.
38 Note that while this feature does not improve speed in any meaningful way, it
39 will ensure the lua file used by the format is identical to the one used to
40 create it.
41
42 It does mean, however, that your file may be executed twice: once when building
43 the format and once when the format is used. In most cases (e.g. callback
44 registration) this is exactly what you want.
45 Sometimes however, you may need to store variable (configurable) data in the
46 format file.
47 You can do this by saying
48 ⟦*local t = M.saved_table('identifier', default-table)⟧.
49 This will retrieve the table from the format file if possible; otherwise, it
50 will return ⟦default-table⟧ and mark it to be saved to the format. A missing
51 second argument is equivalent to an empty table.
52 Saved tables may only contain (arbitrary but non-cyclic nestings of) tables,
53 numbers and strings.
54
55 \section Register allocation
56
57 For allocating the new luatex registers, you can use the following:
58 ⟦*\newfunction⟧,
59 ⟦*\newattribute⟧,
60 ⟦*\newwhatsit⟧,
61 ⟦*\newluabytecode⟧,
62 ⟦*\newluachunkname⟧,
63 ⟦*\newcatcodetable⟧ and
64 ⟦*\newuserrule⟧.
65 Note the one difference with ltluatex, which has ⟦\newluafunction⟧ instead.
66 (The reason for this is that ltluatex, instead of a more sensible method, uses
67 this macro for determining whether it has been read before.)
68 Internally, the very same counts are used for keeping track of register
69 allocation as in ltluatex.
70 Their effect should therefore be identical in all circumstances, with one
71 exception:
72 no bounds checking is performed on any allocation macro defined by minim.
73 Please do not go and use more than sixty five thousand different whatsits.
74
75 All the above and all traditional registers can be allocated from within lua as
76 well, using ⟦*M.new_count('name')⟧, ⟦*M.new_whatsit('name')⟧ etc. All return
77 the allocated number. The (optional) string ⟦name⟧ prevents the same allocation
78 from being made twice: if another register has been retrieved with the same
79 name, the number of that register will be returned. You will need this when you
80 want to allow your lua code to be included in a format file; it has nothing to
81 do with the tex-side ⟦\countdef⟧ and the like.
82
83 If you want to access from lua a register defined in tex, the function
84 ⟦*M.registernumber('name')⟧ will give you the index of register ⟦\name⟧.
85
86 Besides ⟦\newluachunkname\name⟧, you can also use
87 ⟦*\setluachunkname \name {actual name}⟧
88 to enter the value of the name directly.
89
90 Finally, for the registers for which etex defines a local allocation macro (and
91 for those only), you can use ⟦*M.local_count()⟧ etc. These allocation functions
92 take no parameters.
93
94
95 \section Callbacks
96
97 As noted at the beginning of this chapter, the callback functions are only
98 available after you say ⟦local C = require('minim-callbacks')⟧.
99
100 The simple function of this module is allowing multiple callbacks to co-exist.
101 Different callbacks call for different implementations, and some callbacks can
102 only contain a single function. Its interface matches the primitive interface,
103 with ⟦*C.register(callback, fn)⟧, ⟦*C.find(callback)⟧ and ⟦*C.list()⟧ taking
104 the same arguments. In addition to these, ⟦*C.deregister(fn)⟧ will allow you to
105 remove a callback. This is necessary when you want to remove a callback from
106 a list or from the bottom of a stack. The ⟦fn⟧ variable should point to the
107 same object.
108
109 Any callbacks that are already assigned before loading this module will be
110 preserved and the primitive callback interface is still available, though
111 callbacks registered through the latter will actually use the new functions.
112 Ltluatex may be loaded either before or after this module.
113
114 You can create your own callbacks with ⟦*C.new_callback(name, type)⟧. The
115 ⟦type⟧ should be one of the types mentioned below or ⟦'single'⟧ for callbacks
116 that allow only one function. If the ⟦name⟧ is that of a primitive callback,
117 new registrations will target your new callback.
118 You can call the new callback with ⟦*C.call_callback(name, ...)⟧, adding any
119 number of parameters.
120
121 Callbacks of type ⟦*node⟧ operate on a node list: for these, all registered
122 functions will be called in order, each function receiving the result of the
123 last.
124 After one function returns ⟦false⟧, no others will be called.
125 Callbacks of this type are
126 ⟦pre_output_filter⟧,
127 ⟦post_linebreak_filter⟧,
128 ⟦pre_linebreak_filter⟧,
129 ⟦hpack_filter⟧,
130 ⟦vpack_filter⟧
131 and ⟦mlist_to_mlist⟧.
132
133 Similarly, for the ⟦*data⟧ callbacks
134 ⟦process_jobname⟧,
135 ⟦process_output_buffer⟧ and
136 ⟦process_input_buffer⟧,
137 all registered functions will be called in order on the output of the previous.
138 Returning ⟦false⟧ will in this case result in the output of the previous
139 function passing to the next.
140
141 For ⟦*stack⟧ callbacks, a stack is kept and only the top function on the stack
142 will be called. These are
143 ⟦mlist_to_hlist⟧,
144 ⟦hpack_quality⟧,
145 ⟦vpack_quality⟧,
146 ⟦hyphenate⟧,
147 ⟦linebreak_filter⟧,
148 ⟦buildpage_filter⟧ and
149 ⟦build_page_insert⟧.
150 Register ⟦nil⟧ at the callback to pop a function off the stack.
151
152 Finally, for the ⟦*simple⟧ callbacks
153 ⟦uselanguage⟧,
154 ⟦contribute_filter⟧,
155 ⟦pre_dump⟧,
156 ⟦wrapup_run⟧,
157 ⟦finish_pdffile⟧,
158 ⟦finish_pdfpage⟧,
159 ⟦insert_local_par⟧,
160 ⟦ligaturing⟧,
161 ⟦kerning⟧ and
162 ⟦process_rule⟧.
163 all registered functions are called in order with the same arguments.
164
165 Three callbacks are new:
166 \startlist
167 \item 1. ⟦*mlist_to_mlist⟧ is called before ⟦mlist_to_hlist⟧ and should not
168 convert noads to nodes;
169 \item 2. ⟦*uselanguage⟧ is called from ⟦\uselanguage⟧ and receives the
170 language name (not the numerical id) as argument;
171 \item 3. ⟦*pre_shipout⟧ is called just before a box is shipped out,
172 opposite to ⟦finish_pdfpage⟧, and receives the to-be-shipped-out box number as
173 argument.
174
175 If you create a new callback with a number for a name, that callback will
176 replace the ⟦*process_rule⟧ callback when its number matches the index property
177 of the rule.
178
179
180 \section PDF resources
181
182 This package can perform sophisticated pdf resource management, assigning to
183 every page a resource object containing only the resources referenced on that
184 page. pdf resources are ⟦ExtGstate⟧, ⟦ColorSpace⟧, ⟦Pattern⟧ and ⟦Shading⟧
185 objects that have to be referenced by name (⟦/name⟧) instead of with the usual
186 object references (⟦n 0 R⟧).\footnote
187 {*}{This is of course also the case for ⟦Font⟧ resources, but those are
188 already managed by luatex’s pdf backend.}
189 Currently, the only other package managing pdf resources for plain tex is
190 tikz/pgf, and the latter does so by collecting all resources in a single
191 (global) resource object. That approach is not wrong per se, but may cause
192 other tools processing the resulting pdf to retain unneeded resources.
193 Both implementations can safely be used together, but since pgf does not keep
194 track of actual resource use, any resources defined through pgf will be added
195 to the resource dictionary of every subsequent page.
196
197 The resource management is implemented in minim-pdfresources.lua and
198 minim-pdfresources.tex, of which the tex file currently only includes pgf
199 compatibility code (and may thus be omitted in the absence of pgf). In the
200 following, ⟦R = require 'minim-pdfresources'⟧ is understood.
201
202 You must register resources before you use them. This can be done with
203 ⟦*R.add_resource(kind, name, resource)⟧, where ⟦kind⟧ is one of the resource
204 types, ⟦name⟧ is the name you want to use for it (without a preceding slash)
205 and ⟦resource⟧ is a table that may contain any data you want to associate with
206 the resource. In the ⟦resource⟧ table, either the key ⟦value⟧ must be present
207 (containing the (raw) contents of the resource; will be written to the pdf
208 as-is) or the key ⟦write⟧ (which must be a function that will be called once,
209 to generate the ⟦value⟧). Registered resources can be retrieved again with
210 ⟦*R.get_resource(kind, name)⟧.
211
212 You can refer to registered resources with the ⟦name⟧ you used to register
213 them. Whenever you do so, however, you must mark the reference with a special
214 ⟦late_lua⟧ node that will tell minim to include the resource in the resource
215 list for the page it appears on. These nodes can be created from lua with
216 ⟦*R.use_resource_node(kind, name)⟧ or directly inserted by tex with
217 ⟦*\withpdfresource {kind} {name}⟧ (the braces are optional).
218
219
220 \section Programming helpers
221
222 Optional keyword arguments to tex macros can be defined with help of
223 ⟦*M.options_scanner()⟧. An example from the definition of minim-pdf’s
224 ⟦\outline⟧:
225
226 ⟦ local s = M.options_scanner()
227 :keyword('open', 'closed')
228 :string('dest')
229 :scan()
230 s.title = token.scan_string()
231 M.add_bookmark(s)⟧
232
233 Here, the ⟦keyword⟧ function adds two opposite keywords: if one is present, its
234 value will be set to ⟦true⟧ and the other’s to ⟦false⟧ (the second keyword is
235 optional). The ⟦string⟧ function stores the result of ⟦token.scan_string⟧ under
236 its key. Of the same form you have ⟦int⟧, ⟦glue⟧, ⟦dimen⟧, ⟦argument⟧, ⟦word⟧
237 and ⟦list⟧. All these take an optional second argument: if ⟦true⟧ then the
238 keyword can be repeated and its values will be stored as a list.
239
240 The ⟦scan⟧ function, finally, scans all keywords, which may appear in any
241 order. You can give it a table with default values. In the example given above,
242 the argument ⟦s⟧ to ⟦M.add_bookmark⟧ will consist of a table with at most the
243 following entries: ⟦open⟧, ⟦closed⟧, ⟦dest⟧ and ⟦title⟧, though entries whose
244 keywords do not occur will not be present.
245
246 This function is particularly useful when used with
247 ⟦*M.luadef('csname', function, ...)⟧, which defines primitive-like tex macros
248 from lua. There, ⟦function⟧ can be any function (it will be assigned a lua
249 function register) and at the place of the dots you may append ⟦'protected'⟧
250 and/or ⟦'global'⟧.
251
252
253 \section Miscellaneous functions
254
255 The small functions
256 ⟦*M.msg(...)⟧, ⟦*M.log(...)⟧ and ⟦*M.err(...)⟧
257 include a call to ⟦M.string.format⟧;
258 additionally,
259 ⟦*M.amsg(...)⟧ and ⟦*M.alog(...)⟧
260 do not start a new line.
261
262 Both ⟦*M.unset⟧ and ⟦*\unset⟧ contain the value ⟦-0x7FFFFFFF⟧ that can be used
263 for clearing attributes.
264
265 When writing data to pdf literals, ⟦*M.pdf_string(...)⟧,
266 ⟦*M.pdf_name(...)⟧ and ⟦*M.pdf_date(...)⟧ may be useful: they produce strings
267 that can be written to the pdf directly. Surrounding ⟦<>⟧ or ⟦()⟧ characters or
268 a leading ⟦/⟧ will be included in the return value. The ⟦M.pdf_date⟧ function
269 expects a value of the form ⟦yyyy[-mm[-dd]]⟧ and returns a date of the form
270 ⟦(D:yyyymmdd)⟧.
271 The function ⟦M.pdf_string⟧ is also available to tex through the macro
272 ⟦*\pdfstring⟧.
273
274 Finally the function ⟦*M.table_to_text(table)⟧ may be useful when debugging lua
275 code: it dumps a table as a (lua-readable) string. Cyclic references will spin
276 in into an eternal loop, however.
277
278
279 \section Miscellaneous helper macros
280
281 On the tex side, ⟦*\voidbox⟧, ⟦*\ignore⟧, ⟦*\spacechar⟧, ⟦*\unbrace⟧,
282 ⟦*\firstoftwo⟧ and ⟦*\secondoftwo⟧ should be self-explanatory and
283 uncontroversial additions. ⟦*\Ucharcat⟧ works as in xetex. For looking ahead, you can use
284 ⟦*\nextif \token {executed if present} {executed if not}⟧
285 or its siblings ⟦*\nextifx⟧ and ⟦*\nextifcat⟧.
286 For defining macros with optional arguments, ⟦*\withoptions[default]{code}⟧
287 will ensure something within square brackets follows ⟦code⟧.
288
289 Finally, ⟦*\splitcommalist {code} {list}⟧ will apply ⟦code⟧ to every nonempty
290 item on a comma-separated ⟦list⟧.
291 Items of the list will be re-tokenised and have surrounding spaces removed.
292 This macro is fully expandable.
293
294 Because of their usefulness and simplicity, these macros have been made
295 available without special characters in their names; I hope you can tolerate
296 their presence. Please let me know if their names clash with something
297 important.
298
299 \endinput
300