SourceBrowser

cld-ctxfunctions.tex /size: 29 Kb last modification: 2021-10-28 13:50
1% language=us runpath=texruns:manuals/cld
2
3\startcomponent cld-ctxfunctions
4
5\environment cld-environment
6
7\startchapter[title={The \LUA\ interface code}]
8
9\startsection[title={Introduction}]
10
11There is a lot of \LUA\ code in \MKIV. Much is not exposed and a lot of what is
12exposed is not meant to be used directly at the \LUA\ end. But there is also
13functionality and data that can be accessed without side effects.
14
15In the following sections a subset of the built in functionality is discussed.
16There are often more functions alongside those presented but they might change or
17disappear. So, if you use undocumented features, be sure to tag them somehow in
18your source code so that you can check them out when there is an update. Best
19would be to have more functionality defined local so that it is sort of hidden
20but that would be unpractical as for instance functions are often used in other
21modules and or have to be available at the \TEX\ end.
22
23It might be tempting to add your own functions to namespaces created by \CONTEXT\
24or maybe overload some existing ones. Don't do this. First of all, there is no
25guarantee that your code will not interfere, nor that it overloads future
26functionality. Just use your own namespace. Also, future versions of \CONTEXT\
27might have a couple of protection mechanisms built in. Without doubt the
28following sections will be extended as soon as interfaces become more stable.
29
30\stopsection
31
32\startsection[title={Characters}]
33
34% not discussed:
35%
36% characters.filters.utf.addgrapheme()
37% characters.filters.utf.collapse()
38% characters.getrange()
39% characters.bidi[]
40% tex.uprint()
41% utf.string()
42% characters.flush()
43
44There are quite some data tables defined but the largest is the character
45database. You can consult this table any time you want but you're not supposed to
46add or change its content if only because changes will be overwritten when you
47update \CONTEXT. Future versions may carry more information. The table can be
48accessed using an unicode number. A relative simple entry looks as follows:
49
50\ShowLuaExampleTableHex{characters.data[0x00C1]}
51
52Much of this is rather common information but some of it is specific for use with
53\CONTEXT. Some characters have even more information, for instance those that
54deal with mathematics:
55
56\ShowLuaExampleTableHex{characters.data[0x2190]}
57
58Not all characters have a real entry. For instance most \CJK\ characters are
59virtual and share the same data:
60
61\ShowLuaExampleTableHex{characters.data[0x3456]}
62
63You can also access the table using \UTF\ characters:
64
65\ShowLuaExampleTable{characters.data["ä"]}
66
67A more verbose string access is also supported:
68
69\ShowLuaExampleTableHex{characters.data["U+0070"]}
70
71Another (less usefull) table contains information about ranges in this character
72table. You can access this table using rather verbose names, or you can use
73collapsed lowercase variants.
74
75\ShowLuaExampleTableHex{characters.blocks["CJK Compatibility Ideographs"]}
76
77\ShowLuaExampleTableHex{characters.blocks["hebrew"]}
78
79\ShowLuaExampleTableHex{characters.blocks["combiningdiacriticalmarks"]}
80
81Some fields can be accessed using functions. This can be handy when you need that
82information for tracing purposes or overviews. There is some overhead in the
83function call, but you get some extra testing for free. You can use characters as
84well as numbers as index.
85
86\ShowLuaExampleString{characters.contextname("ä")}
87\ShowLuaExampleString{characters.adobename(228)}
88\ShowLuaExampleString{characters.description("ä")}
89
90The category is normally a two character tag, but you can also ask for a more
91verbose variant:
92
93\ShowLuaExampleString{characters.category(228)}
94\ShowLuaExampleString{characters.category(228,true)}
95
96The more verbose category tags are available in a table:
97
98\ShowLuaExampleString{characters.categorytags["lu"]}
99
100There are several fields in a character entry that help us to remap a character.
101The \type {lccode} indicates the lowercase code point and the \type {uccode} to
102the uppercase code point. The \type {shcode} refers to one or more characters
103that have a similar shape.
104
105\ShowLuaExampleString{characters.shape ("ä")}
106\ShowLuaExampleString{characters.uccode("ä")}
107\ShowLuaExampleString{characters.lccode("ä")}
108
109\ShowLuaExampleString{characters.shape (100)}
110\ShowLuaExampleString{characters.uccode(100)}
111\ShowLuaExampleString{characters.lccode(100)}
112
113You can use these function or access these fields directly in an
114entry, but we also provide a few virtual tables that avoid
115accessing the whole entry. This method is rather efficient.
116
117\ShowLuaExampleString{characters.lccodes["ä"]}
118\ShowLuaExampleString{characters.uccodes["ä"]}
119\ShowLuaExampleString{characters.shcodes["ä"]}
120\ShowLuaExampleString{characters.lcchars["ä"]}
121\ShowLuaExampleString{characters.ucchars["ä"]}
122\ShowLuaExampleString{characters.shchars["ä"]}
123
124As with other tables, you can use a number instead of an \UTF\ character. Watch
125how we get a table for multiple shape codes but a string for multiple shape
126characters.
127
128\ShowLuaExampleString{characters.lcchars[0x00C6]}
129\ShowLuaExampleString{characters.ucchars[0x00C6]}
130\ShowLuaExampleString{characters.shchars[0x00C6]}
131\ShowLuaExampleTable {characters.shcodes[0x00C6]}
132
133These codes are used when we manipulate strings. Although there
134are \type {upper} and \type {lower} functions in the \type
135{string} namespace, the following ones are the real ones to be
136used in critical situations.
137
138\ShowLuaExampleString{characters.lower("ÀÁÂÃÄÅàáâãäå")}
139\ShowLuaExampleString{characters.upper("ÀÁÂÃÄÅàáâãäå")}
140\ShowLuaExampleString{characters.shaped("ÀÁÂÃÄÅàáâãäå")}
141
142A rather special one is the following:
143
144\ShowLuaExampleString{characters.lettered("Only 123 letters + count!")}
145
146With the second argument is true, spaces are kept and collapsed. Leading and
147trailing spaces are stripped.
148
149\ShowLuaExampleString{characters.lettered("Only 123 letters + count!",true)}
150
151Access to tables can happen by number or by string, although there are some
152limitations when it gets too confusing. Take for instance the number \type {8}
153and string \type {"8"}: if we would interpret the string as number we could never
154access the entry for the character eight. However, using more verbose hexadecimal
155strings works okay. The remappers are also available as functions:
156
157\ShowLuaExampleString{characters.tonumber("a")}
158\ShowLuaExampleString{characters.fromnumber(100)}
159\ShowLuaExampleString{characters.fromnumber(0x0100)}
160\ShowLuaExampleString{characters.fromnumber("0x0100")}
161\ShowLuaExampleString{characters.fromnumber("U+0100")}
162
163In addition to the already mentioned category information you can also use a more
164direct table approach:
165
166\ShowLuaExampleString{characters.categories["ä"]}
167\ShowLuaExampleString{characters.categories[100]}
168
169In a similar fashion you can test if a given character is in a specific category.
170This can save a lot of tests.
171
172\ShowLuaExampleBoolean{characters.is_character[characters.categories[67]]}
173\ShowLuaExampleBoolean{characters.is_character[67]}
174\ShowLuaExampleBoolean{characters.is_character[characters.data[67].category]}
175\ShowLuaExampleBoolean{characters.is_letter[characters.data[67].category]}
176\ShowLuaExampleBoolean{characters.is_command[characters.data[67].category]}
177
178Another virtual table is the one that provides access to special information, for
179instance about how a composed character is made up of components.
180
181\ShowLuaExampleString{characters.specialchars["ä"]}
182\ShowLuaExampleString{characters.specialchars[100]}
183
184The outcome is often similar to output that uses the shapecode information.
185
186Although not all the code deep down in \CONTEXT\ is meant for use at the user
187level, it sometimes can eb tempting to use data and helpers that are available as
188part of the general housekeeping. The next table was used when looking into
189sorting Korean. For practical reasons we limit the table to ten entries;
190otherwise we would have ended up with hundreds of pages.
191
192\startbuffer
193\startluacode
194local data = characters.data
195local map  = characters.hangul.remapped
196
197local first, last = characters.getrange("hangulsyllables")
198
199last = first + 9 -- for now
200
201context.start()
202
203context.definedfont { "file:unbatang" }
204
205context.starttabulate { "|T||T||T||T||T|" }
206for unicode = first, last do
207    local character = data[unicode]
208    local specials = character.specials
209    if specials then
210        context.NC()
211        context.formatted("%04V",unicode)
212        context.NC()
213        context.formatted("%c",unicode)
214        for i=2,4 do
215            local chr = specials[i]
216            if chr then
217                chr = map[chr] or chr
218                context.NC()
219                context.formatted("%04V",chr)
220                context.NC()
221                context.formatted("%c",chr)
222            else
223                context.NC()
224                context.NC()
225            end
226        end
227        context.NC()
228        context(character.description)
229        context.NC()
230        context.NR()
231    end
232end
233context.stoptabulate()
234
235context.stop()
236\stopluacode
237\stopbuffer
238
239\getbuffer \typebuffer
240
241\stopsection
242
243\startsection[title={Fonts}]
244
245% not discussed (as not too relevant for users):
246%
247% cache cache_version
248% nomath
249% units units_per_em
250% direction embedding encodingbytes
251% boundarychar boundarychar_label
252% has_italic has_math
253% tounicode sub
254% colorscheme (will probably become a hash)
255% language script
256% spacer
257% MathConstants and a few split_names
258%
259% tables.baselines
260
261There is a lot of code that deals with fonts but most is considered to be a black
262box. When a font is defined, its data is collected and turned into a form that
263\TEX\ likes. We keep most of that data available at the \LUA\ end so that we can
264later use it when needed. In this chapter we discuss some of the possibilities.
265More details can be found in the font manual(s) so we don't aim for completeness
266here.
267
268A font instance is identified by its id, which is a number where zero is reserved
269for the so called \type {nullfont}. The current font id can be requested by the
270following function.
271
272\ShowLuaExampleString{fonts.currentid()}
273
274The \type {fonts.current()} call returns the table with data related to the
275current id. You can access the data related to any id as follows:
276
277\starttyping
278local tfmdata = fonts.identifiers[number]
279\stoptyping
280
281Not all entries in the table make sense for the user as some are just meant to
282drive the font initialization at the \TEX\ end or the backend. The next table
283lists the most important ones. Some of the tables are just shortcuts to en entry
284in one of the \type {shared} subtables.
285
286\starttabulate[|l|Tl|p|]
287\NC \type{ascender}       \NC number \NC the height of a line conforming the font \NC \NR
288\NC \type{descender}      \NC number \NC the depth of a line conforming the font \NC \NR
289\NC \type{italicangle}    \NC number \NC the angle of the italic shapes (if present) \NC \NR
290\NC \type{designsize}     \NC number \NC the design size of the font (if known) \NC \NR
291\ML
292\NC \type{size}           \NC number \NC the size in scaled points if the font instance \NC \NR
293\NC \type{factor}         \NC number \NC the multiplication factor for unscaled dimensions \NC \NR
294\NC \type{hfactor}        \NC number \NC the horizontal multiplication factor \NC \NR
295\NC \type{vfactor}        \NC number \NC the vertical multiplication factor \NC \NR
296\NC \type{extend}         \NC number \NC the horizontal scaling to be used by the backend \NC \NR
297\NC \type{slant}          \NC number \NC the slanting to be applied by the backend \NC \NR
298\ML
299\NC \type{characters}     \NC table  \NC the scaled character (glyph) information (tfm) \NC \NR
300\NC \type{descriptions}   \NC table  \NC the original unscaled glyph information (otf, afm, tfm) \NC \NR
301\NC \type{indices}        \NC table  \NC the mapping from unicode slot to glyph index \NC \NR
302\NC \type{unicodes}       \NC table  \NC the mapoing from glyph names to unicode \NC \NR
303\NC \type{marks}          \NC table  \NC a hash table with glyphs that are marks as entry \NC \NR
304\NC \type{parameters}     \NC table  \NC the font parameters as \TEX\ likes them \NC \NR
305\NC \type{mathconstants}  \NC table  \NC the \OPENTYPE\ math parameters \NC \NR
306\NC \type{mathparameters} \NC table  \NC a reference to the \type {MathConstants} table \NC \NR
307\NC \type{shared}         \NC table  \NC a table with information shared between instances \NC \NR
308\NC \type{unique}         \NC table  \NC a table with information unique for this instance \NC \NR
309\NC \type{unscaled}       \NC table  \NC the unscaled (intermediate) table \NC \NR
310\NC \type{goodies}        \NC table  \NC the \CONTEXT\ specific extra font information \NC \NR
311\NC \type{fonts}          \NC table  \NC the table with references to other fonts \NC \NR
312\NC \type{cidinfo}        \NC table  \NC a table with special information for the backend \NC \NR
313\ML
314\NC \type{filename}       \NC string \NC the full path of the loaded font \NC \NR
315\NC \type{fontname}       \NC string \NC the font name as specified in the font (limited in size) \NC \NR
316\NC \type{fullname}       \NC string \NC the complete font name as specified in the font \NC \NR
317\NC \type{name}           \NC string \NC the (short) name of the font \NC \NR
318\NC \type{psname}         \NC string \NC the (unique) name of the font as used by the backend \NC \NR
319\ML
320\NC \type{hash}           \NC string \NC the hash that makes this instance unique \NC \NR
321\NC \type{id}             \NC number \NC the id (number) that \TEX\ will use for this instance \NC \NR
322\ML
323\NC \type{type}           \NC string \NC an idicator if the font is \type {virtual} or \type {real} \NC \NR
324\NC \type{format}         \NC string \NC a qualification for this font, e.g.\ \type {opentype} \NC \NR
325\NC \type{mode}           \NC string \NC the \CONTEXT\ processing mode, \type {node} or \type {base} \NC \NR
326\ML
327\stoptabulate
328
329The \type {parameters} table contains variables that are used by \TEX\ itself.
330You can use numbers as index and these are equivalent to the so called \type
331{\fontdimen} variables. More convenient is is to access by name:
332
333\starttabulate[|l|p|]
334\NC \type{slant}        \NC the slant per point (seldom used) \NC \NR
335\NC \type{space}        \NC the interword space \NC \NR
336\NC \type{spacestretch} \NC the interword stretch \NC \NR
337\NC \type{spaceshrink}  \NC the interword shrink \NC \NR
338\NC \type{xheight}      \NC the x|-|height (not per se the heigth of an x) \NC \NR
339\NC \type{quad}         \NC the so called em|-|width (often the width of an emdash)\NC \NR
340\NC \type{extraspace}   \NC additional space added in specific situations \NC \NR
341\stoptabulate
342
343The math parameters are rather special and explained in the \LUATEX\ manual.
344Quite certainly you never have to touch these parameters at the \LUA\ end.
345
346En entry in the \type {characters} table describes a character if we have entries
347within the \UNICODE\ range. There can be entries in the private area but these
348are normally variants of a shape or special math glyphs.
349
350\starttabulate[|l|p|]
351\NC \type{name}             \NC the name of the character \NC \NR
352\NC \type{index}            \NC the index in the raw font table \NC \NR
353\NC \type{height}           \NC the scaled height of the character \NC \NR
354\NC \type{depth}            \NC the scaled depth of the character \NC \NR
355\NC \type{width}            \NC the scaled height of the character \NC \NR
356\NC \type{tounicode}        \NC a \UTF-16 string representing the conversion back to unicode \NC \NR
357\NC \type{expansion_factor} \NC a multiplication factor for (horizontal) font expansion \NC \NR
358\NC \type{left_protruding}  \NC a multiplication factor for left side protrusion \NC \NR
359\NC \type{right_protruding} \NC a multiplication factor for right side protrusion \NC \NR
360\NC \type{italic}           \NC the italic correction \NC \NR
361\NC \type{next}             \NC a pointer to the next character in a math size chain \NC \NR
362\NC \type{vert_variants}    \NC a pointer to vertical variants conforming \OPENTYPE\ math \NC \NR
363\NC \type{horiz_variants}   \NC a pointer to horizontal variants conforming \OPENTYPE\ math \NC \NR
364\NC \type{top_accent}       \NC information with regards to math top accents \NC \NR
365\NC \type{mathkern}         \NC a table describing stepwise math kerning (following the shape) \NC \NR
366\NC \type{kerns}            \NC a table with intercharacter kerning dimensions \NC \NR
367\NC \type{ligatures}        \NC a (nested) table describing ligatures that start with this character \NC \NR
368\NC \type{commands}         \NC a table with commands that drive the backend code for a virtual shape \NC \NR
369\stoptabulate
370
371Not all entries are present for each character. Also, in so called \type {node}
372mode, the \type {ligatures} and \type {kerns} tables are empty because in that
373case they are dealt with at the \LUA\ end and not by \TEX.
374
375% \startluacode
376% local tfmdata = fonts.current()
377% context.starttabulate{ "|l|pl|" }
378%     for k, v in table.sortedhash(tfmdata) do
379%         local tv = type(v)
380%         if tv == "string" or tv == "number" or tv == "boolean" then
381%             context.NC()
382%             string.tocontext(k)
383%             context.NC()
384%             string.tocontext(tostring(v))
385%             context.NC()
386%             context.NR()
387%         end
388%     end
389% context.stoptabulate()
390% \stopluacode
391
392% \ShowLuaExampleTable{table.sortedkeys(fonts.current())}
393
394Say that you run into a glyph node and want to access the data related to that
395glyph. Given that variable \type {n} points to the node, the most verbose way of
396doing that is:
397
398\starttyping
399local g = fonts.identifiers[n.id].characters[n.char]
400\stoptyping
401
402Given the speed of \LUATEX\ this is quite fast. Another method is the following:
403
404\starttyping
405local g = fonts.characters[n.id][n.char]
406\stoptyping
407
408For some applications you might want faster access to critical
409parameters, like:
410
411\starttyping
412local quad    = fonts.quads   [n.id][n.char]
413local xheight = fonts.xheights[n.id][n.char]
414\stoptyping
415
416but that only makes sense when you don't access more than one such variable at
417the same time.
418
419Among the shared tables is the feature specification:
420
421\ShowLuaExampleTable{fonts.current().shared.features}
422
423As features are a prominent property of \OPENTYPE\ fonts, there are a few
424datatables that can be used to get their meaning.
425
426\ShowLuaExampleString{fonts.handlers.otf.tables.features['liga']}
427\ShowLuaExampleString{fonts.handlers.otf.tables.languages['nld']}
428\ShowLuaExampleString{fonts.handlers.otf.tables.scripts['arab']}
429
430There is a rather extensive font database built in but discussing its interface
431does not make much sense. Most usage happens automatically when you use the \type
432{name:} and \type {spec:} methods of defining fonts and the \type {mtx-fonts}
433script is built on top of it.
434
435\ctxlua{fonts.names.load()} % could be metatable driven
436
437\ShowLuaExampleTable{table.sortedkeys(fonts.names.data)}
438
439You can load the database (if it's not yet loaded) with:
440
441\starttyping
442names.load(reload,verbose)
443\stoptyping
444
445When the first argument is true, the database will be rebuild. The second
446arguments controls verbosity.
447
448Defining a font normally happens at the \TEX\ end but you can also do it in \LUA.
449
450\starttyping
451local id, fontdata = fonts.definers.define {
452    lookup = "file",             -- use the filename (file spec name)
453    name   = "pagella-regular",  -- in this case the filename
454    size   = 10*65535,           -- scaled points
455    global = false,              -- define the font globally
456    cs     = "MyFont",           -- associate the name \MyFont
457    method = "featureset",       -- featureset or virtual (* or @)
458    sub    = nil,                -- no subfont specifier
459    detail = "whatever",         -- the featureset (or whatever method applies)
460}
461\stoptyping
462
463In this case the \type {detail} variable defines what featureset has to be
464applied. You can define such sets at the \LUA\ end too:
465
466\starttyping
467fonts.definers.specifiers.presetcontext (
468    "whatever",
469    "default",
470    {
471        mode = "node",
472        dlig = "yes",
473    }
474)
475\stoptyping
476
477The first argument is the name of the featureset. The second argument can be an
478empty string or a reference to an existing featureset that will be taken as
479starting point. The final argument is the featureset. This can be a table or a
480string with a comma separated list of key|/|value pairs.
481
482\stopsection
483
484\startsection[title={Nodes}]
485
486Nodes are the building blocks that make a document reality. Nodes are linked into
487lists and at various moments in the typesetting process you can manipulate them.
488Deep down in \CONTEXT\ we use quite some \LUA\ magic to manipulate lists of
489nodes. Therefore it is no surprise that we have some tracing available. Take the
490following box.
491
492\startbuffer
493\setbox0\hbox{It's in \hbox{\bf all} those nodes.}
494\stopbuffer
495
496\typebuffer \getbuffer
497
498This box contains characters and glue between the words. The box is already
499constructed. There can also be kerns between characters, but of course only if
500the font provides such a feature. Let's inspect this box:
501
502\ShowLuaExampleString{nodes.toutf(tex.box[0])}
503\ShowLuaExampleString{nodes.toutf(tex.box[0].list)}
504
505This tracer returns the text and spacing and recurses into nested lists. The next
506tracer does not do this and marks non glyph nodes as \type {[-]}:
507
508\ShowLuaExampleString{nodes.listtoutf(tex.box[0])}
509\ShowLuaExampleString{nodes.listtoutf(tex.box[0].list)}
510
511A more verbose tracer is the next one. It does show a bit more detailed
512information about the glyphs nodes.
513
514\ShowLuaExampleString{nodes.tosequence(tex.box[0])}
515\ShowLuaExampleString{nodes.tosequence(tex.box[0].list)}
516
517The fourth tracer does not show that detail and collapses sequences of similar
518node types.
519
520\ShowLuaExampleString{nodes.idstostring(tex.box[0])}
521\ShowLuaExampleString{nodes.idstostring(tex.box[0].list)}
522
523The number of nodes in a list is identified with the \type {countall} function.
524Nested nodes are counted too.
525
526\ShowLuaExampleString{nodes.countall(tex.box[0])}
527\ShowLuaExampleString{nodes.countall(tex.box[0].list)}
528
529There are a lot of helpers in the \type {nodes} namespace. In fact, we map all the
530helpers provided by the engine itself under \type {nodes} too. These are described
531in the \LUATEX\ manual. There are for instance functions to check node types and
532node id's:
533
534\starttyping
535local str = node.type(1)
536local num = node.id("vlist")
537\stoptyping
538
539These are basic \LUATEX\ functions. In addition to those we also provide a few more
540helpers as well as
541mapping tables. There are two tables that map node id's to strings and backwards:
542
543\starttabulate
544\NC \type{nodes.nodecodes}    \NC regular nodes, some fo them are sort of private to the engine \NC \NR
545\NC \type{nodes.noadcodes}    \NC math nodes that later on are converted into regular nodes  \NC \NR
546\stoptabulate
547
548Nodes can have subtypes. Again we have tables that map the subtype numbers onto
549meaningfull names and reverse.
550
551\starttabulate
552\NC \type{nodes.listcodes}    \NC subtypes of \type {hlist} and \type {vlist} nodes \NC \NR
553\NC \type{nodes.kerncodes}    \NC subtypes of \type {kern} nodes \NC \NR
554\NC \type{nodes.gluecodes}    \NC subtypes of \type {glue} nodes (skips) \NC \NR
555\NC \type{nodes.glyphcodes}   \NC subtypes of \type {glyph} nodes, the subtype can change \NC \NR
556\NC \type{nodes.mathcodes}    \NC math specific subtypes \NC \NR
557\NC \type{nodes.fillcodes}    \NC these are not really subtypes but indicate the strength of the filler \NC \NR
558\NC \type{nodes.whatsitcodes} \NC subtypes of a rather large group of extension nodes \NC \NR
559\stoptabulate
560
561Some of the names of types and subtypes have underscores but you can omit them
562when you use these tables. You can use tables like this as follows:
563
564\starttyping
565local glyph_code = nodes.nodecodes.glyph
566local kern_code  = nodes.nodecodes.kern
567local glue_code  = nodes.nodecodes.glue
568
569for n in nodes.traverse(list) do
570    local id == n.id
571    if id == glyph_code then
572        ...
573    elseif id == kern_code then
574        ...
575    elseif id == glue_code then
576        ...
577    else
578        ...
579    end
580end
581\stoptyping
582
583You only need to use such temporary variables in time critical code. In spite of
584what you might think, lists are not that long and given the speed of \LUA\ (and
585successive optimizations in \LUATEX) looping over a paragraphs is rather fast.
586
587Nodes are created using \type {node.new}. If you study the \CONTEXT\ code you
588will notice that there are quite some functions in the \type {nodes.pool}
589namespace, like:
590
591\starttyping
592local g = nodes.pool.glyph(fnt,chr)
593\stoptyping
594
595Of course you need to make sure that the font id is valid and that the referred
596glyph in in the font. You can use the allocators but don't mess with the code in
597the \type {pool} namespace as this might interfere with its usage all over
598\CONTEXT.
599
600The \type {nodes} namespace provides a couple of helpers and some of them are
601similar to ones provided in the \type {node} namespace. This has practical as
602well as historic reasons. For instance some were prototypes functions that were
603later built in.
604
605\starttyping
606local head, current      = nodes.before (head, current, new)
607local head, current      = nodes.after  (head, current, new)
608local head, current      = nodes.delete (head, current)
609local head, current      = nodes.replace(head, current, new)
610local head, current, old = nodes.remove (head, current)
611\stoptyping
612
613Another category deals with attributes:
614
615\starttyping
616nodes.setattribute      (head, attribute, value)
617nodes.unsetattribute    (head, attribute)
618nodes.setunsetattribute (head, attribute, value)
619nodes.setattributes     (head, attribute, value)
620nodes.unsetattributes   (head, attribute)
621nodes.setunsetattributes(head, attribute, value)
622nodes.hasattribute      (head, attribute, value)
623\stoptyping
624
625% context(typesetters.hpack("Hello World!"))
626% context(typesetters.hpack("Hello World!",1,100*1024*10))
627
628% nodes.firstchar
629% nodes.firstcharinbox
630
631% maybe node-tst
632% tasks and so
633% number.points (to numbers)
634
635\stopsection
636
637% \startsection[title={Core}]
638%     {\em todo}
639% \stopsection
640
641\startsection[title={Resolvers}]
642
643All \IO\ is handled by functions in the \type {resolvers} namespace. Most of the
644code that you find in the \type {data-*.lua} files is of litle relevance for
645users, especially at the \LUA\ end, so we won't discuss it here in great detail.
646
647The resolver code is modelled after the \KPSE\ library that itself implements the
648\TEX\ Directory Structure in combination with a configuration file. However, we
649go a bit beyond this structure, for instance in integrating support for other
650resources that file systems. We also have our own configuration file. But
651important is that we still support a similar logic too so that regular
652configurations are dealt with.
653
654During a run \LUATEX\ needs files of a different kind: source files, font files,
655images, etc. In practice you will probably only deal with source files. The most
656fundamental function is \type {findfile}. The first argument is the filename to
657be found. A second optional argument indicates the file type.
658
659The following table relates so called formats to suffixes and variables in the
660configuration file.
661
662\startluacode
663context.starttabulate { "|lp|lp|l|" }
664context.NC() context.bold("variable")
665context.NC() context.bold("format")
666context.NC() context.bold("suffix")
667context.NC() context.NR()
668context.ML()
669for k, v in table.sortedpairs(resolvers.relations.core) do
670    local names = v.names
671    local variable = v.variable
672    local suffixes = v.suffixes
673    context.NC()
674    if variable then
675        context.type(variable)
676    end
677    context.NC()
678    if names then
679        for i=1,#names do
680            context.type(names[i])
681            context.par()
682        end
683    end
684    context.NC()
685    if suffixes then
686        context.type(table.concat(suffixes, " "))
687    end
688    context.NC()
689    context.NR()
690end
691context.stoptabulate()
692\stopluacode
693
694There are a couple of more formats but these are not that relevant in the
695perspective of \CONTEXT.
696
697When a lookup takes place, spaces are ignored and formats are normalized to
698lowercase.
699
700\ShowLuaExampleString{file.strip(resolvers.findfile("context.tex"),"tex/")}
701\ShowLuaExampleString{file.strip(resolvers.findfile("context.mkiv"),"tex/")}
702\ShowLuaExampleString{file.strip(resolvers.findfile("context"),"tex/")}
703\ShowLuaExampleString{file.strip(resolvers.findfile("data-res.lua"),"tex/")}
704\ShowLuaExampleString{file.strip(resolvers.findfile("lmsans10-bold"),"tex/")}
705\ShowLuaExampleString{file.strip(resolvers.findfile("lmsans10-bold.otf"),"tex/")}
706\ShowLuaExampleString{file.strip(resolvers.findfile("lmsans10-bold","otf"),"tex/")}
707\ShowLuaExampleString{file.strip(resolvers.findfile("lmsans10-bold","opentype"),"tex/")}
708\ShowLuaExampleString{file.strip(resolvers.findfile("lmsans10-bold","opentypefonts"),"tex/")}
709\ShowLuaExampleString{file.strip(resolvers.findfile("lmsans10-bold","opentype fonts"),"tex/")}
710
711The plural variant of this function returns one or more matches.
712
713\ShowLuaExampleTable{resolvers.findfiles("texmfcnf.lua","cnf")}
714\ShowLuaExampleTable{resolvers.findfiles("context.tex","")}
715
716% table.print(resolvers.instance.environment)
717% table.print(resolvers.instance.variables)
718% table.print(resolvers.instance.expansions)
719%
720% resolvers.expandbraces
721% resolvers.expandpath
722% resolvers.expandvar
723% resolvers.showpath
724% resolvers.var_value
725%
726% resolvers.getenv
727% resolvers.variable()
728% resolvers.expansion()
729% resolvers.is_variable
730% resolvers.is_expansion
731%
732% resolvers.unexpandedpathlist(str)
733% resolvers.unexpandedpath(str)
734% resolvers.cleanpathlist
735% resolvers.expandpath
736% resolvers.expandedpath
737% resolvers.expandedpathlistfromvariable
738% resolvers.expandpathfromvariable
739% resolvers.expandbraces
740%
741% resolvers.findpath
742% resolvers.findgivenfiles
743% resolvers.findgivenfile
744% resolvers.findwildcardfiles
745% resolvers.findwildcardfile
746% resolvers.showpath
747
748% data-tre as example
749% schemes (data-she)
750% caching (containers)
751% findbinfile  (open|load)
752% variables / environment
753% findtexfile opentexfile loadtexfile
754% file://
755
756% supp
757
758\stopsection
759
760\startsection[title={Mathematics (math)}]
761    {\em todo}
762\stopsection
763
764\startsection[title={Graphics (grph)}]
765    {\em is a separate chapter}
766\stopsection
767
768\startsection[title={Languages (lang)}]
769    {\em todo}
770\stopsection
771
772\startsection[title={MetaPost (mlib)}]
773    {\em todo}
774\stopsection
775
776\startsection[title={Lua\TeX\ (luat)}]
777    {\em todo}
778\stopsection
779
780\startsection[title={Tracing (trac)}]
781    {\em todo}
782\stopsection
783
784\stopchapter
785
786\stopcomponent
787
Source Browser ?
