Debian Codegraph @

texmf-dist/doc/luatex/base/luatex-tex.tex

raw
1 % engine=luatex language=uk
2
3 % lua.newtable
4
5 \environment luatex-style
6
7 \startcomponent luatex-tex
8
9 \startchapter[reference=tex,title={The \TEX\ related libraries}]
10
11 \startsection[title={The \type {lua} library}][library=lua]
12
13 \startsubsection[title={Version information}]
14
15 \topicindex{libraries+\type{lua}}
16 \topicindex{version}
17
18 \libindex{version}
19
20 This library contains one read|-|only item:
21
22 \starttyping
23 <string> s = lua.version
24 \stoptyping
25
26 This returns the \LUA\ version identifier string. The value is currently
27 \directlua {tex.print(lua.version)}.
28
29 \stopsubsection
30
31 \startsubsection[title={Bytecode registers}]
32
33 \topicindex{bytecodes}
34 \topicindex{registers+bytecodes}
35
36 \libindex{bytecode}
37 \libindex{setbytecode}
38 \libindex{getbytecode}
39
40 \LUA\ registers can be used to store \LUA\ code chunks. The accepted values for
41 assignments are functions and \type {nil}. Likewise, the retrieved value is
42 either a function or \type {nil}.
43
44 \starttyping
45 lua.bytecode[<number> n] = <function> f
46 lua.bytecode[<number> n]()
47 \stoptyping
48
49 The contents of the \type {lua.bytecode} array is stored inside the format file
50 as actual \LUA\ bytecode, so it can also be used to preload \LUA\ code. The
51 function must not contain any upvalues. The associated function calls are:
52
53 \startfunctioncall
54 <function> f = lua.getbytecode(<number> n)
55 lua.setbytecode(<number> n, <function> f)
56 \stopfunctioncall
57
58 Note: Since a \LUA\ file loaded using \type {loadfile(filename)} is essentially
59 an anonymous function, a complete file can be stored in a bytecode register like
60 this:
61
62 \startfunctioncall
63 lua.bytecode[n] = loadfile(filename)
64 \stopfunctioncall
65
66 Now all definitions (functions, variables) contained in the file can be
67 created by executing this bytecode register:
68
69 \startfunctioncall
70 lua.bytecode[n]()
71 \stopfunctioncall
72
73 Note that the path of the file is stored in the \LUA\ bytecode to be used in
74 stack backtraces and therefore dumped into the format file if the above code is
75 used in \INITEX. If it contains private information, i.e. the user name, this
76 information is then contained in the format file as well. This should be kept in
77 mind when preloading files into a bytecode register in \INITEX.
78
79 \stopsubsection
80
81 \startsubsection[title={Chunk name registers}]
82
83 \libindex{name}
84 \libindex{setluaname}
85 \libindex{getluaname}
86
87 There is an array of 65536 (0--65535) potential chunk names for use with the
88 \prm {directlua} and \lpr {latelua} primitives.
89
90 \startfunctioncall
91 lua.name[<number> n] = <string> s
92 <string> s = lua.name[<number> n]
93 \stopfunctioncall
94
95 If you want to unset a \LUA\ name, you can assign \type {nil} to it. The function
96 accessors are:
97
98 \startfunctioncall
99 lua.setluaname(<number> n, <string> s)
100 <string> s = lua.getluaname(<number> n)
101 \stopfunctioncall
102
103 \stopsubsection
104
105 \startsubsection[title={Introspection}]
106
107 \libindex{getstacktop}
108 \libindex{getcalllevel}
109
110 The \type {getstacktop} and\type {getcalllevel} functions return numbers
111 indicating how much nesting is going on. They are only of use as breakpoints when
112 checking some mechanism going haywire.
113
114 \stopsubsection
115
116 \stopsection
117
118 \startsection[title={The \type {status} library}][library=status]
119
120 \topicindex{libraries+\type{status}}
121
122 \libindex{list}
123 \libindex{resetmessages}
124 \libindex{setexitcode}
125
126 This contains a number of run|-|time configuration items that you may find useful
127 in message reporting, as well as an iterator function that gets all of the names
128 and values as a table.
129
130 \startfunctioncall
131 <table> info = status.list()
132 \stopfunctioncall
133
134 The keys in the table are the known items, the value is the current value. Almost
135 all of the values in \type {status} are fetched through a metatable at run|-|time
136 whenever they are accessed, so you cannot use \type {pairs} on \type {status},
137 but you {\it can\/} use \type {pairs} on \type {info}, of course. If you do not
138 need the full list, you can also ask for a single item by using its name as an
139 index into \type {status}. The current list is:
140
141 \starttabulate[|l|p|]
142 \DB key \BC explanation \NC \NR
143 \TB
144 \NC \type{banner} \NC terminal display banner \NC \NR
145 \NC \type{best_page_break} \NC the current best break (a node) \NC \NR
146 \NC \type{buf_size} \NC current allocated size of the line buffer \NC \NR
147 \NC \type{callbacks} \NC total number of executed callbacks so far \NC \NR
148 \NC \type{cs_count} \NC number of control sequences \NC \NR
149 \NC \type{dest_names_size} \NC \PDF\ destination table size \NC \NR
150 \NC \type{dvi_gone} \NC written \DVI\ bytes \NC \NR
151 \NC \type{dvi_ptr} \NC not yet written \DVI\ bytes \NC \NR
152 \NC \type{dyn_used} \NC token (multi|-|word) memory in use \NC \NR
153 \NC \type{filename} \NC name of the current input file \NC \NR
154 \NC \type{fix_mem_end} \NC maximum number of used tokens \NC \NR
155 \NC \type{fix_mem_min} \NC minimum number of allocated words for tokens \NC \NR
156 \NC \type{fix_mem_max} \NC maximum number of allocated words for tokens \NC \NR
157 \NC \type{font_ptr} \NC number of active fonts \NC \NR
158 \NC \type{hash_extra} \NC extra allowed hash \NC \NR
159 \NC \type{hash_size} \NC size of hash \NC \NR
160 \NC \type{indirect_callbacks} \NC number of those that were themselves a result of other callbacks (e.g. file readers) \NC \NR
161 \NC \type{ini_version} \NC \type {true} if this is an \INITEX\ run \NC \NR
162 \NC \type{init_pool_ptr} \NC \INITEX\ string pool index \NC \NR
163 \NC \type{init_str_ptr} \NC number of \INITEX\ strings \NC \NR
164 \NC \type{input_ptr} \NC the level of input we're at \NC \NR
165 \NC \type{inputid} \NC numeric id of the current input \NC \NR
166 \NC \type{largest_used_mark} \NC max referenced marks class \NC \NR
167 \NC \type{lasterrorcontext} \NC last error context string (with newlines) \NC \NR
168 \NC \type{lasterrorstring} \NC last \TEX\ error string \NC \NR
169 \NC \type{lastluaerrorstring} \NC last \LUA\ error string \NC \NR
170 \NC \type{lastwarningstring} \NC last warning tag, normally an indication of in what part\NC \NR
171 \NC \type{lastwarningtag} \NC last warning string\NC \NR
172 \NC \type{linenumber} \NC location in the current input file \NC \NR
173 \NC \type{log_name} \NC name of the log file \NC \NR
174 \NC \type{luabytecode_bytes} \NC number of bytes in \LUA\ bytecode registers \NC \NR
175 \NC \type{luabytecodes} \NC number of active \LUA\ bytecode registers \NC \NR
176 \NC \type{luastate_bytes} \NC number of bytes in use by \LUA\ interpreters \NC \NR
177 \NC \type{luatex_engine} \NC the \LUATEX\ engine identifier \NC \NR
178 \NC \type{luatex_hashchars} \NC length to which \LUA\ hashes strings ($2^n$) \NC \NR
179 \NC \type{luatex_hashtype} \NC the hash method used (in \LUAJITTEX) \NC \NR
180 \NC \type{luatex_version} \NC the \LUATEX\ version number \NC \NR
181 \NC \type{luatex_revision} \NC the \LUATEX\ revision string \NC \NR
182 \NC \type{max_buf_stack} \NC max used buffer position \NC \NR
183 \NC \type{max_in_stack} \NC max used input stack entries \NC \NR
184 \NC \type{max_nest_stack} \NC max used nesting stack entries \NC \NR
185 \NC \type{max_param_stack} \NC max used parameter stack entries \NC \NR
186 \NC \type{max_save_stack} \NC max used save stack entries \NC \NR
187 \NC \type{max_strings} \NC maximum allowed strings \NC \NR
188 \NC \type{nest_size} \NC nesting stack size \NC \NR
189 \NC \type{node_mem_usage} \NC a string giving insight into currently used nodes \NC \NR
190 \NC \type{obj_ptr} \NC max \PDF\ object pointer \NC \NR
191 \NC \type{obj_tab_size} \NC \PDF\ object table size \NC \NR
192 \NC \type{output_active} \NC \type {true} if the \prm {output} routine is active \NC \NR
193 \NC \type{output_file_name} \NC name of the \PDF\ or \DVI\ file \NC \NR
194 \NC \type{param_size} \NC parameter stack size \NC \NR
195 \NC \type{pdf_dest_names_ptr} \NC max \PDF\ destination pointer \NC \NR
196 \NC \type{pdf_gone} \NC written \PDF\ bytes \NC \NR
197 \NC \type{pdf_mem_ptr} \NC max \PDF\ memory used \NC \NR
198 \NC \type{pdf_mem_size} \NC \PDF\ memory size \NC \NR
199 \NC \type{pdf_os_cntr} \NC max \PDF\ object stream pointer \NC \NR
200 \NC \type{pdf_os_objidx} \NC \PDF\ object stream index \NC \NR
201 \NC \type{pdf_ptr} \NC not yet written \PDF\ bytes \NC \NR
202 \NC \type{pool_ptr} \NC string pool index \NC \NR
203 \NC \type{pool_size} \NC current size allocated for string characters \NC \NR
204 \NC \type{save_size} \NC save stack size \NC \NR
205 \NC \type{shell_escape} \NC \type {0} means disabled, \type {1} means anything is permitted, and \type {2} is restricted \NC \NR
206 \NC \type{safer_option} \NC \type {1} means safer is enforced \NC \NR
207 \NC \type{luadebug_option} \NC true if the \type{debug} library is enabled at command line \NC\NR
208 \NC \type{output_directory} \NC the value of the output directory \NC \NR
209 \NC \type{kpse_used} \NC \type {1} means that kpse is used \NC \NR
210 \NC \type{stack_size} \NC input stack size \NC \NR
211 \NC \type{str_ptr} \NC number of strings \NC \NR
212 \NC \type{total_pages} \NC number of written pages \NC \NR
213 \NC \type{var_mem_max} \NC number of allocated words for nodes \NC \NR
214 \NC \type{var_used} \NC variable (one|-|word) memory in use \NC \NR
215 \NC \type{lc_collate} \NC the value of \type {LC_COLLATE} at startup time (becomes \type {C} at startup) \NC \NR
216 \NC \type{lc_ctype} \NC the value of \type {LC_CTYPE} at startup time (becomes \type {C} at startup) \NC \NR
217 %NC \type{lc_monetary} \NC the value of \type {LC_MONETARY} at startup time \NC \NR
218 \NC \type{lc_numeric} \NC the value of \type {LC_NUMERIC} at startup time \NC \NR
219 %NC \type{lc_time} \NC the value of \type {LC_TIME} at startup time (becomes \type {C} at startup) \NC \NR
220 \LL
221 \stoptabulate
222
223 The error and warning messages can be wiped with the \type {resetmessages}
224 function. A return value can be set with \type {setexitcode}.
225
226 \stopsection
227
228 \startsection[title={The \type {tex} library}][library=tex]
229
230 \startsubsection[title={Introduction}]
231
232 \topicindex{libraries+\type{tex}}
233
234 The \type {tex} table contains a large list of virtual internal \TEX\
235 parameters that are partially writable.
236
237 The designation \quote {virtual} means that these items are not properly defined
238 in \LUA, but are only front\-ends that are handled by a metatable that operates
239 on the actual \TEX\ values. As a result, most of the \LUA\ table operators (like
240 \type {pairs} and \type {#}) do not work on such items.
241
242 At the moment, it is possible to access almost every parameter that you can use
243 after \prm {the}, is a single tokens or is sort of special in \TEX. This excludes
244 parameters that need extra arguments, like \type {\the\scriptfont}. The subset
245 comprising simple integer and dimension registers are writable as well as
246 readable (like \prm {tracingcommands} and \prm {parindent}).
247
248 \stopsubsection
249
250 \startsubsection[title={Internal parameter values, \type {set} and \type {get}}]
251
252 \topicindex{parameters+internal}
253
254 \libindex{set}
255 \libindex{get}
256
257 For all the parameters in this section, it is possible to access them directly
258 using their names as index in the \type {tex} table, or by using one of the
259 functions \type {tex.get} and \type {tex.set}.
260
261 The exact parameters and return values differ depending on the actual parameter,
262 and so does whether \type {tex.set} has any effect. For the parameters that {\em
263 can} be set, it is possible to use \type {global} as the first argument to \type
264 {tex.set}; this makes the assignment global instead of local.
265
266 \startfunctioncall
267 tex.set (["global",] <string> n, ...)
268 ... = tex.get (<string> n)
269 \stopfunctioncall
270
271 Glue is kind of special because there are five values involved. The return value
272 is a \nod {glue_spec} node but when you pass \type {false} as last argument to
273 \type {tex.get} you get the width of the glue and when you pass \type {true} you
274 get all five values. Otherwise you get a node which is a copy of the internal
275 value so you are responsible for its freeing at the \LUA\ end. When you set a
276 glue quantity you can either pass a \nod {glue_spec} or upto five numbers. If
277 you pass \type {true} to \type {get} you get 5 values returned for a glue and
278 when you pass \type {false} you only get the width returned.
279
280 \subsubsection{Integer parameters}
281
282 The integer parameters accept and return \LUA\ numbers. These are read|-|write:
283
284 \starttwocolumns
285 \starttyping
286 tex.adjdemerits
287 tex.binoppenalty
288 tex.brokenpenalty
289 tex.catcodetable
290 tex.clubpenalty
291 tex.day
292 tex.defaulthyphenchar
293 tex.defaultskewchar
294 tex.delimiterfactor
295 tex.displaywidowpenalty
296 tex.doublehyphendemerits
297 tex.endlinechar
298 tex.errorcontextlines
299 tex.escapechar
300 tex.exhyphenpenalty
301 tex.fam
302 tex.finalhyphendemerits
303 tex.floatingpenalty
304 tex.globaldefs
305 tex.hangafter
306 tex.hbadness
307 tex.holdinginserts
308 tex.hyphenpenalty
309 tex.interlinepenalty
310 tex.language
311 tex.lastlinefit
312 tex.lefthyphenmin
313 tex.linepenalty
314 tex.localbrokenpenalty
315 tex.localinterlinepenalty
316 tex.looseness
317 tex.mag
318 tex.maxdeadcycles
319 tex.month
320 tex.newlinechar
321 tex.outputpenalty
322 tex.pausing
323 tex.postdisplaypenalty
324 tex.predisplaydirection
325 tex.predisplaypenalty
326 tex.pretolerance
327 tex.relpenalty
328 tex.righthyphenmin
329 tex.savinghyphcodes
330 tex.savingvdiscards
331 tex.showboxbreadth
332 tex.showboxdepth
333 tex.time
334 tex.tolerance
335 tex.tracingassigns
336 tex.tracingcommands
337 tex.tracinggroups
338 tex.tracingifs
339 tex.tracinglostchars
340 tex.tracingmacros
341 tex.tracingnesting
342 tex.tracingonline
343 tex.tracingoutput
344 tex.tracingpages
345 tex.tracingparagraphs
346 tex.tracingrestores
347 tex.tracingscantokens
348 tex.tracingstats
349 tex.uchyph
350 tex.vbadness
351 tex.widowpenalty
352 tex.year
353 \stoptyping
354 \stoptwocolumns
355
356 These are read|-|only:
357
358 \startthreecolumns
359 \starttyping
360 tex.deadcycles
361 tex.insertpenalties
362 tex.parshape
363 tex.interlinepenalties
364 tex.clubpenalties
365 tex.widowpenalties
366 tex.displaywidowpenalties
367 tex.prevgraf
368 tex.spacefactor
369 \stoptyping
370 \stopthreecolumns
371
372 \subsubsection{Dimension parameters}
373
374 The dimension parameters accept \LUA\ numbers (signifying scaled points) or
375 strings (with included dimension). The result is always a number in scaled
376 points. These are read|-|write:
377
378 \startthreecolumns
379 \starttyping
380 tex.boxmaxdepth
381 tex.delimitershortfall
382 tex.displayindent
383 tex.displaywidth
384 tex.emergencystretch
385 tex.hangindent
386 tex.hfuzz
387 tex.hoffset
388 tex.hsize
389 tex.lineskiplimit
390 tex.mathsurround
391 tex.maxdepth
392 tex.nulldelimiterspace
393 tex.overfullrule
394 tex.pagebottomoffset
395 tex.pageheight
396 tex.pageleftoffset
397 tex.pagerightoffset
398 tex.pagetopoffset
399 tex.pagewidth
400 tex.parindent
401 tex.predisplaysize
402 tex.scriptspace
403 tex.splitmaxdepth
404 tex.vfuzz
405 tex.voffset
406 tex.vsize
407 tex.prevdepth
408 tex.prevgraf
409 tex.spacefactor
410 \stoptyping
411 \stopthreecolumns
412
413 These are read|-|only:
414
415 \startthreecolumns
416 \starttyping
417 tex.pagedepth
418 tex.pagefilllstretch
419 tex.pagefillstretch
420 tex.pagefilstretch
421 tex.pagegoal
422 tex.pageshrink
423 tex.pagestretch
424 tex.pagetotal
425 \stoptyping
426 \stopthreecolumns
427
428 Beware: as with all \LUA\ tables you can add values to them. So, the following is
429 valid:
430
431 \starttyping
432 tex.foo = 123
433 \stoptyping
434
435 When you access a \TEX\ parameter a look up takes place. For read||only variables
436 that means that you will get something back, but when you set them you create a
437 new entry in the table thereby making the original invisible.
438
439 There are a few special cases that we make an exception for: \type {prevdepth},
440 \type {prevgraf} and \type {spacefactor}. These normally are accessed via the
441 \type {tex.nest} table:
442
443 \starttyping
444 tex.nest[tex.nest.ptr].prevdepth = p
445 tex.nest[tex.nest.ptr].spacefactor = s
446 \stoptyping
447
448 However, the following also works:
449
450 \starttyping
451 tex.prevdepth = p
452 tex.spacefactor = s
453 \stoptyping
454
455 Keep in mind that when you mess with node lists directly at the \LUA\ end you
456 might need to update the top of the nesting stack's \type {prevdepth} explicitly
457 as there is no way \LUATEX\ can guess your intentions. By using the accessor in
458 the \type {tex} tables, you get and set the values at the top of the nesting
459 stack.
460
461 \subsubsection{Direction parameters}
462
463 The direction parameters are read|-|only and return a \LUA\ string.
464
465 \startthreecolumns
466 \starttyping
467 tex.bodydir
468 tex.mathdir
469 tex.pagedir
470 tex.pardir
471 tex.textdir
472 \stoptyping
473 \stopthreecolumns
474
475 \subsubsection{Glue parameters}
476
477 The glue parameters accept and return a userdata object that represents a \nod {glue_spec} node.
478
479 \startthreecolumns
480 \starttyping
481 tex.abovedisplayshortskip
482 tex.abovedisplayskip
483 tex.baselineskip
484 tex.belowdisplayshortskip
485 tex.belowdisplayskip
486 tex.leftskip
487 tex.lineskip
488 tex.parfillskip
489 tex.parskip
490 tex.rightskip
491 tex.spaceskip
492 tex.splittopskip
493 tex.tabskip
494 tex.topskip
495 tex.xspaceskip
496 \stoptyping
497 \stopthreecolumns
498
499 \subsubsection{Muglue parameters}
500
501 All muglue parameters are to be used read|-|only and return a \LUA\ string.
502
503 \startthreecolumns
504 \starttyping
505 tex.medmuskip
506 tex.thickmuskip
507 tex.thinmuskip
508 \stoptyping
509 \stopthreecolumns
510
511 \subsubsection{Tokenlist parameters}
512
513 The tokenlist parameters accept and return \LUA\ strings. \LUA\ strings are
514 converted to and from token lists using \prm {the} \prm {toks} style expansion:
515 all category codes are either space (10) or other (12). It follows that assigning
516 to some of these, like \quote {tex.output}, is actually useless, but it feels bad
517 to make exceptions in view of a coming extension that will accept full|-|blown
518 token strings.
519
520 \startthreecolumns
521 \starttyping
522 tex.errhelp
523 tex.everycr
524 tex.everydisplay
525 tex.everyeof
526 tex.everyhbox
527 tex.everyjob
528 tex.everymath
529 tex.everypar
530 tex.everyvbox
531 tex.output
532 \stoptyping
533 \stopthreecolumns
534
535 \stopsubsection
536
537 \startsubsection[title={Convert commands}]
538
539 \topicindex{convert commands}
540
541 All \quote {convert} commands are read|-|only and return a \LUA\ string. The
542 supported commands at this moment are:
543
544 \starttwocolumns
545 \starttyping
546 tex.eTeXVersion
547 tex.eTeXrevision
548 tex.formatname
549 tex.jobname
550 tex.luatexbanner
551 tex.luatexrevision
552 tex.fontname(number)
553 tex.uniformdeviate(number)
554 tex.number(number)
555 tex.romannumeral(number)
556 tex.fontidentifier(number)
557 \stoptyping
558 \stoptwocolumns
559
560 If you are wondering why this list looks haphazard; these are all the cases of
561 the \quote {convert} internal command that do not require an argument, as well as
562 the ones that require only a simple numeric value. The special (\LUA|-|only) case
563 of \type {tex.fontidentifier} returns the \type {csname} string that matches a
564 font id number (if there is one).
565
566 \stopsubsection
567
568 \startsubsection[title={Last item commands}]
569
570 \topicindex{last items}
571
572 All \quote {last item} commands are read|-|only and return a number. The
573 supported commands at this moment are:
574
575 \startthreecolumns
576 \starttyping
577 tex.lastpenalty
578 tex.lastkern
579 tex.lastskip
580 tex.lastnodetype
581 tex.inputlineno
582 tex.lastxpos
583 tex.lastypos
584 tex.randomseed
585 tex.luatexversion
586 tex.eTeXminorversion
587 tex.eTeXversion
588 tex.currentgrouplevel
589 tex.currentgrouptype
590 tex.currentiflevel
591 tex.currentiftype
592 tex.currentifbranch
593 \stoptyping
594 \stopthreecolumns
595
596 \stopsubsection
597
598 \startsubsection[title={Accessing registers: \type {set*}, \type {get*} and \type {is*}}]
599
600 \topicindex{attributes}
601 \topicindex{registers}
602
603 \libindex{attribute} \libindex{setattribute} \libindex{getattribute} \libindex{isattribute}
604 \libindex{count} \libindex{setcount} \libindex{getcount} \libindex{iscount}
605 \libindex{dimen} \libindex{setdimen} \libindex{getdimen} \libindex{isdimen}
606 \libindex{skip} \libindex{setskip} \libindex{getskip} \libindex{isskip}
607 \libindex{muskip} \libindex{setmuskip} \libindex{getmuskip} \libindex{ismuskip}
608 \libindex{glue} \libindex{setglue} \libindex{getglue} \libindex{isglue}
609 \libindex{muglue} \libindex{setmuglue} \libindex{getmuglue} \libindex{ismuglue}
610 \libindex{toks} \libindex{settoks} \libindex{gettoks} \libindex{istoks}
611 \libindex{box} \libindex{setbox} \libindex{getbox} \libindex{isbox}
612
613 \libindex{scantoks}
614
615 \libindex{getmark}
616
617 \TEX's attributes (\lpr {attribute}), counters (\prm {count}), dimensions (\prm
618 {dimen}), skips (\prm {skip}, \prm {muskip}) and token (\prm {toks}) registers
619 can be accessed and written to using two times five virtual sub|-|tables of the
620 \type {tex} table:
621
622 \startthreecolumns
623 \starttyping
624 tex.attribute
625 tex.count
626 tex.dimen
627 tex.skip
628 tex.glue
629 tex.muskip
630 tex.muglue
631 tex.toks
632 \stoptyping
633 \stopthreecolumns
634
635 It is possible to use the names of relevant \lpr {attributedef}, \prm {countdef},
636 \prm {dimendef}, \prm {skipdef}, or \prm {toksdef} control sequences as indices
637 to these tables:
638
639 \starttyping
640 tex.count.scratchcounter = 0
641 enormous = tex.dimen['maxdimen']
642 \stoptyping
643
644 In this case, \LUATEX\ looks up the value for you on the fly. You have to use a
645 valid \prm {countdef} (or \lpr {attributedef}, or \prm {dimendef}, or \prm
646 {skipdef}, or \prm {toksdef}), anything else will generate an error (the intent
647 is to eventually also allow \type {<chardef tokens>} and even macros that expand
648 into a number).
649
650 \startitemize
651
652 \startitem
653 The count registers accept and return \LUA\ numbers.
654 \stopitem
655
656 \startitem
657 The dimension registers accept \LUA\ numbers (in scaled points) or
658 strings (with an included absolute dimension; \type {em} and \type {ex}
659 and \type {px} are forbidden). The result is always a number in scaled
660 points.
661 \stopitem
662
663 \startitem
664 The token registers accept and return \LUA\ strings. \LUA\ strings are
665 converted to and from token lists using \prm {the} \prm {toks} style
666 expansion: all category codes are either space (10) or other (12).
667 \stopitem
668
669 \startitem
670 The skip registers accept and return \nod {glue_spec} userdata node
671 objects (see the description of the node interface elsewhere in this
672 manual).
673 \stopitem
674
675 \startitem
676 The glue registers are just skip registers but instead of userdata
677 are verbose.
678 \stopitem
679
680 \startitem
681 Like the counts, the attribute registers accept and return \LUA\ numbers.
682 \stopitem
683
684 \stopitemize
685
686 As an alternative to array addressing, there are also accessor functions defined
687 for all cases, for example, here is the set of possibilities for \prm {skip}
688 registers:
689
690 \startfunctioncall
691 tex.setskip (["global",] <number> n, <node> s)
692 tex.setskip (["global",] <string> s, <node> s)
693 <node> s = tex.getskip (<number> n)
694 <node> s = tex.getskip (<string> s)
695 \stopfunctioncall
696
697 We have similar setters for \type {count}, \type {dimen}, \type {muskip}, and
698 \type {toks}. Counters and dimen are represented by numbers, skips and muskips by
699 nodes, and toks by strings.
700
701 Again the glue variants are not using the \nod {glue_spec} userdata nodes. The
702 \type {setglue} function accepts upto 5 arguments: width, stretch, shrink,
703 stretch order and shrink order. If you pass no values or if a value is not a
704 number the corresponding property will become a zero. The \type {getglue}
705 function reports all properties, unless the second argument is \type {false} in
706 which care only the width is returned.
707
708 Here is an example using a threesome:
709
710 \startfunctioncall
711 local d = tex.getdimen("foo")
712 if tex.isdimen("bar") then
713 tex.setdimen("bar",d)
714 end
715 \stopfunctioncall
716
717 There are six extra skip (glue) related helpers:
718
719 \startfunctioncall
720 tex.setglue (["global"], <number> n,
721 width, stretch, shrink, stretch_order, shrink_order)
722 tex.setglue (["global"], <string> s,
723 width, stretch, shrink, stretch_order, shrink_order)
724 width, stretch, shrink, stretch_order, shrink_order =
725 tex.getglue (<number> n)
726 width, stretch, shrink, stretch_order, shrink_order =
727 tex.getglue (<string> s)
728 \stopfunctioncall
729
730 The other two are \type {tex.setmuglue} and \type {tex.getmuglue}.
731
732 There are such helpers for \type {dimen}, \type {count}, \type {skip}, \type
733 {muskip}, \type {box} and \type {attribute} registers but the glue ones
734 are special because they have to deal with more properties.
735
736 As with the general \type {get} and \type {set} function discussed before, for
737 the skip registers \type {getskip} returns a node and \type {getglue} returns
738 numbers, while \type {setskip} accepts a node and \type {setglue} expects upto five
739 numbers. Again, when you pass \type {false} as second argument to \type {getglue}
740 you only get the width returned. The same is true for the \type {mu} variants
741 \type {getmuskip}, \type {setmuskip}, \type {getmuskip} and\type {setmuskip}.
742
743 For tokens registers we have an alternative where a catcode table is specified:
744
745 \startfunctioncall
746 tex.scantoks(0,3,"$e=mc^2$")
747 tex.scantoks("global",0,"$\int\limits^1_2$")
748 \stopfunctioncall
749
750 In the function|-|based interface, it is possible to define values globally by
751 using the string \type {global} as the first function argument.
752
753 There is a dedicated getter for marks: \type {getmark} that takes two arguments.
754 The first argument is one of \type {top}, \type {bottom}, \type {first}, \type
755 {splitbottom} or \type {splitfirst}, and the second argument is a marks class
756 number. When no arguments are given the current maximum number of classes is
757 returned.
758
759 \stopsubsection
760
761 \startsubsection[title={Character code registers: \type {[get|set]*code[s]}}]
762
763 \topicindex{characters+codes}
764
765 \libindex{lccode} \libindex{setlccode} \libindex{getlccode}
766 \libindex{uccode} \libindex{setuccode} \libindex{getuccode}
767 \libindex{sfcode} \libindex{setsfcode} \libindex{getsfcode}
768 \libindex{catcode} \libindex{setcatcode} \libindex{getcatcode}
769 \libindex{mathcode} \libindex{setmathcode} \libindex{getmathcode}
770 \libindex{delcode} \libindex{setdelcode} \libindex{getdelcode}
771
772 \libindex{setdelcodes} \libindex{getdelcodes}
773 \libindex{setmathcodes} \libindex{getmathcodes}
774
775 \TEX's character code tables (\prm {lccode}, \prm {uccode}, \prm {sfcode}, \prm
776 {catcode}, \prm {mathcode}, \prm {delcode}) can be accessed and written to using
777 six virtual subtables of the \type {tex} table
778
779 \startthreecolumns
780 \starttyping
781 tex.lccode
782 tex.uccode
783 tex.sfcode
784 tex.catcode
785 tex.mathcode
786 tex.delcode
787 \stoptyping
788 \stopthreecolumns
789
790 The function call interfaces are roughly as above, but there are a few twists.
791 \type {sfcode}s are the simple ones:
792
793 \startfunctioncall
794 tex.setsfcode (["global",] <number> n, <number> s)
795 <number> s = tex.getsfcode (<number> n)
796 \stopfunctioncall
797
798 The function call interface for \type {lccode} and \type {uccode} additionally
799 allows you to set the associated sibling at the same time:
800
801 \startfunctioncall
802 tex.setlccode (["global"], <number> n, <number> lc)
803 tex.setlccode (["global"], <number> n, <number> lc, <number> uc)
804 <number> lc = tex.getlccode (<number> n)
805 tex.setuccode (["global"], <number> n, <number> uc)
806 tex.setuccode (["global"], <number> n, <number> uc, <number> lc)
807 <number> uc = tex.getuccode (<number> n)
808 \stopfunctioncall
809
810 The function call interface for \type {catcode} also allows you to specify a
811 category table to use on assignment or on query (default in both cases is the
812 current one):
813
814 \startfunctioncall
815 tex.setcatcode (["global"], <number> n, <number> c)
816 tex.setcatcode (["global"], <number> cattable, <number> n, <number> c)
817 <number> lc = tex.getcatcode (<number> n)
818 <number> lc = tex.getcatcode (<number> cattable, <number> n)
819 \stopfunctioncall
820
821 The interfaces for \type {delcode} and \type {mathcode} use small array tables to
822 set and retrieve values:
823
824 \startfunctioncall
825 tex.setmathcode (["global"], <number> n, <table> mval )
826 <table> mval = tex.getmathcode (<number> n)
827 tex.setdelcode (["global"], <number> n, <table> dval )
828 <table> dval = tex.getdelcode (<number> n)
829 \stopfunctioncall
830
831 Where the table for \type {mathcode} is an array of 3 numbers, like this:
832
833 \starttyping
834 {
835 <number> class,
836 <number> family,
837 <number> character
838 }
839 \stoptyping
840
841 And the table for \type {delcode} is an array with 4 numbers, like this:
842
843 \starttyping
844 {
845 <number> small_fam,
846 <number> small_char,
847 <number> large_fam,
848 <number> large_char
849 }
850 \stoptyping
851
852 You can also avoid the table:
853
854 \startfunctioncall
855 tex.setmathcode (["global"], <number> n, <number> class,
856 <number> family, <number> character)
857 class, family, char =
858 tex.getmathcodes (<number> n)
859 tex.setdelcode (["global"], <number> n, <number> smallfam,
860 <number> smallchar, <number> largefam, <number> largechar)
861 smallfam, smallchar, largefam, largechar =
862 tex.getdelcodes (<number> n)
863 \stopfunctioncall
864
865 Normally, the third and fourth values in a delimiter code assignment will be zero
866 according to \lpr {Udelcode} usage, but the returned table can have values there
867 (if the delimiter code was set using \prm {delcode}, for example). Unset \type
868 {delcode}'s can be recognized because \type {dval[1]} is $-1$.
869
870 \stopsubsection
871
872 \startsubsection[title={Box registers: \type {[get|set]box}}]
873
874 \topicindex{registers}
875 \topicindex{boxes}
876
877 \libindex{box}
878 \libindex{setbox} \libindex{getbox}
879
880 It is possible to set and query actual boxes, coming for instance from \prm
881 {hbox}, \prm {vbox} or \prm {vtop}, using the node interface as defined in the
882 \type {node} library:
883
884 \starttyping
885 tex.box
886 \stoptyping
887
888 for array access, or
889
890 \starttyping
891 tex.setbox(["global",] <number> n, <node> s)
892 tex.setbox(["global",] <string> cs, <node> s)
893 <node> n = tex.getbox(<number> n)
894 <node> n = tex.getbox(<string> cs)
895 \stoptyping
896
897 for function|-|based access. In the function-based interface, it is possible to
898 define values globally by using the string \type {global} as the first function
899 argument.
900
901 Be warned that an assignment like
902
903 \starttyping
904 tex.box[0] = tex.box[2]
905 \stoptyping
906
907 does not copy the node list, it just duplicates a node pointer. If \type {\box2}
908 will be cleared by \TEX\ commands later on, the contents of \type {\box0} becomes
909 invalid as well. To prevent this from happening, always use \type
910 {node.copy_list} unless you are assigning to a temporary variable:
911
912 \starttyping
913 tex.box[0] = node.copy_list(tex.box[2])
914 \stoptyping
915
916 \stopsubsection
917
918 \startsubsection[title={Reusing boxes: \type {[use|save]boxresource} and \type {getboxresourcedimensions}}]
919
920 \topicindex{boxes+reuse}
921
922 \libindex{useboxresource}
923 \libindex{saveboxresource}
924 \libindex{getboxresourcedimensions}
925
926 The following function will register a box for reuse (this is modelled after so
927 called xforms in \PDF). You can (re)use the box with \lpr {useboxresource} or
928 by creating a rule node with subtype~2.
929
930 \starttyping
931 local index = tex.saveboxresource(n,attributes,resources,immediate,type,margin)
932 \stoptyping
933
934 The optional second and third arguments are strings, the fourth is a boolean. The
935 fifth argument is a type. When set to non|-|zero the \type {/Type} entry is
936 omitted. A value of 1 or 3 still writes a \type {/BBox}, while 2 or 3 will write
937 a \type {/Matrix}. The sixth argument is the (virtual) margin that extends beyond
938 the effective boundingbox as seen by \TEX. Instead of a box number one can also
939 pass a \type {[h|v]list} node.
940
941 You can generate the reference (a rule type) with:
942
943 \starttyping
944 local reused = tex.useboxresource(n,wd,ht,dp)
945 \stoptyping
946
947 The dimensions are optional and the final ones are returned as extra values. The
948 following is just a bonus (no dimensions returned means that the resource is
949 unknown):
950
951 \starttyping
952 local w, h, d, m = tex.getboxresourcedimensions(n)
953 \stoptyping
954
955 This returns the width, height, depth and margin of the resource.
956
957 \stopsubsection
958
959 \startsubsection[title={\type {triggerbuildpage}}]
960
961 \topicindex{pages}
962
963 \libindex{triggerbuildpage}
964
965 You should not expect to much from the \type {triggerbuildpage} helpers because
966 often \TEX\ doesn't do much if it thinks nothing has to be done, but it might be
967 useful for some applications. It just does as it says it calls the internal
968 function that build a page, given that there is something to build.
969
970 \stopsubsection
971
972 \startsubsection[title={\type {splitbox}}]
973
974 \topicindex{boxes+split}
975
976 \libindex{splitbox}
977
978 You can split a box:
979
980 \starttyping
981 local vlist = tex.splitbox(n,height,mode)
982 \stoptyping
983
984 The remainder is kept in the original box and a packaged vlist is returned. This
985 operation is comparable to the \prm {vsplit} operation. The mode can be \type
986 {additional} or \type {exactly} and concerns the split off box.
987
988 \stopsubsection
989
990 \startsubsection[title={Accessing math parameters: \type {[get|set]math}}]
991
992 \topicindex{math+parameters}
993 \topicindex{parameters+math}
994
995 \libindex{setmath}
996 \libindex{getmath}
997
998 It is possible to set and query the internal math parameters using:
999
1000 \startfunctioncall
1001 tex.setmath(["global",] <string> n, <string> t, <number> n)
1002 <number> n = tex.getmath(<string> n, <string> t)
1003 \stopfunctioncall
1004
1005 As before an optional first parameter \type {global} indicates a global
1006 assignment.
1007
1008 The first string is the parameter name minus the leading \quote {Umath}, and the
1009 second string is the style name minus the trailing \quote {style}. Just to be
1010 complete, the values for the math parameter name are:
1011
1012 \starttyping
1013 quad axis operatorsize
1014 overbarkern overbarrule overbarvgap
1015 underbarkern underbarrule underbarvgap
1016 radicalkern radicalrule radicalvgap
1017 radicaldegreebefore radicaldegreeafter radicaldegreeraise
1018 stackvgap stacknumup stackdenomdown
1019 fractionrule fractionnumvgap fractionnumup
1020 fractiondenomvgap fractiondenomdown fractiondelsize
1021 limitabovevgap limitabovebgap limitabovekern
1022 limitbelowvgap limitbelowbgap limitbelowkern
1023 underdelimitervgap underdelimiterbgap
1024 overdelimitervgap overdelimiterbgap
1025 subshiftdrop supshiftdrop subshiftdown
1026 subsupshiftdown subtopmax supshiftup
1027 supbottommin supsubbottommax subsupvgap
1028 spaceafterscript connectoroverlapmin
1029 ordordspacing ordopspacing ordbinspacing ordrelspacing
1030 ordopenspacing ordclosespacing ordpunctspacing ordinnerspacing
1031 opordspacing opopspacing opbinspacing oprelspacing
1032 opopenspacing opclosespacing oppunctspacing opinnerspacing
1033 binordspacing binopspacing binbinspacing binrelspacing
1034 binopenspacing binclosespacing binpunctspacing bininnerspacing
1035 relordspacing relopspacing relbinspacing relrelspacing
1036 relopenspacing relclosespacing relpunctspacing relinnerspacing
1037 openordspacing openopspacing openbinspacing openrelspacing
1038 openopenspacing openclosespacing openpunctspacing openinnerspacing
1039 closeordspacing closeopspacing closebinspacing closerelspacing
1040 closeopenspacing closeclosespacing closepunctspacing closeinnerspacing
1041 punctordspacing punctopspacing punctbinspacing punctrelspacing
1042 punctopenspacing punctclosespacing punctpunctspacing punctinnerspacing
1043 innerordspacing inneropspacing innerbinspacing innerrelspacing
1044 inneropenspacing innerclosespacing innerpunctspacing innerinnerspacing
1045 \stoptyping
1046
1047 The values for the style parameter are:
1048
1049 \starttyping
1050 display crampeddisplay
1051 text crampedtext
1052 script crampedscript
1053 scriptscript crampedscriptscript
1054 \stoptyping
1055
1056 The value is either a number (representing a dimension or number) or a glue spec
1057 node representing a muskip for \type {ordordspacing} and similar spacing
1058 parameters.
1059
1060 \stopsubsection
1061
1062 \startsubsection[title={Special list heads: \type {[get|set]list}}]
1063
1064 \topicindex{lists}
1065
1066 \libindex{lists}
1067 \libindex{setlist}
1068 \libindex{getlist}
1069
1070 The virtual table \type {tex.lists} contains the set of internal registers that
1071 keep track of building page lists.
1072
1073 \starttabulate[|l|p|]
1074 \DB field \BC explanation \NC \NR
1075 \TB
1076 \NC \type{page_ins_head} \NC circular list of pending insertions \NC \NR
1077 \NC \type{contrib_head} \NC the recent contributions \NC \NR
1078 \NC \type{page_head} \NC the current page content \NC \NR
1079 %NC \type{temp_head} \NC \NC \NR
1080 \NC \type{hold_head} \NC used for held-over items for next page \NC \NR
1081 \NC \type{adjust_head} \NC head of the current \prm {vadjust} list \NC \NR
1082 \NC \type{pre_adjust_head} \NC head of the current \type {\vadjust pre} list \NC \NR
1083 %NC \type{align_head} \NC \NC \NR
1084 \NC \type{page_discards_head} \NC head of the discarded items of a page break \NC \NR
1085 \NC \type{split_discards_head} \NC head of the discarded items in a vsplit \NC \NR
1086 \LL
1087 \stoptabulate
1088
1089 The getter and setter functions are \type {getlist} and \type {setlist}. You have
1090 to be careful with what you set as \TEX\ can have expectations with regards to
1091 how a list is constructed or in what state it is.
1092
1093 \stopsubsection
1094
1095 \startsubsection[title={Semantic nest levels: \type {getnest} and \type {ptr}}]
1096
1097 \topicindex{nesting}
1098
1099 \libindex{nest}
1100 \libindex{ptr}
1101 %libindex{setnest} % only a message
1102 \libindex{getnest}
1103
1104 The virtual table \type {nest} contains the currently active semantic nesting
1105 state. It has two main parts: a zero-based array of userdata for the semantic
1106 nest itself, and the numerical value \type {ptr}, which gives the highest
1107 available index. Neither the array items in \type {nest[]} nor \type {ptr} can be
1108 assigned to (as this would confuse the typesetting engine beyond repair), but you
1109 can assign to the individual values inside the array items, e.g.\ \type
1110 {tex.nest[tex.nest.ptr].prevdepth}.
1111
1112 \type {tex.nest[tex.nest.ptr]} is the current nest state, \type {nest[0]} the
1113 outermost (main vertical list) level. The getter function is \type {getnest}. You
1114 can pass a number (which gives you a list), nothing or \type {top}, which returns
1115 the topmost list, or the string \type {ptr} which gives you the index of the
1116 topmost list.
1117
1118 The known fields are:
1119
1120 \starttabulate[|l|l|l|p|]
1121 \DB key \BC type \BC modes \BC explanation \NC \NR
1122 \TB
1123 \NC \type{mode} \NC number \NC all \NC the meaning of these numbers depends on the engine
1124 and sometimes even the version; you can use \typ
1125 {tex.getmodevalues()} to get the mapping: positive
1126 values signal vertical, horizontal and math mode,
1127 while negative values indicate inner and inline
1128 variants \NC \NR
1129 \NC \type{modeline} \NC number \NC all \NC source input line where this mode was entered in,
1130 negative inside the output routine \NC \NR
1131 \NC \type{head} \NC node \NC all \NC the head of the current list \NC \NR
1132 \NC \type{tail} \NC node \NC all \NC the tail of the current list \NC \NR
1133 \NC \type{prevgraf} \NC number \NC vmode \NC number of lines in the previous paragraph \NC \NR
1134 \NC \type{prevdepth} \NC number \NC vmode \NC depth of the previous paragraph \NC \NR
1135 \NC \type{spacefactor} \NC number \NC hmode \NC the current space factor \NC \NR
1136 \NC \type{dirs} \NC node \NC hmode \NC used for temporary storage by the line break algorithm\NC \NR
1137 \NC \type{noad} \NC node \NC mmode \NC used for temporary storage of a pending fraction numerator,
1138 for \prm {over} etc. \NC \NR
1139 \NC \type{delimptr} \NC node \NC mmode \NC used for temporary storage of the previous math delimiter,
1140 for \prm {middle} \NC \NR
1141 \NC \type{mathdir} \NC boolean \NC mmode \NC true when during math processing the \lpr {mathdir} is not
1142 the same as the surrounding \lpr {textdir} \NC \NR
1143 \NC \type{mathstyle} \NC number \NC mmode \NC the current \lpr {mathstyle} \NC \NR
1144 \LL
1145 \stoptabulate
1146
1147 \stopsubsection
1148
1149 \startsubsection[reference=sec:luaprint,title={Print functions}]
1150
1151 \topicindex{printing}
1152
1153 The \type {tex} table also contains the three print functions that are the major
1154 interface from \LUA\ scripting to \TEX. The arguments to these three functions
1155 are all stored in an in|-|memory virtual file that is fed to the \TEX\ scanner as
1156 the result of the expansion of \prm {directlua}.
1157
1158 The total amount of returnable text from a \prm {directlua} command is only
1159 limited by available system \RAM. However, each separate printed string has to
1160 fit completely in \TEX's input buffer. The result of using these functions from
1161 inside callbacks is undefined at the moment.
1162
1163 \subsubsection{\type {print}}
1164
1165 \libindex{print}
1166
1167 \startfunctioncall
1168 tex.print(<string> s, ...)
1169 tex.print(<number> n, <string> s, ...)
1170 tex.print(<table> t)
1171 tex.print(<number> n, <table> t)
1172 \stopfunctioncall
1173
1174 Each string argument is treated by \TEX\ as a separate input line. If there is a
1175 table argument instead of a list of strings, this has to be a consecutive array
1176 of strings to print (the first non-string value will stop the printing process).
1177
1178 The optional parameter can be used to print the strings using the catcode regime
1179 defined by \lpr {catcodetable}~\type {n}. If \type {n} is $-1$, the currently
1180 active catcode regime is used. If \type {n} is $-2$, the resulting catcodes are
1181 the result of \prm {the} \prm {toks}: all category codes are 12 (other) except for
1182 the space character, that has category code 10 (space). Otherwise, if \type {n}
1183 is not a valid catcode table, then it is ignored, and the currently active
1184 catcode regime is used instead.
1185
1186 The very last string of the very last \type {tex.print} command in a \prm
1187 {directlua} will not have the \prm {endlinechar} appended, all others do.
1188
1189 \subsubsection{\type {sprint}}
1190
1191 \libindex{sprint}
1192
1193 \startfunctioncall
1194 tex.sprint(<string> s, ...)
1195 tex.sprint(<number> n, <string> s, ...)
1196 tex.sprint(<table> t)
1197 tex.sprint(<number> n, <table> t)
1198 \stopfunctioncall
1199
1200 Each string argument is treated by \TEX\ as a special kind of input line that
1201 makes it suitable for use as a partial line input mechanism:
1202
1203 \startitemize[packed]
1204 \startitem
1205 \TEX\ does not switch to the \quote {new line} state, so that leading spaces
1206 are not ignored.
1207 \stopitem
1208 \startitem
1209 No \prm {endlinechar} is inserted.
1210 \stopitem
1211 \startitem
1212 Trailing spaces are not removed. Note that this does not prevent \TEX\ itself
1213 from eating spaces as result of interpreting the line. For example, in
1214
1215 \starttyping
1216 before\directlua{tex.sprint("\\relax")tex.sprint(" inbetween")}after
1217 \stoptyping
1218
1219 the space before \type {in between} will be gobbled as a result of the \quote
1220 {normal} scanning of \prm {relax}.
1221 \stopitem
1222 \stopitemize
1223
1224 If there is a table argument instead of a list of strings, this has to be a
1225 consecutive array of strings to print (the first non-string value will stop the
1226 printing process).
1227
1228 The optional argument sets the catcode regime, as with \type {tex.print}. This
1229 influences the string arguments (or numbers turned into strings).
1230
1231 Although this needs to be used with care, you can also pass token or node
1232 userdata objects. These get injected into the stream. Tokens had best be valid
1233 tokens, while nodes need to be around when they get injected. Therefore it is
1234 important to realize the following:
1235
1236 \startitemize
1237 \startitem
1238 When you inject a token, you need to pass a valid token userdata object. This
1239 object will be collected by \LUA\ when it no longer is referenced. When it gets
1240 printed to \TEX\ the token itself gets copied so there is no interference with the
1241 \LUA\ garbage collection. You manage the object yourself. Because tokens are
1242 actually just numbers, there is no real extra overhead at the \TEX\ end.
1243 \stopitem
1244 \startitem
1245 When you inject a node, you need to pass a valid node userdata object. The
1246 node related to the object will not be collected by \LUA\ when it no longer
1247 is referenced. It lives on at the \TEX\ end in its own memory space. When it
1248 gets printed to \TEX\ the node reference is used assuming that node stays
1249 around. There is no \LUA\ garbage collection involved. Again, you manage the
1250 object yourself. The node itself is freed when \TEX\ is done with it.
1251 \stopitem
1252 \stopitemize
1253
1254 If you consider the last remark you might realize that we have a problem when a
1255 printed mix of strings, tokens and nodes is reused. Inside \TEX\ the sequence
1256 becomes a linked list of input buffers. So, \type {"123"} or \type {"\foo{123}"}
1257 gets read and parsed on the fly, while \typ {<token userdata>} already is
1258 tokenized and effectively is a token list now. A \typ {<node userdata>} is also
1259 tokenized into a token list but it has a reference to a real node. Normally this
1260 goes fine. But now assume that you store the whole lot in a macro: in that case
1261 the tokenized node can be flushed many times. But, after the first such flush the
1262 node is used and its memory freed. You can prevent this by using copies which is
1263 controlled by setting \lpr {luacopyinputnodes} to a non|-|zero value. This is one
1264 of these fuzzy areas you have to live with if you really mess with these low
1265 level issues.
1266
1267 \subsubsection{\type {tprint}}
1268
1269 \libindex{tprint}
1270
1271 \startfunctioncall
1272 tex.tprint({<number> n, <string> s, ...}, {...})
1273 \stopfunctioncall
1274
1275 This function is basically a shortcut for repeated calls to \type
1276 {tex.sprint(<number> n, <string> s, ...)}, once for each of the supplied argument
1277 tables.
1278
1279 \subsubsection{\type {cprint}}
1280
1281 \libindex{cprint}
1282
1283 This function takes a number indicating the to be used catcode, plus either a
1284 table of strings or an argument list of strings that will be pushed into the
1285 input stream.
1286
1287 \startfunctioncall
1288 tex.cprint( 1," 1: $&{\\foo}") tex.print("\\par") -- a lot of \bgroup s
1289 tex.cprint( 2," 2: $&{\\foo}") tex.print("\\par") -- matching \egroup s
1290 tex.cprint( 9," 9: $&{\\foo}") tex.print("\\par") -- all get ignored
1291 tex.cprint(10,"10: $&{\\foo}") tex.print("\\par") -- all become spaces
1292 tex.cprint(11,"11: $&{\\foo}") tex.print("\\par") -- letters
1293 tex.cprint(12,"12: $&{\\foo}") tex.print("\\par") -- other characters
1294 tex.cprint(14,"12: $&{\\foo}") tex.print("\\par") -- comment triggers
1295 \stopfunctioncall
1296
1297 % \subsubsection{\type {write}, \type {twrite}, \type {nwrite}}
1298 \subsubsection{\type {write}}
1299
1300 \libindex{write}
1301 % \libindex{twrite}
1302 % \libindex{nwrite}
1303
1304 \startfunctioncall
1305 tex.write(<string> s, ...)
1306 tex.write(<table> t)
1307 \stopfunctioncall
1308
1309 Each string argument is treated by \TEX\ as a special kind of input line that
1310 makes it suitable for use as a quick way to dump information:
1311
1312 \startitemize
1313 \item All catcodes on that line are either \quote{space} (for '~') or \quote
1314 {character} (for all others).
1315 \item There is no \prm {endlinechar} appended.
1316 \stopitemize
1317
1318 If there is a table argument instead of a list of strings, this has to be a
1319 consecutive array of strings to print (the first non-string value will stop the
1320 printing process).
1321
1322 % The functions \type {twrite} and \type {nwrite} can be used to write a token or
1323 % node back to \TEX\, possibly intermixed with regular strings that will be
1324 % tokenized. You have to make sure that you pass the right data because sometimes
1325 % \TEX\ has expectations that need to be met.
1326
1327 \stopsubsection
1328
1329 \startsubsection[title={Helper functions}]
1330
1331 \subsubsection{\type {round}}
1332
1333 \topicindex {helpers}
1334
1335 \libindex{round}
1336
1337 \startfunctioncall
1338 <number> n = tex.round(<number> o)
1339 \stopfunctioncall
1340
1341 Rounds \LUA\ number \type {o}, and returns a number that is in the range of a
1342 valid \TEX\ register value. If the number starts out of range, it generates a
1343 \quote {number too big} error as well.
1344
1345 \subsubsection{\type {scale}}
1346
1347 \libindex{scale}
1348
1349 \startfunctioncall
1350 <number> n = tex.scale(<number> o, <number> delta)
1351 <table> n = tex.scale(table o, <number> delta)
1352 \stopfunctioncall
1353
1354 Multiplies the \LUA\ numbers \type {o} and \nod {delta}, and returns a rounded
1355 number that is in the range of a valid \TEX\ register value. In the table
1356 version, it creates a copy of the table with all numeric top||level values scaled
1357 in that manner. If the multiplied number(s) are of range, it generates
1358 \quote{number too big} error(s) as well.
1359
1360 Note: the precision of the output of this function will depend on your computer's
1361 architecture and operating system, so use with care! An interface to \LUATEX's
1362 internal, 100\% portable scale function will be added at a later date.
1363
1364 \subsubsection{\type {number} and \type {romannumeral}}
1365
1366 \libindex{number}
1367 \libindex{romannumeral}
1368
1369 These are the companions to the primitives \prm {number} and \prm
1370 {romannumeral}. They can be used like:
1371
1372 \startfunctioncall
1373 tex.print(tex.romannumeral(123))
1374 \stopfunctioncall
1375
1376 \subsubsection{\type {fontidentifier} and \type {fontname}}
1377
1378 \libindex{fontidentifier}
1379 \libindex{fontname}
1380
1381 The first one returns the name only, the second one reports the size too.
1382
1383 \startfunctioncall
1384 tex.print(tex.fontidentifier(1))
1385 tex.print(tex.fontname(1))
1386 \stopfunctioncall
1387
1388 \subsubsection{\type {sp}}
1389
1390 \libindex{sp}
1391
1392 \startfunctioncall
1393 <number> n = tex.sp(<number> o)
1394 <number> n = tex.sp(<string> s)
1395 \stopfunctioncall
1396
1397 Converts the number \type {o} or a string \type {s} that represents an explicit
1398 dimension into an integer number of scaled points.
1399
1400 For parsing the string, the same scanning and conversion rules are used that
1401 \LUATEX\ would use if it was scanning a dimension specifier in its \TEX|-|like
1402 input language (this includes generating errors for bad values), expect for the
1403 following:
1404
1405 \startitemize[n]
1406 \startitem
1407 only explicit values are allowed, control sequences are not handled
1408 \stopitem
1409 \startitem
1410 infinite dimension units (\type {fil...}) are forbidden
1411 \stopitem
1412 \startitem
1413 \type {mu} units do not generate an error (but may not be useful either)
1414 \stopitem
1415 \stopitemize
1416
1417 %\subsubsection{\type {tex.getlinenumber} and \type {tex.setlinenumber}}
1418 %
1419 %\libindex{getlinenumber}
1420 %\libindex{setlinenumber}
1421 %
1422 %You can mess with the current line number:
1423 %
1424 %\startfunctioncall
1425 %local n = tex.getlinenumber()
1426 %tex.setlinenumber(n+10)
1427 %\stopfunctioncall
1428 %
1429 %which can be shortcut to:
1430 %
1431 %\startfunctioncall
1432 %tex.setlinenumber(10,true)
1433 %\stopfunctioncall
1434 %
1435 %This might be handy when you have a callback that read numbers from a file and
1436 %combines them in one line (in which case an error message probably has to refer
1437 %to the original line). Interference with \TEX's internal handling of numbers is
1438 %of course possible.
1439
1440 \subsubsection{\type {error} and \type {show_context}}
1441
1442 \topicindex{errors}
1443
1444 \libindex{error}
1445 \libindex{show_context}
1446
1447 \startfunctioncall
1448 tex.error(<string> s)
1449 tex.error(<string> s, <table> help)
1450 \stopfunctioncall
1451
1452 This creates an error somewhat like the combination of \prm {errhelp} and \prm
1453 {errmessage} would. During this error, deletions are disabled.
1454
1455 The array part of the \type {help} table has to contain strings, one for each
1456 line of error help.
1457
1458 In case of an error the \type {show_context} function will show the current
1459 context where we're at (in the expansion).
1460
1461 \subsubsection{\type {run}, \type {finish}}
1462
1463 \libindex{run}
1464 \libindex{finish}
1465
1466 These two functions start the interpretations and force its end. A runs normally
1467 boils down to \TEX\ entering the so called main loop. A token is fetched and
1468 depending on it current meaning some actions takes place. Sometimes that actions
1469 comes immediately, sometimes more scanning is needed. Quite often tokens get
1470 pushed back into the input. This all means that the \TEX\ scanner is constantly
1471 pushing and popping input states, but in the end after all the action is done
1472 returns to the main loop.
1473
1474 \subsubsection{\type {runtoks}}
1475
1476 Because of the fact that \TEX\ is in a complex dance of expanding, dealing with
1477 fonts, typesetting paragraphs, messing around with boxes, building pages, and so
1478 on, you cannot easily run a nested \TEX\ run (read nested main loop). However,
1479 there is an option to force a local run with \type {runtoks}. The content of the
1480 given token list register gets expanded locally after which we return to where we
1481 triggered this expansion, at the \LUA\ end. Instead a function can get passed
1482 that does some work. You have to make sure that at the end \TEX\ is in a sane
1483 state and this is not always trivial. A more complex mechanism would complicate
1484 \TEX\ itself (and probably also harm performance) so this simple local expansion
1485 loop has to do.
1486
1487 \startfunctioncall
1488 tex.runtoks(<token register>)
1489 tex.runtoks(<lua function>)
1490 \stopfunctioncall
1491
1492 When the \prm {tracingnesting} parameter is set to a value larger than~2 some
1493 information is reported about the state of the local loop.
1494
1495 This function has two optional arguments in case a token register is passed:
1496
1497 \startfunctioncall
1498 tex.runtoks(<token register>,force,grouped)
1499 \stopfunctioncall
1500
1501 Inside for instance an \type {\edef} the \type {runtoks} function behaves (at
1502 least tries to) like it were an \type {\the}. This prevents unwanted side
1503 effects: normally in such an definition tokens remain tokens and (for instance)
1504 characters don't become nodes. With the second argument you can force the local
1505 main loop, no matter what. The third argument adds a level of grouping.
1506
1507 You can quit the local loop with \type {\endlocalcontrol} or from the \LUA\ end
1508 with \type {tex.quittoks}. In that case you end one level up! Of course in the
1509 end that can mean that you arrive at the main level in which case an extra end
1510 will trigger a redundancy warning (not an abort!).
1511
1512 \subsubsection{\type {forcehmode}}
1513
1514 \libindex{forcehmode}
1515
1516 An example of a (possible error triggering) complication is that \TEX\ expects to
1517 be in some state, say horizontal mode, and you have to make sure it is when you
1518 start feeding back something from \LUA\ into \TEX. Normally a user will not run
1519 into issues but when you start writing tokens or nodes or have a nested run there
1520 can be situations that you need to run \type {forcehmode}. There is no recipe for
1521 this and intercepting possible cases would weaken \LUATEX's flexibility.
1522
1523 \subsubsection{\type {hashtokens}}
1524
1525 \libindex{hashtokens}
1526
1527 \topicindex{hash}
1528
1529 \startfunctioncall
1530 for i,v in pairs (tex.hashtokens()) do ... end
1531 \stopfunctioncall
1532
1533 Returns a list of names. This can be useful for debugging, but note that this
1534 also reports control sequences that may be unreachable at this moment due to
1535 local redefinitions: it is strictly a dump of the hash table. You can use \type
1536 {token.create} to inspect properties, for instance when the \type {command} key
1537 in a created table equals \type {123}, you have the \type {cmdname} value \type
1538 {undefined_cs}.
1539
1540 \subsubsection{\type {definefont}}
1541
1542 \topicindex{fonts+defining}
1543
1544 \libindex{definefont}
1545
1546 \startfunctioncall
1547 tex.definefont(<string> csname, <number> fontid)
1548 tex.definefont(<boolean> global, <string> csname, <number> fontid)
1549 \stopfunctioncall
1550
1551 Associates \type {csname} with the internal font number \type {fontid}. The
1552 definition is global if (and only if) \type {global} is specified and true (the
1553 setting of \type {globaldefs} is not taken into account).
1554
1555 \stopsubsection
1556
1557 \startsubsection[reference=luaprimitives,title={Functions for dealing with primitives}]
1558
1559 \subsubsection{\type {enableprimitives}}
1560
1561 \libindex{enableprimitives}
1562
1563 \topicindex{initialization}
1564 \topicindex{primitives}
1565
1566 \startfunctioncall
1567 tex.enableprimitives(<string> prefix, <table> primitive names)
1568 \stopfunctioncall
1569
1570 This function accepts a prefix string and an array of primitive names. For each
1571 combination of \quote {prefix} and \quote {name}, the \type
1572 {tex.enableprimitives} first verifies that \quote {name} is an actual primitive
1573 (it must be returned by one of the \type {tex.extraprimitives} calls explained
1574 below, or part of \TEX82, or \prm {directlua}). If it is not, \type
1575 {tex.enableprimitives} does nothing and skips to the next pair.
1576
1577 But if it is, then it will construct a csname variable by concatenating the
1578 \quote {prefix} and \quote {name}, unless the \quote {prefix} is already the
1579 actual prefix of \quote {name}. In the latter case, it will discard the \quote
1580 {prefix}, and just use \quote {name}.
1581
1582 Then it will check for the existence of the constructed csname. If the csname is
1583 currently undefined (note: that is not the same as \prm {relax}), it will
1584 globally define the csname to have the meaning: run code belonging to the
1585 primitive \quote {name}. If for some reason the csname is already defined, it
1586 does nothing and tries the next pair.
1587
1588 An example:
1589
1590 \starttyping
1591 tex.enableprimitives('LuaTeX', {'formatname'})
1592 \stoptyping
1593
1594 will define \type {\LuaTeXformatname} with the same intrinsic meaning as the
1595 documented primitive \lpr {formatname}, provided that the control sequences \type
1596 {\LuaTeXformatname} is currently undefined.
1597
1598 When \LUATEX\ is run with \type {--ini} only the \TEX82 primitives and \prm
1599 {directlua} are available, so no extra primitives {\bf at all}.
1600
1601 If you want to have all the new functionality available using their default
1602 names, as it is now, you will have to add
1603
1604 \starttyping
1605 \ifx\directlua\undefined \else
1606 \directlua {tex.enableprimitives('',tex.extraprimitives ())}
1607 \fi
1608 \stoptyping
1609
1610 near the beginning of your format generation file. Or you can choose different
1611 prefixes for different subsets, as you see fit.
1612
1613 Calling some form of \type {tex.enableprimitives} is highly important though,
1614 because if you do not, you will end up with a \TEX82-lookalike that can run \LUA\
1615 code but not do much else. The defined csnames are (of course) saved in the
1616 format and will be available at runtime.
1617
1618 \subsubsection{\type {extraprimitives}}
1619
1620 \libindex{extraprimitives}
1621
1622 \startfunctioncall
1623 <table> t = tex.extraprimitives(<string> s, ...)
1624 \stopfunctioncall
1625
1626 This function returns a list of the primitives that originate from the engine(s)
1627 given by the requested string value(s). The possible values and their (current)
1628 return values are given in the following table. In addition the somewhat special
1629 primitives \quote{\tex{ }}, \quote{\tex {/}} and \quote{\type {-}} are defined.
1630
1631 \startluacode
1632 function document.showprimitives(tag)
1633 local t = tex.extraprimitives(tag)
1634 table.sort(t)
1635 for i=1,#t do
1636 local v = t[i]
1637 if v ~= ' ' and v ~= "/" and v ~= "-" then
1638 context.type(v)
1639 context.space()
1640 end
1641 end
1642 end
1643 \stopluacode
1644
1645 \starttabulate[|l|pl|]
1646 \DB name \BC values \NC \NR
1647 \TB
1648 \NC tex \NC \ctxlua{document.showprimitives('tex') } \NC \NR
1649 \NC core \NC \ctxlua{document.showprimitives('core') } \NC \NR
1650 \NC etex \NC \ctxlua{document.showprimitives('etex') } \NC \NR
1651 \NC luatex \NC \ctxlua{document.showprimitives('luatex') } \NC \NR
1652 \LL
1653 \stoptabulate
1654
1655 Note that \type {luatex} does not contain \type {directlua}, as that is
1656 considered to be a core primitive, along with all the \TEX82 primitives, so it is
1657 part of the list that is returned from \type {'core'}.
1658
1659 Running \type {tex.extraprimitives} will give you the complete list of
1660 primitives \type {-ini} startup. It is exactly equivalent to \type
1661 {tex.extraprimitives("etex","luatex")}.
1662
1663 \subsubsection{\type {primitives}}
1664
1665 \libindex{primitives}
1666
1667 \startfunctioncall
1668 <table> t = tex.primitives()
1669 \stopfunctioncall
1670
1671 This function returns a list of all primitives that \LUATEX\ knows about.
1672
1673 \stopsubsection
1674
1675 \startsubsection[title={Core functionality interfaces}]
1676
1677 \subsubsection{\type {badness}}
1678
1679 \libindex{badness}
1680
1681 \startfunctioncall
1682 <number> b = tex.badness(<number> t, <number> s)
1683 \stopfunctioncall
1684
1685 This helper function is useful during linebreak calculations. \type {t} and \type
1686 {s} are scaled values; the function returns the badness for when total \type {t}
1687 is supposed to be made from amounts that sum to \type {s}. The returned number is
1688 a reasonable approximation of \mathematics {100(t/s)^3};
1689
1690 \subsubsection{\type {tex.resetparagraph}}
1691
1692 \topicindex {paragraphs+reset}
1693
1694 \libindex{resetparagraph}
1695
1696 This function resets the parameters that \TEX\ normally resets when a new paragraph
1697 is seen.
1698
1699 \subsubsection{\type {linebreak}}
1700
1701 \topicindex {linebreaks}
1702
1703 \libindex{linebreak}
1704
1705 \startfunctioncall
1706 local <node> nodelist, <table> info =
1707 tex.linebreak(<node> listhead, <table> parameters)
1708 \stopfunctioncall
1709
1710 The understood parameters are as follows:
1711
1712 \starttabulate[|l|l|p|]
1713 \DB name \BC type \BC explanation \NC \NR
1714 \TB
1715 \NC \type{pardir} \NC string \NC \NC \NR
1716 \NC \type{pretolerance} \NC number \NC \NC \NR
1717 \NC \type{tracingparagraphs} \NC number \NC \NC \NR
1718 \NC \type{tolerance} \NC number \NC \NC \NR
1719 \NC \type{looseness} \NC number \NC \NC \NR
1720 \NC \type{hyphenpenalty} \NC number \NC \NC \NR
1721 \NC \type{exhyphenpenalty} \NC number \NC \NC \NR
1722 \NC \type{pdfadjustspacing} \NC number \NC \NC \NR
1723 \NC \type{adjdemerits} \NC number \NC \NC \NR
1724 \NC \type{pdfprotrudechars} \NC number \NC \NC \NR
1725 \NC \type{linepenalty} \NC number \NC \NC \NR
1726 \NC \type{lastlinefit} \NC number \NC \NC \NR
1727 \NC \type{doublehyphendemerits} \NC number \NC \NC \NR
1728 \NC \type{finalhyphendemerits} \NC number \NC \NC \NR
1729 \NC \type{hangafter} \NC number \NC \NC \NR
1730 \NC \type{interlinepenalty} \NC number or table \NC if a table, then it is an array like \prm {interlinepenalties} \NC \NR
1731 \NC \type{clubpenalty} \NC number or table \NC if a table, then it is an array like \prm {clubpenalties} \NC \NR
1732 \NC \type{widowpenalty} \NC number or table \NC if a table, then it is an array like \prm {widowpenalties} \NC \NR
1733 \NC \type{brokenpenalty} \NC number \NC \NC \NR
1734 \NC \type{emergencystretch} \NC number \NC in scaled points \NC \NR
1735 \NC \type{hangindent} \NC number \NC in scaled points \NC \NR
1736 \NC \type{hsize} \NC number \NC in scaled points \NC \NR
1737 \NC \type{leftskip} \NC glue_spec node \NC \NC \NR
1738 \NC \type{rightskip} \NC glue_spec node \NC \NC \NR
1739 \NC \type{parshape} \NC table \NC \NC \NR
1740 \LL
1741 \stoptabulate
1742
1743 Note that there is no interface for \prm {displaywidowpenalties}, you have to
1744 pass the right choice for \type {widowpenalties} yourself.
1745
1746 It is your own job to make sure that \type {listhead} is a proper paragraph list:
1747 this function does not add any nodes to it. To be exact, if you want to replace
1748 the core line breaking, you may have to do the following (when you are not
1749 actually working in the \cbk {pre_linebreak_filter} or \cbk {linebreak_filter}
1750 callbacks, or when the original list starting at listhead was generated in
1751 horizontal mode):
1752
1753 \startitemize
1754 \startitem
1755 add an \quote {indent box} and perhaps a \nod {local_par} node at the start
1756 (only if you need them)
1757 \stopitem
1758 \startitem
1759 replace any found final glue by an infinite penalty (or add such a penalty,
1760 if the last node is not a glue)
1761 \stopitem
1762 \startitem
1763 add a glue node for the \prm {parfillskip} after that penalty node
1764 \stopitem
1765 \startitem
1766 make sure all the \type {prev} pointers are OK
1767 \stopitem
1768 \stopitemize
1769
1770 The result is a node list, it still needs to be vpacked if you want to assign it
1771 to a \prm {vbox}. The returned \type {info} table contains four values that are
1772 all numbers:
1773
1774 \starttabulate[|l|p|]
1775 \DB name \BC explanation \NC \NR
1776 \TB
1777 \NC prevdepth \NC depth of the last line in the broken paragraph \NC \NR
1778 \NC prevgraf \NC number of lines in the broken paragraph \NC \NR
1779 \NC looseness \NC the actual looseness value in the broken paragraph \NC \NR
1780 \NC demerits \NC the total demerits of the chosen solution \NC \NR
1781 \LL
1782 \stoptabulate
1783
1784 Note there are a few things you cannot interface using this function: You cannot
1785 influence font expansion other than via \type {pdfadjustspacing}, because the
1786 settings for that take place elsewhere. The same is true for hbadness and hfuzz
1787 etc. All these are in the \type {hpack} routine, and that fetches its own
1788 variables via globals.
1789
1790 \subsubsection{\type {shipout}}
1791
1792 \topicindex {shipout}
1793
1794 \libindex{shipout}
1795
1796 \startfunctioncall
1797 tex.shipout(<number> n)
1798 \stopfunctioncall
1799
1800 Ships out box number \type {n} to the output file, and clears the box register.
1801
1802 \subsubsection{\type {getpagestate}}
1803
1804 \topicindex {pages}
1805
1806 \libindex{getpagestate}
1807
1808 This helper reports the current page state: \type {empty}, \type {box_there} or
1809 \type {inserts_only} as integer value.
1810
1811 \subsubsection{\type {getlocallevel}}
1812
1813 \topicindex {nesting}
1814
1815 \libindex{getlocallevel}
1816
1817 This integer reports the current level of the local loop. It's only useful for
1818 debugging and the (relative state) numbers can change with the implementation.
1819
1820 \stopsubsection
1821
1822 \startsubsection[title={Randomizers}]
1823
1824 \libindex{lua_math_random}
1825 \libindex{lua_math_randomseed}
1826 \libindex{init_rand}
1827 \libindex{normal_rand}
1828 \libindex{uniform_rand}
1829 \libindex{uniformdeviate}
1830
1831 For practical reasons \LUATEX\ has its own random number generator. The original
1832 \LUA\ random function is available as \typ {tex.lua_math_random}. You can
1833 initialize with a new seed with \type {init_rand} (\typ {lua_math_randomseed} is
1834 equivalent to this one.
1835
1836 There are three generators: \type {normal_rand} (no argument is used), \type
1837 {uniform_rand} (takes a number that will get rounded before being used) and \type
1838 {uniformdeviate} which behaves like the primitive and expects a scaled integer, so
1839
1840 \startfunctioncall
1841 tex.print(tex.uniformdeviate(65536)/65536)
1842 \stopfunctioncall
1843
1844 will give a random number between zero and one.
1845
1846 \stopsubsection
1847
1848 \startsubsection[reference=synctex,title={Functions related to synctex}]
1849
1850 \topicindex {synctex}
1851
1852 \libindex{set_synctex_mode} \libindex{get_synctex_mode}
1853 \libindex{set_synctex_no_files}
1854 \libindex{set_synctex_tag} \libindex{get_synctex_tag} \libindex{force_synctex_tag}
1855 \libindex{set_synctex_line} \libindex{get_synctex_line} \libindex{force_synctex_line}
1856
1857 The next helpers only make sense when you implement your own synctex logic. Keep in
1858 mind that the library used in editors assumes a certain logic and is geared for
1859 plain and \LATEX, so after a decade users expect a certain behaviour.
1860
1861 \starttabulate[|l|p|]
1862 \DB name \BC explanation \NC \NR
1863 \TB
1864 \NC \type{set_synctex_mode} \NC \type {0} is the default and used normal synctex
1865 logic, \type {1} uses the values set by the next
1866 helpers while \type {2} also sets these for glyph
1867 nodes; \type{3} sets glyphs and glue and \type {4}
1868 sets only glyphs \NC \NR
1869 \NC \type{set_synctex_tag} \NC set the current tag (file) value (obeys save stack) \NC \NR
1870 \NC \type{set_synctex_line} \NC set the current line value (obeys save stack) \NC \NR
1871 \NC \type{set_synctex_no_files} \NC disable synctex file logging \NC \NR
1872 \NC \type{get_synctex_mode} \NC returns the current mode (for values see above) \NC \NR
1873 \NC \type{get_synctex_tag} \NC get the currently set value of tag (file) \NC \NR
1874 \NC \type{get_synctex_line} \NC get the currently set value of line \NC \NR
1875 \NC \type{force_synctex_tag} \NC overload the tag (file) value (\type {0} resets) \NC \NR
1876 \NC \type{force_synctex_line} \NC overload the line value (\type {0} resets) \NC \NR
1877 \LL
1878 \stoptabulate
1879
1880 The last one is somewhat special. Due to the way files are registered in \SYNCTEX\ we need
1881 to explicitly disable that feature if we provide our own alternative if we want to avoid
1882 that overhead. Passing a value of 1 disables registering.
1883
1884 \stopsubsection
1885
1886 \stopsection
1887
1888 \startsection[title={The \type {texconfig} table},reference=texconfig][library=texconfig]
1889
1890 \topicindex{libraries+\type{texconfig}}
1891
1892 \topicindex {configuration}
1893
1894 This is a table that is created empty. A startup \LUA\ script could
1895 fill this table with a number of settings that are read out by
1896 the executable after loading and executing the startup file.
1897
1898 \starttabulate[|l|l|l|p|]
1899 \DB key \BC type \BC default \BC explanation \NC \NR
1900 \TB
1901 \NC \type{kpse_init} \NC boolean \NC true
1902 \NC
1903 \type {false} totally disables \KPATHSEA\ initialisation, and enables
1904 interpretation of the following numeric key--value pairs. (only ever unset
1905 this if you implement {\it all\/} file find callbacks!)
1906 \NC \NR
1907 \NC
1908 \type{shell_escape} \NC string \NC \type {'f'} \NC Use \type {'y'} or \type
1909 {'t'} or \type {'1'} to enable \type {\write18} unconditionally, \type {'p'}
1910 to enable the commands that are listed in \type {shell_escape_commands}
1911 \NC \NR
1912 \NC
1913 shell_escape_commands \NC string \NC \NC Comma-separated list of command
1914 names that may be executed by \type {\write18} even if \type {shell_escape}
1915 is set to \type {'p'}. Do {\it not\/} use spaces around commas, separate any
1916 required command arguments by using a space, and use the \ASCII\ double quote
1917 (\type {"}) for any needed argument or path quoting
1918 \NC \NR
1919 \NC \type{string_vacancies} \NC number \NC 75000 \NC cf.\ web2c docs \NC \NR
1920 \NC \type{pool_free} \NC number \NC 5000 \NC cf.\ web2c docs \NC \NR
1921 \NC \type{max_strings} \NC number \NC 15000 \NC cf.\ web2c docs \NC \NR
1922 \NC \type{strings_free} \NC number \NC 100 \NC cf.\ web2c docs \NC \NR
1923 \NC \type{nest_size} \NC number \NC 50 \NC cf.\ web2c docs \NC \NR
1924 \NC \type{max_in_open} \NC number \NC 15 \NC cf.\ web2c docs \NC \NR
1925 \NC \type{param_size} \NC number \NC 60 \NC cf.\ web2c docs \NC \NR
1926 \NC \type{save_size} \NC number \NC 4000 \NC cf.\ web2c docs \NC \NR
1927 \NC \type{stack_size} \NC number \NC 300 \NC cf.\ web2c docs \NC \NR
1928 \NC \type{dvi_buf_size} \NC number \NC 16384 \NC cf.\ web2c docs \NC \NR
1929 \NC \type{error_line} \NC number \NC 79 \NC cf.\ web2c docs \NC \NR
1930 \NC \type{half_error_line} \NC number \NC 50 \NC cf.\ web2c docs \NC \NR
1931 \NC \type{max_print_line} \NC number \NC 79 \NC cf.\ web2c docs \NC \NR
1932 \NC \type{hash_extra} \NC number \NC 0 \NC cf.\ web2c docs \NC \NR
1933 \NC \type{pk_dpi} \NC number \NC 72 \NC cf.\ web2c docs \NC \NR
1934 \NC \type{trace_file_names} \NC boolean \NC true
1935 \NC
1936 \type {false} disables \TEX's normal file open|-|close feedback (the
1937 assumption is that callbacks will take care of that)
1938 \NC \NR
1939 \NC \type{trace_extra_newline} \NC boolean \NC false \NC adds an extra newline in \type{\tracingmacros} \NC\NR
1940 \NC \type{file_line_error} \NC boolean \NC false
1941 \NC
1942 do \type {file:line} style error messages
1943 \NC \NR
1944 \NC \type{halt_on_error} \NC boolean \NC false
1945 \NC
1946 abort run on the first encountered error
1947 \NC \NR
1948 \NC \type{formatname} \NC string \NC
1949 \NC
1950 if no format name was given on the command line, this key will be tested first
1951 instead of simply quitting
1952 \NC \NR
1953 \NC \type{jobname} \NC string \NC
1954 \NC
1955 if no input file name was given on the command line, this key will be tested
1956 first instead of simply giving up
1957 \NC \NR
1958 \NC \type{level_chr} \NC number \NC
1959 \NC
1960 character to put in front of traced macros (see next value)
1961 \NC \NR
1962 \NC \type{level_max} \NC number \NC
1963 \NC
1964 when larger than zero the input nesting level will be shown when \type
1965 {\tracingmacros} is set; levels above this value will be clipped with
1966 the level shown up front
1967 \NC \NR
1968 \NC \type{check_dvi_total_pages} \NC boolean \NC
1969 \NC
1970 in \DVI\ output mode, if true abort run when the number of pages exceeds 65535.
1971 This is the default behaviour. If false, the run goes on as is in \TEX.
1972 \NC \NR
1973 \NC \type{texlua_img} \NC boolean \NC
1974 \NC
1975 if true, allows access to the \type {img} library in \TEXLUA\ mode. If
1976 false (the default), the \type {img} library is not available in \TEXLUA\
1977 mode (as it was unconditionally for \LUATEX\ versions prior to 1.22.0).
1978 Note that this setting is {\bf experimental} and subject to be removed at
1979 any time, without notice.
1980 \NC \NR
1981 \LL
1982 \stoptabulate
1983
1984 Note: the numeric values that match web2c parameters are only used if \type
1985 {kpse_init} is explicitly set to \type {false}. In all other cases, the normal
1986 values from \type {texmf.cnf} are used.
1987
1988 You can kick in your own nesting level visualizer, for instance:
1989
1990 \starttyping
1991 callback.register("input_level_string",function(n)
1992 if tex.tracingmacros > 0 and tex.count.tracingstacklevels > 0 then
1993 if tex.tracingmacros > 1 then
1994 return "! " .. string.rep(">",n) .. " "
1995 end
1996 end
1997 return ""
1998 end)
1999 \stoptyping
2000
2001 Or, in sync with other engines (not checked):
2002
2003 \newcount\tracingstacklevels
2004
2005 \starttyping
2006 \directlua {
2007 callback.register("input_level_string", function(n)
2008 if tex.tracingmacros > 0 then
2009 local l = tex.count.tracingstacklevels
2010 if l > 0 then
2011 return string.rep("~",l) .. string.rep(".",n-l)
2012 end
2013 end
2014 return ""
2015 end)
2016 }
2017 \stoptyping
2018
2019 \stopsection
2020
2021 \startsection[title={The \type {texio} library}][library=texio]
2022
2023 \topicindex{libraries+\type{texio}}
2024 \topicindex{\IO}
2025
2026 This library takes care of the low|-|level I/O interface: writing to the log file
2027 and|/|or console.
2028
2029 \startsubsection[title={\type {write}}]
2030
2031 \libindex{write}
2032
2033 \startfunctioncall
2034 texio.write(<string> target, <string> s, ...)
2035 texio.write(<string> s, ...)
2036 \stopfunctioncall
2037
2038 Without the \type {target} argument, writes all given strings to the same
2039 location(s) \TEX\ writes messages to at this moment. If \prm {batchmode} is in
2040 effect, it writes only to the log, otherwise it writes to the log and the
2041 terminal. The optional \type {target} can be one of three possibilities: \type
2042 {term}, \type {log} or \type {term and log}.
2043
2044 Note: If several strings are given, and if the first of these strings is or might
2045 be one of the targets above, the \type {target} must be specified explicitly to
2046 prevent \LUA\ from interpreting the first string as the target.
2047
2048 \stopsubsection
2049
2050 \startsubsection[title={\type {write_nl}}]
2051
2052 \libindex{write_nl}
2053
2054 \startfunctioncall
2055 texio.write_nl(<string> target, <string> s, ...)
2056 texio.write_nl(<string> s, ...)
2057 \stopfunctioncall
2058
2059 This function behaves like \type {texio.write}, but make sure that the given
2060 strings will appear at the beginning of a new line. You can pass a single empty
2061 string if you only want to move to the next line.
2062
2063 \stopsubsection
2064
2065 \startsubsection[title={\type {setescape}}]
2066
2067 \libindex{setescape}
2068
2069 You can disable \type {^^} escaping of control characters by passing a value of
2070 zero.
2071
2072 \stopsubsection
2073
2074 \startsubsection[title={\type {closeinput}}]
2075
2076 \libindex{closeinput}
2077
2078 This function that should be used with care. It acts as \prm {endinput} but at
2079 the \LUA\ end. You can use it to (sort of) force a jump back to \TEX. Normally a
2080 \LUA\ will just collect prints and at the end bump an input level and flush these
2081 prints. This function can help you stay at the current level but you need to know
2082 what you're doing (or more precise: what \TEX\ is doing with input).
2083
2084 \stopsubsection
2085
2086 \stopsection
2087
2088 \startsection[title={The \type {token} library}][library=token]
2089
2090 \startsubsection[title={The scanner}]
2091
2092 \topicindex{libraries+\type{token}}
2093 \topicindex{tokens}
2094
2095 \libindex{scan_keyword}
2096 \libindex{scan_keyword_cs}
2097 \libindex{scan_int}
2098 \libindex{scan_real}
2099 \libindex{scan_float}
2100 \libindex{scan_dimen}
2101 \libindex{scan_glue}
2102 \libindex{scan_toks}
2103 \libindex{scan_code}
2104 \libindex{scan_string}
2105 \libindex{scan_argument}
2106 \libindex{scan_word}
2107 \libindex{scan_csname}
2108 \libindex{scan_list}
2109
2110 The token library provides means to intercept the input and deal with it at the
2111 \LUA\ level. The library provides a basic scanner infrastructure that can be used
2112 to write macros that accept a wide range of arguments. This interface is on
2113 purpose kept general and as performance is quite ok. One can build additional
2114 parsers without too much overhead. It's up to macro package writers to see how
2115 they can benefit from this as the main principle behind \LUATEX\ is to provide a
2116 minimal set of tools and no solutions. The scanner functions are probably the
2117 most intriguing.
2118
2119 \starttabulate[|l|l|p|]
2120 \DB function \BC argument \BC result \NC \NR
2121 \TB
2122 \NC \type{scan_keyword} \NC string \NC returns true if the given keyword is gobbled; as with
2123 the regular \TEX\ keyword scanner this is case insensitive
2124 (and \ASCII\ based) \NC \NR
2125 \NC \type{scan_keyword_cs} \NC string \NC returns true if the given keyword is gobbled; this variant
2126 is case sensitive and also suitable for \UTF8 \NC \NR
2127 \NC \type{scan_int} \NC \NC returns an integer \NC \NR
2128 \NC \type{scan_real} \NC \NC returns a number from e.g.\ \type {1}, \type {1.1}, \type {.1} with optional collapsed signs \NC \NR
2129 \NC \type{scan_float} \NC \NC returns a number from e.g.\ \type {1}, \type {1.1}, \type {.1}, \type {1.1E10}, , \type {.1e-10} with optional collapsed signs \NC \NR
2130 \NC \type{scan_dimen} \NC infinity, mu-units \NC returns a number representing a dimension and or two numbers being the filler and order \NC \NR
2131 \NC \type{scan_glue} \NC mu-units \NC returns a glue spec node \NC \NR
2132 \NC \type{scan_toks} \NC definer, expand \NC returns a table of tokens tokens \NC \NR
2133 \NC \type{scan_code} \NC bitset \NC returns a character if its category is in the given bitset (representing catcodes) \NC \NR
2134 \NC \type{scan_string} \NC \NC returns a string given between \type {{}}, as \type {\macro} or as sequence of characters with catcode 11 or 12 \NC \NR
2135 \NC \type{scan_argument} \NC boolean \NC this one is simular to \type {scanstring} but also accepts a \type {\cs} \NC \NR
2136 \NC \type{scan_word} \NC \NC returns a sequence of characters with catcode 11 or 12 as string \NC \NR
2137 \NC \type{scan_csname} \NC \NC returns \type {foo} after scanning \type {\foo} \NC \NR
2138 \NC \type{scan_list} \NC \NC picks up a box specification and returns a \type {[h|v]list} node \NC \NR
2139 \LL
2140 \stoptabulate
2141
2142 The scanners can be considered stable apart from the one scanning for a token.
2143 The \type {scan_code} function takes an optional number, the \type {keyword}
2144 function a normal \LUA\ string. The \type {infinity} boolean signals that we also
2145 permit \type {fill} as dimension and the \type {mu-units} flags the scanner that
2146 we expect math units. When scanning tokens we can indicate that we are defining a
2147 macro, in which case the result will also provide information about what
2148 arguments are expected and in the result this is separated from the meaning by a
2149 separator token. The \type {expand} flag determines if the list will be expanded.
2150
2151 The \type {scan_argument} function expands the given argument. When a braced
2152 argument is scanned, expansion can be prohibited by passing \type {false}
2153 (default is \type {true}). In case of a control sequence passing \type {false}
2154 will result in a one|-|level expansion (the meaning of the macro).
2155
2156 The string scanner scans for something between curly braces and expands on the
2157 way, or when it sees a control sequence it will return its meaning. Otherwise it
2158 will scan characters with catcode \type {letter} or \type {other}. So, given the
2159 following definition:
2160
2161 \startbuffer
2162 \def\bar{bar}
2163 \def\foo{foo-\bar}
2164 \stopbuffer
2165
2166 \typebuffer \getbuffer
2167
2168 we get:
2169
2170 \starttabulate[|l|Tl|l|]
2171 \DB name \BC result \NC \NR
2172 \TB
2173 \NC \type {\directlua{token.scan_string()}{foo}} \NC \directlua{context("{\\red\\type {"..token.scan_string().."}}")} {foo} \NC full expansion \NC \NR
2174 \NC \type {\directlua{token.scan_string()}foo} \NC \directlua{context("{\\red\\type {"..token.scan_string().."}}")} foo \NC letters and others \NC \NR
2175 \NC \type {\directlua{token.scan_string()}\foo} \NC \directlua{context("{\\red\\type {"..token.scan_string().."}}")}\foo \NC meaning \NC \NR
2176 \LL
2177 \stoptabulate
2178
2179 The \type {\foo} case only gives the meaning, but one can pass an already
2180 expanded definition (\prm {edef}'d). In the case of the braced variant one can of
2181 course use the \prm {detokenize} and \prm {unexpanded} primitives since there we
2182 do expand.
2183
2184 The \type {scan_word} scanner can be used to implement for instance a number scanner:
2185
2186 \starttyping
2187 function token.scan_number(base)
2188 return tonumber(token.scan_word(),base)
2189 end
2190 \stoptyping
2191
2192 This scanner accepts any valid \LUA\ number so it is a way to pick up floats
2193 in the input.
2194
2195 You can use the \LUA\ interface as follows:
2196
2197 \starttyping
2198 \directlua {
2199 function mymacro(n)
2200 ...
2201 end
2202 }
2203
2204 \def\mymacro#1{%
2205 \directlua {
2206 mymacro(\number\dimexpr#1)
2207 }%
2208 }
2209
2210 \mymacro{12pt}
2211 \mymacro{\dimen0}
2212 \stoptyping
2213
2214 You can also do this:
2215
2216 \starttyping
2217 \directlua {
2218 function mymacro()
2219 local d = token.scan_dimen()
2220 ...
2221 end
2222 }
2223
2224 \def\mymacro{%
2225 \directlua {
2226 mymacro()
2227 }%
2228 }
2229
2230 \mymacro 12pt
2231 \mymacro \dimen0
2232 \stoptyping
2233
2234 It is quite clear from looking at the code what the first method needs as
2235 argument(s). For the second method you need to look at the \LUA\ code to see what
2236 gets picked up. Instead of passing from \TEX\ to \LUA\ we let \LUA\ fetch from
2237 the input stream.
2238
2239 In the first case the input is tokenized and then turned into a string, then it
2240 is passed to \LUA\ where it gets interpreted. In the second case only a function
2241 call gets interpreted but then the input is picked up by explicitly calling the
2242 scanner functions. These return proper \LUA\ variables so no further conversion
2243 has to be done. This is more efficient but in practice (given what \TEX\ has to
2244 do) this effect should not be overestimated. For numbers and dimensions it saves
2245 a bit but for passing strings conversion to and from tokens has to be done anyway
2246 (although we can probably speed up the process in later versions if needed).
2247
2248 \stopsubsection
2249
2250 \startsubsection[title= {Picking up one token}]
2251
2252 \libindex {get_next}
2253 \libindex {scan_token}
2254 \libindex {expand}
2255
2256 The scanners look for a sequence. When you want to pick up one token from the
2257 input you use \type {get_next}. This creates a token with the (low level)
2258 properties as discussed next. This token is just the next one. If you want to
2259 enforce expansion first you can use \type {scan_token}. Internally tokens are
2260 characterized by a number that packs a lot of information. In order to access
2261 the bits of information a token is wrapped in a userdata object.
2262
2263 The \type {expand} function will trigger expansion of the next token in the
2264 input. This can be quite unpredictable but when you call it you probably know
2265 enough about \TEX\ not to be too worried about that. It basically is a call to
2266 the internal expand related function.
2267
2268 \stopsubsection
2269
2270 \startsubsection[title={Creating tokens}]
2271
2272 \libindex{create}
2273 \libindex{new}
2274
2275 \libindex{is_defined}
2276 \libindex{is_token}
2277 \libindex{biggest_char}
2278
2279 \libindex{commands}
2280 \libindex{command_id}
2281
2282 \libindex{get_command}
2283 \libindex{get_cmdname}
2284 \libindex{get_csname}
2285 \libindex{get_id}
2286 \libindex{get_active}
2287 \libindex{get_expandable}
2288 \libindex{get_protected}
2289 \libindex{get_mode}
2290 \libindex{get_index}
2291 \libindex{get_tok}
2292
2293 \libindex{get_next}
2294
2295 The creator function can be used as follows:
2296
2297 \starttyping
2298 local t = token.create("relax")
2299 \stoptyping
2300
2301 This gives back a token object that has the properties of the \prm {relax}
2302 primitive. The possible properties of tokens are:
2303
2304 \starttabulate[|l|p|]
2305 \DB name \BC explanation \NC \NR
2306 \TB
2307 \NC \type {command} \NC a number representing the internal command number \NC \NR
2308 \NC \type {cmdname} \NC the type of the command (for instance the catcode in case of a
2309 character or the classifier that determines the internal
2310 treatment \NC \NR
2311 \NC \type {csname} \NC the associated control sequence (if applicable) \NC \NR
2312 \NC \type {id} \NC the unique id of the token \NC \NR
2313 \NC \type {tok} \NC the full token number as stored in \TEX \NC \NR
2314 \NC \type {active} \NC a boolean indicating the active state of the token \NC \NR
2315 \NC \type {expandable} \NC a boolean indicating if the token (macro) is expandable \NC \NR
2316 \NC \type {protected} \NC a boolean indicating if the token (macro) is protected \NC \NR
2317 \NC \type {mode} \NC a number either representing a character or another entity \NC \NR
2318 \NC \type {index} \NC a number running from 0x0000 upto 0xFFFF indicating a \TEX\ register index \NC \NR
2319 \LL
2320 \stoptabulate
2321
2322 Alternatively you can use a getter \type {get_<fieldname>} to access a property
2323 of a token.
2324
2325 The numbers that represent a catcode are the same as in \TEX\ itself, so using
2326 this information assumes that you know a bit about \TEX's internals. The other
2327 numbers and names are used consistently but are not frozen. So, when you use them
2328 for comparing you can best query a known primitive or character first to see the
2329 values.
2330
2331 You can ask for a list of commands:
2332
2333 \starttyping
2334 local t = token.commands()
2335 \stoptyping
2336
2337 The id of a token class can be queried as follows:
2338
2339 \starttyping
2340 local id = token.command_id("math_shift")
2341 \stoptyping
2342
2343 If you really know what you're doing you can create character tokens by not
2344 passing a string but a number:
2345
2346 \starttyping
2347 local letter_x = token.create(string.byte("x"))
2348 local other_x = token.create(string.byte("x"),12)
2349 \stoptyping
2350
2351 Passing weird numbers can give side effects so don't expect too much help with
2352 that. As said, you need to know what you're doing. The best way to explore the
2353 way these internals work is to just look at how primitives or macros or \prm
2354 {chardef}'d commands are tokenized. Just create a known one and inspect its
2355 fields. A variant that ignores the current catcode table is:
2356
2357 \starttyping
2358 local whatever = token.new(123,12)
2359 \stoptyping
2360
2361 You can test if a control sequence is defined with \type {is_defined}, which
2362 accepts a string and returns a boolean:
2363
2364 \starttyping
2365 local okay = token.is_defined("foo")
2366 \stoptyping
2367
2368 When a second argument to \type {is_defined} is \type {true} the check is for an
2369 undefined control sequence (only), otherwise any undefined command gives true.
2370
2371 The largest character possible is returned by \type {biggest_char}, just in case you
2372 need to know that boundary condition.
2373
2374 \stopsubsection
2375
2376 \startsubsection[title={Macros}]
2377
2378 \topicindex {macros}
2379
2380 \libindex{set_macro}
2381 \libindex{get_macro}
2382 \libindex{get_meaning}
2383 \libindex{set_char}
2384 \libindex{set_lua}
2385 \libindex{get_functions_table}
2386
2387 The \type {set_macro} function can get upto 4 arguments:
2388
2389 \starttyping
2390 set_macro("csname","content")
2391 set_macro("csname","content","global")
2392 set_macro("csname")
2393 \stoptyping
2394
2395 You can pass a catcodetable identifier as first argument:
2396
2397 \starttyping
2398 set_macro(catcodetable,"csname","content")
2399 set_macro(catcodetable,"csname","content","global")
2400 set_macro(catcodetable,"csname")
2401 \stoptyping
2402
2403 The results are like:
2404
2405 \starttyping
2406 \def\csname{content}
2407 \gdef\csname{content}
2408 \def\csname{}
2409 \stoptyping
2410
2411 The \type {get_macro} function can be used to get the content of a macro while
2412 the \type {get_meaning} function gives the meaning including the argument
2413 specification (as usual in \TEX\ separated by \type {->}).
2414
2415 The \type {set_char} function can be used to do a \prm {chardef} at the
2416 \LUA\ end, where invalid assignments are silently ignored:
2417
2418 \starttyping
2419 set_char("csname",number)
2420 set_char("csname",number,"global")
2421 \stoptyping
2422
2423 A special one is the following:
2424
2425 \starttyping
2426 set_lua("mycode",id)
2427 set_lua("mycode",id,"global","protected")
2428 \stoptyping
2429
2430 This creates a token that refers to a \LUA\ function with an entry in the table
2431 that you can access with \type {lua.get_functions_table}. It is the companion
2432 to \lpr {luadef}.
2433
2434 \stopsubsection
2435
2436 \startsubsection[title={Pushing back}]
2437
2438 \libindex{get_next}
2439 \libindex{put_next}
2440 \libindex{unchecked_put_next}
2441
2442 There is a (for now) experimental putter:
2443
2444 \starttyping
2445 local t1 = token.get_next()
2446 local t2 = token.get_next()
2447 local t3 = token.get_next()
2448 local t4 = token.get_next()
2449 -- watch out, we flush in sequence
2450 token.put_next { t1, t2 }
2451 -- but this one gets pushed in front
2452 token.put_next ( t3, t4 )
2453 \stoptyping
2454
2455 When we scan \type {wxyz!} we get \type {yzwx!} back. The argument is either a table
2456 with tokens or a list of tokens. The new function \type {token.unchecked_put_next}
2457 has been added per request of the \LATEX\ team. It skips this error checking and
2458 follows a different code path. It assumes that a valid token user datum is
2459 passed and can crash the engine otherwise.
2460
2461 The \type {token.expand} function will trigger
2462 expansion but what happens really depends on what you're doing where.
2463
2464 \stopsubsection
2465
2466 \startsubsection[title={Nota bene}]
2467
2468 When scanning for the next token you need to keep in mind that we're not scanning
2469 like \TEX\ does: expanding, changing modes and doing things as it goes. When we
2470 scan with \LUA\ we just pick up tokens. Say that we have:
2471
2472 \starttyping
2473 \bar
2474 \stoptyping
2475
2476 but \type {\bar} is undefined. Normally \TEX\ will then issue an error message.
2477 However, when we have:
2478
2479 \starttyping
2480 \def\foo{\bar}
2481 \stoptyping
2482
2483 We get no error, unless we expand \type {\foo} while \type {\bar} is still
2484 undefined. What happens is that as soon as \TEX\ sees an undefined macro it will
2485 create a hash entry and when later it gets defined that entry will be reused. So,
2486 \type {\bar} really exists but can be in an undefined state.
2487
2488 \startbuffer[demo]
2489 bar : \directlua{tex.print(token.scan_csname())}\bar
2490 foo : \directlua{tex.print(token.scan_csname())}\foo
2491 myfirstbar : \directlua{tex.print(token.scan_csname())}\myfirstbar
2492 \stopbuffer
2493
2494 \startlines
2495 \getbuffer[demo]
2496 \stoplines
2497
2498 This was entered as:
2499
2500 \typebuffer[demo]
2501
2502 The reason that you see \type {bar} reported and not \type {myfirstbar} is that
2503 \type {\bar} was already used in a previous paragraph.
2504
2505 If we now say:
2506
2507 \startbuffer
2508 \def\foo{}
2509 \stopbuffer
2510
2511 \typebuffer \getbuffer
2512
2513 we get:
2514
2515 \startlines
2516 \getbuffer[demo]
2517 \stoplines
2518
2519 And if we say
2520
2521 \startbuffer
2522 \def\foo{\bar}
2523 \stopbuffer
2524
2525 \typebuffer \getbuffer
2526
2527 we get:
2528
2529 \startlines
2530 \getbuffer[demo]
2531 \stoplines
2532
2533 When scanning from \LUA\ we are not in a mode that defines (undefined) macros at
2534 all. There we just get the real primitive undefined macro token.
2535
2536 \startbuffer
2537 \directlua{local t = token.get_next() tex.print(t.id.." "..t.tok)}\myfirstbar
2538 \directlua{local t = token.get_next() tex.print(t.id.." "..t.tok)}\mysecondbar
2539 \directlua{local t = token.get_next() tex.print(t.id.." "..t.tok)}\mythirdbar
2540 \stopbuffer
2541
2542 \startlines
2543 \getbuffer
2544 \stoplines
2545
2546 This was generated with:
2547
2548 \typebuffer
2549
2550 So, we do get a unique token because after all we need some kind of \LUA\ object
2551 that can be used and garbage collected, but it is basically the same one,
2552 representing an undefined control sequence.
2553
2554 \stopsubsection
2555
2556 \stopsection
2557
2558 \startsection[title={The \type {kpse} library}][library=kpse]
2559
2560 \topicindex{libraries+\type{kpse}}
2561
2562 This library provides two separate, but nearly identical interfaces to the
2563 \KPATHSEA\ file search functionality: there is a \quote {normal} procedural
2564 interface that shares its kpathsea instance with \LUATEX\ itself, and an object
2565 oriented interface that is completely on its own.
2566
2567 \startsubsection[title={\type {set_program_name} and \type {new}}]
2568
2569 \libindex{set_program_name}
2570 \libindex{default_texmfcnf}
2571 \libindex{new}
2572
2573 The way the library looks up variables is driven by the \type {texmf.cmf} file
2574 where the currently set program name acts as filter. You can check what file is
2575 used by with \type {default_texmfcnf}.
2576
2577 Before the search library can be used at all, its database has to be initialized.
2578 There are three possibilities, two of which belong to the procedural interface.
2579
2580 First, when \LUATEX\ is used to typeset documents, this initialization happens
2581 automatically and the \KPATHSEA\ executable and program names are set to \type
2582 {luatex} (that is, unless explicitly prohibited by the user's startup script.
2583 See~\in {section} [init] for more details).
2584
2585 Second, in \TEXLUA\ mode, the initialization has to be done explicitly via the
2586 \type {kpse.set_program_name} function, which sets the \KPATHSEA\ executable
2587 (and optionally program) name.
2588
2589 \startfunctioncall
2590 kpse.set_program_name(<string> name)
2591 kpse.set_program_name(<string> name, <string> progname)
2592 \stopfunctioncall
2593
2594 The second argument controls the use of the \quote {dotted} values in the \type
2595 {texmf.cnf} configuration file, and defaults to the first argument.
2596
2597 Third, if you prefer the object oriented interface, you have to call a different
2598 function. It has the same arguments, but it returns a userdata variable.
2599
2600 \startfunctioncall
2601 local kpathsea = kpse.new(<string> name)
2602 local kpathsea = kpse.new(<string> name, <string> progname)
2603 \stopfunctioncall
2604
2605 Apart from these two functions, the calling conventions of the interfaces are
2606 identical. Depending on the chosen interface, you either call \type
2607 {kpse.find_file} or \type {kpathsea:find_file}, with identical arguments and
2608 return values.
2609
2610 \stopsubsection
2611
2612 \startsubsection[title={\type {record_input_file} and \type {record_output_file}}]
2613
2614 \topicindex {files+recording}
2615
2616 \libindex{record_input_file}
2617 \libindex{record_output_file}
2618
2619 These two function can be used to register used files. Because callbacks can load
2620 files themselves you might need these helpers (if you use recording at all).
2621
2622 \startfunctioncall
2623 kpse.record_input_file(<string> name)
2624 kpse.record_output_file(<string> name)
2625 \stopfunctioncall
2626
2627 \stopsubsection
2628
2629 \startsubsection[title={\type {find_file}}]
2630
2631 \topicindex {files+finding}
2632
2633 \libindex {find_file}
2634
2635 The most often used function in the library is \type {find_file}:
2636
2637 \startfunctioncall
2638 <string> f = kpse.find_file(<string> filename)
2639 <string> f = kpse.find_file(<string> filename, <string> ftype)
2640 <string> f = kpse.find_file(<string> filename, <boolean> mustexist)
2641 <string> f = kpse.find_file(<string> filename, <string> ftype, <boolean> mustexist)
2642 <string> f = kpse.find_file(<string> filename, <string> ftype, <number> dpi)
2643 \stopfunctioncall
2644
2645 Arguments:
2646
2647 \startitemize[intro]
2648
2649 \sym{filename}
2650
2651 the name of the file you want to find, with or without extension.
2652
2653 \sym{ftype}
2654
2655 maps to the \type {-format} argument of \KPSEWHICH. The supported \type {ftype}
2656 values are the same as the ones supported by the standalone \type {kpsewhich}
2657 program: \startluacode
2658 local list = {
2659 "afm",
2660 "base",
2661 "bib",
2662 "bitmap font",
2663 "bst",
2664 "cid maps",
2665 "clua",
2666 "cmap files",
2667 "cnf",
2668 "cweb",
2669 "dvips config",
2670 "enc files",
2671 "fmt",
2672 "font feature files",
2673 "gf",
2674 "graphic|/|figure",
2675 "ist",
2676 "lig files",
2677 "ls-R",
2678 "lua",
2679 "map",
2680 "mem",
2681 "MetaPost support",
2682 "mf",
2683 "mfpool",
2684 "mft",
2685 "misc fonts",
2686 "mlbib",
2687 "mlbst",
2688 "mp",
2689 "mppool",
2690 "ocp",
2691 "ofm",
2692 "opentype fonts",
2693 "opl",
2694 "other binary files",
2695 "other text files",
2696 "otp",
2697 "ovf",
2698 "ovp",
2699 "pdftex config",
2700 "pk",
2701 "PostScript header",
2702 "subfont definition files",
2703 "tex",
2704 "TeX system documentation",
2705 "TeX system sources",
2706 "texmfscripts",
2707 "texpool",
2708 "tfm",
2709 "Troff fonts",
2710 "truetype fonts",
2711 "type1 fonts",
2712 "type42 fonts",
2713 "vf",
2714 "web",
2715 "web2c files",
2716 }
2717 table.sort(list)
2718 context("{\\tttf \letterpercent, t}",list)
2719 \stopluacode
2720
2721 The default type is \type {tex}. Note: this is different from \KPSEWHICH, which
2722 tries to deduce the file type itself from looking at the supplied extension.
2723
2724 \sym{mustexist}
2725
2726 is similar to \KPSEWHICH's \type {-must-exist}, and the default is \type {false}.
2727 If you specify \type {true} (or a non|-|zero integer), then the \KPSE\ library
2728 will search the disk as well as the \type {ls-R} databases.
2729
2730 \sym{dpi}
2731
2732 This is used for the size argument of the formats \type {pk}, \type {gf}, and
2733 \type {bitmap font}. \stopitemize
2734
2735 If \type {--output-directory} is specified and the value is a relative pathname,
2736 the file is searched first here and if it fails it will be searched in the standard tree.
2737
2738 \stopsubsection
2739
2740 \startsubsection[title={\type {lookup}}]
2741
2742 \libindex{lookup}
2743
2744 A more powerful (but slower) generic method for finding files is also available.
2745 It returns a string for each found file.
2746
2747 \startfunctioncall
2748 <string> f, ... = kpse.lookup(<string> filename, <table> options)
2749 \stopfunctioncall
2750
2751 The options match commandline arguments from \type {kpsewhich}:
2752
2753 \starttabulate[|l|l|p|]
2754 \DB key \BC type \BC explanation \NC \NR
2755 \TB
2756 \NC \type{debug} \NC number \NC set debugging flags for this lookup\NC \NR
2757 \NC \type{format} \NC string \NC use specific file type (see list above)\NC \NR
2758 \NC \type{dpi} \NC number \NC use this resolution for this lookup; default 600\NC \NR
2759 \NC \type{path} \NC string \NC search in the given path\NC \NR
2760 \NC \type{all} \NC boolean \NC output all matches, not just the first\NC \NR
2761 \NC \type{mustexist} \NC boolean \NC search the disk as well as ls-R if necessary\NC \NR
2762 \NC \type{mktexpk} \NC boolean \NC disable/enable mktexpk generation for this lookup\NC \NR
2763 \NC \type{mktextex} \NC boolean \NC disable/enable mktextex generation for this lookup\NC \NR
2764 \NC \type{mktexmf} \NC boolean \NC disable/enable mktexmf generation for this lookup\NC \NR
2765 \NC \type{mktextfm} \NC boolean \NC disable/enable mktextfm generation for this lookup\NC \NR
2766 \NC \type{subdir} \NC string
2767 or table \NC only output matches whose directory part
2768 ends with the given string(s) \NC \NR
2769 \LL
2770 \stoptabulate
2771
2772 If \type {--output-directory} is specified and the value is a relative pathname,
2773 the file is searched first here and then in the standard tree.
2774
2775
2776 \stopsubsection
2777
2778 \startsubsection[title={\type {init_prog}}]
2779
2780 \topicindex {initialization+bitmaps}
2781
2782 \libindex{init_prog}
2783
2784 Extra initialization for programs that need to generate bitmap fonts.
2785
2786 \startfunctioncall
2787 kpse.init_prog(<string> prefix, <number> base_dpi, <string> mfmode)
2788 kpse.init_prog(<string> prefix, <number> base_dpi, <string> mfmode, <string> fallback)
2789 \stopfunctioncall
2790
2791 \stopsubsection
2792
2793 \startsubsection[title={\type {readable_file}}]
2794
2795 \libindex{readable_file}
2796
2797 Test if an (absolute) file name is a readable file.
2798
2799 \startfunctioncall
2800 <string> f = kpse.readable_file(<string> name)
2801 \stopfunctioncall
2802
2803 The return value is the actual absolute filename you should use, because the disk
2804 name is not always the same as the requested name, due to aliases and
2805 system|-|specific handling under e.g.\ \MSDOS. Returns \type {nil} if the file
2806 does not exist or is not readable.
2807
2808 \stopsubsection
2809
2810 \startsubsection[title={\type {expand_path}}]
2811
2812 \libindex{expand_path}
2813
2814 Like kpsewhich's \type {-expand-path}:
2815
2816 \startfunctioncall
2817 <string> r = kpse.expand_path(<string> s)
2818 \stopfunctioncall
2819
2820 \stopsubsection
2821
2822 \startsubsection[title={\type {expand_var}}]
2823
2824 \libindex{expand_var}
2825
2826 Like kpsewhich's \type {-expand-var}:
2827
2828 \startfunctioncall
2829 <string> r = kpse.expand_var(<string> s)
2830 \stopfunctioncall
2831
2832 \stopsubsection
2833
2834 \startsubsection[title={\type {expand_braces}}]
2835
2836 \libindex{expand_braces}
2837
2838 Like kpsewhich's \type {-expand-braces}:
2839
2840 \startfunctioncall
2841 <string> r = kpse.expand_braces(<string> s)
2842 \stopfunctioncall
2843
2844 \stopsubsection
2845
2846 \startsubsection[title={\type {in_name_ok}}]
2847
2848 \libindex{in_name_ok}
2849
2850 Returns true if \type{fname} is acceptable to open for reading, otherwise false and
2851 write a message to standard error.
2852
2853 \startfunctioncall
2854 <boolean> r = kpse.in_name_ok(<string> fname)
2855 \stopfunctioncall
2856
2857 \startsubsection[title={\type {in_name_ok_silent_extended}}]
2858
2859 \libindex{in_name_ok_silent_extended}
2860
2861 \startfunctioncall
2862 <boolean> r = kpse.in_name_ok_silent_extended(<string> fname)
2863 \stopfunctioncall
2864
2865 Returns true if \type{fname} is acceptable to open for reading;
2866 the values of \type{TEXMFVAR} and \type{TEXMFSYSVAR} are also
2867 checked for absolute filenames. Returns false otherwise but it doesn't write
2868 a message to standard error.
2869
2870 \stopsubsection
2871
2872
2873 \startsubsection[title={\type {out_name_ok}}]
2874
2875 \libindex{out_name_ok}
2876
2877 Returns true if \type{fname} is acceptable to open for writing.
2878
2879 \startfunctioncall
2880 <boolean> r = kpse.out_name_ok(<string> fname)
2881 \stopfunctioncall
2882
2883 \stopsubsection
2884
2885
2886 \startsubsection[title={\type {out_name_ok_silent_extended}}]
2887
2888 \libindex{out_name_ok_silent_extended}
2889
2890 \startfunctioncall
2891 <boolean> r = kpse.out_name_ok_silent_extended(<string> fname)
2892 \stopfunctioncall
2893
2894 Returns true if \type{fname} is acceptable to open for writing;
2895 the values of \type{TEXMFVAR} and \type{TEXMFSYSVAR} are also
2896 checked for absolute filenames. Returns false otherwise but it doesn't write
2897 a message to standard error.
2898
2899 \stopsubsection
2900
2901
2902
2903
2904 \startsubsection[title={\type {show_path}}]
2905
2906 \libindex{show_path}
2907
2908 Like kpsewhich's \type {-show-path}:
2909
2910 \startfunctioncall
2911 <string> r = kpse.show_path(<string> ftype)
2912 \stopfunctioncall
2913
2914 \stopsubsection
2915
2916 \startsubsection[title={\type {var_value}}]
2917
2918 \libindex{var_value}
2919
2920 Like kpsewhich's \type {-var-value}:
2921
2922 \startfunctioncall
2923 <string> r = kpse.var_value(<string> s)
2924 \stopfunctioncall
2925
2926 \stopsubsection
2927
2928 \startsubsection[title={\type {version}}]
2929
2930 \libindex{version}
2931
2932 Returns the kpathsea version string.
2933
2934 \startfunctioncall
2935 <string> r = kpse.version()
2936 \stopfunctioncall
2937
2938 \stopsubsection
2939
2940 \startsubsection[title={\type {check_permission}}]
2941
2942 \libindex{check\_permission}
2943
2944 Checks if the \type{filename} can be executed or not.
2945 Returns \type{1}, \type{filename} or a safe cmd alternative if it can be executed,
2946 otherwise returns \type{0} and an error message.
2947
2948 \startfunctioncall
2949 <string> res, cmd = kpse.check_permission(<string> filename)
2950 \stopfunctioncall
2951
2952 \stopsubsection
2953
2954
2955 \stopsection
2956
2957 \stopchapter
2958
2959 \stopcomponent