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
}. If you created aliasses,
201 you can use accessors like
\type {tex.getdimen
} as these also understand
202 names of built|-|in variables.
204 The exact parameters and return values differ depending on the actual parameter,
205 and so does whether
\type {tex.set
} has any effect. For the parameters that
{\it
206 can\/
} be set, it is possible to use
\type {global
} as the first argument to
207 \type {tex.set
}; this makes the assignment global instead of local.
210 tex.set (
["global",
] <string> n, ...)
211 ... = tex.get (<string> n)
214 There are also dedicated setters, getters and checkers:
217 local d = tex.getdimen("foo")
218 if tex.isdimen("bar") then
219 tex.setdimen("bar",d)
223 There are such helpers for
\type {dimen
},
\type {count
},
\type {skip
},
\type
224 {box
} and
\type {attribute
} registers.
226 \subsubsection{Integer parameters
}
228 The integer parameters accept and return
\LUA\ numbers.
240 tex.defaulthyphenchar
243 tex.displaywidowpenalty
244 tex.doublehyphendemerits
246 tex.errorcontextlines
250 tex.finalhyphendemerits
262 tex.localbrokenpenalty
263 tex.localinterlinepenalty
271 tex.postdisplaypenalty
272 tex.predisplaydirection
273 tex.predisplaypenalty
293 tex.tracingparagraphs
295 tex.tracingscantokens
316 \subsubsection{Dimension parameters
}
318 The dimension parameters accept
\LUA\ numbers (signifying scaled points) or
319 strings (with included dimension). The result is always a number in scaled
327 tex.delimitershortfall
338 tex.nulldelimiterspace
374 Beware: as with all
\LUA\ tables you can add values to them. So, the following is valid:
380 When you access a
\TEX\ parameter a look up takes place. For read||only variables
381 that means that you will get something back, but when you set them you create a
382 new entry in the table thereby making the original invisible.
384 There are a few special cases that we make an exception for:
\type {prevdepth
},
385 \type {prevgraf
} and
\type {spacefactor
}. These normally are accessed via the
386 \type {tex.nest
} table:
389 tex.nest
[tex.nest.ptr
].prevdepth = p
390 tex.nest
[tex.nest.ptr
].spacefactor = s
393 However, the following also works:
400 Keep in mind that when you mess with node lists directly at the
\LUA\ end you
401 might need to update the top of the nesting stack's
\type {prevdepth
} explicitly
402 as there is no way
\LUATEX\ can guess your intentions. By using the accessor in
403 the
\type {tex
} tables, you get and set the values atthe top of the nest stack.
405 \subsubsection{Direction parameters
}
407 The direction parameters are read|-|only and return a
\LUA\ string.
419 \subsubsection{Glue parameters
}
421 The glue parameters accept and return a userdata object that represents a
\type
426 tex.abovedisplayshortskip
429 tex.belowdisplayshortskip
444 \subsubsection{Muglue parameters
}
446 All muglue parameters are to be used read|-|only and return a
\LUA\ string.
456 \subsubsection{Tokenlist parameters
}
458 The tokenlist parameters accept and return
\LUA\ strings.
\LUA\ strings are
459 converted to and from token lists using
\type {\the} \type {\toks} style expansion:
460 all category codes are either space (
10) or other (
12). It follows that assigning
461 to some of these, like
\quote {tex.output
}, is actually useless, but it feels bad
462 to make exceptions in view of a coming extension that will accept full|-|blown
484 \subsection{Convert commands
}
486 All
\quote {convert
} commands are read|-|only and return a
\LUA\ string. The
487 supported commands at this moment are:
499 tex.pdffontname(number)
500 tex.pdffontobjnum(number)
501 tex.pdffontsize(number)
502 tex.uniformdeviate(number)
504 tex.romannumeral(number)
505 tex.pdfpageref(number)
506 tex.pdfxformname(number)
507 tex.fontidentifier(number)
511 If you are wondering why this list looks haphazard; these are all the cases of
512 the
\quote {convert
} internal command that do not require an argument, as well as
513 the ones that require only a simple numeric value.
515 The special (lua-only) case of
\type {tex.fontidentifier
} returns the
\type
516 {csname
} string that matches a font id number (if there is one).
518 if these are really needed in a macro package.
520 \subsection{Last item commands
}
522 All
\quote {last item
} commands are read|-|only and return a number.
524 The supported commands at this moment are:
536 tex.pdflastximagepages
545 tex.currentgrouplevel
550 tex.pdflastximagecolordepth
554 \subsection{Attribute, count, dimension, skip and token registers
}
556 \TEX's attributes (
\type {\attribute}), counters (
\type {\count}), dimensions (
\type
557 {\dimen}), skips (
\type {\skip}) and token (
\type {\toks}) registers can be accessed
558 and written to using two times five virtual sub|-|tables of the
\type {tex
}
571 It is possible to use the names of relevant
\type {\attributedef},
\type {\countdef},
572 \type {\dimendef},
\type {\skipdef}, or
\type {\toksdef} control sequences as indices
576 tex.count.scratchcounter =
0
577 enormous = tex.dimen
['maxdimen'
]
580 In this case,
\LUATEX\ looks up the value for you on the fly. You have to use a
581 valid
\type {\countdef} (or
\type {\attributedef}, or
\type {\dimendef}, or
\type
582 {\skipdef}, or
\type {\toksdef}), anything else will generate an error (the intent
583 is to eventually also allow
\type {<chardef tokens>
} and even macros that expand
586 The attribute and count registers accept and return
\LUA\ numbers.
588 The dimension registers accept
\LUA\ numbers (in scaled points) or strings (with
589 an included absolute dimension;
\type {em
} and
\type {ex
} and
\type {px
} are
590 forbidden). The result is always a number in scaled points.
592 The token registers accept and return
\LUA\ strings.
\LUA\ strings are converted
593 to and from token lists using
\type {\the} \type {\toks} style expansion: all
594 category codes are either space (
10) or other (
12).
596 The skip registers accept and return
\type {glue_spec
} userdata node objects (see
597 the description of the node interface elsewhere in this manual).
599 As an alternative to array addressing, there are also accessor functions defined
600 for all cases, for example, here is the set of possibilities for
\type {\skip}
604 tex.setskip (
["global",
] <number> n, <node> s)
605 tex.setskip (
["global",
] <string> s, <node> s)
606 <node> s = tex.getskip (<number> n)
607 <node> s = tex.getskip (<string> s)
610 We have similar setters for
\type {count
},
\type {dimen
},
\type {muskip
}, and
611 \type {toks
}. Counters and dimen are represented by numbers, skips and muskips by
612 nodes, and toks by strings. For tokens registers we have an alternative where a
613 catcode table is specified:
616 tex.scantoks(
0,
3,"$e=mc^
2$")
617 tex.scantoks("global",
0,"$
\int\limits^
1_2$")
620 In the function-based interface, it is possible to define values globally by
621 using the string
\type {global
} as the first function argument.
623 There are four extra skip related helpers:
626 tex.setglue (
["global"
], <number> n,
627 width, stretch, shrink, stretch_order, shrink_order)
628 tex.setglue (
["global"
], <string> s,
629 width, stretch, shrink, stretch_order, shrink_order)
630 width, stretch, shrink, stretch_order, shrink_order =
631 tex.getglue (<number> n)
632 width, stretch, shrink, stretch_order, shrink_order =
633 tex.getglue (<string> s)
636 The other two are
\type {tex.setmuglue
} and
\type {tex.getmuglue
}.
638 \subsection{Character code registers
}
640 \TEX's character code tables (
\type {\lccode},
\type {\uccode},
\type {\sfcode},
\type
641 {\catcode},
\type {\mathcode},
\type {\delcode}) can be accessed and written to using
642 six virtual subtables of the
\type {tex
} table
655 The function call interfaces are roughly as above, but there are a few twists.
656 \type {sfcode
}s are the simple ones:
659 tex.setsfcode (
["global",
] <number> n, <number> s)
660 <number> s = tex.getsfcode (<number> n)
663 The function call interface for
\type {lccode
} and
\type {uccode
} additionally
664 allows you to set the associated sibling at the same time:
667 tex.setlccode (
["global"
], <number> n, <number> lc)
668 tex.setlccode (
["global"
], <number> n, <number> lc, <number> uc)
669 <number> lc = tex.getlccode (<number> n)
670 tex.setuccode (
["global"
], <number> n, <number> uc)
671 tex.setuccode (
["global"
], <number> n, <number> uc, <number> lc)
672 <number> uc = tex.getuccode (<number> n)
675 The function call interface for
\type {catcode
} also allows you to specify a
676 category table to use on assignment or on query (default in both cases is the
680 tex.setcatcode (
["global"
], <number> n, <number> c)
681 tex.setcatcode (
["global"
], <number> cattable, <number> n, <number> c)
682 <number> lc = tex.getcatcode (<number> n)
683 <number> lc = tex.getcatcode (<number> cattable, <number> n)
686 The interfaces for
\type {delcode
} and
\type {mathcode
} use small array tables to
687 set and retrieve values:
690 tex.setmathcode (
["global"
], <number> n, <table> mval )
691 <table> mval = tex.getmathcode (<number> n)
692 tex.setdelcode (
["global"
], <number> n, <table> dval )
693 <table> dval = tex.getdelcode (<number> n)
696 Where the table for
\type {mathcode
} is an array of
3 numbers, like this:
706 And the table for
\type {delcode
} is an array with
4 numbers, like this:
717 You can also avoid the table:
720 class, family, char =
721 tex.getmathcodes (<number> n)
722 smallfam, smallchar, largefam, largechar =
723 tex.getdelcodes (<number> n)
726 Normally, the third and fourth values in a delimiter code assignment will be zero
727 according to
\type {\Udelcode} usage, but the returned table can have values there
728 (if the delimiter code was set using
\type {\delcode}, for example). Unset
\type
729 {delcode
}'s can be recognized because
\type {dval
[1]} is $-
1$.
731 \subsection{Box registers
}
733 It is possible to set and query actual boxes, using the node interface as defined
734 in the
\type {node
} library:
743 tex.setbox(
["global",
] <number> n, <node> s)
744 tex.setbox(
["global",
] <string> cs, <node> s)
745 <node> n = tex.getbox(<number> n)
746 <node> n = tex.getbox(<string> cs)
749 for function|-|based access. In the function-based interface, it is possible to
750 define values globally by using the string
\type {global
} as the first function
753 Be warned that an assignment like
756 tex.box
[0] = tex.box
[2]
759 does not copy the node list, it just duplicates a node pointer. If
\type {\box2}
760 will be cleared by
\TEX\ commands later on, the contents of
\type {\box0} becomes
761 invalid as well. To prevent this from happening, always use
\type
762 {node.copy_list()
} unless you are assigning to a temporary variable:
765 tex.box
[0] = node.copy_list(tex.box
[2])
768 The following function will register a box for reuse (this is modelled after so
769 called xforms in
\PDF). You can (re)use the box with
\type {\useboxresource} or
770 by creating a rule node with subtype~
2.
773 local index = tex.saveboxresource(n,attributes,resources,immediate)
776 The optional second and third arguments are strings, the fourth is a boolean.
778 You can generate the reference (a rule type) with:
781 local reused = tex.useboxresource(n,wd,ht,dp)
784 The dimensions are optional and the final ones are returned as extra values. The
785 following is just a bonus (no dimensions returned means that the resource is
789 local w, h, d = tex.getboxresourcedimensions(n)
795 local vlist = tex.splitbox(n,height,mode)
798 The remainder is kept in the original box and a packaged vlist is returned. This
799 operation is comparable to the
\type {\vsplit} operation. The mode can be
\type
800 {additional
} or
\type {exactly
} and concerns the split off box.
802 \subsection{Math parameters
}
804 It is possible to set and query the internal math parameters using:
807 tex.setmath(
["global",
] <string> n, <string> t, <number> n)
808 <number> n = tex.getmath(<string> n, <string> t)
811 As before an optional first parameter
\type {global
} indicates a global
814 The first string is the parameter name minus the leading
\quote {Umath
}, and the
815 second string is the style name minus the trailing
\quote {style
}. Just to be
816 complete, the values for the math parameter name are:
819 quad axis operatorsize
820 overbarkern overbarrule overbarvgap
821 underbarkern underbarrule underbarvgap
822 radicalkern radicalrule radicalvgap
823 radicaldegreebefore radicaldegreeafter radicaldegreeraise
824 stackvgap stacknumup stackdenomdown
825 fractionrule fractionnumvgap fractionnumup
826 fractiondenomvgap fractiondenomdown fractiondelsize
827 limitabovevgap limitabovebgap limitabovekern
828 limitbelowvgap limitbelowbgap limitbelowkern
829 underdelimitervgap underdelimiterbgap
830 overdelimitervgap overdelimiterbgap
831 subshiftdrop supshiftdrop subshiftdown
832 subsupshiftdown subtopmax supshiftup
833 supbottommin supsubbottommax subsupvgap
834 spaceafterscript connectoroverlapmin
835 ordordspacing ordopspacing ordbinspacing ordrelspacing
836 ordopenspacing ordclosespacing ordpunctspacing ordinnerspacing
837 opordspacing opopspacing opbinspacing oprelspacing
838 opopenspacing opclosespacing oppunctspacing opinnerspacing
839 binordspacing binopspacing binbinspacing binrelspacing
840 binopenspacing binclosespacing binpunctspacing bininnerspacing
841 relordspacing relopspacing relbinspacing relrelspacing
842 relopenspacing relclosespacing relpunctspacing relinnerspacing
843 openordspacing openopspacing openbinspacing openrelspacing
844 openopenspacing openclosespacing openpunctspacing openinnerspacing
845 closeordspacing closeopspacing closebinspacing closerelspacing
846 closeopenspacing closeclosespacing closepunctspacing closeinnerspacing
847 punctordspacing punctopspacing punctbinspacing punctrelspacing
848 punctopenspacing punctclosespacing punctpunctspacing punctinnerspacing
849 innerordspacing inneropspacing innerbinspacing innerrelspacing
850 inneropenspacing innerclosespacing innerpunctspacing innerinnerspacing
853 The values for the style parameter name are:
856 display crampeddisplay
859 scriptscript crampedscriptscript
862 The value is either a number (representing a dimension or number) or a glue spec
863 node representing a muskip for
\type {ordordspacing
} and similar spacing
866 \subsection{Special list heads
}
868 The virtual table
\type {tex.lists
} contains the set of internal registers that
869 keep track of building page lists.
871 \starttabulate[|lT|p|
]
872 \NC \bf field
\NC \bf description
\NC \NR
873 \NC page_ins_head
\NC circular list of pending insertions
\NC \NR
874 \NC contrib_head
\NC the recent contributions
\NC \NR
875 \NC page_head
\NC the current page content
\NC \NR
876 %NC temp_head \NC \NC \NR
877 \NC hold_head
\NC used for held-over items for next page
\NC \NR
878 \NC adjust_head
\NC head of the current
\type {\vadjust} list
\NC \NR
879 \NC pre_adjust_head
\NC head of the current
\type {\vadjust pre
} list
\NC \NR
880 %NC align_head \NC \NC \NR
881 \NC page_discards_head
\NC head of the discarded items of a page break
\NC \NR
882 \NC split_discards_head
\NC head of the discarded items in a vsplit
\NC \NR
885 \subsection{Semantic nest levels
}
887 The virtual table
\type {tex.nest
} contains the currently active
888 semantic nesting state. It has two main parts: a zero-based array of userdata for
889 the semantic nest itself, and the numerical value
\type {tex.nest.ptr
}, which
890 gives the highest available index. Neither the array items in
\type {tex.nest
[]}
891 nor
\type {tex.nest.ptr
} can be assigned to (as this would confuse the
892 typesetting engine beyond repair), but you can assign to the individual values
893 inside the array items, e.g.\
\type {tex.nest
[tex.nest.ptr
].prevdepth
}.
895 \type {tex.nest
[tex.nest.ptr
]} is the current nest state,
\type {tex.nest
[0]} the
896 outermost (main vertical list) level.
898 The known fields are:
900 \starttabulate[|lT|l|l|p|
]
901 \NC \rmbf key
\NC \bf type
\NC \bf modes
\NC \bf explanation
\NC \NR
902 \NC mode
\NC number
\NC all
\NC a number representing the main mode at this level:
903 \type {0} = no mode (this happens during
\type {\write}),
904 \type {1} = vertical,
905 \type {127} = horizontal,
906 \type {253} = display math,
907 \type {-
1} = internal vertical,
908 \type {-
127} = restricted horizontal,
909 \type {-
253} = inline math
\NC \NR
910 \NC modeline
\NC number
\NC all
\NC source input line where this mode was entered in,
911 negative inside the output routine
\NC \NR
912 \NC head
\NC node
\NC all
\NC the head of the current list
\NC \NR
913 \NC tail
\NC node
\NC all
\NC the tail of the current list
\NC \NR
914 \NC prevgraf
\NC number
\NC vmode
\NC number of lines in the previous paragraph
\NC \NR
915 \NC prevdepth
\NC number
\NC vmode
\NC depth of the previous paragraph (equal to
\type {\pdfignoreddimen}
916 when it is to be ignored)
\NC \NR
917 \NC spacefactor
\NC number
\NC hmode
\NC the current space factor
\NC \NR
918 \NC dirs
\NC node
\NC hmode
\NC used for temporary storage by the line break algorithm
\NC \NR
919 \NC noad
\NC node
\NC mmode
\NC used for temporary storage of a pending fraction numerator,
920 for
\type {\over} etc.
\NC \NR
921 \NC delimptr
\NC node
\NC mmode
\NC used for temporary storage of the previous math delimiter,
922 for
\type {\middle} \NC \NR
923 \NC mathdir
\NC boolean
\NC mmode
\NC true when during math processing the
\type {\mathdir} is not
924 the same as the surrounding
\type {\textdir} \NC \NR
925 \NC mathstyle
\NC number
\NC mmode
\NC the current
\type {\mathstyle} \NC \NR
928 \subsection[sec:luaprint
]{Print functions
}
930 The
\type {tex
} table also contains the three print functions that are the
931 major interface from
\LUA\ scripting to
\TEX.
933 The arguments to these three functions are all stored in an in|-|memory virtual
934 file that is fed to the
\TEX\ scanner as the result of the expansion of
937 The total amount of returnable text from a
\type {\directlua} command is only
938 limited by available system
\RAM. However, each separate printed string has to
939 fit completely in
\TEX's input buffer.
941 The result of using these functions from inside callbacks is undefined
944 \subsubsection{\type {tex.print
}}
947 tex.print(<string> s, ...)
948 tex.print(<number> n, <string> s, ...)
950 tex.print(<number> n, <table> t)
953 Each string argument is treated by
\TEX\ as a separate input line. If there is a
954 table argument instead of a list of strings, this has to be a consecutive array
955 of strings to print (the first non-string value will stop the printing process).
957 The optional parameter can be used to print the strings using the catcode regime
958 defined by
\type {\catcodetable}~
\type {n
}. If
\type {n
} is $-
1$, the currently
959 active catcode regime is used. If
\type {n
} is $-
2$, the resulting catcodes are
960 the result of
\type {\the} \type {\toks}: all category codes are
12 (other) except for
961 the space character, that has category code
10 (space). Otherwise, if
\type {n
}
962 is not a valid catcode table, then it is ignored, and the currently active
963 catcode regime is used instead.
965 The very last string of the very last
\type {tex.print()
} command in a
\type
966 {\directlua} will not have the
\type {\endlinechar
} appended, all others do.
968 \subsubsection{\type {tex.sprint
}}
971 tex.sprint(<string> s, ...)
972 tex.sprint(<number> n, <string> s, ...)
973 tex.sprint(<table> t)
974 tex.sprint(<number> n, <table> t)
977 Each string argument is treated by
\TEX\ as a special kind of input line that
978 makes it suitable for use as a partial line input mechanism:
980 \startitemize[packed
]
982 \TEX\ does not switch to the
\quote {new line
} state, so that leading spaces
986 No
\type {\endlinechar} is inserted.
989 Trailing spaces are not removed.
991 Note that this does not prevent
\TEX\ itself from eating spaces as result of
992 interpreting the line. For example, in
995 before
\directlua{tex
.sprint("\\relax")tex
.sprint(" inbetween")}after
997 the space before
\type {in between
} will be gobbled as a result of the
\quote
998 {normal
} scanning of
\type {\relax}.
1002 If there is a table argument instead of a list of strings, this has to
1003 be a consecutive array of strings to print (the first non-string value
1004 will stop the printing process).
1006 The optional argument sets the catcode regime, as with
\type {tex.print()
}.
1008 \subsubsection{\type {tex.tprint
}}
1011 tex.tprint(
{<number> n, <string> s, ...
},
{...
})
1014 This function is basically a shortcut for repeated calls to
\type
1015 {tex.sprint(<number> n, <string> s, ...)
}, once for each of the supplied argument
1018 \subsubsection{\type {tex.cprint
}}
1020 This function takes a number indicating the to be used catcode, plus either a
1021 table of strings or an argument list of strings that will be pushed into the
1025 tex.cprint(
1,"
1: $&
{\
\foo}") tex.print("\
\par") -- a lot of
\bgroup s
1026 tex.cprint(
2,"
2: $&
{\
\foo}") tex.print("\
\par") -- matching
\egroup s
1027 tex.cprint(
9,"
9: $&
{\
\foo}") tex.print("\
\par") -- all get ignored
1028 tex.cprint(
10,"
10: $&
{\
\foo}") tex.print("\
\par") -- all become spaces
1029 tex.cprint(
11,"
11: $&
{\
\foo}") tex.print("\
\par") -- letters
1030 tex.cprint(
12,"
12: $&
{\
\foo}") tex.print("\
\par") -- other characters
1031 tex.cprint(
14,"
12: $&
{\
\foo}") tex.print("\
\par") -- comment triggers
1034 \subsubsection{\type {tex.write
}}
1037 tex.write(<string> s, ...)
1038 tex.write(<table> t)
1041 Each string argument is treated by
\TEX\ as a special kind of input line that
1042 makes it suitable for use as a quick way to dump information:
1045 \item All catcodes on that line are either
\quote{space
} (for '~') or
1046 \quote{character
} (for all others).
1047 \item There is no
\type {\endlinechar} appended.
1050 If there is a table argument instead of a list of strings, this has to be a
1051 consecutive array of strings to print (the first non-string value will stop the
1054 \subsection{Helper functions
}
1056 \subsubsection{\type {tex.round
}}
1059 <number> n = tex.round(<number> o)
1062 Rounds
\LUA\ number
\type {o
}, and returns a number that is in the range of a
1063 valid
\TEX\ register value. If the number starts out of range, it generates a
1064 \quote {number to big
} error as well.
1066 \subsubsection{\type {tex.scale
}}
1069 <number> n = tex.scale(<number> o, <number> delta)
1070 <table> n = tex.scale(table o, <number> delta)
1073 Multiplies the
\LUA\ numbers
\type {o
} and
\type {delta
}, and returns a rounded
1074 number that is in the range of a valid
\TEX\ register value. In the table
1075 version, it creates a copy of the table with all numeric top||level values scaled
1076 in that manner. If the multiplied number(s) are of range, it generates
1077 \quote{number to big
} error(s) as well.
1079 Note: the precision of the output of this function will depend on your computer's
1080 architecture and operating system, so use with care! An interface to
\LUATEX's
1081 internal,
100\% portable scale function will be added at a later date.
1083 \subsubsection{\type {tex.sp
}}
1086 <number> n = tex.sp(<number> o)
1087 <number> n = tex.sp(<string> s)
1090 Converts the number
\type {o
} or a string
\type {s
} that represents an explicit
1091 dimension into an integer number of scaled points.
1093 For parsing the string, the same scanning and conversion rules are used that
1094 \LUATEX\ would use if it was scanning a dimension specifier in its
\TEX|-|like
1095 input language (this includes generating errors for bad values), expect for the
1100 only explicit values are allowed, control sequences are not handled
1103 infinite dimension units (
\type {fil...
}) are forbidden
1106 \type {mu
} units do not generate an error (but may not be useful either)
1110 \subsubsection{\type {tex.definefont
}}
1113 tex.definefont(<string> csname, <number> fontid)
1114 tex.definefont(<boolean> global, <string> csname, <number> fontid)
1117 Associates
\type {csname
} with the internal font number
\type {fontid
}. The
1118 definition is global if (and only if)
\type {global
} is specified and true (the
1119 setting of
\type {globaldefs
} is not taken into account).
1121 \subsubsection{\type {tex.getlinenumber
} and
\type {tex.setlinenumber
}}
1123 You can mess with the current line number:
1126 local n = tex.getlinenumber()
1127 tex.setlinenumber(n+
10)
1130 which can be shortcut to:
1133 tex.setlinenumber(
10,true)
1136 This might be handy when you have a callback that read numbers from a file and
1137 combines them in one line (in which case an error message probably has to refer
1138 to the original line). Interference with
\TEX's internal handling of numbers is
1141 \subsubsection{\type {tex.error
}}
1144 tex.error(<string> s)
1145 tex.error(<string> s, <table> help)
1148 This creates an error somewhat like the combination of
\type {\errhelp} and
\type
1149 {\errmessage} would. During this error, deletions are disabled.
1151 The array part of the
\type {help
} table has to contain strings, one for each
1154 \subsubsection{\type {tex.hashtokens
}}
1157 for i,v in pairs (tex.hashtokens()) do ... end
1160 Returns a name and token table pair (see~
\in {section
} [luatokens
] about token
1161 tables) iterator for every non-zero entry in the hash table. This can be useful
1162 for debugging, but note that this also reports control sequences that may be
1163 unreachable at this moment due to local redefinitions: it is strictly a dump of
1166 \subsection[luaprimitives
]{Functions for dealing with primitives
}
1168 \subsubsection{\type {tex.enableprimitives
}}
1171 tex.enableprimitives(<string> prefix, <table> primitive names)
1174 This function accepts a prefix string and an array of primitive names.
1176 For each combination of
\quote {prefix
} and
\quote {name
}, the
\type
1177 {tex.enableprimitives
} first verifies that
\quote {name
} is an actual primitive
1178 (it must be returned by one of the
\type {tex.extraprimitives()
} calls explained
1179 below, or part of
\TEX82, or
\type {\directlua}). If it is not,
\type
1180 {tex.enableprimitives
} does nothing and skips to the next pair.
1182 But if it is, then it will construct a csname variable by concatenating the
1183 \quote {prefix
} and
\quote {name
}, unless the
\quote {prefix
} is already the
1184 actual prefix of
\quote {name
}. In the latter case, it will discard the
\quote
1185 {prefix
}, and just use
\quote {name
}.
1187 Then it will check for the existence of the constructed csname. If the csname is
1188 currently undefined (note: that is not the same as
\type {\relax}), it will
1189 globally define the csname to have the meaning: run code belonging to the
1190 primitive
\quote {name
}. If for some reason the csname is already defined, it
1191 does nothing and tries the next pair.
1196 tex.enableprimitives('LuaTeX',
{'formatname'
})
1199 will define
\type {\LuaTeXformatname} with the same intrinsic meaning as the
1200 documented primitive
\type {\formatname}, provided that the control sequences
\type
1201 {\LuaTeXformatname} is currently undefined.
1203 When
\LUATEX\ is run with
\type {--ini
} only the
\TEX82 primitives and
\type
1204 {\directlua} are available, so no extra primitives
{\bf at all
}.
1206 If you want to have all the new functionality available using their default
1207 names, as it is now, you will have to add
1210 \ifx\directlua\undefined \else
1211 \directlua {tex
.enableprimitives('',tex
.extraprimitives ())}
1215 near the beginning of your format generation file. Or you can choose different
1216 prefixes for different subsets, as you see fit.
1218 Calling some form of
\type {tex.enableprimitives()
} is highly important though,
1219 because if you do not, you will end up with a
\TEX82-lookalike that can run
\LUA\
1220 code but not do much else. The defined csnames are (of course) saved in the
1221 format and will be available at runtime.
1223 \subsubsection{\type {tex.extraprimitives
}}
1226 <table> t = tex.extraprimitives(<string> s, ...)
1229 This function returns a list of the primitives that originate from the engine(s)
1230 given by the requested string value(s). The possible values and their (current)
1234 function
document.showprimitives(tag)
1235 for k, v in table.sortedpairs(tex.extraprimitives(tag)) do
1237 v = '\
\normalcontrolspace'
1245 \starttabulate[|l|pl|
]
1246 \NC \bf name
\NC \bf values
\NC \NR
1247 \NC tex
\NC \ctxlua{document.showprimitives('tex')
} \NC \NR
1248 \NC core
\NC \ctxlua{document.showprimitives('core')
} \NC \NR
1249 \NC etex
\NC \ctxlua{document.showprimitives('etex')
} \NC \NR
1250 \NC luatex
\NC \ctxlua{document.showprimitives('luatex')
} \NC \NR
1253 Note that
\type {'luatex'
} does not contain
\type {directlua
}, as that is
1254 considered to be a core primitive, along with all the
\TEX82 primitives, so it is
1255 part of the list that is returned from
\type {'core'
}.
1257 % \type {'umath'} is a subset of \type {'luatex'} that covers the Unicode math
1258 % primitives as it might be desired to handle the prefixing of that subset
1261 Running
\type {tex.extraprimitives()
} will give you the complete list of
1262 primitives
\type {-ini
} startup. It is exactly equivalent to
\type
1263 {tex.extraprimitives('etex' and 'luatex')
}.
1265 \subsubsection{\type {tex.primitives
}}
1268 <table> t = tex.primitives()
1271 This function returns a hash table listing all primitives that
\LUATEX\ knows
1272 about. The keys in the hash are primitives names, the values are tables
1273 representing tokens (see~
\in{section
}[luatokens
]). The third value is always
1276 {\em In the beginning we had
\type {omega
} and
\type {pdftex
} subsets but in the
1277 meantime relevant primitives ave been promoted (either or not adapted) to the
1278 \type {luatex
} set when found useful, or removed when considered to be of no use.
1279 Originally we had two sets of math definition primitives but the
\OMEGA\ ones
1280 have been removed, so we no longer have a subset for math either.
}
1282 \subsection{Core functionality interfaces
}
1284 \subsubsection{\type {tex.badness
}}
1287 <number> b = tex.badness(<number> t, <number> s)
1290 This helper function is useful during linebreak calculations.
\type {t
} and
\type
1291 {s
} are scaled values; the function returns the badness for when total
\type {t
}
1292 is supposed to be made from amounts that sum to
\type {s
}. The returned number is
1293 a reasonable approximation of $
100(t/s)^
3$;
1295 \subsubsection{\type {tex.resetparagraph
}}
1297 This function resets the parameters that
\TEX\ normally resets when a new paragraph
1300 \subsubsection{\type {tex.linebreak
}}
1303 local <node> nodelist, <table> info =
1304 tex.linebreak(<node> listhead, <table> parameters)
1307 The understood parameters are as follows:
1309 \starttabulate[|l|l|p|
]
1310 \NC \bf name
\NC \bf type
\NC \bf description
\NC \NR
1311 \NC pardir
\NC string
\NC \NC \NR
1312 \NC pretolerance
\NC number
\NC \NC \NR
1313 \NC tracingparagraphs
\NC number
\NC \NC \NR
1314 \NC tolerance
\NC number
\NC \NC \NR
1315 \NC looseness
\NC number
\NC \NC \NR
1316 \NC hyphenpenalty
\NC number
\NC \NC \NR
1317 \NC exhyphenpenalty
\NC number
\NC \NC \NR
1318 \NC pdfadjustspacing
\NC number
\NC \NC \NR
1319 \NC adjdemerits
\NC number
\NC \NC \NR
1320 \NC pdfprotrudechars
\NC number
\NC \NC \NR
1321 \NC linepenalty
\NC number
\NC \NC \NR
1322 \NC lastlinefit
\NC number
\NC \NC \NR
1323 \NC doublehyphendemerits
\NC number
\NC \NC \NR
1324 \NC finalhyphendemerits
\NC number
\NC \NC \NR
1325 \NC hangafter
\NC number
\NC \NC \NR
1326 \NC interlinepenalty
\NC number or table
\NC if a table, then it is an array like
\type {\interlinepenalties} \NC \NR
1327 \NC clubpenalty
\NC number or table
\NC if a table, then it is an array like
\type {\clubpenalties} \NC \NR
1328 \NC widowpenalty
\NC number or table
\NC if a table, then it is an array like
\type {\widowpenalties} \NC \NR
1329 \NC brokenpenalty
\NC number
\NC \NC \NR
1330 \NC emergencystretch
\NC number
\NC in scaled points
\NC \NR
1331 \NC hangindent
\NC number
\NC in scaled points
\NC \NR
1332 \NC hsize
\NC number
\NC in scaled points
\NC \NR
1333 \NC leftskip
\NC glue_spec node
\NC \NC \NR
1334 \NC rightskip
\NC glue_spec node
\NC \NC \NR
1335 \NC pdfignoreddimen
\NC number
\NC in scaled points
\NC \NR
1336 \NC parshape
\NC table
\NC \NC \NR
1339 Note that there is no interface for
\type {\displaywidowpenalties}, you have to
1340 pass the right choice for
\type {widowpenalties
} yourself.
1342 The meaning of the various keys should be fairly obvious from the table (the
1343 names match the
\TEX\ and
\PDFTEX\ primitives) except for the last
5 entries. The
1344 four
\type {pdf...line...
} keys are ignored if their value equals
\type
1347 It is your own job to make sure that
\type {listhead
} is a proper paragraph list:
1348 this function does not add any nodes to it. To be exact, if you want to replace
1349 the core line breaking, you may have to do the following (when you are not
1350 actually working in the
\type {pre_linebreak_filter
} or
\type {linebreak_filter
}
1351 callbacks, or when the original list starting at listhead was generated in
1356 add an
\quote {indent box
} and perhaps a
\type {local_par
} node at the start
1357 (only if you need them)
1360 replace any found final glue by an infinite penalty (or add such a penalty,
1361 if the last node is not a glue)
1364 add a glue node for the
\type {\parfillskip} after that penalty node
1367 make sure all the
\type {prev
} pointers are OK
1371 The result is a node list, it still needs to be vpacked if you want to assign it
1374 The returned
\type {info
} table contains four values that are all numbers:
1376 \starttabulate[|l|p|
]
1377 \NC prevdepth
\NC depth of the last line in the broken paragraph
\NC \NR
1378 \NC prevgraf
\NC number of lines in the broken paragraph
\NC \NR
1379 \NC looseness
\NC the actual looseness value in the broken paragraph
\NC \NR
1380 \NC demerits
\NC the total demerits of the chosen solution
\NC \NR
1383 Note there are a few things you cannot interface using this function: You cannot
1384 influence font expansion other than via
\type {pdfadjustspacing
}, because the
1385 settings for that take place elsewhere. The same is true for hbadness and hfuzz
1386 etc. All these are in the
\type {hpack()
} routine, and that fetches its own
1387 variables via globals.
1389 \subsubsection{\type {tex.shipout
}}
1392 tex.shipout(<number> n)
1395 Ships out box number
\type {n
} to the output file, and clears the box register.
1397 \section[texconfig
]{The
\type {texconfig
} table
}
1399 This is a table that is created empty. A startup
\LUA\ script could
1400 fill this table with a number of settings that are read out by
1401 the executable after loading and executing the startup file.
1403 \starttabulate[|lT|l|l|p|
]
1404 \NC \rmbf key
\NC \bf type
\NC \bf default
\NC \bf explanation
\NC \NR
1405 \NC kpse_init
\NC boolean
\NC true
1407 \type {false
} totally disables
\KPATHSEA\ initialisation, and enables
1408 interpretation of the following numeric key--value pairs. (only ever unset
1409 this if you implement
{\it all\/
} file find callbacks!)
1412 shell_escape
\NC string
\NC \type {'f'
} \NC
1413 Use
\type {'y'
} or
\type {'t'
} or
\type {'
1'
} to enable
\type {\write18}
1414 unconditionally,
\type {'p'
} to enable the commands that are listed in
\type
1415 {shell_escape_commands
}
1418 shell_escape_commands
\NC string
\NC \NC Comma-separated list of command
1419 names that may be executed by
\type {\write18} even if
\type {shell_escape
}
1420 is set to
\type {'p'
}. Do
{\it not\/
} use spaces around commas, separate any
1421 required command arguments by using a space, and use the
\ASCII\ double quote
1422 (
\type {"
}) for any needed argument or path quoting
1425 \NC string_vacancies
\NC number
\NC 75000 \NC cf.\ web2c docs
\NC \NR
1426 \NC pool_free
\NC number
\NC 5000 \NC cf.\ web2c docs
\NC \NR
1427 \NC max_strings
\NC number
\NC 15000 \NC cf.\ web2c docs
\NC \NR
1428 \NC strings_free
\NC number
\NC 100 \NC cf.\ web2c docs
\NC \NR
1429 \NC nest_size
\NC number
\NC 50 \NC cf.\ web2c docs
\NC \NR
1430 \NC max_in_open
\NC number
\NC 15 \NC cf.\ web2c docs
\NC \NR
1431 \NC param_size
\NC number
\NC 60 \NC cf.\ web2c docs
\NC \NR
1432 \NC save_size
\NC number
\NC 4000 \NC cf.\ web2c docs
\NC \NR
1433 \NC stack_size
\NC number
\NC 300 \NC cf.\ web2c docs
\NC \NR
1434 \NC dvi_buf_size
\NC number
\NC 16384 \NC cf.\ web2c docs
\NC \NR
1435 \NC error_line
\NC number
\NC 79 \NC cf.\ web2c docs
\NC \NR
1436 \NC half_error_line
\NC number
\NC 50 \NC cf.\ web2c docs
\NC \NR
1437 \NC max_print_line
\NC number
\NC 79 \NC cf.\ web2c docs
\NC \NR
1438 \NC hash_extra
\NC number
\NC 0 \NC cf.\ web2c docs
\NC \NR
1439 \NC pk_dpi
\NC number
\NC 72 \NC cf.\ web2c docs
\NC \NR
1440 \NC trace_file_names
\NC boolean
\NC true
1442 \type {false
} disables
\TEX's normal file open|-|close feedback (the
1443 assumption is that callbacks will take care of that)
1445 \NC file_line_error
\NC boolean
\NC false
1447 do
\type {file:line
} style error messages
1449 \NC halt_on_error
\NC boolean
\NC false
1451 abort run on the first encountered error
1453 \NC formatname
\NC string
\NC
1455 if no format name was given on the command line, this key will be tested first
1456 instead of simply quitting
1458 \NC jobname
\NC string
\NC
1460 if no input file name was given on the command line, this key will be tested
1461 first instead of simply giving up
1465 Note: the numeric values that match web2c parameters are only used if
\type
1466 {kpse_init
} is explicitly set to
\type {false
}. In all other cases, the normal
1467 values from
\type {texmf.cnf
} are used.
1469 \section{The
\type {texio
} library
}
1471 This library takes care of the low|-|level I/O interface.
1473 \subsection{Printing functions
}
1475 \subsubsection{\type {texio.write
}}
1478 texio.write(<string> target, <string> s, ...)
1479 texio.write(<string> s, ...)
1482 Without the
\type {target
} argument, writes all given strings to the same
1483 location(s)
\TEX\ writes messages to at this moment. If
\type {\batchmode} is in
1484 effect, it writes only to the log, otherwise it writes to the log and the
1485 terminal. The optional
\type {target
} can be one of three possibilities:
\type
1486 {term
},
\type {log
} or
\type {term and log
}.
1488 Note: If several strings are given, and if the first of these strings is or might
1489 be one of the targets above, the
\type {target
} must be specified explicitly to
1490 prevent
\LUA\ from interpreting the first string as the target.
1492 \subsubsection{\type {texio.write_nl
}}
1495 texio.write_nl(<string> target, <string> s, ...)
1496 texio.write_nl(<string> s, ...)
1499 This function behaves like
\type {texio.write
}, but make sure that the given
1500 strings will appear at the beginning of a new line. You can pass a single empty
1501 string if you only want to move to the next line.
1503 \subsubsection{\type {texio.setescape
}}
1505 You can disable
\type {^^
} escaping of control characters by passing a value of
1508 \section{The
\type {token
} libray
}
1510 The current
\type {token
} library will be replaced by a new one that is more
1511 flexible and powerful. The transition takes place in steps. In version
0.80 we
1512 have
\type {token
} and in version
0.85 the old lib will be replaced
1513 completely. So if you use this new mechanism in production code you need to be
1514 aware of incompatible updates between
0.80 and
0.90. Because the related in- and
1515 output code will also be cleaned up and rewritten you should be aware of
1516 incompatible logging and error reporting too.
1518 The old library presents tokens as triplets or numbers, the new library presents
1519 a userdata object. The old library used a callback to intercept tokens in the
1520 input but the new library provides a basic scanner infrastructure that can be
1521 used to write macros that accept a wide range of arguments. This interface is on
1522 purpose kept general and as performance is quite ok one can build additional
1523 parsers without too much overhead. It's up to macro package writers to see how
1524 they can benefit from this as the main principle behind
\LUATEX\ is to provide a
1525 minimal set of tools and no solutions.
1527 The current functions in the
\type {token
} namespace are given in the next
1530 \starttabulate[|lT|lT|p|
]
1531 \NC \bf function
\NC \bf argument
\NC \bf result
\NC \NR
1533 \NC is_token
\NC token
\NC checks if the given argument is a token userdatum
\NC \NR
1534 \NC get_next
\NC \NC returns the next token in the input
\NC \NR
1535 \NC scan_keyword
\NC string
\NC returns true if the given keyword is gobbled
\NC \NR
1536 \NC scan_int
\NC \NC returns a number
\NC \NR
1537 \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
1538 \NC scan_glue
\NC mu-units
\NC returns a glue spec node
\NC \NR
1539 \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
1540 \NC scan_code
\NC bitset
\NC returns a character if its category is in the given bitset (representing catcodes)
\NC \NR
1541 \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
1542 \NC scan_word
\NC \NC returns a sequence of characters with catcode
11 or
12 as string
\NC \NR
1543 \NC scan_csname
\NC \NC returns
\type {foo
} after scanning
\type {\foo} \NC \NR
1544 \NC set_macro
\NC see below
\NC assign a macro
\NC \NR
1545 \NC create
\NC \NC returns a userdata token object of the given control sequence name (or character); this interface can change
\NC \NR
1548 The scanners can be considered stable apart from the one scanning for a token.
1549 This is because futures releases can return a linked list instead of a table (as
1550 with nodes). The
\type {scan_code
} function takes an optional number, the
\type
1551 {keyword
} function a normal
\LUA\ string. The
\type {infinity
} boolean signals
1552 that we also permit
\type {fill
} as dimension and the
\type {mu-units
} flags the
1553 scanner that we expect math units. When scanning tokens we can indicate that we
1554 are defining a macro, in which case the result will also provide information
1555 about what arguments are expected and in the result this is separated from the
1556 meaning by a separator token. The
\type {expand
} flag determines if the list will
1559 The string scanner scans for something between curly braces and expands on the
1560 way, or when it sees a control sequence it will return its meaning. Otherwise it
1561 will scan characters with catcode
\type {letter
} or
\type {other
}. So, given the
1562 following definition:
1569 \typebuffer \getbuffer
1573 \starttabulate[|l|Tl|l|
]
1574 \NC \type {\directlua{token
.scan_string()}{foo
}} \NC \directlua{context("
{\
\red\
\type {"..token.scan_string().."
}}")
} {foo
} \NC full expansion
\NR
1575 \NC \type {\directlua{token
.scan_string()}foo
} \NC \directlua{context("
{\
\red\
\type {"..token.scan_string().."
}}")
} foo
\NC letters and others
\NR
1576 \NC \type {\directlua{token
.scan_string()}\foo} \NC \directlua{context("
{\
\red\
\type {"..token.scan_string().."
}}")
}\foo \NC meaning
\NR
1579 The
\type {\foo} case only gives the meaning, but one can pass an already
1580 expanded definition (
\type {\edef}'d). In the case of the braced variant one can of
1581 course use the
\type {\detokenize} and
\type {\unexpanded} primitives as there we
1584 The
\type {scan_word
} scanner can be used to implement for instance a number scanner:
1587 function token.scan_number(base)
1588 return tonumber(token.scan_word(),base)
1592 This scanner accepts any valid
\LUA\ number so it is a way to pick up floats
1595 The creator function can be used as follows:
1598 local t = token.create("relax")
1601 This gives back a token object that has the properties of the
\type {\relax}
1602 primitive. The possible properties of tokens are:
1604 \starttabulate[|lT|p|
]
1605 \NC command
\NC a number representing the internal command number
\NC \NR
1606 \NC cmdname
\NC the type of the command (for instance the catcode in case of a
1607 character or the classifier that determines the internal
1609 \NC csname
\NC the associated control sequence (if applicable)
\NC \NR
1610 \NC id
\NC the unique id of the token
\NC \NR
1611 %NC tok \NC \NC \NR % might change
1612 \NC active
\NC a boolean indicating the active state of the token
\NC \NR
1613 \NC expandable
\NC a boolean indicating if the token (macro) is expandable
\NC \NR
1614 \NC protected
\NC a boolean indicating if the token (macro) is protected
\NC \NR
1617 The numbers that represent a catcode are the same as in
\TEX\ itself, so using
1618 this information assumes that you know a bit about
\TEX's internals. The other
1619 numbers and names are used consistently but are not frozen. So, when you use them
1620 for comparing you can best query a known primitive or character first to see the
1623 More interesting are the scanners. You can use the
\LUA\ interface as follows:
1634 mymacro(\number
\dimexpr
#1)
1642 You can also do this:
1647 local d
= token
.scan_dimen()
1662 It is quite clear from looking at the code what the first method needs as
1663 argument(s). For the second method you need to look at the
\LUA\ code to see what
1664 gets picked up. Instead of passing from
\TEX\ to
\LUA\ we let
\LUA\ fetch from
1667 In the first case the input is tokenized and then turned into a string when it's
1668 passed to
\LUA\ where it gets interpreted. In the second case only a function
1669 call gets interpreted but then the input is picked up by explicitly calling the
1670 scanner functions. These return proper
\LUA\ variables so no further conversion
1671 has to be done. This is more efficient but in practice (given what
\TEX\ has to
1672 do) this effect should not be overestimated. For numbers and dimensions it saves a
1673 bit but for passing strings conversion to and from tokens has to be done anyway
1674 (although we can probably speed up the process in later versions if needed).
1676 When the interface is stable and has replaced the old one completely we will add
1677 some more information here. By that time the internals have been cleaned up a bit
1678 more so we know then what will stay and go. A positive side effect of this
1679 transition is that we can simplify the input part because we no longer need to
1680 intercept using callbacks.
1682 The
\type {set_macro
} function can get upto
4 arguments:
1685 setmacro("csname","content")
1686 setmacro("csname","content","global")
1690 You can pass a catcodetable identifier as first argument:
1693 setmacro(catcodetable,"csname","content")
1694 setmacro(catcodetable,"csname","content","global")
1695 setmacro(catcodetable,"csname")
1698 The results are like:
1701 \def\csname{content
}
1702 \gdef\csname{content
}
1706 There is a (for now) experimental putter:
1709 local t1 = token.get_next()
1710 local t2 = token.get_next()
1711 local t3 = token.get_next()
1712 local t4 = token.get_next()
1713 -- watch out, we flush in sequence
1714 token.put_next
{ t1, t2
}
1715 -- but this one gets pushed in front
1716 token.put_next ( t3, t4 )
1719 When we scan
\type {wxyz!
} we get
\type {yzwx!
} back. The argument is either a table
1720 with tokens or a list of tokens.
1722 \section{The
\type {kpse
} library
}
1724 This library provides two separate, but nearly identical interfaces to the
1725 \KPATHSEA\ file search functionality: there is a
\quote {normal
} procedural
1726 interface that shares its kpathsea instance with
\LUATEX\ itself, and an object
1727 oriented interface that is completely on its own.
1729 \subsection{\type {kpse.set_program_name
} and
\type {kpse.new
}}
1731 Before the search library can be used at all, its database has to be initialized.
1732 There are three possibilities, two of which belong to the procedural interface.
1734 First, when
\LUATEX\ is used to typeset documents, this initialization happens
1735 automatically and the
\KPATHSEA\ executable and program names are set to
\type
1736 {luatex
} (that is, unless explicitly prohibited by the user's startup script.
1737 See~
\in {section
} [init
] for more details).
1739 Second, in
\TEXLUA\ mode, the initialization has to be done explicitly via the
1740 \type {kpse.set_program_name
} function, which sets the
\KPATHSEA\ executable
1741 (and optionally program) name.
1744 kpse.set_program_name(<string> name)
1745 kpse.set_program_name(<string> name, <string> progname)
1748 The second argument controls the use of the
\quote {dotted
} values in the
\type
1749 {texmf.cnf
} configuration file, and defaults to the first argument.
1751 Third, if you prefer the object oriented interface, you have to call a different
1752 function. It has the same arguments, but it returns a userdata variable.
1755 local kpathsea = kpse.new(<string> name)
1756 local kpathsea = kpse.new(<string> name, <string> progname)
1759 Apart from these two functions, the calling conventions of the interfaces are
1760 identical. Depending on the chosen interface, you either call
\type
1761 {kpse.find_file()
} or
\type {kpathsea:find_file()
}, with identical arguments and
1764 \subsection{\type {find_file
}}
1766 The most often used function in the library is
\type {find_file
}:
1769 <string> f = kpse.find_file(<string> filename)
1770 <string> f = kpse.find_file(<string> filename, <string> ftype)
1771 <string> f = kpse.find_file(<string> filename, <boolean> mustexist)
1772 <string> f = kpse.find_file(<string> filename, <string> ftype, <boolean> mustexist)
1773 <string> f = kpse.find_file(<string> filename, <string> ftype, <number> dpi)
1778 \startitemize[intro
]
1782 the name of the file you want to find, with or without extension.
1786 maps to the
\type {-format
} argument of
\KPSEWHICH. The supported
\type {ftype
}
1787 values are the same as the ones supported by the standalone
\type {kpsewhich
}
1788 program:
\startluacode
1803 "font feature files",
1825 "other binary files",
1832 "PostScript header",
1833 "subfont definition files",
1835 "TeX system documentation",
1836 "TeX system sources",
1849 context("
{\
\tttf \letterpercent, t
}",list)
1852 The default type is
\type {tex
}. Note: this is different from
\KPSEWHICH, which
1853 tries to deduce the file type itself from looking at the supplied extension.
1857 is similar to
\KPSEWHICH's
\type {-must-exist
}, and the default is
\type {false
}.
1858 If you specify
\type {true
} (or a non|-|zero integer), then the
\KPSE\ library
1859 will search the disk as well as the
\type {ls-R
} databases.
1863 This is used for the size argument of the formats
\type {pk
},
\type {gf
}, and
1864 \type {bitmap font
}.
\stopitemize
1867 \subsection{\type {lookup
}}
1869 A more powerful (but slower) generic method for finding files is also available.
1870 It returns a string for each found file.
1873 <string> f, ... = kpse.lookup(<string> filename, <table> options)
1876 The options match commandline arguments from
\type {kpsewhich
}:
1878 \starttabulate[|l|l|p|
]
1879 \NC \rmbf key
\NC \rmbf type
\NC \rmbf description
\NC \NR
1880 \NC debug
\NC number
\NC set debugging flags for this lookup
\NC \NR
1881 \NC format
\NC string
\NC use specific file type (see list above)
\NC \NR
1882 \NC dpi
\NC number
\NC use this resolution for this lookup; default
600\NC \NR
1883 \NC path
\NC string
\NC search in the given path
\NC \NR
1884 \NC all
\NC boolean
\NC output all matches, not just the first
\NC \NR
1885 \NC mustexist
\NC boolean
\NC search the disk as well as ls-R if necessary
\NC \NR
1886 \NC mktexpk
\NC boolean
\NC disable/enable mktexpk generation for this lookup
\NC \NR
1887 \NC mktextex
\NC boolean
\NC disable/enable mktextex generation for this lookup
\NC \NR
1888 \NC mktexmf
\NC boolean
\NC disable/enable mktexmf generation for this lookup
\NC \NR
1889 \NC mktextfm
\NC boolean
\NC disable/enable mktextfm generation for this lookup
\NC \NR
1890 \NC subdir
\NC string
1891 or table
\NC only output matches whose directory part
1892 ends with the given string(s)
\NC \NR
1895 \subsection{\type {init_prog
}}
1897 Extra initialization for programs that need to generate bitmap fonts.
1900 kpse.init_prog(<string> prefix, <number> base_dpi, <string> mfmode)
1901 kpse.init_prog(<string> prefix, <number> base_dpi, <string> mfmode, <string> fallback)
1904 \subsection{\type {readable_file
}}
1906 Test if an (absolute) file name is a readable file.
1909 <string> f = kpse.readable_file(<string> name)
1912 The return value is the actual absolute filename you should use, because the disk
1913 name is not always the same as the requested name, due to aliases and
1914 system|-|specific handling under e.g.\
\MSDOS. Returns
\type {nil
} if the file
1915 does not exist or is not readable.
1917 \subsection{\type {expand_path
}}
1919 Like kpsewhich's
\type {-expand-path
}:
1922 <string> r = kpse.expand_path(<string> s)
1925 \subsection{\type {expand_var
}}
1927 Like kpsewhich's
\type {-expand-var
}:
1930 <string> r = kpse.expand_var(<string> s)
1933 \subsection{\type {expand_braces
}}
1935 Like kpsewhich's
\type {-expand-braces
}:
1938 <string> r = kpse.expand_braces(<string> s)
1941 \subsection{\type {show_path
}}
1943 Like kpsewhich's
\type {-show-path
}:
1946 <string> r = kpse.show_path(<string> ftype)
1950 \subsection{\type {var_value
}}
1952 Like kpsewhich's
\type {-var-value
}:
1955 <string> r = kpse.var_value(<string> s)
1958 \subsection{\type {version
}}
1960 Returns the kpathsea version string.
1963 <string> r = kpse.version()