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