1
2
3\environment luametatexstyle
4
5\startdocument[title=\TEX,xtitle=\TEX]
6
7\startsection[title={Introduction}]
8
9Here we dont explain \TEX\ itself but the interface between \TEX\ and \LUA. We
10dont need to talk nodes and tokens because they have their own chapters.
11
12\stopsection
13
14\startsection[title={Status information}]
15
16The \type {status} library provides information not only about the current run
17and system setup but also about all kind of variables and constants used in the
18engine. A difference between \LUATEX\ and \LUAMETATEX\ is that every quantity
19that is hard coded is available as a constant to be used. The same is true for
20various bit sets for instance those use in setting options, as we will see in the
21\type {tex} library.
22
23A number of runtime configuration items that you may find useful
24in message reporting, as well as an iterator function that gets all of the names
25and values as a table.
26
27\starttyping[option=LUA]
28function status.list ( )
29 return <t:table>
30end
31\stoptyping
32
33The keys in the returned table are the known items, the value is the current
34value. There are top level items and items that are tables with sub entries. The
35current list gives:
36
37\startluacode
38 local list = status.list()
39 context.starttabulate { "|T|Tp|" }
40 context.FL()
41 context.BC() context("toplevel statistics")
42 context.BC()
43 context.NC() context.NR()
44 context.TL()
45 for k, v in table.sortedhash(list) do
46 if type(v) ~= "table" then
47 context.NC() context(k)
48 context.NC() context(tostring(v))
49 context.NC() context.NR()
50 end
51 end
52 context.LL()
53 context.stoptabulate()
54 for k, v in table.sortedhash(list) do
55 if type(v) == "table" then
56 context.starttabulate { "|Tw(10em)|Tp|" }
57 context.FL()
58 context.BC() context(k ..".*")
59 context.BC()
60 context.NC() context.NR()
61 context.TL()
62 for k, v in table.sortedhash(v) do
63 context.NC() context(k)
64 context.NC() context(v == "" and "unset" or tostring(v))
65 context.NC() context.NR()
66 end
67 context.LL()
68 context.stoptabulate()
69 end
70 end
71\stopluacode
72
73The \type {getconstants} query gives back a table with all kind of internal
74quantities and again these are only relevant for diagnostic and development
75purposes. Many are good old \TEX\ constants that are describes in the original
76documentation of the source but some are definitely \LUAMETATEX\ specific.
77
78\starttyping[option=LUA]
79function status.getconstants ( )
80 return <t:table>
81end
82\stoptyping
83
84The returned table contains:
85
86\startluacode
87 context.starttabulate { "|T|Tr|" }
88 context.FL()
89 context.BC() context("constants.*")
90 context.BC()
91 context.NC() context.NR()
92 context.TL()
93 for k, v in table.sortedhash(status.getconstants()) do
94 if type(v) ~= "table" then
95 context.NC() context(k)
96 context.NC() context(tostring(v))
97 context.NC() context.NR()
98 end
99 end
100 context.LL()
101 context.stoptabulate()
102\stopluacode
103
104Most variables speak for themselves, some are more obscure. For instance the
105\type {runstate} variable indicates what the engine is doing:
106
107\getbuffer[engine:syntax:runstates]
108
109These overviews can get asked for, for instance with \type {getrunstatevalues} in
110the \type {tex} library. Most of these constants are stable but especially for
111those that relate to evolving engine functionality there can be changes, so keep
112an eye on these mappings!
113
114The individual states can be fetched with the following helpers:
115
116\starttyping[option=LUA]
117function status.getbufferstate ( ) return <t:table> end
118function status.getcallbackstate ( ) return <t:table> end
119function status.geterrorlinestate ( ) return <t:table> end
120function status.geterrorstate ( ) return <t:table> end
121function status.getexpandstate ( ) return <t:table> end
122function status.getextrastate ( ) return <t:table> end
123function status.getfilestate ( ) return <t:table> end
124function status.getfontstate ( ) return <t:table> end
125function status.gethalferrorlinestate ( ) return <t:table> end
126function status.gethashstate ( ) return <t:table> end
127function status.gethyphenationstate ( ) return <t:table> end
128function status.getinputstate ( ) return <t:table> end
129function status.getinsertstate ( ) return <t:table> end
130function status.getlanguagestate ( ) return <t:table> end
131function status.getlinebreakstate ( ) return <t:table> end
132function status.getlookupstate ( ) return <t:table> end
133function status.getluastate ( ) return <t:table> end
134function status.getmarkstate ( ) return <t:table> end
135function status.getneststate ( ) return <t:table> end
136function status.getnodestate ( ) return <t:table> end
137function status.getparameterstate ( ) return <t:table> end
138function status.getpoolstate ( ) return <t:table> end
139function status.getreadstate ( ) return <t:table> end
140function status.getsavestate ( ) return <t:table> end
141function status.getsparsestate ( ) return <t:table> end
142function status.getstringstate ( ) return <t:table> end
143function status.gettexstate ( ) return <t:table> end
144function status.gettokenstate ( ) return <t:table> end
145function status.getwarningstate ( ) return <t:table> end
146\stoptyping
147
148The error and warning messages can be wiped with:
149
150\starttyping[option=LUA]
151function status.resetmessages ( )
152 no return values
153end
154\stoptyping
155
156\stopsection
157
158\startsection[title={Everything \TEX}]
159
160\startsubsection[title={Introduction}]
161
162The \type {tex} library contains a large list of (possibly virtual) internal
163\TEX\ parameters that are partially writable. The designation \quote {virtual}
164means that these items are not properly defined in \LUA, but are only frontends
165that are handled by a metatable that operates on the actual \TEX\ values. As a
166result, most of the \LUA\ table operators (like \type {pairs} and \type {#}) do
167not work on such items. In addition to this kind of access we have getters and
168setters, which are the preferred way, but e keep the field like accessors around
169for compatibility reasons.
170
171At the moment, it is possible to access almost every parameter that you can use
172after \type {\the}, is a single token or is sort of special in \TEX. This
173excludes parameters that need extra arguments, like \typ {\the \scriptfont}. The
174subset comprising simple integer and dimension registers are writable as well as
175readable (like \type {\tracingcommands} and \type {\parindent}).
176
177\stopsubsection
178
179\startsubsection[title=Registers]
180
181Among of the oldest accessors to internals are \type {tex.dimen} and \type
182{tex.count}. This permits calls like this:
183
184\startbuffer
185\setbox0\hbox{test}
186\directlua{tex.sprint(tex.box[0].width)}
187\stopbuffer
188
189\typebuffer
190
191to give us (in this case typeset): \inlinebuffer\ scaled points. Here we access a
192box register, get back a userdata node, and access one of its fields. The skip
193registers also are stored on userdata. The register are accessed in the following
194way; watch the different value types that you get:
195
196\starttyping[option=LUA]
197<t:integer> value = tex.attribute [index]
198<t:node> value = tex.skip [index]
199<t:integer> value = tex.glue [index]
200<t:node> value = tex.muskip [index]
201<t:integer> value = tex.muglue [index]
202<t:integer> value = tex.dimen [index]
203<t:integer> value = tex.count [index]
204<t:number> value = tex.posit [index]
205<t:string> value = tex.toks [index]
206<t:node> value = tex.box [index]
207\stoptyping
208
209You can also assign values:
210
211\starttyping[option=LUA]
212tex.attribute [index] = value <t:integer>
213tex.skip [index] = value <t:node>
214tex.glue [index] = value <t:integer>
215tex.muskip [index] = value <t:node>
216tex.muglue [index] = value <t:integer>
217tex.dimen [index] = value <t:integer>
218tex.count [index] = value <t:integer>
219tex.posit [index] = value <t:number>
220tex.toks [index] = value <t:string>
221tex.box [index] = value <t:node>
222\stoptyping
223
224Be warned that an assignment like
225
226\starttyping[option=LUA]
227tex.box[0] = tex.box[2]
228\stoptyping
229
230does not copy the node list, it just duplicates a node pointer. If \type {\box2}
231will be cleared by \TEX\ commands later on, the contents of \type {\box0} becomes
232invalid as well. To prevent this from happening, always use \type {node.copylist}
233unless you are assigning to a temporary variable:
234
235\starttyping
236tex.box[0] = node.copylist(tex.box[2])
237\stoptyping
238
239When you access a \TEX\ parameter a look up takes place. For readonly variables
240that means that you will get something back, but when you set them you create a
241new entry in the table thereby making the original invisible.
242
243Although these are actually not stored in arrays but in hashes, the various
244\quote {codes} can also be accessed this way:
245
246\starttyping[option=LUA]
247<t:integer> value = tex.sfcode = [index]
248<t:integer> value = tex.lccode = [index]
249<t:integer> value = tex.uccode = [index]
250<t:integer> value = tex.hccode = [index]
251<t:integer> value = tex.hmcode = [index]
252<t:integer> value = tex.amcode = [index]
253<t:integer> value = tex.cccode = [index]
254<t:integer> value = tex.catcode = [index]
255<t:integer> value = tex.mathcode = [index]
256<t:integer> value = tex.delcode = [index]
257\stoptyping
258
259and
260
261\starttyping[option=LUA]
262tex.sfcode = [index] = value <t:integer>
263tex.lccode = [index] = value <t:integer>
264tex.uccode = [index] = value <t:integer>
265tex.hccode = [index] = value <t:integer>
266tex.hmcode = [index] = value <t:integer>
267tex.amcode = [index] = value <t:integer>
268tex.cccode = [index] = value <t:integer>
269tex.catcode = [index] = value <t:integer>
270tex.mathcode = [index] = value <t:integer>
271tex.delcode = [index] = value <t:integer>
272\stoptyping
273
274The getters are
275
276\starttyping[option=LUA]
277function tex.getamcode ( <t:integer> character ) return <t:integer> end
278function tex.getcatcode ( <t:integer> character ) return <t:integer> end
279function tex.getcccode ( <t:integer> character ) return <t:integer> end
280function tex.gethccode ( <t:integer> character ) return <t:integer> end
281function tex.gethmcode ( <t:integer> character ) return <t:integer> end
282function tex.getlccode ( <t:integer> character ) return <t:integer> end
283function tex.getsfcode ( <t:integer> character ) return <t:integer> end
284function tex.getuccode ( <t:integer> character ) return <t:integer> end
285\stoptyping
286
287and the setters:
288
289\starttyping[option=LUA]
290function tex.setamcode ( <t:integer> character, <t:integer> value ) end
291function tex.setcatcode ( <t:integer> character, <t:integer> value ) end
292function tex.setcccode ( <t:integer> character, <t:integer> value ) end
293function tex.sethccode ( <t:integer> character, <t:integer> value ) end
294function tex.sethmcode ( <t:integer> character, <t:integer> value ) end
295function tex.setlccode ( <t:integer> character, <t:integer> value ) end
296function tex.setsfcode ( <t:integer> character, <t:integer> value ) end
297function tex.setuccode ( <t:integer> character, <t:integer> value ) end
298\stoptyping
299
300The \type {setlccode} and \type {setuccode} additionally allow you to set the
301associated sibling at the same time by passing an extra argument.
302
303\starttyping[option=LUA]
304function tex.setlccode ( <t:integer> character, <t:integer> lcvalue, <t:integer> ucvalue ) end
305function tex.setuccode ( <t:integer> character, <t:integer> ucvalue, <t:integer> lcvalue ) end
306\stoptyping
307
308The function call interface for \type {setcatcode} also allows you to specify a
309category table to use on assignment or on query (default in both cases is the
310current one):
311
312\starttyping[option=LUA]
313function tex.setcatcode (
314 <t:integer> catcodetable,
315 <t:integer> character,
316 <t:integer> value
317)
318 no return values
319end
320\stoptyping
321
322All these setters accept an initial \type{global} string.
323
324\stopsubsection
325
326\startsubsection[title={Setters and getters}]
327
328Most of \TEXs parameters can be accessed directly by using their names as index
329in the \type {tex} table, or by using one of the functions \type {tex.get} and
330\type {tex.set}. The exact parameters and return values differ depending on the
331actual parameter. In most cases we have integers but especially glue have more
332properties than just the amount. For the parameters that {\em can} be set, it is
333possible to use \type {global} as the first argument to \type {tex.set}. Them
334being more complete is an argument for using setters instead of assignments.
335
336The \type {set} function is meant for what we call internal parameter. These can
337be registers but without a known number (one can actually figure out the internal
338number via the token library).
339
340\starttyping[option=LUA]
341function tex.set ( <t:string> name, <t:whatever> value )
342 no return values
343end
344
345function tex.set ( "global", <t:string> name, <t:whatever> value )
346 no return values
347end
348\stoptyping
349
350You can get back a value with:
351
352\starttyping[option=LUA]
353function tex.get ( <t:string> name )
354 return <t:whatever>
355end
356\stoptyping
357
358Glue is kind of special because there are five values involved. The return value
359is a \type {gluespec} node but when you pass \type {false} as last argument to
360\type {tex.get} you get the width of the glue and when you pass \type {true} you
361get all five values. Otherwise you get a node which is a copy of the internal
362value so you are responsible for its freeing at the \LUA\ end. When you set a
363glue quantity you can either pass a \type {gluespec} or upto five numbers.
364
365Traditional \TEX\ has 256 registers per type, \ETEX\ bumps that to 32K and
366\LUAMETATEX\ doubles that. But how many are enough? Do we really need that many
367different attributes and glue specifiers?
368
369In \LUAMETATEX\ on the one hand can go lower on registers and at the same time
370go beyond with alternatives when using named quantities.
371
372It is possible to define named registers with t\type {\attributedef}, \type
373{\countdef}, \type {\dimendef}, \type {\skipdef}, \type {\floatdef} or \type
374{\toksdef} control sequences as indices to these tables and these can be accessed
375by name at the \LUA\ end. Here are some examples:
376
377\starttyping
378tex.count.scratchcounter = 123
379tex.dimen.scratchdimen = "20pt"
380
381tex.setcount( "scratchcounter", 123)
382tex.setdimen( "scratchdimen", 10 *65536)
383tex.setdimen("global", "scratchdimen", "10pt")
384
385enormous = tex.dimen.maxdimen
386enormous = tex.getdimen("maxdimen")
387
388unknown = tex.dimen[3]
389unknown = tex.getdimen(3)
390\stoptyping
391
392Of course this assumes that these registers are defined. What you can do depends
393on the type:
394
395\startitemize
396
397 \startitem
398 The count registers accept and return \LUA\ numbers (integers in this case).
399 \stopitem
400
401 \startitem
402 The dimension registers accept \LUA\ numbers (in scaled points) or
403 strings with a dimension.
404 \stopitem
405
406 \startitem
407 The token registers accept and return \LUA\ strings. \LUA\ strings are
408 converted to and from token lists using \type {\the \toks} style
409 expansion: all category codes are either space (10) or other (12).
410 \stopitem
411
412 \startitem
413 The skip registers accept and return \type {gluespec} userdata node
414 objects (see the description of the node interface elsewhere in this
415 manual).
416 \stopitem
417
418 \startitem
419 The glue registers are just skip registers but instead of userdata
420 accept verbose (integers).
421 \stopitem
422
423 \startitem
424 Like the counts, the attribute registers accept and return integers.
425 \stopitem
426
427 \startitem
428 Float (aka posit) registers accept and return floating point numbers.
429 \stopitem
430
431\stopitemize
432
433The \type {setglue} function accepts upto five arguments:
434
435\starttyping[option=LUA]
436function tex.setskip (
437 <t:string> register, can also be an index
438 <t:node> value gluespec
439)
440 no return values
441end
442
443function tex.setglue (
444 <t:string> register, can also be an index
445 <t:integer> amount,
446 <t:integer> stretch,
447 <t:integer> shrink,
448 <t:integer> stretchorder,
449 <t:integer> shrinkorder
450)
451 no return values
452end
453\stoptyping
454
455Actually there can be one more argument here because as first argument we can
456pass \type {"global"}. The whole repertoire is:
457
458\starttyping[option=LUA]
459function tex.getattribute ( <t:string> name ) return <t:integer> end
460function tex.getcount ( <t:string> name ) return <t:integer> end
461function tex.getdimen ( <t:string> name ) return <t:integer> end
462function tex.getfloat ( <t:string> name ) return <t:number> end
463function tex.getskip ( <t:string> name ) return <t:node> end
464function tex.getmuskip ( <t:string> name ) return <t:node> end
465function tex.gettoks ( <t:string> name ) return <t:string> end
466
467function tex.getglue ( <t:string> name ) return <t:integer>, ... end
468function tex.getmuglue ( <t:string> name ) return <t:integer>, ... end
469function tex.getglue ( <t:string> name, false ) return <t:integer> end
470function tex.getmuglue ( <t:string> name, false ) return <t:integer> end
471\stoptyping
472
473and
474
475\starttyping[option=LUA]
476function tex.setattribute (<t:string> name, <t:integer> value) end
477function tex.setcount (<t:string> name, <t:integer> value) end
478function tex.setdimen (<t:string> name, <t:integer> value) end
479function tex.setfloat (<t:string> name, <t:number> value) end
480function tex.setmuskip (<t:string> name, <t:node> value) end
481function tex.setskip (<t:string> name, <t:node> value) end
482function tex.settoks (<t:string> name, <t:string> value) end
483
484function tex.setglue (<t:string> name, <t:integer> value, ...) end
485function tex.setmuglue (<t:string> name, <t:integer> value, ...) end
486\stoptyping
487
488Just to be clear, getting a glue has two variants, the third one is just a reduced variant:
489
490\starttyping[option=LUA]
491function tex.getskip (
492 <t:string> register can also be an index
493)
494 return <t:node> a gluespec
495end
496
497function tex.getglue (
498 <t:string> register can also be an index
499)
500 return
501 <t:integer> amount,
502 <t:integer> stretch,
503 <t:integer> shrink,
504 <t:integer> stretchorder,
505 <t:integer> shrinkorder
506end
507
508function tex.getglue (
509 <t:string> register, can also be an index
510 false
511)
512 return <t:integer> amount,
513end
514\stoptyping
515
516When \type {tex.gettoks} gets an extra argument \type {true} it will return a
517table with userdata tokens. For tokens registers we have an alternative where a
518catcode table is specified:
519
520\starttyping[option=LUA]
521function tex.scantoks (
522 <t:integer> catcodetable,
523 <t:integer> registerindex, or just a name
524 <t:string> data
525)
526 no return values
527end
528\stoptyping
529
530Again there is the option to pass \type {"global"} as first argument. Here is an
531example that used the default \CONTEXT\ catcode table index \typ
532{tex.ctxcatcodes}.
533
534\starttyping[option=LUA]
535local t = tex.scantoks("global",tex.ctxcatcodes,3,"$e=mc2$")
536\stoptyping
537
538This is a bit different getter that was introduced to accommodate interfacing
539between \TEX\ and \METAPOST. We specify what kind of parsing takes place:
540
541\starttyping[option=LUA]
542function tex.expandasvalue (
543 <t:integer> kind, how interpreted
544 <t:string> name macro name
545)
546 return <t:integer> <t:boolean> <t:string>
547end
548\stoptyping
549
550\startfourrows
551\getbuffer[engine:syntax:functioncodes]
552\stopfourrows
553
554\stopsubsection
555
556\startsubsection[title=Fonts]
557
558There are a few functions that deal with fonts. The next function relates a
559control sequence to a font identifier. This is not to be confused with
560registering font data in the engine which happens with the functions in the \type
561{font} library. This is basically a setter that as one some in the \type {token}
562library also accepts prefixes (like \type {global}):
563
564\starttyping[option=LUA]
565function tex.definefont (
566 <t:string> name,
567 <t:integer> fontid,
568 <t:string> prefix
569 there can be more prefixes
570)
571 no return values
572end
573\stoptyping
574
575In \LUATEX\ and other engines the file names are stored in the table of
576equivalents but not so in \LUAMETATEX. But for old times sake we keep some
577getters in the \type {tex} library, as they are basically \quote {convert}
578commands. The next two are like \type {\fontid} and \type {\fontname}:
579
580\starttyping[option=LUA]
581function tex.fontidentifier ( <t:integer> id ) return <t:integer> end
582function tex.fontname ( <t:integer> id ) return <t:string> end
583\stoptyping
584
585When no \type {id} is given the current font is assumed, as if \type {\font} was
586the argument to the mentioned equivalent macros, so here we have: {\tttf
587\cldcontext {tex.fontidentifier ()}} and {\tttf \cldcontext {tex.fontname ()}}.
588
589We can query the font id bound to a family (and optionally style):
590
591\starttyping[option=LUA]
592function tex.getfontoffamily (
593 <t:integer> family,
594 <t:integer> style 0, 1, 2
595)
596 return <t:integer> id
597end
598\stoptyping
599
600This is a good place to mention a pitfall when it comes to accessing some
601internals. Many variables are just that, variables, but there are also some that
602need an argument. This means that we get the following:
603
604\starttabulate[lTlT]
605\FL
606\BC \LUA\ call \BC result (if any) \NC \NR
607\TL
608\NC tex.fontname \NC \cldcontext {tex.fontname } \NC \NR
609\NC tex.fontidentifier \NC \cldcontext {tex.fontidentifier } \NC \NR
610\NC tex.fontname() \NC \cldcontext {tex.fontname ()} \NC \NR
611\NC tex.fontidentifier() \NC \cldcontext {tex.fontidentifier ()} \NC \NR
612\NC tex.get("fontname",1) \NC \cldcontext {tex.get("fontname",-1)} \NC \NR
613\NC tex.get("fontidentifier",1) \NC \cldcontext {tex.get("fontidentifier",-1)} \NC \NR
614\LL
615\stoptabulate
616
617When called as \quote {field} we get nothing. When called as a function we get
618the font info of the id passes as argument. When no argument is given the current
619font is used. When we use a getter the id is mandate but a negative value will
620again make that the current font is used. Making the first two use the current
621font and the last two accept no second argument is technically possible but
622complicating the code for these few cases makes no sense. We already handle more
623than in \LUATEX\ anyway.
624
625\stopsubsection
626
627\startsubsection[title={Box registers}]
628
629It is possible to set and query actual boxes, coming for instance from \prm
630{hbox}, \prm {vbox} or \prm {vtop}, using the node interface as defined in the
631\type {node} library. In the setters you can pass as first argument \type
632{global} if needed. Alternatively you can use the \type {tex.box} array
633interface.
634
635\starttyping[option=LUA]
636function tex.setbox (
637 <t:integer> index,
638 <t:node> packedlist
639)
640 no return values
641end
642
643function tex.setbox (
644 <t:string> name,
645 <t:node> packedlist
646)
647 no return values
648end
649\stoptyping
650
651The getters return a packed list or \type {nil} when the register is void.
652
653\starttyping[option=LUA]
654function tex.getbox (
655 <t:integer> index
656)
657 return <t:node>
658end
659
660function tex.getbox (
661 <t:string> name
662)
663 return <t:node>
664end
665\stoptyping
666
667You can split a box:
668
669\starttyping[option=LUA]
670local vlist =
671function tex.splitbox (
672 <t:integer> index,
673 <t:integer> height,
674 <t:integer> mode
675)
676\stoptyping
677
678The remainder is kept in the original box and a packaged vlist is returned. This
679operation is comparable to the \type {\vsplit} operation. The mode can be \type
680{additional} or \type {exactly} and concerns the split off box.
681
682\stopsubsection
683
684\startsubsection[title=Marks]
685
686There is a dedicated getter for marks:
687
688\starttyping[option=LUA]
689function tex.getmark (
690 <t:string> name,
691 <t:integer> markindex
692)
693 no return values
694end
695
696function tex.getmark ( )
697 return <t:integer> max mark class
698end
699\stoptyping
700
701The first argument can also be an integer, actually the subtype of a mark node:
702
703\starttworows
704\getbuffer[engine:syntax:marknames]
705\stoptworows
706
707The largest used mark class is returned by:
708
709\starttyping[option=LUA]
710function tex.getlargestusedmark ( )
711 return <t:integer> max mark class
712end
713\stoptyping
714
715\stopsubsection
716
717\startsubsection[title=Inserts]
718
719Access to inserts is kind of special and often only makes sense when we are
720constructing the final page. Where in traditional \TEX\ inserts use a \type
721{\dimen}, \type {\count}, \type {\skip} and \type {\box}, registers, in
722\LUAMETATEX\ we can use dedicted storage instead. This is why we need setters and
723getters.
724
725\starttyping[option=LUA]
726function tex.getinsertdistance ( <t:integer> class ) return <t:integer> end
727function tex.getinsertmultiplier ( <t:integer> class ) return <t:integer> end
728function tex.getinsertlimit ( <t:integer> class ) return <t:integer> end
729function tex.getinsertcontent ( <t:integer> class ) return <t:node> end
730function tex.getinsertheight ( <t:integer> class ) return <t:integer> end
731function tex.getinsertdepth ( <t:integer> class ) return <t:integer> end
732function tex.getinsertwidth ( <t:integer> class ) return <t:integer> end
733\stoptyping
734
735Only some properties can be set:
736
737\starttyping[option=LUA]
738function tex.setinsertdistance ( <t:integer> class, <t:integer> distance ) end
739function tex.setinsertmultiplier ( <t:integer> class, <t:integer> multiplier ) end
740function tex.setinsertlimit ( <t:integer> class, <t:integer> limit ) end
741function tex.setinsertcontent ( <t:integer> class, <t:node> list ) end
742\stoptyping
743
744\stopsubsection
745
746\startsubsection[title=Local boxes]
747
748Local boxes, \typ {\localleftbox}, \typ {\localrightbox} and specific for
749\LUAMETATEX, \typ {\localmiddlebox}, are not regular box registers so they have
750dedicated accessors:
751
752\starttyping[option=LUA]
753function tex.getlocalbox ( <t:integer> location )
754 return <t:node>
755end
756
757function tex.setlocalbox ( <t:integer> location, <t:node> list )
758 no return values
759end
760\stoptyping
761
762Instead of integers you can also use the name. Valid local box locations are:
763
764\getbuffer[engine:syntax:localboxlocations]
765
766\stopsubsection
767
768\startsubsection[title=Constants]
769
770The name of this section is a bit misleading but reflects history. At some point
771\LUAMETATEX\ got a way to store values differently than in registers because it
772felt a bit weird to use registers for what actually are constant values. However,
773it was not that hard to make them behave like registers which opens up the
774possibility to reduce the number of registers at some point.
775
776At the \TEX\ end we have \type {\integerdef}, \type {\dimensiondef}, \type
777{\floatdef}, \type {\gluespecdef} and \type {\mugluespecdef} but at the \LUA\ end
778we (currently) only handle the first three.
779
780\starttyping[option=LUA]
781function tex.dimensiondef ( <t:string> name ) end
782function tex.integerdef ( <t:string> name ) end
783function tex.positdef ( <t:string> name ) end
784\stoptyping
785
786These are the setters:
787
788\starttyping[option=LUA]
789function tex.setdimensionvalue ( <t:string> name, <t:integer> value ) end
790function tex.setintegervalue ( <t:string> name, <t:integer> value ) end
791function tex.setcardinalvalue ( <t:string> name, <t:integer> value ) end
792function tex.setpositvalue ( <t:string> name, <t:number> value ) end
793\stoptyping
794
795and these the getters:
796
797\starttyping[option=LUA]
798function tex.getdimensionvalue ( <t:string> name ) return <t:integer> end
799function tex.getintegervalue ( <t:string> name ) return <t:integer> end
800function tex.getcardinalvalue ( <t:string> name ) return <t:integer> end
801function tex.getpositvalue ( <t:string> name ) return <t:number> end
802\stoptyping
803
804Now, in order to make access more convenient, the getters and setters that deal
805with these quantities that we discussed in a previous section also handle these
806\quote {constants}.
807
808The following helper is a bit tricky:
809
810\starttyping[option=LUA]
811function tex.getregisterindex ( <t:string> name )
812 return <t:integer>
813end
814\stoptyping
815
816The integer that is returned can be used instead of a name when accessing a register,
817
818\startbuffer
819\newcount \MyCount \newinteger \MyInteger
820\newdimen \MyDimen \newdimension \MyDimension
821
822\startluacode
823 context("[%s] [%s] [%s] [%s]",
824 tex.getregisterindex("MyCount"),
825 tex.getregisterindex("MyInteger"),
826 tex.getregisterindex("MyDimen"),
827 tex.getregisterindex("MyDimension")
828 )
829\stopluacode
830\stopbuffer
831
832\typebuffer[option=LUA]
833
834This will only show something for the registers:
835
836\getbuffer
837
838This is why we have a more complete completed solution:
839
840\starttyping[option=LUA]
841tex.isattribute ( <t:string> name ) return <t:integer> end
842tex.iscount ( <t:string> name ) return <t:integer> end
843tex.isdimen ( <t:string> name ) return <t:integer> end
844tex.isfloat ( <t:string> name ) return <t:integer> end
845tex.isglue ( <t:string> name ) return <t:integer> end
846tex.ismuglue ( <t:string> name ) return <t:integer> end
847tex.ismuskip ( <t:string> name ) return <t:integer> end
848tex.isskip ( <t:string> name ) return <t:integer> end
849tex.istoks ( <t:string> name ) return <t:integer> end
850tex.isbox ( <t:string> name ) return <t:integer> end
851\stoptyping
852
853We now use this:
854
855\startbuffer
856\startluacode
857 context("[%s] [%s] [%s] [%s]",
858 tex.iscount("MyCount"),
859 tex.iscount("MyInteger"),
860 tex.isdimen("MyDimen"),
861 tex.isdimen("MyDimension")
862 )
863\stopluacode
864\stopbuffer
865
866\typebuffer[option=LUA]
867
868This time all four names are resolved:
869
870\getbuffer
871
872The larger numbers are references to these \quote {constants}. Using these
873instead of names in the getters (like \type {getcount} and \type {getdimen} can
874be more efficient when the number times we need access is very large because we
875bypass a hash lookup. Of course these numbers are to be seen as abstract
876references, so these larger numbers are unpredictable.
877
878\stopsubsection
879
880\startsubsection[title=Nesting]
881
882The virtual table \type {nest} contains the currently active semantic nesting
883state (think building boxes). It has two main parts: a zerobased array of
884userdata for the semantic nest itself, and the numerical value \type {ptr}, which
885gives the highest available index. Neither the array items in \type {nest[]} nor
886\type {ptr} can be assigned to, because this would confuse the typesetting engine
887beyond repair, but you can assign to the individual values inside the array
888items.
889
890The zero entry \type {nest[0]} is the outermost (main vertical list) level while
891\typ {tex.nest [tex.nest.ptr]} is the current nest state. The next example shows
892all of this:
893
894\startbuffer
895\setbox\scratchbox\vbox\bgroup
896 \vbox\bgroup
897 \startluacode
898 for i=0,tex.nest.ptr do
899 context(tostring(tex.nest[i]))
900 context.space()
901 context(tostring(tex.nest[i].prevdepth))
902 context.par()
903 end
904 \stopluacode
905 \egroup
906\egroup
907\stopbuffer
908
909\typebuffer
910
911\start \forgetall \getbuffer
912\startlinecorrection
913 \box\scratchbox
914\stoplinecorrection
915\stop
916
917The current nest level (\type {tex.nest.ptr} is also available with:
918
919\starttyping[option=LUA]
920function tex.getnestlevel ( )
921 return <t:integer>
922end
923\stoptyping
924
925The getter function is \type {tex.getnest}. You can pass a number (which gives
926you a list), nothing or \type {top}, which returns the topmost list, or the
927string \type {ptr} which gives you the index of the topmost list. The complete list
928of fields is: \showenginekeylist {tex.getnestfields()}.
929
930Possible modes are:
931
932\starttworows
933\getbuffer[engine:syntax:modes]
934\stoptworows
935
936Valid directions are:
937
938\starttworows
939\getbuffer[engine:syntax:directioncodes]
940\stoptworows
941
942Math styles conforms to:
943
944\starttworows
945\getbuffer[engine:syntax:mathstyles]
946\stoptworows
947
948The math begin and end classes can be builtin or \CONTEXT\ specific:
949
950\startfourrows
951\getbuffer[engine:syntax:mathclasses]
952\stopfourrows
953
954The helpers are:
955
956\starttyping[option=LUA]
957function tex.getnest ( <t:integer> level )
958 return <t:userdata> nest
959end
960
961function tex.getnest ( <t:integer> level, <t:string> name )
962 return <t:whatever> value
963end
964
965function tex.setnest ( <t:integer> level, <t:string> name ), <t:whatever> value )
966 no return values
967end
968\stoptyping
969
970Instead of an integer level you can use the keywords \type {ptr} and \type {top}
971instead of the current level or zero.
972
973There are a few special cases that we make an exception for: \type {prevdepth},
974\type {prevgraf} and \type {spacefactor}. These normally are accessed via the
975\type {tex.nest} table:
976
977\starttyping
978tex.nest[tex.nest.ptr].prevdepth = <t:integer> value
979tex.nest[tex.nest.ptr].spacefactor = <t:integer> value
980\stoptyping
981
982However, the following also works for the current level:
983
984\starttyping
985tex.prevdepth = <t:integer> value
986tex.spacefactor = <t:integer> value
987\stoptyping
988
989Keep in mind that when you mess with node lists directly at the \LUA\ end you
990might need to update the top of the nesting stacks \type {\prevdepth} explicitly
991as there is no way \LUATEX\ can guess your intentions. By using the accessor in
992the \type {tex} tables, you get and set the values at the top of the nesting
993stack.
994
995\stopsubsection
996
997\startsubsection[title={Directions}]
998
999In \LUAMETATEX\ we only have lefttoright (l2r) and righttoleft (r2l)
1000directions, contrary to \LUATEX\ that has few more. In the end those made no
1001sense because the typesetter is not geared for that and demands can be met by a
1002combination of \TEX\ macros and \LUA\ code.
1003
1004There are two sets of helpers:
1005
1006\starttyping[option=LUA]
1007function tex.gettextdir ( ) return <t:integer end
1008function tex.getlinedir ( ) return <t:integer end
1009function tex.getmathdir ( ) return <t:integer end
1010function tex.getpardir ( ) return <t:integer end
1011function tex.getboxdir ( ) return <t:integer end
1012\stoptyping
1013
1014and:
1015
1016\starttyping[option=LUA]
1017function tex.settextdir ( <t:integer> direction ) end no return values
1018function tex.setlinedir ( <t:integer> direction ) end no return values
1019function tex.setmathdir ( <t:integer> direction ) end no return values
1020function tex.setpardir ( <t:integer> direction ) end no return values
1021function tex.setboxdir ( <t:integer> direction ) end no return values
1022\stoptyping
1023
1024For old times sake you can also set them using the virtual interfaces, like
1025
1026\starttyping[option=LUA]
1027tex.textdirection = 1
1028\stoptyping
1029
1030but in \CONTEXT\ we consider this obsolete. In \LUAMETATEX\ we dropped the
1031direction related keywords and only use numbers:
1032
1033\getbuffer[engine:syntax:directioncodes]
1034
1035\stopsubsection
1036
1037\startsubsection[title={Special lists}]
1038
1039The virtual table \type {tex.lists} contains the set of internal registers that
1040keep track of building page lists. We have the following lists plus some extras:
1041\showenginekeylist {tex.getlistfields()}. Using these assumes that you know what
1042\TEX\ is doing.
1043
1044The getter and setter functions are \type {getlist} and \type {setlist}. You have
1045to be careful with what you set as \TEX\ can have expectations with regards to
1046how a list is constructed or in what state it is.
1047
1048\starttyping[option=LUA]
1049function tex.getlist ( <t:string> name )
1050 return <t:whatever> value
1051end
1052
1053function tex.setlist ( <t:string> name ), <t:whatever> value )
1054 no return values
1055end
1056\stoptyping
1057
1058You can mess up I ways that make the engine fail, for instance due to wrongly
1059linked lists, for instance maybe circular, or invalid nodes.
1060
1061\stopsubsection
1062
1063\startsubsection[title=Printing]
1064
1065The engine reads tokens from file, token lists and \LUA. When we print from \LUA\
1066it ends up in a special data structure that efficiently handle strings, tokens
1067and nodes because we can push all three back to \TEX. It is important to notice
1068that when we have a call to \LUA, that new input is collected and only pushed
1069onto the input stack when we are done. The total amount of returnable text from a
1070\type {\directlua} command or primitive driven function call is only limited by
1071available system \RAM. However, each separate printed string has to fit
1072completely in \TEXs input buffer. The result of using these functions from
1073inside callbacks is undefined at the moment. First we look at \type {tex.print}
1074and \type {tex.sprint}.
1075
1076\starttyping[option=LUA]
1077function tex.print ( also tex.sprint
1078 <t:string> data,
1079 more strings
1080)
1081 nothing to return
1082end
1083
1084function tex.print ( also tex.sprint
1085 <t:integer> catcodetable,
1086 <t:string> data,
1087 more strings
1088)
1089 nothing to return
1090end
1091
1092function tex.print ( also tex.sprint
1093 <t:table> data
1094)
1095 nothing to return
1096end
1097
1098function tex.print ( also tex.sprint
1099 <t:integer> catcodetable,
1100 <t:table> data
1101)
1102 nothing to return
1103end
1104\stoptyping
1105
1106With \type {tex.print} each string argument is treated by \TEX\ as a separate
1107input line. If there is a table argument instead of a list of strings, this has
1108to be a consecutive array of strings to print (the first nonstring value will
1109stop the printing process). The optional first integer parameter can be used to
1110print the strings using the catcode regime defined by \type {\catcodetable}. A
1111value of $1$ means that the currently active catcode regime is used while $2$
1112gives a result similar to \type {\the\toks}: all category codes are 12 (other)
1113except for the space character, that has category code 10 (space). An invalid
1114catcode table index is silently ignored, and the currently active catcode regime
1115is used instead. The very last string of the very last \type {tex.print} command
1116in a \type {\directlua} call will not have the \type {\endlinechar} appended, all
1117others do.
1118
1119In the case if \type {tex.sprint} each string argument is treated by \TEX\ as a
1120special kind of input line that makes it suitable for use as a partial line input
1121mechanism:
1122
1123\startitemize[packed]
1124\startitem
1125 \TEX\ does not switch to the \quote {new line} state, so that leading spaces
1126 are not ignored.
1127\stopitem
1128\startitem
1129 No \type {\endlinechar} is inserted.
1130\stopitem
1131\startitem
1132 Trailing spaces are not removed. Note that this does not prevent \TEX\ itself
1133 from eating spaces as result of interpreting the line. For example, in
1134
1135 \starttyping
1136 before\directlua{tex.sprint("\\relax")tex.sprint(" in between")}after
1137 \stoptyping
1138
1139 the space before \type {in between} will be gobbled as a result of the \quote
1140 {normal} scanning of \prm {relax}.
1141\stopitem
1142\stopitemize
1143
1144Although this needs to be used with care, in both function you can also pass
1145token or node userdata objects. These get injected into the stream. Tokens had
1146best be valid tokens, while nodes need to be around when they get injected.
1147Therefore it is important to realize the following:
1148
1149\startitemize
1150\startitem
1151 When you inject a token, you need to pass a valid token userdata object. This
1152 object will be collected by \LUA\ when it no longer is referenced. When it gets
1153 printed to \TEX\ the token itself gets copied so there is no interference with the
1154 \LUA\ garbage collection. You manage the object yourself. Because tokens are
1155 actually just numbers, there is no real extra overhead at the \TEX\ end.
1156\stopitem
1157\startitem
1158 When you inject a node, you need to pass a valid node userdata object. The
1159 node related to the object will not be collected by \LUA\ when it no longer
1160 is referenced. It lives on at the \TEX\ end in its own memory space. When it
1161 gets printed to \TEX\ the node reference is used assuming that node stays
1162 around. There is no \LUA\ garbage collection involved. Again, you manage the
1163 object yourself. The node itself is freed when \TEX\ is done with it.
1164\stopitem
1165\stopitemize
1166
1167If you consider the last remark you might realize that we have a problem when a
1168printed mix of strings, tokens and nodes is reused. Inside \TEX\ the sequence
1169becomes a linked list of input buffers. So, \type {"123"} or \type {"\foo{123}"}
1170gets read and parsed on the fly, while \typ {<t:token>} already is
1171tokenized and effectively is a token list now. A \typ {<t:node>} is also
1172tokenized into a token list but it has a reference to a real node. Normally this
1173goes fine. But now assume that you store the whole lot in a macro: in that case
1174the tokenized node can be flushed many times. But, after the first such flush the
1175node is used and its memory freed. You can prevent this by using copies which is
1176controlled by setting \type {\luacopyinputnodes} to a nonzero value. This is one
1177of these fuzzy areas you have to live with if you really mess with these low
1178level issues.
1179
1180The \type {tex.cprint} function is similar to \type {tex,sprint} but instead of
1181am optional first catcodetable it takes a catcode value, like:
1182
1183\starttyping[option=LUA]
1184function tex.cprint (
1185 <t:integer> catcode,
1186 <string> data
1187 more strings
1188)
1189 no return values
1190end
1191\stoptyping
1192
1193Of course the other three ways to call it are also supported. This might explain
1194better:
1195
1196\startbuffer
1197\startluacode
1198tex.cprint( 1," 1: $&{\\foo}") tex.print("\\par")
1199tex.cprint( 2," 2: $&{\\foo}") tex.print("\\par")
1200tex.cprint( 9," 9: $&{\\foo}") tex.print("\\par")
1201tex.cprint(10,"10: $&{\\foo}") tex.print("\\par")
1202tex.cprint(11,"11: $&{\\foo}") tex.print("\\par")
1203tex.cprint(12,"12: $&{\\foo}") tex.print("\\par")
1204tex.cprint(14,"14: $&{\\foo}") tex.print("\\par")
1205\stopluacode
1206\stopbuffer
1207
1208\typebuffer
1209
1210We get two lines separate by one with only spaces:
1211
1212\getbuffer
1213
1214A variant on \type {tex.sprint} is the next one:
1215
1216\starttyping[option=LUA]
1217function tex.tprint (
1218 { <t:integer> catcodetable, <string> data},
1219 more tables
1220)
1221 no return values
1222end
1223\stoptyping
1224
1225The \type {tex.write} function is a quick way to dump information. Each string
1226argument is treated as a special kind of input line that only has spaces and
1227letters.
1228
1229\starttyping[option=LUA]
1230function tex.write ( <t:string> data, ... )
1231 no return values
1232end
1233
1234function tex.write ( <t:table> data)
1235 no return values
1236end
1237\stoptyping
1238
1239Often you can mix strings, nodes and tokens in a print but you might want to check beforehand
1240what you pass:
1241
1242\starttyping[option=LUA]
1243function tex.isprintable ( <t:whatever> object )
1244 return <t:boolean>
1245end
1246\stoptyping
1247
1248\stopsubsection
1249
1250\startsubsection [title=Numbers and dimensions]
1251
1252We can rounds a \LUA\ number to an integer that is in the range of a valid \TEX\
1253register value. If the number starts out of range, it generates a \quote {number
1254too big} error as well.
1255
1256\starttyping[option=LUA]
1257function tex.round ( <t:number> n )
1258 return <t:integer>
1259end
1260\stoptyping
1261
1262In many places the engine multiplies and divides integers and ensures proper
1263rounding. In \LUAMETATEX\ some (new) mechanisms use doubles and round, especially
1264when multiple scale value accumulate beyond the available integer range. The next
1265function multiplies two \LUA\ numbers and returns a rounded number that is in the
1266range of a valid \TEX\ register value. In the table version, it creates a copy of
1267the table with all numeric toplevel values scaled in that manner. If the
1268multiplied number(s) are of range, it generates \quote {number too big} error(s)
1269as well.
1270
1271\starttyping[option=LUA]
1272function tex.scale ( <t:number> original, <t:number> factor )
1273 return <t:integer> result
1274end
1275
1276function tex.scale ( <t:table> originals, <t:number> factor )
1277 return <t:table> results
1278end
1279\stoptyping
1280
1281Here are companions to the primitives \type {\number} and \type {\romannumeral}.
1282Both take the long route: the string goes to \TEX, gets tokenized, then converted
1283to what is wanted and finally ends up in \LUA. They can be used like:
1284
1285\starttyping[option=LUA]
1286function tex.number ( <t:integer> original ) return <t:string> end
1287function tex.romannumeral ( <t:integer> original ) return <t:string> end
1288\stoptyping
1289
1290The dimension converter takes a string and returns an integer that represents an
1291dimension in scaled points. When a number is passed it gets rounded.
1292
1293\starttyping[option=LUA]
1294function tex.toscaled ( <t:string> original ) return <t:integer> end
1295function tex.toscaled ( <t:number> original ) return <t:integer> end
1296\stoptyping
1297
1298For completeness the engine also provides \type {tex.tonumber}:
1299
1300\starttyping[option=LUA]
1301function tex.tonumber ( <t:string> original ) return <t:integer> end
1302function tex.tonumber ( <t:number> original ) return <t:integer> end
1303\stoptyping
1304
1305For parsing the string, the same scanning and conversion rules are used that
1306\LUATEX\ would use if it was scanning a dimension specifier in its \TEXlike
1307input language (this includes generating errors for bad values), expect for the
1308following:
1309
1310\startitemize[n,packed]
1311\startitem
1312 only explicit values are allowed, control sequences are not handled
1313\stopitem
1314\startitem
1315 infinite dimension units (\type {fil...}) are forbidden
1316\stopitem
1317\startitem
1318 \type {mu} units do not generate an error (but may not be useful either)
1319\stopitem
1320\stopitemize
1321
1322\stopsubsection
1323
1324\startsubsection[title={Primitives}]
1325
1326Where in \LUATEX\ we explicitly need to enable the core set of primitives,
1327\LUAMETATEX\ does that for you. The only reason that we still have a way
1328to enable them is that its a convenient way to create prefixed copies.
1329
1330\starttyping[option=LUA]
1331function tex.enableprimitives (
1332 <t:string> prefix,
1333 <t:table> names
1334)
1335 no return values
1336end
1337\stoptyping
1338
1339Only valid primitive names are processed. Because it is no fun to enter the
1340names, there is this one. It has two variants, where the boolean variant returns
1341a table with all primitives.
1342
1343\starttyping[option=LUA]
1344function tex.extraprimitives ( <t:string> subset, ... )
1345 return <t:table> names
1346end
1347
1348function tex.extraprimitives ( <t:true> )
1349 return <t:table> names
1350end
1351\stoptyping
1352
1353Possible values for \type {subset} are:
1354
1355\getbuffer[engine:syntax:primitiveorigins]
1356
1357You can feed the result of the last one in \type {tex.enableprimitives}. If
1358there is already a macro with that name if will not be overloaded.
1359
1360\starttyping[option=LUA]
1361tex.enableprimitives(normal,tex.extraprimitives(true))
1362\stoptyping
1363
1364A complete list of primitives can be requested by:
1365
1366\starttyping[option=LUA]
1367function tex.primitives ( )
1368 return <t:table> names
1369end
1370\stoptyping
1371
1372of course the fact that the name is there doesnt mean that it has the same
1373meaning.
1374
1375A complete list of all hash entries can be asked for by the following function, but
1376in \CONTEXT\ it will be a big one, a bit more that 50.000 names, many of which are
1377kind of weird because they use some namespace.
1378
1379\starttyping[option=LUA]
1380function tex.hashtokens ( )
1381 return <t:table> names
1382end
1383\stoptyping
1384
1385\stopsubsection
1386
1387\startsubsection[title=Values (constants)]
1388
1389The engine uses lots of very specific values (constants) for control. These can
1390be status values (where are we currently), options (in nodes), control parameters
1391(typesetting), etc.\ and all are available in lists that relate numbers to
1392strings. Here is the complete list. We show the results in various places in the
1393documentation. The advantage is that the engine is partly self documenting.
1394
1395\starttyping[option=LUA]
1396function tex.getadjustoptionvalues ( ) return <t:table> end
1397function tex.getalignmentcontextvalues ( ) return <t:table> end
1398function tex.getappendlinecontextvalues ( ) return <t:table> end
1399function tex.getautomigrationvalues ( ) return <t:table> end
1400function tex.getautoparagraphvalues ( ) return <t:table> end
1401function tex.getbalancestepoptionvalues ( ) return <t:table> end
1402function tex.getbalancecallbackvalues ( ) return <t:table> end
1403function tex.getboxoptionvalues ( ) return <t:table> end
1404function tex.getbreakcontextvalues ( ) return <t:table> end
1405function tex.getbuildcontextvalues ( ) return <t:table> end
1406function tex.getcharactercontrolvalues ( ) return <t:table> end
1407function tex.getcharactertagvalues ( ) return <t:table> end
1408function tex.getdirectionvalues ( ) return <t:table> end
1409function tex.getdiscoptionvalues ( ) return <t:table> end
1410function tex.getdiscpartvalues ( ) return <t:table> end
1411function tex.getdoublescriptoptionvalues ( ) return <t:table> end
1412function tex.geterrorvalues ( ) return <t:table> end
1413function tex.getfillvalues ( ) return <t:table> end
1414function tex.getflagvalues ( ) return <t:table> end
1415function tex.getfrozenparvalues ( ) return <t:table> end
1416function tex.getglueoptionvalues ( ) return <t:table> end
1417function tex.getglyphdiscvalues ( ) return <t:table> end
1418function tex.getglyphoptionvalues ( ) return <t:table> end
1419function tex.getglyphprotectionvalues ( ) return <t:table> end
1420function tex.getgroupvalues ( ) return <t:table> end
1421function tex.gethyphenationvalues ( ) return <t:table> end
1422function tex.getiftypes ( ) return <t:table> end
1423function tex.getinteractionmodes ( ) return <t:table> end
1424function tex.getiovalues ( ) return <t:table> end
1425function tex.getkernoptionvalues ( ) return <t:table> end
1426function tex.getkerneloptionvalues ( ) return <t:table> end
1427function tex.getlinebreakparameterfields ( ) return <t:table> end
1428function tex.getlinebreakresultfields ( ) return <t:table> end
1429function tex.getlinebreakstatevalues ( ) return <t:table> end
1430function tex.getlistanchorvalues ( ) return <t:table> end
1431function tex.getlistfields ( ) return <t:table> end
1432function tex.getlistgeometryvalues ( ) return <t:table> end
1433function tex.getlistsignvalues ( ) return <t:table> end
1434function tex.getlocalboxlocations ( ) return <t:table> end
1435function tex.getmathclassoptionvalues ( ) return <t:table> end
1436function tex.getmathcontrolvalues ( ) return <t:table> end
1437function tex.getmathgluevalues ( ) return <t:table> end
1438function tex.getmathoptionvalues ( ) return <t:table> end
1439function tex.getmathparametervalues ( ) return <t:table> end
1440function tex.getmathscriptordervalues ( ) return <t:table> end
1441function tex.getmathscriptsmodevalues ( ) return <t:table> end
1442function tex.getmathstylenamevalues ( ) return <t:table> end
1443function tex.getmathstylevalues ( ) return <t:table> end
1444function tex.getmathsurroundvalues ( ) return <t:table> end
1445function tex.getmathvariantpresets ( ) return <t:table> end
1446function tex.getmathvariantvalues ( ) return <t:table> end
1447function tex.getmarknames ( ) return <t:table> end
1448function tex.getmvloptionvalues ( ) return <t:table> end
1449function tex.getmodevalues ( ) return <t:table> end
1450function tex.getnestfields ( ) return <t:table> end
1451function tex.getnoadoptionvalues ( ) return <t:table> end
1452function tex.getnormalizelinevalues ( ) return <t:table> end
1453function tex.getnormalizeparvalues ( ) return <t:table> end
1454function tex.getpacktypevalues ( ) return <t:table> end
1455function tex.getpagecontextvalues ( ) return <t:table> end
1456function tex.getpagestatevalues ( ) return <t:table> end
1457function tex.getparametermodevalues ( ) return <t:table> end
1458function tex.getparcontextvalues ( ) return <t:table> end
1459function tex.getparmodevalues ( ) return <t:table> end
1460function tex.getpartriggervalues ( ) return <t:table> end
1461function tex.getpenaltyoptionvalues ( ) return <t:table> end
1462function tex.getprepoststatevalues ( ) return <t:table> end
1463function tex.getprimitiveorigins ( ) return <t:table> end
1464function tex.getprotrusionboundaryvalues ( ) return <t:table> end
1465function tex.getruleoptionvalues ( ) return <t:table> end
1466function tex.getrunstatevalues ( ) return <t:table> end
1467function tex.getshapingpenaltiesvalues ( ) return <t:table> end
1468function tex.getspecialmathclassvalues ( ) return <t:table> end
1469function tex.getspecificationoptionvalues ( ) return <t:table> end
1470function tex.gettextcontrolvalues ( ) return <t:table> end
1471function tex.getuleaderlocationvalues ( ) return <t:table> end
1472function tex.getunitclassvalues ( ) return <t:table> end
1473\stoptyping
1474
1475\stopsubsection
1476
1477\startsubsection [title={Glyphs}]
1478
1479There are a few (internal) integer parameters that relate to glyphs, \typ
1480{\glyphdatafield}, \typ {\glyphstatefield}, \typ {\glyphscriptfield} as well as
1481the three scales \typ {\glyphscale}, \typ {\glyphxscale} and \typ
1482{\glyphyscale}, and for these we have fast accessors:
1483
1484\starttyping[option=LUA]
1485function tex.setglyphdata ( <t:integer> ) end
1486function tex.setglyphstate ( <t:integer> ) end
1487function tex.setglyphscript ( <t:integer> ) end
1488\stoptyping
1489
1490and
1491
1492\starttyping[option=LUA]
1493function tex.getglyphdata ( ) return <t:integer> end
1494function tex.getglyphstate ( ) return <t:integer> end
1495function tex.getglyphscript ( ) return <t:integer> end
1496\stoptyping
1497
1498The scale getter returns more:
1499
1500\starttyping[option=LUA]
1501function tex.getglyphscales ( )
1502 return
1503 <t:integer>, scale
1504 <t:integer>, xscale
1505 <t:integer>, yscale
1506 <t:integer> data
1507end
1508\stoptyping
1509
1510\stopsubsection
1511
1512\startsubsection [title={Whatever}]
1513
1514We have no backend so all that the next does is wiping the box:
1515
1516\starttyping[option=LUA]
1517function tex.shipout ( <t:integer> index )
1518 no return values
1519end
1520\stoptyping
1521
1522This helper function is useful during line break calculations. The arguments
1523\type {t} and \type {s} are scaled values; the function returns the badness for
1524when total \type {t} is supposed to be made from amounts that sum to \type {s}.
1525The returned number is a reasonable approximation of \mathematics {100 ( t s)
15263}.
1527
1528\starttyping[option=LUA]
1529function tex.badness (
1530 <t:integer> t,
1531 <t:integer> s
1532)
1533 return <t:integer>
1534end
1535\stoptyping
1536
1537The page builder can be in different states, so here is how you get the current state:
1538
1539\starttyping[option=LUA]
1540function tex.getpagestate ( )
1541 return <t:integer>
1542end
1543\stoptyping
1544
1545possible states are:
1546
1547\starttworows
1548\getbuffer[engine:syntax:pagestatecodes]
1549\stoptworows
1550
1551You can also check if were in the output routine:
1552
1553\starttyping[option=LUA]
1554function tex.getoutputactive ( )
1555 return <t:boolean>
1556end
1557\stoptyping
1558
1559An example of a (possible error triggering) complication is that \TEX\ expects to
1560be in some state, say horizontal mode, and you have to make sure it is when you
1561start feeding back something from \LUA\ into \TEX. Normally a user will not run
1562into issues but when you start writing tokens or nodes or have a nested run there
1563can be situations that you need to enforce horizontal mode. There is no recipe
1564for this and intercepting possible cases would weaken \LUATEXs flexibility.
1565Therefore we provide \type {forcehmode} which is similar to \type {\quitvmode} at
1566the \TEX\ end, although in \CONTEXT, that had it already, we always use \type
1567{\dontleavehmode} as name.
1568
1569\starttyping[option=LUA]
1570function tex.forcehmode ( )
1571 no return values
1572end
1573\stoptyping
1574
1575The last node in the current list is queried with the following helper. If there is no
1576node you get \type {nil}s back.
1577
1578\starttyping[option=LUA]
1579function tex.lastnodetype ( )
1580 return
1581 <t:integer>, type
1582 <t:integer> subtype
1583end
1584\stoptyping
1585
1586The current mode is available with:
1587
1588\starttyping[option=LUA]
1589function tex.getmode ( )
1590 return <t:integer>
1591end
1592\stoptyping
1593
1594Currently were in mode {\tttf 0x\tohexadecimal\cldcontext {tex.getmode()}}, a
1595number that you can give meaning with \type {tex.getmodevalues()}:
1596
1597\getbuffer[engine:syntax:modes]
1598
1599The run state can be fetched with:
1600
1601\starttyping[option=LUA]
1602function tex.getrunstate ( )
1603 return <t:integer>
1604end
1605\stoptyping
1606
1607which returns one of:
1608
1609\getbuffer[engine:syntax:runstates]
1610
1611When we load create the format file were initializing and when we then do a
1612regular run we are in production. The updating state is just there so that we can
1613deal with overload protection. In that case we need to honor the \type
1614{\enforced} prefix, that can only be used when not in production mode. When a
1615runtime module nevertheless wants to use that prefix it can (from \LUA) set the
1616mode to updating. This is all kind of \CONTEXT\ specific because there we use
1617the overload protection mechanism.
1618
1619\stopsubsection
1620
1621\startsubsection[title=Files and lines]
1622
1623You can register a file id and line number in a \type {glyph}, \type {hlist} and
1624\type {vlist} nodes, for instance for implementing a \SYNCTEX\ emulator. There are
1625some helpers that relate to this. When the mode is zero, no registering will
1626done, when set to one, lists will be tagged and larger values make that glyphs
1627will be tagged too.
1628
1629\starttyping[option=LUA]
1630function tex.setinputstatemode ( <t:integer> mode )
1631 no return values
1632end
1633\stoptyping
1634
1635The file is registered as a number and the engine is agnostic about what it
1636refers too. The same is true for lines. In fact, you can use these fields
1637for whatever purpose you like.
1638
1639\starttyping[option=LUA]
1640function tex.setinputstatefile ( <t:integer> fileid )
1641 no return values
1642end
1643
1644function tex.setinputstateline ( <t:integer> linenumber )
1645 no return values
1646end
1647\stoptyping
1648
1649The getters just return the currently set values:
1650
1651\starttyping[option=LUA]
1652function tex.getinputstatemode ( ) return <t:integer> end
1653function tex.getinputstatefile ( ) return <t:integer> end
1654function tex.getinputstateline ( ) return <t:integer> end
1655\stoptyping
1656
1657The file and line number are bound to the current input which can be nested. So,
1658nesting is handled by the engine. However, you can overload that with the
1659following two helpers. The values set will win over the ones bound to the current
1660input file.
1661
1662\starttyping[option=LUA]
1663function tex.forceinputstatefile ( <t:integer> fileid )
1664 no return values
1665end
1666
1667function tex.forceinputstateline ( <t:integer> linenumber )
1668 no return values
1669end
1670\stoptyping
1671
1672\stopsubsection
1673
1674\startsubsection[title=Interacting]
1675
1676In \LUAMETATEX\ valid interaction modes are:
1677
1678\starttworows
1679\getbuffer[engine:syntax:interactionmodes]
1680\stoptworows
1681
1682You can get and set the mode with:
1683
1684\starttyping[option=LUA]
1685function tex.getinteraction ( )
1686 return <t:integer> mode
1687end
1688function tex.setinteraction ( <t:integer> mode )
1689 no return values
1690end
1691\stoptyping
1692
1693When an error occurs it can be intercepted by a callback in which case you have
1694to handle the feedback yourself. For this we have two helpers:
1695
1696\starttyping[option=LUA]
1697function tex.showcontext ( ) end
1698function tex.gethelptext ( ) end
1699\stoptyping
1700
1701An error can be triggered with:
1702
1703\starttyping[option=LUA]
1704function tex.error (
1705 <t:string> error,
1706 <t:string> help
1707)
1708 no return values
1709end
1710\stoptyping
1711
1712Of course these are also intercepted by the callback, when set, in which case the
1713help text can be fetched. There can arise a situation where the engine is in a
1714state where properly dealing with errors has become a problem. In that case you
1715can use:
1716
1717\starttyping[option=LUA]
1718function tex.fatalerror ( <t:string> error) end
1719\stoptyping
1720
1721In this case the run will be aborted. For the record: in \CONTEXT\ any error will
1722quit the run, just because it makes no sense to try to recover from unpredictable
1723situations and a fix is needed anyway.
1724
1725\stopsubsection
1726
1727\startsubsection[title=Save levels]
1728
1729When you start a group or any construct that behaves like one, for instance
1730boxing, the save stack is \quote {pushed} which means that a boundary is set.
1731When the group ends the values that were saved in the current region (bounded)
1732are restored. You can also do this in \LUA:
1733
1734\starttyping[option=LUA]
1735function tex.pushsavelevel ( ) end
1736function tex.popsavelevel ( ) end
1737\stoptyping
1738
1739This is a way to create grouping when in \LUA\ so that when you set some register
1740the engine will handle the restore.
1741
1742\stopsubsection
1743
1744\startsubsection[title=Local control]
1745
1746When we talk about local control we mean expanding \TEX\ code in a nested main
1747loop. We start with explaining \type {tex.runlocal}. The first argument can be a
1748number (of a token register), a macro name, the name of a token list or some
1749(userdata) token made at the \LUA\ end. The second argument is optional and when
1750true forces expansion inside a definition. The optional third argument can be
1751used to force grouping. The return value indicates an error: 0 means no error, 1
1752means that a bad register number has been passed, a value of 2 indicated an
1753unknown register or macro name, while 3 reports that the macro is not suitable
1754for local control because it takes arguments.
1755
1756\startbuffer
1757\scratchtoks{This is {\bf an example} indeed.}
1758\startluacode
1759 tex.runlocal("scratchtoks")
1760\stopluacode
1761\stopbuffer
1762
1763\typebuffer
1764
1765This typesets: \inlinebuffer
1766
1767However, the neat thing about local control is that it happens immediately, so not
1768after the \LUA\ blob ended as with \typ [option=LUA] {tex.print ("\\the\scratchtoks")}.
1769
1770\startbuffer
1771\scratchtoks{\setbox\scratchbox\hbox{This is {\bf an example} indeed.}}
1772\startluacode
1773 tex.runlocal("scratchtoks")
1774 context("The width is: %p",tex.box.scratchbox.width)
1775\stopluacode
1776\stopbuffer
1777
1778\typebuffer
1779
1780This typesets: \inlinebuffer
1781
1782\starttyping[option=LUA]
1783function tex.runlocal (
1784 <t:string> name,
1785 <t:boolean> expand,
1786 <t:boolean> group
1787)
1788 return <t:integer> state
1789end
1790\stoptyping
1791
1792You can quit a local controlled expansion with the following, but if it works
1793depends on the situation.
1794
1795\starttyping[option=LUA]
1796function tex.quitlocal ( )
1797 no return values
1798end
1799\stoptyping
1800
1801There might be situations that you push something from \LUA\ to \TEX\ in a local
1802call and dont want interference. In that case wrapping might help but it is not
1803that well tested yet:
1804
1805\starttyping[option=LUA]
1806function tex.pushlocal ( )
1807 no return values
1808end
1809
1810function tex.poplocal ( )
1811 no return values
1812end
1813\stoptyping
1814
1815The current level of local calls is available with:
1816
1817\starttyping[option=LUA]
1818function tex.getlocallevel ( )
1819 return <t:integer>
1820end
1821\stoptyping
1822
1823You can also run a string through \TEX; the last three booleans are optional.
1824
1825\starttyping[option=LUA]
1826function tex.runlocal (
1827 <t:string> str,
1828 <t:boolean> expandindefinitions,
1829 <t:boolean> group,
1830 <t:boolean> ignoreundefindcs
1831)
1832 no return values
1833end
1834
1835function tex.runlocal (
1836 <t:integer> catcodetable,
1837 <t:string> str,
1838 <t:boolean> expandindefinitions,
1839 <t:boolean> group,
1840 <t:boolean> ignoreundefindcs
1841)
1842 no return values
1843end
1844\stoptyping
1845
1846\stopsubsection
1847
1848\startsubsection[title=Math]
1849
1850There are some setters and getters that relate to the math sub engine. The setter has two variants:
1851
1852\starttyping[option=LUA]
1853function tex.setmathcode (
1854 <t:integer> target,
1855 <t:integer> class,
1856 <t:integer> family,
1857 <t:integer> character
1858)
1859 no return values
1860end
1861
1862function tex.setmathcode (
1863 <t:integer> target,
1864 <t:table> {
1865 <t:integer>, class
1866 <t:integer>, family
1867 <t:integer> character
1868 }
1869)
1870 no return values
1871end
1872\stoptyping
1873
1874But there are two getters:
1875
1876\starttyping[option=LUA]
1877function tex.getmathcode (
1878 <t:integer> target
1879)
1880 return <t:table> {
1881 <t:integer>, class
1882 <t:integer>, family
1883 <t:integer> character
1884 }
1885end
1886
1887function tex.getmathcodes (
1888 <t:integer> target
1889)
1890 return
1891 <t:integer>, class
1892 <t:integer>, family
1893 <t:integer> character
1894end
1895\stoptyping
1896
1897Delcodes have different properties:
1898
1899
1900
1901
1902
1903\starttyping[option=LUA]
1904function tex.setdelcode (
1905 <t:integer> target,
1906 <t:integer> smallfamily,
1907 <t:integer> smallcharacter,
1908 <t:integer> largefamily,
1909 <t:integer> largecharacter
1910)
1911 no return values
1912end
1913
1914function tex.setdelcode (
1915 <t:integer> target,
1916 <t:table> {
1917 <t:integer>, smallfamily,
1918 <t:integer>, smallcharacter,
1919 <t:integer>, largefamily,
1920 <t:integer> largecharacter
1921 }
1922)
1923 no return values
1924end
1925\stoptyping
1926
1927Again there two getters:
1928
1929\starttyping[option=LUA]
1930function tex.getdelcode (
1931 <t:integer> target
1932)
1933 return <t:table> {
1934 <t:integer>, smallfamily,
1935 <t:integer>, smallcharacter,
1936 <t:integer>, largefamily,
1937 <t:integer> largecharacter
1938 }
1939end
1940
1941function tex.getdelcodes (
1942 <t:integer> target
1943)
1944 return
1945 <t:integer>, smallfamily,
1946 <t:integer>, smallcharacter,
1947 <t:integer>, largefamily,
1948 <t:integer> largecharacter
1949 end
1950\stoptyping
1951
1952In \LUAMETATEX\ the engine can do without these delimiter specifications so they
1953might eventually go way. The reason is that when a delimiter is needed we also
1954accent a math character. When we use an \OPENTYPE\ model its likely that the
1955large character comes from the same font as the small character. And because the
1956font is loaded under \LUA\ control one can always use a virtual character to
1957refer to an other font, something that we do in \CONTEXT\ when we load a
1958\TYPEONE\ based math font.
1959
1960A named math character is defined with \type {mathchardef} but contrary to its
1961\TEX\ counterpart \typ {\mathchardef} it accepts three four extra parameters.
1962The \typ {properties}, \type {group} and \type {index} are data fields that the
1963(for instance) the backend can use. We make no assumptions about their use
1964because it is macro package dependent. There can be flags before the three
1965optional parameters.
1966
1967\starttyping[option=LUA]
1968function tex.mathchardef (
1969 <t:string> name
1970 <t:integer> class,
1971 <t:integer> family,
1972 <t:integer> character,
1973 <t:integer> flags, zero or more
1974 <t:integer> properties,
1975 <t:integer> group,
1976 <t:integer> index
1977)
1978 no return values
1979end
1980\stoptyping
1981
1982The \type {\chardef} equivalent is:
1983
1984\starttyping[option=LUA]
1985function tex.chardef (
1986 <t:string> name
1987 <t:integer> character,
1988 <t:integer> flags, zero or more
1989)
1990 no return values
1991end
1992\stoptyping
1993
1994Math parameters have their own setter and getter. The first string is the
1995parameter name minus the leading \type {Umath}, and the second string is the
1996style name minus the trailing \type {style}. A value is either an integer
1997(representing a dimension or number) or a list of glue components.
1998
1999\starttyping[option=LUA]
2000function tex.setmath (
2001 <t:string> prefix, zero or more
2002 <t:integer> parameter,
2003 <t:integer> style,
2004 <t:integer> value, one or more
2005)
2006 no return values
2007end
2008\stoptyping
2009
2010\starttyping[option=LUA]
2011function tex.setmath (
2012 <t:integer> parameter,
2013 <t:integer> style
2014)
2015 return <t:integer> one or more value
2016end
2017\stoptyping
2018
2019For the next one you need to know what style variants which we will not discuss
2020here:
2021
2022\starttyping[option=LUA]
2023function tex.getmathstylevariant (
2024 <t:integer> style,
2025 <t:integer> parameter
2026)
2027 <t:integer>, value
2028 <t:integer> variant
2029end
2030\stoptyping
2031
2032\stopsubsection
2033
2034\startsubsection[title=Processing]
2035
2036You should not expect to much from the \type {triggerbuildpage} helpers because
2037often \TEX\ doesnt do much if it thinks nothing has to be done, but it might be
2038useful for some applications. It just does as it says it calls the internal
2039function that build a page, given that there is something to build.
2040
2041\starttyping[option=LUA]
2042function tex.triggerbuildpage ( )
2043 no return values
2044end
2045\stoptyping
2046
2047This function resets the parameters that \TEX\ normally resets when a new paragraph
2048is seen.
2049
2050\starttyping[option=LUA]
2051function tex.resetparagraph ( )
2052 no return values
2053end
2054\stoptyping
2055
2056The linebreak algorithm can also be applied explicitly to a node list that better
2057be right. There is some checking done with respect to the beginning and paragraph
2058and interfering glue.
2059
2060\starttyping[option=LUA]
2061function tex.linebreak (
2062 <t:direct> listhead,
2063 <t:table> parameters
2064)
2065 return
2066 <t:direct>, nodelist
2067 <t:table> info
2068end
2069\stoptyping
2070
2071There are a lot of parameters that drive the process and many can be set. The
2072interface might be extended in the future. Valid parameter fields are:
2073\showenginekeylist {tex.getlinebreakparameterfields()}. There is no need to set
2074them (at all) because the usual \TEX\ parameters apply when they are absent.
2075
2076The result is a node list, it still needs to be vpacked if you want to assign it
2077to a \type {\vbox}. The returned \type {info} table contains the following fields:
2078\showenginekeylist {tex.getlinebreakresultfields()}.
2079
2080A list can be \quote {prepared} for a linebreak call with the next function.
2081Normally the linebreak routine will do this. The return values are pointers to
2082some relevant nodes.
2083
2084\starttyping[option=LUA]
2085function tex.preparelinebreak (
2086 <t:direct> listhead
2087)
2088 return
2089 <t:node>, nodelist
2090 <t:table> info
2091 <t:direct>, par (head)
2092 <t:direct>, tail
2093 <t:direct>, parinitleftskip
2094 <t:direct>, parinitrightskip
2095 <t:direct>, parfillleftskip
2096 <t:direct> parfillrightskip
2097end
2098\stoptyping
2099
2100\starttyping[option=LUA]
2101function tex.snapshotpar ( <t:integer> bitset )
2102 return <t:integer> state (bitset)
2103end
2104\stoptyping
2105
2106The bitset is made from:
2107
2108\startthreerows
2109\getbuffer[engine:syntax:frozenparcodes]
2110\stopthreerows
2111
2112This one is handy when you mess with lists and want to take some parameters
2113into account that matter when building a paragraph. The returned fields are:
2114\showenginekeylist {tex.getparstatefields()}.
2115
2116\starttyping[option=LUA]
2117function tex.getparstate ( )
2118 return <t:table>
2119end
2120\stoptyping
2121
2122A par shape normally is discarded when the paragraph ends but we can continue
2123using it if needed. In that case we can shift the current array and either
2124or not rotate.
2125
2126\starttyping[option=LUA]
2127function tex.shiftparshape (
2128 <t:integer> shift,
2129 <t:boolean> rotate
2130)
2131 no return values
2132end
2133\stoptyping
2134
2135A specification, like \type {\parshape} or \type {\widowpenalties} can be fetched
2136with:
2137
2138\starttyping[option=LUA]
2139function tex.getspecification ( <t:string> name )
2140 return <t:table>
2141end
2142\stoptyping
2143
2144\stopsubsection
2145
2146\startsubsection[title=MVL]
2147
2148This returns the currently active main vertical list:
2149
2150\starttyping[option=LUA]
2151function tex.getcurrentmvl ( )
2152 return <t:integer>
2153end
2154\stoptyping
2155
2156\stopsubsection
2157
2158\startsubsection[title=Balancing]
2159
2160At the moment we only have a few balance related helpers. One of them can set
2161the current \prm {balanceshape}.
2162
2163\starttyping[option=LUA]
2164function tex.setbalanceshape (
2165 <t:table> steps
2166)
2167 return <t:integer>
2168end
2169\stoptyping
2170
2171The indexed table has subtables with fields:
2172
2173\starttabulate[ll]
2174\NC \type {index} \NC \type[option=lua]{<t:integer>} \NC \NR
2175\NC \type {options} \NC \type[option=lua]{<t:integer>} \NC \NR
2176\NC \type {vsize} \NC \type[option=lua]{<t:number>} \NC \NR
2177\NC \type {topskip} \NC \type[option=lua]{<t:number> <t:node>} \NC \NR
2178\NC \type {bottomskip} \NC \type[option=lua]{<t:number> <t:node>} \NC \NR
2179\NC \type {extra} \NC \type[option=lua]{<t:number>} \NC \NR
2180\stoptabulate
2181
2182\stopsubsection
2183
2184\stopsection
2185
2186\startsection[title={The configuration}]
2187
2188The global \type {texconfig} table is created empty. A startup \LUA\ script could
2189fill this table with a number of settings that are read out by the executable
2190after loading and executing the startup file. Watch out: some keys are different
2191from \LUATEX, which is a side effect of a more granular and dynamic memory
2192management.
2193
2194\starttabulate[llll]
2195\FL
2196\BC key \BC type \BC default \BC comment \NC \NR
2197\TL
2198\NC \type {buffersize} \NC numbertable \NC 1000000 \NC input buffer bytes \NC \NR
2199\NC \type {filesize} \NC numbertable \NC 1000 \NC max number of open files \NC \NR
2200\NC \type {fontsize} \NC numbertable \NC 250 \NC number of permitted fonts \NC \NR
2201\NC \type {hashsize} \NC numbertable \NC 150000 \NC number of hash entries \NC \NR
2202\NC \type {inputsize} \NC numbertable \NC 10000 \NC maximum input stack \NC \NR
2203\NC \type {languagesize} \NC numbertable \NC 250 \NC number of permitted languages \NC \NR
2204\NC \type {marksize} \NC numbertable \NC 50 \NC number of mark classes \NC \NR
2205\NC \type {nestsize} \NC numbertable \NC 1000 \NC max depth of nesting \NC \NR
2206\NC \type {nodesize} \NC numbertable \NC 1000000 \NC max node memory (various size) \NC \NR
2207\NC \type {parametersize} \NC numbertable \NC 20000 \NC max size of parameter stack \NC \NR
2208\NC \type {poolsize} \NC numbertable \NC 10000000 \NC max number of string bytes \NC \NR
2209\NC \type {savesize} \NC numbertable \NC 100000 \NC mas size of save stack \NC \NR
2210\NC \type {stringsize} \NC numbertable \NC 150000 \NC max number of strings \NC \NR
2211\NC \type {tokensize} \NC numbertable \NC 1000000 \NC max token memory \NC \NR
2212\NC \type {mvlsize} \NC numbertable \NC 10 \NC max mvl memory \NC \NR
2213\ML
2214\NC \type {expandsize} \NC numbertable \NC 10000 \NC max expansion nesting \NC \NR
2215\NC \type {propertiessize} \NC number \NC 0 \NC initial size of node properties table \NC \NR
2216\NC \type {functionsize} \NC number \NC 0 \NC initial size of \LUA\ functions table \NC \NR
2217\NC \type {errorlinesize} \NC number \NC 79 \NC how much or an error is shown \NC \NR
2218\NC \type {halferrorlinesize} \NC number \NC 50 \NC idem \NC \NR
2219\ML
2220\NC \type {formatname} \NC string \NC \NC \NC \NR
2221\NC \type {jobname} \NC string \NC \NC \NC \NR
2222\ML
2223\NC \type {starttime} \NC number \NC \NC for testing only \NC \NR
2224\NC \type {useutctime} \NC number \NC \NC for testing only \NC \NR
2225\NC \type {permitloadlib} \NC number \NC \NC for testing only \NC \NR
2226\LL
2227\stoptabulate
2228
2229If no format name or jobname is given on the command line, the related keys will
2230be tested first instead of simply quitting. The statistics library has methods
2231for tracking down how much memory is available and has been configured. The size
2232parameters take a number (for the maximum allocated size) or a table with three
2233possible keys: \type {size}, \type {plus} (for extra size) and \type {step} for
2234the increment when more memory is needed. They all start out with a hard coded
2235minimum and also have an hard coded maximum, the the configured size sits
2236somewhere between these.
2237
2238\stopsection
2239
2240\startsection[title={Input and output}]
2241
2242This library takes care of the lowlevel IO interface: writing to the log file
2243andor the console. The log file is registered with the following function:
2244
2245\starttyping[option=LUA]
2246function texio.setlogfile ( <t:file> handle )
2247 no return values
2248end
2249\stoptyping
2250
2251When \TEX\ serializes something it uses a seslector to determine where it goes.
2252The public selectors are:
2253
2254\getbuffer[engine:syntax:selectorvalues]
2255
2256Internal we have a string selector, \LUA\ buffer selector, and a so called pseudo
2257selector that is used when we want to show the context of an error and that keeps
2258track of the position. These are not opened up.
2259
2260We start with \type {texio.write}. Without the \type {target} argument, it writes
2261all given strings to the same location(s) that \TEX\ writes messages to at that
2262moment. If \type {\batchmode} is in effect, it writes only to the log, otherwise
2263it writes to the log and the terminal. A target can be a number or string.
2264
2265\starttyping[option=LUA]
2266function texio.write ( <t:string> target, <t:string> s, ...)
2267 no return values
2268end
2269
2270function texio.write ( <t:string> s, ... )
2271 no return values
2272end
2273\stoptyping
2274
2275If several strings are given, and if the first of these strings is or might be
2276one of the targets above, the \type {target} must be specified explicitly to
2277prevent \LUA\ from interpreting the first string as the target.
2278
2279The next function behaves like the above, but makes sure that the given strings
2280will appear at the beginning of a new line. You can pass a single empty string if
2281you only want to move to the next line. One reason why log output can slow down a
2282run is that the engine works piecewise instead of printing lines. Deep down many
2283writes go character by character because messages can occur everywhere during the
2284expansion process.
2285
2286\starttyping[option=LUA]
2287function texio.writenl ( <t:string> s, ... )
2288 no return values
2289end
2290\stoptyping
2291
2292The selector variants below always expect a selector, so there is no
2293misunderstanding if \type {logfile} is a string or selector.
2294
2295\starttyping[option=LUA]
2296function texio.writeselector ( <t:string> s, ... )
2297 no return values
2298end
2299
2300function texio.writeselectornl ( <t:string> s, ... )
2301 no return values
2302end
2303
2304function texio.writeselectorlf ( <t:string> s, ... )
2305 no return values
2306end
2307\stoptyping
2308
2309The next function should be used with care. It acts as \type {\endinput} but at
2310the \LUA\ end. You can use it to (sort of) force a jump back to \TEX. Normally a
2311\LUA\ call will just collect prints and at the end bump an input level and flush
2312these prints. This function can help you stay at the current level but you need
2313to know what youre doing (or more precise: what \TEX\ is doing with input).
2314
2315\starttyping[option=LUA]
2316function texio.closeinput ( )
2317 no return values
2318end
2319\stoptyping
2320
2321
2322
2323
2324
2325
2326
2327\stopsection
2328
2329\stopdocument
2330
2331
2332
2333
2334
2335 |