summaryrefslogtreecommitdiff
path: root/systems/doc/luatex/luatex-nodes.tex
blob: a379b7b0a4d34d042483acffd4209dda6c19cbd6 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306
2307
2308
2309
2310
2311
2312
2313
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
2328
2329
2330
2331
2332
2333
2334
2335
2336
2337
2338
2339
2340
2341
2342
2343
2344
2345
2346
2347
2348
2349
2350
2351
2352
2353
2354
2355
2356
2357
2358
2359
2360
2361
2362
2363
2364
2365
2366
2367
2368
2369
2370
2371
2372
2373
2374
2375
2376
2377
2378
2379
2380
2381
2382
2383
2384
2385
2386
2387
2388
2389
2390
2391
2392
2393
2394
2395
2396
2397
2398
2399
2400
2401
2402
2403
2404
2405
2406
2407
2408
2409
2410
2411
2412
2413
2414
2415
2416
2417
2418
2419
2420
2421
2422
2423
2424
2425
2426
2427
2428
2429
2430
2431
2432
2433
2434
2435
2436
2437
2438
2439
2440
2441
2442
2443
2444
2445
2446
2447
2448
2449
2450
2451
2452
2453
2454
2455
2456
2457
2458
2459
2460
2461
2462
2463
2464
2465
2466
2467
2468
2469
2470
2471
2472
2473
2474
2475
2476
2477
2478
2479
2480
2481
2482
2483
2484
2485
2486
2487
2488
2489
2490
2491
2492
2493
2494
2495
2496
2497
2498
2499
2500
2501
2502
2503
2504
2505
2506
2507
2508
2509
2510
2511
2512
2513
2514
2515
2516
2517
2518
2519
2520
2521
2522
2523
2524
2525
2526
2527
2528
2529
2530
2531
2532
2533
2534
2535
2536
2537
2538
2539
2540
2541
2542
2543
2544
2545
2546
2547
2548
2549
2550
2551
2552
2553
2554
2555
2556
2557
2558
2559
2560
2561
2562
2563
2564
2565
2566
2567
2568
2569
2570
2571
2572
2573
2574
2575
2576
2577
2578
2579
2580
2581
2582
2583
2584
2585
2586
2587
2588
2589
2590
2591
2592
2593
2594
2595
2596
2597
2598
2599
2600
2601
2602
2603
2604
2605
2606
2607
2608
2609
2610
2611
2612
2613
2614
2615
2616
2617
2618
2619
2620
2621
2622
2623
2624
2625
2626
2627
2628
2629
2630
2631
2632
2633
2634
2635
2636
2637
2638
2639
2640
2641
2642
2643
2644
2645
2646
2647
2648
2649
2650
2651
2652
2653
2654
2655
2656
2657
2658
2659
2660
2661
2662
2663
2664
% language=uk

\environment luatex-style

\startcomponent luatex-nodes

\startchapter[reference=nodes,title={Nodes}]

\startsection[title={\LUA\ node representation}][library=node]

\topicindex {nodes}

\libindex {fields}
\libindex {subtypes}
\libindex {values}

\TEX's nodes are represented in \LUA\ as userdata objects with a variable set of
fields. In the following syntax tables, such as the type of such a userdata object
is represented as \syntax {<node>}.

The current return value of \type {node.types()} is:
\startluacode
    for id, name in table.sortedhash(node.types()) do
        context.type(name)
        context(" (%s), ",id)
    end
    context.removeunwantedspaces()
    context.removepunctuation()
\stopluacode
. % period

The \prm {lastnodetype} primitive is \ETEX\ compliant. The valid range is still
$[-1,15]$ and glyph nodes (formerly known as char nodes) have number~0 while
ligature nodes are mapped to~7. That way macro packages can use the same symbolic
names as in traditional \ETEX. Keep in mind that these \ETEX\ node numbers are
different from the real internal ones and that there are more \ETEX\ node types
than~15.

You can ask for a list of fields with \type {node.fields} and for valid subtypes
with \type {node.subtypes}. The \type {node.values} function reports some used
values. Valid arguments are \nod {dir}, \type {direction}, \nod {glue}, \whs
{pdf_literal}, \whs {pdf_action}, \whs {pdf_window} and \whs {color_stack}. Keep
in mind that the setters normally expect a number, but this helper gives you a
list of what numbers matter. For practical reason the \type {pagestate} values
are also reported with this helper.

\stopsection

\startsection[title={Main text nodes}]

\topicindex {nodes+text}

These are the nodes that comprise actual typesetting commands. A few fields are
present in all nodes regardless of their type, these are:

\starttabulate[|l|l|p|]
\DB field          \BC type   \BC explanation \NC \NR
\TB
\NC \type{next}    \NC node   \NC the next node in a list, or nil \NC \NR
\NC \type{id}      \NC number \NC the node's type (\type {id}) number \NC \NR
\NC \type{subtype} \NC number \NC the node \type {subtype} identifier \NC \NR
\LL
\stoptabulate

The \type {subtype} is sometimes just a dummy entry because not all nodes
actually use the \type {subtype}, but this way you can be sure that all nodes
accept it as a valid field name, and that is often handy in node list traversal.
In the following tables \type {next} and \type {id} are not explicitly mentioned.

Besides these three fields, almost all nodes also have an \type {attr} field, and
there is a also a field called \type {prev}. That last field is always present,
but only initialized on explicit request: when the function \type {node.slide()}
is called, it will set up the \type {prev} fields to be a backwards pointer in
the argument node list. By now most of \TEX's node processing makes sure that the
\type {prev} nodes are valid but there can be exceptions, especially when the
internal magic uses a leading \nod {temp} nodes to temporarily store a state.

\subsection{\nod {hlist} nodes}

\starttabulate[|l|l|p|]
\DB field             \BC type   \BC explanation \NC \NR
\TB
\NC \type{subtype}    \NC number \NC \showsubtypes{list} \NC \NR
\NC \type{attr}       \NC node   \NC list of attributes \NC \NR
\NC \type{width}      \NC number \NC the width of the box \NC \NR
\NC \type{height}     \NC number \NC the height of the box \NC \NR
\NC \type{depth}      \NC number \NC the depth of the box \NC \NR
\NC \type{shift}      \NC number \NC a displacement perpendicular to the character
                                     progression direction \NC \NR
\NC \type{glue_order} \NC number \NC a number in the range $[0,4]$, indicating the
                                     glue order \NC \NR
\NC \type{glue_set}   \NC number \NC the calculated glue ratio \NC \NR
\NC \type{glue_sign}  \NC number \NC 0 = \type {normal}, 1 = \type {stretching}, 2 =
                                     \type {shrinking} \NC \NR
\NC \type{head/list}  \NC node   \NC the first node of the body of this list \NC \NR
\NC \type{dir}        \NC string \NC the direction of this box, see~\in [dirnodes] \NC \NR
\LL
\stoptabulate

\topicindex {nodes+lists}
\topicindex {lists}

A warning: never assign a node list to the \type {head} field unless you are sure
its internal link structure is correct, otherwise an error may result.

Note: the field name \type {head} and \type {list} are both valid. Sometimes it
makes more sense to refer to a list by \type {head}, sometimes \type {list} makes
more sense.

\subsection{\nod {vlist} nodes}

\topicindex {nodes+lists}
\topicindex {lists}

This node is similar to \nod {hlist}, except that \quote {shift} is a displacement
perpendicular to the line progression direction, and \quote {subtype} only has
the values 0, 4, and~5.

\subsection{\nod {rule} nodes}

\topicindex {nodes+rules}
\topicindex {rules}

Contrary to traditional \TEX, \LUATEX\ has more \prm {rule} subtypes because we
also use rules to store reuseable objects and images. User nodes are invisible
and can be intercepted by a callback.

\starttabulate[|l|l|p|]
\DB field            \BC type   \BC explanation \NC \NR
\TB
\NC \type{subtype}   \NC number \NC \showsubtypes {rule} \NC \NR
\NC \type{attr}      \NC node   \NC list of attributes \NC \NR
\NC \type{width}     \NC number \NC the width of the rule where the special value
                                    $-1073741824$ is used for \quote {running} glue dimensions \NC \NR
\NC \type{height}    \NC number \NC the height of the rule (can be negative) \NC \NR
\NC \type{depth}     \NC number \NC the depth of the rule (can be negative) \NC \NR
\NC \type{left}      \NC number \NC shift at the left end (also subtracted from width) \NC \NR
\NC \type{right}     \NC number \NC (subtracted from width) \NC \NR
\NC \type{dir}       \NC string \NC the direction of this rule, see~\in[dirnodes] \NC \NR
\NC \type{index}     \NC number \NC an optional index that can be referred to \NC \NR
\NC \type{transform} \NC number \NC an private variable (also used to specify outline width) \NC \NR
\LL
\stoptabulate

The \type {left} and type {right} keys are somewhat special (and experimental).
When rules are auto adapting to the surrounding box width you can enforce a shift
to the right by setting \type {left}. The value is also subtracted from the width
which can be a value set by the engine itself and is not entirely under user
control. The \type {right} is also subtracted from the width. It all happens in
the backend so these are not affecting the calculations in the frontend (actually
the auto settings also happen in the backend). For a vertical rule \type {left}
affects the height and \type {right} affects the depth. There is no matching
interface at the \TEX\ end (although we can have more keywords for rules it would
complicate matters and introduce a speed penalty.) However, you can just
construct a rule node with \LUA\ and write it to the \TEX\ input. The \type
{outline} subtype is just a convenient variant and the \type {transform} field
specifies the width of the outline.

\subsection{\nod {ins} nodes}

\topicindex {nodes+insertions}
\topicindex {insertions}

This node relates to the \prm {insert} primitive.

\starttabulate[|l|l|p|]
\DB field            \BC type   \BC explanation \NC \NR
\TB
\NC \type{subtype}   \NC number \NC the insertion class \NC \NR
\NC \type{attr}      \NC node   \NC list of attributes \NC \NR
\NC \type{cost}      \NC number \NC the penalty associated with this insert \NC \NR
\NC \type{height}    \NC number \NC height of the insert \NC \NR
\NC \type{depth}     \NC number \NC depth of the insert \NC \NR
\NC \type{head/list} \NC node   \NC the first node of the body of this insert \NC \NR
\LL
\stoptabulate

There is a set of extra fields that concern the associated glue: \type {width},
\type {stretch}, \type {stretch_order}, \type {shrink} and \type {shrink_order}.
These are all numbers.

A warning: never assign a node list to the \type {head} field unless you are sure
its internal link structure is correct, otherwise an error may result. You can use
\type {list} instead (often in functions you want to use local variable with similar
names and both names are equally sensible).

\subsection{\nod {mark} nodes}

\topicindex {nodes+marks}
\topicindex {marks}

This one relates to the \prm {mark} primitive.

\starttabulate[|l|l|p|]
\DB field          \BC type   \BC explanation \NC \NR
\TB
\NC \type{subtype} \NC number \NC unused \NC \NR
\NC \type{attr}    \NC node   \NC list of attributes \NC \NR
\NC \type{class}   \NC number \NC the mark class \NC \NR
\NC \type{mark}    \NC table  \NC a table representing a token list \NC \NR
\LL
\stoptabulate

\subsection{\nod {adjust} nodes}

\topicindex {nodes+adjust}
\topicindex {adjust}

This node comes from \prm {vadjust} primitive.

\starttabulate[|l|l|p|]
\DB field            \BC type   \BC explanation \NC \NR
\TB
\NC \type{subtype}   \NC number \NC \showsubtypes{adjust} \NC \NR
\NC \type{attr}      \NC node   \NC list of attributes \NC \NR
\NC \type{head/list} \NC node   \NC adjusted material \NC \NR
\LL
\stoptabulate

A warning: never assign a node list to the \type {head} field unless you are sure
its internal link structure is correct, otherwise an error may be the result.

\subsection{\nod {disc} nodes}

\topicindex {nodes+discretionaries}
\topicindex {discretionaries}

The \prm {discretionary} and \prm {-}, the \type {-} character but also the
hyphenation mechanism produces these nodes.

\starttabulate[|l|l|p|]
\DB field          \BC type   \BC explanation \NC \NR
\TB
\NC \type{subtype} \NC number \NC \showsubtypes{disc} \NC \NR
\NC \type{attr}    \NC node   \NC list of attributes \NC \NR
\NC \type{pre}     \NC node   \NC pointer to the pre|-|break text \NC \NR
\NC \type{post}    \NC node   \NC pointer to the post|-|break text \NC \NR
\NC \type{replace} \NC node   \NC pointer to the no|-|break text \NC \NR
\NC \type{penalty} \NC number \NC the penalty associated with the break, normally
                                  \prm {hyphenpenalty} or \prm {exhyphenpenalty} \NC \NR
\LL
\stoptabulate

The subtype numbers~4 and~5 belong to the \quote {of-f-ice} explanation given
elsewhere. These disc nodes are kind of special as at some point they also keep
information about breakpoints and nested ligatures.

The \type {pre}, \type {post} and \type {replace} fields at the \LUA\ end are in
fact indirectly accessed and have a \type {prev} pointer that is not \type {nil}.
This means that when you mess around with the head of these (three) lists, you
also need to reassign them because that will restore the proper \type {prev}
pointer, so:

\starttyping
pre = d.pre
-- change the list starting with pre
d.pre = pre
\stoptyping

Otherwise you can end up with an invalid internal perception of reality and
\LUATEX\ might even decide to crash on you. It also means that running forward
over for instance \type {pre} is ok but backward you need to stop at \type {pre}.
And you definitely must not mess with the node that \type {prev} points to, if
only because it is not really a node but part of the disc data structure (so
freeing it again might crash \LUATEX).

\subsection{\nod {math} nodes}

\topicindex {nodes+math}
\topicindex {math+nodes}

Math nodes represent the boundaries of a math formula, normally wrapped into
\type {$} signs.

\starttabulate[|l|l|p|]
\DB field           \BC type   \BC explanation \NC \NR
\TB
\NC \type{subtype}  \NC number \NC \showsubtypes{math} \NC \NR
\NC \type{attr}     \NC node   \NC list of attributes \NC \NR
\NC \type{surround} \NC number \NC width of the \prm {mathsurround} kern \NC \NR
\LL
\stoptabulate

There is a set of extra fields that concern the associated glue: \type {width},
\type {stretch}, \type {stretch_order}, \type {shrink} and \type {shrink_order}.
These are all numbers.

\subsection{\nod {glue} nodes}

\topicindex {nodes+glue}
\topicindex {glue}

Skips are about the only type of data objects in traditional \TEX\ that are not a
simple value. They are inserted when \TEX\ sees a space in the text flow but also
by \prm {hskip} and \prm {vskip}. The structure that represents the glue
components of a skip is called a \nod {glue_spec}, and it has the following
accessible fields:

\starttabulate[|l|l|p|]
\DB field                \BC type   \BC explanation \NC \NR
\TB
\NC \type{width}         \NC number \NC the horizontal or vertical displacement \NC \NR
\NC \type{stretch}       \NC number \NC extra (positive) displacement or stretch amount \NC \NR
\NC \type{stretch_order} \NC number \NC factor applied to stretch amount \NC \NR
\NC \type{shrink}        \NC number \NC extra (negative) displacement or shrink amount\NC \NR
\NC \type{shrink_order}  \NC number \NC factor applied to shrink amount \NC \NR
\LL
\stoptabulate

The effective width of some glue subtypes depends on the stretch or shrink needed
to make the encapsulating box fit its dimensions. For instance, in a paragraph
lines normally have glue representing spaces and these stretch or shrink to make
the content fit in the available space. The \type {effective_glue} function that
takes a glue node and a parent (hlist or vlist) returns the effective width of
that glue item. When you pass \type {true} as third argument the value will be
rounded.

A \nod {glue_spec} node is a special kind of node that is used for storing a set
of glue values in registers. Originally they were also used to store properties
of glue nodes (using a system of reference counts) but we now keep these
properties in the glue nodes themselves, which gives a cleaner interface to \LUA.

The indirect spec approach was in fact an optimization in the original \TEX\
code. First of all it can save quite some memory because all these spaces that
become glue now share the same specification (only the reference count is
incremented), and zero testing is also a bit faster because only the pointer has
to be checked (this is no longer true for engines that implement for instance
protrusion where we really need to ensure that zero is zero when we test for
bounds). Another side effect is that glue specifications are read|-|only, so in
the end copies need to be made when they are used from \LUA\ (each assignment to
a field can result in a new copy). So in the end the advantages of sharing are
not that high (and nowadays memory is less an issue, also given that a glue node
is only a few memory words larger than a spec).

\starttabulate[|l|l|p|]
\DB field          \BC type   \BC explanation \NC \NR
\TB
\NC \type{subtype} \NC number \NC \showsubtypes{glue} \NC \NR
\NC \type{attr}    \NC node   \NC list of attributes \NC \NR
\NC \type{leader}  \NC node   \NC pointer to a box or rule for leaders \NC \NR
\LL
\stoptabulate

In addition there are the \type {width}, \type {stretch} \type {stretch_order},
\type {shrink}, and \type {shrink_order} fields. Note that we use the key \type
{width} in both horizontal and vertical glue. This suits the \TEX\ internals well
so we decided to stick to that naming.

A regular word space also results in a \type {spaceskip} subtype (this used to be
a \type {userskip} with subtype zero).

\subsection{\nod {kern} nodes}

\topicindex {nodes+kerns}
\topicindex {kerns}

The \prm {kern} command creates such nodes but for instance the font and math
machinery can also add them.

\starttabulate[|l|l|p|]
\DB field          \BC type   \BC explanation \NC \NR
\TB
\NC \type{subtype} \NC number \NC \showsubtypes{kern} \NC \NR
\NC \type{attr}    \NC node   \NC list of attributes \NC \NR
\NC \type{kern}    \NC number \NC fixed horizontal or vertical advance \NC \NR
\LL
\stoptabulate

\subsection{\nod {penalty} nodes}

\topicindex {nodes+penalty}
\topicindex {penalty}

The \prm {penalty} command is one that generates these nodes.

\starttabulate[|l|l|p|]
\DB field          \BC type   \BC explanation \NC \NR
\TB
\NC \type{subtype} \NC number \NC \showsubtypes{penalty} \NC \NR
\NC \type{attr}    \NC node   \NC list of attributes \NC \NR
\NC \type{penalty} \NC number \NC the penalty value \NC \NR
\LL
\stoptabulate

The subtypes are just informative and \TEX\ itself doesn't use them. When you
run into an \type {linebreakpenalty} you need to keep in mind that it's a
accumulation of \type {club}, \type{widow} and other relevant penalties.

\subsection[glyphnodes]{\nod {glyph} nodes}

\topicindex {nodes+glyph}
\topicindex {glyphs}

These are probably the mostly used nodes and although you can push them in the
current list with for instance \prm {char} \TEX\ will normally do it for you when
it considers some input to be text.

\starttabulate[|l|l|p|]
\DB field                   \BC type    \BC explanation \NC \NR
\TB
\NC \type{subtype}          \NC number  \NC bit field \NC \NR
\NC \type{attr}             \NC node    \NC list of attributes \NC \NR
\NC \type{char}             \NC number  \NC the character index in the font \NC \NR
\NC \type{font}             \NC number  \NC the font identifier \NC \NR
\NC \type{lang}             \NC number  \NC the language identifier \NC \NR
\NC \type{left}             \NC number  \NC the frozen \type {\lefthyphenmnin} value \NC \NR
\NC \type{right}            \NC number  \NC the frozen \type {\righthyphenmnin} value \NC \NR
\NC \type{uchyph}           \NC boolean \NC the frozen \prm {uchyph} value \NC \NR
\NC \type{components}       \NC node    \NC pointer to ligature components \NC \NR
\NC \type{xoffset}          \NC number  \NC a virtual displacement in horizontal direction \NC \NR
\NC \type{yoffset}          \NC number  \NC a virtual displacement in vertical direction \NC \NR
\NC \type{width}            \NC number  \NC the (original) width of the character \NC \NR
\NC \type{height}           \NC number  \NC the (original) height of the character\NC \NR
\NC \type{depth}            \NC number  \NC the (original) depth of the character\NC \NR
\NC \type{expansion_factor} \NC number  \NC the to be applied expansion_factor \NC \NR
\NC \type{data}             \NC number  \NC a general purpose field for users (we had room for it) \NC \NR
\LL
\stoptabulate

The \type {width}, \type {height} and \type {depth} values are read|-|only. The
\type {expansion_factor} is assigned in the par builder and used in the backend.

A warning: never assign a node list to the components field unless you are sure
its internal link structure is correct, otherwise an error may be result. Valid
bits for the \type {subtype} field are:

\starttabulate[|c|l|]
\DB bit \BC meaning   \NC \NR
\TB
\NC 0   \NC character \NC \NR
\NC 1   \NC ligature  \NC \NR
\NC 2   \NC ghost     \NC \NR
\NC 3   \NC left      \NC \NR
\NC 4   \NC right     \NC \NR
\LL
\stoptabulate

See \in {section} [charsandglyphs] for a detailed description of the \type
{subtype} field.

The \type {expansion_factor} has been introduced as part of the separation
between font- and backend. It is the result of extensive experiments with a more
efficient implementation of expansion. Early versions of \LUATEX\ already
replaced multiple instances of fonts in the backend by scaling but contrary to
\PDFTEX\ in \LUATEX\ we now also got rid of font copies in the frontend and
replaced them by expansion factors that travel with glyph nodes. Apart from a
cleaner approach this is also a step towards a better separation between front-
and backend.

The \type {is_char} function checks if a node is a glyph node with a subtype still
less than 256. This function can be used to determine if applying font logic to a
glyph node makes sense. The value \type {nil} gets returned when the node is not
a glyph, a character number is returned if the node is still tagged as character
and \type {false} gets returned otherwise. When nil is returned, the id is also
returned. The \type {is_glyph} variant doesn't check for a subtype being less
than 256, so it returns either the character value or nil plus the id. These
helpers are not always faster than separate calls but they sometimes permit
making more readable tests. The \type {uses_font} helpers takes a node
and font id and returns true when a glyph or disc node references that font.

\subsection{\nod {boundary} nodes}

\topicindex {nodes+boundary}
\topicindex {boundary}

This node relates to the \prm {noboundary}, \prm {boundary}, \prm
{protrusionboundary} and \prm {wordboundary} primitives.

\starttabulate[|l|l|p|]
\DB field          \BC type   \BC explanation \NC \NR
\TB
\NC \type{subtype} \NC number \NC \showsubtypes{boundary} \NC \NR
\NC \type{attr}    \NC node   \NC list of attributes \NC \NR
\NC \type{value}   \NC number \NC values 0--255 are reserved \NC \NR
\LL
\stoptabulate

\subsection{\nod {local_par} nodes}

\topicindex {nodes+paragraphs}
\topicindex {paragraphs}

This node is inserted at the start of a paragraph. You should not mess
too much with this one.

\starttabulate[|l|l|p|]
\DB field                  \BC type   \BC explanation \NC \NR
\TB
\NC \type{attr}            \NC node   \NC list of attributes \NC \NR
\NC \type{pen_inter}       \NC number \NC local interline penalty (from \lpr {localinterlinepenalty}) \NC \NR
\NC \type{pen_broken}      \NC number \NC local broken penalty (from \lpr {localbrokenpenalty}) \NC \NR
\NC \type{dir}             \NC string \NC the direction of this par. see~\in [dirnodes] \NC \NR
\NC \type{box_left}        \NC node   \NC the \lpr {localleftbox} \NC \NR
\NC \type{box_left_width}  \NC number \NC width of the \lpr {localleftbox} \NC \NR
\NC \type{box_right}       \NC node   \NC the \lpr {localrightbox} \NC \NR
\NC \type{box_right_width} \NC number \NC width of the \lpr {localrightbox} \NC \NR
\LL
\stoptabulate

A warning: never assign a node list to the \type {box_left} or \type {box_right}
field unless you are sure its internal link structure is correct, otherwise an
error may result.

\subsection[dirnodes]{\nod {dir} nodes}

\topicindex {nodes+direction}
\topicindex {directions}

Direction nodes mark parts of the running text that need a change of direction and \
the \prm {textdir} command generates them.

\starttabulate[|l|l|p|]
\DB field        \BC type   \BC explanation \NC \NR
\TB
\NC \type{attr}  \NC node   \NC list of attributes \NC \NR
\NC \type{dir}   \NC string \NC the direction (but see below) \NC \NR
\NC \type{level} \NC number \NC nesting level of this direction whatsit \NC \NR
\LL
\stoptabulate

Direction specifiers are three|-|letter combinations of \type {T}, \type {B},
\type {R}, and \type {L}. These are built up out of three separate items:

\startitemize[packed]
\startitem
    the first  is the direction of the \quote{top}   of paragraphs
\stopitem
\startitem
    the second is the direction of the \quote{start} of lines
\stopitem
\startitem
    the third  is the direction of the \quote{top}   of glyphs
\stopitem
\stopitemize

However, only four combinations are accepted: \type {TLT}, \type {TRT}, \type
{RTT}, and \type {LTL}. Inside actual \nod {dir} nodes, the representation of
\nod {dir} is not a three|-|letter but a combination of numbers. When printed the
direction is indicated by a \type {+} or \type {-}, indicating whether the value
is pushed or popped from the direction stack.

\subsection{\nod {marginkern} nodes}

\topicindex {nodes+paragraphs}
\topicindex {paragraphs}
\topicindex {protrusion}

Margin kerns result from protrusion.

\starttabulate[|l|l|p|]
\DB field          \BC type   \BC explanation \NC \NR
\TB
\NC \type{subtype} \NC number \NC \showsubtypes{marginkern} \NC \NR
\NC \type{attr}    \NC node   \NC list of attributes \NC \NR
\NC \type{width}   \NC number \NC the advance of the kern \NC \NR
\NC \type{glyph}   \NC node   \NC the glyph to be used \NC \NR
\LL
\stoptabulate

\stopsection

\startsection[title={Math noads}]

\topicindex {nodes+math}
\topicindex {math+nodes}

These are the so||called \quote {noad}s and the nodes that are specifically
associated with math processing. Most of these nodes contain subnodes so that the
list of possible fields is actually quite small. First, the subnodes:

\subsection{Math kernel subnodes}

Many object fields in math mode are either simple characters in a specific family
or math lists or node lists. There are four associated subnodes that represent
these cases (in the following node descriptions these are indicated by the word
\type {<kernel>}).

The \type {next} and \type {prev} fields for these subnodes are unused.

\subsection{\nod {math_char} and \nod {math_text_char} subnodes}

\starttabulate[|l|l|p|]
\DB field       \BC type   \BC explanation \NC \NR
\TB
\NC \type{attr} \NC node   \NC list of attributes \NC \NR
\NC \type{char} \NC number \NC the character index \NC \NR
\NC \type{fam}  \NC number \NC the family number \NC \NR
\LL
\stoptabulate

The \nod {math_char} is the simplest subnode field, it contains the character
and family for a single glyph object. The \nod {math_text_char} is a special
case that you will not normally encounter, it arises temporarily during math list
conversion (its sole function is to suppress a following italic correction).

\subsection{\nod {sub_box} and \nod {sub_mlist} subnodes}

\starttabulate[|l|l|p|]
\DB field            \BC type \BC explanation \NC \NR
\TB
\NC \type{attr}      \NC node \NC list of attributes \NC \NR
\NC \type{head/list} \NC node \NC list of nodes \NC \NR
\LL
\stoptabulate

These two subnode types are used for subsidiary list items. For \nod {sub_box},
the \type {head} points to a \quote {normal} vbox or hbox. For \nod {sub_mlist},
the \type {head} points to a math list that is yet to be converted.

A warning: never assign a node list to the \type {head} field unless you are sure
its internal link structure is correct, otherwise an error is triggered.

\subsection{\nod {delim} subnodes}

There is a fifth subnode type that is used exclusively for delimiter fields. As
before, the \type {next} and \type {prev} fields are unused.

\starttabulate[|l|l|p|]
\DB field             \BC type   \BC explanation \NC \NR
\TB
\NC \type{attr}       \NC node   \NC list of attributes \NC \NR
\NC \type{small_char} \NC number \NC character index of base character \NC \NR
\NC \type{small_fam}  \NC number \NC family number of base character \NC \NR
\NC \type{large_char} \NC number \NC character index of next larger character \NC \NR
\NC \type{large_fam}  \NC number \NC family number of next larger character \NC \NR
\LL
\stoptabulate

The fields \type {large_char} and \type {large_fam} can be zero, in that case the
font that is set for the \type {small_fam} is expected to provide the large
version as an extension to the \type {small_char}.

\subsection{Math core nodes}

First, there are the objects (the \TEX book calls them \quote {atoms}) that are
associated with the simple math objects: ord, op, bin, rel, open, close, punct,
inner, over, under, vcent. These all have the same fields, and they are combined
into a single node type with separate subtypes for differentiation.

Some noads have an option field. The values in this bitset are common:

\starttabulate[|l|r|]
\DB meaning         \BC bits                      \NC \NR
\TB
\NC set             \NC               \type{0x08} \NC \NR
\NC internal        \NC \type{0x00} + \type{0x08} \NC \NR
\NC internal        \NC \type{0x01} + \type{0x08} \NC \NR
\NC axis            \NC \type{0x02} + \type{0x08} \NC \NR
\NC no axis         \NC \type{0x04} + \type{0x08} \NC \NR
\NC exact           \NC \type{0x10} + \type{0x08} \NC \NR
\NC left            \NC \type{0x11} + \type{0x08} \NC \NR
\NC middle          \NC \type{0x12} + \type{0x08} \NC \NR
\NC right           \NC \type{0x14} + \type{0x08} \NC \NR
\NC no sub script   \NC \type{0x21} + \type{0x08} \NC \NR
\NC no super script \NC \type{0x22} + \type{0x08} \NC \NR
\NC no script       \NC \type{0x23} + \type{0x08} \NC \NR
\LL
\stoptabulate

\subsection{simple \nod {noad} nodes}

\starttabulate[|l|l|p|]
\DB field          \BC type        \BC explanation \NC \NR
\TB
\NC \type{subtype} \NC number      \NC \showsubtypes{noad} \NC \NR
\NC \type{attr}    \NC node        \NC list of attributes \NC \NR
\NC \type{nucleus} \NC kernel node \NC base \NC \NR
\NC \type{sub}     \NC kernel node \NC subscript \NC \NR
\NC \type{sup}     \NC kernel node \NC superscript \NC \NR
\NC \type{options} \NC number      \NC bitset of rendering options \NC \NR
\LL
\stoptabulate

\subsection{\nod {accent} nodes}

\starttabulate[|l|l|p|]
\DB field             \BC type        \BC explanation \NC \NR
\TB
\NC \type{subtype}    \NC number      \NC \showsubtypes{accent} \NC \NR
\NC \type{nucleus}    \NC kernel node \NC base \NC \NR
\NC \type{sub}        \NC kernel node \NC subscript \NC \NR
\NC \type{sup}        \NC kernel node \NC superscript \NC \NR
\NC \type{accent}     \NC kernel node \NC top accent \NC \NR
\NC \type{bot_accent} \NC kernel node \NC bottom accent \NC \NR
\NC \type{fraction}   \NC number      \NC larger step criterium (divided by 1000) \NC \NR
\LL
\stoptabulate

\subsection{\nod {style} nodes}

\starttabulate[|l|l|p|]
\DB field        \BC type   \BC explanation    \NC \NR
\TB
\NC \type{style} \NC string \NC contains the style \NC \NR
\LL
\stoptabulate

There are eight possibilities for the string value: one of \type {display},
\type {text}, \type {script}, or \type {scriptscript}. Each of these can have
be prefixed by \type {cramped}.

\subsection{\nod {choice} nodes}

\starttabulate[|l|l|p|]
\DB field               \BC type \BC explanation \NC \NR
\TB
\NC \type{attr}         \NC node \NC list of attributes \NC \NR
\NC \type{display}      \NC node \NC list of display size alternatives \NC \NR
\NC \type{text}         \NC node \NC list of text size alternatives \NC \NR
\NC \type{script}       \NC node \NC list of scriptsize alternatives \NC \NR
\NC \type{scriptscript} \NC node \NC list of scriptscriptsize alternatives \NC \NR
\LL
\stoptabulate

Warning: never assign a node list to the \type {display}, \type {text}, \type
{script}, or \type {scriptscript} field unless you are sure its internal link
structure is correct, otherwise an error can occur.

\subsection{\nod {radical} nodes}

\starttabulate[|l|l|p|]
\DB field          \BC type           \BC explanation \NC \NR
\TB
\NC \type{subtype} \NC number         \NC \showsubtypes{radical} \NC \NR
\NC \type{attr}    \NC node           \NC list of attributes \NC \NR
\NC \type{nucleus} \NC kernel node    \NC base \NC \NR
\NC \type{sub}     \NC kernel node    \NC subscript \NC \NR
\NC \type{sup}     \NC kernel node    \NC superscript \NC \NR
\NC \type{left}    \NC delimiter node \NC \NC \NR
\NC \type{degree}  \NC kernel node    \NC only set by \lpr {Uroot} \NC \NR
\NC \type{width}   \NC number         \NC required width \NC \NR
\NC \type{options} \NC number         \NC bitset of rendering options \NC \NR
\LL
\stoptabulate

Warning: never assign a node list to the \type {nucleus}, \type {sub}, \type
{sup}, \type {left}, or \type {degree} field unless you are sure its internal
link structure is correct, otherwise an error can be triggered.

\subsection{\nod {fraction} nodes}

\starttabulate[|l|l|p|]
\DB field          \BC type           \BC explanation \NC \NR
\TB
\NC \type{attr}    \NC node           \NC list of attributes \NC \NR
\NC \type{width}   \NC number         \NC (optional) width of the fraction \NC \NR
\NC \type{num}     \NC kernel node    \NC numerator \NC \NR
\NC \type{denom}   \NC kernel node    \NC denominator \NC \NR
\NC \type{left}    \NC delimiter node \NC left side symbol \NC \NR
\NC \type{right}   \NC delimiter node \NC right side symbol \NC \NR
\NC \type{middle}  \NC delimiter node \NC middle symbol \NC \NR
\NC \type{options} \NC number         \NC bitset of rendering options \NC \NR
\LL
\stoptabulate

Warning: never assign a node list to the \type {num}, or \type {denom} field
unless you are sure its internal link structure is correct, otherwise an error
can result.

\subsection{\nod {fence} nodes}

\starttabulate[|l|l|p|]
\DB field          \BC type           \BC explanation \NC \NR
\TB
\NC \type{subtype} \NC number         \NC \showsubtypes{fence} \NC \NR
\NC \type{attr}    \NC node           \NC list of attributes \NC \NR
\NC \type{delim}   \NC delimiter node \NC delimiter specification \NC \NR
\NC \type{italic}  \NC number         \NC italic correction \NC \NR
\NC \type{height}  \NC number         \NC required height \NC \NR
\NC \type{depth}   \NC number         \NC required depth \NC \NR
\NC \type{options} \NC number         \NC bitset of rendering options \NC \NR
\NC \type{class}   \NC number         \NC spacing related class \NC \NR
\LL
\stoptabulate

Warning: some of these fields are used by the renderer and might get adapted in
the process.

\stopsection

\startsection[title={Front|-|end whatsits}]

Whatsit nodes come in many subtypes that you can ask for them by running
\type {node.whatsits}:
\startluacode
    for id, name in table.sortedpairs(node.whatsits()) do
        context.type(name)
        context(" (%s), ",id)
    end
    context.removeunwantedspaces()
    context.removepunctuation()
\stopluacode
. % period

Some of them are generic and independent of the output mode and others are
specific to the chosen backend: \DVI\ or \PDF. Here we discuss the generic
font|-|end nodes nodes.

\subsection{\whs {open}}

\starttabulate[|l|l|p|]
\DB field         \BC type   \BC explanation \NC \NR
\TB
\NC \type{attr}   \NC node   \NC list of attributes \NC \NR
\NC \type{stream} \NC number \NC \TEX's stream id number \NC \NR
\NC \type{name}   \NC string \NC file name \NC \NR
\NC \type{ext}    \NC string \NC file extension \NC \NR
\NC \type{area}   \NC string \NC file area (this may become obsolete) \NC \NR
\LL
\stoptabulate

\subsection{\whs {write}}

\starttabulate[|l|l|p|]
\DB field         \BC type   \BC explanation \NC \NR
\TB
\NC \type{attr}   \NC node   \NC list of attributes \NC \NR
\NC \type{stream} \NC number \NC \TEX's stream id number \NC \NR
\NC \type{data}   \NC table  \NC a table representing the token list to be written \NC \NR
\LL
\stoptabulate

\subsection{\whs {close}}

\starttabulate[|l|l|p|]
\DB field         \BC type   \BC explanation \NC \NR
\TB
\NC \type{attr}   \NC node   \NC list of attributes \NC \NR
\NC \type{stream} \NC number \NC \TEX's stream id number \NC \NR
\LL
\stoptabulate

\subsection{\whs {user_defined}}

User|-|defined whatsit nodes can only be created and handled from \LUA\ code. In
effect, they are an extension to the extension mechanism. The \LUATEX\ engine
will simply step over such whatsits without ever looking at the contents.

\starttabulate[|l|l|p|]
\DB field          \BC type   \BC explanation \NC \NR
\TB
\NC \type{attr}    \NC node   \NC list of attributes \NC \NR
\NC \type{user_id} \NC number \NC id number \NC \NR
\NC \type{type}    \NC number \NC type of the value \NC \NR
\NC \type{value}   \NC number \NC a \LUA\ number \NC \NR
\NC                \NC node   \NC a node list \NC \NR
\NC                \NC string \NC a \LUA\ string \NC \NR
\NC                \NC table  \NC a \LUA\ table \NC \NR
\LL
\stoptabulate

The \type {type} can have one of six distinct values. The number is the \ASCII\
value if the first character of the type name (so you can use string.byte("l")
instead of \type {108}).

\starttabulate[|r|c|p|]
\DB value \BC meaning \BC explanation \NC \NR
\TB
\NC   97  \NC a       \NC list of attributes (a node list) \NC \NR
\NC  100  \NC d       \NC a \LUA\ number \NC \NR
\NC  108  \NC l       \NC a \LUA\ value (table, number, boolean, etc) \NC \NR
\NC  110  \NC n       \NC a node list \NC \NR
\NC  115  \NC s       \NC a \LUA\ string \NC \NR
\NC  116  \NC t       \NC a \LUA\ token list in \LUA\ table form (a list of triplets) \NC \NR
\LL
\stoptabulate

\subsection{\whs {save_pos}}

\starttabulate[|l|l|p|]
\DB field       \BC type \BC explanation \NC \NR
\TB
\NC \type{attr} \NC node \NC list of attributes \NC \NR
\LL
\stoptabulate

\subsection{\whs {late_lua}}

\starttabulate[|l|l|p|]
\DB field        \BC type               \BC explanation \NC \NR
\TB
\NC \type{attr}  \NC node               \NC list of attributes \NC \NR
\NC \type{data}  \NC string or function \NC the to be written information stored as \LUA\ value \NC \NR
\NC \type{token} \NC string             \NC the to be written information stored as token list \NC \NR
\NC \type{name}  \NC string             \NC the name to use for \LUA\ error reporting \NC \NR
\LL
\stoptabulate

The difference between \type {data} and \type {string} is that on assignment, the
\type {data} field is converted to a token list, cf.\ use as \lpr {latelua}. The
\type {string} version is treated as a literal string.

\stopsection

\startsection[title={\DVI\ backend whatsits}]

\subsection{\whs {special}}

There is only one \DVI\ backend whatsit, and it just flushes its content to the
output file.

\starttabulate[|l|l|p|]
\DB field       \BC type   \BC explanation \NC \NR
\TB
\NC \type{attr} \NC node   \NC list of attributes \NC \NR
\NC \type{data} \NC string \NC the \prm {special} information \NC \NR
\LL
\stoptabulate

\stopsection

\startsection[title={\PDF\ backend whatsits}]

\subsection{\whs {pdf_literal}}

\starttabulate[|l|l|p|]
\DB field        \BC type   \BC explanation \NC \NR
\TB
\NC \type{attr}  \NC node   \NC list of attributes \NC \NR
\NC \type{mode}  \NC number \NC the \quote {mode} setting of this literal \NC \NR
\NC \type{data}  \NC string \NC the to be written information stored as \LUA\ string \NC \NR
\NC \type{token} \NC string \NC the to be written information stored as token list \NC \NR
\LL
\stoptabulate

Possible mode values are:

\starttabulate[|c|p|]
\DB value \BC keyword        \NC \NR
\TB
\NC 0     \NC \type{origin}  \NC \NR
\NC 1     \NC \type{page}    \NC \NR
\NC 2     \NC \type{direct}  \NC \NR
\NC 3     \NC \type{raw}     \NC \NR
\NC 4     \NC \type{text}    \NC \NR
\LL
\stoptabulate

The higher the number, the less checking and the more you can run into trouble.
Especially the \type {raw} variant can produce bad \PDF\ so you can best check
what you generate.

\subsection{\whs {pdf_refobj}}

\starttabulate[|l|l|p|]
\DB field         \BC type   \BC explanation \NC \NR
\TB
\NC \type{attr}   \NC node   \NC list of attributes \NC \NR
\NC \type{objnum} \NC number \NC the referenced \PDF\ object number \NC \NR
\LL
\stoptabulate

\subsection{\whs {pdf_annot}}

\starttabulate[|l|l|p|]
\DB field         \BC type   \BC explanation \NC \NR
\TB
\NC \type{attr}   \NC node   \NC list of attributes \NC \NR
\NC \type{width}  \NC number \NC the width (not used in calculations) \NC \NR
\NC \type{height} \NC number \NC the height (not used in calculations) \NC \NR
\NC \type{depth}  \NC number \NC the depth (not used in calculations) \NC \NR
\NC \type{objnum} \NC number \NC the referenced \PDF\ object number \NC \NR
\NC \type{data}   \NC string \NC the annotation data \NC \NR
\LL
\stoptabulate

\subsection{\whs {pdf_start_link}}

\starttabulate[|l|l|p|]
\DB field            \BC type   \BC explanation \NC \NR
\TB
\NC \type{attr}      \NC node   \NC list of attributes \NC \NR
\NC \type{width}     \NC number \NC the width (not used in calculations) \NC \NR
\NC \type{height}    \NC number \NC the height (not used in calculations) \NC \NR
\NC \type{depth}     \NC number \NC the depth (not used in calculations) \NC \NR
\NC \type{objnum}    \NC number \NC the referenced \PDF\ object number \NC \NR
\NC \type{link_attr} \NC table  \NC the link attribute token list \NC \NR
\NC \type{action}    \NC node   \NC the action to perform \NC \NR
\LL
\stoptabulate

\subsection{\whs {pdf_end_link}}

\starttabulate[|l|l|p|]
\DB field       \BC type \BC explanation \NC \NR
\TB
\NC \type{attr} \NC node \NC \NC \NR
\LL
\stoptabulate

\subsection{\whs {pdf_dest}}

\starttabulate[|l|l|p|]
\DB field              \BC type     \BC explanation \NC \NR
\TB
\NC \type{attr}        \NC node     \NC list of attributes \NC \NR
\NC \type{width}       \NC number   \NC the width (not used in calculations) \NC \NR
\NC \type{height}      \NC number   \NC the height (not used in calculations) \NC \NR
\NC \type{depth}       \NC number   \NC the depth (not used in calculations) \NC \NR
\NC \type{named_id}    \NC number   \NC is the \type {dest_id} a string value? \NC \NR
\NC \type{dest_id}     \NC number   \NC the destination id \NC \NR
\NC                    \NC string   \NC the destination name \NC \NR
\NC \type{dest_type}   \NC number   \NC type of destination \NC \NR
\NC \type{xyz_zoom}    \NC number   \NC the zoom factor (times 1000) \NC \NR
\NC \type{objnum}      \NC number   \NC the \PDF\ object number \NC \NR
\LL
\stoptabulate

\subsection{\whs {pdf_action}}

These are a special kind of items that only appear inside \PDF\ start link
objects.

\starttabulate[|l|l|p|]
\DB field              \BC type             \BC explanation \NC \NR
\TB
\NC \type{action_type} \NC number           \NC the kind of action involved \NC \NR
\NC \type{action_id}   \NC number or string \NC token list reference or string \NC \NR
\NC \type{named_id}    \NC number           \NC the index of the destination \NC \NR
\NC \type{file}        \NC string           \NC the target filename \NC \NR
\NC \type{new_window}  \NC number           \NC the window state of the target \NC \NR
\NC \type{data}        \NC string           \NC the name of the destination \NC \NR
\LL
\stoptabulate

Valid action types are:

\starttabulate[|l|l|]
\DB value \BC meaning       \NC \NR
\TB
\NC 0     \NC \type{page}   \NC \NR
\NC 1     \NC \type{goto}   \NC \NR
\NC 2     \NC \type{thread} \NC \NR
\NC 3     \NC \type{user}   \NC \NR
\LL
\stoptabulate

Valid window types are:

\starttabulate[|l|l|]
\DB value \BC meaning       \NC \NR
\TB
\NC 0     \NC \type{notset} \NC \NR
\NC 1     \NC \type{new}    \NC \NR
\NC 2     \NC \type{nonew}  \NC \NR
\LL
\stoptabulate

\subsection{\whs {pdf_thread}}

\starttabulate[|l|l|p|]
\DB field              \BC type   \BC explanation \NC \NR
\TB
\NC \type{attr}        \NC node   \NC list of attributes \NC \NR
\NC \type{width}       \NC number \NC the width (not used in calculations) \NC \NR
\NC \type{height}      \NC number \NC the height (not used in calculations) \NC \NR
\NC \type{depth}       \NC number \NC the depth (not used in calculations) \NC \NR
\NC \type{named_id}    \NC number \NC is \type {tread_id} a string value? \NC \NR
\NC \type{tread_id}    \NC number \NC the thread id \NC \NR
\NC                    \NC string \NC the thread name \NC \NR
\NC \type{thread_attr} \NC number \NC extra thread information \NC \NR
\LL
\stoptabulate

\subsection{\whs {pdf_start_thread}}

\starttabulate[|l|l|p|]
\DB field              \BC type   \BC explanation \NC \NR
\TB
\NC \type{attr}        \NC node   \NC list of attributes \NC \NR
\NC \type{width}       \NC number \NC the width (not used in calculations) \NC \NR
\NC \type{height}      \NC number \NC the height (not used in calculations) \NC \NR
\NC \type{depth}       \NC number \NC the depth (not used in calculations) \NC \NR
\NC \type{named_id}    \NC number \NC is \type {tread_id} a string value? \NC \NR
\NC \type{tread_id}    \NC number \NC the thread id \NC \NR
\NC                    \NC string \NC the thread name \NC \NR
\NC \type{thread_attr} \NC number \NC extra thread information \NC \NR
\LL
\stoptabulate

\subsection{\whs {pdf_end_thread}}

\starttabulate[|l|l|p|]
\DB field       \BC type \BC explanation \NC \NR
\TB
\NC \type{attr} \NC node \NC \NC \NR
\LL
\stoptabulate

\subsection{\whs {pdf_colorstack}}

\starttabulate[|l|l|p|]
\DB field          \BC type   \BC explanation \NC \NR
\TB
\NC \type{attr}    \NC node   \NC list of attributes \NC \NR
\NC \type{stack}   \NC number \NC colorstack id number \NC \NR
\NC \type{command} \NC number \NC command to execute \NC \NR
\NC \type{data}    \NC string \NC data \NC \NR
\LL
\stoptabulate

\subsection{\whs {pdf_setmatrix}}

\starttabulate[|l|l|p|]
\DB field       \BC type   \BC explanation \NC \NR
\TB
\NC \type{attr} \NC node   \NC list of attributes \NC \NR
\NC \type{data} \NC string \NC data \NC \NR
\LL
\stoptabulate

\subsection{\whs {pdf_save}}

\starttabulate[|l|l|p|]
\DB field       \BC type \BC explanation \NC \NR
\TB
\NC \type{attr} \NC node \NC list of attributes \NC \NR
\LL
\stoptabulate

\subsection{\whs {pdf_restore}}

\starttabulate[|l|l|p|]
\DB field       \BC type \BC explanation \NC \NR
\TB
\NC \type{attr} \NC node \NC list of attributes \NC \NR
\LL
\stoptabulate

\stopsection

\startsection[title={The \type {node} library}][library=node]

\subsection {Introduction}

The \type {node} library contains functions that facilitate dealing with (lists
of) nodes and their values. They allow you to create, alter, copy, delete, and
insert \LUATEX\ node objects, the core objects within the typesetter.

\LUATEX\ nodes are represented in \LUA\ as userdata with the metadata type
\type {luatex.node}. The various parts within a node can be accessed using
named fields.

Each node has at least the three fields \type {next}, \type {id}, and \type {subtype}:

\startitemize[intro]

\startitem
    The \type {next} field returns the userdata object for the next node in a
    linked list of nodes, or \type {nil}, if there is no next node.
\stopitem

\startitem
    The \type {id} indicates \TEX's \quote{node type}. The field \type {id} has a
    numeric value for efficiency reasons, but some of the library functions also
    accept a string value instead of \type {id}.
\stopitem

\startitem
    The \type {subtype} is another number. It often gives further information
    about a node of a particular \type {id}, but it is most important when
    dealing with \quote {whatsits}, because they are differentiated solely based
    on their \type {subtype}.
\stopitem

\stopitemize

The other available fields depend on the \type {id} (and for \quote {whatsits},
the \type {subtype}) of the node.

Support for \nod {unset} (alignment) nodes is partial: they can be queried and
modified from \LUA\ code, but not created.

Nodes can be compared to each other, but: you are actually comparing indices into
the node memory. This means that equality tests can only be trusted under very
limited conditions. It will not work correctly in any situation where one of the
two nodes has been freed and|/|or reallocated: in that case, there will be false
positives.

At the moment, memory management of nodes should still be done explicitly by the
user. Nodes are not \quote {seen} by the \LUA\ garbage collector, so you have to
call the node freeing functions yourself when you are no longer in need of a node
(list). Nodes form linked lists without reference counting, so you have to be
careful that when control returns back to \LUATEX\ itself, you have not deleted
nodes that are still referenced from a \type {next} pointer elsewhere, and that
you did not create nodes that are referenced more than once. Normally the setters
and getters handle this for you.

There are statistics available with regards to the allocated node memory, which
can be handy for tracing.

\subsection{\type {is_node}}

\topicindex {nodes+functions}

\libindex {is_node}

\startfunctioncall
<boolean|integer> t =
    node.is_node(<any> item)
\stopfunctioncall

This function returns a number (the internal index of the node) if the argument
is a userdata object of type \type {<node>} and false when no node is passed.

\subsection{\type {types} and \type {whatsits}}

\libindex {types}
\libindex {whatsits}

This function returns an array that maps node id numbers to node type strings,
providing an overview of the possible top|-|level \type {id} types.

\startfunctioncall
<table> t =
    node.types()
\stopfunctioncall

\TEX's \quote {whatsits} all have the same \type {id}. The various subtypes are
defined by their \type {subtype} fields. The function is much like \type {types},
except that it provides an array of \type {subtype} mappings.

\startfunctioncall
<table> t =
    node.whatsits()
\stopfunctioncall

\subsection{\type {id}}

\libindex{id}

This converts a single type name to its internal numeric representation.

\startfunctioncall
<number> id =
    node.id(<string> type)
\stopfunctioncall

\subsection{\type {type} and \type {subtype}}

\libindex {type}
\libindex {subtype}

In the argument is a number, then the next function converts an internal numeric
representation to an external string representation. Otherwise, it will return
the string \type {node} if the object represents a node, and \type {nil}
otherwise.

\startfunctioncall
<string> type =
    node.type(<any> n)
\stopfunctioncall

This next one converts a single whatsit name to its internal numeric
representation (\type {subtype}).

\startfunctioncall
<number> subtype =
    node.subtype(<string> type)
\stopfunctioncall

\subsection{\type {fields}}

\libindex {fields}

This function returns an array of valid field names for a particular type of
node. If you want to get the valid fields for a \quote {whatsit}, you have to
supply the second argument also. In other cases, any given second argument will
be silently ignored.

\startfunctioncall
<table> t =
    node.fields(<number> id)
<table> t =
    node.fields(<number> id, <number> subtype)
\stopfunctioncall

The function accepts string \type {id} and \type {subtype} values as well.

\subsection{\type {has_field}}

\libindex {has_field}

This function returns a boolean that is only true if \type {n} is
actually a node, and it has the field.

\startfunctioncall
<boolean> t =
    node.has_field(<node> n, <string> field)
\stopfunctioncall

\subsection{\type {new}}

\libindex{new}

The \type {new} function creates a new node. All its fields are initialized to
either zero or \type {nil} except for \type {id} and \type {subtype}. Instead of
numbers you can also use strings (names). If you create a new \nod {whatsit} node
the second argument is required. As with all node functions, this function
creates a node at the \TEX\ level.

\startfunctioncall
<node> n =
    node.new(<number> id)
<node> n =
    node.new(<number> id, <number> subtype)
\stopfunctioncall

\subsection{\type {free}, \type {flush_node} and \type {flush_list}}

\libindex{free}
\libindex{flush_node}
\libindex{flush_list}

The next one the node \type {n} from \TEX's memory. Be careful: no checks are
done on whether this node is still pointed to from a register or some \type
{next} field: it is up to you to make sure that the internal data structures
remain correct.

\startfunctioncall
<node> next =
    node.free(<node> n)
flush_node(<node> n)
\stopfunctioncall

The \type {free} function returns the next field of the freed node, while the
\type {flush_node} alternative returns nothing.

A list starting with node \type {n} can be flushed from \TEX's memory too. Be
careful: no checks are done on whether any of these nodes is still pointed to
from a register or some \type {next} field: it is up to you to make sure that the
internal data structures remain correct.

\startfunctioncall
node.flush_list(<node> n)
\stopfunctioncall

\subsection{\type {copy} and \type {copy_list}}

\libindex{copy}
\libindex{copy_list}

This creates a deep copy of node \type {n}, including all nested lists as in the case
of a hlist or vlist node. Only the \type {next} field is not copied.

\startfunctioncall
<node> m =
    node.copy(<node> n)
\stopfunctioncall

A deep copy of the node list that starts at \type {n} can be created too. If
\type {m} is also given, the copy stops just before node \type {m}.

\startfunctioncall
<node> m =
    node.copy_list(<node> n)
<node> m =
    node.copy_list(<node> n, <node> m)
\stopfunctioncall

Note that you cannot copy attribute lists this way. However, there is normally no
need to copy attribute lists as when you do assignments to the \type {attr} field
or make changes to specific attributes, the needed copying and freeing takes
place automatically.

\subsection{\type {prev} and \type{next}}

\libindex{prev}
\libindex{next}

These returns the node preceding or following the given node, or \type {nil} if
there is no such node.

\startfunctioncall
<node> m =
    node.next(<node> n)
<node> m =
    node.prev(<node> n)
\stopfunctioncall

\subsection{\type {current_attr}}

\libindex{current_attr}

This returns the currently active list of attributes, if there is one.

\startfunctioncall
<node> m =
    node.current_attr()
\stopfunctioncall

The intended usage of \type {current_attr} is as follows:

\starttyping
local x1 = node.new("glyph")
x1.attr = node.current_attr()
local x2 = node.new("glyph")
x2.attr = node.current_attr()
\stoptyping

or:

\starttyping
local x1 = node.new("glyph")
local x2 = node.new("glyph")
local ca = node.current_attr()
x1.attr = ca
x2.attr = ca
\stoptyping

The attribute lists are ref counted and the assignment takes care of incrementing
the refcount. You cannot expect the value \type {ca} to be valid any more when
you assign attributes (using \type {tex.setattribute}) or when control has been
passed back to \TEX.

Note: this function is somewhat experimental, and it returns the {\it actual}
attribute list, not a copy thereof. Therefore, changing any of the attributes in
the list will change these values for all nodes that have the current attribute
list assigned to them.

\subsection{\type {hpack}}

\libindex {hpack}

This function creates a new hlist by packaging the list that begins at node \type
{n} into a horizontal box. With only a single argument, this box is created using
the natural width of its components. In the three argument form, \type {info}
must be either \type {additional} or \type {exactly}, and \type {w} is the
additional (\type {\hbox spread}) or exact (\type {\hbox to}) width to be used.
The second return value is the badness of the generated box.

\startfunctioncall
<node> h, <number> b =
    node.hpack(<node> n)
<node> h, <number> b =
    node.hpack(<node> n, <number> w, <string> info)
<node> h, <number> b =
    node.hpack(<node> n, <number> w, <string> info, <string> dir)
\stopfunctioncall

Caveat: there can be unexpected side|-|effects to this function, like updating
some of the \prm {marks} and \type {\inserts}. Also note that the content of
\type {h} is the original node list \type {n}: if you call \type {node.free(h)}
you will also free the node list itself, unless you explicitly set the \type
{list} field to \type {nil} beforehand. And in a similar way, calling \type
{node.free(n)} will invalidate \type {h} as well!

\subsection{\type {vpack}}

\libindex {vpack}

This function creates a new vlist by packaging the list that begins at node \type
{n} into a vertical box. With only a single argument, this box is created using
the natural height of its components. In the three argument form, \type {info}
must be either \type {additional} or \type {exactly}, and \type {w} is the
additional (\type {\vbox spread}) or exact (\type {\vbox to}) height to be used.

\startfunctioncall
<node> h, <number> b =
    node.vpack(<node> n)
<node> h, <number> b =
    node.vpack(<node> n, <number> w, <string> info)
<node> h, <number> b =
    node.vpack(<node> n, <number> w, <string> info, <string> dir)
\stopfunctioncall

The second return value is the badness of the generated box. See the description
of \type {hpack} for a few memory allocation caveats.

\subsection{\type {prepend_prevdepth}}

\libindex {prepend_prevdepth}

This function is somewhat special in the sense that it is an experimental helper
that adds the interlinespace to a line keeping the baselineskip and lineskip into
account.

\startfunctioncall
<node> n, <number> delta =
    node.prepend_prevdepth(<node> n,<number> prevdepth)
\stopfunctioncall

\subsection{\type {dimensions} and \type {rangedimensions}}

\libindex{dimensions}
\libindex{rangedimensions}

\startfunctioncall
<number> w, <number> h, <number> d  =
    node.dimensions(<node> n)
<number> w, <number> h, <number> d  =
    node.dimensions(<node> n, <string> dir)
<number> w, <number> h, <number> d  =
    node.dimensions(<node> n, <node> t)
<number> w, <number> h, <number> d  =
    node.dimensions(<node> n, <node> t, <string> dir)
\stopfunctioncall

This function calculates the natural in|-|line dimensions of the node list starting
at node \type {n} and terminating just before node \type {t} (or the end of the
list, if there is no second argument). The return values are scaled points. An
alternative format that starts with glue parameters as the first three arguments
is also possible:

\startfunctioncall
<number> w, <number> h, <number> d  =
    node.dimensions(<number> glue_set, <number> glue_sign, <number> glue_order,
        <node> n)
<number> w, <number> h, <number> d  =
    node.dimensions(<number> glue_set, <number> glue_sign, <number> glue_order,
        <node> n, <string> dir)
<number> w, <number> h, <number> d  =
    node.dimensions(<number> glue_set, <number> glue_sign, <number> glue_order,
        <node> n, <node> t)
<number> w, <number> h, <number> d  =
    node.dimensions(<number> glue_set, <number> glue_sign, <number> glue_order,
        <node> n, <node> t, <string> dir)
\stopfunctioncall

This calling method takes glue settings into account and is especially useful for
finding the actual width of a sublist of nodes that are already boxed, for
example in code like this, which prints the width of the space in between the
\type {a} and \type {b} as it would be if \type {\box0} was used as-is:

\starttyping
\setbox0 = \hbox to 20pt {a b}

\directlua{print (node.dimensions(
    tex.box[0].glue_set,
    tex.box[0].glue_sign,
    tex.box[0].glue_order,
    tex.box[0].head.next,
    node.tail(tex.box[0].head)
)) }
\stoptyping

You need to keep in mind that this is one of the few places in \TEX\ where floats
are used, which means that you can get small differences in rounding when you
compare the width reported by \type {hpack} with \type {dimensions}.

The second alternative saves a few lookups and can be more convenient in some
cases:

\startfunctioncall
<number> w, <number> h, <number> d  =
    node.rangedimensions(<node> parent, <node> first)
<number> w, <number> h, <number> d  =
    node.rangedimensions(<node> parent, <node> first, <node> last)
\stopfunctioncall

\subsection{\type {mlist_to_hlist}}

\libindex {mlist_to_hlist}

\startfunctioncall
<node> h =
    node.mlist_to_hlist(<node> n, <string> display_type, <boolean> penalties)
\stopfunctioncall

This runs the internal mlist to hlist conversion, converting the math list in
\type {n} into the horizontal list \type {h}. The interface is exactly the same
as for the callback \cbk {mlist_to_hlist}.

\subsection{\type {slide}}

\startfunctioncall
<node> m =
    node.slide(<node> n)
\stopfunctioncall

Returns the last node of the node list that starts at \type {n}. As a
side|-|effect, it also creates a reverse chain of \type {prev} pointers between
nodes.

\subsection{\type {tail}}

\libindex {tail}

\startfunctioncall
<node> m =
    node.tail(<node> n)
\stopfunctioncall

Returns the last node of the node list that starts at \type {n}.

\subsection{\type {length} and type {count}}

\libindex {length}
\libindex {count}

\startfunctioncall
<number> i =
    node.length(<node> n)
<number> i =
    node.length(<node> n, <node> m)
\stopfunctioncall

Returns the number of nodes contained in the node list that starts at \type {n}.
If \type {m} is also supplied it stops at \type {m} instead of at the end of the
list. The node \type {m} is not counted.

\startfunctioncall
<number> i =
    node.count(<number> id, <node> n)
<number> i =
    node.count(<number> id, <node> n, <node> m)
\stopfunctioncall

Returns the number of nodes contained in the node list that starts at \type {n}
that have a matching \type {id} field. If \type {m} is also supplied, counting
stops at \type {m} instead of at the end of the list. The node \type {m} is not
counted. This function also accept string \type {id}'s.

\subsection{\type {is_char} and \type {is_glyph}}

\libindex {is_char}
\libindex {is_glyph}

The subtype of a glyph node signals if the glyph is already turned into a character reference
or not.

\startfunctioncall
<boolean> b =
    node.is_char(<node> n)
<boolean> b =
    node.is_glyph(<node> n)
\stopfunctioncall

\subsection{\type {traverse}}

\libindex {traverse}

\startfunctioncall
<node> t, id, subtype =
    node.traverse(<node> n)
\stopfunctioncall

This is a \LUA\ iterator that loops over the node list that starts at \type {n}.
Typically code looks like this:

\starttyping
for n in node.traverse(head) do
   ...
end
\stoptyping

is functionally equivalent to:

\starttyping
do
  local n
  local function f (head,var)
    local t
    if var == nil then
       t = head
    else
       t = var.next
    end
    return t
  end
  while true do
    n = f (head, n)
    if n == nil then break end
    ...
  end
end
\stoptyping

It should be clear from the definition of the function \type {f} that even though
it is possible to add or remove nodes from the node list while traversing, you
have to take great care to make sure all the \type {next} (and \type {prev})
pointers remain valid.

If the above is unclear to you, see the section \quote {For Statement} in the
\LUA\ Reference Manual.

\subsection{\type {traverse_id}}

\libindex {traverse_id}

\startfunctioncall
<node> t, subtype =
    node.traverse_id(<number> id, <node> n)
\stopfunctioncall

This is an iterator that loops over all the nodes in the list that starts at
\type {n} that have a matching \type {id} field.

See the previous section for details. The change is in the local function \type
{f}, which now does an extra while loop checking against the upvalue \type {id}:

\starttyping
 local function f(head,var)
   local t
   if var == nil then
      t = head
   else
      t = var.next
   end
   while not t.id == id do
      t = t.next
   end
   return t
 end
\stoptyping

\subsection{\type {traverse_char} and \type {traverse_glyph}}

\libindex {traverse_char}
\libindex {traverse_glyph}

The \type{traverse_char} iterator loops over the \nod {glyph} nodes in a list.
Only nodes with a subtype less than 256 are seen.

\startfunctioncall
<node> n, font, char =
    node.traverse_char(<node> n)
\stopfunctioncall

The \type{traverse_glyph} iterator loops over a list and returns the list and
filters all glyphs:

\startfunctioncall
<node> n, font, char =
    node.traverse_glyph(<node> n)
\stopfunctioncall

\subsection{\type {traverse_list}}

\libindex {traverse_list}

This iterator loops over the \nod {hlist} and \nod {vlist} nodes in a list.

\startfunctioncall
<node> n, id, subtype, list =
    node.traverse_list(<node> n)
\stopfunctioncall

The four return values can save some time compared to fetching these fields but
in practice you seldom need them all. So consider it a (side effect of
experimental) convenience.

\subsection{\type {has_glyph}}

\libindex {has_glyph}

This function returns the first glyph or disc node in the given list:

\startfunctioncall
<node> n =
    node.has_glyph(<node> n)
\stopfunctioncall

\subsection{\type {end_of_math}}

\libindex {end_of_math}

\startfunctioncall
<node> t =
    node.end_of_math(<node> start)
\stopfunctioncall

Looks for and returns the next \type {math_node} following the \type {start}. If
the given node is a math end node this helper returns that node, else it follows
the list and returns the next math endnote. If no such node is found nil is
returned.

\subsection{\type {remove}}

\libindex {remove}

\startfunctioncall
<node> head, current =
    node.remove(<node> head, <node> current)
\stopfunctioncall

This function removes the node \type {current} from the list following \type
{head}. It is your responsibility to make sure it is really part of that list.
The return values are the new \type {head} and \type {current} nodes. The
returned \type {current} is the node following the \type {current} in the calling
argument, and is only passed back as a convenience (or \type {nil}, if there is
no such node). The returned \type {head} is more important, because if the
function is called with \type {current} equal to \type {head}, it will be
changed.

\subsection{\type {insert_before}}

\libindex {insert_before}

\startfunctioncall
<node> head, new =
    node.insert_before(<node> head, <node> current, <node> new)
\stopfunctioncall

This function inserts the node \type {new} before \type {current} into the list
following \type {head}. It is your responsibility to make sure that \type
{current} is really part of that list. The return values are the (potentially
mutated) \type {head} and the node \type {new}, set up to be part of the list
(with correct \type {next} field). If \type {head} is initially \type {nil}, it
will become \type {new}.

\subsection{\type {insert_after}}

\libindex {insert_after}

\startfunctioncall
<node> head, new =
    node.insert_after(<node> head, <node> current, <node> new)
\stopfunctioncall

This function inserts the node \type {new} after \type {current} into the list
following \type {head}. It is your responsibility to make sure that \type
{current} is really part of that list. The return values are the \type {head} and
the node \type {new}, set up to be part of the list (with correct \type {next}
field). If \type {head} is initially \type {nil}, it will become \type {new}.

\subsection{\type {first_glyph}}

\libindex {first_glyph}

\startfunctioncall
<node> n =
    node.first_glyph(<node> n)
<node> n =
    node.first_glyph(<node> n, <node> m)
\stopfunctioncall

Returns the first node in the list starting at \type {n} that is a glyph node
with a subtype indicating it is a glyph, or \type {nil}. If \type {m} is given,
processing stops at (but including) that node, otherwise processing stops at the
end of the list.

\subsection{\type {ligaturing}}

\libindex {ligaturing}

\startfunctioncall
<node> h, <node> t, <boolean> success =
    node.ligaturing(<node> n)
<node> h, <node> t, <boolean> success =
    node.ligaturing(<node> n, <node> m)
\stopfunctioncall

Apply \TEX-style ligaturing to the specified nodelist. The tail node \type {m} is
optional. The two returned nodes \type {h} and \type {t} are the new head and
tail (both \type {n} and \type {m} can change into a new ligature).

\subsection{\type {kerning}}

\libindex {kerning}

\startfunctioncall
<node> h, <node> t, <boolean> success =
    node.kerning(<node> n)
<node> h, <node> t, <boolean> success =
    node.kerning(<node> n, <node> m)
\stopfunctioncall

Apply \TEX|-|style kerning to the specified node list. The tail node \type {m} is
optional. The two returned nodes \type {h} and \type {t} are the head and tail
(either one of these can be an inserted kern node, because special kernings with
word boundaries are possible).

\subsection{\type {unprotect_glyph[s]}}

\libindex {unprotect_glyphs}
\libindex {unprotect_glyph}

\startfunctioncall
node.unprotect_glyph(<node> n)
node.unprotect_glyphs(<node> n,[<node> n])
\stopfunctioncall

Subtracts 256 from all glyph node subtypes. This and the next function are
helpers to convert from \type {characters} to \type {glyphs} during node
processing. The second argument is optional and indicates the end of a range.

\subsection{\type {protect_glyph[s]}}

\libindex {protect_glyphs}
\libindex {protect_glyph}

\startfunctioncall
node.protect_glyph(<node> n)
node.protect_glyphs(<node> n,[<node> n])
\stopfunctioncall

Adds 256 to all glyph node subtypes in the node list starting at \type {n},
except that if the value is 1, it adds only 255. The special handling of 1 means
that \type {characters} will become \type {glyphs} after subtraction of 256. A
single character can be marked by the singular call. The second argument is
optional and indicates the end of a range.

\subsection{\type {last_node}}

\libindex {last_node}

\startfunctioncall
<node> n =
    node.last_node()
\stopfunctioncall

This function pops the last node from \TEX's \quote{current list}. It returns
that node, or \type {nil} if the current list is empty.

\subsection{\type {write}}

\libindex {write}

\startfunctioncall
node.write(<node> n)
\stopfunctioncall

This function that will append a node list to \TEX's \quote {current list}. The
node list is not deep|-|copied! There is no error checking either! You mignt need
to enforce horizontal mode in order for this to work as expected.

\subsection{\type {protrusion_skippable}}

\libindex {protrusion_skippable}

\startfunctioncall
<boolean> skippable =
    node.protrusion_skippable(<node> n)
\stopfunctioncall

Returns \type {true} if, for the purpose of line boundary discovery when
character protrusion is active, this node can be skipped.

\stopsection

\startsection[title={Glue handling}][library=node]

\subsection{\type {setglue}}

\libindex {setglue}

You can set the five properties of a glue in one go. Non|-|numeric values are
equivalent to zero and reset a property.

\startfunctioncall
node.setglue(<node> n)
node.setglue(<node> n,width,stretch,shrink,stretch_order,shrink_order)
\stopfunctioncall

When you pass values, only arguments that are numbers are assigned so

\starttyping
node.setglue(n,655360,false,65536)
\stoptyping

will only adapt the width and shrink.

When a list node is passed, you set the glue, order and sign instead.

\subsection{\type {getglue}}

\libindex {getglue}

The next call will return 5 values or nothing when no glue is passed.

\startfunctioncall
<integer> width, <integer> stretch, <integer> shrink, <integer> stretch_order,
    <integer> shrink_order = node.getglue(<node> n)
\stopfunctioncall

When the second argument is false, only the width is returned (this is consistent
with \type {tex.get}).

When a list node is passed, you get back the glue that is set, the order of that
glue and the sign.

\subsection{\type {is_zero_glue}}

\libindex {is_zero_glue}

This function returns \type {true} when the width, stretch and shrink properties
are zero.

\startfunctioncall
<boolean> isglue =
    node.is_zero_glue(<node> n)
\stopfunctioncall

\stopsection

\startsection[title={Attribute handling}][library=node]

\subsection{Attributes}

\topicindex {attributes}

The newly introduced attribute registers are non|-|trivial, because the value
that is attached to a node is essentially a sparse array of key|-|value pairs. It
is generally easiest to deal with attribute lists and attributes by using the
dedicated functions in the \type {node} library, but for completeness, here is
the low|-|level interface.

Attributes appear as linked list of userdata objects in the \type {attr} field of
individual nodes. They can be handled individually, but it is much safer and more
efficient to use the dedicated functions associated with them.

\subsection{\nod {attribute_list} nodes}

\topicindex {nodes+attributes}

An \nod {attribute_list} item is used as a head pointer for a list of attribute
items. It has only one user-visible field:

\starttabulate[|l|l|p|]
\DB field       \BC type \BC explanation \NC \NR
\TB
\NC \type{next} \NC node \NC pointer to the first attribute \NC \NR
\LL
\stoptabulate

\subsection{\nod {attr} nodes}

A normal node's attribute field will point to an item of type \nod
{attribute_list}, and the \type {next} field in that item will point to the first
defined \quote {attribute} item, whose \type {next} will point to the second
\quote {attribute} item, etc.

\starttabulate[|l|l|p|]
\DB field         \BC type   \BC explanation \NC \NR
\TB
\NC \type{next}   \NC node   \NC pointer to the next attribute \NC \NR
\NC \type{number} \NC number \NC the attribute type id \NC \NR
\NC \type{value}  \NC number \NC the attribute value \NC \NR
\LL
\stoptabulate

As mentioned it's better to use the official helpers rather than edit these
fields directly. For instance the \type {prev} field is used for other purposes
and there is no double linked list.

\subsection{\type {has_attribute}}

\libindex {has_attribute}

\startfunctioncall
<number> v =
    node.has_attribute(<node> n, <number> id)
<number> v =
    node.has_attribute(<node> n, <number> id, <number> val)
\stopfunctioncall

Tests if a node has the attribute with number \type {id} set. If \type {val} is
also supplied, also tests if the value matches \type {val}. It returns the value,
or, if no match is found, \type {nil}.

\subsection{\type {get_attribute}}

\libindex {get_attribute}

\startfunctioncall
<number> v =
    node.get_attribute(<node> n, <number> id)
\stopfunctioncall

Tests if a node has an attribute with number \type {id} set. It returns the
value, or, if no match is found, \type {nil}. If no \type {id} is given then the
zero attributes is assumed.

\subsection{\type {find_attribute}}

\libindex {find_attribute}

\startfunctioncall
<number> v, <node> n =
    node.find_attribute(<node> n, <number> id)
\stopfunctioncall

Finds the first node that has attribute with number \type {id} set. It returns
the value and the node if there is a match and otherwise nothing.

\subsection{\type {set_attribute}}

\libindex {set_attribute}

\startfunctioncall
node.set_attribute(<node> n, <number> id, <number> val)
\stopfunctioncall

Sets the attribute with number \type {id} to the value \type {val}. Duplicate
assignments are ignored.

\subsection{\type {unset_attribute}}

\libindex {unset_attribute}

\startfunctioncall
<number> v =
    node.unset_attribute(<node> n, <number> id)
<number> v =
    node.unset_attribute(<node> n, <number> id, <number> val)
\stopfunctioncall

Unsets the attribute with number \type {id}. If \type {val} is also supplied, it
will only perform this operation if the value matches \type {val}. Missing
attributes or attribute|-|value pairs are ignored.

If the attribute was actually deleted, returns its old value. Otherwise, returns
\type {nil}.

\subsection{\type {slide}}

\libindex {slide}

This helper makes sure that the node lists is double linked and returns the found
tail node.

\startfunctioncall
<node> tail =
    node.slide(<node> n)
\stopfunctioncall

After some callbacks automatic sliding takes place. This feature can be turned
off with \type {node.fix_node_lists(false)} but you better make sure then that
you don't mess up lists. In most cases \TEX\ itself only uses \type {next}
pointers but your other callbacks might expect proper \type {prev} pointers too.
Future versions of \LUATEX\ can add more checking but this will not influence
usage.

\subsection{\type {check_discretionary}, \type {check_discretionaries}}

\libindex{check_discretionary}
\libindex{check_discretionaries}

When you fool around with disc nodes you need to be aware of the fact that they
have a special internal data structure. As long as you reassign the fields when
you have extended the lists it's ok because then the tail pointers get updated,
but when you add to list without reassigning you might end up in trouble when
the linebreak routine kicks in. You can call this function to check the list for
issues with disc nodes.

\startfunctioncall
node.check_discretionary(<node> n)
node.check_discretionaries(<node> head)
\stopfunctioncall

The plural variant runs over all disc nodes in a list, the singular variant
checks one node only (it also checks if the node is a disc node).

\subsection{\type {flatten_discretionaries}}

\libindex {flatten_discretionaries}

This function will remove the discretionaries in the list and inject the replace
field when set.

\startfunctioncall
<node> head, count = node.flatten_discretionaries(<node> n)
\stopfunctioncall

\subsection{\type {family_font}}

\libindex {family_font}

When you pass a proper family identifier the next helper will return the font
currently associated with it. You can normally also access the font with the
normal font field or getter because it will resolve the family automatically for
noads.

\startfunctioncall
<integer> id =
    node.family_font(<integer> fam)
\stopfunctioncall

\stopsection

\startsection[title={Two access models}][library=node]

\topicindex{nodes+direct}
\topicindex{direct nodes}

\libindex {todirect}
\libindex {tonode}
\libindex {tostring}

Deep down in \TEX\ a node has a number which is a numeric entry in a memory
table. In fact, this model, where \TEX\ manages memory is real fast and one of
the reasons why plugging in callbacks that operate on nodes is quite fast too.
Each node gets a number that is in fact an index in the memory table and that
number often is reported when you print node related information. You go from
userdata nodes and there numeric references and back with:

\startfunctioncall
<integer> d = node.todirect(<node> n))
<node> n = node.tonode(<integer> d))
\stopfunctioncall

The userdata model is rather robust as it is a virtual interface with some
additional checking while the more direct access which uses the node numbers
directly. However, even with userdata you can get into troubles when you free
nodes that are no longer allocated or mess up lists. if you apply \type
{tostring} to a node you see its internal (direct) number and id.

The first model provides key based access while the second always accesses fields
via functions:

\starttyping
nodeobject.char
getfield(nodenumber,"char")
\stoptyping

If you use the direct model, even if you know that you deal with numbers, you
should not depend on that property but treat it as an abstraction just like
traditional nodes. In fact, the fact that we use a simple basic datatype has the
penalty that less checking can be done, but less checking is also the reason why
it's somewhat faster. An important aspect is that one cannot mix both methods,
but you can cast both models. So, multiplying a node number makes no sense.

So our advice is: use the indexed (table) approach when possible and investigate
the direct one when speed might be a real issue. For that reason \LUATEX\ also
provide the \type {get*} and \type {set*} functions in the top level node
namespace. There is a limited set of getters. When implementing this direct
approach the regular index by key variant was also optimized, so direct access
only makes sense when nodes are accessed millions of times (which happens in some
font processing for instance).

We're talking mostly of getters because setters are less important. Documents
have not that many content related nodes and setting many thousands of properties
is hardly a burden contrary to millions of consultations.

Normally you will access nodes like this:

\starttyping
local next = current.next
if next then
    -- do something
end
\stoptyping

Here \type {next} is not a real field, but a virtual one. Accessing it results in
a metatable method being called. In practice it boils down to looking up the node
type and based on the node type checking for the field name. In a worst case you
have a node type that sits at the end of the lookup list and a field that is last
in the lookup chain. However, in successive versions of \LUATEX\ these lookups
have been optimized and the most frequently accessed nodes and fields have a
higher priority.

Because in practice the \type {next} accessor results in a function call, there
is some overhead involved. The next code does the same and performs a tiny bit
faster (but not that much because it is still a function call but one that knows
what to look up).

\starttyping
local next = node.next(current)
if next then
    -- do something
end
\stoptyping

Some accessors are used frequently and for these we provide more efficient helpers:

\starttabulate[|l|p|]
\DB function          \BC explanation \NC \NR
\TB
\NC \type{getnext}    \NC parsing nodelist always involves this one \NC \NR
\NC \type{getprev}    \NC used less but a logical companion to \type {getnext} \NC \NR
\NC \type{getboth}    \NC returns the next and prev pointer of a node \NC \NR
\NC \type{getid}      \NC consulted a lot \NC \NR
\NC \type{getsubtype} \NC consulted less but also a topper \NC \NR
\NC \type{getfont}    \NC used a lot in \OPENTYPE\ handling (glyph nodes are consulted a lot) \NC \NR
\NC \type{getchar}    \NC idem and also in other places \NC \NR
\NC \type{getwhd}     \NC returns the \type {width}, \type {height} and \type {depth} of a list, rule or
                          (unexpanded) glyph as well as glue (its spec is looked at) and unset nodes\NC \NR
\NC \type{getdisc}    \NC returns the \type {pre}, \type {post} and \type {replace} fields and
                          optionally when true is passed also the tail fields \NC \NR
\NC \type{getlist}    \NC we often parse nested lists so this is a convenient one too \NC \NR
\NC \type{getleader}  \NC comparable to list, seldom used in \TEX\ (but needs frequent consulting
                          like lists; leaders could have been made a dedicated node type) \NC \NR
\NC \type{getfield}   \NC generic getter, sufficient for the rest (other field names are
                          often shared so a specific getter makes no sense then) \NC \NR
\NC \type{getbox}     \NC gets the given box (a list node) \NC \NR
\NC \type{getoffsets} \NC gets the \type {xoffset} and \type {yoffset} of a glyph or
                          \type {left} and \type {right} values of a rule \NC \NR
\LL
\stoptabulate

In the direct namespace there are more such helpers and most of them are
accompanied by setters. The getters and setters are clever enough to see what
node is meant. We don't deal with whatsit nodes: their fields are always accessed
by name. It doesn't make sense to add getters for all fields, we just identifier
the most likely candidates. In complex documents, many node and fields types
never get seen, or seen only a few times, but for instance glyphs are candidates
for such optimization. The \type {node.direct} interface has some more helpers.
\footnote {We can define the helpers in the node namespace with \type {getfield}
which is about as efficient, so at some point we might provide that as module.}

The \type {setdisc} helper takes three (optional) arguments plus an optional
fourth indicating the subtype. Its \type {getdisc} takes an optional boolean;
when its value is \type {true} the tail nodes will also be returned. The \type
{setfont} helper takes an optional second argument, it being the character. The
directmode setter \type {setlink} takes a list of nodes and will link them,
thereby ignoring \type {nil} entries. The first valid node is returned (beware:
for good reason it assumes single nodes). For rarely used fields no helpers are
provided and there are a few that probably are used seldom too but were added for
consistency. You can of course always define additional accessors using \type
{getfield} and \type {setfield} with little overhead. When the second argument of
\type {setattributelist} is \type {true} the current attribute list is assumed.

\def\yes{$+$} \def\nop{$-$}

\def\supported#1#2#3%
 {\NC \type{#1}
  \NC \ifx#2\yes\lix{node}       {#1}\fi #2
  \NC \ifx#3\yes\lix{node.direct}{#1}\fi #3 \NC
  \NR}

\starttabulate[|l|c|c|]
\DB function \BC node \BC direct \NC \NR
\TB
\supported {check_discretionaries}   \yes \yes
\supported {check_discretionary}     \yes \yes
\supported {copy_list}               \yes \yes
\supported {copy}                    \yes \yes
\supported {count}                   \yes \yes
\supported {current_attr}            \yes \yes
\supported {dimensions}              \yes \yes
\supported {effective_glue}          \yes \yes
\supported {end_of_math}             \yes \yes
\supported {family_font}             \yes \nop
\supported {fields}                  \yes \nop
\supported {find_attribute}          \yes \yes
\supported {first_glyph}             \yes \yes
\supported {flatten_discretionaries} \yes \yes
\supported {flush_list}              \yes \yes
\supported {flush_node}              \yes \yes
\supported {free}                    \yes \yes
\supported {get_attribute}           \yes \yes
\supported {get_synctex_fields}      \nop \yes
\supported {getattributelist}        \nop \yes
\supported {getboth}                 \yes \yes
\supported {getbox}                  \nop \yes
\supported {getchar}                 \yes \yes
\supported {getcomponents}           \nop \yes
\supported {getdepth}                \nop \yes
\supported {getdirection}            \nop \yes
\supported {getdir}                  \nop \yes
\supported {getdisc}                 \yes \yes
\supported {getfam}                  \nop \yes
\supported {getfield}                \yes \yes
\supported {getfont}                 \yes \yes
\supported {getglue}                 \yes \yes
\supported {getheight}               \nop \yes
\supported {getid}                   \yes \yes
\supported {getkern}                 \nop \yes
\supported {getlang}                 \nop \yes
\supported {getleader}               \yes \yes
\supported {getlist}                 \yes \yes
\supported {getnext}                 \yes \yes
\supported {getnucleus}              \nop \yes
\supported {getoffsets}              \nop \yes
\supported {getpenalty}              \nop \yes
\supported {getprev}                 \yes \yes
\supported {getproperty}             \yes \yes
\supported {getshift}                \nop \yes
\supported {getsubtype}              \yes \yes
\supported {getsub}                  \nop \yes
\supported {getsup}                  \nop \yes
\supported {getdata}                 \nop \yes
\supported {getwhd}                  \yes \yes
\supported {getwidth}                \nop \yes
\supported {has_attribute}           \yes \yes
\supported {has_field}               \yes \yes
\supported {has_glyph}               \yes \yes
\supported {hpack}                   \yes \yes
\supported {id}                      \yes \nop
\supported {insert_after}            \yes \yes
\supported {insert_before}           \yes \yes
\supported {is_char}                 \yes \yes
\supported {is_direct}               \nop \yes
\supported {is_glyph}                \yes \yes
\supported {is_node}                 \yes \yes
\supported {is_zero_glue}            \yes \yes
\supported {kerning}                 \yes \yes
\supported {last_node}               \yes \yes
\supported {length}                  \yes \yes
\supported {ligaturing}              \yes \yes
\supported {mlist_to_hlist}          \yes \nop
\supported {new}                     \yes \yes
\supported {next}                    \yes \nop
\supported {prepend_prevdepth}       \nop \yes
\supported {prev}                    \yes \nop
\supported {protect_glyphs}          \yes \yes
\supported {protect_glyph}           \yes \yes
\supported {protrusion_skippable}    \yes \yes
\supported {rangedimensions}         \yes \yes
\supported {remove}                  \yes \yes
\supported {set_attribute}           \yes \yes
\supported {set_synctex_fields}      \nop \yes
\supported {setattributelist}        \nop \yes
\supported {setboth}                 \nop \yes
\supported {setbox}                  \nop \yes
\supported {setchar}                 \nop \yes
\supported {setcomponents}           \nop \yes
\supported {setdepth}                \nop \yes
\supported {setdirection}            \nop \yes
\supported {setdir}                  \nop \yes
\supported {setdisc}                 \nop \yes
\supported {setfam}                  \nop \yes
\supported {setfield}                \yes \yes
\supported {setfont}                 \nop \yes
\supported {setexpansion}            \nop \yes
\supported {setglue}                 \yes \yes
\supported {setheight}               \nop \yes
\supported {setkern}                 \nop \yes
\supported {setlang}                 \nop \yes
\supported {setleader}               \nop \yes
\supported {setlink}                 \nop \yes
\supported {setlist}                 \nop \yes
\supported {setnext}                 \nop \yes
\supported {setnucleus}              \nop \yes
\supported {setoffsets}              \nop \yes
\supported {setpenalty}              \nop \yes
\supported {setprev}                 \nop \yes
\supported {setproperty}             \yes \yes
\supported {setshift}                \nop \yes
\supported {setsplit}                \nop \yes
\supported {setsubtype}              \nop \yes
\supported {setsub}                  \nop \yes
\supported {setsup}                  \nop \yes
\supported {setwhd}                  \nop \yes
\supported {setwidth}                \nop \yes
\supported {slide}                   \yes \yes
\supported {subtypes}                \yes \nop
\supported {subtype}                 \yes \nop
\supported {tail}                    \yes \yes
\supported {todirect}                \yes \yes
\supported {tonode}                  \yes \yes
\supported {tostring}                \yes \yes
\supported {traverse_char}           \yes \yes
\supported {traverse_glyph}          \yes \yes
\supported {traverse_id}             \yes \yes
\supported {traverse}                \yes \yes
\supported {types}                   \yes \nop
\supported {type}                    \yes \nop
\supported {unprotect_glyphs}        \yes \yes
\supported {unprotect_glyph}         \yes \yes
\supported {unset_attribute}         \yes \yes
\supported {usedlist}                \yes \yes
\supported {uses_font}               \yes \yes
\supported {vpack}                   \yes \yes
\supported {whatsits}                \yes \nop
\supported {write}                   \yes \yes
\LL
\stoptabulate

The \type {node.next} and \type {node.prev} functions will stay but for
consistency there are variants called \type {getnext} and \type {getprev}. We had
to use \type {get} because \type {node.id} and \type {node.subtype} are already
taken for providing meta information about nodes. Note: The getters do only basic
checking for valid keys. You should just stick to the keys mentioned in the
sections that describe node properties.

Some of the getters and setters handle multiple node types, given that the field
is relevant. In that case, some field names are considered similar (like \type
{kern} and \type {width}, or \type {data} and \type {value}. In retrospect we
could have normalized field names better but we decided to stick to the original
(internal) names as much as possible. After all, at the \LUA\ end one can easily
create synonyms.

Some nodes have indirect references. For instance a math character refers to a
family instead of a font. In that case we provide a virtual font field as
accessor. So, \type {getfont} and \type {.font} can be used on them. The same is
true for the \type {width}, \type {height} and \type {depth} of glue nodes. These
actually access the spec node properties, and here we can set as well as get the
values.

In some places \LUATEX\ can do a bit of extra checking for valid node lists and
you can enable that with:

\startfunctioncall
node.fix_node_lists(<boolean> b)
\stopfunctioncall

You can set and query the \SYNCTEX\ fields, a file number aka tag and a line
number, for a glue, kern, hlist, vlist, rule and math nodes as well as glyph
nodes (although this last one is not used in native \SYNCTEX).

\startfunctioncall
node.set_synctex_fields(<integer> f, <integer> l)
<integer> f, <integer> l =
    node.get_synctex_fields(<node> n)
\stopfunctioncall

Of course you need to know what you're doing as no checking on sane values takes
place. Also, the synctex interpreter used in editors is rather peculiar and has
some assumptions (heuristics).

\stopsection

\startsection[title={Properties}][library=node]

\topicindex {nodes+properties}
\topicindex {properties}

\libindex{flush_properties_table}
\libindex{get_properties_table}
\libindex{set_properties_mode}

Attributes are a convenient way to relate extra information to a node. You can
assign them at the \TEX\ end as well as at the \LUA\ end and and consult them at
the \LUA\ end. One big advantage is that they obey grouping. They are linked
lists and normally checking for them is pretty efficient, even if you use a lot
of them. A macro package has to provide some way to manage these attributes at the
\TEX\ end because otherwise clashes in their usage can occur.

Each node also can have a properties table and you can assign values to this
table using the \type {setproperty} function and get properties using the \type
{getproperty} function. Managing properties is way more demanding than managing
attributes.

Take the following example:

\starttyping
\directlua {
    local n = node.new("glyph")

    node.setproperty(n,"foo")
    print(node.getproperty(n))

    node.setproperty(n,"bar")
    print(node.getproperty(n))

    node.free(n)
}
\stoptyping

This will print \type {foo} and \type {bar} which in itself is not that useful
when multiple mechanisms want to use this feature. A variant is:

\starttyping
\directlua {
    local n = node.new("glyph")

    node.setproperty(n,{ one = "foo", two = "bar" })
    print(node.getproperty(n).one)
    print(node.getproperty(n).two)

    node.free(n)
}
\stoptyping

This time we store two properties with the node. It really makes sense to have a
table as property because that way we can store more. But in order for that to
work well you need to do it this way:

\starttyping
\directlua {
    local n = node.new("glyph")

    local t = node.getproperty(n)

    if not t then
        t = { }
        node.setproperty(n,t)
    end
    t.one = "foo"
    t.two = "bar"

    print(node.getproperty(n).one)
    print(node.getproperty(n).two)

    node.free(n)
}
\stoptyping

Here our own properties will not overwrite other users properties unless of
course they use the same keys. So, eventually you will end up with something:

\starttyping
\directlua {
    local n = node.new("glyph")

    local t = node.getproperty(n)

    if not t then
        t = { }
        node.setproperty(n,t)
    end
    t.myself = { one = "foo", two = "bar" }

    print(node.getproperty(n).myself.one)
    print(node.getproperty(n).myself.two)

    node.free(n)
}
\stoptyping

This assumes that only you use \type {myself} as subtable. The possibilities are
endless but care is needed. For instance, the generic font handler that ships
with \CONTEXT\ uses the \type {injections} subtable and you should not mess with
that one!

There are a few helper functions that you normally should not touch as user: \typ
{flush_properties_table} will wipe the table (normally a bad idea), \typ
{get_properties_table} and will give the table that stores properties (using
direct entries) and you can best not mess too much with that one either because
\LUATEX\ itself will make sure that entries related to nodes will get wiped when
nodes get freed, so that the \LUA\ garbage collector can do its job. In fact, the
main reason why we have this mechanism is that it saves the user (or macro
package) some work. One can easily write a property mechanism in \LUA\ where
after a shipout properties gets cleaned up but it's not entirely trivial to make
sure that with each freed node also its properties get freed, due to the fact
that there can be nodes left over for a next page. And having a callback bound to
the node deallocator would add way to much overhead.

Managing properties in the node (de)allocator functions is disabled by default
and is enabled by:

\starttyping
node.set_properties_mode(true)
\stoptyping

When we copy a node list that has a table as property, there are several possibilities: we do the same as
a new node, we copy the entry to the table in properties (a reference), we do
a deep copy of a table in the properties, we create a new table and give it
the original one as a metatable. After some experiments (that also included
timing) with these scenarios we decided that a deep copy made no sense, nor
did nilling. In the end both the shallow copy and the metatable variant were
both ok, although the second one is slower. The most important aspect to keep
in mind is that references to other nodes in properties no longer can be
valid for that copy. We could use two tables (one unique and one shared) or
metatables but that only complicates matters.

When defining a new node, we could already allocate a table but it is rather easy
to do that at the lua end e.g.\ using a metatable \type {__index} method. That
way it is under macro package control. When deleting a node, we could keep the
slot (e.g. setting it to false) but it could make memory consumption raise
unneeded when we have temporary large node lists and after that only small lists.
Both are not done.

So in the end this is what happens now: when a node is copied, and it has a table
as property, the new node will share that table. If the second argument of \typ
{set_properties_mode} is \type {true} then a metatable approach is chosen: the
copy gets its own table with the original table as metatable. If you use the
generic font loader the mode is enabled that way.

A few more xperiments were done. For instance: copy attributes to the properties
so that we have fast access at the \LUA\ end. In the end the overhead is not
compensated by speed and convenience, in fact, attributes are not that slow when
it comes to accessing them. So this was rejected.

Another experiment concerned a bitset in the node but again the gain compared to
attributes was neglectable and given the small amount of available bits it also
demands a pretty strong agreement over what bit represents what, and this is
unlikely to succeed in the \TEX\ community. It doesn't pay off.

Just in case one wonders why properties make sense: it is not so much speed that
we gain, but more convenience: storing all kind of (temporary) data in attributes
is no fun and this mechanism makes sure that properties are cleaned up when a
node is freed. Also, the advantage of a more or less global properties table is
that we stay at the \LUA\ end. An alternative is to store a reference in the node
itself but that is complicated by the fact that the register has some limitations
(no numeric keys) and we also don't want to mess with it too much.

\stopsection

\stopchapter

\stopcomponent