diff options
author | Luigi Scarso <luigi.scarso@gmail.com> | 2016-04-08 19:42:16 +0000 |
---|---|---|
committer | Luigi Scarso <luigi.scarso@gmail.com> | 2016-04-08 19:42:16 +0000 |
commit | cebb31e8b80f96ab89fc2f3ae2b8d3b0f9e24666 (patch) | |
tree | 4a8e767071838937f00aabe754edc43779308784 /Master/texmf-dist/doc/luatex/base/luatex-tex.tex | |
parent | f24f87356b748ebbf5d65761c95d42ae987da8d0 (diff) |
new luatex manual
git-svn-id: svn://tug.org/texlive/trunk@40354 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/luatex/base/luatex-tex.tex')
-rw-r--r-- | Master/texmf-dist/doc/luatex/base/luatex-tex.tex | 1968 |
1 files changed, 1968 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/luatex/base/luatex-tex.tex b/Master/texmf-dist/doc/luatex/base/luatex-tex.tex new file mode 100644 index 00000000000..edf86870c6a --- /dev/null +++ b/Master/texmf-dist/doc/luatex/base/luatex-tex.tex @@ -0,0 +1,1968 @@ +% language=uk + +\environment luatex-style +\environment luatex-logos + +\startcomponent luatex-tex + +\startchapter[reference=tex,title={The \TEX\ related libraries}] + +\section{The \type {lua} library} + +\subsection{\LUA\ version} + +This library contains one read|-|only item: + +\starttyping +<string> s = lua.version +\stoptyping + +This returns the \LUA\ version identifier string. The value is currently +\directlua {tex.print(lua.version)}. + +\subsection{\LUA\ bytecode registers} + +\LUA\ registers can be used to communicate \LUA\ functions across \LUA\ chunks. +The accepted values for assignments are functions and \type {nil}. Likewise, the +retrieved value is either a function or \type {nil}. + +\starttyping +lua.bytecode[<number> n] = <function> f +lua.bytecode[<number> n]() +\stoptyping + +The contents of the \type {lua.bytecode} array is stored inside the format file +as actual \LUA\ bytecode, so it can also be used to preload \LUA\ code. + +Note: The function must not contain any upvalues. Currently, functions containing +upvalues can be stored (and their upvalues are set to \type {nil}), but this is +an artifact of the current \LUA\ implementation and thus subject to change. + +The associated function calls are + +\startfunctioncall +<function> f = lua.getbytecode(<number> n) +lua.setbytecode(<number> n, <function> f) +\stopfunctioncall + +Note: Since a \LUA\ file loaded using \type {loadfile(filename)} is essentially +an anonymous function, a complete file can be stored in a bytecode register like +this: + +\startfunctioncall +lua.bytecode[n] = loadfile(filename) +\stopfunctioncall + +Now all definitions (functions, variables) contained in the file can be +created by executing this bytecode register: + +\startfunctioncall +lua.bytecode[n]() +\stopfunctioncall + +Note that the path of the file is stored in the \LUA\ bytecode to be used in +stack backtraces and therefore dumped into the format file if the above code is +used in \INITEX. If it contains private information, i.e. the user name, this +information is then contained in the format file as well. This should be kept in +mind when preloading files into a bytecode register in \INITEX. + +\subsection{\LUA\ chunk name registers} + +There is an array of 65536 (0--65535) potential chunk names for use with the +\type {\directlua} and \type {\latelua} primitives. + +\startfunctioncall +lua.name[<number> n] = <string> s +<string> s = lua.name[<number> n] +\stopfunctioncall + +If you want to unset a \LUA\ name, you can assign \type {nil} to it. + +\section{The \type {status} library} + +This contains a number of run|-|time configuration items that you may find useful +in message reporting, as well as an iterator function that gets all of the names +and values as a table. + +\startfunctioncall +<table> info = status.list() +\stopfunctioncall + +The keys in the table are the known items, the value is the current value. Almost +all of the values in \type {status} are fetched through a metatable at run|-|time +whenever they are accessed, so you cannot use \type {pairs} on \type {status}, +but you {\it can\/} use \type {pairs} on \type {info}, of course. If you do not +need the full list, you can also ask for a single item by using its name as an +index into \type {status}. + +The current list is: + +\starttabulate[|lT|p|] +\NC \rmbf key \NC \bf explanation \NC \NR +\NC pdf_gone \NC written \PDF\ bytes \NC \NR +\NC pdf_ptr \NC not yet written \PDF\ bytes \NC \NR +\NC dvi_gone \NC written \DVI\ bytes \NC \NR +\NC dvi_ptr \NC not yet written \DVI\ bytes \NC \NR +\NC total_pages \NC number of written pages \NC \NR +\NC output_file_name \NC name of the \PDF\ or \DVI\ file \NC \NR +\NC log_name \NC name of the log file \NC \NR +\NC banner \NC terminal display banner \NC \NR +\NC var_used \NC variable (one|-|word) memory in use \NC \NR +\NC dyn_used \NC token (multi|-|word) memory in use \NC \NR +\NC str_ptr \NC number of strings \NC \NR +\NC init_str_ptr \NC number of \INITEX\ strings \NC \NR +\NC max_strings \NC maximum allowed strings \NC \NR +\NC pool_ptr \NC string pool index \NC \NR +\NC init_pool_ptr \NC \INITEX\ string pool index \NC \NR +\NC pool_size \NC current size allocated for string characters \NC \NR +\NC node_mem_usage \NC a string giving insight into currently used nodes \NC \NR +\NC var_mem_max \NC number of allocated words for nodes \NC \NR +\NC fix_mem_max \NC number of allocated words for tokens \NC \NR +\NC fix_mem_end \NC maximum number of used tokens \NC \NR +\NC cs_count \NC number of control sequences \NC \NR +\NC hash_size \NC size of hash \NC \NR +\NC hash_extra \NC extra allowed hash \NC \NR +\NC font_ptr \NC number of active fonts \NC \NR +\NC input_ptr \NC th elevel of input we're at \NC \NR +\NC max_in_stack \NC max used input stack entries \NC \NR +\NC max_nest_stack \NC max used nesting stack entries \NC \NR +\NC max_param_stack \NC max used parameter stack entries \NC \NR +\NC max_buf_stack \NC max used buffer position \NC \NR +\NC max_save_stack \NC max used save stack entries \NC \NR +\NC stack_size \NC input stack size \NC \NR +\NC nest_size \NC nesting stack size \NC \NR +\NC param_size \NC parameter stack size \NC \NR +\NC buf_size \NC current allocated size of the line buffer \NC \NR +\NC save_size \NC save stack size \NC \NR +\NC obj_ptr \NC max \PDF\ object pointer \NC \NR +\NC obj_tab_size \NC \PDF\ object table size \NC \NR +\NC pdf_os_cntr \NC max \PDF\ object stream pointer \NC \NR +\NC pdf_os_objidx \NC \PDF\ object stream index \NC \NR +\NC pdf_dest_names_ptr \NC max \PDF\ destination pointer \NC \NR +\NC dest_names_size \NC \PDF\ destination table size \NC \NR +\NC pdf_mem_ptr \NC max \PDF\ memory used \NC \NR +\NC pdf_mem_size \NC \PDF\ memory size \NC \NR +\NC largest_used_mark \NC max referenced marks class \NC \NR +\NC filename \NC name of the current input file \NC \NR +\NC inputid \NC numeric id of the current input \NC \NR +\NC linenumber \NC location in the current input file \NC \NR +\NC lasterrorstring \NC last \TEX\ error string \NC \NR +\NC lastluaerrorstring \NC last \LUA\ error string \NC \NR +\NC lastwarningtag \NC last warning string\NC \NR +\NC lastwarningstring \NC last warning tag, normally an indication of in what part\NC \NR +\NC lasterrorcontext \NC last error context string (with newlines) \NC \NR +\NC luabytecodes \NC number of active \LUA\ bytecode registers \NC \NR +\NC luabytecode_bytes \NC number of bytes in \LUA\ bytecode registers \NC \NR +\NC luastate_bytes \NC number of bytes in use by \LUA\ interpreters \NC \NR +\NC output_active \NC \type {true} if the \type {\output} routine is active \NC \NR +\NC callbacks \NC total number of executed callbacks so far \NC \NR +\NC indirect_callbacks \NC number of those that were themselves + a result of other callbacks (e.g. file readers) \NC \NR +\NC luatex_version \NC the \LUATEX\ version number \NC \NR +\NC luatex_revision \NC the \LUATEX\ revision string \NC \NR +\NC ini_version \NC \type {true} if this is an \INITEX\ run \NC \NR +\NC shell_escape \NC \type {0} means disabled, \type {1} is restricted and + \type {2} means anything is permitted \NC \NR +\stoptabulate + +The error and warning messages can be wiped with the \type {resetmessages} +function. + +\section{The \type {tex} library} + +The \type {tex} table contains a large list of virtual internal \TEX\ +parameters that are partially writable. + +The designation \quote {virtual} means that these items are not properly defined +in \LUA, but are only front\-ends that are handled by a metatable that operates +on the actual \TEX\ values. As a result, most of the \LUA\ table operators (like +\type {pairs} and \type {#}) do not work on such items. + +At the moment, it is possible to access almost every parameter that has these +characteristics: + +\startitemize[packed] +\item You can use it after \type {\the} +\item It is a single token. +\item Some special others, see the list below +\stopitemize + +This excludes parameters that need extra arguments, like \type {\the\scriptfont}. + +The subset comprising simple integer and dimension registers are +writable as well as readable (stuff like \type {\tracingcommands} and +\type {\parindent}). + +\subsection{Internal parameter values} + +For all the parameters in this section, it is possible to access them directly +using their names as index in the \type {tex} table, or by using one of the +functions \type {tex.get} and \type {tex.set}. If you created aliasses, +you can use accessors like \type {tex.getdimen} as these also understand +names of built|-|in variables. + +The exact parameters and return values differ depending on the actual parameter, +and so does whether \type {tex.set} has any effect. For the parameters that {\it +can\/} be set, it is possible to use \type {global} as the first argument to +\type {tex.set}; this makes the assignment global instead of local. + +\startfunctioncall +tex.set (["global",] <string> n, ...) +... = tex.get (<string> n) +\stopfunctioncall + +There are also dedicated setters, getters and checkers: + +\startfunctioncall +local d = tex.getdimen("foo") +if tex.isdimen("bar") then + tex.setdimen("bar",d) +end +\stopfunctioncall + +There are such helpers for \type {dimen}, \type {count}, \type {skip}, \type +{box} and \type {attribute} registers. + +\subsubsection{Integer parameters} + +The integer parameters accept and return \LUA\ numbers. + +Read|-|write: + +\starttwocolumns +\starttyping +tex.adjdemerits +tex.binoppenalty +tex.brokenpenalty +tex.catcodetable +tex.clubpenalty +tex.day +tex.defaulthyphenchar +tex.defaultskewchar +tex.delimiterfactor +tex.displaywidowpenalty +tex.doublehyphendemerits +tex.endlinechar +tex.errorcontextlines +tex.escapechar +tex.exhyphenpenalty +tex.fam +tex.finalhyphendemerits +tex.floatingpenalty +tex.globaldefs +tex.hangafter +tex.hbadness +tex.holdinginserts +tex.hyphenpenalty +tex.interlinepenalty +tex.language +tex.lastlinefit +tex.lefthyphenmin +tex.linepenalty +tex.localbrokenpenalty +tex.localinterlinepenalty +tex.looseness +tex.mag +tex.maxdeadcycles +tex.month +tex.newlinechar +tex.outputpenalty +tex.pausing +tex.postdisplaypenalty +tex.predisplaydirection +tex.predisplaypenalty +tex.pretolerance +tex.relpenalty +tex.righthyphenmin +tex.savinghyphcodes +tex.savingvdiscards +tex.showboxbreadth +tex.showboxdepth +tex.time +tex.tolerance +tex.tracingassigns +tex.tracingcommands +tex.tracinggroups +tex.tracingifs +tex.tracinglostchars +tex.tracingmacros +tex.tracingnesting +tex.tracingonline +tex.tracingoutput +tex.tracingpages +tex.tracingparagraphs +tex.tracingrestores +tex.tracingscantokens +tex.tracingstats +tex.uchyph +tex.vbadness +tex.widowpenalty +tex.year +\stoptyping +\stoptwocolumns + +Read|-|only: + +\startthreecolumns +\starttyping +tex.deadcycles +tex.insertpenalties +tex.parshape +tex.prevgraf +tex.spacefactor +\stoptyping +\stopthreecolumns + +\subsubsection{Dimension parameters} + +The dimension parameters accept \LUA\ numbers (signifying scaled points) or +strings (with included dimension). The result is always a number in scaled +points. + +Read|-|write: + +\startthreecolumns +\starttyping +tex.boxmaxdepth +tex.delimitershortfall +tex.displayindent +tex.displaywidth +tex.emergencystretch +tex.hangindent +tex.hfuzz +tex.hoffset +tex.hsize +tex.lineskiplimit +tex.mathsurround +tex.maxdepth +tex.nulldelimiterspace +tex.overfullrule +tex.pagebottomoffset +tex.pageheight +tex.pageleftoffset +tex.pagerightoffset +tex.pagetopoffset +tex.pagewidth +tex.parindent +tex.predisplaysize +tex.scriptspace +tex.splitmaxdepth +tex.vfuzz +tex.voffset +tex.vsize +tex.prevdepth +tex.prevgraf +tex.spacefactor +\stoptyping +\stopthreecolumns + +Read|-|only: + +\startthreecolumns +\starttyping +tex.pagedepth +tex.pagefilllstretch +tex.pagefillstretch +tex.pagefilstretch +tex.pagegoal +tex.pageshrink +tex.pagestretch +tex.pagetotal +\stoptyping +\stopthreecolumns + +Beware: as with all \LUA\ tables you can add values to them. So, the following is valid: + +\starttyping +tex.foo = 123 +\stoptyping + +When you access a \TEX\ parameter a look up takes place. For read||only variables +that means that you will get something back, but when you set them you create a +new entry in the table thereby making the original invisible. + +There are a few special cases that we make an exception for: \type {prevdepth}, +\type {prevgraf} and \type {spacefactor}. These normally are accessed via the +\type {tex.nest} table: + +\starttyping +tex.nest[tex.nest.ptr].prevdepth = p +tex.nest[tex.nest.ptr].spacefactor = s +\stoptyping + +However, the following also works: + +\starttyping +tex.prevdepth = p +tex.spacefactor = s +\stoptyping + +Keep in mind that when you mess with node lists directly at the \LUA\ end you +might need to update the top of the nesting stack's \type {prevdepth} explicitly +as there is no way \LUATEX\ can guess your intentions. By using the accessor in +the \type {tex} tables, you get and set the values atthe top of the nest stack. + +\subsubsection{Direction parameters} + +The direction parameters are read|-|only and return a \LUA\ string. + +\startthreecolumns +\starttyping +tex.bodydir +tex.mathdir +tex.pagedir +tex.pardir +tex.textdir +\stoptyping +\stopthreecolumns + +\subsubsection{Glue parameters} + +The glue parameters accept and return a userdata object that represents a \type +{glue_spec} node. + +\startthreecolumns +\starttyping +tex.abovedisplayshortskip +tex.abovedisplayskip +tex.baselineskip +tex.belowdisplayshortskip +tex.belowdisplayskip +tex.leftskip +tex.lineskip +tex.parfillskip +tex.parskip +tex.rightskip +tex.spaceskip +tex.splittopskip +tex.tabskip +tex.topskip +tex.xspaceskip +\stoptyping +\stopthreecolumns + +\subsubsection{Muglue parameters} + +All muglue parameters are to be used read|-|only and return a \LUA\ string. + +\startthreecolumns +\starttyping +tex.medmuskip +tex.thickmuskip +tex.thinmuskip +\stoptyping +\stopthreecolumns + +\subsubsection{Tokenlist parameters} + +The tokenlist parameters accept and return \LUA\ strings. \LUA\ strings are +converted to and from token lists using \type {\the} \type {\toks} style expansion: +all category codes are either space (10) or other (12). It follows that assigning +to some of these, like \quote {tex.output}, is actually useless, but it feels bad +to make exceptions in view of a coming extension that will accept full|-|blown +token strings. + +\startthreecolumns +\starttyping +tex.errhelp +tex.everycr +tex.everydisplay +tex.everyeof +tex.everyhbox +tex.everyjob +tex.everymath +tex.everypar +tex.everyvbox +tex.output +tex.pdfpageattr +tex.pdfpageresources +tex.pdfpagesattr +tex.pdfpkmode +\stoptyping +\stopthreecolumns + +\subsection{Convert commands} + +All \quote {convert} commands are read|-|only and return a \LUA\ string. The +supported commands at this moment are: + +\starttwocolumns +\starttyping +tex.eTeXVersion +tex.eTeXrevision +tex.formatname +tex.jobname +tex.luatexbanner +tex.luatexrevision +tex.pdfnormaldeviate +tex.fontname(number) +tex.pdffontname(number) +tex.pdffontobjnum(number) +tex.pdffontsize(number) +tex.uniformdeviate(number) +tex.number(number) +tex.romannumeral(number) +tex.pdfpageref(number) +tex.pdfxformname(number) +tex.fontidentifier(number) +\stoptyping +\stoptwocolumns + +If you are wondering why this list looks haphazard; these are all the cases of +the \quote {convert} internal command that do not require an argument, as well as +the ones that require only a simple numeric value. + +The special (lua-only) case of \type {tex.fontidentifier} returns the \type +{csname} string that matches a font id number (if there is one). + +if these are really needed in a macro package. + +\subsection{Last item commands} + +All \quote {last item} commands are read|-|only and return a number. + +The supported commands at this moment are: + +\startthreecolumns +\starttyping +tex.lastpenalty +tex.lastkern +tex.lastskip +tex.lastnodetype +tex.inputlineno +tex.pdflastobj +tex.pdflastxform +tex.pdflastximage +tex.pdflastximagepages +tex.pdflastannot +tex.pdflastxpos +tex.pdflastypos +tex.pdfrandomseed +tex.pdflastlink +tex.luatexversion +tex.eTeXminorversion +tex.eTeXversion +tex.currentgrouplevel +tex.currentgrouptype +tex.currentiflevel +tex.currentiftype +tex.currentifbranch +tex.pdflastximagecolordepth +\stoptyping +\stopthreecolumns + +\subsection{Attribute, count, dimension, skip and token registers} + +\TEX's attributes (\type {\attribute}), counters (\type {\count}), dimensions (\type +{\dimen}), skips (\type {\skip}) and token (\type {\toks}) registers can be accessed +and written to using two times five virtual sub|-|tables of the \type {tex} +table: + +\startthreecolumns +\starttyping +tex.attribute +tex.count +tex.dimen +tex.skip +tex.toks +\stoptyping +\stopthreecolumns + +It is possible to use the names of relevant \type {\attributedef}, \type {\countdef}, +\type {\dimendef}, \type {\skipdef}, or \type {\toksdef} control sequences as indices +to these tables: + +\starttyping +tex.count.scratchcounter = 0 +enormous = tex.dimen['maxdimen'] +\stoptyping + +In this case, \LUATEX\ looks up the value for you on the fly. You have to use a +valid \type {\countdef} (or \type {\attributedef}, or \type {\dimendef}, or \type +{\skipdef}, or \type {\toksdef}), anything else will generate an error (the intent +is to eventually also allow \type {<chardef tokens>} and even macros that expand +into a number). + +The attribute and count registers accept and return \LUA\ numbers. + +The dimension registers accept \LUA\ numbers (in scaled points) or strings (with +an included absolute dimension; \type {em} and \type {ex} and \type {px} are +forbidden). The result is always a number in scaled points. + +The token registers accept and return \LUA\ strings. \LUA\ strings are converted +to and from token lists using \type {\the} \type {\toks} style expansion: all +category codes are either space (10) or other (12). + +The skip registers accept and return \type {glue_spec} userdata node objects (see +the description of the node interface elsewhere in this manual). + +As an alternative to array addressing, there are also accessor functions defined +for all cases, for example, here is the set of possibilities for \type {\skip} +registers: + +\startfunctioncall +tex.setskip (["global",] <number> n, <node> s) +tex.setskip (["global",] <string> s, <node> s) +<node> s = tex.getskip (<number> n) +<node> s = tex.getskip (<string> s) +\stopfunctioncall + +We have similar setters for \type {count}, \type {dimen}, \type {muskip}, and +\type {toks}. Counters and dimen are represented by numbers, skips and muskips by +nodes, and toks by strings. For tokens registers we have an alternative where a +catcode table is specified: + +\startfunctioncall +tex.scantoks(0,3,"$e=mc^2$") +tex.scantoks("global",0,"$\int\limits^1_2$") +\stopfunctioncall + +In the function-based interface, it is possible to define values globally by +using the string \type {global} as the first function argument. + +There are four extra skip related helpers: + +\startfunctioncall +tex.setglue (["global"], <number> n, + width, stretch, shrink, stretch_order, shrink_order) +tex.setglue (["global"], <string> s, + width, stretch, shrink, stretch_order, shrink_order) +width, stretch, shrink, stretch_order, shrink_order = + tex.getglue (<number> n) +width, stretch, shrink, stretch_order, shrink_order = + tex.getglue (<string> s) +\stopfunctioncall + +The other two are \type {tex.setmuglue} and \type {tex.getmuglue}. + +\subsection{Character code registers} + +\TEX's character code tables (\type {\lccode}, \type {\uccode}, \type {\sfcode}, \type +{\catcode}, \type {\mathcode}, \type {\delcode}) can be accessed and written to using +six virtual subtables of the \type {tex} table + +\startthreecolumns +\starttyping +tex.lccode +tex.uccode +tex.sfcode +tex.catcode +tex.mathcode +tex.delcode +\stoptyping +\stopthreecolumns + +The function call interfaces are roughly as above, but there are a few twists. +\type {sfcode}s are the simple ones: + +\startfunctioncall +tex.setsfcode (["global",] <number> n, <number> s) +<number> s = tex.getsfcode (<number> n) +\stopfunctioncall + +The function call interface for \type {lccode} and \type {uccode} additionally +allows you to set the associated sibling at the same time: + +\startfunctioncall +tex.setlccode (["global"], <number> n, <number> lc) +tex.setlccode (["global"], <number> n, <number> lc, <number> uc) +<number> lc = tex.getlccode (<number> n) +tex.setuccode (["global"], <number> n, <number> uc) +tex.setuccode (["global"], <number> n, <number> uc, <number> lc) +<number> uc = tex.getuccode (<number> n) +\stopfunctioncall + +The function call interface for \type {catcode} also allows you to specify a +category table to use on assignment or on query (default in both cases is the +current one): + +\startfunctioncall +tex.setcatcode (["global"], <number> n, <number> c) +tex.setcatcode (["global"], <number> cattable, <number> n, <number> c) +<number> lc = tex.getcatcode (<number> n) +<number> lc = tex.getcatcode (<number> cattable, <number> n) +\stopfunctioncall + +The interfaces for \type {delcode} and \type {mathcode} use small array tables to +set and retrieve values: + +\startfunctioncall +tex.setmathcode (["global"], <number> n, <table> mval ) +<table> mval = tex.getmathcode (<number> n) +tex.setdelcode (["global"], <number> n, <table> dval ) +<table> dval = tex.getdelcode (<number> n) +\stopfunctioncall + +Where the table for \type {mathcode} is an array of 3 numbers, like this: + +\starttyping +{ + <number> mathclass, + <number> family, + <number> character +} +\stoptyping + +And the table for \type {delcode} is an array with 4 numbers, like this: + +\starttyping +{ + <number> small_fam, + <number> small_char, + <number> large_fam, + <number> large_char +} +\stoptyping + +You can also avoid the table: + +\startfunctioncall +class, family, char = + tex.getmathcodes (<number> n) +smallfam, smallchar, largefam, largechar = + tex.getdelcodes (<number> n) +\stopfunctioncall + +Normally, the third and fourth values in a delimiter code assignment will be zero +according to \type {\Udelcode} usage, but the returned table can have values there +(if the delimiter code was set using \type {\delcode}, for example). Unset \type +{delcode}'s can be recognized because \type {dval[1]} is $-1$. + +\subsection{Box registers} + +It is possible to set and query actual boxes, using the node interface as defined +in the \type {node} library: + +\starttyping +tex.box +\stoptyping + +for array access, or + +\starttyping +tex.setbox(["global",] <number> n, <node> s) +tex.setbox(["global",] <string> cs, <node> s) +<node> n = tex.getbox(<number> n) +<node> n = tex.getbox(<string> cs) +\stoptyping + +for function|-|based access. In the function-based interface, it is possible to +define values globally by using the string \type {global} as the first function +argument. + +Be warned that an assignment like + +\starttyping +tex.box[0] = tex.box[2] +\stoptyping + +does not copy the node list, it just duplicates a node pointer. If \type {\box2} +will be cleared by \TEX\ commands later on, the contents of \type {\box0} becomes +invalid as well. To prevent this from happening, always use \type +{node.copy_list()} unless you are assigning to a temporary variable: + +\starttyping +tex.box[0] = node.copy_list(tex.box[2]) +\stoptyping + +The following function will register a box for reuse (this is modelled after so +called xforms in \PDF). You can (re)use the box with \type {\useboxresource} or +by creating a rule node with subtype~2. + +\starttyping +local index = tex.saveboxresource(n,attributes,resources,immediate) +\stoptyping + +The optional second and third arguments are strings, the fourth is a boolean. + +You can generate the reference (a rule type) with: + +\starttyping +local reused = tex.useboxresource(n,wd,ht,dp) +\stoptyping + +The dimensions are optional and the final ones are returned as extra values. The +following is just a bonus (no dimensions returned means that the resource is +unknown): + +\starttyping +local w, h, d = tex.getboxresourcedimensions(n) +\stoptyping + +You can split a box: + +\starttyping +local vlist = tex.splitbox(n,height,mode) +\stoptyping + +The remainder is kept in the original box and a packaged vlist is returned. This +operation is comparable to the \type {\vsplit} operation. The mode can be \type +{additional} or \type {exactly} and concerns the split off box. + +\subsection{Math parameters} + +It is possible to set and query the internal math parameters using: + +\startfunctioncall +tex.setmath(["global",] <string> n, <string> t, <number> n) +<number> n = tex.getmath(<string> n, <string> t) +\stopfunctioncall + +As before an optional first parameter \type {global} indicates a global +assignment. + +The first string is the parameter name minus the leading \quote {Umath}, and the +second string is the style name minus the trailing \quote {style}. Just to be +complete, the values for the math parameter name are: + +\starttyping +quad axis operatorsize +overbarkern overbarrule overbarvgap +underbarkern underbarrule underbarvgap +radicalkern radicalrule radicalvgap +radicaldegreebefore radicaldegreeafter radicaldegreeraise +stackvgap stacknumup stackdenomdown +fractionrule fractionnumvgap fractionnumup +fractiondenomvgap fractiondenomdown fractiondelsize +limitabovevgap limitabovebgap limitabovekern +limitbelowvgap limitbelowbgap limitbelowkern +underdelimitervgap underdelimiterbgap +overdelimitervgap overdelimiterbgap +subshiftdrop supshiftdrop subshiftdown +subsupshiftdown subtopmax supshiftup +supbottommin supsubbottommax subsupvgap +spaceafterscript connectoroverlapmin +ordordspacing ordopspacing ordbinspacing ordrelspacing +ordopenspacing ordclosespacing ordpunctspacing ordinnerspacing +opordspacing opopspacing opbinspacing oprelspacing +opopenspacing opclosespacing oppunctspacing opinnerspacing +binordspacing binopspacing binbinspacing binrelspacing +binopenspacing binclosespacing binpunctspacing bininnerspacing +relordspacing relopspacing relbinspacing relrelspacing +relopenspacing relclosespacing relpunctspacing relinnerspacing +openordspacing openopspacing openbinspacing openrelspacing +openopenspacing openclosespacing openpunctspacing openinnerspacing +closeordspacing closeopspacing closebinspacing closerelspacing +closeopenspacing closeclosespacing closepunctspacing closeinnerspacing +punctordspacing punctopspacing punctbinspacing punctrelspacing +punctopenspacing punctclosespacing punctpunctspacing punctinnerspacing +innerordspacing inneropspacing innerbinspacing innerrelspacing +inneropenspacing innerclosespacing innerpunctspacing innerinnerspacing +\stoptyping + +The values for the style parameter name are: + +\starttyping +display crampeddisplay +text crampedtext +script crampedscript +scriptscript crampedscriptscript +\stoptyping + +The value is either a number (representing a dimension or number) or a glue spec +node representing a muskip for \type {ordordspacing} and similar spacing +parameters. + +\subsection{Special list heads} + +The virtual table \type {tex.lists} contains the set of internal registers that +keep track of building page lists. + +\starttabulate[|lT|p|] +\NC \bf field \NC \bf description \NC \NR +\NC page_ins_head \NC circular list of pending insertions \NC \NR +\NC contrib_head \NC the recent contributions \NC \NR +\NC page_head \NC the current page content \NC \NR +%NC temp_head \NC \NC \NR +\NC hold_head \NC used for held-over items for next page \NC \NR +\NC adjust_head \NC head of the current \type {\vadjust} list \NC \NR +\NC pre_adjust_head \NC head of the current \type {\vadjust pre} list \NC \NR +%NC align_head \NC \NC \NR +\NC page_discards_head \NC head of the discarded items of a page break \NC \NR +\NC split_discards_head \NC head of the discarded items in a vsplit \NC \NR +\stoptabulate + +\subsection{Semantic nest levels} + +The virtual table \type {tex.nest} contains the currently active +semantic nesting state. It has two main parts: a zero-based array of userdata for +the semantic nest itself, and the numerical value \type {tex.nest.ptr}, which +gives the highest available index. Neither the array items in \type {tex.nest[]} +nor \type {tex.nest.ptr} can be assigned to (as this would confuse the +typesetting engine beyond repair), but you can assign to the individual values +inside the array items, e.g.\ \type {tex.nest[tex.nest.ptr].prevdepth}. + +\type {tex.nest[tex.nest.ptr]} is the current nest state, \type {tex.nest[0]} the +outermost (main vertical list) level. + +The known fields are: + +\starttabulate[|lT|l|l|p|] +\NC \rmbf key \NC \bf type \NC \bf modes \NC \bf explanation \NC \NR +\NC mode \NC number \NC all \NC a number representing the main mode at this level: + \type {0} = no mode (this happens during \type {\write}), + \type {1} = vertical, + \type {127} = horizontal, + \type {253} = display math, + \type {-1} = internal vertical, + \type {-127} = restricted horizontal, + \type {-253} = inline math \NC \NR +\NC modeline \NC number \NC all \NC source input line where this mode was entered in, + negative inside the output routine \NC \NR +\NC head \NC node \NC all \NC the head of the current list \NC \NR +\NC tail \NC node \NC all \NC the tail of the current list \NC \NR +\NC prevgraf \NC number \NC vmode \NC number of lines in the previous paragraph \NC \NR +\NC prevdepth \NC number \NC vmode \NC depth of the previous paragraph (equal to \type {\pdfignoreddimen} + when it is to be ignored) \NC \NR +\NC spacefactor \NC number \NC hmode \NC the current space factor \NC \NR +\NC dirs \NC node \NC hmode \NC used for temporary storage by the line break algorithm\NC \NR +\NC noad \NC node \NC mmode \NC used for temporary storage of a pending fraction numerator, + for \type {\over} etc. \NC \NR +\NC delimptr \NC node \NC mmode \NC used for temporary storage of the previous math delimiter, + for \type {\middle} \NC \NR +\NC mathdir \NC boolean \NC mmode \NC true when during math processing the \type {\mathdir} is not + the same as the surrounding \type {\textdir} \NC \NR +\NC mathstyle \NC number \NC mmode \NC the current \type {\mathstyle} \NC \NR +\stoptabulate + +\subsection[sec:luaprint]{Print functions} + +The \type {tex} table also contains the three print functions that are the +major interface from \LUA\ scripting to \TEX. + +The arguments to these three functions are all stored in an in|-|memory virtual +file that is fed to the \TEX\ scanner as the result of the expansion of +\type {\directlua}. + +The total amount of returnable text from a \type {\directlua} command is only +limited by available system \RAM. However, each separate printed string has to +fit completely in \TEX's input buffer. + +The result of using these functions from inside callbacks is undefined +at the moment. + +\subsubsection{\type {tex.print}} + +\startfunctioncall +tex.print(<string> s, ...) +tex.print(<number> n, <string> s, ...) +tex.print(<table> t) +tex.print(<number> n, <table> t) +\stopfunctioncall + +Each string argument is treated by \TEX\ as a separate input line. If there is a +table argument instead of a list of strings, this has to be a consecutive array +of strings to print (the first non-string value will stop the printing process). + +The optional parameter can be used to print the strings using the catcode regime +defined by \type {\catcodetable}~\type {n}. If \type {n} is $-1$, the currently +active catcode regime is used. If \type {n} is $-2$, the resulting catcodes are +the result of \type {\the} \type {\toks}: all category codes are 12 (other) except for +the space character, that has category code 10 (space). Otherwise, if \type {n} +is not a valid catcode table, then it is ignored, and the currently active +catcode regime is used instead. + +The very last string of the very last \type {tex.print()} command in a \type +{\directlua} will not have the \type {\endlinechar} appended, all others do. + +\subsubsection{\type {tex.sprint}} + +\startfunctioncall +tex.sprint(<string> s, ...) +tex.sprint(<number> n, <string> s, ...) +tex.sprint(<table> t) +tex.sprint(<number> n, <table> t) +\stopfunctioncall + +Each string argument is treated by \TEX\ as a special kind of input line that +makes it suitable for use as a partial line input mechanism: + +\startitemize[packed] +\startitem + \TEX\ does not switch to the \quote {new line} state, so that leading spaces + are not ignored. +\stopitem +\startitem + No \type {\endlinechar} is inserted. +\stopitem +\startitem + Trailing spaces are not removed. + + Note that this does not prevent \TEX\ itself from eating spaces as result of + interpreting the line. For example, in + +\starttyping +before\directlua{tex.sprint("\\relax")tex.sprint(" inbetween")}after +\stoptyping + the space before \type {in between} will be gobbled as a result of the \quote + {normal} scanning of \type {\relax}. +\stopitem +\stopitemize + +If there is a table argument instead of a list of strings, this has to +be a consecutive array of strings to print (the first non-string value +will stop the printing process). + +The optional argument sets the catcode regime, as with \type {tex.print()}. + +\subsubsection{\type {tex.tprint}} + +\startfunctioncall +tex.tprint({<number> n, <string> s, ...}, {...}) +\stopfunctioncall + +This function is basically a shortcut for repeated calls to \type +{tex.sprint(<number> n, <string> s, ...)}, once for each of the supplied argument +tables. + +\subsubsection{\type {tex.cprint}} + +This function takes a number indicating the to be used catcode, plus either a +table of strings or an argument list of strings that will be pushed into the +input stream. + +\startfunctioncall +tex.cprint( 1," 1: $&{\\foo}") tex.print("\\par") -- a lot of \bgroup s +tex.cprint( 2," 2: $&{\\foo}") tex.print("\\par") -- matching \egroup s +tex.cprint( 9," 9: $&{\\foo}") tex.print("\\par") -- all get ignored +tex.cprint(10,"10: $&{\\foo}") tex.print("\\par") -- all become spaces +tex.cprint(11,"11: $&{\\foo}") tex.print("\\par") -- letters +tex.cprint(12,"12: $&{\\foo}") tex.print("\\par") -- other characters +tex.cprint(14,"12: $&{\\foo}") tex.print("\\par") -- comment triggers +\stopfunctioncall + +\subsubsection{\type {tex.write}} + +\startfunctioncall +tex.write(<string> s, ...) +tex.write(<table> t) +\stopfunctioncall + +Each string argument is treated by \TEX\ as a special kind of input line that +makes it suitable for use as a quick way to dump information: + +\startitemize +\item All catcodes on that line are either \quote{space} (for '~') or + \quote{character} (for all others). +\item There is no \type {\endlinechar} appended. +\stopitemize + +If there is a table argument instead of a list of strings, this has to be a +consecutive array of strings to print (the first non-string value will stop the +printing process). + +\subsection{Helper functions} + +\subsubsection{\type {tex.round}} + +\startfunctioncall +<number> n = tex.round(<number> o) +\stopfunctioncall + +Rounds \LUA\ number \type {o}, and returns a number that is in the range of a +valid \TEX\ register value. If the number starts out of range, it generates a +\quote {number to big} error as well. + +\subsubsection{\type {tex.scale}} + +\startfunctioncall +<number> n = tex.scale(<number> o, <number> delta) +<table> n = tex.scale(table o, <number> delta) +\stopfunctioncall + +Multiplies the \LUA\ numbers \type {o} and \type {delta}, and returns a rounded +number that is in the range of a valid \TEX\ register value. In the table +version, it creates a copy of the table with all numeric top||level values scaled +in that manner. If the multiplied number(s) are of range, it generates +\quote{number to big} error(s) as well. + +Note: the precision of the output of this function will depend on your computer's +architecture and operating system, so use with care! An interface to \LUATEX's +internal, 100\% portable scale function will be added at a later date. + +\subsubsection{\type {tex.sp}} + +\startfunctioncall +<number> n = tex.sp(<number> o) +<number> n = tex.sp(<string> s) +\stopfunctioncall + +Converts the number \type {o} or a string \type {s} that represents an explicit +dimension into an integer number of scaled points. + +For parsing the string, the same scanning and conversion rules are used that +\LUATEX\ would use if it was scanning a dimension specifier in its \TEX|-|like +input language (this includes generating errors for bad values), expect for the +following: + +\startitemize[n] +\startitem + only explicit values are allowed, control sequences are not handled +\stopitem +\startitem + infinite dimension units (\type {fil...}) are forbidden +\stopitem +\startitem + \type {mu} units do not generate an error (but may not be useful either) +\stopitem +\stopitemize + +\subsubsection{\type {tex.definefont}} + +\startfunctioncall +tex.definefont(<string> csname, <number> fontid) +tex.definefont(<boolean> global, <string> csname, <number> fontid) +\stopfunctioncall + +Associates \type {csname} with the internal font number \type {fontid}. The +definition is global if (and only if) \type {global} is specified and true (the +setting of \type {globaldefs} is not taken into account). + +\subsubsection{\type {tex.getlinenumber} and \type {tex.setlinenumber}} + +You can mess with the current line number: + +\startfunctioncall +local n = tex.getlinenumber() +tex.setlinenumber(n+10) +\stopfunctioncall + +which can be shortcut to: + +\startfunctioncall +tex.setlinenumber(10,true) +\stopfunctioncall + +This might be handy when you have a callback that read numbers from a file and +combines them in one line (in which case an error message probably has to refer +to the original line). Interference with \TEX's internal handling of numbers is +of course possible. + +\subsubsection{\type {tex.error}} + +\startfunctioncall +tex.error(<string> s) +tex.error(<string> s, <table> help) +\stopfunctioncall + +This creates an error somewhat like the combination of \type {\errhelp} and \type +{\errmessage} would. During this error, deletions are disabled. + +The array part of the \type {help} table has to contain strings, one for each +line of error help. + +\subsubsection{\type {tex.hashtokens}} + +\startfunctioncall +for i,v in pairs (tex.hashtokens()) do ... end +\stopfunctioncall + +Returns a name and token table pair (see~\in {section} [luatokens] about token +tables) iterator for every non-zero entry in the hash table. This can be useful +for debugging, but note that this also reports control sequences that may be +unreachable at this moment due to local redefinitions: it is strictly a dump of +the hash table. + +\subsection[luaprimitives]{Functions for dealing with primitives } + +\subsubsection{\type {tex.enableprimitives}} + +\startfunctioncall +tex.enableprimitives(<string> prefix, <table> primitive names) +\stopfunctioncall + +This function accepts a prefix string and an array of primitive names. + +For each combination of \quote {prefix} and \quote {name}, the \type +{tex.enableprimitives} first verifies that \quote {name} is an actual primitive +(it must be returned by one of the \type {tex.extraprimitives()} calls explained +below, or part of \TEX82, or \type {\directlua}). If it is not, \type +{tex.enableprimitives} does nothing and skips to the next pair. + +But if it is, then it will construct a csname variable by concatenating the +\quote {prefix} and \quote {name}, unless the \quote {prefix} is already the +actual prefix of \quote {name}. In the latter case, it will discard the \quote +{prefix}, and just use \quote {name}. + +Then it will check for the existence of the constructed csname. If the csname is +currently undefined (note: that is not the same as \type {\relax}), it will +globally define the csname to have the meaning: run code belonging to the +primitive \quote {name}. If for some reason the csname is already defined, it +does nothing and tries the next pair. + +An example: + +\starttyping + tex.enableprimitives('LuaTeX', {'formatname'}) +\stoptyping + +will define \type {\LuaTeXformatname} with the same intrinsic meaning as the +documented primitive \type {\formatname}, provided that the control sequences \type +{\LuaTeXformatname} is currently undefined. + +When \LUATEX\ is run with \type {--ini} only the \TEX82 primitives and \type +{\directlua} are available, so no extra primitives {\bf at all}. + +If you want to have all the new functionality available using their default +names, as it is now, you will have to add + +\starttyping + \ifx\directlua\undefined \else + \directlua {tex.enableprimitives('',tex.extraprimitives ())} + \fi +\stoptyping + +near the beginning of your format generation file. Or you can choose different +prefixes for different subsets, as you see fit. + +Calling some form of \type {tex.enableprimitives()} is highly important though, +because if you do not, you will end up with a \TEX82-lookalike that can run \LUA\ +code but not do much else. The defined csnames are (of course) saved in the +format and will be available at runtime. + +\subsubsection{\type {tex.extraprimitives}} + +\startfunctioncall +<table> t = tex.extraprimitives(<string> s, ...) +\stopfunctioncall + +This function returns a list of the primitives that originate from the engine(s) +given by the requested string value(s). The possible values and their (current) +return values are: + +\startluacode +function document.showprimitives(tag) + for k, v in table.sortedpairs(tex.extraprimitives(tag)) do + if v == ' ' then + v = '\\normalcontrolspace' + end + context.type(v) + context.space() + end +end +\stopluacode + +\starttabulate[|l|pl|] +\NC \bf name\NC \bf values \NC \NR +\NC tex \NC \ctxlua{document.showprimitives('tex') } \NC \NR +\NC core \NC \ctxlua{document.showprimitives('core') } \NC \NR +\NC etex \NC \ctxlua{document.showprimitives('etex') } \NC \NR +\NC luatex \NC \ctxlua{document.showprimitives('luatex') } \NC \NR +\stoptabulate + +Note that \type {'luatex'} does not contain \type {directlua}, as that is +considered to be a core primitive, along with all the \TEX82 primitives, so it is +part of the list that is returned from \type {'core'}. + +% \type {'umath'} is a subset of \type {'luatex'} that covers the Unicode math +% primitives as it might be desired to handle the prefixing of that subset +% differently. + +Running \type {tex.extraprimitives()} will give you the complete list of +primitives \type {-ini} startup. It is exactly equivalent to \type +{tex.extraprimitives('etex' and 'luatex')}. + +\subsubsection{\type {tex.primitives}} + +\startfunctioncall +<table> t = tex.primitives() +\stopfunctioncall + +This function returns a hash table listing all primitives that \LUATEX\ knows +about. The keys in the hash are primitives names, the values are tables +representing tokens (see~\in{section }[luatokens]). The third value is always +zero. + +{\em In the beginning we had \type {omega} and \type {pdftex} subsets but in the +meantime relevant primitives ave been promoted (either or not adapted) to the +\type {luatex} set when found useful, or removed when considered to be of no use. +Originally we had two sets of math definition primitives but the \OMEGA\ ones +have been removed, so we no longer have a subset for math either.} + +\subsection{Core functionality interfaces} + +\subsubsection{\type {tex.badness}} + +\startfunctioncall +<number> b = tex.badness(<number> t, <number> s) +\stopfunctioncall + +This helper function is useful during linebreak calculations. \type {t} and \type +{s} are scaled values; the function returns the badness for when total \type {t} +is supposed to be made from amounts that sum to \type {s}. The returned number is +a reasonable approximation of $100(t/s)^3$; + +\subsubsection{\type {tex.resetparagraph}} + +This function resets the parameters that \TEX\ normally resets when a new paragraph +is seen. + +\subsubsection{\type {tex.linebreak}} + +\startfunctioncall +local <node> nodelist, <table> info = + tex.linebreak(<node> listhead, <table> parameters) +\stopfunctioncall + +The understood parameters are as follows: + +\starttabulate[|l|l|p|] +\NC \bf name \NC \bf type \NC \bf description \NC \NR +\NC pardir \NC string \NC \NC \NR +\NC pretolerance \NC number \NC \NC \NR +\NC tracingparagraphs \NC number \NC \NC \NR +\NC tolerance \NC number \NC \NC \NR +\NC looseness \NC number \NC \NC \NR +\NC hyphenpenalty \NC number \NC \NC \NR +\NC exhyphenpenalty \NC number \NC \NC \NR +\NC pdfadjustspacing \NC number \NC \NC \NR +\NC adjdemerits \NC number \NC \NC \NR +\NC pdfprotrudechars \NC number \NC \NC \NR +\NC linepenalty \NC number \NC \NC \NR +\NC lastlinefit \NC number \NC \NC \NR +\NC doublehyphendemerits \NC number \NC \NC \NR +\NC finalhyphendemerits \NC number \NC \NC \NR +\NC hangafter \NC number \NC \NC \NR +\NC interlinepenalty \NC number or table \NC if a table, then it is an array like \type {\interlinepenalties} \NC \NR +\NC clubpenalty \NC number or table \NC if a table, then it is an array like \type {\clubpenalties} \NC \NR +\NC widowpenalty \NC number or table \NC if a table, then it is an array like \type {\widowpenalties} \NC \NR +\NC brokenpenalty \NC number \NC \NC \NR +\NC emergencystretch \NC number \NC in scaled points \NC \NR +\NC hangindent \NC number \NC in scaled points \NC \NR +\NC hsize \NC number \NC in scaled points \NC \NR +\NC leftskip \NC glue_spec node \NC \NC \NR +\NC rightskip \NC glue_spec node \NC \NC \NR +\NC pdfignoreddimen \NC number \NC in scaled points \NC \NR +\NC parshape \NC table \NC \NC \NR +\stoptabulate + +Note that there is no interface for \type {\displaywidowpenalties}, you have to +pass the right choice for \type {widowpenalties} yourself. + +The meaning of the various keys should be fairly obvious from the table (the +names match the \TEX\ and \PDFTEX\ primitives) except for the last 5 entries. The +four \type {pdf...line...} keys are ignored if their value equals \type +{pdfignoreddimen}. + +It is your own job to make sure that \type {listhead} is a proper paragraph list: +this function does not add any nodes to it. To be exact, if you want to replace +the core line breaking, you may have to do the following (when you are not +actually working in the \type {pre_linebreak_filter} or \type {linebreak_filter} +callbacks, or when the original list starting at listhead was generated in +horizontal mode): + +\startitemize +\startitem + add an \quote {indent box} and perhaps a \type {local_par} node at the start + (only if you need them) +\stopitem +\startitem + replace any found final glue by an infinite penalty (or add such a penalty, + if the last node is not a glue) +\stopitem +\startitem + add a glue node for the \type {\parfillskip} after that penalty node +\stopitem +\startitem + make sure all the \type {prev} pointers are OK +\stopitem +\stopitemize + +The result is a node list, it still needs to be vpacked if you want to assign it +to a \type {\vbox}. + +The returned \type {info} table contains four values that are all numbers: + +\starttabulate[|l|p|] +\NC prevdepth \NC depth of the last line in the broken paragraph \NC \NR +\NC prevgraf \NC number of lines in the broken paragraph \NC \NR +\NC looseness \NC the actual looseness value in the broken paragraph \NC \NR +\NC demerits \NC the total demerits of the chosen solution \NC \NR +\stoptabulate + +Note there are a few things you cannot interface using this function: You cannot +influence font expansion other than via \type {pdfadjustspacing}, because the +settings for that take place elsewhere. The same is true for hbadness and hfuzz +etc. All these are in the \type {hpack()} routine, and that fetches its own +variables via globals. + +\subsubsection{\type {tex.shipout}} + +\startfunctioncall +tex.shipout(<number> n) +\stopfunctioncall + +Ships out box number \type {n} to the output file, and clears the box register. + +\section[texconfig]{The \type {texconfig} table} + +This is a table that is created empty. A startup \LUA\ script could +fill this table with a number of settings that are read out by +the executable after loading and executing the startup file. + +\starttabulate[|lT|l|l|p|] +\NC \rmbf key \NC \bf type \NC \bf default \NC \bf explanation \NC \NR +\NC kpse_init \NC boolean \NC true +\NC + \type {false} totally disables \KPATHSEA\ initialisation, and enables + interpretation of the following numeric key--value pairs. (only ever unset + this if you implement {\it all\/} file find callbacks!) +\NC \NR +\NC + shell_escape \NC string \NC \type {'f'} \NC + Use \type {'y'} or \type {'t'} or \type {'1'} to enable \type {\write18} + unconditionally, \type {'p'} to enable the commands that are listed in \type + {shell_escape_commands} +\NC \NR +\NC + shell_escape_commands \NC string \NC \NC Comma-separated list of command + names that may be executed by \type {\write18} even if \type {shell_escape} + is set to \type {'p'}. Do {\it not\/} use spaces around commas, separate any + required command arguments by using a space, and use the \ASCII\ double quote + (\type {"}) for any needed argument or path quoting +\NC \NR + +\NC string_vacancies \NC number \NC 75000 \NC cf.\ web2c docs \NC \NR +\NC pool_free \NC number \NC 5000 \NC cf.\ web2c docs \NC \NR +\NC max_strings \NC number \NC 15000 \NC cf.\ web2c docs \NC \NR +\NC strings_free \NC number \NC 100 \NC cf.\ web2c docs \NC \NR +\NC nest_size \NC number \NC 50 \NC cf.\ web2c docs \NC \NR +\NC max_in_open \NC number \NC 15 \NC cf.\ web2c docs \NC \NR +\NC param_size \NC number \NC 60 \NC cf.\ web2c docs \NC \NR +\NC save_size \NC number \NC 4000 \NC cf.\ web2c docs \NC \NR +\NC stack_size \NC number \NC 300 \NC cf.\ web2c docs \NC \NR +\NC dvi_buf_size \NC number \NC 16384 \NC cf.\ web2c docs \NC \NR +\NC error_line \NC number \NC 79 \NC cf.\ web2c docs \NC \NR +\NC half_error_line \NC number \NC 50 \NC cf.\ web2c docs \NC \NR +\NC max_print_line \NC number \NC 79 \NC cf.\ web2c docs \NC \NR +\NC hash_extra \NC number \NC 0 \NC cf.\ web2c docs \NC \NR +\NC pk_dpi \NC number \NC 72 \NC cf.\ web2c docs \NC \NR +\NC trace_file_names \NC boolean \NC true +\NC + \type {false} disables \TEX's normal file open|-|close feedback (the + assumption is that callbacks will take care of that) +\NC \NR +\NC file_line_error \NC boolean \NC false +\NC + do \type {file:line} style error messages +\NC \NR +\NC halt_on_error \NC boolean \NC false +\NC + abort run on the first encountered error +\NC \NR +\NC formatname \NC string \NC +\NC + if no format name was given on the command line, this key will be tested first + instead of simply quitting +\NC \NR +\NC jobname \NC string \NC +\NC + if no input file name was given on the command line, this key will be tested + first instead of simply giving up +\NC \NR +\stoptabulate + +Note: the numeric values that match web2c parameters are only used if \type +{kpse_init} is explicitly set to \type {false}. In all other cases, the normal +values from \type {texmf.cnf} are used. + +\section{The \type {texio} library} + +This library takes care of the low|-|level I/O interface. + +\subsection{Printing functions} + +\subsubsection{\type {texio.write}} + +\startfunctioncall +texio.write(<string> target, <string> s, ...) +texio.write(<string> s, ...) +\stopfunctioncall + +Without the \type {target} argument, writes all given strings to the same +location(s) \TEX\ writes messages to at this moment. If \type {\batchmode} is in +effect, it writes only to the log, otherwise it writes to the log and the +terminal. The optional \type {target} can be one of three possibilities: \type +{term}, \type {log} or \type {term and log}. + +Note: If several strings are given, and if the first of these strings is or might +be one of the targets above, the \type {target} must be specified explicitly to +prevent \LUA\ from interpreting the first string as the target. + +\subsubsection{\type {texio.write_nl}} + +\startfunctioncall +texio.write_nl(<string> target, <string> s, ...) +texio.write_nl(<string> s, ...) +\stopfunctioncall + +This function behaves like \type {texio.write}, but make sure that the given +strings will appear at the beginning of a new line. You can pass a single empty +string if you only want to move to the next line. + +\subsubsection{\type {texio.setescape}} + +You can disable \type {^^} escaping of control characters by passing a value of +zero. + +\section{The \type {token} libray} + +The current \type {token} library will be replaced by a new one that is more +flexible and powerful. The transition takes place in steps. In version 0.80 we +have \type {token} and in version 0.85 the old lib will be replaced +completely. So if you use this new mechanism in production code you need to be +aware of incompatible updates between 0.80 and 0.90. Because the related in- and +output code will also be cleaned up and rewritten you should be aware of +incompatible logging and error reporting too. + +The old library presents tokens as triplets or numbers, the new library presents +a userdata object. The old library used a callback to intercept tokens in the +input but the new library provides a basic scanner infrastructure that can be +used to write macros that accept a wide range of arguments. This interface is on +purpose kept general and as performance is quite ok one can build additional +parsers without too much overhead. It's up to macro package writers to see how +they can benefit from this as the main principle behind \LUATEX\ is to provide a +minimal set of tools and no solutions. + +The current functions in the \type {token} namespace are given in the next +table: + +\starttabulate[|lT|lT|p|] +\NC \bf function \NC \bf argument \NC \bf result \NC \NR +\HL +\NC is_token \NC token \NC checks if the given argument is a token userdatum \NC \NR +\NC get_next \NC \NC returns the next token in the input \NC \NR +\NC scan_keyword \NC string \NC returns true if the given keyword is gobbled \NC \NR +\NC scan_int \NC \NC returns a number \NC \NR +\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 +\NC scan_glue \NC mu-units \NC returns a glue spec node \NC \NR +\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 +\NC scan_code \NC bitset \NC returns a character if its category is in the given bitset (representing catcodes) \NC \NR +\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 +\NC scan_word \NC \NC returns a sequence of characters with catcode 11 or 12 as string \NC \NR +\NC scan_csname \NC \NC returns \type {foo} after scanning \type {\foo} \NC \NR +\NC set_macro \NC see below \NC assign a macro \NC \NR +\NC create \NC \NC returns a userdata token object of the given control sequence name (or character); this interface can change \NC \NR +\stoptabulate + +The scanners can be considered stable apart from the one scanning for a token. +This is because futures releases can return a linked list instead of a table (as +with nodes). The \type {scan_code} function takes an optional number, the \type +{keyword} function a normal \LUA\ string. The \type {infinity} boolean signals +that we also permit \type {fill} as dimension and the \type {mu-units} flags the +scanner that we expect math units. When scanning tokens we can indicate that we +are defining a macro, in which case the result will also provide information +about what arguments are expected and in the result this is separated from the +meaning by a separator token. The \type {expand} flag determines if the list will +be expanded. + +The string scanner scans for something between curly braces and expands on the +way, or when it sees a control sequence it will return its meaning. Otherwise it +will scan characters with catcode \type {letter} or \type {other}. So, given the +following definition: + +\startbuffer +\def\bar{bar} +\def\foo{foo-\bar} +\stopbuffer + +\typebuffer \getbuffer + +we get: + +\starttabulate[|l|Tl|l|] +\NC \type {\directlua{token.scan_string()}{foo}} \NC \directlua{context("{\\red\\type {"..token.scan_string().."}}")} {foo} \NC full expansion \NR +\NC \type {\directlua{token.scan_string()}foo} \NC \directlua{context("{\\red\\type {"..token.scan_string().."}}")} foo \NC letters and others \NR +\NC \type {\directlua{token.scan_string()}\foo} \NC \directlua{context("{\\red\\type {"..token.scan_string().."}}")}\foo \NC meaning \NR +\stoptabulate + +The \type {\foo} case only gives the meaning, but one can pass an already +expanded definition (\type {\edef}'d). In the case of the braced variant one can of +course use the \type {\detokenize} and \type {\unexpanded} primitives as there we +do expand. + +The \type {scan_word} scanner can be used to implement for instance a number scanner: + +\starttyping +function token.scan_number(base) + return tonumber(token.scan_word(),base) +end +\stoptyping + +This scanner accepts any valid \LUA\ number so it is a way to pick up floats +in the input. + +The creator function can be used as follows: + +\starttyping +local t = token.create("relax") +\stoptyping + +This gives back a token object that has the properties of the \type {\relax} +primitive. The possible properties of tokens are: + +\starttabulate[|lT|p|] +\NC command \NC a number representing the internal command number \NC \NR +\NC cmdname \NC the type of the command (for instance the catcode in case of a + character or the classifier that determines the internal + treatment \NC \NR +\NC csname \NC the associated control sequence (if applicable) \NC \NR +\NC id \NC the unique id of the token \NC \NR +%NC tok \NC \NC \NR % might change +\NC active \NC a boolean indicating the active state of the token \NC \NR +\NC expandable \NC a boolean indicating if the token (macro) is expandable \NC \NR +\NC protected \NC a boolean indicating if the token (macro) is protected \NC \NR +\stoptabulate + +The numbers that represent a catcode are the same as in \TEX\ itself, so using +this information assumes that you know a bit about \TEX's internals. The other +numbers and names are used consistently but are not frozen. So, when you use them +for comparing you can best query a known primitive or character first to see the +values. + +More interesting are the scanners. You can use the \LUA\ interface as follows: + +\starttyping +\directlua { + function mymacro(n) + ... + end +} + +\def\mymacro#1{% + \directlua { + mymacro(\number\dimexpr#1) + }% +} + +\mymacro{12pt} +\mymacro{\dimen0} +\stoptyping + +You can also do this: + +\starttyping +\directlua { + function mymacro() + local d = token.scan_dimen() + ... + end +} + +\def\mymacro{% + \directlua { + mymacro() + }% +} + +\mymacro 12pt +\mymacro \dimen0 +\stoptyping + +It is quite clear from looking at the code what the first method needs as +argument(s). For the second method you need to look at the \LUA\ code to see what +gets picked up. Instead of passing from \TEX\ to \LUA\ we let \LUA\ fetch from +the input stream. + +In the first case the input is tokenized and then turned into a string when it's +passed to \LUA\ where it gets interpreted. In the second case only a function +call gets interpreted but then the input is picked up by explicitly calling the +scanner functions. These return proper \LUA\ variables so no further conversion +has to be done. This is more efficient but in practice (given what \TEX\ has to +do) this effect should not be overestimated. For numbers and dimensions it saves a +bit but for passing strings conversion to and from tokens has to be done anyway +(although we can probably speed up the process in later versions if needed). + +When the interface is stable and has replaced the old one completely we will add +some more information here. By that time the internals have been cleaned up a bit +more so we know then what will stay and go. A positive side effect of this +transition is that we can simplify the input part because we no longer need to +intercept using callbacks. + +The \type {set_macro} function can get upto 4 arguments: + +\starttyping +setmacro("csname","content") +setmacro("csname","content","global") +setmacro("csname") +\stoptyping + +You can pass a catcodetable identifier as first argument: + +\starttyping +setmacro(catcodetable,"csname","content") +setmacro(catcodetable,"csname","content","global") +setmacro(catcodetable,"csname") +\stoptyping + +The results are like: + +\starttyping + \def\csname{content} +\gdef\csname{content} + \def\csname{} +\stoptyping + +There is a (for now) experimental putter: + +\starttyping +local t1 = token.get_next() +local t2 = token.get_next() +local t3 = token.get_next() +local t4 = token.get_next() +-- watch out, we flush in sequence +token.put_next { t1, t2 } +-- but this one gets pushed in front +token.put_next ( t3, t4 ) +\stoptyping + +When we scan \type {wxyz!} we get \type {yzwx!} back. The argument is either a table +with tokens or a list of tokens. + +\section{The \type {kpse} library} + +This library provides two separate, but nearly identical interfaces to the +\KPATHSEA\ file search functionality: there is a \quote {normal} procedural +interface that shares its kpathsea instance with \LUATEX\ itself, and an object +oriented interface that is completely on its own. + +\subsection{\type {kpse.set_program_name} and \type {kpse.new}} + +Before the search library can be used at all, its database has to be initialized. +There are three possibilities, two of which belong to the procedural interface. + +First, when \LUATEX\ is used to typeset documents, this initialization happens +automatically and the \KPATHSEA\ executable and program names are set to \type +{luatex} (that is, unless explicitly prohibited by the user's startup script. +See~\in {section} [init] for more details). + +Second, in \TEXLUA\ mode, the initialization has to be done explicitly via the +\type {kpse.set_program_name} function, which sets the \KPATHSEA\ executable +(and optionally program) name. + +\startfunctioncall +kpse.set_program_name(<string> name) +kpse.set_program_name(<string> name, <string> progname) +\stopfunctioncall + +The second argument controls the use of the \quote {dotted} values in the \type +{texmf.cnf} configuration file, and defaults to the first argument. + +Third, if you prefer the object oriented interface, you have to call a different +function. It has the same arguments, but it returns a userdata variable. + +\startfunctioncall +local kpathsea = kpse.new(<string> name) +local kpathsea = kpse.new(<string> name, <string> progname) +\stopfunctioncall + +Apart from these two functions, the calling conventions of the interfaces are +identical. Depending on the chosen interface, you either call \type +{kpse.find_file()} or \type {kpathsea:find_file()}, with identical arguments and +return vales. + +\subsection{\type {find_file}} + +The most often used function in the library is \type {find_file}: + +\startfunctioncall +<string> f = kpse.find_file(<string> filename) +<string> f = kpse.find_file(<string> filename, <string> ftype) +<string> f = kpse.find_file(<string> filename, <boolean> mustexist) +<string> f = kpse.find_file(<string> filename, <string> ftype, <boolean> mustexist) +<string> f = kpse.find_file(<string> filename, <string> ftype, <number> dpi) +\stopfunctioncall + +Arguments: + +\startitemize[intro] + +\sym{filename} + +the name of the file you want to find, with or without extension. + +\sym{ftype} + +maps to the \type {-format} argument of \KPSEWHICH. The supported \type {ftype} +values are the same as the ones supported by the standalone \type {kpsewhich} +program: \startluacode + local list = { + "afm", + "base", + "bib", + "bitmap font", + "bst", + "cid maps", + "clua", + "cmap files", + "cnf", + "cweb", + "dvips config", + "enc files", + "fmt", + "font feature files", + "gf", + "graphic|/|figure", + "ist", + "lig files", + "ls-R", + "lua", + "map", + "mem", + "MetaPost support", + "mf", + "mfpool", + "mft", + "misc fonts", + "mlbib", + "mlbst", + "mp", + "mppool", + "ocp", + "ofm", + "opentype fonts", + "opl", + "other binary files", + "other text files", + "otp", + "ovf", + "ovp", + "pdftex config", + "pk", + "PostScript header", + "subfont definition files", + "tex", + "TeX system documentation", + "TeX system sources", + "texmfscripts", + "texpool", + "tfm", + "Troff fonts", + "truetype fonts", + "type1 fonts", + "type42 fonts", + "vf", + "web", + "web2c files", + } + table.sort(list) + context("{\\tttf \letterpercent, t}",list) +\stopluacode + +The default type is \type {tex}. Note: this is different from \KPSEWHICH, which +tries to deduce the file type itself from looking at the supplied extension. + +\sym{mustexist} + +is similar to \KPSEWHICH's \type {-must-exist}, and the default is \type {false}. +If you specify \type {true} (or a non|-|zero integer), then the \KPSE\ library +will search the disk as well as the \type {ls-R} databases. + +\sym{dpi} + +This is used for the size argument of the formats \type {pk}, \type {gf}, and +\type {bitmap font}. \stopitemize + + +\subsection{\type {lookup}} + +A more powerful (but slower) generic method for finding files is also available. +It returns a string for each found file. + +\startfunctioncall +<string> f, ... = kpse.lookup(<string> filename, <table> options) +\stopfunctioncall + +The options match commandline arguments from \type {kpsewhich}: + +\starttabulate[|l|l|p|] +\NC \rmbf key \NC \rmbf type \NC \rmbf description \NC \NR +\NC debug \NC number \NC set debugging flags for this lookup\NC \NR +\NC format \NC string \NC use specific file type (see list above)\NC \NR +\NC dpi \NC number \NC use this resolution for this lookup; default 600\NC \NR +\NC path \NC string \NC search in the given path\NC \NR +\NC all \NC boolean \NC output all matches, not just the first\NC \NR +\NC mustexist \NC boolean \NC search the disk as well as ls-R if necessary\NC \NR +\NC mktexpk \NC boolean \NC disable/enable mktexpk generation for this lookup\NC \NR +\NC mktextex \NC boolean \NC disable/enable mktextex generation for this lookup\NC \NR +\NC mktexmf \NC boolean \NC disable/enable mktexmf generation for this lookup\NC \NR +\NC mktextfm \NC boolean \NC disable/enable mktextfm generation for this lookup\NC \NR +\NC subdir \NC string + or table \NC only output matches whose directory part + ends with the given string(s) \NC \NR +\stoptabulate + +\subsection{\type {init_prog}} + +Extra initialization for programs that need to generate bitmap fonts. + +\startfunctioncall +kpse.init_prog(<string> prefix, <number> base_dpi, <string> mfmode) +kpse.init_prog(<string> prefix, <number> base_dpi, <string> mfmode, <string> fallback) +\stopfunctioncall + +\subsection{\type {readable_file}} + +Test if an (absolute) file name is a readable file. + +\startfunctioncall +<string> f = kpse.readable_file(<string> name) +\stopfunctioncall + +The return value is the actual absolute filename you should use, because the disk +name is not always the same as the requested name, due to aliases and +system|-|specific handling under e.g.\ \MSDOS. Returns \type {nil} if the file +does not exist or is not readable. + +\subsection{\type {expand_path}} + +Like kpsewhich's \type {-expand-path}: + +\startfunctioncall +<string> r = kpse.expand_path(<string> s) +\stopfunctioncall + +\subsection{\type {expand_var}} + +Like kpsewhich's \type {-expand-var}: + +\startfunctioncall +<string> r = kpse.expand_var(<string> s) +\stopfunctioncall + +\subsection{\type {expand_braces}} + +Like kpsewhich's \type {-expand-braces}: + +\startfunctioncall +<string> r = kpse.expand_braces(<string> s) +\stopfunctioncall + +\subsection{\type {show_path}} + +Like kpsewhich's \type {-show-path}: + +\startfunctioncall +<string> r = kpse.show_path(<string> ftype) +\stopfunctioncall + + +\subsection{\type {var_value}} + +Like kpsewhich's \type {-var-value}: + +\startfunctioncall +<string> r = kpse.var_value(<string> s) +\stopfunctioncall + +\subsection{\type {version}} + +Returns the kpathsea version string. + +\startfunctioncall +<string> r = kpse.version() +\stopfunctioncall + +\stopchapter + +\stopcomponent |