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