diff options
author | Luigi Scarso <luigi.scarso@gmail.com> | 2019-01-06 19:35:42 +0000 |
---|---|---|
committer | Luigi Scarso <luigi.scarso@gmail.com> | 2019-01-06 19:35:42 +0000 |
commit | 522dfa21dfa73176aedd7412314b510564144cfc (patch) | |
tree | a8a2796313a30d939d99f74f6e0df648f1259148 /Master/texmf-dist/doc/luatex/base/luatex-tex.tex | |
parent | 0c14fd18747b9f6fbbecb75ba8beef6d449c460a (diff) |
updated reference manual for luatex 1.09.2
git-svn-id: svn://tug.org/texlive/trunk@49615 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 | 4825 |
1 files changed, 2755 insertions, 2070 deletions
diff --git a/Master/texmf-dist/doc/luatex/base/luatex-tex.tex b/Master/texmf-dist/doc/luatex/base/luatex-tex.tex index 2dd9521c4dd..6b1ba1689b0 100644 --- a/Master/texmf-dist/doc/luatex/base/luatex-tex.tex +++ b/Master/texmf-dist/doc/luatex/base/luatex-tex.tex @@ -1,2070 +1,2755 @@ -% 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[|l|p|] -\BC key \BC explanation \NC \NR -\NC \type{banner} \NC terminal display banner \NC \NR -\NC \type{best_page_break} \NC the current best break (a node) \NR \NR -\NC \type{buf_size} \NC current allocated size of the line buffer \NC \NR -\NC \type{callbacks} \NC total number of executed callbacks so far \NC \NR -\NC \type{cs_count} \NC number of control sequences \NC \NR -\NC \type{dest_names_size} \NC \PDF\ destination table size \NC \NR -\NC \type{dvi_gone} \NC written \DVI\ bytes \NC \NR -\NC \type{dvi_ptr} \NC not yet written \DVI\ bytes \NC \NR -\NC \type{dyn_used} \NC token (multi|-|word) memory in use \NC \NR -\NC \type{filename} \NC name of the current input file \NC \NR -\NC \type{fix_mem_end} \NC maximum number of used tokens \NC \NR -\NC \type{fix_mem_min} \NC minimum number of allocated words for tokens \NC \NR -\NC \type{fix_mem_max} \NC maximum number of allocated words for tokens \NC \NR -\NC \type{font_ptr} \NC number of active fonts \NC \NR -\NC \type{hash_extra} \NC extra allowed hash \NC \NR -\NC \type{hash_size} \NC size of hash \NC \NR -\NC \type{indirect_callbacks} \NC number of those that were themselves a result of other callbacks (e.g. file readers) \NC \NR -\NC \type{ini_version} \NC \type {true} if this is an \INITEX\ run \NC \NR -\NC \type{init_pool_ptr} \NC \INITEX\ string pool index \NC \NR -\NC \type{init_str_ptr} \NC number of \INITEX\ strings \NC \NR -\NC \type{input_ptr} \NC th elevel of input we're at \NC \NR -\NC \type{inputid} \NC numeric id of the current input \NC \NR -\NC \type{largest_used_mark} \NC max referenced marks class \NC \NR -\NC \type{lasterrorcontext} \NC last error context string (with newlines) \NC \NR -\NC \type{lasterrorstring} \NC last \TEX\ error string \NC \NR -\NC \type{lastluaerrorstring} \NC last \LUA\ error string \NC \NR -\NC \type{lastwarningstring} \NC last warning tag, normally an indication of in what part\NC \NR -\NC \type{lastwarningtag} \NC last warning string\NC \NR -\NC \type{linenumber} \NC location in the current input file \NC \NR -\NC \type{log_name} \NC name of the log file \NC \NR -\NC \type{luabytecode_bytes} \NC number of bytes in \LUA\ bytecode registers \NC \NR -\NC \type{luabytecodes} \NC number of active \LUA\ bytecode registers \NC \NR -\NC \type{luastate_bytes} \NC number of bytes in use by \LUA\ interpreters \NC \NR -\NC \type{luatex_engine} \NC the \LUATEX\ engine identifier \NC \NR -\NC \type{luatex_hashchars} \NC length to which \LUA\ hashes strings ($2^n$) \NC \NR -\NC \type{luatex_hashtype} \NC the hash method used (in \LUAJITTEX) \NC \NR -\NC \type{luatex_revision} \NC the \LUATEX\ revision string \NC \NR -\NC \type{luatex_revision} \NC the \LUATEX\ revision string \NC \NR -\NC \type{luatex_version} \NC the \LUATEX\ version number \NC \NR -\NC \type{max_buf_stack} \NC max used buffer position \NC \NR -\NC \type{max_in_stack} \NC max used input stack entries \NC \NR -\NC \type{max_nest_stack} \NC max used nesting stack entries \NC \NR -\NC \type{max_param_stack} \NC max used parameter stack entries \NC \NR -\NC \type{max_save_stack} \NC max used save stack entries \NC \NR -\NC \type{max_strings} \NC maximum allowed strings \NC \NR -\NC \type{nest_size} \NC nesting stack size \NC \NR -\NC \type{node_mem_usage} \NC a string giving insight into currently used nodes \NC \NR -\NC \type{obj_ptr} \NC max \PDF\ object pointer \NC \NR -\NC \type{obj_tab_size} \NC \PDF\ object table size \NC \NR -\NC \type{output_active} \NC \type {true} if the \type {\output} routine is active \NC \NR -\NC \type{output_file_name} \NC name of the \PDF\ or \DVI\ file \NC \NR -\NC \type{param_size} \NC parameter stack size \NC \NR -\NC \type{pdf_dest_names_ptr} \NC max \PDF\ destination pointer \NC \NR -\NC \type{pdf_gone} \NC written \PDF\ bytes \NC \NR -\NC \type{pdf_mem_ptr} \NC max \PDF\ memory used \NC \NR -\NC \type{pdf_mem_size} \NC \PDF\ memory size \NC \NR -\NC \type{pdf_os_cntr} \NC max \PDF\ object stream pointer \NC \NR -\NC \type{pdf_os_objidx} \NC \PDF\ object stream index \NC \NR -\NC \type{pdf_ptr} \NC not yet written \PDF\ bytes \NC \NR -\NC \type{pool_ptr} \NC string pool index \NC \NR -\NC \type{pool_size} \NC current size allocated for string characters \NC \NR -\NC \type{save_size} \NC save stack size \NC \NR -\NC \type{shell_escape} \NC \type {0} means disabled, \type {1} means anything is permitted, and \type {2} is restricted \NC \NR -\NC \type{safer_option} \NC \type {1} means safer is enforced \NC \NR -\NC \type{kpse_used} \NC \type {1} means that kpse is used \NC \NR -\NC \type{stack_size} \NC input stack size \NC \NR -\NC \type{str_ptr} \NC number of strings \NC \NR -\NC \type{total_pages} \NC number of written pages \NC \NR -\NC \type{var_mem_max} \NC number of allocated words for nodes \NC \NR -\NC \type{var_used} \NC variable (one|-|word) memory in use \NC \NR -\NC \type{lc_collate} \NC the value of \type {LC_COLLATE} at startup time (becomes \type {C} at startup) \NC \NR -\NC \type{lc_ctype} \NC the value of \type {LC_CTYPE} at startup time (becomes \type {C} at startup) \NC \NR -%NC \type{lc_monetary} \NC the value of \type {LC_MONETARY} at startup time \NC \NR -\NC \type{lc_numeric} \NC the value of \type {LC_NUMERIC} at startup time \NC \NR -%NC \type{lc_time} \NC the value of \type {LC_TIME} at startup time (becomes \type {C} at startup) \NC \NR -\stoptabulate - -The error and warning messages can be wiped with the \type {resetmessages} -function. A return value can be set with \type {setexitcode}. - -\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}. - -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 - -Glue is kind of special because there are five values involved. The return value -is a \type {glue_spec} node btu when you pass \type {false} as last argument to -\type {tex.get} you get the width of the glue and when you pass \type {true} you -get all five values. Otherwise you get a node which is a copy of the internal -value so you are responsible for its freeing at the \LUA\ end. When you set a -glue quantity you can either pass a \type {glue_spec} or upto five numbers. If -you pass \type {true} to \type {get} you get 5 values returned for a glue and -when you pass \type {false} you only get the width returned. - -For the registers you can use \type {getskip} (node), \type {getglue} (numbers) -\type {setskip} (node) and \type {setglue} (numbers). If you pass \type {false} -as second argument to \type {getglue} you only get the width returned. - -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 -\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.fontname(number) -tex.uniformdeviate(number) -tex.number(number) -tex.romannumeral(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.lastxpos -tex.lastypos -tex.randomseed -tex.luatexversion -tex.eTeXminorversion -tex.eTeXversion -tex.currentgrouplevel -tex.currentgrouptype -tex.currentiflevel -tex.currentiftype -tex.currentifbranch -\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> class, - <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 -tex.setmathcode (["global"], <number> n, <number> class, - <number> family, <number> character) -class, family, char = - tex.getmathcodes (<number> n) -tex.setdelcode (["global"], <number> n, <number> smallfam, - <number> smallchar, <number> largefam, <number> largechar) -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,type,margin) -\stoptyping - -The optional second and third arguments are strings, the fourth is a boolean. The -fifth argument is a type. When set to non|-|zero the \type {/Type} entry is -omitted. A value of 1 or 3 still writes a \type {/BBox}, while 2 or 3 will write -a \type {/Matrix}. The sixth argument is the (virtual) margin that extends beyond -the effective boundingbox as seen by \TEX. - -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, m = tex.getboxresourcedimensions(n) -\stoptyping - -This returns the width, height, depth and margin of the resource. - -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[|l|p|] -\BC field \BC description \NC \NR -\NC \type{page_ins_head} \NC circular list of pending insertions \NC \NR -\NC \type{contrib_head} \NC the recent contributions \NC \NR -\NC \type{page_head} \NC the current page content \NC \NR -%NC \type{temp_head} \NC \NC \NR -\NC \type{hold_head} \NC used for held-over items for next page \NC \NR -\NC \type{adjust_head} \NC head of the current \type {\vadjust} list \NC \NR -\NC \type{pre_adjust_head} \NC head of the current \type {\vadjust pre} list \NC \NR -%NC \type{align_head} \NC \NC \NR -\NC \type{page_discards_head} \NC head of the discarded items of a page break \NC \NR -\NC \type{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[|l|l|l|p|] -\BC key \BC type \BC modes \BC explanation \NC \NR -\NC \type{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 \type{modeline} \NC number \NC all \NC source input line where this mode was entered in, - negative inside the output routine \NC \NR -\NC \type{head} \NC node \NC all \NC the head of the current list \NC \NR -\NC \type{tail} \NC node \NC all \NC the tail of the current list \NC \NR -\NC \type{prevgraf} \NC number \NC vmode \NC number of lines in the previous paragraph \NC \NR -\NC \type{prevdepth} \NC number \NC vmode \NC depth of the previous paragraph \NC \NR -\NC \type{spacefactor} \NC number \NC hmode \NC the current space factor \NC \NR -\NC \type{dirs} \NC node \NC hmode \NC used for temporary storage by the line break algorithm\NC \NR -\NC \type{noad} \NC node \NC mmode \NC used for temporary storage of a pending fraction numerator, - for \type {\over} etc. \NC \NR -\NC \type{delimptr} \NC node \NC mmode \NC used for temporary storage of the previous math delimiter, - for \type {\middle} \NC \NR -\NC \type{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 \type{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 list of names. 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. You can use \type -{token.create} to inspect properties, for instance when the \type {command} key -in a created table equals \type {123}, you have the \type {cmdname} value \type -{undefined_cs}. - -\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|] -\BC name \BC 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","luatex")}. - -\subsubsection{\type {tex.primitives}} - -\startfunctioncall -<table> t = tex.primitives() -\stopfunctioncall - -This function returns a list of all primitives that \LUATEX\ knows about. - -\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|] -\BC name \BC type \BC description \NC \NR -\NC \type{pardir} \NC string \NC \NC \NR -\NC \type{pretolerance} \NC number \NC \NC \NR -\NC \type{tracingparagraphs} \NC number \NC \NC \NR -\NC \type{tolerance} \NC number \NC \NC \NR -\NC \type{looseness} \NC number \NC \NC \NR -\NC \type{hyphenpenalty} \NC number \NC \NC \NR -\NC \type{exhyphenpenalty} \NC number \NC \NC \NR -\NC \type{pdfadjustspacing} \NC number \NC \NC \NR -\NC \type{adjdemerits} \NC number \NC \NC \NR -\NC \type{pdfprotrudechars} \NC number \NC \NC \NR -\NC \type{linepenalty} \NC number \NC \NC \NR -\NC \type{lastlinefit} \NC number \NC \NC \NR -\NC \type{doublehyphendemerits} \NC number \NC \NC \NR -\NC \type{finalhyphendemerits} \NC number \NC \NC \NR -\NC \type{hangafter} \NC number \NC \NC \NR -\NC \type{interlinepenalty} \NC number or table \NC if a table, then it is an array like \type {\interlinepenalties} \NC \NR -\NC \type{clubpenalty} \NC number or table \NC if a table, then it is an array like \type {\clubpenalties} \NC \NR -\NC \type{widowpenalty} \NC number or table \NC if a table, then it is an array like \type {\widowpenalties} \NC \NR -\NC \type{brokenpenalty} \NC number \NC \NC \NR -\NC \type{emergencystretch} \NC number \NC in scaled points \NC \NR -\NC \type{hangindent} \NC number \NC in scaled points \NC \NR -\NC \type{hsize} \NC number \NC in scaled points \NC \NR -\NC \type{leftskip} \NC glue_spec node \NC \NC \NR -\NC \type{rightskip} \NC glue_spec node \NC \NC \NR -\NC \type{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. - -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. - -\subsection[synctex]{Functions related to synctex} - -The next helpers only make sense when you implement your own synctex logic. Keep in -mind that the library used in editors assumes a certain logic and is geared for -plain and \LATEX, so after a decade users expect a certain behaviour. - -\starttabulate[|l|p|] -\NC \type{set_synctex_mode} \NC \type {0} is the default and used normal synctex - logic, \type {1} uses the values set by the next - helpers while \type {2} also sets these for glyph - nodes; \type{3} sets glyphs and glue and \type {4} - sets only glyphs \NC \NR -\NC \type{set_synctex_tag} \NC set the current tag (file) value (obeys save stack) \NC \NR -\NC \type{set_synctex_line} \NC set the current line value (obeys save stack) \NC \NR -\NC \type{force_synctex_tag} \NC overload the tag (file) value (\type {0} resets) \NC \NR -\NC \type{force_synctex_line} \NC overload the line value (\type {0} resets) \NC \NR -\NC \type{get_synctex_tag} \NC get the currently set value of tag (file) \NC \NR -\NC \type{get_synctex_line} \NC get the currently set value of line \NC \NR -\NC \type{set_synctex_no_files} \NC disable synctex file logging \NC \NR -\stoptabulate - -The last one is somewhat special. Due to the way files are registered in \SYNCTEX\ we need -to explicitly disable that feature if we provide our own alternative if we want to avoid -that overhead. Passing a value of 1 disables registering. - -This mechanism is somewhat experimental. - -\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[|l|l|l|p|] -\BC key \BC type \BC default \BC explanation \NC \NR -\NC \type{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 - \type{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 \type{string_vacancies} \NC number \NC 75000 \NC cf.\ web2c docs \NC \NR -\NC \type{pool_free} \NC number \NC 5000 \NC cf.\ web2c docs \NC \NR -\NC \type{max_strings} \NC number \NC 15000 \NC cf.\ web2c docs \NC \NR -\NC \type{strings_free} \NC number \NC 100 \NC cf.\ web2c docs \NC \NR -\NC \type{nest_size} \NC number \NC 50 \NC cf.\ web2c docs \NC \NR -\NC \type{max_in_open} \NC number \NC 15 \NC cf.\ web2c docs \NC \NR -\NC \type{param_size} \NC number \NC 60 \NC cf.\ web2c docs \NC \NR -\NC \type{save_size} \NC number \NC 4000 \NC cf.\ web2c docs \NC \NR -\NC \type{stack_size} \NC number \NC 300 \NC cf.\ web2c docs \NC \NR -\NC \type{dvi_buf_size} \NC number \NC 16384 \NC cf.\ web2c docs \NC \NR -\NC \type{error_line} \NC number \NC 79 \NC cf.\ web2c docs \NC \NR -\NC \type{half_error_line} \NC number \NC 50 \NC cf.\ web2c docs \NC \NR -\NC \type{max_print_line} \NC number \NC 79 \NC cf.\ web2c docs \NC \NR -\NC \type{hash_extra} \NC number \NC 0 \NC cf.\ web2c docs \NC \NR -\NC \type{pk_dpi} \NC number \NC 72 \NC cf.\ web2c docs \NC \NR -\NC \type{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 \type{file_line_error} \NC boolean \NC false -\NC - do \type {file:line} style error messages -\NC \NR -\NC \type{halt_on_error} \NC boolean \NC false -\NC - abort run on the first encountered error -\NC \NR -\NC \type{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 \type{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: writing to the log file -and|/|or console. - -\subsection{\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. - -\subsection{\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. - -\subsection{\type {texio.setescape}} - -You can disable \type {^^} escaping of control characters by passing a value of -zero. - -\section{The \type {token} library} - -\subsection{The scanner} - -The token library provides means to intercept the input and deal with it at the -\LUA\ level. The 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 functions provided in the \type -{token} namespace are given in the next table: - -\starttabulate[|l|l|p|] -\BC function \BC argument \BC result \NC \NR -\HL -\NC \type{is_token} \NC token \NC checks if the given argument is a token userdatum \NC \NR -\NC \type{get_next} \NC \NC returns the next token in the input \NC \NR -\NC \type{scan_keyword} \NC string \NC returns true if the given keyword is gobbled \NC \NR -\NC \type{scan_int} \NC \NC returns a number \NC \NR -\NC \type{scan_dimen} \NC infinity, mu-units \NC returns a number representing a dimension and or two numbers being the filler and order \NC \NR -\NC \type{scan_glue} \NC mu-units \NC returns a glue spec node \NC \NR -\NC \type{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 \type{scan_code} \NC bitset \NC returns a character if its category is in the given bitset (representing catcodes) \NC \NR -\NC \type{scan_string} \NC \NC returns a string given between \type {{}}, as \type {\macro} or as sequence of characters with catcode 11 or 12 \NC \NR -\NC \type{scan_word} \NC \NC returns a sequence of characters with catcode 11 or 12 as string \NC \NR -\NC \type{scan_csname} \NC \NC returns \type {foo} after scanning \type {\foo} \NC \NR -\NC \type{set_macro} \NC see below \NC assign a macro \NC \NR -\NC \type{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 \NC \NR -\NC \type {\directlua{token.scan_string()}foo} \NC \directlua{context("{\\red\\type {"..token.scan_string().."}}")} foo \NC letters and others \NC \NR -\NC \type {\directlua{token.scan_string()}\foo} \NC \directlua{context("{\\red\\type {"..token.scan_string().."}}")}\foo \NC meaning \NC \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[|l|p|] -\NC \type {command} \NC a number representing the internal command number \NC \NR -\NC \type {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 \type{csname} \NC the associated control sequence (if applicable) \NC \NR -\NC \type{id} \NC the unique id of the token \NC \NR -%NC \type{tok} \NC \NC \NR % might change -\NC \type{active} \NC a boolean indicating the active state of the token \NC \NR -\NC \type{expandable} \NC a boolean indicating if the token (macro) is expandable \NC \NR -\NC \type{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). - -\subsection{Macros} - -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 - -\subsection{Pushing back} - -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. - -\subsection{Nota bene} - -When scanning for the next token you need to keep in mind that we're not scanning -like \TEX\ does: expanding, changing modes and doing things as it goes. When we -scan with \LUA\ we just pick up tokens. Say that we have: - -\starttyping -\bar -\stoptyping - -but \type {\bar} is undefined. Normally \TEX\ will then issue an error message. -However, when we have: - -\starttyping -\def\foo{\bar} -\stoptyping - -We get no error, unless we expand \type {\foo} while \type {\bar} is still -undefined. What happens is that as soon as \TEX\ sees an undefined macro it will -create a hash entry and when later it gets defined that entry will be reused. So, -\type {\bar} really exists but can be in an undefined state. - -\startbuffer[demo] -bar : \directlua{tex.print(token.scan_csname())}\bar -foo : \directlua{tex.print(token.scan_csname())}\foo -myfirstbar : \directlua{tex.print(token.scan_csname())}\myfirstbar -\stopbuffer - -\startlines -\getbuffer[demo] -\stoplines - -This was entered as: - -\typebuffer[demo] - -The reason that you see \type {bar} reported and not \type {myfirstbar} is that -\type {\bar} was already used in a previous paragraph. - -If we now say: - -\startbuffer -\def\foo{} -\stopbuffer - -\typebuffer \getbuffer - -we get: - -\startlines -\getbuffer[demo] -\stoplines - -And if we say - -\startbuffer -\def\foo{\bar} -\stopbuffer - -\typebuffer \getbuffer - -we get: - -\startlines -\getbuffer[demo] -\stoplines - -When scanning from \LUA\ we are not in a mode that defines (undefined) macros at -all. There we just get the real primitive undefined macro token. - -\startbuffer -\directlua{local t = token.get_next() tex.print(t.id.." "..t.tok)}\myfirstbar -\directlua{local t = token.get_next() tex.print(t.id.." "..t.tok)}\mysecondbar -\directlua{local t = token.get_next() tex.print(t.id.." "..t.tok)}\mythirdbar -\stopbuffer - -\startlines -\getbuffer -\stoplines - -This was generated with: - -\typebuffer - -So, we do get a unique token because after all we need some kind of \LUA\ object -that can be used and garbage collected, but it is basically the same one, -representing an undefined control sequence. - -\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|] -\BC key \BC type \BC description \NC \NR -\NC \type{debug} \NC number \NC set debugging flags for this lookup\NC \NR -\NC \type{format} \NC string \NC use specific file type (see list above)\NC \NR -\NC \type{dpi} \NC number \NC use this resolution for this lookup; default 600\NC \NR -\NC \type{path} \NC string \NC search in the given path\NC \NR -\NC \type{all} \NC boolean \NC output all matches, not just the first\NC \NR -\NC \type{mustexist} \NC boolean \NC search the disk as well as ls-R if necessary\NC \NR -\NC \type{mktexpk} \NC boolean \NC disable/enable mktexpk generation for this lookup\NC \NR -\NC \type{mktextex} \NC boolean \NC disable/enable mktextex generation for this lookup\NC \NR -\NC \type{mktexmf} \NC boolean \NC disable/enable mktexmf generation for this lookup\NC \NR -\NC \type{mktextfm} \NC boolean \NC disable/enable mktextfm generation for this lookup\NC \NR -\NC \type{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 +% language=uk
+
+% lua.newtable
+
+\environment luatex-style
+
+\startcomponent luatex-tex
+
+\startchapter[reference=tex,title={The \TEX\ related libraries}]
+
+\startsection[title={The \type {lua} library}][library=lua]
+
+\startsubsection[title={Version information}]
+
+\topicindex{libraries+\type{lua}}
+\topicindex{version}
+
+\libindex{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)}.
+
+\stopsubsection
+
+\startsubsection[title={Bytecode registers}]
+
+\topicindex{bytecodes}
+\topicindex{registers+bytecodes}
+
+\libindex{bytecode}
+\libindex{setbytecode}
+\libindex{getbytecode}
+
+\LUA\ registers can be used to store \LUA\ code 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. The
+function must not contain any upvalues. 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.
+
+\stopsubsection
+
+\startsubsection[title={Chunk name registers}]
+
+\libindex{name}
+\libindex{setluaname}
+\libindex{getluaname}
+
+There is an array of 65536 (0--65535) potential chunk names for use with the
+\prm {directlua} and \lpr {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. The function
+accessors are:
+
+\startfunctioncall
+lua.setluaname(<string> s,<number> n])
+<string> s = lua.getluaname(<number> n)
+\stopfunctioncall
+
+\stopsubsection
+
+\startsubsection[title={Introspection}]
+
+\libindex{getstacktop}
+\libindex{getcalllevel}
+
+The \type {getstacktop} and\type {getcalllevel} functions return numbers
+indicating how much nesting is going on. They are only of use as breakpoints when
+checking some mechanism going haywire.
+
+\stopsubsection
+
+\stopsection
+
+\startsection[title={The \type {status} library}][library=status]
+
+\topicindex{libraries+\type{status}}
+
+\libindex{list}
+\libindex{resetmessages}
+\libindex{setexitcode}
+
+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[|l|p|]
+\DB key \BC explanation \NC \NR
+\TB
+\NC \type{banner} \NC terminal display banner \NC \NR
+\NC \type{best_page_break} \NC the current best break (a node) \NC \NR
+\NC \type{buf_size} \NC current allocated size of the line buffer \NC \NR
+\NC \type{callbacks} \NC total number of executed callbacks so far \NC \NR
+\NC \type{cs_count} \NC number of control sequences \NC \NR
+\NC \type{dest_names_size} \NC \PDF\ destination table size \NC \NR
+\NC \type{dvi_gone} \NC written \DVI\ bytes \NC \NR
+\NC \type{dvi_ptr} \NC not yet written \DVI\ bytes \NC \NR
+\NC \type{dyn_used} \NC token (multi|-|word) memory in use \NC \NR
+\NC \type{filename} \NC name of the current input file \NC \NR
+\NC \type{fix_mem_end} \NC maximum number of used tokens \NC \NR
+\NC \type{fix_mem_min} \NC minimum number of allocated words for tokens \NC \NR
+\NC \type{fix_mem_max} \NC maximum number of allocated words for tokens \NC \NR
+\NC \type{font_ptr} \NC number of active fonts \NC \NR
+\NC \type{hash_extra} \NC extra allowed hash \NC \NR
+\NC \type{hash_size} \NC size of hash \NC \NR
+\NC \type{indirect_callbacks} \NC number of those that were themselves a result of other callbacks (e.g. file readers) \NC \NR
+\NC \type{ini_version} \NC \type {true} if this is an \INITEX\ run \NC \NR
+\NC \type{init_pool_ptr} \NC \INITEX\ string pool index \NC \NR
+\NC \type{init_str_ptr} \NC number of \INITEX\ strings \NC \NR
+\NC \type{input_ptr} \NC the level of input we're at \NC \NR
+\NC \type{inputid} \NC numeric id of the current input \NC \NR
+\NC \type{largest_used_mark} \NC max referenced marks class \NC \NR
+\NC \type{lasterrorcontext} \NC last error context string (with newlines) \NC \NR
+\NC \type{lasterrorstring} \NC last \TEX\ error string \NC \NR
+\NC \type{lastluaerrorstring} \NC last \LUA\ error string \NC \NR
+\NC \type{lastwarningstring} \NC last warning tag, normally an indication of in what part\NC \NR
+\NC \type{lastwarningtag} \NC last warning string\NC \NR
+\NC \type{linenumber} \NC location in the current input file \NC \NR
+\NC \type{log_name} \NC name of the log file \NC \NR
+\NC \type{luabytecode_bytes} \NC number of bytes in \LUA\ bytecode registers \NC \NR
+\NC \type{luabytecodes} \NC number of active \LUA\ bytecode registers \NC \NR
+\NC \type{luastate_bytes} \NC number of bytes in use by \LUA\ interpreters \NC \NR
+\NC \type{luatex_engine} \NC the \LUATEX\ engine identifier \NC \NR
+\NC \type{luatex_hashchars} \NC length to which \LUA\ hashes strings ($2^n$) \NC \NR
+\NC \type{luatex_hashtype} \NC the hash method used (in \LUAJITTEX) \NC \NR
+\NC \type{luatex_version} \NC the \LUATEX\ version number \NC \NR
+\NC \type{luatex_revision} \NC the \LUATEX\ revision string \NC \NR
+\NC \type{max_buf_stack} \NC max used buffer position \NC \NR
+\NC \type{max_in_stack} \NC max used input stack entries \NC \NR
+\NC \type{max_nest_stack} \NC max used nesting stack entries \NC \NR
+\NC \type{max_param_stack} \NC max used parameter stack entries \NC \NR
+\NC \type{max_save_stack} \NC max used save stack entries \NC \NR
+\NC \type{max_strings} \NC maximum allowed strings \NC \NR
+\NC \type{nest_size} \NC nesting stack size \NC \NR
+\NC \type{node_mem_usage} \NC a string giving insight into currently used nodes \NC \NR
+\NC \type{obj_ptr} \NC max \PDF\ object pointer \NC \NR
+\NC \type{obj_tab_size} \NC \PDF\ object table size \NC \NR
+\NC \type{output_active} \NC \type {true} if the \prm {output} routine is active \NC \NR
+\NC \type{output_file_name} \NC name of the \PDF\ or \DVI\ file \NC \NR
+\NC \type{param_size} \NC parameter stack size \NC \NR
+\NC \type{pdf_dest_names_ptr} \NC max \PDF\ destination pointer \NC \NR
+\NC \type{pdf_gone} \NC written \PDF\ bytes \NC \NR
+\NC \type{pdf_mem_ptr} \NC max \PDF\ memory used \NC \NR
+\NC \type{pdf_mem_size} \NC \PDF\ memory size \NC \NR
+\NC \type{pdf_os_cntr} \NC max \PDF\ object stream pointer \NC \NR
+\NC \type{pdf_os_objidx} \NC \PDF\ object stream index \NC \NR
+\NC \type{pdf_ptr} \NC not yet written \PDF\ bytes \NC \NR
+\NC \type{pool_ptr} \NC string pool index \NC \NR
+\NC \type{pool_size} \NC current size allocated for string characters \NC \NR
+\NC \type{save_size} \NC save stack size \NC \NR
+\NC \type{shell_escape} \NC \type {0} means disabled, \type {1} means anything is permitted, and \type {2} is restricted \NC \NR
+\NC \type{safer_option} \NC \type {1} means safer is enforced \NC \NR
+\NC \type{kpse_used} \NC \type {1} means that kpse is used \NC \NR
+\NC \type{stack_size} \NC input stack size \NC \NR
+\NC \type{str_ptr} \NC number of strings \NC \NR
+\NC \type{total_pages} \NC number of written pages \NC \NR
+\NC \type{var_mem_max} \NC number of allocated words for nodes \NC \NR
+\NC \type{var_used} \NC variable (one|-|word) memory in use \NC \NR
+\NC \type{lc_collate} \NC the value of \type {LC_COLLATE} at startup time (becomes \type {C} at startup) \NC \NR
+\NC \type{lc_ctype} \NC the value of \type {LC_CTYPE} at startup time (becomes \type {C} at startup) \NC \NR
+%NC \type{lc_monetary} \NC the value of \type {LC_MONETARY} at startup time \NC \NR
+\NC \type{lc_numeric} \NC the value of \type {LC_NUMERIC} at startup time \NC \NR
+%NC \type{lc_time} \NC the value of \type {LC_TIME} at startup time (becomes \type {C} at startup) \NC \NR
+\LL
+\stoptabulate
+
+The error and warning messages can be wiped with the \type {resetmessages}
+function. A return value can be set with \type {setexitcode}.
+
+\stopsection
+
+\startsection[title={The \type {tex} library}][library=tex]
+
+\startsubsection[title={Introduction}]
+
+\topicindex{libraries+\type{tex}}
+
+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 you can use
+after \prm {the}, is a single tokens or is sort of special in \TEX. 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 (like \prm {tracingcommands} and \prm {parindent}).
+
+\stopsubsection
+
+\startsubsection[title={Internal parameter values, \type {set} and \type {get}}]
+
+\topicindex{parameters+internal}
+
+\libindex{set} \libindex{get}
+
+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}.
+
+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 {\em
+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
+
+Glue is kind of special because there are five values involved. The return value
+is a \nod {glue_spec} node but when you pass \type {false} as last argument to
+\type {tex.get} you get the width of the glue and when you pass \type {true} you
+get all five values. Otherwise you get a node which is a copy of the internal
+value so you are responsible for its freeing at the \LUA\ end. When you set a
+glue quantity you can either pass a \nod {glue_spec} or upto five numbers. If
+you pass \type {true} to \type {get} you get 5 values returned for a glue and
+when you pass \type {false} you only get the width returned.
+
+\subsubsection{Integer parameters}
+
+The integer parameters accept and return \LUA\ numbers. These are 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
+
+These are 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. These are 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
+
+These are 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 at the top of the nesting
+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 \nod {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 \prm {the} \prm {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
+\stoptyping
+\stopthreecolumns
+
+\stopsubsection
+
+\startsubsection[title={Convert commands}]
+
+\topicindex{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.fontname(number)
+tex.uniformdeviate(number)
+tex.number(number)
+tex.romannumeral(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).
+
+\stopsubsection
+
+\startsubsection[title={Last item commands}]
+
+\topicindex{last items}
+
+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.lastxpos
+tex.lastypos
+tex.randomseed
+tex.luatexversion
+tex.eTeXminorversion
+tex.eTeXversion
+tex.currentgrouplevel
+tex.currentgrouptype
+tex.currentiflevel
+tex.currentiftype
+tex.currentifbranch
+\stoptyping
+\stopthreecolumns
+
+\stopsubsection
+
+\startsubsection[title={Accessing registers: \type {set*}, \type {get*} and \type {is*}}]
+
+\topicindex{attributes}
+\topicindex{registers}
+
+\libindex{attribute} \libindex{setattribute} \libindex{getattribute} \libindex{isattribute}
+\libindex{count} \libindex{setcount} \libindex{getcount} \libindex{iscount}
+\libindex{dimen} \libindex{setdimen} \libindex{getdimen} \libindex{isdimen}
+\libindex{skip} \libindex{setskip} \libindex{getskip} \libindex{isskip}
+\libindex{muskip} \libindex{setmuskip} \libindex{getmuskip} \libindex{ismuskip}
+\libindex{glue} \libindex{setglue} \libindex{getglue} \libindex{isglue}
+\libindex{muglue} \libindex{setmuglue} \libindex{getmuglue} \libindex{ismuglue}
+\libindex{toks} \libindex{settoks} \libindex{gettoks} \libindex{istoks}
+\libindex{box} \libindex{setbox} \libindex{getbox} \libindex{isbox}
+
+\libindex{scantoks}
+
+\TEX's attributes (\lpr {attribute}), counters (\prm {count}), dimensions (\prm
+{dimen}), skips (\prm {skip}, \prm {muskip}) and token (\prm {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.glue
+tex.muskip
+tex.muglue
+tex.toks
+\stoptyping
+\stopthreecolumns
+
+It is possible to use the names of relevant \lpr {attributedef}, \prm {countdef},
+\prm {dimendef}, \prm {skipdef}, or \prm {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 \prm {countdef} (or \lpr {attributedef}, or \prm {dimendef}, or \prm
+{skipdef}, or \prm {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).
+
+\startitemize
+
+ \startitem
+ The count registers accept and return \LUA\ numbers.
+ \stopitem
+
+ \startitem
+ 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.
+ \stopitem
+
+ \startitem
+ The token registers accept and return \LUA\ strings. \LUA\ strings are
+ converted to and from token lists using \prm {the} \prm {toks} style
+ expansion: all category codes are either space (10) or other (12).
+ \stopitem
+
+ \startitem
+ The skip registers accept and return \nod {glue_spec} userdata node
+ objects (see the description of the node interface elsewhere in this
+ manual).
+ \stopitem
+
+ \startitem
+ The glue registers are just skip registers but instead of userdata
+ are verbose.
+ \stopitem
+
+ \startitem
+ Like the counts, the attribute registers accept and return \LUA\ numbers.
+ \stopitem
+
+\stopitemize
+
+As an alternative to array addressing, there are also accessor functions defined
+for all cases, for example, here is the set of possibilities for \prm {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.
+
+Again the glue variants are not using the \nod {glue-spec} userdata nodes. The
+\type {setglue} function accepts upto 5 arguments: width, stretch, shrink,
+stretch order and shrink order and the \type {getglue} function reports them,
+unless the second argument is \type {false} in which care only the width is
+returned.
+
+Here is an example usign a threesome:
+
+\startfunctioncall
+local d = tex.getdimen("foo")
+if tex.isdimen("bar") then
+ tex.setdimen("bar",d)
+end
+\stopfunctioncall
+
+There are six extra skip (glue) 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}.
+
+There are such helpers for \type {dimen}, \type {count}, \type {skip}, \type
+{muskip}, \type {box} and \type {attribute} registers but the glue ones
+are special because they have to deal with more properties.
+
+As with the general \type {get} and \type {set} function discussed before, for
+the skip registers \type {getskip} returns a node and \type {getglue} returns
+numbers, while \type {setskip} accepts a node and \type {setglue} expects upto 5
+numbers. Again, when you pass \type {false} as second argument to \type {getglue}
+you only get the width returned. The same is true for the \type {mu} variants
+\type {getmuskip}, \type {setmuskip}, \type {getmuskip} and\type {setmuskip}.
+
+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.
+
+\stopsubsection
+
+\startsubsection[title={Character code registers: \type {[get|set]*code[s]}}]
+
+\topicindex{characters+codes}
+
+\libindex{lccode} \libindex{setlccode} \libindex{getlccode}
+\libindex{uccode} \libindex{setuccode} \libindex{getuccode}
+\libindex{sfcode} \libindex{setsfcode} \libindex{getsfcode}
+\libindex{catcode} \libindex{setcatcode} \libindex{getcatcode}
+\libindex{mathcode} \libindex{setmathcode} \libindex{getmathcode}
+\libindex{delcode} \libindex{setdelcode} \libindex{getdelcode}
+
+\libindex{setdelcodes} \libindex{getdelcodes}
+\libindex{setmathcodes} \libindex{getmathcodes}
+
+\TEX's character code tables (\prm {lccode}, \prm {uccode}, \prm {sfcode}, \prm
+{catcode}, \prm {mathcode}, \prm {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> class,
+ <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
+tex.setmathcode (["global"], <number> n, <number> class,
+ <number> family, <number> character)
+class, family, char =
+ tex.getmathcodes (<number> n)
+tex.setdelcode (["global"], <number> n, <number> smallfam,
+ <number> smallchar, <number> largefam, <number> largechar)
+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 \lpr {Udelcode} usage, but the returned table can have values there
+(if the delimiter code was set using \prm {delcode}, for example). Unset \type
+{delcode}'s can be recognized because \type {dval[1]} is $-1$.
+
+\stopsubsection
+
+\startsubsection[title={Box registers: \type {[get|set]box}}]
+
+\topicindex{registers}
+\topicindex{boxes}
+
+\libindex{box}
+\libindex{setbox} \libindex{getbox}
+
+It is possible to set and query actual boxes, coming for instance from \prm
+{hbox}, \prm {vbox} or \prm {vtop}, 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
+
+\stopsubsection
+
+\startsubsection[title={Reusing boxes: \type {[use|save]boxresource} and \type {getboxresourcedimensions}}]
+
+\topicindex{boxes+reuse}
+
+\libindex{useboxresource}
+\libindex{saveboxresource}
+\libindex{getboxresourcedimensions}
+
+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 \lpr {useboxresource} or
+by creating a rule node with subtype~2.
+
+\starttyping
+local index = tex.saveboxresource(n,attributes,resources,immediate,type,margin)
+\stoptyping
+
+The optional second and third arguments are strings, the fourth is a boolean. The
+fifth argument is a type. When set to non|-|zero the \type {/Type} entry is
+omitted. A value of 1 or 3 still writes a \type {/BBox}, while 2 or 3 will write
+a \type {/Matrix}. The sixth argument is the (virtual) margin that extends beyond
+the effective boundingbox as seen by \TEX. Instead of a box number one can also
+pass a \type {[h|v]list} node.
+
+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, m = tex.getboxresourcedimensions(n)
+\stoptyping
+
+This returns the width, height, depth and margin of the resource.
+
+\stopsubsection
+
+\startsubsection[title={\type {triggerbuildpage}}]
+
+\topicindex{pages}
+
+\libindex{triggerbuildpage}
+
+You should not expect to much from the \type {triggerbuildpage} helpers because
+often \TEX\ doesn't do much if it thinks nothing has to be done, but it might be
+useful for some applications. It just does as it says it calls the internal
+function that build a page, given that there is something to build.
+
+\stopsubsection
+
+\startsubsection[title={\type {splitbox}}]
+
+\topicindex{boxes+split}
+
+\libindex{splitbox}
+
+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 \prm {vsplit} operation. The mode can be \type
+{additional} or \type {exactly} and concerns the split off box.
+
+\stopsubsection
+
+\startsubsection[title={Accessing math parameters: \type {[get|set]math}}]
+
+\topicindex{math+parameters}
+\topicindex{parameters+math}
+
+\libindex{setmath}
+\libindex{getmath}
+
+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 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.
+
+\stopsubsection
+
+\startsubsection[title={Special list heads: \type {[get|set]list}}]
+
+\topicindex{lists}
+
+\libindex{lists}
+\libindex{setlist}
+\libindex{getlist}
+
+The virtual table \type {tex.lists} contains the set of internal registers that
+keep track of building page lists.
+
+\starttabulate[|l|p|]
+\DB field \BC explanation \NC \NR
+\TB
+\NC \type{page_ins_head} \NC circular list of pending insertions \NC \NR
+\NC \type{contrib_head} \NC the recent contributions \NC \NR
+\NC \type{page_head} \NC the current page content \NC \NR
+%NC \type{temp_head} \NC \NC \NR
+\NC \type{hold_head} \NC used for held-over items for next page \NC \NR
+\NC \type{adjust_head} \NC head of the current \prm {vadjust} list \NC \NR
+\NC \type{pre_adjust_head} \NC head of the current \type {\vadjust pre} list \NC \NR
+%NC \type{align_head} \NC \NC \NR
+\NC \type{page_discards_head} \NC head of the discarded items of a page break \NC \NR
+\NC \type{split_discards_head} \NC head of the discarded items in a vsplit \NC \NR
+\LL
+\stoptabulate
+
+The getter and setter functions are \type {getlist} and \type {setlist}. You have
+to be careful with what you set as \TEX\ can have expectations with regards to
+how a list is constructed or in what state it is.
+
+\stopsubsection
+
+\startsubsection[title={Semantic nest levels: \type {getnest} and \type {ptr}}]
+
+\topicindex{nesting}
+
+\libindex{nest}
+\libindex{ptr}
+%libindex{setnest} % only a message
+\libindex{getnest}
+
+The virtual table \type {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 {ptr}, which gives the highest
+available index. Neither the array items in \type {nest[]} nor \type {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 {nest[0]} the
+outermost (main vertical list) level. The getter function is \type {getnest}. You
+can pass a number (which gives you a list), nothing or \type {top}, which returns
+the topmost list, or the string \type {ptr} which gives you the index of the
+topmost list.
+
+The known fields are:
+
+\starttabulate[|l|l|l|p|]
+\DB key \BC type \BC modes \BC explanation \NC \NR
+\TB
+\NC \type{mode} \NC number \NC all \NC a string:
+ \type {none} (this happens during \prm {write}),
+ \type {vmode}, \type {hmode}, \type {displaymath},
+ \type {innervmode}, \type {innerhmode}, \type {inlinemath};
+ these fields cannot be set \NC \NR
+\NC \type{modeline} \NC number \NC all \NC source input line where this mode was entered in,
+ negative inside the output routine \NC \NR
+\NC \type{head} \NC node \NC all \NC the head of the current list \NC \NR
+\NC \type{tail} \NC node \NC all \NC the tail of the current list \NC \NR
+\NC \type{prevgraf} \NC number \NC vmode \NC number of lines in the previous paragraph \NC \NR
+\NC \type{prevdepth} \NC number \NC vmode \NC depth of the previous paragraph \NC \NR
+\NC \type{spacefactor} \NC number \NC hmode \NC the current space factor \NC \NR
+\NC \type{dirs} \NC node \NC hmode \NC used for temporary storage by the line break algorithm\NC \NR
+\NC \type{noad} \NC node \NC mmode \NC used for temporary storage of a pending fraction numerator,
+ for \prm {over} etc. \NC \NR
+\NC \type{delimptr} \NC node \NC mmode \NC used for temporary storage of the previous math delimiter,
+ for \prm {middle} \NC \NR
+\NC \type{mathdir} \NC boolean \NC mmode \NC true when during math processing the \lpr {mathdir} is not
+ the same as the surrounding \lpr {textdir} \NC \NR
+\NC \type{mathstyle} \NC number \NC mmode \NC the current \lpr {mathstyle} \NC \NR
+\LL
+\stoptabulate
+
+\stopsubsection
+
+\startsubsection[reference=sec:luaprint,title={Print functions}]
+
+\topicindex{printing}
+
+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 \prm {directlua}.
+
+The total amount of returnable text from a \prm {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 {print}}
+
+\libindex{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 \lpr {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 \prm {the} \prm {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 \prm
+{directlua} will not have the \prm {endlinechar} appended, all others do.
+
+\subsubsection{\type {sprint}}
+
+\libindex{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 \prm {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 \prm {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}. This
+influences the string arguments (or numbers turned into strings).
+
+Although this needs to be used with care, you can also pass token or node
+userdata objects. These get injected into the stream. Tokens had best be valid
+tokens, while nodes need to be around when they get injected. Therefore it is
+important to realize the following:
+
+\startitemize
+\startitem
+ When you inject a token, you need to pass a valid token userdata object. This
+ object will be collected by \LUA\ when it no longer is referenced. When it gets
+ printed to \TEX\ the token itself gets copied so there is no interference with the
+ \LUA\ garbage collection. You manage the object yourself. Because tokens are
+ actually just numbers, there is no real extra overhead at the \TEX\ end.
+\stopitem
+\startitem
+ When you inject a node, you need to pass a valid node userdata object. The
+ node related to the object will not be collected by \LUA\ when it no longer
+ is referenced. It lives on at the \TEX\ end in its own memory space. When it
+ gets printed to \TEX\ the node reference is used assuming that node stays
+ around. There is no \LUA\ garbage collection involved. Again, you manage the
+ object yourself. The node itself is freed when \TEX\ is done with it.
+\stopitem
+\stopitemize
+
+If you consider the last remark you might realize that we have a problem when a
+printed mix of strings, tokens and nodes is reused. Inside \TEX\ the sequence
+becomes a linked list of input buffers. So, \type {"123"} or \type {"\foo{123}"}
+gets read and parsed on the fly, while \typ {<token userdata>} already is
+tokenized and effectively is a token list now. A \typ {<node userdata>} is also
+tokenized into a token list but it has a reference to a real node. Normally this
+goes fine. But now assume that you store the whole lot in a macro: in that case
+the tokenized node can be flushed many times. But, after the first such flush the
+node is used and its memory freed. You can prevent this by using copies which is
+controlled by setting \lpr {luacopyinputnodes} to a non|-|zero value. This is one
+of these fuzzy areas you have to live with if you really mess with these low
+level issues.
+
+\subsubsection{\type {tprint}}
+
+\libindex{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 {cprint}}
+
+\libindex{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 {write}, \type {twrite}, \type {nwrite}}
+
+\libindex{write}
+\libindex{twrite}
+\libindex{nwrite}
+
+\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 \prm {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).
+
+The functions \type {twrite} and \type {nwrite} can be used to write a token or
+node back to \TEX\, possibly intermixed with regular strings that will be
+tokenized. You have to make sure that you pass the right data because sometimes
+\TEX\ has expectations that need to be met.
+
+\stopsubsection
+
+\startsubsection[title={Helper functions}]
+
+\subsubsection{\type {round}}
+
+\topicindex {helpers}
+
+\libindex{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 too big} error as well.
+
+\subsubsection{\type {scale}}
+
+\libindex{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 \nod {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 too 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 {number} and \type {romannumeral}}
+
+\libindex{number}
+\libindex{romannumeral}
+
+These are the companions to the primitives \prm {number} and \prm
+{romannumeral}. They can be used like:
+
+\startfunctioncall
+tex.print(tex.romannumeral(123))
+\stopfunctioncall
+
+\subsubsection{\type {fontidentifier} and \type {fontname}}
+
+\libindex{fontidentifier}
+\libindex{fontname}
+
+The first one returns the name only, the second one reports the size too.
+
+\startfunctioncall
+tex.print(tex.fontname(tex.fontname))
+tex.print(tex.fontname(tex.fontidentidier))
+\stopfunctioncall
+
+\subsubsection{\type {sp}}
+
+\libindex{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.getlinenumber} and \type {tex.setlinenumber}}
+
+\libindex{getlinenumber}
+\libindex{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 {error} and \type {show_context}}
+
+\topicindex{errors}
+
+\libindex{error}
+\libindex{show_context}
+
+\startfunctioncall
+tex.error(<string> s)
+tex.error(<string> s, <table> help)
+\stopfunctioncall
+
+This creates an error somewhat like the combination of \prm {errhelp} and \prm
+{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.
+
+In case of an error the \type {show_context} function will show the current
+context where we're at (in the expansion).
+
+\subsubsection{\type {run}, \type {runtoks}, \type {finish}}
+
+\libindex{run}
+\libindex{runtoks}
+\libindex{finish}
+
+These two functions start the interpretations and force its end. A runs normally
+boils down to \TEX\ entering the so called main loop. A token is fetched and
+depending on it current meaning some actions takes place. Sometimes that actions
+comes immediately, sometimes more scanning is needed. Quite often tokens get
+pushed back into the input. This all means that the \TEX\ scanner is constantly
+pushing and popping input states, but in the end after all the action is done
+returns to the main loop.
+
+Because of the fact that \TEX\ is in a complex dance of expanding, dealing with
+fonts, typesetting paragraphs, messing around with boxes, building pages, and so
+on, you cannot easily run a nested \TEX\ run (read nested main loop). However,
+there is an option to force a local run with \type {runtoks}. The content of the
+given token list register gets expanded locally after which we return to where we
+triggered this expansion, at the \LUA\ end. Instead a function can get passed
+that does some work. You have to make sure that at the end \TEX\ is in a sane
+state and this is not always trivial. A more complex mechanism would complicate
+\TEX\ itself (and probably also harm performance) so this simple local expansion
+loop has to do.
+
+\startfunctioncall
+tex.runtoks(<token register>)
+tex.runtoks(<lua function>)
+\stopfunctioncall
+
+When the \prm {tracingnesting} parameter is set to a value larger than~2 some
+information is reported about the state of the local loop.
+
+\subsubsection{\type {run}, \type {runtoks}, \type {finish}}
+
+\libindex{forcehmode}
+
+An example of a (possible error triggering) complication is that \TEX\ expects to
+be in some state, say horizontal mode, and you have to make sure it is when you
+start feeding back something from \LUA\ into \TEX. Normally a user will not run
+into issues but when you start writing tokens or nodes or have a nested run there
+can be situations that you need to run \type {forcehmode}. There is no recipe for
+this and intercepting possible cases would weaken \LUATEX's flexibility.
+
+\subsubsection{\type {hashtokens}}
+
+\libindex{hashtokens}
+
+\topicindex{hash}
+
+\startfunctioncall
+for i,v in pairs (tex.hashtokens()) do ... end
+\stopfunctioncall
+
+Returns a list of names. 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. You can use \type
+{token.create} to inspect properties, for instance when the \type {command} key
+in a created table equals \type {123}, you have the \type {cmdname} value \type
+{undefined_cs}.
+
+\subsubsection{\type {definefont}}
+
+\topicindex{fonts+defining}
+
+\libindex{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).
+
+\stopsubsection
+
+\startsubsection[reference=luaprimitives,title={Functions for dealing with primitives}]
+
+\subsubsection{\type {enableprimitives}}
+
+\libindex{enableprimitives}
+
+\topicindex{initialization}
+\topicindex{primitives}
+
+\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 \prm {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 \prm {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 \lpr {formatname}, provided that the control sequences \type
+{\LuaTeXformatname} is currently undefined.
+
+When \LUATEX\ is run with \type {--ini} only the \TEX82 primitives and \prm
+{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 {extraprimitives}}
+
+\libindex{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 given in the following table. In addition the somewhat special
+primitives \quote{\tex{ }}, \quote{\tex {/}} and \quote{\type {-}} are defined.
+
+\startluacode
+function document.showprimitives(tag)
+ for k, v in table.sortedpairs(tex.extraprimitives(tag)) do
+ if v ~= ' ' and v ~= "/" and v ~= "-" then
+ context.type(v)
+ context.space()
+ end
+ end
+end
+\stopluacode
+
+\starttabulate[|l|pl|]
+\DB name \BC values \NC \NR
+\TB
+\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
+\LL
+\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'}.
+
+Running \type {tex.extraprimitives} will give you the complete list of
+primitives \type {-ini} startup. It is exactly equivalent to \type
+{tex.extraprimitives("etex","luatex")}.
+
+\subsubsection{\type {primitives}}
+
+\libindex{primitives}
+
+\startfunctioncall
+<table> t = tex.primitives()
+\stopfunctioncall
+
+This function returns a list of all primitives that \LUATEX\ knows about.
+
+\stopsubsection
+
+\startsubsection[title={Core functionality interfaces}]
+
+\subsubsection{\type {badness}}
+
+\libindex{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 \mathematics {100(t/s)^3};
+
+\subsubsection{\type {tex.resetparagraph}}
+
+\topicindex {paragraphs+reset}
+
+\libindex{resetparagraph}
+
+This function resets the parameters that \TEX\ normally resets when a new paragraph
+is seen.
+
+\subsubsection{\type {linebreak}}
+
+\topicindex {linebreaks}
+
+\libindex{linebreak}
+
+\startfunctioncall
+local <node> nodelist, <table> info =
+ tex.linebreak(<node> listhead, <table> parameters)
+\stopfunctioncall
+
+The understood parameters are as follows:
+
+\starttabulate[|l|l|p|]
+\DB name \BC type \BC explanation \NC \NR
+\TB
+\NC \type{pardir} \NC string \NC \NC \NR
+\NC \type{pretolerance} \NC number \NC \NC \NR
+\NC \type{tracingparagraphs} \NC number \NC \NC \NR
+\NC \type{tolerance} \NC number \NC \NC \NR
+\NC \type{looseness} \NC number \NC \NC \NR
+\NC \type{hyphenpenalty} \NC number \NC \NC \NR
+\NC \type{exhyphenpenalty} \NC number \NC \NC \NR
+\NC \type{pdfadjustspacing} \NC number \NC \NC \NR
+\NC \type{adjdemerits} \NC number \NC \NC \NR
+\NC \type{pdfprotrudechars} \NC number \NC \NC \NR
+\NC \type{linepenalty} \NC number \NC \NC \NR
+\NC \type{lastlinefit} \NC number \NC \NC \NR
+\NC \type{doublehyphendemerits} \NC number \NC \NC \NR
+\NC \type{finalhyphendemerits} \NC number \NC \NC \NR
+\NC \type{hangafter} \NC number \NC \NC \NR
+\NC \type{interlinepenalty} \NC number or table \NC if a table, then it is an array like \prm {interlinepenalties} \NC \NR
+\NC \type{clubpenalty} \NC number or table \NC if a table, then it is an array like \prm {clubpenalties} \NC \NR
+\NC \type{widowpenalty} \NC number or table \NC if a table, then it is an array like \prm {widowpenalties} \NC \NR
+\NC \type{brokenpenalty} \NC number \NC \NC \NR
+\NC \type{emergencystretch} \NC number \NC in scaled points \NC \NR
+\NC \type{hangindent} \NC number \NC in scaled points \NC \NR
+\NC \type{hsize} \NC number \NC in scaled points \NC \NR
+\NC \type{leftskip} \NC glue_spec node \NC \NC \NR
+\NC \type{rightskip} \NC glue_spec node \NC \NC \NR
+\NC \type{parshape} \NC table \NC \NC \NR
+\LL
+\stoptabulate
+
+Note that there is no interface for \prm {displaywidowpenalties}, you have to
+pass the right choice for \type {widowpenalties} yourself.
+
+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 \cbk {pre_linebreak_filter} or \cbk {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 \nod {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 \prm {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 \prm {vbox}. The returned \type {info} table contains four values that are
+all numbers:
+
+\starttabulate[|l|p|]
+\DB name \BC explanation \NC \NR
+\TB
+\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
+\LL
+\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 {shipout}}
+
+\topicindex {shipout}
+
+\libindex{shipout}
+
+\startfunctioncall
+tex.shipout(<number> n)
+\stopfunctioncall
+
+Ships out box number \type {n} to the output file, and clears the box register.
+
+\subsubsection{\type {getpagestate}}
+
+\topicindex {pages}
+
+\libindex{getpagestate}
+
+This helper reports the current page state: \type {empty}, \type {box_there} or
+\type {inserts_only} as integer value.
+
+\subsubsection{\type {getlocallevel}}
+
+\topicindex {nesting}
+
+\libindex{getlocallevel}
+
+This integer reports the current level of the local loop. It's only useful for
+debugging and the (relative state) numbers can change with the implementation.
+
+\stopsubsection
+
+\startsubsection[title={Randomizers}]
+
+\libindex{lua_math_random}
+\libindex{lua_math_randomseed}
+\libindex{init_rand}
+\libindex{normal_rand}
+\libindex{uniform_rand}
+\libindex{uniformdeviate}
+
+For practical reasons \LUATEX\ has its own random number generator. The original
+\LUA\ random function is available as \typ {tex.lua_math_random}. You can
+initialize with a new seed with \type {init_rand} (\typ {lua_math_randomseed} is
+equivalent to this one.
+
+There are three generators: \type {normal_rand} (no argument is used), \type
+{uniform_rand} (takes a number that will get rounded before being used) and \type
+{uniformdeviate} which behaves like the primitive and expects a scaled integer, so
+
+\startfunctioncall
+tex.print(tex.uniformdeviate(65536)/65536)
+\stopfunctioncall
+
+will give a random number between zero and one.
+
+\stopsubsection
+
+\startsubsection[reference=synctex,title={Functions related to synctex}]
+
+\topicindex {synctex}
+
+\libindex{set_synctex_mode} \libindex{get_synctex_mode}
+\libindex{set_synctex_no_files}
+\libindex{set_synctex_tag} \libindex{get_synctex_tag} \libindex{force_synctex_tag}
+\libindex{set_synctex_line} \libindex{get_synctex_line} \libindex{force_synctex_line}
+
+The next helpers only make sense when you implement your own synctex logic. Keep in
+mind that the library used in editors assumes a certain logic and is geared for
+plain and \LATEX, so after a decade users expect a certain behaviour.
+
+\starttabulate[|l|p|]
+\DB name \BC explanation \NC \NR
+\TB
+\NC \type{set_synctex_mode} \NC \type {0} is the default and used normal synctex
+ logic, \type {1} uses the values set by the next
+ helpers while \type {2} also sets these for glyph
+ nodes; \type{3} sets glyphs and glue and \type {4}
+ sets only glyphs \NC \NR
+\NC \type{set_synctex_tag} \NC set the current tag (file) value (obeys save stack) \NC \NR
+\NC \type{set_synctex_line} \NC set the current line value (obeys save stack) \NC \NR
+\NC \type{set_synctex_no_files} \NC disable synctex file logging \NC \NR
+\NC \type{get_synctex_mode} \NC returns the current mode (for values see above) \NC \NR
+\NC \type{get_synctex_tag} \NC get the currently set value of tag (file) \NC \NR
+\NC \type{get_synctex_line} \NC get the currently set value of line \NC \NR
+\NC \type{force_synctex_tag} \NC overload the tag (file) value (\type {0} resets) \NC \NR
+\NC \type{force_synctex_line} \NC overload the line value (\type {0} resets) \NC \NR
+\LL
+\stoptabulate
+
+The last one is somewhat special. Due to the way files are registered in \SYNCTEX\ we need
+to explicitly disable that feature if we provide our own alternative if we want to avoid
+that overhead. Passing a value of 1 disables registering.
+
+\stopsubsection
+
+\stopsection
+
+\startsection[title={The \type {texconfig} table},reference=texconfig][library=texconfig]
+
+\topicindex{libraries+\type{texconfig}}
+
+\topicindex {configuration}
+
+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[|l|l|l|p|]
+\DB key \BC type \BC default \BC explanation \NC \NR
+\TB
+\NC \type{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
+ \type{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 \type{string_vacancies} \NC number \NC 75000 \NC cf.\ web2c docs \NC \NR
+\NC \type{pool_free} \NC number \NC 5000 \NC cf.\ web2c docs \NC \NR
+\NC \type{max_strings} \NC number \NC 15000 \NC cf.\ web2c docs \NC \NR
+\NC \type{strings_free} \NC number \NC 100 \NC cf.\ web2c docs \NC \NR
+\NC \type{nest_size} \NC number \NC 50 \NC cf.\ web2c docs \NC \NR
+\NC \type{max_in_open} \NC number \NC 15 \NC cf.\ web2c docs \NC \NR
+\NC \type{param_size} \NC number \NC 60 \NC cf.\ web2c docs \NC \NR
+\NC \type{save_size} \NC number \NC 4000 \NC cf.\ web2c docs \NC \NR
+\NC \type{stack_size} \NC number \NC 300 \NC cf.\ web2c docs \NC \NR
+\NC \type{dvi_buf_size} \NC number \NC 16384 \NC cf.\ web2c docs \NC \NR
+\NC \type{error_line} \NC number \NC 79 \NC cf.\ web2c docs \NC \NR
+\NC \type{half_error_line} \NC number \NC 50 \NC cf.\ web2c docs \NC \NR
+\NC \type{max_print_line} \NC number \NC 79 \NC cf.\ web2c docs \NC \NR
+\NC \type{hash_extra} \NC number \NC 0 \NC cf.\ web2c docs \NC \NR
+\NC \type{pk_dpi} \NC number \NC 72 \NC cf.\ web2c docs \NC \NR
+\NC \type{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 \type{file_line_error} \NC boolean \NC false
+\NC
+ do \type {file:line} style error messages
+\NC \NR
+\NC \type{halt_on_error} \NC boolean \NC false
+\NC
+ abort run on the first encountered error
+\NC \NR
+\NC \type{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 \type{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
+\LL
+\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.
+
+\stopsection
+
+\startsection[title={The \type {texio} library}][library=texio]
+
+\topicindex{libraries+\type{texio}}
+\topicindex{\IO}
+
+This library takes care of the low|-|level I/O interface: writing to the log file
+and|/|or console.
+
+\startsubsection[title={\type {write}}]
+
+\libindex{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 \prm {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.
+
+\stopsubsection
+
+\startsubsection[title={\type {write_nl}}]
+
+\libindex{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.
+
+\stopsubsection
+
+\startsubsection[title={\type {setescape}}]
+
+\libindex{setescape}
+
+You can disable \type {^^} escaping of control characters by passing a value of
+zero.
+
+\stopsubsection
+
+\startsubsection[title={\type {closeinput}}]
+
+\libindex{closeinput}
+
+This function that should be used with care. It acts as \prm {endinput} but at
+the \LUA\ end. You can use it to (sort of) force a jump back to \TEX. Normally a
+\LUA\ will just collect prints and at the end bump an input level and flush these
+prints. This function can help you stay at the current level but you need to know
+what you're doing (or more precise: what \TEX\ is doing with input).
+
+\stopsubsection
+
+\stopsection
+
+\startsection[title={The \type {token} library}][library=token]
+
+\startsubsection[title={The scanner}]
+
+\topicindex{libraries+\type{token}}
+\topicindex{tokens}
+
+\libindex{scan_keyword}
+\libindex{scan_keywordcs}
+\libindex{scan_int}
+\libindex{scan_real}
+\libindex{scan_float}
+\libindex{scan_dimen}
+\libindex{scan_glue}
+\libindex{scan_toks}
+\libindex{scan_code}
+\libindex{scan_string}
+\libindex{scan_argument}
+\libindex{scan_word}
+\libindex{scan_csname}
+\libindex{scan_list}
+
+The token library provides means to intercept the input and deal with it at the
+\LUA\ level. The 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 scanner functions are probably the
+most intriguing.
+
+\starttabulate[|l|l|p|]
+\DB function \BC argument \BC result \NC \NR
+\TB
+\NC \type{scan_keyword} \NC string \NC returns true if the given keyword is gobbled; as with
+ the regular \TEX\ keyword scanner this is case insensitive
+ (and \ASCII\ based) \NC \NR
+\NC \type{scan_keywordcs} \NC string \NC returns true if the given keyword is gobbled; this variant
+ is case sensitive and also suitable for \UTF8 \NC \NR
+\NC \type{scan_int} \NC \NC returns an integer \NC \NR
+\NC \type{scan_real} \NC \NC returns a number from e.g.\ \type {1}, \type {1.1}, \type {.1} with optional collapsed signs \NC \NR
+\NC \type{scan_float} \NC \NC returns a number from e.g.\ \type {1}, \type {1.1}, \type {.1}, \type {1.1E10}, , \type {.1e-10} with optional collapsed signs \NC \NR
+\NC \type{scan_dimen} \NC infinity, mu-units \NC returns a number representing a dimension and or two numbers being the filler and order \NC \NR
+\NC \type{scan_glue} \NC mu-units \NC returns a glue spec node \NC \NR
+\NC \type{scan_toks} \NC definer, expand \NC returns a table of tokens tokens \NC \NR
+\NC \type{scan_code} \NC bitset \NC returns a character if its category is in the given bitset (representing catcodes) \NC \NR
+\NC \type{scan_string} \NC \NC returns a string given between \type {{}}, as \type {\macro} or as sequence of characters with catcode 11 or 12 \NC \NR
+\NC \type{scan_argument} \NC \NC this one is simular to \type {scanstring} but also accepts a \type {\cs}
+ (which then get expanded) \NC \NR
+\NC \type{scan_word} \NC \NC returns a sequence of characters with catcode 11 or 12 as string \NC \NR
+\NC \type{scan_csname} \NC \NC returns \type {foo} after scanning \type {\foo} \NC \NR
+\NC \type{scan_list} \NC \NC picks up a box specification and returns a \type {[h|v]list} node \NC \NR
+\LL
+\stoptabulate
+
+The scanners can be considered stable apart from the one scanning for a token.
+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|]
+\DB name \BC result \NC \NR
+\TB
+\NC \type {\directlua{token.scan_string()}{foo}} \NC \directlua{context("{\\red\\type {"..token.scan_string().."}}")} {foo} \NC full expansion \NC \NR
+\NC \type {\directlua{token.scan_string()}foo} \NC \directlua{context("{\\red\\type {"..token.scan_string().."}}")} foo \NC letters and others \NC \NR
+\NC \type {\directlua{token.scan_string()}\foo} \NC \directlua{context("{\\red\\type {"..token.scan_string().."}}")}\foo \NC meaning \NC \NR
+\LL
+\stoptabulate
+
+The \type {\foo} case only gives the meaning, but one can pass an already
+expanded definition (\prm {edef}'d). In the case of the braced variant one can of
+course use the \prm {detokenize} and \prm {unexpanded} primitives since 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.
+
+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, then it
+is 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).
+
+\stopsubsection
+
+\startsubsection[title= {Picking up one token}]
+
+\libindex {get_next}
+\libindex {scan_token}
+\libindex {expand}
+
+The scanners look for a sequence. When you want to pick up one token from the
+input you use \type {get_next}. This creates a token with the (low level)
+properties as discussed next. This token is just the next one. If you want to
+enforce expansion first you can use \type {scan_token}. Internally tokens are
+characterized by a number that packs a lot of information. In order to access
+the bits of information a token is wrapped in a userdata object.
+
+The \type {expand} function will trigger expansion of the next token in the
+input. This can be quite unpredictable but when you call it you probably know
+enough about \TEX\ not to be too worried about that. It basically is a call to
+the internal expand related function.
+
+\stopsubsection
+
+\startsubsection[title={Creating tokens}]
+
+\libindex{create}
+\libindex{new}
+
+\libindex{is_defined}
+\libindex{is_token}
+\libindex{biggest_char}
+
+\libindex{commands}
+\libindex{command_id}
+
+\libindex{get_command}
+\libindex{get_cmdname}
+\libindex{get_csname}
+\libindex{get_id}
+\libindex{get_active}
+\libindex{get_expandable}
+\libindex{get_protected}
+\libindex{get_mode}
+\libindex{get_index}
+\libindex{get_tok}
+
+\libindex{get_next}
+
+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 \prm {relax}
+primitive. The possible properties of tokens are:
+
+\starttabulate[|l|p|]
+\DB name \BC explanation \NC \NR
+\TB
+\NC \type {command} \NC a number representing the internal command number \NC \NR
+\NC \type {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 \type {csname} \NC the associated control sequence (if applicable) \NC \NR
+\NC \type {id} \NC the unique id of the token \NC \NR
+\NC \type {tok} \NC the full token number as stored in \TEX \NC \NR
+\NC \type {active} \NC a boolean indicating the active state of the token \NC \NR
+\NC \type {expandable} \NC a boolean indicating if the token (macro) is expandable \NC \NR
+\NC \type {protected} \NC a boolean indicating if the token (macro) is protected \NC \NR
+\NC \type {mode} \NC a number either representing a character or another entity \NC \NR
+\NC \type {index} \NC a number running from 0x0000 upto 0xFFFF indicating a \TEX\ register index \NC \NR
+\LL
+\stoptabulate
+
+Alternatively you can use a getter \type {get_<fieldname>} to access a property
+of a token.
+
+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.
+
+You can ask for a list of commands:
+
+\starttyping
+local t = token.commands()
+\stoptyping
+
+The id of a token class can be queried as follows:
+
+\starttyping
+local id = token.command_id("math_shift")
+\stoptyping
+
+If you really know what you're doing you can create character tokens by not
+passing a string but a number:
+
+\starttyping
+local letter_x = token.create(string.byte("x"))
+local other_x = token.create(string.byte("x"),12)
+\stoptyping
+
+Passing weird numbers can give side effects so don't expect too much help with
+that. As said, you need to know what you're doing. The best way to explore the
+way these internals work is to just look at how primitives or macros or \prm
+{chardef}'d commands are tokenized. Just create a known one and inspect its
+fields. A variant that ignores the current catcode table is:
+
+\starttyping
+local whatever = token.new(123,12)
+\stoptyping
+
+You can test if a control sequence is defined with \type {is_defined}, which
+accepts a string and returns a boolean:
+
+\starttyping
+local okay = token.is_defined("foo")
+\stoptyping
+
+The largest character possible is returned by \type {biggest_char}, just in case you
+need to know that boundary condition.
+
+\stopsubsection
+
+\startsubsection[title={Macros}]
+
+\topicindex {macros}
+
+\libindex{set_macro}
+\libindex{get_macro}
+\libindex{get_meaning}
+\libindex{set_char}
+\libindex{set_lua}
+\libindex{get_functions_table}
+
+The \type {set_macro} function can get upto 4 arguments:
+
+\starttyping
+set_macro("csname","content")
+set_macro("csname","content","global")
+set_macro("csname")
+\stoptyping
+
+You can pass a catcodetable identifier as first argument:
+
+\starttyping
+set_macro(catcodetable,"csname","content")
+set_macro(catcodetable,"csname","content","global")
+set_macro(catcodetable,"csname")
+\stoptyping
+
+The results are like:
+
+\starttyping
+ \def\csname{content}
+\gdef\csname{content}
+ \def\csname{}
+\stoptyping
+
+The \type {get_macro} function can be used to get the content of a macro while
+the \type {get_meaning} function gives the meaning including the argument
+specification (as usual in \TEX\ separated by \type {->}).
+
+The \type {set_char} function can be used to do a \prm {chardef} at the
+\LUA\ end, where invalid assignments are silently ignored:
+
+\starttyping
+set_char("csname",number)
+set_char("csname",number,"global")
+\stoptyping
+
+A special one is the following:
+
+\starttyping
+set_lua("mycode",id)
+set_lua("mycode",id,"global","protected")
+\stoptyping
+
+This creates a token that refers to a \LUA\ function with an entry in the table
+that you can access with \type {lua.get_functions_table}. It is the companion
+to \lpr {luadef}.
+
+\stopsubsection
+
+\startsubsection[title={Pushing back}]
+
+\libindex{get_next}
+\libindex{put_next}
+
+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. The \type {token.expand} function will trigger
+expansion but what happens really depends on what you're doing where.
+
+\stopsubsection
+
+\startsubsection[title={Nota bene}]
+
+When scanning for the next token you need to keep in mind that we're not scanning
+like \TEX\ does: expanding, changing modes and doing things as it goes. When we
+scan with \LUA\ we just pick up tokens. Say that we have:
+
+\starttyping
+\bar
+\stoptyping
+
+but \type {\bar} is undefined. Normally \TEX\ will then issue an error message.
+However, when we have:
+
+\starttyping
+\def\foo{\bar}
+\stoptyping
+
+We get no error, unless we expand \type {\foo} while \type {\bar} is still
+undefined. What happens is that as soon as \TEX\ sees an undefined macro it will
+create a hash entry and when later it gets defined that entry will be reused. So,
+\type {\bar} really exists but can be in an undefined state.
+
+\startbuffer[demo]
+bar : \directlua{tex.print(token.scan_csname())}\bar
+foo : \directlua{tex.print(token.scan_csname())}\foo
+myfirstbar : \directlua{tex.print(token.scan_csname())}\myfirstbar
+\stopbuffer
+
+\startlines
+\getbuffer[demo]
+\stoplines
+
+This was entered as:
+
+\typebuffer[demo]
+
+The reason that you see \type {bar} reported and not \type {myfirstbar} is that
+\type {\bar} was already used in a previous paragraph.
+
+If we now say:
+
+\startbuffer
+\def\foo{}
+\stopbuffer
+
+\typebuffer \getbuffer
+
+we get:
+
+\startlines
+\getbuffer[demo]
+\stoplines
+
+And if we say
+
+\startbuffer
+\def\foo{\bar}
+\stopbuffer
+
+\typebuffer \getbuffer
+
+we get:
+
+\startlines
+\getbuffer[demo]
+\stoplines
+
+When scanning from \LUA\ we are not in a mode that defines (undefined) macros at
+all. There we just get the real primitive undefined macro token.
+
+\startbuffer
+\directlua{local t = token.get_next() tex.print(t.id.." "..t.tok)}\myfirstbar
+\directlua{local t = token.get_next() tex.print(t.id.." "..t.tok)}\mysecondbar
+\directlua{local t = token.get_next() tex.print(t.id.." "..t.tok)}\mythirdbar
+\stopbuffer
+
+\startlines
+\getbuffer
+\stoplines
+
+This was generated with:
+
+\typebuffer
+
+So, we do get a unique token because after all we need some kind of \LUA\ object
+that can be used and garbage collected, but it is basically the same one,
+representing an undefined control sequence.
+
+\stopsubsection
+
+\stopsection
+
+\startsection[title={The \type {kpse} library}][library=kpse]
+
+\topicindex{libraries+\type{kpse}}
+
+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.
+
+\startsubsection[title={\type {set_program_name} and \type {new}}]
+
+\libindex{set_program_name}
+\libindex{default_texmfcnf}
+\libindex{new}
+
+The way the library looks up variables is driven by the \type {texmf.cmf} file
+where the currently set program name acts as filter. You can check what file is
+used by with \type {default_texmfcnf}.
+
+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 values.
+
+\stopsubsection
+
+\startsubsection[title={\type {find_file}}]
+
+\topicindex {files+finding}
+
+\libindex {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
+
+\stopsubsection
+
+\startsubsection[title={\type {lookup}}]
+
+\libindex{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|]
+\DB key \BC type \BC explanation \NC \NR
+\TB
+\NC \type{debug} \NC number \NC set debugging flags for this lookup\NC \NR
+\NC \type{format} \NC string \NC use specific file type (see list above)\NC \NR
+\NC \type{dpi} \NC number \NC use this resolution for this lookup; default 600\NC \NR
+\NC \type{path} \NC string \NC search in the given path\NC \NR
+\NC \type{all} \NC boolean \NC output all matches, not just the first\NC \NR
+\NC \type{mustexist} \NC boolean \NC search the disk as well as ls-R if necessary\NC \NR
+\NC \type{mktexpk} \NC boolean \NC disable/enable mktexpk generation for this lookup\NC \NR
+\NC \type{mktextex} \NC boolean \NC disable/enable mktextex generation for this lookup\NC \NR
+\NC \type{mktexmf} \NC boolean \NC disable/enable mktexmf generation for this lookup\NC \NR
+\NC \type{mktextfm} \NC boolean \NC disable/enable mktextfm generation for this lookup\NC \NR
+\NC \type{subdir} \NC string
+ or table \NC only output matches whose directory part
+ ends with the given string(s) \NC \NR
+\LL
+\stoptabulate
+
+\stopsubsection
+
+\startsubsection[title={\type {init_prog}}]
+
+\topicindex {initialization+bitmaps}
+
+\libindex{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
+
+\stopsubsection
+
+\startsubsection[title={\type {readable_file}}]
+
+\libindex{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.
+
+\stopsubsection
+
+\startsubsection[title={\type {expand_path}}]
+
+\libindex{expand_path}
+
+Like kpsewhich's \type {-expand-path}:
+
+\startfunctioncall
+<string> r = kpse.expand_path(<string> s)
+\stopfunctioncall
+
+\stopsubsection
+
+\startsubsection[title={\type {expand_var}}]
+
+\libindex{expand_var}
+
+Like kpsewhich's \type {-expand-var}:
+
+\startfunctioncall
+<string> r = kpse.expand_var(<string> s)
+\stopfunctioncall
+
+\stopsubsection
+
+\startsubsection[title={\type {expand_braces}}]
+
+\libindex{expand_braces}
+
+Like kpsewhich's \type {-expand-braces}:
+
+\startfunctioncall
+<string> r = kpse.expand_braces(<string> s)
+\stopfunctioncall
+
+\stopsubsection
+
+\startsubsection[title={\type {show_path}}]
+
+\libindex{show_path}
+
+Like kpsewhich's \type {-show-path}:
+
+\startfunctioncall
+<string> r = kpse.show_path(<string> ftype)
+\stopfunctioncall
+
+\stopsubsection
+
+\startsubsection[title={\type {var_value}}]
+
+\libindex{var_value}
+
+Like kpsewhich's \type {-var-value}:
+
+\startfunctioncall
+<string> r = kpse.var_value(<string> s)
+\stopfunctioncall
+
+\stopsubsection
+
+\startsubsection[title={\type {version}}]
+
+\libindex{version}
+
+Returns the kpathsea version string.
+
+\startfunctioncall
+<string> r = kpse.version()
+\stopfunctioncall
+
+\stopsubsection
+
+\stopsection
+
+\stopchapter
+
+\stopcomponent
|