Debian Codegraph @

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

raw
1 % language=us engine=luatex runpath=texruns:manuals/luatex
2
3 \environment luatex-style
4
5 \startcomponent luatex-nodes
6
7 \startchapter[reference=nodes,title={Nodes}]
8
9 \startsection[title={\LUA\ node representation}][library=node]
10
11 \topicindex {nodes}
12
13 \libindex {fields}
14 \libindex {subtypes}
15 \libindex {values}
16
17 \TEX's nodes are represented in \LUA\ as userdata objects with a variable set of
18 fields. In the following syntax tables, such as the type of such a userdata object
19 is represented as \syntax {<node>}.
20
21 The current return value of \type {node.types()} is:
22 \startluacode
23 for id, name in table.sortedhash(node.types()) do
24 context.type(name)
25 context(" (%s), ",id)
26 end
27 context.removeunwantedspaces()
28 context.removepunctuation()
29 \stopluacode
30 . % period
31
32 The \prm {lastnodetype} primitive is \ETEX\ compliant. The valid range is still
33 $[-1,15]$ and glyph nodes (formerly known as char nodes) have number~0 while
34 ligature nodes are mapped to~7. That way macro packages can use the same symbolic
35 names as in traditional \ETEX. Keep in mind that these \ETEX\ node numbers are
36 different from the real internal ones and that there are more \ETEX\ node types
37 than~15.
38
39 You can ask for a list of fields with \type {node.fields} and for valid subtypes
40 with \type {node.subtypes}. The \type {node.values} function reports some used
41 values. Valid arguments are \nod {dir}, \type {direction}, \nod {glue}, \whs
42 {pdf_literal}, \whs {pdf_action}, \whs {pdf_window} and \whs {color_stack}. Keep
43 in mind that the setters normally expect a number, but this helper gives you a
44 list of what numbers matter. For practical reason the \type {pagestate} values
45 are also reported with this helper.
46
47 \stopsection
48
49 \startsection[title={Main text nodes}]
50
51 \topicindex {nodes+text}
52
53 These are the nodes that comprise actual typesetting commands. A few fields are
54 present in all nodes regardless of their type, these are:
55
56 \starttabulate[|l|l|p|]
57 \DB field \BC type \BC explanation \NC \NR
58 \TB
59 \NC \type{next} \NC node \NC the next node in a list, or nil \NC \NR
60 \NC \type{id} \NC number \NC the node's type (\type {id}) number \NC \NR
61 \NC \type{subtype} \NC number \NC the node \type {subtype} identifier \NC \NR
62 \LL
63 \stoptabulate
64
65 The \type {subtype} is sometimes just a dummy entry because not all nodes
66 actually use the \type {subtype}, but this way you can be sure that all nodes
67 accept it as a valid field name, and that is often handy in node list traversal.
68 In the following tables \type {next} and \type {id} are not explicitly mentioned.
69
70 Besides these three fields, almost all nodes also have an \type {attr} field, and
71 there is a also a field called \type {prev}. That last field is always present,
72 but only initialized on explicit request: when the function \type {node.slide()}
73 is called, it will set up the \type {prev} fields to be a backwards pointer in
74 the argument node list. By now most of \TEX's node processing makes sure that the
75 \type {prev} nodes are valid but there can be exceptions, especially when the
76 internal magic uses a leading \nod {temp} nodes to temporarily store a state.
77
78 \subsection{\nod {hlist} nodes}
79
80 \starttabulate[|l|l|p|]
81 \DB field \BC type \BC explanation \NC \NR
82 \TB
83 \NC \type{subtype} \NC number \NC \showsubtypes{list} \NC \NR
84 \NC \type{attr} \NC node \NC list of attributes \NC \NR
85 \NC \type{width} \NC number \NC the width of the box \NC \NR
86 \NC \type{height} \NC number \NC the height of the box \NC \NR
87 \NC \type{depth} \NC number \NC the depth of the box \NC \NR
88 \NC \type{shift} \NC number \NC a displacement perpendicular to the character
89 progression direction \NC \NR
90 \NC \type{glue_order} \NC number \NC a number in the range $[0,4]$, indicating the
91 glue order \NC \NR
92 \NC \type{glue_set} \NC number \NC the calculated glue ratio \NC \NR
93 \NC \type{glue_sign} \NC number \NC 0 = \type {normal}, 1 = \type {stretching}, 2 =
94 \type {shrinking} \NC \NR
95 \NC \type{head/list} \NC node \NC the first node of the body of this list \NC \NR
96 \NC \type{dir} \NC string \NC the direction of this box, see~\in [dirnodes] \NC \NR
97 \LL
98 \stoptabulate
99
100 \topicindex {nodes+lists}
101 \topicindex {lists}
102
103 A warning: never assign a node list to the \type {head} field unless you are sure
104 its internal link structure is correct, otherwise an error may result.
105
106 Note: the field name \type {head} and \type {list} are both valid. Sometimes it
107 makes more sense to refer to a list by \type {head}, sometimes \type {list} makes
108 more sense.
109
110 \subsection{\nod {vlist} nodes}
111
112 \topicindex {nodes+lists}
113 \topicindex {lists}
114
115 This node is similar to \nod {hlist}, except that \quote {shift} is a displacement
116 perpendicular to the line progression direction, and \quote {subtype} only has
117 the values 0, 4, and~5.
118
119 \subsection{\nod {rule} nodes}
120
121 \topicindex {nodes+rules}
122 \topicindex {rules}
123
124 Contrary to traditional \TEX, \LUATEX\ has more \prm {rule} subtypes because we
125 also use rules to store reuseable objects and images. User nodes are invisible
126 and can be intercepted by a callback.
127
128 \starttabulate[|l|l|p|]
129 \DB field \BC type \BC explanation \NC \NR
130 \TB
131 \NC \type{subtype} \NC number \NC \showsubtypes {rule} \NC \NR
132 \NC \type{attr} \NC node \NC list of attributes \NC \NR
133 \NC \type{width} \NC number \NC the width of the rule where the special value
134 $-1073741824$ is used for \quote {running} glue dimensions \NC \NR
135 \NC \type{height} \NC number \NC the height of the rule (can be negative) \NC \NR
136 \NC \type{depth} \NC number \NC the depth of the rule (can be negative) \NC \NR
137 \NC \type{left} \NC number \NC shift at the left end (also subtracted from width) \NC \NR
138 \NC \type{right} \NC number \NC (subtracted from width) \NC \NR
139 \NC \type{dir} \NC string \NC the direction of this rule, see~\in[dirnodes] \NC \NR
140 \NC \type{index} \NC number \NC an optional index that can be referred to \NC \NR
141 \NC \type{transform} \NC number \NC an private variable (also used to specify outline width) \NC \NR
142 \LL
143 \stoptabulate
144
145 The \type {left} and type {right} keys are somewhat special (and experimental).
146 When rules are auto adapting to the surrounding box width you can enforce a shift
147 to the right by setting \type {left}. The value is also subtracted from the width
148 which can be a value set by the engine itself and is not entirely under user
149 control. The \type {right} is also subtracted from the width. It all happens in
150 the backend so these are not affecting the calculations in the frontend (actually
151 the auto settings also happen in the backend). For a vertical rule \type {left}
152 affects the height and \type {right} affects the depth. There is no matching
153 interface at the \TEX\ end (although we can have more keywords for rules it would
154 complicate matters and introduce a speed penalty.) However, you can just
155 construct a rule node with \LUA\ and write it to the \TEX\ input. The \type
156 {outline} subtype is just a convenient variant and the \type {transform} field
157 specifies the width of the outline.
158
159 \subsection{\nod {ins} nodes}
160
161 \topicindex {nodes+insertions}
162 \topicindex {insertions}
163
164 This node relates to the \prm {insert} primitive.
165
166 \starttabulate[|l|l|p|]
167 \DB field \BC type \BC explanation \NC \NR
168 \TB
169 \NC \type{subtype} \NC number \NC the insertion class \NC \NR
170 \NC \type{attr} \NC node \NC list of attributes \NC \NR
171 \NC \type{cost} \NC number \NC the penalty associated with this insert \NC \NR
172 \NC \type{height} \NC number \NC height of the insert \NC \NR
173 \NC \type{depth} \NC number \NC depth of the insert \NC \NR
174 \NC \type{head/list} \NC node \NC the first node of the body of this insert \NC \NR
175 \LL
176 \stoptabulate
177
178 There is a set of extra fields that concern the associated glue: \type {width},
179 \type {stretch}, \type {stretch_order}, \type {shrink} and \type {shrink_order}.
180 These are all numbers.
181
182 A warning: never assign a node list to the \type {head} field unless you are sure
183 its internal link structure is correct, otherwise an error may result. You can use
184 \type {list} instead (often in functions you want to use local variable with similar
185 names and both names are equally sensible).
186
187 \subsection{\nod {mark} nodes}
188
189 \topicindex {nodes+marks}
190 \topicindex {marks}
191
192 This one relates to the \prm {mark} primitive.
193
194 \starttabulate[|l|l|p|]
195 \DB field \BC type \BC explanation \NC \NR
196 \TB
197 \NC \type{subtype} \NC number \NC unused \NC \NR
198 \NC \type{attr} \NC node \NC list of attributes \NC \NR
199 \NC \type{class} \NC number \NC the mark class \NC \NR
200 \NC \type{mark} \NC table \NC a table representing a token list \NC \NR
201 \LL
202 \stoptabulate
203
204 \subsection{\nod {adjust} nodes}
205
206 \topicindex {nodes+adjust}
207 \topicindex {adjust}
208
209 This node comes from \prm {vadjust} primitive.
210
211 \starttabulate[|l|l|p|]
212 \DB field \BC type \BC explanation \NC \NR
213 \TB
214 \NC \type{subtype} \NC number \NC \showsubtypes{adjust} \NC \NR
215 \NC \type{attr} \NC node \NC list of attributes \NC \NR
216 \NC \type{head/list} \NC node \NC adjusted material \NC \NR
217 \LL
218 \stoptabulate
219
220 A warning: never assign a node list to the \type {head} field unless you are sure
221 its internal link structure is correct, otherwise an error may be the result.
222
223 \subsection{\nod {disc} nodes}
224
225 \topicindex {nodes+discretionaries}
226 \topicindex {discretionaries}
227
228 The \prm {discretionary} and \prm {-}, the \type {-} character but also the
229 hyphenation mechanism produces these nodes.
230
231 \starttabulate[|l|l|p|]
232 \DB field \BC type \BC explanation \NC \NR
233 \TB
234 \NC \type{subtype} \NC number \NC \showsubtypes{disc} \NC \NR
235 \NC \type{attr} \NC node \NC list of attributes \NC \NR
236 \NC \type{pre} \NC node \NC pointer to the pre|-|break text \NC \NR
237 \NC \type{post} \NC node \NC pointer to the post|-|break text \NC \NR
238 \NC \type{replace} \NC node \NC pointer to the no|-|break text \NC \NR
239 \NC \type{penalty} \NC number \NC the penalty associated with the break, normally
240 \prm {hyphenpenalty} or \prm {exhyphenpenalty} \NC \NR
241 \LL
242 \stoptabulate
243
244 The subtype numbers~4 and~5 belong to the \quote {of-f-ice} explanation given
245 elsewhere. These disc nodes are kind of special as at some point they also keep
246 information about breakpoints and nested ligatures.
247
248 The \type {pre}, \type {post} and \type {replace} fields at the \LUA\ end are in
249 fact indirectly accessed and have a \type {prev} pointer that is not \type {nil}.
250 This means that when you mess around with the head of these (three) lists, you
251 also need to reassign them because that will restore the proper \type {prev}
252 pointer, so:
253
254 \starttyping
255 pre = d.pre
256 -- change the list starting with pre
257 d.pre = pre
258 \stoptyping
259
260 Otherwise you can end up with an invalid internal perception of reality and
261 \LUATEX\ might even decide to crash on you. It also means that running forward
262 over for instance \type {pre} is ok but backward you need to stop at \type {pre}.
263 And you definitely must not mess with the node that \type {prev} points to, if
264 only because it is not really a node but part of the disc data structure (so
265 freeing it again might crash \LUATEX).
266
267 \subsection{\nod {math} nodes}
268
269 \topicindex {nodes+math}
270 \topicindex {math+nodes}
271
272 Math nodes represent the boundaries of a math formula, normally wrapped into
273 \type {$} signs.
274
275 \starttabulate[|l|l|p|]
276 \DB field \BC type \BC explanation \NC \NR
277 \TB
278 \NC \type{subtype} \NC number \NC \showsubtypes{math} \NC \NR
279 \NC \type{attr} \NC node \NC list of attributes \NC \NR
280 \NC \type{surround} \NC number \NC width of the \prm {mathsurround} kern \NC \NR
281 \LL
282 \stoptabulate
283
284 There is a set of extra fields that concern the associated glue: \type {width},
285 \type {stretch}, \type {stretch_order}, \type {shrink} and \type {shrink_order}.
286 These are all numbers.
287
288 \subsection{\nod {glue} nodes}
289
290 \topicindex {nodes+glue}
291 \topicindex {glue}
292
293 Skips are about the only type of data objects in traditional \TEX\ that are not a
294 simple value. They are inserted when \TEX\ sees a space in the text flow but also
295 by \prm {hskip} and \prm {vskip}. The structure that represents the glue
296 components of a skip is called a \nod {glue_spec}, and it has the following
297 accessible fields:
298
299 \starttabulate[|l|l|p|]
300 \DB field \BC type \BC explanation \NC \NR
301 \TB
302 \NC \type{width} \NC number \NC the horizontal or vertical displacement \NC \NR
303 \NC \type{stretch} \NC number \NC extra (positive) displacement or stretch amount \NC \NR
304 \NC \type{stretch_order} \NC number \NC factor applied to stretch amount \NC \NR
305 \NC \type{shrink} \NC number \NC extra (negative) displacement or shrink amount\NC \NR
306 \NC \type{shrink_order} \NC number \NC factor applied to shrink amount \NC \NR
307 \LL
308 \stoptabulate
309
310 The effective width of some glue subtypes depends on the stretch or shrink needed
311 to make the encapsulating box fit its dimensions. For instance, in a paragraph
312 lines normally have glue representing spaces and these stretch or shrink to make
313 the content fit in the available space. The \type {effective_glue} function that
314 takes a glue node and a parent (hlist or vlist) returns the effective width of
315 that glue item. When you pass \type {true} as third argument the value will be
316 rounded.
317
318 A \nod {glue_spec} node is a special kind of node that is used for storing a set
319 of glue values in registers. Originally they were also used to store properties
320 of glue nodes (using a system of reference counts) but we now keep these
321 properties in the glue nodes themselves, which gives a cleaner interface to \LUA.
322
323 The indirect spec approach was in fact an optimization in the original \TEX\
324 code. First of all it can save quite some memory because all these spaces that
325 become glue now share the same specification (only the reference count is
326 incremented), and zero testing is also a bit faster because only the pointer has
327 to be checked (this is no longer true for engines that implement for instance
328 protrusion where we really need to ensure that zero is zero when we test for
329 bounds). Another side effect is that glue specifications are read|-|only, so in
330 the end copies need to be made when they are used from \LUA\ (each assignment to
331 a field can result in a new copy). So in the end the advantages of sharing are
332 not that high (and nowadays memory is less an issue, also given that a glue node
333 is only a few memory words larger than a spec).
334
335 \starttabulate[|l|l|p|]
336 \DB field \BC type \BC explanation \NC \NR
337 \TB
338 \NC \type{subtype} \NC number \NC \showsubtypes{glue} \NC \NR
339 \NC \type{attr} \NC node \NC list of attributes \NC \NR
340 \NC \type{leader} \NC node \NC pointer to a box or rule for leaders \NC \NR
341 \LL
342 \stoptabulate
343
344 In addition there are the \type {width}, \type {stretch} \type {stretch_order},
345 \type {shrink}, and \type {shrink_order} fields. Note that we use the key \type
346 {width} in both horizontal and vertical glue. This suits the \TEX\ internals well
347 so we decided to stick to that naming.
348
349 A regular word space also results in a \type {spaceskip} subtype (this used to be
350 a \type {userskip} with subtype zero).
351
352 \subsection{\nod {kern} nodes}
353
354 \topicindex {nodes+kerns}
355 \topicindex {kerns}
356
357 The \prm {kern} command creates such nodes but for instance the font and math
358 machinery can also add them.
359
360 \starttabulate[|l|l|p|]
361 \DB field \BC type \BC explanation \NC \NR
362 \TB
363 \NC \type{subtype} \NC number \NC \showsubtypes{kern} \NC \NR
364 \NC \type{attr} \NC node \NC list of attributes \NC \NR
365 \NC \type{kern} \NC number \NC fixed horizontal or vertical advance \NC \NR
366 \LL
367 \stoptabulate
368
369 \subsection{\nod {penalty} nodes}
370
371 \topicindex {nodes+penalty}
372 \topicindex {penalty}
373
374 The \prm {penalty} command is one that generates these nodes.
375
376 \starttabulate[|l|l|p|]
377 \DB field \BC type \BC explanation \NC \NR
378 \TB
379 \NC \type{subtype} \NC number \NC \showsubtypes{penalty} \NC \NR
380 \NC \type{attr} \NC node \NC list of attributes \NC \NR
381 \NC \type{penalty} \NC number \NC the penalty value \NC \NR
382 \LL
383 \stoptabulate
384
385 The subtypes are just informative and \TEX\ itself doesn't use them. When you
386 run into an \type {linebreakpenalty} you need to keep in mind that it's a
387 accumulation of \type {club}, \type{widow} and other relevant penalties.
388
389 \subsection[glyphnodes]{\nod {glyph} nodes}
390
391 \topicindex {nodes+glyph}
392 \topicindex {glyphs}
393
394 These are probably the mostly used nodes and although you can push them in the
395 current list with for instance \prm {char} \TEX\ will normally do it for you when
396 it considers some input to be text.
397
398 \starttabulate[|l|l|p|]
399 \DB field \BC type \BC explanation \NC \NR
400 \TB
401 \NC \type{subtype} \NC number \NC bit field \NC \NR
402 \NC \type{attr} \NC node \NC list of attributes \NC \NR
403 \NC \type{char} \NC number \NC the character index in the font \NC \NR
404 \NC \type{font} \NC number \NC the font identifier \NC \NR
405 \NC \type{lang} \NC number \NC the language identifier \NC \NR
406 \NC \type{left} \NC number \NC the frozen \type {\lefthyphenmnin} value \NC \NR
407 \NC \type{right} \NC number \NC the frozen \type {\righthyphenmnin} value \NC \NR
408 \NC \type{uchyph} \NC boolean \NC the frozen \prm {uchyph} value \NC \NR
409 \NC \type{components} \NC node \NC pointer to ligature components \NC \NR
410 \NC \type{xoffset} \NC number \NC a virtual displacement in horizontal direction \NC \NR
411 \NC \type{yoffset} \NC number \NC a virtual displacement in vertical direction \NC \NR
412 \NC \type{width} \NC number \NC the (original) width of the character \NC \NR
413 \NC \type{height} \NC number \NC the (original) height of the character\NC \NR
414 \NC \type{depth} \NC number \NC the (original) depth of the character\NC \NR
415 \NC \type{expansion_factor} \NC number \NC the to be applied expansion_factor \NC \NR
416 \NC \type{data} \NC number \NC a general purpose field for users (we had room for it) \NC \NR
417 \LL
418 \stoptabulate
419
420 The \type {width}, \type {height} and \type {depth} values are read|-|only. The
421 \type {expansion_factor} is assigned in the par builder and used in the backend.
422
423 A warning: never assign a node list to the components field unless you are sure
424 its internal link structure is correct, otherwise an error may be result. Valid
425 bits for the \type {subtype} field are:
426
427 \starttabulate[|c|l|]
428 \DB bit \BC meaning \NC \NR
429 \TB
430 \NC 0 \NC character \NC \NR
431 \NC 1 \NC ligature \NC \NR
432 \NC 2 \NC ghost \NC \NR
433 \NC 3 \NC left \NC \NR
434 \NC 4 \NC right \NC \NR
435 \LL
436 \stoptabulate
437
438 See \in {section} [charsandglyphs] for a detailed description of the \type
439 {subtype} field.
440
441 The \type {expansion_factor} has been introduced as part of the separation
442 between font- and backend. It is the result of extensive experiments with a more
443 efficient implementation of expansion. Early versions of \LUATEX\ already
444 replaced multiple instances of fonts in the backend by scaling but contrary to
445 \PDFTEX\ in \LUATEX\ we now also got rid of font copies in the frontend and
446 replaced them by expansion factors that travel with glyph nodes. Apart from a
447 cleaner approach this is also a step towards a better separation between front-
448 and backend.
449
450 The \type {is_char} function checks if a node is a glyph node with a subtype still
451 less than 256. This function can be used to determine if applying font logic to a
452 glyph node makes sense. The value \type {nil} gets returned when the node is not
453 a glyph, a character number is returned if the node is still tagged as character
454 and \type {false} gets returned otherwise. When nil is returned, the id is also
455 returned. The \type {is_glyph} variant doesn't check for a subtype being less
456 than 256, so it returns either the character value or nil plus the id. These
457 helpers are not always faster than separate calls but they sometimes permit
458 making more readable tests. The \type {uses_font} helpers takes a node
459 and font id and returns true when a glyph or disc node references that font.
460
461 \subsection{\nod {boundary} nodes}
462
463 \topicindex {nodes+boundary}
464 \topicindex {boundary}
465
466 This node relates to the \prm {noboundary}, \prm {boundary}, \prm
467 {protrusionboundary} and \prm {wordboundary} primitives.
468
469 \starttabulate[|l|l|p|]
470 \DB field \BC type \BC explanation \NC \NR
471 \TB
472 \NC \type{subtype} \NC number \NC \showsubtypes{boundary} \NC \NR
473 \NC \type{attr} \NC node \NC list of attributes \NC \NR
474 \NC \type{value} \NC number \NC values 0--255 are reserved \NC \NR
475 \LL
476 \stoptabulate
477
478 \subsection{\nod {local_par} nodes}
479
480 \topicindex {nodes+paragraphs}
481 \topicindex {paragraphs}
482
483 This node is inserted at the start of a paragraph. You should not mess
484 too much with this one.
485
486 \starttabulate[|l|l|p|]
487 \DB field \BC type \BC explanation \NC \NR
488 \TB
489 \NC \type{attr} \NC node \NC list of attributes \NC \NR
490 \NC \type{pen_inter} \NC number \NC local interline penalty (from \lpr {localinterlinepenalty}) \NC \NR
491 \NC \type{pen_broken} \NC number \NC local broken penalty (from \lpr {localbrokenpenalty}) \NC \NR
492 \NC \type{dir} \NC string \NC the direction of this par. see~\in [dirnodes] \NC \NR
493 \NC \type{box_left} \NC node \NC the \lpr {localleftbox} \NC \NR
494 \NC \type{box_left_width} \NC number \NC width of the \lpr {localleftbox} \NC \NR
495 \NC \type{box_right} \NC node \NC the \lpr {localrightbox} \NC \NR
496 \NC \type{box_right_width} \NC number \NC width of the \lpr {localrightbox} \NC \NR
497 \LL
498 \stoptabulate
499
500 A warning: never assign a node list to the \type {box_left} or \type {box_right}
501 field unless you are sure its internal link structure is correct, otherwise an
502 error may result.
503
504 \subsection[dirnodes]{\nod {dir} nodes}
505
506 \topicindex {nodes+direction}
507 \topicindex {directions}
508
509 Direction nodes mark parts of the running text that need a change of direction and \
510 the \prm {textdir} command generates them.
511
512 \starttabulate[|l|l|p|]
513 \DB field \BC type \BC explanation \NC \NR
514 \TB
515 \NC \type{attr} \NC node \NC list of attributes \NC \NR
516 \NC \type{dir} \NC string \NC the direction (but see below) \NC \NR
517 \NC \type{level} \NC number \NC nesting level of this direction whatsit \NC \NR
518 \LL
519 \stoptabulate
520
521 Direction specifiers are three|-|letter combinations of \type {T}, \type {B},
522 \type {R}, and \type {L}. These are built up out of three separate items:
523
524 \startitemize[packed]
525 \startitem
526 the first is the direction of the \quote{top} of paragraphs
527 \stopitem
528 \startitem
529 the second is the direction of the \quote{start} of lines
530 \stopitem
531 \startitem
532 the third is the direction of the \quote{top} of glyphs
533 \stopitem
534 \stopitemize
535
536 However, only four combinations are accepted: \type {TLT}, \type {TRT}, \type
537 {RTT}, and \type {LTL}. Inside actual \nod {dir} nodes, the representation of
538 \nod {dir} is not a three|-|letter but a combination of numbers. When printed the
539 direction is indicated by a \type {+} or \type {-}, indicating whether the value
540 is pushed or popped from the direction stack.
541
542 \subsection{\nod {marginkern} nodes}
543
544 \topicindex {nodes+paragraphs}
545 \topicindex {paragraphs}
546 \topicindex {protrusion}
547
548 Margin kerns result from protrusion.
549
550 \starttabulate[|l|l|p|]
551 \DB field \BC type \BC explanation \NC \NR
552 \TB
553 \NC \type{subtype} \NC number \NC \showsubtypes{marginkern} \NC \NR
554 \NC \type{attr} \NC node \NC list of attributes \NC \NR
555 \NC \type{width} \NC number \NC the advance of the kern \NC \NR
556 \NC \type{glyph} \NC node \NC the glyph to be used \NC \NR
557 \LL
558 \stoptabulate
559
560 \stopsection
561
562 \startsection[title={Math noads}]
563
564 \topicindex {nodes+math}
565 \topicindex {math+nodes}
566
567 These are the so||called \quote {noad}s and the nodes that are specifically
568 associated with math processing. Most of these nodes contain subnodes so that the
569 list of possible fields is actually quite small. First, the subnodes:
570
571 \subsection{Math kernel subnodes}
572
573 Many object fields in math mode are either simple characters in a specific family
574 or math lists or node lists. There are four associated subnodes that represent
575 these cases (in the following node descriptions these are indicated by the word
576 \type {<kernel>}).
577
578 The \type {next} and \type {prev} fields for these subnodes are unused.
579
580 \subsection{\nod {math_char} and \nod {math_text_char} subnodes}
581
582 \starttabulate[|l|l|p|]
583 \DB field \BC type \BC explanation \NC \NR
584 \TB
585 \NC \type{attr} \NC node \NC list of attributes \NC \NR
586 \NC \type{char} \NC number \NC the character index \NC \NR
587 \NC \type{fam} \NC number \NC the family number \NC \NR
588 \LL
589 \stoptabulate
590
591 The \nod {math_char} is the simplest subnode field, it contains the character
592 and family for a single glyph object. The \nod {math_text_char} is a special
593 case that you will not normally encounter, it arises temporarily during math list
594 conversion (its sole function is to suppress a following italic correction).
595
596 \subsection{\nod {sub_box} and \nod {sub_mlist} subnodes}
597
598 \starttabulate[|l|l|p|]
599 \DB field \BC type \BC explanation \NC \NR
600 \TB
601 \NC \type{attr} \NC node \NC list of attributes \NC \NR
602 \NC \type{head/list} \NC node \NC list of nodes \NC \NR
603 \LL
604 \stoptabulate
605
606 These two subnode types are used for subsidiary list items. For \nod {sub_box},
607 the \type {head} points to a \quote {normal} vbox or hbox. For \nod {sub_mlist},
608 the \type {head} points to a math list that is yet to be converted.
609
610 A warning: never assign a node list to the \type {head} field unless you are sure
611 its internal link structure is correct, otherwise an error is triggered.
612
613 \subsection{\nod {delim} subnodes}
614
615 There is a fifth subnode type that is used exclusively for delimiter fields. As
616 before, the \type {next} and \type {prev} fields are unused.
617
618 \starttabulate[|l|l|p|]
619 \DB field \BC type \BC explanation \NC \NR
620 \TB
621 \NC \type{attr} \NC node \NC list of attributes \NC \NR
622 \NC \type{small_char} \NC number \NC character index of base character \NC \NR
623 \NC \type{small_fam} \NC number \NC family number of base character \NC \NR
624 \NC \type{large_char} \NC number \NC character index of next larger character \NC \NR
625 \NC \type{large_fam} \NC number \NC family number of next larger character \NC \NR
626 \LL
627 \stoptabulate
628
629 The fields \type {large_char} and \type {large_fam} can be zero, in that case the
630 font that is set for the \type {small_fam} is expected to provide the large
631 version as an extension to the \type {small_char}.
632
633 \subsection{Math core nodes}
634
635 First, there are the objects (the \TEX book calls them \quote {atoms}) that are
636 associated with the simple math objects: ord, op, bin, rel, open, close, punct,
637 inner, over, under, vcent. These all have the same fields, and they are combined
638 into a single node type with separate subtypes for differentiation.
639
640 Some noads have an option field. The values in this bitset are common:
641
642 \starttabulate[|l|r|]
643 \DB meaning \BC bits \NC \NR
644 \TB
645 \NC set \NC \type{0x08} \NC \NR
646 \NC internal \NC \type{0x00} + \type{0x08} \NC \NR
647 \NC internal \NC \type{0x01} + \type{0x08} \NC \NR
648 \NC axis \NC \type{0x02} + \type{0x08} \NC \NR
649 \NC no axis \NC \type{0x04} + \type{0x08} \NC \NR
650 \NC exact \NC \type{0x10} + \type{0x08} \NC \NR
651 \NC left \NC \type{0x11} + \type{0x08} \NC \NR
652 \NC middle \NC \type{0x12} + \type{0x08} \NC \NR
653 \NC right \NC \type{0x14} + \type{0x08} \NC \NR
654 \NC no sub script \NC \type{0x21} + \type{0x08} \NC \NR
655 \NC no super script \NC \type{0x22} + \type{0x08} \NC \NR
656 \NC no script \NC \type{0x23} + \type{0x08} \NC \NR
657 \LL
658 \stoptabulate
659
660 \subsection{simple \nod {noad} nodes}
661
662 \starttabulate[|l|l|p|]
663 \DB field \BC type \BC explanation \NC \NR
664 \TB
665 \NC \type{subtype} \NC number \NC \showsubtypes{noad} \NC \NR
666 \NC \type{attr} \NC node \NC list of attributes \NC \NR
667 \NC \type{nucleus} \NC kernel node \NC base \NC \NR
668 \NC \type{sub} \NC kernel node \NC subscript \NC \NR
669 \NC \type{sup} \NC kernel node \NC superscript \NC \NR
670 \NC \type{options} \NC number \NC bitset of rendering options \NC \NR
671 \LL
672 \stoptabulate
673
674 \subsection{\nod {accent} nodes}
675
676 \starttabulate[|l|l|p|]
677 \DB field \BC type \BC explanation \NC \NR
678 \TB
679 \NC \type{subtype} \NC number \NC \showsubtypes{accent} \NC \NR
680 \NC \type{nucleus} \NC kernel node \NC base \NC \NR
681 \NC \type{sub} \NC kernel node \NC subscript \NC \NR
682 \NC \type{sup} \NC kernel node \NC superscript \NC \NR
683 \NC \type{accent} \NC kernel node \NC top accent \NC \NR
684 \NC \type{bot_accent} \NC kernel node \NC bottom accent \NC \NR
685 \NC \type{fraction} \NC number \NC larger step criterium (divided by 1000) \NC \NR
686 \LL
687 \stoptabulate
688
689 \subsection{\nod {style} nodes}
690
691 \starttabulate[|l|l|p|]
692 \DB field \BC type \BC explanation \NC \NR
693 \TB
694 \NC \type{style} \NC string \NC contains the style \NC \NR
695 \LL
696 \stoptabulate
697
698 There are eight possibilities for the string value: one of \type {display},
699 \type {text}, \type {script}, or \type {scriptscript}. Each of these can have
700 be prefixed by \type {cramped}.
701
702 \subsection{\nod {choice} nodes}
703
704 \starttabulate[|l|l|p|]
705 \DB field \BC type \BC explanation \NC \NR
706 \TB
707 \NC \type{attr} \NC node \NC list of attributes \NC \NR
708 \NC \type{display} \NC node \NC list of display size alternatives \NC \NR
709 \NC \type{text} \NC node \NC list of text size alternatives \NC \NR
710 \NC \type{script} \NC node \NC list of scriptsize alternatives \NC \NR
711 \NC \type{scriptscript} \NC node \NC list of scriptscriptsize alternatives \NC \NR
712 \LL
713 \stoptabulate
714
715 Warning: never assign a node list to the \type {display}, \type {text}, \type
716 {script}, or \type {scriptscript} field unless you are sure its internal link
717 structure is correct, otherwise an error can occur.
718
719 \subsection{\nod {radical} nodes}
720
721 \starttabulate[|l|l|p|]
722 \DB field \BC type \BC explanation \NC \NR
723 \TB
724 \NC \type{subtype} \NC number \NC \showsubtypes{radical} \NC \NR
725 \NC \type{attr} \NC node \NC list of attributes \NC \NR
726 \NC \type{nucleus} \NC kernel node \NC base \NC \NR
727 \NC \type{sub} \NC kernel node \NC subscript \NC \NR
728 \NC \type{sup} \NC kernel node \NC superscript \NC \NR
729 \NC \type{left} \NC delimiter node \NC \NC \NR
730 \NC \type{degree} \NC kernel node \NC only set by \lpr {Uroot} \NC \NR
731 \NC \type{width} \NC number \NC required width \NC \NR
732 \NC \type{options} \NC number \NC bitset of rendering options \NC \NR
733 \LL
734 \stoptabulate
735
736 Warning: never assign a node list to the \type {nucleus}, \type {sub}, \type
737 {sup}, \type {left}, or \type {degree} field unless you are sure its internal
738 link structure is correct, otherwise an error can be triggered.
739
740 \subsection{\nod {fraction} nodes}
741
742 \starttabulate[|l|l|p|]
743 \DB field \BC type \BC explanation \NC \NR
744 \TB
745 \NC \type{attr} \NC node \NC list of attributes \NC \NR
746 \NC \type{width} \NC number \NC (optional) width of the fraction \NC \NR
747 \NC \type{num} \NC kernel node \NC numerator \NC \NR
748 \NC \type{denom} \NC kernel node \NC denominator \NC \NR
749 \NC \type{left} \NC delimiter node \NC left side symbol \NC \NR
750 \NC \type{right} \NC delimiter node \NC right side symbol \NC \NR
751 \NC \type{middle} \NC delimiter node \NC middle symbol \NC \NR
752 \NC \type{options} \NC number \NC bitset of rendering options \NC \NR
753 \LL
754 \stoptabulate
755
756 Warning: never assign a node list to the \type {num}, or \type {denom} field
757 unless you are sure its internal link structure is correct, otherwise an error
758 can result.
759
760 \subsection{\nod {fence} nodes}
761
762 \starttabulate[|l|l|p|]
763 \DB field \BC type \BC explanation \NC \NR
764 \TB
765 \NC \type{subtype} \NC number \NC \showsubtypes{fence} \NC \NR
766 \NC \type{attr} \NC node \NC list of attributes \NC \NR
767 \NC \type{delim} \NC delimiter node \NC delimiter specification \NC \NR
768 \NC \type{italic} \NC number \NC italic correction \NC \NR
769 \NC \type{height} \NC number \NC required height \NC \NR
770 \NC \type{depth} \NC number \NC required depth \NC \NR
771 \NC \type{options} \NC number \NC bitset of rendering options \NC \NR
772 \NC \type{class} \NC number \NC spacing related class \NC \NR
773 \LL
774 \stoptabulate
775
776 Warning: some of these fields are used by the renderer and might get adapted in
777 the process.
778
779 \stopsection
780
781 \startsection[title={Front|-|end whatsits}]
782
783 Whatsit nodes come in many subtypes that you can ask for them by running
784 \type {node.whatsits}:
785 \startluacode
786 for id, name in table.sortedpairs(node.whatsits()) do
787 context.type(name)
788 context(" (%s), ",id)
789 end
790 context.removeunwantedspaces()
791 context.removepunctuation()
792 \stopluacode
793 . % period
794
795 Some of them are generic and independent of the output mode and others are
796 specific to the chosen backend: \DVI\ or \PDF. Here we discuss the generic
797 font|-|end nodes nodes.
798
799 \subsection{\whs {open}}
800
801 \starttabulate[|l|l|p|]
802 \DB field \BC type \BC explanation \NC \NR
803 \TB
804 \NC \type{attr} \NC node \NC list of attributes \NC \NR
805 \NC \type{stream} \NC number \NC \TEX's stream id number \NC \NR
806 \NC \type{name} \NC string \NC file name \NC \NR
807 \NC \type{ext} \NC string \NC file extension \NC \NR
808 \NC \type{area} \NC string \NC file area (this may become obsolete) \NC \NR
809 \LL
810 \stoptabulate
811
812 \subsection{\whs {write}}
813
814 \starttabulate[|l|l|p|]
815 \DB field \BC type \BC explanation \NC \NR
816 \TB
817 \NC \type{attr} \NC node \NC list of attributes \NC \NR
818 \NC \type{stream} \NC number \NC \TEX's stream id number \NC \NR
819 \NC \type{data} \NC string \NC a string representing the token list to be written \NC \NR
820 \NC \type{value} \NC table \NC a table representing the token list to be written \NC \NR
821 \LL
822 \stoptabulate
823
824 \subsection{\whs {close}}
825
826 \starttabulate[|l|l|p|]
827 \DB field \BC type \BC explanation \NC \NR
828 \TB
829 \NC \type{attr} \NC node \NC list of attributes \NC \NR
830 \NC \type{stream} \NC number \NC \TEX's stream id number \NC \NR
831 \LL
832 \stoptabulate
833
834 \subsection{\whs {user_defined}}
835
836 User|-|defined whatsit nodes can only be created and handled from \LUA\ code. In
837 effect, they are an extension to the extension mechanism. The \LUATEX\ engine
838 will simply step over such whatsits without ever looking at the contents.
839
840 \starttabulate[|l|l|p|]
841 \DB field \BC type \BC explanation \NC \NR
842 \TB
843 \NC \type{attr} \NC node \NC list of attributes \NC \NR
844 \NC \type{user_id} \NC number \NC id number \NC \NR
845 \NC \type{type} \NC number \NC type of the value \NC \NR
846 \NC \type{value} \NC number \NC a \LUA\ number \NC \NR
847 \NC \NC node \NC a node list \NC \NR
848 \NC \NC string \NC a \LUA\ string \NC \NR
849 \NC \NC table \NC a \LUA\ table \NC \NR
850 \LL
851 \stoptabulate
852
853 The \type {type} can have one of six distinct values. The number is the \ASCII\
854 value if the first character of the type name (so you can use string.byte("l")
855 instead of \type {108}).
856
857 \starttabulate[|r|c|p|]
858 \DB value \BC meaning \BC explanation \NC \NR
859 \TB
860 \NC 97 \NC a \NC list of attributes (a node list) \NC \NR
861 \NC 100 \NC d \NC a \LUA\ number \NC \NR
862 \NC 108 \NC l \NC a \LUA\ value (table, number, boolean, etc) \NC \NR
863 \NC 110 \NC n \NC a node list \NC \NR
864 \NC 115 \NC s \NC a \LUA\ string \NC \NR
865 \NC 116 \NC t \NC a \LUA\ token list in \LUA\ table form (a list of triplets) \NC \NR
866 \LL
867 \stoptabulate
868
869 \subsection{\whs {save_pos}}
870
871 \starttabulate[|l|l|p|]
872 \DB field \BC type \BC explanation \NC \NR
873 \TB
874 \NC \type{attr} \NC node \NC list of attributes \NC \NR
875 \LL
876 \stoptabulate
877
878 \subsection{\whs {late_lua}}
879
880 \starttabulate[|l|l|p|]
881 \DB field \BC type \BC explanation \NC \NR
882 \TB
883 \NC \type{attr} \NC node \NC list of attributes \NC \NR
884 \NC \type{data} \NC string or function \NC the to be written information stored as \LUA\ value \NC \NR
885 \NC \type{token} \NC string \NC the to be written information stored as token list \NC \NR
886 \NC \type{name} \NC string \NC the name to use for \LUA\ error reporting \NC \NR
887 \LL
888 \stoptabulate
889
890 The difference between \type {data} and \type {string} is that on assignment, the
891 \type {data} field is converted to a token list, cf.\ use as \lpr {latelua}. The
892 \type {string} version is treated as a literal string.
893
894 When a function is used, it gets called with as first argument the node that triggers
895 the call.
896
897 \stopsection
898
899 \startsection[title={\DVI\ backend whatsits}]
900
901 \subsection{\whs {special}}
902
903 There is only one \DVI\ backend whatsit, and it just flushes its content to the
904 output file.
905
906 \starttabulate[|l|l|p|]
907 \DB field \BC type \BC explanation \NC \NR
908 \TB
909 \NC \type{attr} \NC node \NC list of attributes \NC \NR
910 \NC \type{data} \NC string \NC the \prm {special} information \NC \NR
911 \LL
912 \stoptabulate
913
914 \stopsection
915
916 \startsection[title={\PDF\ backend whatsits}]
917
918 \subsection{\whs {pdf_literal} and \whs {pdf_late_literal}}
919
920 \starttabulate[|l|l|p|]
921 \DB field \BC type \BC explanation \NC \NR
922 \TB
923 \NC \type{attr} \NC node \NC list of attributes \NC \NR
924 \NC \type{mode} \NC number \NC the \quote {mode} setting of this literal \NC \NR
925 \NC \type{data} \NC string \NC the to be written information stored as \LUA\ string \NC \NR
926 \NC \type{token} \NC string \NC the to be written information stored as token list \NC \NR
927 \LL
928 \stoptabulate
929
930 Possible mode values are:
931
932 \starttabulate[|c|p|]
933 \DB value \BC keyword \NC \NR
934 \TB
935 \NC 0 \NC \type{origin} \NC \NR
936 \NC 1 \NC \type{page} \NC \NR
937 \NC 2 \NC \type{direct} \NC \NR
938 \NC 3 \NC \type{raw} \NC \NR
939 \NC 4 \NC \type{text} \NC \NR
940 \LL
941 \stoptabulate
942
943 The higher the number, the less checking and the more you can run into trouble.
944 Especially the \type {raw} variant can produce bad \PDF\ so you can best check
945 what you generate.
946
947 \subsection{\whs {pdf_refobj}}
948
949 \starttabulate[|l|l|p|]
950 \DB field \BC type \BC explanation \NC \NR
951 \TB
952 \NC \type{attr} \NC node \NC list of attributes \NC \NR
953 \NC \type{objnum} \NC number \NC the referenced \PDF\ object number \NC \NR
954 \LL
955 \stoptabulate
956
957 \subsection{\whs {pdf_annot}}
958
959 \starttabulate[|l|l|p|]
960 \DB field \BC type \BC explanation \NC \NR
961 \TB
962 \NC \type{attr} \NC node \NC list of attributes \NC \NR
963 \NC \type{width} \NC number \NC the width (not used in calculations) \NC \NR
964 \NC \type{height} \NC number \NC the height (not used in calculations) \NC \NR
965 \NC \type{depth} \NC number \NC the depth (not used in calculations) \NC \NR
966 \NC \type{objnum} \NC number \NC the referenced \PDF\ object number \NC \NR
967 \NC \type{data} \NC string \NC the annotation data \NC \NR
968 \LL
969 \stoptabulate
970
971 \subsection{\whs {pdf_start_link}}
972
973 \starttabulate[|l|l|p|]
974 \DB field \BC type \BC explanation \NC \NR
975 \TB
976 \NC \type{attr} \NC node \NC list of attributes \NC \NR
977 \NC \type{width} \NC number \NC the width (not used in calculations) \NC \NR
978 \NC \type{height} \NC number \NC the height (not used in calculations) \NC \NR
979 \NC \type{depth} \NC number \NC the depth (not used in calculations) \NC \NR
980 \NC \type{objnum} \NC number \NC the referenced \PDF\ object number \NC \NR
981 \NC \type{link_attr} \NC table \NC the link attribute token list \NC \NR
982 \NC \type{action} \NC node \NC the action to perform \NC \NR
983 \LL
984 \stoptabulate
985
986 \subsection{\whs {pdf_end_link}}
987
988 \starttabulate[|l|l|p|]
989 \DB field \BC type \BC explanation \NC \NR
990 \TB
991 \NC \type{attr} \NC node \NC \NC \NR
992 \LL
993 \stoptabulate
994
995 \subsection{\whs {pdf_dest}}
996
997 \starttabulate[|l|l|p|]
998 \DB field \BC type \BC explanation \NC \NR
999 \TB
1000 \NC \type{attr} \NC node \NC list of attributes \NC \NR
1001 \NC \type{width} \NC number \NC the width (not used in calculations) \NC \NR
1002 \NC \type{height} \NC number \NC the height (not used in calculations) \NC \NR
1003 \NC \type{depth} \NC number \NC the depth (not used in calculations) \NC \NR
1004 \NC \type{named_id} \NC number \NC is the \type {dest_id} a string value? \NC \NR
1005 \NC \type{dest_id} \NC number \NC the destination id \NC \NR
1006 \NC \NC string \NC the destination name \NC \NR
1007 \NC \type{dest_type} \NC number \NC type of destination \NC \NR
1008 \NC \type{xyz_zoom} \NC number \NC the zoom factor (times 1000) \NC \NR
1009 \NC \type{objnum} \NC number \NC the \PDF\ object number; for structure references the \PDF\ object number of the linked structure element \NC \NR
1010 \LL
1011 \stoptabulate
1012
1013 \subsection{\whs {pdf_action}}
1014
1015 These are a special kind of items that only appear inside \PDF\ start link
1016 objects.
1017
1018 \starttabulate[|l|l|p|]
1019 \DB field \BC type \BC explanation \NC \NR
1020 \TB
1021 \NC \type{action_type} \NC number \NC the kind of action involved \NC \NR
1022 \NC \type{action_id} \NC number or string \NC token list reference or string \NC \NR
1023 %NC \type{named_id} \NC number \NC the index of the destination \NC \NR
1024 % a strange key but needed for latex; a probably downward incompable patch instead of a fix
1025 \NC \type{named_id} \NC number \NC are \type {dest_id} and \type {struct_id} string values? \NC \NR
1026 \NC \type{file} \NC string \NC the target filename \NC \NR
1027 \NC \type{new_window} \NC number \NC the window state of the target \NC \NR
1028 \NC \type{data} \NC string \NC the name of the destination \NC \NR
1029 % needed for latex and therefore equivalent to pdftex
1030 \NC \type{struct_id} \NC nil \NC the action does not reference a structure destination \NC \NR
1031 \NC \NC number \NC id of the referenced structure destination \NC \NR
1032 \NC \NC string \NC name of the referenced structure destination \NC \NR
1033 \LL
1034 \stoptabulate
1035
1036 Valid action types are:
1037
1038 \starttabulate[|l|l|]
1039 \DB value \BC meaning \NC \NR
1040 \TB
1041 \NC 0 \NC \type{page} \NC \NR
1042 \NC 1 \NC \type{goto} \NC \NR
1043 \NC 2 \NC \type{thread} \NC \NR
1044 \NC 3 \NC \type{user} \NC \NR
1045 \LL
1046 \stoptabulate
1047
1048 Valid window types are:
1049
1050 \starttabulate[|l|l|]
1051 \DB value \BC meaning \NC \NR
1052 \TB
1053 \NC 0 \NC \type{notset} \NC \NR
1054 \NC 1 \NC \type{new} \NC \NR
1055 \NC 2 \NC \type{nonew} \NC \NR
1056 \LL
1057 \stoptabulate
1058
1059 \subsection{\whs {pdf_thread}}
1060
1061 \starttabulate[|l|l|p|]
1062 \DB field \BC type \BC explanation \NC \NR
1063 \TB
1064 \NC \type{attr} \NC node \NC list of attributes \NC \NR
1065 \NC \type{width} \NC number \NC the width (not used in calculations) \NC \NR
1066 \NC \type{height} \NC number \NC the height (not used in calculations) \NC \NR
1067 \NC \type{depth} \NC number \NC the depth (not used in calculations) \NC \NR
1068 \NC \type{named_id} \NC number \NC is \type {tread_id} a string value? \NC \NR
1069 \NC \type{tread_id} \NC number \NC the thread id \NC \NR
1070 \NC \NC string \NC the thread name \NC \NR
1071 \NC \type{thread_attr} \NC number \NC extra thread information \NC \NR
1072 \LL
1073 \stoptabulate
1074
1075 \subsection{\whs {pdf_start_thread}}
1076
1077 \starttabulate[|l|l|p|]
1078 \DB field \BC type \BC explanation \NC \NR
1079 \TB
1080 \NC \type{attr} \NC node \NC list of attributes \NC \NR
1081 \NC \type{width} \NC number \NC the width (not used in calculations) \NC \NR
1082 \NC \type{height} \NC number \NC the height (not used in calculations) \NC \NR
1083 \NC \type{depth} \NC number \NC the depth (not used in calculations) \NC \NR
1084 \NC \type{named_id} \NC number \NC is \type {tread_id} a string value? \NC \NR
1085 \NC \type{tread_id} \NC number \NC the thread id \NC \NR
1086 \NC \NC string \NC the thread name \NC \NR
1087 \NC \type{thread_attr} \NC number \NC extra thread information \NC \NR
1088 \LL
1089 \stoptabulate
1090
1091 \subsection{\whs {pdf_end_thread}}
1092
1093 \starttabulate[|l|l|p|]
1094 \DB field \BC type \BC explanation \NC \NR
1095 \TB
1096 \NC \type{attr} \NC node \NC \NC \NR
1097 \LL
1098 \stoptabulate
1099
1100 \subsection{\whs {pdf_colorstack}}
1101
1102 \starttabulate[|l|l|p|]
1103 \DB field \BC type \BC explanation \NC \NR
1104 \TB
1105 \NC \type{attr} \NC node \NC list of attributes \NC \NR
1106 \NC \type{stack} \NC number \NC colorstack id number \NC \NR
1107 \NC \type{command} \NC number \NC command to execute \NC \NR
1108 \NC \type{data} \NC string \NC data \NC \NR
1109 \LL
1110 \stoptabulate
1111
1112 \subsection{\whs {pdf_setmatrix}}
1113
1114 \starttabulate[|l|l|p|]
1115 \DB field \BC type \BC explanation \NC \NR
1116 \TB
1117 \NC \type{attr} \NC node \NC list of attributes \NC \NR
1118 \NC \type{data} \NC string \NC data \NC \NR
1119 \LL
1120 \stoptabulate
1121
1122 \subsection{\whs {pdf_save}}
1123
1124 \starttabulate[|l|l|p|]
1125 \DB field \BC type \BC explanation \NC \NR
1126 \TB
1127 \NC \type{attr} \NC node \NC list of attributes \NC \NR
1128 \LL
1129 \stoptabulate
1130
1131 \subsection{\whs {pdf_restore}}
1132
1133 \starttabulate[|l|l|p|]
1134 \DB field \BC type \BC explanation \NC \NR
1135 \TB
1136 \NC \type{attr} \NC node \NC list of attributes \NC \NR
1137 \LL
1138 \stoptabulate
1139
1140 \stopsection
1141
1142 \startsection[title={The \type {node} library}][library=node]
1143
1144 \subsection {Introduction}
1145
1146 The \type {node} library contains functions that facilitate dealing with (lists
1147 of) nodes and their values. They allow you to create, alter, copy, delete, and
1148 insert \LUATEX\ node objects, the core objects within the typesetter.
1149
1150 \LUATEX\ nodes are represented in \LUA\ as userdata with the metadata type
1151 \type {luatex.node}. The various parts within a node can be accessed using
1152 named fields.
1153
1154 Each node has at least the three fields \type {next}, \type {id}, and \type {subtype}:
1155
1156 \startitemize[intro]
1157
1158 \startitem
1159 The \type {next} field returns the userdata object for the next node in a
1160 linked list of nodes, or \type {nil}, if there is no next node.
1161 \stopitem
1162
1163 \startitem
1164 The \type {id} indicates \TEX's \quote{node type}. The field \type {id} has a
1165 numeric value for efficiency reasons, but some of the library functions also
1166 accept a string value instead of \type {id}.
1167 \stopitem
1168
1169 \startitem
1170 The \type {subtype} is another number. It often gives further information
1171 about a node of a particular \type {id}, but it is most important when
1172 dealing with \quote {whatsits}, because they are differentiated solely based
1173 on their \type {subtype}.
1174 \stopitem
1175
1176 \stopitemize
1177
1178 The other available fields depend on the \type {id} (and for \quote {whatsits},
1179 the \type {subtype}) of the node.
1180
1181 Support for \nod {unset} (alignment) nodes is partial: they can be queried and
1182 modified from \LUA\ code, but not created.
1183
1184 Nodes can be compared to each other, but: you are actually comparing indices into
1185 the node memory. This means that equality tests can only be trusted under very
1186 limited conditions. It will not work correctly in any situation where one of the
1187 two nodes has been freed and|/|or reallocated: in that case, there will be false
1188 positives.
1189
1190 At the moment, memory management of nodes should still be done explicitly by the
1191 user. Nodes are not \quote {seen} by the \LUA\ garbage collector, so you have to
1192 call the node freeing functions yourself when you are no longer in need of a node
1193 (list). Nodes form linked lists without reference counting, so you have to be
1194 careful that when control returns back to \LUATEX\ itself, you have not deleted
1195 nodes that are still referenced from a \type {next} pointer elsewhere, and that
1196 you did not create nodes that are referenced more than once. Normally the setters
1197 and getters handle this for you.
1198
1199 There are statistics available with regards to the allocated node memory, which
1200 can be handy for tracing.
1201
1202 \subsection{\type {is_node}}
1203
1204 \topicindex {nodes+functions}
1205
1206 \libindex {is_node}
1207
1208 \startfunctioncall
1209 <boolean|integer> t =
1210 node.is_node(<any> item)
1211 \stopfunctioncall
1212
1213 This function returns a number (the internal index of the node) if the argument
1214 is a userdata object of type \type {<node>} and false when no node is passed.
1215
1216 \subsection{\type {types} and \type {whatsits}}
1217
1218 \libindex {types}
1219 \libindex {whatsits}
1220
1221 This function returns an array that maps node id numbers to node type strings,
1222 providing an overview of the possible top|-|level \type {id} types.
1223
1224 \startfunctioncall
1225 <table> t =
1226 node.types()
1227 \stopfunctioncall
1228
1229 \TEX's \quote {whatsits} all have the same \type {id}. The various subtypes are
1230 defined by their \type {subtype} fields. The function is much like \type {types},
1231 except that it provides an array of \type {subtype} mappings.
1232
1233 \startfunctioncall
1234 <table> t =
1235 node.whatsits()
1236 \stopfunctioncall
1237
1238 \subsection{\type {id}}
1239
1240 \libindex{id}
1241
1242 This converts a single type name to its internal numeric representation.
1243
1244 \startfunctioncall
1245 <number> id =
1246 node.id(<string> type)
1247 \stopfunctioncall
1248
1249 \subsection{\type {type} and \type {subtype}}
1250
1251 \libindex {type}
1252 \libindex {subtype}
1253
1254 If the argument is a number, then the next function converts an internal numeric
1255 representation to an external string representation. Otherwise, it will return
1256 the string \type {node} if the object represents a node, and \type {nil}
1257 otherwise.
1258
1259 \startfunctioncall
1260 <string> type =
1261 node.type(<any> n)
1262 \stopfunctioncall
1263
1264 This next one converts a single whatsit name to its internal numeric
1265 representation (\type {subtype}).
1266
1267 \startfunctioncall
1268 <number> subtype =
1269 node.subtype(<string> type)
1270 \stopfunctioncall
1271
1272 \subsection{\type {fields}}
1273
1274 \libindex {fields}
1275
1276 This function returns an array of valid field names for a particular type of
1277 node. If you want to get the valid fields for a \quote {whatsit}, you have to
1278 supply the second argument also. In other cases, any given second argument will
1279 be silently ignored.
1280
1281 \startfunctioncall
1282 <table> t =
1283 node.fields(<number> id)
1284 <table> t =
1285 node.fields(<number> id, <number> subtype)
1286 \stopfunctioncall
1287
1288 The function accepts string \type {id} and \type {subtype} values as well.
1289
1290 \subsection{\type {has_field}}
1291
1292 \libindex {has_field}
1293
1294 This function returns a boolean that is only true if \type {n} is
1295 actually a node, and it has the field.
1296
1297 \startfunctioncall
1298 <boolean> t =
1299 node.has_field(<node> n, <string> field)
1300 \stopfunctioncall
1301
1302 \subsection{\type {new}}
1303
1304 \libindex{new}
1305
1306 The \type {new} function creates a new node. All its fields are initialized to
1307 either zero or \type {nil} except for \type {id} and \type {subtype}. Instead of
1308 numbers you can also use strings (names). If you create a new \nod {whatsit} node
1309 the second argument is required. As with all node functions, this function
1310 creates a node at the \TEX\ level.
1311
1312 \startfunctioncall
1313 <node> n =
1314 node.new(<number> id)
1315 <node> n =
1316 node.new(<number> id, <number> subtype)
1317 \stopfunctioncall
1318
1319 \subsection{\type {free}, \type {flush_node} and \type {flush_list}}
1320
1321 \libindex{free}
1322 \libindex{flush_node}
1323 \libindex{flush_list}
1324
1325 The next one removes the node \type {n} from \TEX's memory. Be careful: no checks are
1326 done on whether this node is still pointed to from a register or some \type
1327 {next} field: it is up to you to make sure that the internal data structures
1328 remain correct.
1329
1330 \startfunctioncall
1331 <node> next =
1332 node.free(<node> n)
1333 flush_node(<node> n)
1334 \stopfunctioncall
1335
1336 The \type {free} function returns the next field of the freed node, while the
1337 \type {flush_node} alternative returns nothing.
1338
1339 A list starting with node \type {n} can be flushed from \TEX's memory too. Be
1340 careful: no checks are done on whether any of these nodes is still pointed to
1341 from a register or some \type {next} field: it is up to you to make sure that the
1342 internal data structures remain correct.
1343
1344 \startfunctioncall
1345 node.flush_list(<node> n)
1346 \stopfunctioncall
1347
1348 \subsection{\type {copy} and \type {copy_list}}
1349
1350 \libindex{copy}
1351 \libindex{copy_list}
1352
1353 This creates a deep copy of node \type {n}, including all nested lists as in the case
1354 of a hlist or vlist node. Only the \type {next} field is not copied.
1355
1356 \startfunctioncall
1357 <node> m =
1358 node.copy(<node> n)
1359 \stopfunctioncall
1360
1361 A deep copy of the node list that starts at \type {n} can be created too. If
1362 \type {m} is also given, the copy stops just before node \type {m}.
1363
1364 \startfunctioncall
1365 <node> m =
1366 node.copy_list(<node> n)
1367 <node> m =
1368 node.copy_list(<node> n, <node> m)
1369 \stopfunctioncall
1370
1371 Note that you cannot copy attribute lists this way. However, there is normally no
1372 need to copy attribute lists as when you do assignments to the \type {attr} field
1373 or make changes to specific attributes, the needed copying and freeing takes
1374 place automatically.
1375
1376 \subsection{\type {prev} and \type{next}}
1377
1378 \libindex{prev}
1379 \libindex{next}
1380
1381 These returns the node preceding or following the given node, or \type {nil} if
1382 there is no such node.
1383
1384 \startfunctioncall
1385 <node> m =
1386 node.next(<node> n)
1387 <node> m =
1388 node.prev(<node> n)
1389 \stopfunctioncall
1390
1391 \subsection{\type {current_attr}}
1392
1393 \libindex{current_attr}
1394
1395 This returns the currently active list of attributes, if there is one.
1396
1397 \startfunctioncall
1398 <node> m =
1399 node.current_attr()
1400 \stopfunctioncall
1401
1402 The intended usage of \type {current_attr} is as follows:
1403
1404 \starttyping
1405 local x1 = node.new("glyph")
1406 x1.attr = node.current_attr()
1407 local x2 = node.new("glyph")
1408 x2.attr = node.current_attr()
1409 \stoptyping
1410
1411 or:
1412
1413 \starttyping
1414 local x1 = node.new("glyph")
1415 local x2 = node.new("glyph")
1416 local ca = node.current_attr()
1417 x1.attr = ca
1418 x2.attr = ca
1419 \stoptyping
1420
1421 The attribute lists are ref counted and the assignment takes care of incrementing
1422 the refcount. You cannot expect the value \type {ca} to be valid any more when
1423 you assign attributes (using \type {tex.setattribute}) or when control has been
1424 passed back to \TEX.
1425
1426 Note: this function is somewhat experimental, and it returns the {\it actual}
1427 attribute list, not a copy thereof. Therefore, changing any of the attributes in
1428 the list will change these values for all nodes that have the current attribute
1429 list assigned to them.
1430
1431 \subsection{\type {hpack}}
1432
1433 \libindex {hpack}
1434
1435 This function creates a new hlist by packaging the list that begins at node \type
1436 {n} into a horizontal box. With only a single argument, this box is created using
1437 the natural width of its components. In the three argument form, \type {info}
1438 must be either \type {additional} or \type {exactly}, and \type {w} is the
1439 additional (\type {\hbox spread}) or exact (\type {\hbox to}) width to be used.
1440 The second return value is the badness of the generated box.
1441
1442 \startfunctioncall
1443 <node> h, <number> b =
1444 node.hpack(<node> n)
1445 <node> h, <number> b =
1446 node.hpack(<node> n, <number> w, <string> info)
1447 <node> h, <number> b =
1448 node.hpack(<node> n, <number> w, <string> info, <string> dir)
1449 \stopfunctioncall
1450
1451 Caveat: there can be unexpected side|-|effects to this function, like updating
1452 some of the \prm {marks} and \type {\inserts}. Also note that the content of
1453 \type {h} is the original node list \type {n}: if you call \type {node.free(h)}
1454 you will also free the node list itself, unless you explicitly set the \type
1455 {list} field to \type {nil} beforehand. And in a similar way, calling \type
1456 {node.free(n)} will invalidate \type {h} as well!
1457
1458 \subsection{\type {vpack}}
1459
1460 \libindex {vpack}
1461
1462 This function creates a new vlist by packaging the list that begins at node \type
1463 {n} into a vertical box. With only a single argument, this box is created using
1464 the natural height of its components. In the three argument form, \type {info}
1465 must be either \type {additional} or \type {exactly}, and \type {w} is the
1466 additional (\type {\vbox spread}) or exact (\type {\vbox to}) height to be used.
1467
1468 \startfunctioncall
1469 <node> h, <number> b =
1470 node.vpack(<node> n)
1471 <node> h, <number> b =
1472 node.vpack(<node> n, <number> w, <string> info)
1473 <node> h, <number> b =
1474 node.vpack(<node> n, <number> w, <string> info, <string> dir)
1475 \stopfunctioncall
1476
1477 The second return value is the badness of the generated box. See the description
1478 of \type {hpack} for a few memory allocation caveats.
1479
1480 \subsection{\type {prepend_prevdepth}}
1481
1482 \libindex {prepend_prevdepth}
1483
1484 This function is somewhat special in the sense that it is an experimental helper
1485 that adds the interlinespace to a line keeping the baselineskip and lineskip into
1486 account.
1487
1488 \startfunctioncall
1489 <node> n, <number> delta =
1490 node.prepend_prevdepth(<node> n,<number> prevdepth)
1491 \stopfunctioncall
1492
1493 \subsection{\type {dimensions} and \type {rangedimensions}}
1494
1495 \libindex{dimensions}
1496 \libindex{rangedimensions}
1497
1498 \startfunctioncall
1499 <number> w, <number> h, <number> d =
1500 node.dimensions(<node> n)
1501 <number> w, <number> h, <number> d =
1502 node.dimensions(<node> n, <string> dir)
1503 <number> w, <number> h, <number> d =
1504 node.dimensions(<node> n, <node> t)
1505 <number> w, <number> h, <number> d =
1506 node.dimensions(<node> n, <node> t, <string> dir)
1507 \stopfunctioncall
1508
1509 This function calculates the natural in|-|line dimensions of the node list starting
1510 at node \type {n} and terminating just before node \type {t} (or the end of the
1511 list, if there is no second argument). The return values are scaled points. An
1512 alternative format that starts with glue parameters as the first three arguments
1513 is also possible:
1514
1515 \startfunctioncall
1516 <number> w, <number> h, <number> d =
1517 node.dimensions(<number> glue_set, <number> glue_sign, <number> glue_order,
1518 <node> n)
1519 <number> w, <number> h, <number> d =
1520 node.dimensions(<number> glue_set, <number> glue_sign, <number> glue_order,
1521 <node> n, <string> dir)
1522 <number> w, <number> h, <number> d =
1523 node.dimensions(<number> glue_set, <number> glue_sign, <number> glue_order,
1524 <node> n, <node> t)
1525 <number> w, <number> h, <number> d =
1526 node.dimensions(<number> glue_set, <number> glue_sign, <number> glue_order,
1527 <node> n, <node> t, <string> dir)
1528 \stopfunctioncall
1529
1530 This calling method takes glue settings into account and is especially useful for
1531 finding the actual width of a sublist of nodes that are already boxed, for
1532 example in code like this, which prints the width of the space in between the
1533 \type {a} and \type {b} as it would be if \type {\box0} was used as-is:
1534
1535 \starttyping
1536 \setbox0 = \hbox to 20pt {a b}
1537
1538 \directlua{print (node.dimensions(
1539 tex.box[0].glue_set,
1540 tex.box[0].glue_sign,
1541 tex.box[0].glue_order,
1542 tex.box[0].head.next,
1543 node.tail(tex.box[0].head)
1544 )) }
1545 \stoptyping
1546
1547 You need to keep in mind that this is one of the few places in \TEX\ where floats
1548 are used, which means that you can get small differences in rounding when you
1549 compare the width reported by \type {hpack} with \type {dimensions}.
1550
1551 The second alternative saves a few lookups and can be more convenient in some
1552 cases:
1553
1554 \startfunctioncall
1555 <number> w, <number> h, <number> d =
1556 node.rangedimensions(<node> parent, <node> first)
1557 <number> w, <number> h, <number> d =
1558 node.rangedimensions(<node> parent, <node> first, <node> last)
1559 \stopfunctioncall
1560
1561 \subsection{\type {mlist_to_hlist}}
1562
1563 \libindex {mlist_to_hlist}
1564
1565 \startfunctioncall
1566 <node> h =
1567 node.mlist_to_hlist(<node> n, <string> display_type, <boolean> penalties)
1568 \stopfunctioncall
1569
1570 This runs the internal mlist to hlist conversion, converting the math list in
1571 \type {n} into the horizontal list \type {h}. The interface is exactly the same
1572 as for the callback \cbk {mlist_to_hlist}.
1573
1574 \subsection{\type {slide}}
1575
1576 \startfunctioncall
1577 <node> m =
1578 node.slide(<node> n)
1579 \stopfunctioncall
1580
1581 Returns the last node of the node list that starts at \type {n}. As a
1582 side|-|effect, it also creates a reverse chain of \type {prev} pointers between
1583 nodes.
1584
1585 \subsection{\type {tail}}
1586
1587 \libindex {tail}
1588
1589 \startfunctioncall
1590 <node> m =
1591 node.tail(<node> n)
1592 \stopfunctioncall
1593
1594 Returns the last node of the node list that starts at \type {n}.
1595
1596 \subsection{\type {length} and type {count}}
1597
1598 \libindex {length}
1599 \libindex {count}
1600
1601 \startfunctioncall
1602 <number> i =
1603 node.length(<node> n)
1604 <number> i =
1605 node.length(<node> n, <node> m)
1606 \stopfunctioncall
1607
1608 Returns the number of nodes contained in the node list that starts at \type {n}.
1609 If \type {m} is also supplied it stops at \type {m} instead of at the end of the
1610 list. The node \type {m} is not counted.
1611
1612 \startfunctioncall
1613 <number> i =
1614 node.count(<number> id, <node> n)
1615 <number> i =
1616 node.count(<number> id, <node> n, <node> m)
1617 \stopfunctioncall
1618
1619 Returns the number of nodes contained in the node list that starts at \type {n}
1620 that have a matching \type {id} field. If \type {m} is also supplied, counting
1621 stops at \type {m} instead of at the end of the list. The node \type {m} is not
1622 counted. This function also accept string \type {id}'s.
1623
1624 \subsection{\type {is_char} and \type {is_glyph}}
1625
1626 \libindex {is_char}
1627 \libindex {is_glyph}
1628
1629 The subtype of a glyph node signals if the glyph is already turned into a character reference
1630 or not.
1631
1632 \startfunctioncall
1633 <boolean> b =
1634 node.is_char(<node> n)
1635 <boolean> b =
1636 node.is_glyph(<node> n)
1637 \stopfunctioncall
1638
1639 \subsection{\type {traverse}}
1640
1641 \libindex {traverse}
1642
1643 \startfunctioncall
1644 <node> t, id, subtype =
1645 node.traverse(<node> n)
1646 \stopfunctioncall
1647
1648 This is a \LUA\ iterator that loops over the node list that starts at \type {n}.
1649 Typically code looks like this:
1650
1651 \starttyping
1652 for n in node.traverse(head) do
1653 ...
1654 end
1655 \stoptyping
1656
1657 is functionally equivalent to:
1658
1659 \starttyping
1660 do
1661 local n
1662 local function f (head,var)
1663 local t
1664 if var == nil then
1665 t = head
1666 else
1667 t = var.next
1668 end
1669 return t
1670 end
1671 while true do
1672 n = f (head, n)
1673 if n == nil then break end
1674 ...
1675 end
1676 end
1677 \stoptyping
1678
1679 It should be clear from the definition of the function \type {f} that even though
1680 it is possible to add or remove nodes from the node list while traversing, you
1681 have to take great care to make sure all the \type {next} (and \type {prev})
1682 pointers remain valid.
1683
1684 If the above is unclear to you, see the section \quote {For Statement} in the
1685 \LUA\ Reference Manual.
1686
1687 \subsection{\type {traverse_id}}
1688
1689 \libindex {traverse_id}
1690
1691 \startfunctioncall
1692 <node> t, subtype =
1693 node.traverse_id(<number> id, <node> n)
1694 \stopfunctioncall
1695
1696 This is an iterator that loops over all the nodes in the list that starts at
1697 \type {n} that have a matching \type {id} field.
1698
1699 See the previous section for details. The change is in the local function \type
1700 {f}, which now does an extra while loop checking against the upvalue \type {id}:
1701
1702 \starttyping
1703 local function f(head,var)
1704 local t
1705 if var == nil then
1706 t = head
1707 else
1708 t = var.next
1709 end
1710 while not t.id == id do
1711 t = t.next
1712 end
1713 return t
1714 end
1715 \stoptyping
1716
1717 \subsection{\type {traverse_char} and \type {traverse_glyph}}
1718
1719 \libindex {traverse_char}
1720 \libindex {traverse_glyph}
1721
1722 The \type{traverse_char} iterator loops over the \nod {glyph} nodes in a list.
1723 Only nodes with a subtype less than 256 are seen.
1724
1725 \startfunctioncall
1726 <node> n, char, font =
1727 node.traverse_char(<node> n)
1728 \stopfunctioncall
1729
1730 The \type{traverse_glyph} iterator loops over a list and returns the list and
1731 filters all glyphs:
1732
1733 \startfunctioncall
1734 <node> n, char, font =
1735 node.traverse_glyph(<node> n)
1736 \stopfunctioncall
1737
1738 \subsection{\type {traverse_list}}
1739
1740 \libindex {traverse_list}
1741
1742 This iterator loops over the \nod {hlist} and \nod {vlist} nodes in a list.
1743
1744 \startfunctioncall
1745 <node> n, id, subtype, list =
1746 node.traverse_list(<node> n)
1747 \stopfunctioncall
1748
1749 The four return values can save some time compared to fetching these fields but
1750 in practice you seldom need them all. So consider it a (side effect of
1751 experimental) convenience.
1752
1753 \subsection{\type {has_glyph}}
1754
1755 \libindex {has_glyph}
1756
1757 This function returns the first glyph or disc node in the given list:
1758
1759 \startfunctioncall
1760 <node> n =
1761 node.has_glyph(<node> n)
1762 \stopfunctioncall
1763
1764 \subsection{\type {end_of_math}}
1765
1766 \libindex {end_of_math}
1767
1768 \startfunctioncall
1769 <node> t =
1770 node.end_of_math(<node> start)
1771 \stopfunctioncall
1772
1773 Looks for and returns the next \type {math_node} following the \type {start}. If
1774 the given node is a math end node this helper returns that node, else it follows
1775 the list and returns the next math endnote. If no such node is found nil is
1776 returned.
1777
1778 \subsection{\type {remove}}
1779
1780 \libindex {remove}
1781
1782 \startfunctioncall
1783 <node> head, current =
1784 node.remove(<node> head, <node> current)
1785 \stopfunctioncall
1786
1787 This function removes the node \type {current} from the list following \type
1788 {head}. It is your responsibility to make sure it is really part of that list.
1789 The return values are the new \type {head} and \type {current} nodes. The
1790 returned \type {current} is the node following the \type {current} in the calling
1791 argument, and is only passed back as a convenience (or \type {nil}, if there is
1792 no such node). The returned \type {head} is more important, because if the
1793 function is called with \type {current} equal to \type {head}, it will be
1794 changed.
1795
1796 \subsection{\type {insert_before}}
1797
1798 \libindex {insert_before}
1799
1800 \startfunctioncall
1801 <node> head, new =
1802 node.insert_before(<node> head, <node> current, <node> new)
1803 \stopfunctioncall
1804
1805 This function inserts the node \type {new} before \type {current} into the list
1806 following \type {head}. It is your responsibility to make sure that \type
1807 {current} is really part of that list. The return values are the (potentially
1808 mutated) \type {head} and the node \type {new}, set up to be part of the list
1809 (with correct \type {next} field). If \type {head} is initially \type {nil}, it
1810 will become \type {new}.
1811
1812 \subsection{\type {insert_after}}
1813
1814 \libindex {insert_after}
1815
1816 \startfunctioncall
1817 <node> head, new =
1818 node.insert_after(<node> head, <node> current, <node> new)
1819 \stopfunctioncall
1820
1821 This function inserts the node \type {new} after \type {current} into the list
1822 following \type {head}. It is your responsibility to make sure that \type
1823 {current} is really part of that list. The return values are the \type {head} and
1824 the node \type {new}, set up to be part of the list (with correct \type {next}
1825 field). If \type {head} is initially \type {nil}, it will become \type {new}.
1826
1827 \subsection{\type {first_glyph}}
1828
1829 \libindex {first_glyph}
1830
1831 \startfunctioncall
1832 <node> n =
1833 node.first_glyph(<node> n)
1834 <node> n =
1835 node.first_glyph(<node> n, <node> m)
1836 \stopfunctioncall
1837
1838 Returns the first node in the list starting at \type {n} that is a glyph node
1839 with a subtype indicating it is a glyph, or \type {nil}. If \type {m} is given,
1840 processing stops at (but including) that node, otherwise processing stops at the
1841 end of the list.
1842
1843 \subsection{\type {ligaturing}}
1844
1845 \libindex {ligaturing}
1846
1847 \startfunctioncall
1848 <node> h, <node> t, <boolean> success =
1849 node.ligaturing(<node> n)
1850 <node> h, <node> t, <boolean> success =
1851 node.ligaturing(<node> n, <node> m)
1852 \stopfunctioncall
1853
1854 Apply \TEX-style ligaturing to the specified nodelist. The tail node \type {m} is
1855 optional. The two returned nodes \type {h} and \type {t} are the new head and
1856 tail (both \type {n} and \type {m} can change into a new ligature).
1857
1858 \subsection{\type {kerning}}
1859
1860 \libindex {kerning}
1861
1862 \startfunctioncall
1863 <node> h, <node> t, <boolean> success =
1864 node.kerning(<node> n)
1865 <node> h, <node> t, <boolean> success =
1866 node.kerning(<node> n, <node> m)
1867 \stopfunctioncall
1868
1869 Apply \TEX|-|style kerning to the specified node list. The tail node \type {m} is
1870 optional. The two returned nodes \type {h} and \type {t} are the head and tail
1871 (either one of these can be an inserted kern node, because special kernings with
1872 word boundaries are possible).
1873
1874 \subsection{\type {unprotect_glyph[s]}}
1875
1876 \libindex {unprotect_glyphs}
1877 \libindex {unprotect_glyph}
1878
1879 \startfunctioncall
1880 node.unprotect_glyph(<node> n)
1881 node.unprotect_glyphs(<node> n,[<node> ,m])
1882 \stopfunctioncall
1883
1884 Subtracts 256 from all glyph node subtypes. This and the next function are
1885 helpers to convert from \type {characters} to \type {glyphs} during node
1886 processing. The second argument is optional and indicates the end of a range.
1887
1888 \subsection{\type {protect_glyph[s]}}
1889
1890 \libindex {protect_glyphs}
1891 \libindex {protect_glyph}
1892
1893 \startfunctioncall
1894 node.protect_glyph(<node> n)
1895 node.protect_glyphs(<node> n,[<node> m])
1896 \stopfunctioncall
1897
1898 Adds 256 to all glyph node subtypes in the node list starting at \type {n},
1899 except that if the value is 1, it adds only 255. The special handling of 1 means
1900 that \type {characters} will become \type {glyphs} after subtraction of 256. A
1901 single character can be marked by the singular call. The second argument is
1902 optional and indicates the end of a range.
1903
1904 \subsection{\type {last_node}}
1905
1906 \libindex {last_node}
1907
1908 \startfunctioncall
1909 <node> n =
1910 node.last_node()
1911 \stopfunctioncall
1912
1913 This function pops the last node from \TEX's \quote{current list}. It returns
1914 that node, or \type {nil} if the current list is empty.
1915
1916 \subsection{\type {write}}
1917
1918 \libindex {write}
1919
1920 \startfunctioncall
1921 node.write(<node> n)
1922 \stopfunctioncall
1923
1924 This function that will append a node list to \TEX's \quote {current list}. The
1925 node list is not deep|-|copied! There is no error checking either! You mignt need
1926 to enforce horizontal mode in order for this to work as expected.
1927
1928 \subsection{\type {protrusion_skippable}}
1929
1930 \libindex {protrusion_skippable}
1931
1932 \startfunctioncall
1933 <boolean> skippable =
1934 node.protrusion_skippable(<node> n)
1935 \stopfunctioncall
1936
1937 Returns \type {true} if, for the purpose of line boundary discovery when
1938 character protrusion is active, this node can be skipped.
1939
1940 \stopsection
1941
1942 \startsection[title={Glue handling}][library=node]
1943
1944 \subsection{\type {setglue}}
1945
1946 \libindex {setglue}
1947
1948 You can set the five properties of a glue in one go. Non|-|numeric values are
1949 equivalent to zero and reset a property.
1950
1951 \startfunctioncall
1952 node.setglue(<node> n)
1953 node.setglue(<node> n,width,stretch,shrink,stretch_order,shrink_order)
1954 \stopfunctioncall
1955
1956 When you pass values, only arguments that are numbers are assigned so
1957
1958 \starttyping
1959 node.setglue(n,655360,false,65536)
1960 \stoptyping
1961
1962 will only adapt the width and shrink.
1963
1964 When a list node is passed, you set the glue, order and sign instead.
1965
1966 \subsection{\type {getglue}}
1967
1968 \libindex {getglue}
1969
1970 The next call will return 5 values or nothing when no glue is passed.
1971
1972 \startfunctioncall
1973 <integer> width, <integer> stretch, <integer> shrink, <integer> stretch_order,
1974 <integer> shrink_order = node.getglue(<node> n)
1975 \stopfunctioncall
1976
1977 When the second argument is false, only the width is returned (this is consistent
1978 with \type {tex.get}).
1979
1980 When a list node is passed, you get back the glue that is set, the order of that
1981 glue and the sign.
1982
1983 \subsection{\type {is_zero_glue}}
1984
1985 \libindex {is_zero_glue}
1986
1987 This function returns \type {true} when the width, stretch and shrink properties
1988 are zero.
1989
1990 \startfunctioncall
1991 <boolean> isglue =
1992 node.is_zero_glue(<node> n)
1993 \stopfunctioncall
1994
1995 \stopsection
1996
1997 \startsection[title={Attribute handling}][library=node]
1998
1999 \subsection{Attributes}
2000
2001 \topicindex {attributes}
2002
2003 The newly introduced attribute registers are non|-|trivial, because the value
2004 that is attached to a node is essentially a sparse array of key|-|value pairs. It
2005 is generally easiest to deal with attribute lists and attributes by using the
2006 dedicated functions in the \type {node} library, but for completeness, here is
2007 the low|-|level interface.
2008
2009 Attributes appear as linked list of userdata objects in the \type {attr} field of
2010 individual nodes. They can be handled individually, but it is much safer and more
2011 efficient to use the dedicated functions associated with them.
2012
2013 \subsection{\nod {attribute_list} nodes}
2014
2015 \topicindex {nodes+attributes}
2016
2017 An \nod {attribute_list} item is used as a head pointer for a list of attribute
2018 items. It has only one user-visible field:
2019
2020 \starttabulate[|l|l|p|]
2021 \DB field \BC type \BC explanation \NC \NR
2022 \TB
2023 \NC \type{next} \NC node \NC pointer to the first attribute \NC \NR
2024 \LL
2025 \stoptabulate
2026
2027 \subsection{\nod {attr} nodes}
2028
2029 A normal node's attribute field will point to an item of type \nod
2030 {attribute_list}, and the \type {next} field in that item will point to the first
2031 defined \quote {attribute} item, whose \type {next} will point to the second
2032 \quote {attribute} item, etc.
2033
2034 \starttabulate[|l|l|p|]
2035 \DB field \BC type \BC explanation \NC \NR
2036 \TB
2037 \NC \type{next} \NC node \NC pointer to the next attribute \NC \NR
2038 \NC \type{number} \NC number \NC the attribute type id \NC \NR
2039 \NC \type{value} \NC number \NC the attribute value \NC \NR
2040 \LL
2041 \stoptabulate
2042
2043 As mentioned it's better to use the official helpers rather than edit these
2044 fields directly. For instance the \type {prev} field is used for other purposes
2045 and there is no double linked list.
2046
2047 \subsection{\type {has_attribute}}
2048
2049 \libindex {has_attribute}
2050
2051 \startfunctioncall
2052 <number> v =
2053 node.has_attribute(<node> n, <number> id)
2054 <number> v =
2055 node.has_attribute(<node> n, <number> id, <number> val)
2056 \stopfunctioncall
2057
2058 Tests if a node has the attribute with number \type {id} set. If \type {val} is
2059 also supplied, also tests if the value matches \type {val}. It returns the value,
2060 or, if no match is found, \type {nil}.
2061
2062 \subsection{\type {get_attribute}}
2063
2064 \libindex {get_attribute}
2065
2066 \startfunctioncall
2067 <number> v =
2068 node.get_attribute(<node> n, <number> id)
2069 \stopfunctioncall
2070
2071 Tests if a node has an attribute with number \type {id} set. It returns the
2072 value, or, if no match is found, \type {nil}. If no \type {id} is given then the
2073 zero attributes is assumed.
2074
2075 \subsection{\type {find_attribute}}
2076
2077 \libindex {find_attribute}
2078
2079 \startfunctioncall
2080 <number> v, <node> n =
2081 node.find_attribute(<node> n, <number> id)
2082 \stopfunctioncall
2083
2084 Finds the first node that has attribute with number \type {id} set. It returns
2085 the value and the node if there is a match and otherwise nothing.
2086
2087 \subsection{\type {set_attribute}}
2088
2089 \libindex {set_attribute}
2090
2091 \startfunctioncall
2092 node.set_attribute(<node> n, <number> id, <number> val)
2093 \stopfunctioncall
2094
2095 Sets the attribute with number \type {id} to the value \type {val}. Duplicate
2096 assignments are ignored.
2097
2098 \subsection{\type {unset_attribute}}
2099
2100 \libindex {unset_attribute}
2101
2102 \startfunctioncall
2103 <number> v =
2104 node.unset_attribute(<node> n, <number> id)
2105 <number> v =
2106 node.unset_attribute(<node> n, <number> id, <number> val)
2107 \stopfunctioncall
2108
2109 Unsets the attribute with number \type {id}. If \type {val} is also supplied, it
2110 will only perform this operation if the value matches \type {val}. Missing
2111 attributes or attribute|-|value pairs are ignored.
2112
2113 If the attribute was actually deleted, returns its old value. Otherwise, returns
2114 \type {nil}.
2115
2116 \subsection{\type {slide}}
2117
2118 \libindex {slide}
2119
2120 This helper makes sure that the node lists is double linked and returns the found
2121 tail node.
2122
2123 \startfunctioncall
2124 <node> tail =
2125 node.slide(<node> n)
2126 \stopfunctioncall
2127
2128 After some callbacks automatic sliding takes place. This feature can be turned
2129 off with \type {node.fix_node_lists(false)} but you better make sure then that
2130 you don't mess up lists. In most cases \TEX\ itself only uses \type {next}
2131 pointers but your other callbacks might expect proper \type {prev} pointers too.
2132 Future versions of \LUATEX\ can add more checking but this will not influence
2133 usage.
2134
2135 \subsection{\type {check_discretionary}, \type {check_discretionaries}}
2136
2137 \libindex{check_discretionary}
2138 \libindex{check_discretionaries}
2139
2140 When you fool around with disc nodes you need to be aware of the fact that they
2141 have a special internal data structure. As long as you reassign the fields when
2142 you have extended the lists it's ok because then the tail pointers get updated,
2143 but when you add to list without reassigning you might end up in trouble when
2144 the linebreak routine kicks in. You can call this function to check the list for
2145 issues with disc nodes.
2146
2147 \startfunctioncall
2148 node.check_discretionary(<node> n)
2149 node.check_discretionaries(<node> head)
2150 \stopfunctioncall
2151
2152 The plural variant runs over all disc nodes in a list, the singular variant
2153 checks one node only (it also checks if the node is a disc node).
2154
2155 \subsection{\type {flatten_discretionaries}}
2156
2157 \libindex {flatten_discretionaries}
2158
2159 This function will remove the discretionaries in the list and inject the replace
2160 field when set.
2161
2162 \startfunctioncall
2163 <node> head, count = node.flatten_discretionaries(<node> n)
2164 \stopfunctioncall
2165
2166 \subsection{\type {family_font}}
2167
2168 \libindex {family_font}
2169
2170 When you pass a proper family identifier the next helper will return the font
2171 currently associated with it. You can normally also access the font with the
2172 normal font field or getter because it will resolve the family automatically for
2173 noads.
2174
2175 \startfunctioncall
2176 <integer> id =
2177 node.family_font(<integer> fam)
2178 \stopfunctioncall
2179
2180 \stopsection
2181
2182 \startsection[title={Two access models}][library=node]
2183
2184 \topicindex{nodes+direct}
2185 \topicindex{direct nodes}
2186
2187 \libindex {todirect}
2188 \libindex {tonode}
2189 \libindex {tostring}
2190
2191 Deep down in \TEX\ a node has a number which is a numeric entry in a memory
2192 table. In fact, this model, where \TEX\ manages memory is real fast and one of
2193 the reasons why plugging in callbacks that operate on nodes is quite fast too.
2194 Each node gets a number that is in fact an index in the memory table and that
2195 number often is reported when you print node related information. You go from
2196 userdata nodes and there numeric references and back with:
2197
2198 \startfunctioncall
2199 <integer> d = node.direct.todirect(<node> n))
2200 <node> n = node.direct.tonode(<integer> d))
2201 \stopfunctioncall
2202
2203 The userdata model is rather robust as it is a virtual interface with some
2204 additional checking while the more direct access which uses the node numbers
2205 directly. However, even with userdata you can get into troubles when you free
2206 nodes that are no longer allocated or mess up lists. if you apply \type
2207 {tostring} to a node you see its internal (direct) number and id.
2208
2209 The first model provides key based access while the second always accesses fields
2210 via functions:
2211
2212 \starttyping
2213 nodeobject.char
2214 getfield(nodenumber,"char")
2215 \stoptyping
2216
2217 If you use the direct model, even if you know that you deal with numbers, you
2218 should not depend on that property but treat it as an abstraction just like
2219 traditional nodes. In fact, the fact that we use a simple basic datatype has the
2220 penalty that less checking can be done, but less checking is also the reason why
2221 it's somewhat faster. An important aspect is that one cannot mix both methods,
2222 but you can cast both models. So, multiplying a node number makes no sense.
2223
2224 So our advice is: use the indexed (table) approach when possible and investigate
2225 the direct one when speed might be a real issue. For that reason \LUATEX\ also
2226 provide the \type {get*} and \type {set*} functions in the top level node
2227 namespace. There is a limited set of getters. When implementing this direct
2228 approach the regular index by key variant was also optimized, so direct access
2229 only makes sense when nodes are accessed millions of times (which happens in some
2230 font processing for instance).
2231
2232 We're talking mostly of getters because setters are less important. Documents
2233 have not that many content related nodes and setting many thousands of properties
2234 is hardly a burden contrary to millions of consultations.
2235
2236 Normally you will access nodes like this:
2237
2238 \starttyping
2239 local next = current.next
2240 if next then
2241 -- do something
2242 end
2243 \stoptyping
2244
2245 Here \type {next} is not a real field, but a virtual one. Accessing it results in
2246 a metatable method being called. In practice it boils down to looking up the node
2247 type and based on the node type checking for the field name. In a worst case you
2248 have a node type that sits at the end of the lookup list and a field that is last
2249 in the lookup chain. However, in successive versions of \LUATEX\ these lookups
2250 have been optimized and the most frequently accessed nodes and fields have a
2251 higher priority.
2252
2253 Because in practice the \type {next} accessor results in a function call, there
2254 is some overhead involved. The next code does the same and performs a tiny bit
2255 faster (but not that much because it is still a function call but one that knows
2256 what to look up).
2257
2258 \starttyping
2259 local next = node.next(current)
2260 if next then
2261 -- do something
2262 end
2263 \stoptyping
2264
2265 Some accessors are used frequently and for these we provide more efficient helpers:
2266
2267 \starttabulate[|l|p|]
2268 \DB function \BC explanation \NC \NR
2269 \TB
2270 \NC \type{getnext} \NC parsing nodelist always involves this one \NC \NR
2271 \NC \type{getprev} \NC used less but a logical companion to \type {getnext} \NC \NR
2272 \NC \type{getboth} \NC returns the next and prev pointer of a node \NC \NR
2273 \NC \type{getid} \NC consulted a lot \NC \NR
2274 \NC \type{getsubtype} \NC consulted less but also a topper \NC \NR
2275 \NC \type{getfont} \NC used a lot in \OPENTYPE\ handling (glyph nodes are consulted a lot) \NC \NR
2276 \NC \type{getchar} \NC idem and also in other places \NC \NR
2277 \NC \type{getwhd} \NC returns the \type {width}, \type {height} and \type {depth} of a list, rule or
2278 (unexpanded) glyph as well as glue (its spec is looked at) and unset nodes\NC \NR
2279 \NC \type{getdisc} \NC returns the \type {pre}, \type {post} and \type {replace} fields and
2280 optionally when true is passed also the tail fields \NC \NR
2281 \NC \type{getlist} \NC we often parse nested lists so this is a convenient one too \NC \NR
2282 \NC \type{getleader} \NC comparable to list, seldom used in \TEX\ (but needs frequent consulting
2283 like lists; leaders could have been made a dedicated node type) \NC \NR
2284 \NC \type{getfield} \NC generic getter, sufficient for the rest (other field names are
2285 often shared so a specific getter makes no sense then) \NC \NR
2286 \NC \type{getbox} \NC gets the given box (a list node) \NC \NR
2287 \NC \type{getoffsets} \NC gets the \type {xoffset} and \type {yoffset} of a glyph or
2288 \type {left} and \type {right} values of a rule \NC \NR
2289 \LL
2290 \stoptabulate
2291
2292 In the direct namespace there are more such helpers and most of them are
2293 accompanied by setters. The getters and setters are clever enough to see what
2294 node is meant. We don't deal with whatsit nodes: their fields are always accessed
2295 by name. It doesn't make sense to add getters for all fields, we just identifier
2296 the most likely candidates. In complex documents, many node and fields types
2297 never get seen, or seen only a few times, but for instance glyphs are candidates
2298 for such optimization. The \type {node.direct} interface has some more helpers.
2299 \footnote {We can define the helpers in the node namespace with \type {getfield}
2300 which is about as efficient, so at some point we might provide that as module.}
2301
2302 The \type {setdisc} helper takes three (optional) arguments plus an optional
2303 fourth indicating the subtype. Its \type {getdisc} takes an optional boolean;
2304 when its value is \type {true} the tail nodes will also be returned. The \type
2305 {setfont} helper takes an optional second argument, it being the character. The
2306 directmode setter \type {setlink} takes a list of nodes and will link them,
2307 thereby ignoring \type {nil} entries. The first valid node is returned (beware:
2308 for good reason it assumes single nodes). For rarely used fields no helpers are
2309 provided and there are a few that probably are used seldom too but were added for
2310 consistency. You can of course always define additional accessors using \type
2311 {getfield} and \type {setfield} with little overhead. When the second argument of
2312 \type {setattributelist} is \type {true} the current attribute list is assumed.
2313
2314 \def\yes{$+$} \def\nop{$-$}
2315
2316 \def\supported#1#2#3%
2317 {\NC \type{#1}
2318 \NC \ifx#2\yes\lix{node} {#1}\fi #2
2319 \NC \ifx#3\yes\lix{node.direct}{#1}\fi #3 \NC
2320 \NR}
2321
2322 \starttabulate[|l|c|c|]
2323 \DB function \BC node \BC direct \NC \NR
2324 \TB
2325 \supported {check_discretionaries} \yes \yes
2326 \supported {check_discretionary} \yes \yes
2327 \supported {copy_list} \yes \yes
2328 \supported {copy} \yes \yes
2329 \supported {count} \yes \yes
2330 \supported {current_attr} \yes \yes
2331 \supported {dimensions} \yes \yes
2332 \supported {effective_glue} \yes \yes
2333 \supported {end_of_math} \yes \yes
2334 \supported {family_font} \yes \nop
2335 \supported {fields} \yes \nop
2336 \supported {find_attribute} \yes \yes
2337 \supported {first_glyph} \yes \yes
2338 \supported {fix_node_lists} \yes \nop
2339 \supported {flatten_discretionaries} \yes \yes
2340 \supported {flush_list} \yes \yes
2341 \supported {flush_node} \yes \yes
2342 \supported {flush_properties_table} \yes \yes
2343 \supported {free} \yes \yes
2344 \supported {get_attribute} \yes \yes
2345 \supported {get_properties_table} \yes \yes
2346 \supported {get_synctex_fields} \nop \yes
2347 \supported {getattributelist} \nop \yes
2348 \supported {getboth} \yes \yes
2349 \supported {getbox} \nop \yes
2350 \supported {getchar} \yes \yes
2351 \supported {getcomponents} \nop \yes
2352 \supported {getdata} \nop \yes
2353 \supported {getdepth} \nop \yes
2354 \supported {getdirection} \nop \yes
2355 \supported {getdir} \nop \yes
2356 \supported {getdisc} \yes \yes
2357 \supported {getexpansion} \nop \yes
2358 \supported {getfam} \nop \yes
2359 \supported {getfield} \yes \yes
2360 \supported {getfont} \yes \yes
2361 \supported {getglue} \yes \yes
2362 \supported {getheight} \nop \yes
2363 \supported {getid} \yes \yes
2364 \supported {getkern} \nop \yes
2365 \supported {getlang} \nop \yes
2366 \supported {getleader} \yes \yes
2367 \supported {getlist} \yes \yes
2368 \supported {getnext} \yes \yes
2369 \supported {getnucleus} \nop \yes
2370 \supported {getoffsets} \nop \yes
2371 \supported {getpenalty} \nop \yes
2372 \supported {getprev} \yes \yes
2373 \supported {getproperty} \yes \yes
2374 \supported {getshift} \nop \yes
2375 \supported {getsubtype} \yes \yes
2376 \supported {getsub} \nop \yes
2377 \supported {getsup} \nop \yes
2378 \supported {getwhd} \yes \yes
2379 \supported {getwidth} \nop \yes
2380 \supported {has_attribute} \yes \yes
2381 \supported {has_field} \yes \yes
2382 \supported {has_glyph} \yes \yes
2383 \supported {hpack} \yes \yes
2384 \supported {hyphenating} \nop \yes
2385 \supported {id} \yes \nop
2386 \supported {insert_after} \yes \yes
2387 \supported {insert_before} \yes \yes
2388 \supported {is_char} \yes \yes
2389 \supported {is_direct} \nop \yes
2390 \supported {is_glyph} \yes \yes
2391 \supported {is_node} \yes \yes
2392 \supported {is_zero_glue} \yes \yes
2393 \supported {kerning} \yes \yes
2394 \supported {last_node} \yes \yes
2395 \supported {length} \yes \yes
2396 \supported {ligaturing} \yes \yes
2397 \supported {make_extensible} \yes \nop
2398 \supported {mlist_to_hlist} \yes \nop
2399 \supported {new} \yes \yes
2400 \supported {next} \yes \nop
2401 \supported {prepend_prevdepth} \yes \yes
2402 \supported {prev} \yes \nop
2403 \supported {protect_glyphs} \yes \yes
2404 \supported {protect_glyph} \yes \yes
2405 \supported {protrusion_skippable} \yes \yes
2406 \supported {rangedimensions} \yes \yes
2407 \supported {remove} \yes \yes
2408 \supported {set_attribute} \yes \yes
2409 \supported {set_properties_mode} \yes \yes
2410 \supported {set_synctex_fields} \nop \yes
2411 \supported {setattributelist} \nop \yes
2412 \supported {setboth} \nop \yes
2413 \supported {setbox} \nop \yes
2414 \supported {setchar} \nop \yes
2415 \supported {setcomponents} \nop \yes
2416 \supported {setdata} \nop \yes
2417 \supported {setdepth} \nop \yes
2418 \supported {setdirection} \nop \yes
2419 \supported {setdir} \nop \yes
2420 \supported {setdisc} \nop \yes
2421 \supported {setexpansion} \nop \yes
2422 \supported {setfam} \nop \yes
2423 \supported {setfield} \yes \yes
2424 \supported {setfont} \nop \yes
2425 \supported {setglue} \yes \yes
2426 \supported {setheight} \nop \yes
2427 \supported {setkern} \nop \yes
2428 \supported {setlang} \nop \yes
2429 \supported {setleader} \nop \yes
2430 \supported {setlink} \nop \yes
2431 \supported {setlist} \nop \yes
2432 \supported {setnext} \nop \yes
2433 \supported {setnucleus} \nop \yes
2434 \supported {setoffsets} \nop \yes
2435 \supported {setpenalty} \nop \yes
2436 \supported {setprev} \nop \yes
2437 \supported {setproperty} \yes \yes
2438 \supported {setshift} \nop \yes
2439 \supported {setsplit} \nop \yes
2440 \supported {setsubtype} \nop \yes
2441 \supported {setsub} \nop \yes
2442 \supported {setsup} \nop \yes
2443 \supported {setwhd} \nop \yes
2444 \supported {setwidth} \nop \yes
2445 \supported {slide} \yes \yes
2446 \supported {subtypes} \yes \nop
2447 \supported {subtype} \yes \nop
2448 \supported {tail} \yes \yes
2449 \supported {todirect} \nop \yes
2450 \supported {tonode} \nop \yes
2451 \supported {tostring} \yes \yes
2452 \supported {traverse_char} \yes \yes
2453 \supported {traverse_glyph} \yes \yes
2454 \supported {traverse_id} \yes \yes
2455 \supported {traverse_list} \nop \yes
2456 \supported {traverse} \yes \yes
2457 \supported {types} \yes \nop
2458 \supported {type} \yes \nop
2459 \supported {unprotect_glyphs} \yes \yes
2460 \supported {unprotect_glyph} \yes \yes
2461 \supported {unset_attribute} \yes \yes
2462 \supported {usedlist} \yes \yes
2463 \supported {uses_font} \yes \yes
2464 \supported {values} \yes \nop
2465 \supported {vpack} \yes \yes
2466 \supported {whatsits} \yes \nop
2467 \supported {write} \yes \yes
2468 \LL
2469 \stoptabulate
2470
2471 The \type {node.next} and \type {node.prev} functions will stay but for
2472 consistency there are variants called \type {getnext} and \type {getprev}. We had
2473 to use \type {get} because \type {node.id} and \type {node.subtype} are already
2474 taken for providing meta information about nodes. Note: The getters do only basic
2475 checking for valid keys. You should just stick to the keys mentioned in the
2476 sections that describe node properties.
2477
2478 Some of the getters and setters handle multiple node types, given that the field
2479 is relevant. In that case, some field names are considered similar (like \type
2480 {kern} and \type {width}, or \type {data} and \type {value}. In retrospect we
2481 could have normalized field names better but we decided to stick to the original
2482 (internal) names as much as possible. After all, at the \LUA\ end one can easily
2483 create synonyms.
2484
2485 In \type {setfield} and \type {getfield} specials and writes accept \type {data}
2486 and \type {value} as equivalent keys. In the case of a write whatsit getting the
2487 \type {value} returns the token list as table, while \type {data} returns the
2488 expansion as a string (version 1.23.2, 2025).
2489
2490 Some nodes have indirect references. For instance a math character refers to a
2491 family instead of a font. In that case we provide a virtual font field as
2492 accessor. So, \type {getfont} and \type {.font} can be used on them. The same is
2493 true for the \type {width}, \type {height} and \type {depth} of glue nodes. These
2494 actually access the spec node properties, and here we can set as well as get the
2495 values.
2496
2497 In some places \LUATEX\ can do a bit of extra checking for valid node lists and
2498 you can enable that with:
2499
2500 \startfunctioncall
2501 node.fix_node_lists(<boolean> b)
2502 \stopfunctioncall
2503
2504 You can set and query the \SYNCTEX\ fields, a file number aka tag and a line
2505 number, for a glue, kern, hlist, vlist, rule and math nodes as well as glyph
2506 nodes (although this last one is not used in native \SYNCTEX).
2507
2508 \startfunctioncall
2509 node.direct.set_synctex_fields(<integer> n, <integer> f, <integer> l)
2510 <integer> f, <integer> l =
2511 node.direct.get_synctex_fields(<integer> n)
2512 \stopfunctioncall
2513
2514 Of course you need to know what you're doing as no checking on sane values takes
2515 place. Also, the synctex interpreter used in editors is rather peculiar and has
2516 some assumptions (heuristics).
2517
2518 \stopsection
2519
2520 \startsection[title={Properties}][library=node]
2521
2522 \topicindex {nodes+properties}
2523 \topicindex {properties}
2524
2525 \libindex{flush_properties_table}
2526 \libindex{get_properties_table}
2527 \libindex{set_properties_mode}
2528
2529 Attributes are a convenient way to relate extra information to a node. You can
2530 assign them at the \TEX\ end as well as at the \LUA\ end and and consult them at
2531 the \LUA\ end. One big advantage is that they obey grouping. They are linked
2532 lists and normally checking for them is pretty efficient, even if you use a lot
2533 of them. A macro package has to provide some way to manage these attributes at the
2534 \TEX\ end because otherwise clashes in their usage can occur.
2535
2536 Each node also can have a properties table and you can assign values to this
2537 table using the \type {setproperty} function and get properties using the \type
2538 {getproperty} function. Managing properties is way more demanding than managing
2539 attributes.
2540
2541 Take the following example:
2542
2543 \starttyping
2544 \directlua {
2545 local n = node.new("glyph")
2546
2547 node.setproperty(n,"foo")
2548 print(node.getproperty(n))
2549
2550 node.setproperty(n,"bar")
2551 print(node.getproperty(n))
2552
2553 node.free(n)
2554 }
2555 \stoptyping
2556
2557 This will print \type {foo} and \type {bar} which in itself is not that useful
2558 when multiple mechanisms want to use this feature. A variant is:
2559
2560 \starttyping
2561 \directlua {
2562 local n = node.new("glyph")
2563
2564 node.setproperty(n,{ one = "foo", two = "bar" })
2565 print(node.getproperty(n).one)
2566 print(node.getproperty(n).two)
2567
2568 node.free(n)
2569 }
2570 \stoptyping
2571
2572 This time we store two properties with the node. It really makes sense to have a
2573 table as property because that way we can store more. But in order for that to
2574 work well you need to do it this way:
2575
2576 \starttyping
2577 \directlua {
2578 local n = node.new("glyph")
2579
2580 local t = node.getproperty(n)
2581
2582 if not t then
2583 t = { }
2584 node.setproperty(n,t)
2585 end
2586 t.one = "foo"
2587 t.two = "bar"
2588
2589 print(node.getproperty(n).one)
2590 print(node.getproperty(n).two)
2591
2592 node.free(n)
2593 }
2594 \stoptyping
2595
2596 Here our own properties will not overwrite other users properties unless of
2597 course they use the same keys. So, eventually you will end up with something:
2598
2599 \starttyping
2600 \directlua {
2601 local n = node.new("glyph")
2602
2603 local t = node.getproperty(n)
2604
2605 if not t then
2606 t = { }
2607 node.setproperty(n,t)
2608 end
2609 t.myself = { one = "foo", two = "bar" }
2610
2611 print(node.getproperty(n).myself.one)
2612 print(node.getproperty(n).myself.two)
2613
2614 node.free(n)
2615 }
2616 \stoptyping
2617
2618 This assumes that only you use \type {myself} as subtable. The possibilities are
2619 endless but care is needed. For instance, the generic font handler that ships
2620 with \CONTEXT\ uses the \type {injections} subtable and you should not mess with
2621 that one!
2622
2623 There are a few helper functions that you normally should not touch as user: \typ
2624 {flush_properties_table} will wipe the table (normally a bad idea), \typ
2625 {get_properties_table} and will give the table that stores properties (using
2626 direct entries) and you can best not mess too much with that one either because
2627 \LUATEX\ itself will make sure that entries related to nodes will get wiped when
2628 nodes get freed, so that the \LUA\ garbage collector can do its job. In fact, the
2629 main reason why we have this mechanism is that it saves the user (or macro
2630 package) some work. One can easily write a property mechanism in \LUA\ where
2631 after a shipout properties gets cleaned up but it's not entirely trivial to make
2632 sure that with each freed node also its properties get freed, due to the fact
2633 that there can be nodes left over for a next page. And having a callback bound to
2634 the node deallocator would add way to much overhead.
2635
2636 Managing properties in the node (de)allocator functions is disabled by default
2637 and is enabled by:
2638
2639 \starttyping
2640 node.set_properties_mode(true)
2641 \stoptyping
2642
2643 When we copy a node list that has a table as property, there are several possibilities: we do the same as
2644 a new node, we copy the entry to the table in properties (a reference), we do
2645 a deep copy of a table in the properties, we create a new table and give it
2646 the original one as a metatable. After some experiments (that also included
2647 timing) with these scenarios we decided that a deep copy made no sense, nor
2648 did nilling. In the end both the shallow copy and the metatable variant were
2649 both ok, although the second one is slower. The most important aspect to keep
2650 in mind is that references to other nodes in properties no longer can be
2651 valid for that copy. We could use two tables (one unique and one shared) or
2652 metatables but that only complicates matters.
2653
2654 When defining a new node, we could already allocate a table but it is rather easy
2655 to do that at the lua end e.g.\ using a metatable \type {__index} method. That
2656 way it is under macro package control. When deleting a node, we could keep the
2657 slot (e.g. setting it to false) but it could make memory consumption raise
2658 unneeded when we have temporary large node lists and after that only small lists.
2659 Both are not done.
2660
2661 So in the end this is what happens now: when a node is copied, and it has a table
2662 as property, the new node will share that table. If the second argument of \typ
2663 {set_properties_mode} is \type {true} then a metatable approach is chosen: the
2664 copy gets its own table with the original table as metatable. If you use the
2665 generic font loader the mode is enabled that way.
2666
2667 A few more xperiments were done. For instance: copy attributes to the properties
2668 so that we have fast access at the \LUA\ end. In the end the overhead is not
2669 compensated by speed and convenience, in fact, attributes are not that slow when
2670 it comes to accessing them. So this was rejected.
2671
2672 Another experiment concerned a bitset in the node but again the gain compared to
2673 attributes was neglectable and given the small amount of available bits it also
2674 demands a pretty strong agreement over what bit represents what, and this is
2675 unlikely to succeed in the \TEX\ community. It doesn't pay off.
2676
2677 Just in case one wonders why properties make sense: it is not so much speed that
2678 we gain, but more convenience: storing all kind of (temporary) data in attributes
2679 is no fun and this mechanism makes sure that properties are cleaned up when a
2680 node is freed. Also, the advantage of a more or less global properties table is
2681 that we stay at the \LUA\ end. An alternative is to store a reference in the node
2682 itself but that is complicated by the fact that the register has some limitations
2683 (no numeric keys) and we also don't want to mess with it too much.
2684
2685 \stopsection
2686
2687 \stopchapter
2688
2689 \stopcomponent