3 \environment luatex-style
4 \environment luatex-logos
6 \startcomponent luatex-tex
8 \startchapter[reference=tex,title=
{The
\TEX\ related libraries
}]
10 \section{The
\type {lua
} library
}
12 \subsection{\LUA\ version
}
14 This library contains one read|-|only item:
17 <string> s = lua.version
20 This returns the
\LUA\ version identifier string. The value is currently
21 \directlua {tex
.print(lua
.version
)}.
23 \subsection{\LUA\ bytecode registers
}
25 \LUA\ registers can be used to communicate
\LUA\ functions across
\LUA\ chunks.
26 The accepted values for assignments are functions and
\type {nil
}. Likewise, the
27 retrieved value is either a function or
\type {nil
}.
30 lua.bytecode
[<number> n
] = <function> f
31 lua.bytecode
[<number> n
]()
34 The contents of the
\type {lua.bytecode
} array is stored inside the format file
35 as actual
\LUA\ bytecode, so it can also be used to preload
\LUA\ code.
37 Note: The function must not contain any upvalues. Currently, functions containing
38 upvalues can be stored (and their upvalues are set to
\type {nil
}), but this is
39 an artifact of the current
\LUA\ implementation and thus subject to change.
41 The associated function calls are
44 <function> f = lua.getbytecode(<number> n)
45 lua.setbytecode(<number> n, <function> f)
48 Note: Since a
\LUA\ file loaded using
\type {loadfile(filename)
} is essentially
49 an anonymous function, a complete file can be stored in a bytecode register like
53 lua.bytecode
[n
] = loadfile(filename)
56 Now all definitions (functions, variables) contained in the file can be
57 created by executing this bytecode register:
63 Note that the path of the file is stored in the
\LUA\ bytecode to be used in
64 stack backtraces and therefore dumped into the format file if the above code is
65 used in
\INITEX. If it contains private information, i.e. the user name, this
66 information is then contained in the format file as well. This should be kept in
67 mind when preloading files into a bytecode register in
\INITEX.
69 \subsection{\LUA\ chunk name registers
}
71 There is an array of
65536 (
0--
65535) potential chunk names for use with the
72 \type {\directlua} and
\type {\latelua
} primitives.
75 lua.name
[<number> n
] = <string> s
76 <string> s = lua.name
[<number> n
]
79 If you want to unset a
\LUA\ name, you can assign
\type {nil
} to it.
81 \section{The
\type {status
} library
}
83 This contains a number of run|-|time configuration items that you may find useful
84 in message reporting, as well as an iterator function that gets all of the names
85 and values as a table.
88 <table> info = status.list()
91 The keys in the table are the known items, the value is the current value. Almost
92 all of the values in
\type {status
} are fetched through a metatable at run|-|time
93 whenever they are accessed, so you cannot use
\type {pairs
} on
\type {status
},
94 but you
{\it can\/
} use
\type {pairs
} on
\type {info
}, of course. If you do not
95 need the full list, you can also ask for a single item by using its name as an
96 index into
\type {status
}.
100 \starttabulate[|lT|p|
]
101 \NC \rmbf key
\NC \bf explanation
\NC \NR
102 \NC pdf_gone
\NC written
\PDF\ bytes
\NC \NR
103 \NC pdf_ptr
\NC not yet written
\PDF\ bytes
\NC \NR
104 \NC dvi_gone
\NC written
\DVI\ bytes
\NC \NR
105 \NC dvi_ptr
\NC not yet written
\DVI\ bytes
\NC \NR
106 \NC total_pages
\NC number of written pages
\NC \NR
107 \NC output_file_name
\NC name of the
\PDF\ or
\DVI\ file
\NC \NR
108 \NC log_name
\NC name of the log file
\NC \NR
109 \NC banner
\NC terminal display banner
\NC \NR
110 \NC var_used
\NC variable (one|-|word) memory in use
\NC \NR
111 \NC dyn_used
\NC token (multi|-|word) memory in use
\NC \NR
112 \NC str_ptr
\NC number of strings
\NC \NR
113 \NC init_str_ptr
\NC number of
\INITEX\ strings
\NC \NR
114 \NC max_strings
\NC maximum allowed strings
\NC \NR
115 \NC pool_ptr
\NC string pool index
\NC \NR
116 \NC init_pool_ptr
\NC \INITEX\ string pool index
\NC \NR
117 \NC pool_size
\NC current size allocated for string characters
\NC \NR
118 \NC node_mem_usage
\NC a string giving insight into currently used nodes
\NC \NR
119 \NC var_mem_max
\NC number of allocated words for nodes
\NC \NR
120 \NC fix_mem_max
\NC number of allocated words for tokens
\NC \NR
121 \NC fix_mem_end
\NC maximum number of used tokens
\NC \NR
122 \NC cs_count
\NC number of control sequences
\NC \NR
123 \NC hash_size
\NC size of hash
\NC \NR
124 \NC hash_extra
\NC extra allowed hash
\NC \NR
125 \NC font_ptr
\NC number of active fonts
\NC \NR
126 \NC input_ptr
\NC th elevel of input we're at
\NC \NR
127 \NC max_in_stack
\NC max used input stack entries
\NC \NR
128 \NC max_nest_stack
\NC max used nesting stack entries
\NC \NR
129 \NC max_param_stack
\NC max used parameter stack entries
\NC \NR
130 \NC max_buf_stack
\NC max used buffer position
\NC \NR
131 \NC max_save_stack
\NC max used save stack entries
\NC \NR
132 \NC stack_size
\NC input stack size
\NC \NR
133 \NC nest_size
\NC nesting stack size
\NC \NR
134 \NC param_size
\NC parameter stack size
\NC \NR
135 \NC buf_size
\NC current allocated size of the line buffer
\NC \NR
136 \NC save_size
\NC save stack size
\NC \NR
137 \NC obj_ptr
\NC max
\PDF\ object pointer
\NC \NR
138 \NC obj_tab_size
\NC \PDF\ object table size
\NC \NR
139 \NC pdf_os_cntr
\NC max
\PDF\ object stream pointer
\NC \NR
140 \NC pdf_os_objidx
\NC \PDF\ object stream index
\NC \NR
141 \NC pdf_dest_names_ptr
\NC max
\PDF\ destination pointer
\NC \NR
142 \NC dest_names_size
\NC \PDF\ destination table size
\NC \NR
143 \NC pdf_mem_ptr
\NC max
\PDF\ memory used
\NC \NR
144 \NC pdf_mem_size
\NC \PDF\ memory size
\NC \NR
145 \NC largest_used_mark
\NC max referenced marks class
\NC \NR
146 \NC filename
\NC name of the current input file
\NC \NR
147 \NC inputid
\NC numeric id of the current input
\NC \NR
148 \NC linenumber
\NC location in the current input file
\NC \NR
149 \NC lasterrorstring
\NC last
\TEX\ error string
\NC \NR
150 \NC lastluaerrorstring
\NC last
\LUA\ error string
\NC \NR
151 \NC lastwarningtag
\NC last warning string
\NC \NR
152 \NC lastwarningstring
\NC last warning tag, normally an indication of in what part
\NC \NR
153 \NC lasterrorcontext
\NC last error context string (with newlines)
\NC \NR
154 \NC luabytecodes
\NC number of active
\LUA\ bytecode registers
\NC \NR
155 \NC luabytecode_bytes
\NC number of bytes in
\LUA\ bytecode registers
\NC \NR
156 \NC luastate_bytes
\NC number of bytes in use by
\LUA\ interpreters
\NC \NR
157 \NC output_active
\NC \type {true
} if the
\type {\output} routine is active
\NC \NR
158 \NC callbacks
\NC total number of executed callbacks so far
\NC \NR
159 \NC indirect_callbacks
\NC number of those that were themselves
160 a result of other callbacks (e.g. file readers)
\NC \NR
161 \NC luatex_version
\NC the
\LUATEX\ version number
\NC \NR
162 \NC luatex_revision
\NC the
\LUATEX\ revision string
\NC \NR
163 \NC ini_version
\NC \type {true
} if this is an
\INITEX\ run
\NC \NR
164 \NC shell_escape
\NC \type {0} means disabled,
\type {1} is restricted and
165 \type {2} means anything is permitted
\NC \NR
168 The error and warning messages can be wiped with the
\type {resetmessages
}
171 \section{The
\type {tex
} library
}
173 The
\type {tex
} table contains a large list of virtual internal
\TEX\
174 parameters that are partially writable.
176 The designation
\quote {virtual
} means that these items are not properly defined
177 in
\LUA, but are only front\-ends that are handled by a metatable that operates
178 on the actual
\TEX\ values. As a result, most of the
\LUA\ table operators (like
179 \type {pairs
} and
\type {#
}) do not work on such items.
181 At the moment, it is possible to access almost every parameter that has these
184 \startitemize[packed
]
185 \item You can use it after
\type {\the}
186 \item It is a single token.
187 \item Some special others, see the list below
190 This excludes parameters that need extra arguments, like
\type {\the\scriptfont}.
192 The subset comprising simple integer and dimension registers are
193 writable as well as readable (stuff like
\type {\tracingcommands} and
196 \subsection{Internal parameter values
}
198 For all the parameters in this section, it is possible to access them directly
199 using their names as index in the
\type {tex
} table, or by using one of the
200 functions
\type {tex.get
} and
\type {tex.set
}.
202 The exact parameters and return values differ depending on the actual parameter,
203 and so does whether
\type {tex.set
} has any effect. For the parameters that
{\it
204 can\/
} be set, it is possible to use
\type {global
} as the first argument to
205 \type {tex.set
}; this makes the assignment global instead of local.
208 tex.set (
["global",
] <string> n, ...)
209 ... = tex.get (<string> n)
212 Glue is kind of special because there are five values involved. The return value
213 is a
\type {glue_spec
} node btu when you pass
\type {false
} as last argument to
214 \type {tex.get
} you get the width of the glue and when you pass
\type {true
} you
215 get all five values. Otherwise you get a node which is a copy of the internal
216 value so you are responsible for its freeing at the
\LUA\ end. When you set a
217 glue quantity you can either pass a
\type {glue_spec
} or upto five numbers.
219 For the registers you can use
\type {getskip
} (node),
\type {getglue
} (numbers)
220 \type {setskip
} (node) and
\type {setglue
} (numbers).
222 There are also dedicated setters, getters and checkers:
225 local d = tex.getdimen("foo")
226 if tex.isdimen("bar") then
227 tex.setdimen("bar",d)
231 There are such helpers for
\type {dimen
},
\type {count
},
\type {skip
},
\type
232 {box
} and
\type {attribute
} registers.
234 \subsubsection{Integer parameters
}
236 The integer parameters accept and return
\LUA\ numbers.
248 tex.defaulthyphenchar
251 tex.displaywidowpenalty
252 tex.doublehyphendemerits
254 tex.errorcontextlines
258 tex.finalhyphendemerits
270 tex.localbrokenpenalty
271 tex.localinterlinepenalty
279 tex.postdisplaypenalty
280 tex.predisplaydirection
281 tex.predisplaypenalty
301 tex.tracingparagraphs
303 tex.tracingscantokens
324 \subsubsection{Dimension parameters
}
326 The dimension parameters accept
\LUA\ numbers (signifying scaled points) or
327 strings (with included dimension). The result is always a number in scaled
335 tex.delimitershortfall
346 tex.nulldelimiterspace
382 Beware: as with all
\LUA\ tables you can add values to them. So, the following is valid:
388 When you access a
\TEX\ parameter a look up takes place. For read||only variables
389 that means that you will get something back, but when you set them you create a
390 new entry in the table thereby making the original invisible.
392 There are a few special cases that we make an exception for:
\type {prevdepth
},
393 \type {prevgraf
} and
\type {spacefactor
}. These normally are accessed via the
394 \type {tex.nest
} table:
397 tex.nest
[tex.nest.ptr
].prevdepth = p
398 tex.nest
[tex.nest.ptr
].spacefactor = s
401 However, the following also works:
408 Keep in mind that when you mess with node lists directly at the
\LUA\ end you
409 might need to update the top of the nesting stack's
\type {prevdepth
} explicitly
410 as there is no way
\LUATEX\ can guess your intentions. By using the accessor in
411 the
\type {tex
} tables, you get and set the values atthe top of the nest stack.
413 \subsubsection{Direction parameters
}
415 The direction parameters are read|-|only and return a
\LUA\ string.
427 \subsubsection{Glue parameters
}
429 The glue parameters accept and return a userdata object that represents a
\type
434 tex.abovedisplayshortskip
437 tex.belowdisplayshortskip
452 \subsubsection{Muglue parameters
}
454 All muglue parameters are to be used read|-|only and return a
\LUA\ string.
464 \subsubsection{Tokenlist parameters
}
466 The tokenlist parameters accept and return
\LUA\ strings.
\LUA\ strings are
467 converted to and from token lists using
\type {\the} \type {\toks} style expansion:
468 all category codes are either space (
10) or other (
12). It follows that assigning
469 to some of these, like
\quote {tex.output
}, is actually useless, but it feels bad
470 to make exceptions in view of a coming extension that will accept full|-|blown
488 \subsection{Convert commands
}
490 All
\quote {convert
} commands are read|-|only and return a
\LUA\ string. The
491 supported commands at this moment are:
502 tex.uniformdeviate(number)
504 tex.romannumeral(number)
505 tex.fontidentifier(number)
509 If you are wondering why this list looks haphazard; these are all the cases of
510 the
\quote {convert
} internal command that do not require an argument, as well as
511 the ones that require only a simple numeric value.
513 The special (lua-only) case of
\type {tex.fontidentifier
} returns the
\type
514 {csname
} string that matches a font id number (if there is one).
516 if these are really needed in a macro package.
518 \subsection{Last item commands
}
520 All
\quote {last item
} commands are read|-|only and return a number.
522 The supported commands at this moment are:
537 tex.currentgrouplevel
545 \subsection{Attribute, count, dimension, skip and token registers
}
547 \TEX's attributes (
\type {\attribute}), counters (
\type {\count}), dimensions (
\type
548 {\dimen}), skips (
\type {\skip}) and token (
\type {\toks}) registers can be accessed
549 and written to using two times five virtual sub|-|tables of the
\type {tex
}
562 It is possible to use the names of relevant
\type {\attributedef},
\type {\countdef},
563 \type {\dimendef},
\type {\skipdef}, or
\type {\toksdef} control sequences as indices
567 tex.count.scratchcounter =
0
568 enormous = tex.dimen
['maxdimen'
]
571 In this case,
\LUATEX\ looks up the value for you on the fly. You have to use a
572 valid
\type {\countdef} (or
\type {\attributedef}, or
\type {\dimendef}, or
\type
573 {\skipdef}, or
\type {\toksdef}), anything else will generate an error (the intent
574 is to eventually also allow
\type {<chardef tokens>
} and even macros that expand
577 The attribute and count registers accept and return
\LUA\ numbers.
579 The dimension registers accept
\LUA\ numbers (in scaled points) or strings (with
580 an included absolute dimension;
\type {em
} and
\type {ex
} and
\type {px
} are
581 forbidden). The result is always a number in scaled points.
583 The token registers accept and return
\LUA\ strings.
\LUA\ strings are converted
584 to and from token lists using
\type {\the} \type {\toks} style expansion: all
585 category codes are either space (
10) or other (
12).
587 The skip registers accept and return
\type {glue_spec
} userdata node objects (see
588 the description of the node interface elsewhere in this manual).
590 As an alternative to array addressing, there are also accessor functions defined
591 for all cases, for example, here is the set of possibilities for
\type {\skip}
595 tex.setskip (
["global",
] <number> n, <node> s)
596 tex.setskip (
["global",
] <string> s, <node> s)
597 <node> s = tex.getskip (<number> n)
598 <node> s = tex.getskip (<string> s)
601 We have similar setters for
\type {count
},
\type {dimen
},
\type {muskip
}, and
602 \type {toks
}. Counters and dimen are represented by numbers, skips and muskips by
603 nodes, and toks by strings. For tokens registers we have an alternative where a
604 catcode table is specified:
607 tex.scantoks(
0,
3,"$e=mc^
2$")
608 tex.scantoks("global",
0,"$
\int\limits^
1_2$")
611 In the function-based interface, it is possible to define values globally by
612 using the string
\type {global
} as the first function argument.
614 There are four extra skip related helpers:
617 tex.setglue (
["global"
], <number> n,
618 width, stretch, shrink, stretch_order, shrink_order)
619 tex.setglue (
["global"
], <string> s,
620 width, stretch, shrink, stretch_order, shrink_order)
621 width, stretch, shrink, stretch_order, shrink_order =
622 tex.getglue (<number> n)
623 width, stretch, shrink, stretch_order, shrink_order =
624 tex.getglue (<string> s)
627 The other two are
\type {tex.setmuglue
} and
\type {tex.getmuglue
}.
629 \subsection{Character code registers
}
631 \TEX's character code tables (
\type {\lccode},
\type {\uccode},
\type {\sfcode},
\type
632 {\catcode},
\type {\mathcode},
\type {\delcode}) can be accessed and written to using
633 six virtual subtables of the
\type {tex
} table
646 The function call interfaces are roughly as above, but there are a few twists.
647 \type {sfcode
}s are the simple ones:
650 tex.setsfcode (
["global",
] <number> n, <number> s)
651 <number> s = tex.getsfcode (<number> n)
654 The function call interface for
\type {lccode
} and
\type {uccode
} additionally
655 allows you to set the associated sibling at the same time:
658 tex.setlccode (
["global"
], <number> n, <number> lc)
659 tex.setlccode (
["global"
], <number> n, <number> lc, <number> uc)
660 <number> lc = tex.getlccode (<number> n)
661 tex.setuccode (
["global"
], <number> n, <number> uc)
662 tex.setuccode (
["global"
], <number> n, <number> uc, <number> lc)
663 <number> uc = tex.getuccode (<number> n)
666 The function call interface for
\type {catcode
} also allows you to specify a
667 category table to use on assignment or on query (default in both cases is the
671 tex.setcatcode (
["global"
], <number> n, <number> c)
672 tex.setcatcode (
["global"
], <number> cattable, <number> n, <number> c)
673 <number> lc = tex.getcatcode (<number> n)
674 <number> lc = tex.getcatcode (<number> cattable, <number> n)
677 The interfaces for
\type {delcode
} and
\type {mathcode
} use small array tables to
678 set and retrieve values:
681 tex.setmathcode (
["global"
], <number> n, <table> mval )
682 <table> mval = tex.getmathcode (<number> n)
683 tex.setdelcode (
["global"
], <number> n, <table> dval )
684 <table> dval = tex.getdelcode (<number> n)
687 Where the table for
\type {mathcode
} is an array of
3 numbers, like this:
697 And the table for
\type {delcode
} is an array with
4 numbers, like this:
708 You can also avoid the table:
711 tex.setmathcode (
["global"
], <number> n, <number> class,
712 <number> family, <number> character)
713 class, family, char =
714 tex.getmathcodes (<number> n)
715 tex.setdelcode (
["global"
], <number> n, <number> smallfam,
716 <number> smallchar, <number> largefam, <number> largechar)
717 smallfam, smallchar, largefam, largechar =
718 tex.getdelcodes (<number> n)
721 Normally, the third and fourth values in a delimiter code assignment will be zero
722 according to
\type {\Udelcode} usage, but the returned table can have values there
723 (if the delimiter code was set using
\type {\delcode}, for example). Unset
\type
724 {delcode
}'s can be recognized because
\type {dval
[1]} is $-
1$.
726 \subsection{Box registers
}
728 It is possible to set and query actual boxes, using the node interface as defined
729 in the
\type {node
} library:
738 tex.setbox(
["global",
] <number> n, <node> s)
739 tex.setbox(
["global",
] <string> cs, <node> s)
740 <node> n = tex.getbox(<number> n)
741 <node> n = tex.getbox(<string> cs)
744 for function|-|based access. In the function-based interface, it is possible to
745 define values globally by using the string
\type {global
} as the first function
748 Be warned that an assignment like
751 tex.box
[0] = tex.box
[2]
754 does not copy the node list, it just duplicates a node pointer. If
\type {\box2}
755 will be cleared by
\TEX\ commands later on, the contents of
\type {\box0} becomes
756 invalid as well. To prevent this from happening, always use
\type
757 {node.copy_list()
} unless you are assigning to a temporary variable:
760 tex.box
[0] = node.copy_list(tex.box
[2])
763 The following function will register a box for reuse (this is modelled after so
764 called xforms in
\PDF). You can (re)use the box with
\type {\useboxresource} or
765 by creating a rule node with subtype~
2.
768 local index = tex.saveboxresource(n,attributes,resources,immediate,type)
771 The optional second and third arguments are strings, the fourth is a boolean. The
772 fifth argument is a type. When set to non|-|zero the
\type {/Type
} entry is
773 omitted. A value of
1 or
3 still writes a
\type {/BBox
}, while
2 or
3 will write
776 You can generate the reference (a rule type) with:
779 local reused = tex.useboxresource(n,wd,ht,dp)
782 The dimensions are optional and the final ones are returned as extra values. The
783 following is just a bonus (no dimensions returned means that the resource is
787 local w, h, d = tex.getboxresourcedimensions(n)
793 local vlist = tex.splitbox(n,height,mode)
796 The remainder is kept in the original box and a packaged vlist is returned. This
797 operation is comparable to the
\type {\vsplit} operation. The mode can be
\type
798 {additional
} or
\type {exactly
} and concerns the split off box.
800 \subsection{Math parameters
}
802 It is possible to set and query the internal math parameters using:
805 tex.setmath(
["global",
] <string> n, <string> t, <number> n)
806 <number> n = tex.getmath(<string> n, <string> t)
809 As before an optional first parameter
\type {global
} indicates a global
812 The first string is the parameter name minus the leading
\quote {Umath
}, and the
813 second string is the style name minus the trailing
\quote {style
}. Just to be
814 complete, the values for the math parameter name are:
817 quad axis operatorsize
818 overbarkern overbarrule overbarvgap
819 underbarkern underbarrule underbarvgap
820 radicalkern radicalrule radicalvgap
821 radicaldegreebefore radicaldegreeafter radicaldegreeraise
822 stackvgap stacknumup stackdenomdown
823 fractionrule fractionnumvgap fractionnumup
824 fractiondenomvgap fractiondenomdown fractiondelsize
825 limitabovevgap limitabovebgap limitabovekern
826 limitbelowvgap limitbelowbgap limitbelowkern
827 underdelimitervgap underdelimiterbgap
828 overdelimitervgap overdelimiterbgap
829 subshiftdrop supshiftdrop subshiftdown
830 subsupshiftdown subtopmax supshiftup
831 supbottommin supsubbottommax subsupvgap
832 spaceafterscript connectoroverlapmin
833 ordordspacing ordopspacing ordbinspacing ordrelspacing
834 ordopenspacing ordclosespacing ordpunctspacing ordinnerspacing
835 opordspacing opopspacing opbinspacing oprelspacing
836 opopenspacing opclosespacing oppunctspacing opinnerspacing
837 binordspacing binopspacing binbinspacing binrelspacing
838 binopenspacing binclosespacing binpunctspacing bininnerspacing
839 relordspacing relopspacing relbinspacing relrelspacing
840 relopenspacing relclosespacing relpunctspacing relinnerspacing
841 openordspacing openopspacing openbinspacing openrelspacing
842 openopenspacing openclosespacing openpunctspacing openinnerspacing
843 closeordspacing closeopspacing closebinspacing closerelspacing
844 closeopenspacing closeclosespacing closepunctspacing closeinnerspacing
845 punctordspacing punctopspacing punctbinspacing punctrelspacing
846 punctopenspacing punctclosespacing punctpunctspacing punctinnerspacing
847 innerordspacing inneropspacing innerbinspacing innerrelspacing
848 inneropenspacing innerclosespacing innerpunctspacing innerinnerspacing
851 The values for the style parameter name are:
854 display crampeddisplay
857 scriptscript crampedscriptscript
860 The value is either a number (representing a dimension or number) or a glue spec
861 node representing a muskip for
\type {ordordspacing
} and similar spacing
864 \subsection{Special list heads
}
866 The virtual table
\type {tex.lists
} contains the set of internal registers that
867 keep track of building page lists.
869 \starttabulate[|lT|p|
]
870 \NC \bf field
\NC \bf description
\NC \NR
871 \NC page_ins_head
\NC circular list of pending insertions
\NC \NR
872 \NC contrib_head
\NC the recent contributions
\NC \NR
873 \NC page_head
\NC the current page content
\NC \NR
874 %NC temp_head \NC \NC \NR
875 \NC hold_head
\NC used for held-over items for next page
\NC \NR
876 \NC adjust_head
\NC head of the current
\type {\vadjust} list
\NC \NR
877 \NC pre_adjust_head
\NC head of the current
\type {\vadjust pre
} list
\NC \NR
878 %NC align_head \NC \NC \NR
879 \NC page_discards_head
\NC head of the discarded items of a page break
\NC \NR
880 \NC split_discards_head
\NC head of the discarded items in a vsplit
\NC \NR
883 \subsection{Semantic nest levels
}
885 The virtual table
\type {tex.nest
} contains the currently active
886 semantic nesting state. It has two main parts: a zero-based array of userdata for
887 the semantic nest itself, and the numerical value
\type {tex.nest.ptr
}, which
888 gives the highest available index. Neither the array items in
\type {tex.nest
[]}
889 nor
\type {tex.nest.ptr
} can be assigned to (as this would confuse the
890 typesetting engine beyond repair), but you can assign to the individual values
891 inside the array items, e.g.\
\type {tex.nest
[tex.nest.ptr
].prevdepth
}.
893 \type {tex.nest
[tex.nest.ptr
]} is the current nest state,
\type {tex.nest
[0]} the
894 outermost (main vertical list) level.
896 The known fields are:
898 \starttabulate[|lT|l|l|p|
]
899 \NC \rmbf key
\NC \bf type
\NC \bf modes
\NC \bf explanation
\NC \NR
900 \NC mode
\NC number
\NC all
\NC a number representing the main mode at this level:
901 \type {0} = no mode (this happens during
\type {\write}),
902 \type {1} = vertical,
903 \type {127} = horizontal,
904 \type {253} = display math,
905 \type {-
1} = internal vertical,
906 \type {-
127} = restricted horizontal,
907 \type {-
253} = inline math
\NC \NR
908 \NC modeline
\NC number
\NC all
\NC source input line where this mode was entered in,
909 negative inside the output routine
\NC \NR
910 \NC head
\NC node
\NC all
\NC the head of the current list
\NC \NR
911 \NC tail
\NC node
\NC all
\NC the tail of the current list
\NC \NR
912 \NC prevgraf
\NC number
\NC vmode
\NC number of lines in the previous paragraph
\NC \NR
913 \NC prevdepth
\NC number
\NC vmode
\NC depth of the previous paragraph
\NC \NR
914 \NC spacefactor
\NC number
\NC hmode
\NC the current space factor
\NC \NR
915 \NC dirs
\NC node
\NC hmode
\NC used for temporary storage by the line break algorithm
\NC \NR
916 \NC noad
\NC node
\NC mmode
\NC used for temporary storage of a pending fraction numerator,
917 for
\type {\over} etc.
\NC \NR
918 \NC delimptr
\NC node
\NC mmode
\NC used for temporary storage of the previous math delimiter,
919 for
\type {\middle} \NC \NR
920 \NC mathdir
\NC boolean
\NC mmode
\NC true when during math processing the
\type {\mathdir} is not
921 the same as the surrounding
\type {\textdir} \NC \NR
922 \NC mathstyle
\NC number
\NC mmode
\NC the current
\type {\mathstyle} \NC \NR
925 \subsection[sec:luaprint
]{Print functions
}
927 The
\type {tex
} table also contains the three print functions that are the
928 major interface from
\LUA\ scripting to
\TEX.
930 The arguments to these three functions are all stored in an in|-|memory virtual
931 file that is fed to the
\TEX\ scanner as the result of the expansion of
934 The total amount of returnable text from a
\type {\directlua} command is only
935 limited by available system
\RAM. However, each separate printed string has to
936 fit completely in
\TEX's input buffer.
938 The result of using these functions from inside callbacks is undefined
941 \subsubsection{\type {tex.print
}}
944 tex.print(<string> s, ...)
945 tex.print(<number> n, <string> s, ...)
947 tex.print(<number> n, <table> t)
950 Each string argument is treated by
\TEX\ as a separate input line. If there is a
951 table argument instead of a list of strings, this has to be a consecutive array
952 of strings to print (the first non-string value will stop the printing process).
954 The optional parameter can be used to print the strings using the catcode regime
955 defined by
\type {\catcodetable}~
\type {n
}. If
\type {n
} is $-
1$, the currently
956 active catcode regime is used. If
\type {n
} is $-
2$, the resulting catcodes are
957 the result of
\type {\the} \type {\toks}: all category codes are
12 (other) except for
958 the space character, that has category code
10 (space). Otherwise, if
\type {n
}
959 is not a valid catcode table, then it is ignored, and the currently active
960 catcode regime is used instead.
962 The very last string of the very last
\type {tex.print()
} command in a
\type
963 {\directlua} will not have the
\type {\endlinechar
} appended, all others do.
965 \subsubsection{\type {tex.sprint
}}
968 tex.sprint(<string> s, ...)
969 tex.sprint(<number> n, <string> s, ...)
970 tex.sprint(<table> t)
971 tex.sprint(<number> n, <table> t)
974 Each string argument is treated by
\TEX\ as a special kind of input line that
975 makes it suitable for use as a partial line input mechanism:
977 \startitemize[packed
]
979 \TEX\ does not switch to the
\quote {new line
} state, so that leading spaces
983 No
\type {\endlinechar} is inserted.
986 Trailing spaces are not removed.
988 Note that this does not prevent
\TEX\ itself from eating spaces as result of
989 interpreting the line. For example, in
992 before
\directlua{tex
.sprint("\\relax")tex
.sprint(" inbetween")}after
994 the space before
\type {in between
} will be gobbled as a result of the
\quote
995 {normal
} scanning of
\type {\relax}.
999 If there is a table argument instead of a list of strings, this has to
1000 be a consecutive array of strings to print (the first non-string value
1001 will stop the printing process).
1003 The optional argument sets the catcode regime, as with
\type {tex.print()
}.
1005 \subsubsection{\type {tex.tprint
}}
1008 tex.tprint(
{<number> n, <string> s, ...
},
{...
})
1011 This function is basically a shortcut for repeated calls to
\type
1012 {tex.sprint(<number> n, <string> s, ...)
}, once for each of the supplied argument
1015 \subsubsection{\type {tex.cprint
}}
1017 This function takes a number indicating the to be used catcode, plus either a
1018 table of strings or an argument list of strings that will be pushed into the
1022 tex.cprint(
1,"
1: $&
{\
\foo}") tex.print("\
\par") -- a lot of
\bgroup s
1023 tex.cprint(
2,"
2: $&
{\
\foo}") tex.print("\
\par") -- matching
\egroup s
1024 tex.cprint(
9,"
9: $&
{\
\foo}") tex.print("\
\par") -- all get ignored
1025 tex.cprint(
10,"
10: $&
{\
\foo}") tex.print("\
\par") -- all become spaces
1026 tex.cprint(
11,"
11: $&
{\
\foo}") tex.print("\
\par") -- letters
1027 tex.cprint(
12,"
12: $&
{\
\foo}") tex.print("\
\par") -- other characters
1028 tex.cprint(
14,"
12: $&
{\
\foo}") tex.print("\
\par") -- comment triggers
1031 \subsubsection{\type {tex.write
}}
1034 tex.write(<string> s, ...)
1035 tex.write(<table> t)
1038 Each string argument is treated by
\TEX\ as a special kind of input line that
1039 makes it suitable for use as a quick way to dump information:
1042 \item All catcodes on that line are either
\quote{space
} (for '~') or
1043 \quote{character
} (for all others).
1044 \item There is no
\type {\endlinechar} appended.
1047 If there is a table argument instead of a list of strings, this has to be a
1048 consecutive array of strings to print (the first non-string value will stop the
1051 \subsection{Helper functions
}
1053 \subsubsection{\type {tex.round
}}
1056 <number> n = tex.round(<number> o)
1059 Rounds
\LUA\ number
\type {o
}, and returns a number that is in the range of a
1060 valid
\TEX\ register value. If the number starts out of range, it generates a
1061 \quote {number to big
} error as well.
1063 \subsubsection{\type {tex.scale
}}
1066 <number> n = tex.scale(<number> o, <number> delta)
1067 <table> n = tex.scale(table o, <number> delta)
1070 Multiplies the
\LUA\ numbers
\type {o
} and
\type {delta
}, and returns a rounded
1071 number that is in the range of a valid
\TEX\ register value. In the table
1072 version, it creates a copy of the table with all numeric top||level values scaled
1073 in that manner. If the multiplied number(s) are of range, it generates
1074 \quote{number to big
} error(s) as well.
1076 Note: the precision of the output of this function will depend on your computer's
1077 architecture and operating system, so use with care! An interface to
\LUATEX's
1078 internal,
100\% portable scale function will be added at a later date.
1080 \subsubsection{\type {tex.sp
}}
1083 <number> n = tex.sp(<number> o)
1084 <number> n = tex.sp(<string> s)
1087 Converts the number
\type {o
} or a string
\type {s
} that represents an explicit
1088 dimension into an integer number of scaled points.
1090 For parsing the string, the same scanning and conversion rules are used that
1091 \LUATEX\ would use if it was scanning a dimension specifier in its
\TEX|-|like
1092 input language (this includes generating errors for bad values), expect for the
1097 only explicit values are allowed, control sequences are not handled
1100 infinite dimension units (
\type {fil...
}) are forbidden
1103 \type {mu
} units do not generate an error (but may not be useful either)
1107 \subsubsection{\type {tex.definefont
}}
1110 tex.definefont(<string> csname, <number> fontid)
1111 tex.definefont(<boolean> global, <string> csname, <number> fontid)
1114 Associates
\type {csname
} with the internal font number
\type {fontid
}. The
1115 definition is global if (and only if)
\type {global
} is specified and true (the
1116 setting of
\type {globaldefs
} is not taken into account).
1118 \subsubsection{\type {tex.getlinenumber
} and
\type {tex.setlinenumber
}}
1120 You can mess with the current line number:
1123 local n = tex.getlinenumber()
1124 tex.setlinenumber(n+
10)
1127 which can be shortcut to:
1130 tex.setlinenumber(
10,true)
1133 This might be handy when you have a callback that read numbers from a file and
1134 combines them in one line (in which case an error message probably has to refer
1135 to the original line). Interference with
\TEX's internal handling of numbers is
1138 \subsubsection{\type {tex.error
}}
1141 tex.error(<string> s)
1142 tex.error(<string> s, <table> help)
1145 This creates an error somewhat like the combination of
\type {\errhelp} and
\type
1146 {\errmessage} would. During this error, deletions are disabled.
1148 The array part of the
\type {help
} table has to contain strings, one for each
1151 \subsubsection{\type {tex.hashtokens
}}
1154 for i,v in pairs (tex.hashtokens()) do ... end
1157 Returns a list of names. This can be useful for debugging, but note that this
1158 also reports control sequences that may be unreachable at this moment due to
1159 local redefinitions: it is strictly a dump of the hash table. You can use
\type
1160 {token.create
} to inspect properties, for instance when the
\type {command
} key
1161 in a created table equals
\type {123}, you have the
\type {cmdname
} value
\type
1164 \subsection[luaprimitives
]{Functions for dealing with primitives
}
1166 \subsubsection{\type {tex.enableprimitives
}}
1169 tex.enableprimitives(<string> prefix, <table> primitive names)
1172 This function accepts a prefix string and an array of primitive names.
1174 For each combination of
\quote {prefix
} and
\quote {name
}, the
\type
1175 {tex.enableprimitives
} first verifies that
\quote {name
} is an actual primitive
1176 (it must be returned by one of the
\type {tex.extraprimitives()
} calls explained
1177 below, or part of
\TEX82, or
\type {\directlua}). If it is not,
\type
1178 {tex.enableprimitives
} does nothing and skips to the next pair.
1180 But if it is, then it will construct a csname variable by concatenating the
1181 \quote {prefix
} and
\quote {name
}, unless the
\quote {prefix
} is already the
1182 actual prefix of
\quote {name
}. In the latter case, it will discard the
\quote
1183 {prefix
}, and just use
\quote {name
}.
1185 Then it will check for the existence of the constructed csname. If the csname is
1186 currently undefined (note: that is not the same as
\type {\relax}), it will
1187 globally define the csname to have the meaning: run code belonging to the
1188 primitive
\quote {name
}. If for some reason the csname is already defined, it
1189 does nothing and tries the next pair.
1194 tex.enableprimitives('LuaTeX',
{'formatname'
})
1197 will define
\type {\LuaTeXformatname} with the same intrinsic meaning as the
1198 documented primitive
\type {\formatname}, provided that the control sequences
\type
1199 {\LuaTeXformatname} is currently undefined.
1201 When
\LUATEX\ is run with
\type {--ini
} only the
\TEX82 primitives and
\type
1202 {\directlua} are available, so no extra primitives
{\bf at all
}.
1204 If you want to have all the new functionality available using their default
1205 names, as it is now, you will have to add
1208 \ifx\directlua\undefined \else
1209 \directlua {tex
.enableprimitives('',tex
.extraprimitives ())}
1213 near the beginning of your format generation file. Or you can choose different
1214 prefixes for different subsets, as you see fit.
1216 Calling some form of
\type {tex.enableprimitives()
} is highly important though,
1217 because if you do not, you will end up with a
\TEX82-lookalike that can run
\LUA\
1218 code but not do much else. The defined csnames are (of course) saved in the
1219 format and will be available at runtime.
1221 \subsubsection{\type {tex.extraprimitives
}}
1224 <table> t = tex.extraprimitives(<string> s, ...)
1227 This function returns a list of the primitives that originate from the engine(s)
1228 given by the requested string value(s). The possible values and their (current)
1232 function
document.showprimitives(tag)
1233 for k, v in table.sortedpairs(tex.extraprimitives(tag)) do
1235 v = '\
\normalcontrolspace'
1243 \starttabulate[|l|pl|
]
1244 \NC \bf name
\NC \bf values
\NC \NR
1245 \NC tex
\NC \ctxlua{document.showprimitives('tex')
} \NC \NR
1246 \NC core
\NC \ctxlua{document.showprimitives('core')
} \NC \NR
1247 \NC etex
\NC \ctxlua{document.showprimitives('etex')
} \NC \NR
1248 \NC luatex
\NC \ctxlua{document.showprimitives('luatex')
} \NC \NR
1251 Note that
\type {luatex
} does not contain
\type {directlua
}, as that is
1252 considered to be a core primitive, along with all the
\TEX82 primitives, so it is
1253 part of the list that is returned from
\type {'core'
}.
1255 % \type {'umath'} is a subset of \type {'luatex'} that covers the Unicode math
1256 % primitives as it might be desired to handle the prefixing of that subset
1259 Running
\type {tex.extraprimitives()
} will give you the complete list of
1260 primitives
\type {-ini
} startup. It is exactly equivalent to
\type
1261 {tex.extraprimitives("etex","luatex")
}.
1263 \subsubsection{\type {tex.primitives
}}
1266 <table> t = tex.primitives()
1269 This function returns a list of all primitives that
\LUATEX\ knows about.
1271 \subsection{Core functionality interfaces
}
1273 \subsubsection{\type {tex.badness
}}
1276 <number> b = tex.badness(<number> t, <number> s)
1279 This helper function is useful during linebreak calculations.
\type {t
} and
\type
1280 {s
} are scaled values; the function returns the badness for when total
\type {t
}
1281 is supposed to be made from amounts that sum to
\type {s
}. The returned number is
1282 a reasonable approximation of $
100(t/s)^
3$;
1284 \subsubsection{\type {tex.resetparagraph
}}
1286 This function resets the parameters that
\TEX\ normally resets when a new paragraph
1289 \subsubsection{\type {tex.linebreak
}}
1292 local <node> nodelist, <table> info =
1293 tex.linebreak(<node> listhead, <table> parameters)
1296 The understood parameters are as follows:
1298 \starttabulate[|l|l|p|
]
1299 \NC \bf name
\NC \bf type
\NC \bf description
\NC \NR
1300 \NC pardir
\NC string
\NC \NC \NR
1301 \NC pretolerance
\NC number
\NC \NC \NR
1302 \NC tracingparagraphs
\NC number
\NC \NC \NR
1303 \NC tolerance
\NC number
\NC \NC \NR
1304 \NC looseness
\NC number
\NC \NC \NR
1305 \NC hyphenpenalty
\NC number
\NC \NC \NR
1306 \NC exhyphenpenalty
\NC number
\NC \NC \NR
1307 \NC pdfadjustspacing
\NC number
\NC \NC \NR
1308 \NC adjdemerits
\NC number
\NC \NC \NR
1309 \NC pdfprotrudechars
\NC number
\NC \NC \NR
1310 \NC linepenalty
\NC number
\NC \NC \NR
1311 \NC lastlinefit
\NC number
\NC \NC \NR
1312 \NC doublehyphendemerits
\NC number
\NC \NC \NR
1313 \NC finalhyphendemerits
\NC number
\NC \NC \NR
1314 \NC hangafter
\NC number
\NC \NC \NR
1315 \NC interlinepenalty
\NC number or table
\NC if a table, then it is an array like
\type {\interlinepenalties} \NC \NR
1316 \NC clubpenalty
\NC number or table
\NC if a table, then it is an array like
\type {\clubpenalties} \NC \NR
1317 \NC widowpenalty
\NC number or table
\NC if a table, then it is an array like
\type {\widowpenalties} \NC \NR
1318 \NC brokenpenalty
\NC number
\NC \NC \NR
1319 \NC emergencystretch
\NC number
\NC in scaled points
\NC \NR
1320 \NC hangindent
\NC number
\NC in scaled points
\NC \NR
1321 \NC hsize
\NC number
\NC in scaled points
\NC \NR
1322 \NC leftskip
\NC glue_spec node
\NC \NC \NR
1323 \NC rightskip
\NC glue_spec node
\NC \NC \NR
1324 \NC pdfignoreddimen
\NC number
\NC in scaled points
\NC \NR
1325 \NC parshape
\NC table
\NC \NC \NR
1328 Note that there is no interface for
\type {\displaywidowpenalties}, you have to
1329 pass the right choice for
\type {widowpenalties
} yourself.
1331 The meaning of the various keys should be fairly obvious from the table (the
1332 names match the
\TEX\ and
\PDFTEX\ primitives) except for the last
5 entries. The
1333 four
\type {pdf...line...
} keys are ignored if their value equals
\type
1336 It is your own job to make sure that
\type {listhead
} is a proper paragraph list:
1337 this function does not add any nodes to it. To be exact, if you want to replace
1338 the core line breaking, you may have to do the following (when you are not
1339 actually working in the
\type {pre_linebreak_filter
} or
\type {linebreak_filter
}
1340 callbacks, or when the original list starting at listhead was generated in
1345 add an
\quote {indent box
} and perhaps a
\type {local_par
} node at the start
1346 (only if you need them)
1349 replace any found final glue by an infinite penalty (or add such a penalty,
1350 if the last node is not a glue)
1353 add a glue node for the
\type {\parfillskip} after that penalty node
1356 make sure all the
\type {prev
} pointers are OK
1360 The result is a node list, it still needs to be vpacked if you want to assign it
1363 The returned
\type {info
} table contains four values that are all numbers:
1365 \starttabulate[|l|p|
]
1366 \NC prevdepth
\NC depth of the last line in the broken paragraph
\NC \NR
1367 \NC prevgraf
\NC number of lines in the broken paragraph
\NC \NR
1368 \NC looseness
\NC the actual looseness value in the broken paragraph
\NC \NR
1369 \NC demerits
\NC the total demerits of the chosen solution
\NC \NR
1372 Note there are a few things you cannot interface using this function: You cannot
1373 influence font expansion other than via
\type {pdfadjustspacing
}, because the
1374 settings for that take place elsewhere. The same is true for hbadness and hfuzz
1375 etc. All these are in the
\type {hpack()
} routine, and that fetches its own
1376 variables via globals.
1378 \subsubsection{\type {tex.shipout
}}
1381 tex.shipout(<number> n)
1384 Ships out box number
\type {n
} to the output file, and clears the box register.
1386 \section[texconfig
]{The
\type {texconfig
} table
}
1388 This is a table that is created empty. A startup
\LUA\ script could
1389 fill this table with a number of settings that are read out by
1390 the executable after loading and executing the startup file.
1392 \starttabulate[|lT|l|l|p|
]
1393 \NC \rmbf key
\NC \bf type
\NC \bf default
\NC \bf explanation
\NC \NR
1394 \NC kpse_init
\NC boolean
\NC true
1396 \type {false
} totally disables
\KPATHSEA\ initialisation, and enables
1397 interpretation of the following numeric key--value pairs. (only ever unset
1398 this if you implement
{\it all\/
} file find callbacks!)
1401 shell_escape
\NC string
\NC \type {'f'
} \NC
1402 Use
\type {'y'
} or
\type {'t'
} or
\type {'
1'
} to enable
\type {\write18}
1403 unconditionally,
\type {'p'
} to enable the commands that are listed in
\type
1404 {shell_escape_commands
}
1407 shell_escape_commands
\NC string
\NC \NC Comma-separated list of command
1408 names that may be executed by
\type {\write18} even if
\type {shell_escape
}
1409 is set to
\type {'p'
}. Do
{\it not\/
} use spaces around commas, separate any
1410 required command arguments by using a space, and use the
\ASCII\ double quote
1411 (
\type {"
}) for any needed argument or path quoting
1414 \NC string_vacancies
\NC number
\NC 75000 \NC cf.\ web2c docs
\NC \NR
1415 \NC pool_free
\NC number
\NC 5000 \NC cf.\ web2c docs
\NC \NR
1416 \NC max_strings
\NC number
\NC 15000 \NC cf.\ web2c docs
\NC \NR
1417 \NC strings_free
\NC number
\NC 100 \NC cf.\ web2c docs
\NC \NR
1418 \NC nest_size
\NC number
\NC 50 \NC cf.\ web2c docs
\NC \NR
1419 \NC max_in_open
\NC number
\NC 15 \NC cf.\ web2c docs
\NC \NR
1420 \NC param_size
\NC number
\NC 60 \NC cf.\ web2c docs
\NC \NR
1421 \NC save_size
\NC number
\NC 4000 \NC cf.\ web2c docs
\NC \NR
1422 \NC stack_size
\NC number
\NC 300 \NC cf.\ web2c docs
\NC \NR
1423 \NC dvi_buf_size
\NC number
\NC 16384 \NC cf.\ web2c docs
\NC \NR
1424 \NC error_line
\NC number
\NC 79 \NC cf.\ web2c docs
\NC \NR
1425 \NC half_error_line
\NC number
\NC 50 \NC cf.\ web2c docs
\NC \NR
1426 \NC max_print_line
\NC number
\NC 79 \NC cf.\ web2c docs
\NC \NR
1427 \NC hash_extra
\NC number
\NC 0 \NC cf.\ web2c docs
\NC \NR
1428 \NC pk_dpi
\NC number
\NC 72 \NC cf.\ web2c docs
\NC \NR
1429 \NC trace_file_names
\NC boolean
\NC true
1431 \type {false
} disables
\TEX's normal file open|-|close feedback (the
1432 assumption is that callbacks will take care of that)
1434 \NC file_line_error
\NC boolean
\NC false
1436 do
\type {file:line
} style error messages
1438 \NC halt_on_error
\NC boolean
\NC false
1440 abort run on the first encountered error
1442 \NC formatname
\NC string
\NC
1444 if no format name was given on the command line, this key will be tested first
1445 instead of simply quitting
1447 \NC jobname
\NC string
\NC
1449 if no input file name was given on the command line, this key will be tested
1450 first instead of simply giving up
1454 Note: the numeric values that match web2c parameters are only used if
\type
1455 {kpse_init
} is explicitly set to
\type {false
}. In all other cases, the normal
1456 values from
\type {texmf.cnf
} are used.
1458 \section{The
\type {texio
} library
}
1460 This library takes care of the low|-|level I/O interface: writing to the log file
1463 \subsection{\type {texio.write
}}
1466 texio.write(<string> target, <string> s, ...)
1467 texio.write(<string> s, ...)
1470 Without the
\type {target
} argument, writes all given strings to the same
1471 location(s)
\TEX\ writes messages to at this moment. If
\type {\batchmode} is in
1472 effect, it writes only to the log, otherwise it writes to the log and the
1473 terminal. The optional
\type {target
} can be one of three possibilities:
\type
1474 {term
},
\type {log
} or
\type {term and log
}.
1476 Note: If several strings are given, and if the first of these strings is or might
1477 be one of the targets above, the
\type {target
} must be specified explicitly to
1478 prevent
\LUA\ from interpreting the first string as the target.
1480 \subsection{\type {texio.write_nl
}}
1483 texio.write_nl(<string> target, <string> s, ...)
1484 texio.write_nl(<string> s, ...)
1487 This function behaves like
\type {texio.write
}, but make sure that the given
1488 strings will appear at the beginning of a new line. You can pass a single empty
1489 string if you only want to move to the next line.
1491 \subsection{\type {texio.setescape
}}
1493 You can disable
\type {^^
} escaping of control characters by passing a value of
1496 \section{The
\type {token
} library
}
1498 \subsection{The scanner
}
1500 The token library provides means to intercept the input and deal with it at the
1501 \LUA\ level. The library provides a basic scanner infrastructure that can be used
1502 to write macros that accept a wide range of arguments. This interface is on
1503 purpose kept general and as performance is quite ok one can build additional
1504 parsers without too much overhead. It's up to macro package writers to see how
1505 they can benefit from this as the main principle behind
\LUATEX\ is to provide a
1506 minimal set of tools and no solutions. The functions provided in the
\type
1507 {token
} namespace are given in the next table:
1509 \starttabulate[|lT|lT|p|
]
1510 \NC \bf function
\NC \bf argument
\NC \bf result
\NC \NR
1512 \NC is_token
\NC token
\NC checks if the given argument is a token userdatum
\NC \NR
1513 \NC get_next
\NC \NC returns the next token in the input
\NC \NR
1514 \NC scan_keyword
\NC string
\NC returns true if the given keyword is gobbled
\NC \NR
1515 \NC scan_int
\NC \NC returns a number
\NC \NR
1516 \NC scan_dimen
\NC infinity, mu-units
\NC returns a number representing a dimension and or two numbers being the filler and order
\NC \NR
1517 \NC scan_glue
\NC mu-units
\NC returns a glue spec node
\NC \NR
1518 \NC scan_toks
\NC definer, expand
\NC returns a table of tokens token list (this can become a linked list in later releases)
\NC \NR
1519 \NC scan_code
\NC bitset
\NC returns a character if its category is in the given bitset (representing catcodes)
\NC \NR
1520 \NC 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
1521 \NC scan_word
\NC \NC returns a sequence of characters with catcode
11 or
12 as string
\NC \NR
1522 \NC scan_csname
\NC \NC returns
\type {foo
} after scanning
\type {\foo} \NC \NR
1523 \NC set_macro
\NC see below
\NC assign a macro
\NC \NR
1524 \NC create
\NC \NC returns a userdata token object of the given control sequence name (or character); this interface can change
\NC \NR
1527 The scanners can be considered stable apart from the one scanning for a token.
1528 This is because futures releases can return a linked list instead of a table (as
1529 with nodes). The
\type {scan_code
} function takes an optional number, the
\type
1530 {keyword
} function a normal
\LUA\ string. The
\type {infinity
} boolean signals
1531 that we also permit
\type {fill
} as dimension and the
\type {mu-units
} flags the
1532 scanner that we expect math units. When scanning tokens we can indicate that we
1533 are defining a macro, in which case the result will also provide information
1534 about what arguments are expected and in the result this is separated from the
1535 meaning by a separator token. The
\type {expand
} flag determines if the list will
1538 The string scanner scans for something between curly braces and expands on the
1539 way, or when it sees a control sequence it will return its meaning. Otherwise it
1540 will scan characters with catcode
\type {letter
} or
\type {other
}. So, given the
1541 following definition:
1548 \typebuffer \getbuffer
1552 \starttabulate[|l|Tl|l|
]
1553 \NC \type {\directlua{token
.scan_string()}{foo
}} \NC \directlua{context("
{\
\red\
\type {"..token.scan_string().."
}}")
} {foo
} \NC full expansion
\NR
1554 \NC \type {\directlua{token
.scan_string()}foo
} \NC \directlua{context("
{\
\red\
\type {"..token.scan_string().."
}}")
} foo
\NC letters and others
\NR
1555 \NC \type {\directlua{token
.scan_string()}\foo} \NC \directlua{context("
{\
\red\
\type {"..token.scan_string().."
}}")
}\foo \NC meaning
\NR
1558 The
\type {\foo} case only gives the meaning, but one can pass an already
1559 expanded definition (
\type {\edef}'d). In the case of the braced variant one can of
1560 course use the
\type {\detokenize} and
\type {\unexpanded} primitives as there we
1563 The
\type {scan_word
} scanner can be used to implement for instance a number scanner:
1566 function token.scan_number(base)
1567 return tonumber(token.scan_word(),base)
1571 This scanner accepts any valid
\LUA\ number so it is a way to pick up floats
1574 The creator function can be used as follows:
1577 local t = token.create("relax")
1580 This gives back a token object that has the properties of the
\type {\relax}
1581 primitive. The possible properties of tokens are:
1583 \starttabulate[|lT|p|
]
1584 \NC command
\NC a number representing the internal command number
\NC \NR
1585 \NC cmdname
\NC the type of the command (for instance the catcode in case of a
1586 character or the classifier that determines the internal
1588 \NC csname
\NC the associated control sequence (if applicable)
\NC \NR
1589 \NC id
\NC the unique id of the token
\NC \NR
1590 %NC tok \NC \NC \NR % might change
1591 \NC active
\NC a boolean indicating the active state of the token
\NC \NR
1592 \NC expandable
\NC a boolean indicating if the token (macro) is expandable
\NC \NR
1593 \NC protected
\NC a boolean indicating if the token (macro) is protected
\NC \NR
1596 The numbers that represent a catcode are the same as in
\TEX\ itself, so using
1597 this information assumes that you know a bit about
\TEX's internals. The other
1598 numbers and names are used consistently but are not frozen. So, when you use them
1599 for comparing you can best query a known primitive or character first to see the
1602 More interesting are the scanners. You can use the
\LUA\ interface as follows:
1613 mymacro(\number
\dimexpr
#1)
1621 You can also do this:
1626 local d
= token
.scan_dimen()
1641 It is quite clear from looking at the code what the first method needs as
1642 argument(s). For the second method you need to look at the
\LUA\ code to see what
1643 gets picked up. Instead of passing from
\TEX\ to
\LUA\ we let
\LUA\ fetch from
1646 In the first case the input is tokenized and then turned into a string when it's
1647 passed to
\LUA\ where it gets interpreted. In the second case only a function
1648 call gets interpreted but then the input is picked up by explicitly calling the
1649 scanner functions. These return proper
\LUA\ variables so no further conversion
1650 has to be done. This is more efficient but in practice (given what
\TEX\ has to
1651 do) this effect should not be overestimated. For numbers and dimensions it saves a
1652 bit but for passing strings conversion to and from tokens has to be done anyway
1653 (although we can probably speed up the process in later versions if needed).
1657 The
\type {set_macro
} function can get upto
4 arguments:
1660 setmacro("csname","content")
1661 setmacro("csname","content","global")
1665 You can pass a catcodetable identifier as first argument:
1668 setmacro(catcodetable,"csname","content")
1669 setmacro(catcodetable,"csname","content","global")
1670 setmacro(catcodetable,"csname")
1673 The results are like:
1676 \def\csname{content
}
1677 \gdef\csname{content
}
1681 \subsection{Pushing back
}
1683 There is a (for now) experimental putter:
1686 local t1 = token.get_next()
1687 local t2 = token.get_next()
1688 local t3 = token.get_next()
1689 local t4 = token.get_next()
1690 -- watch out, we flush in sequence
1691 token.put_next
{ t1, t2
}
1692 -- but this one gets pushed in front
1693 token.put_next ( t3, t4 )
1696 When we scan
\type {wxyz!
} we get
\type {yzwx!
} back. The argument is either a table
1697 with tokens or a list of tokens.
1699 \subsection{Nota bene
}
1701 When scanning for the next token you need to keep in mind that we're not scanning
1702 like
\TEX\ does: expanding, changing modes and doing things as it goes. When we
1703 scan with
\LUA\ we just pick up tokens. Say that we have:
1709 but
\type {\bar} is undefined. Normally
\TEX\ will then issue an error message.
1710 However, when we have:
1716 We get no error, unless we expand
\type {\foo} while
\type {\bar} is still
1717 undefined. What happens is that as soon as
\TEX\ sees an undefined macro it will
1718 create a hash entry and when later it gets defined that entry will be reused. So,
1719 \type {\bar} really exists but can be in an undefined state.
1722 bar :
\directlua{tex
.print(token
.scan_csname())}\bar
1723 foo :
\directlua{tex
.print(token
.scan_csname())}\foo
1724 myfirstbar :
\directlua{tex
.print(token
.scan_csname())}\myfirstbar
1731 This was entered as:
1735 The reason that you see
\type {bar
} reported and not
\type {myfirstbar
} is that
1736 \type {\bar} was already used in a previous paragraph.
1744 \typebuffer \getbuffer
1758 \typebuffer \getbuffer
1766 When scanning from
\LUA\ we are not in a mode that defines (undefined) macros at
1767 all. There we just get the real primitive undefined macro token.
1770 \directlua{local t
= token
.get_next() tex
.print(t
.id
.." "..t
.tok
)}\myfirstbar
1771 \directlua{local t
= token
.get_next() tex
.print(t
.id
.." "..t
.tok
)}\mysecondbar
1772 \directlua{local t
= token
.get_next() tex
.print(t
.id
.." "..t
.tok
)}\mythirdbar
1779 This was generated with:
1783 So, we do get a unique token because after all we need some kind of
\LUA\ object
1784 that can be used and garbage collected, but it is basically the same one,
1785 representing an undefined control sequence.
1787 \section{The
\type {kpse
} library
}
1789 This library provides two separate, but nearly identical interfaces to the
1790 \KPATHSEA\ file search functionality: there is a
\quote {normal
} procedural
1791 interface that shares its kpathsea instance with
\LUATEX\ itself, and an object
1792 oriented interface that is completely on its own.
1794 \subsection{\type {kpse.set_program_name
} and
\type {kpse.new
}}
1796 Before the search library can be used at all, its database has to be initialized.
1797 There are three possibilities, two of which belong to the procedural interface.
1799 First, when
\LUATEX\ is used to typeset documents, this initialization happens
1800 automatically and the
\KPATHSEA\ executable and program names are set to
\type
1801 {luatex
} (that is, unless explicitly prohibited by the user's startup script.
1802 See~
\in {section
} [init
] for more details).
1804 Second, in
\TEXLUA\ mode, the initialization has to be done explicitly via the
1805 \type {kpse.set_program_name
} function, which sets the
\KPATHSEA\ executable
1806 (and optionally program) name.
1809 kpse.set_program_name(<string> name)
1810 kpse.set_program_name(<string> name, <string> progname)
1813 The second argument controls the use of the
\quote {dotted
} values in the
\type
1814 {texmf.cnf
} configuration file, and defaults to the first argument.
1816 Third, if you prefer the object oriented interface, you have to call a different
1817 function. It has the same arguments, but it returns a userdata variable.
1820 local kpathsea = kpse.new(<string> name)
1821 local kpathsea = kpse.new(<string> name, <string> progname)
1824 Apart from these two functions, the calling conventions of the interfaces are
1825 identical. Depending on the chosen interface, you either call
\type
1826 {kpse.find_file()
} or
\type {kpathsea:find_file()
}, with identical arguments and
1829 \subsection{\type {find_file
}}
1831 The most often used function in the library is
\type {find_file
}:
1834 <string> f = kpse.find_file(<string> filename)
1835 <string> f = kpse.find_file(<string> filename, <string> ftype)
1836 <string> f = kpse.find_file(<string> filename, <boolean> mustexist)
1837 <string> f = kpse.find_file(<string> filename, <string> ftype, <boolean> mustexist)
1838 <string> f = kpse.find_file(<string> filename, <string> ftype, <number> dpi)
1843 \startitemize[intro
]
1847 the name of the file you want to find, with or without extension.
1851 maps to the
\type {-format
} argument of
\KPSEWHICH. The supported
\type {ftype
}
1852 values are the same as the ones supported by the standalone
\type {kpsewhich
}
1853 program:
\startluacode
1868 "font feature files",
1890 "other binary files",
1897 "PostScript header",
1898 "subfont definition files",
1900 "TeX system documentation",
1901 "TeX system sources",
1914 context("
{\
\tttf \letterpercent, t
}",list)
1917 The default type is
\type {tex
}. Note: this is different from
\KPSEWHICH, which
1918 tries to deduce the file type itself from looking at the supplied extension.
1922 is similar to
\KPSEWHICH's
\type {-must-exist
}, and the default is
\type {false
}.
1923 If you specify
\type {true
} (or a non|-|zero integer), then the
\KPSE\ library
1924 will search the disk as well as the
\type {ls-R
} databases.
1928 This is used for the size argument of the formats
\type {pk
},
\type {gf
}, and
1929 \type {bitmap font
}.
\stopitemize
1932 \subsection{\type {lookup
}}
1934 A more powerful (but slower) generic method for finding files is also available.
1935 It returns a string for each found file.
1938 <string> f, ... = kpse.lookup(<string> filename, <table> options)
1941 The options match commandline arguments from
\type {kpsewhich
}:
1943 \starttabulate[|l|l|p|
]
1944 \NC \rmbf key
\NC \rmbf type
\NC \rmbf description
\NC \NR
1945 \NC debug
\NC number
\NC set debugging flags for this lookup
\NC \NR
1946 \NC format
\NC string
\NC use specific file type (see list above)
\NC \NR
1947 \NC dpi
\NC number
\NC use this resolution for this lookup; default
600\NC \NR
1948 \NC path
\NC string
\NC search in the given path
\NC \NR
1949 \NC all
\NC boolean
\NC output all matches, not just the first
\NC \NR
1950 \NC mustexist
\NC boolean
\NC search the disk as well as ls-R if necessary
\NC \NR
1951 \NC mktexpk
\NC boolean
\NC disable/enable mktexpk generation for this lookup
\NC \NR
1952 \NC mktextex
\NC boolean
\NC disable/enable mktextex generation for this lookup
\NC \NR
1953 \NC mktexmf
\NC boolean
\NC disable/enable mktexmf generation for this lookup
\NC \NR
1954 \NC mktextfm
\NC boolean
\NC disable/enable mktextfm generation for this lookup
\NC \NR
1955 \NC subdir
\NC string
1956 or table
\NC only output matches whose directory part
1957 ends with the given string(s)
\NC \NR
1960 \subsection{\type {init_prog
}}
1962 Extra initialization for programs that need to generate bitmap fonts.
1965 kpse.init_prog(<string> prefix, <number> base_dpi, <string> mfmode)
1966 kpse.init_prog(<string> prefix, <number> base_dpi, <string> mfmode, <string> fallback)
1969 \subsection{\type {readable_file
}}
1971 Test if an (absolute) file name is a readable file.
1974 <string> f = kpse.readable_file(<string> name)
1977 The return value is the actual absolute filename you should use, because the disk
1978 name is not always the same as the requested name, due to aliases and
1979 system|-|specific handling under e.g.\
\MSDOS. Returns
\type {nil
} if the file
1980 does not exist or is not readable.
1982 \subsection{\type {expand_path
}}
1984 Like kpsewhich's
\type {-expand-path
}:
1987 <string> r = kpse.expand_path(<string> s)
1990 \subsection{\type {expand_var
}}
1992 Like kpsewhich's
\type {-expand-var
}:
1995 <string> r = kpse.expand_var(<string> s)
1998 \subsection{\type {expand_braces
}}
2000 Like kpsewhich's
\type {-expand-braces
}:
2003 <string> r = kpse.expand_braces(<string> s)
2006 \subsection{\type {show_path
}}
2008 Like kpsewhich's
\type {-show-path
}:
2011 <string> r = kpse.show_path(<string> ftype)
2015 \subsection{\type {var_value
}}
2017 Like kpsewhich's
\type {-var-value
}:
2020 <string> r = kpse.var_value(<string> s)
2023 \subsection{\type {version
}}
2025 Returns the kpathsea version string.
2028 <string> r = kpse.version()