summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-tex.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-tex.tex')
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-tex.tex706
1 files changed, 268 insertions, 438 deletions
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-tex.tex b/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-tex.tex
index 737f3b96081..503bbfd8293 100644
--- a/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-tex.tex
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-tex.tex
@@ -4,6 +4,16 @@
\startcomponent luametatex-tex
+% { "getbytecode", lualib_get_bytecode },
+% { "setbytecode", lualib_set_bytecode },
+% { "callbytecode", lualib_call_bytecode },
+% { "getfunctionstable", lualib_get_functions_table },
+% { "getstartupfile", lualib_get_startupfile },
+% { "getversion", lualib_get_version },
+% { "setexitcode", lualib_set_exitcode },
+% { NULL, NULL },
+
+
\startchapter[reference=tex,title={The \TEX\ related libraries}]
\startsection[title={The \type {lua} library}][library=lua]
@@ -11,21 +21,28 @@
\startsubsection[title={Version information}]
\topicindex{libraries+\type{lua}}
-\topicindex{version}
-\topicindex{startupfile}
+\topicindex{getversion}
+\topicindex{getstartupfile}
+
+\libindex{getversion}
+\libindex{getstartupfile}
+
+This version of the used \LUA\ interpreter (currently {\tttf \cldcontext
+{lua.getversion()}}) can be queried with:
-\libindex{version}
-\libindex{startupfile}
+\starttyping
+<string> v = lua.getversion()
+\stoptyping
-This library contains two read|-|only items:
+The name of used startup file, if at all, is returned by:
\starttyping
-<string> v = lua.version
-<string> s = lua.startupfile
+<string> s = lua.getstartupfile()
\stoptyping
-This returns the \LUA\ version identifier string. The value currently is
-\directlua {tex.print(lua.version)}.
+For this document the reported value is:
+
+\blank {\ttx \cldcontext {lua.getstartupfile()}} \blank
\stopsubsection
@@ -60,6 +77,7 @@ This preallocates 100 hash entries and 5000 index entries. The \type
\libindex{bytecode}
\libindex{setbytecode}
\libindex{getbytecode}
+\libindex{callbytecode}
\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
@@ -67,7 +85,7 @@ either a function or \type {nil}.
\starttyping
lua.bytecode[<number> n] = <function> f
-lua.bytecode[<number> n]()
+<function> f = lua.bytecode[<number> n] % -- f()
\stoptyping
The contents of the \type {lua.bytecode} array is stored inside the format file
@@ -75,8 +93,8 @@ 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)
+<function> f = lua.getbytecode(<number> n)
\stopfunctioncall
Note: Since a \LUA\ file loaded using \type {loadfile(filename)} is essentially
@@ -84,14 +102,14 @@ an anonymous function, a complete file can be stored in a bytecode register like
this:
\startfunctioncall
-lua.bytecode[n] = loadfile(filename)
+lua.setbytecode(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]()
+lua.callbytecode(n)
\stopfunctioncall
Note that the path of the file is stored in the \LUA\ bytecode to be used in
@@ -102,30 +120,6 @@ 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}
@@ -166,96 +160,100 @@ and values as a table.
<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:
+The keys in the table are the known items, the value is the current value. There are
+toplevel items and items that are tables with subentries. The current list is:
-\starttabulate[|l|p|]
-\DB key \BC explanation \NC \NR
+\startluacode
+ local list = status.list()
+
+ context.starttabulate { "|Tw(10em)|Tp|" }
+ context.DB()
+ context("toplevel statistics")
+ context.BC()
+ context.NC()
+ context.NR()
+ context.TB()
+ for k, v in table.sortedhash(list) do
+ if type(v) ~= "table" then
+ context.NC()
+ context(k)
+ context.NC()
+ context(tostring(v))
+ context.NC()
+ context.NR()
+ end
+ end
+ context.LL()
+ context.stoptabulate()
+
+ for k, v in table.sortedhash(list) do
+ if type(v) == "table" then
+ context.starttabulate { "|Tw(10em)|Tp|" }
+ context.DB()
+ context(k ..".*")
+ context.BC()
+ context.NC()
+ context.NR()
+ context.TB()
+ for k, v in table.sortedhash(v) do
+ context.NC()
+ context(k)
+ context.NC()
+ context(v == "" and "unset" or tostring(v))
+ context.NC()
+ context.NR()
+ end
+ context.LL()
+ context.stoptabulate()
+ end
+ end
+\stopluacode
+
+There are also getters for the subtables. The whole repertoire of functions in
+the \type {status} table is: {\tttf \cldcontext {table . concat ( table .
+sortedkeys (status), ", ")}}. The error and warning messages can be wiped with
+the \type {resetmessages} function. The states in subtables relate to memory
+management and are mostly there for development purposes.
+
+The \type {getconstants} query gives back a table with all kind of internal
+quantities and again these are only relevant for diagnostic and development
+purposes. Many are good old \TEX\ constants that are describes in the original
+documentation of the source but some are definitely \LUAMETATEX\ specific.
+
+\startluacode
+ context.starttabulate { "|Tw(15em)|Tp|" }
+ context.DB()
+ context("constants.*")
+ context.BC()
+ context.NC()
+ context.NR()
+ context.TB()
+ for k, v in table.sortedhash(status.getconstants()) do
+ if type(v) ~= "table" then
+ context.NC()
+ context(k)
+ context.NC()
+ context(tostring(v))
+ context.NC()
+ context.NR()
+ end
+ end
+ context.LL()
+ context.stoptabulate()
+\stopluacode
+
+Most variables speak for themselves, some are more obscure. For instance the
+\type {run_state} variable indicates what the engine is doing:
+
+\starttabulate[|l|l|p|]
+\DB n \NC meaning \NC 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
+\NC 0 \NC initializing \NC \type {--ini} mnode \NC \NR
+\NC 1 \NC updating \NC relates to \lpr {overloadmode} \NC \NR
+\NC 2 \NC production \NC a regular (format driven) run \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]
@@ -284,7 +282,8 @@ readable (like \prm {tracingcommands} and \prm {parindent}).
\topicindex{parameters+internal}
-\libindex{set} \libindex{get}
+\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
@@ -307,152 +306,8 @@ 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.
-\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:
+Beware: as with regular \LUA\ tables you can add values to the \type {tex} table.
+So, the following is valid:
\starttyping
tex.foo = 123
@@ -484,70 +339,52 @@ 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}
+\subsubsection{Integer parameters}
-The direction states can be queried and set with:
+The integer parameters accept and return \LUA\ integers. In some cases the values
+are checked, trigger other settings or result in some immediate change of
+behaviour: \ctxlua {document.filteredprimitives ("internal_int")}.
-\startthreecolumns
-\starttyping
-tex.gettextdir()
-tex.getlinedir()
-tex.getmathdir()
-tex.getpardir()
-tex.settextdir(<number>)
-tex.setlinedir(<number>)
-tex.setmathdir(<number>)
-tex.setpardir(<number>)
-\stoptyping
-\stopthreecolumns
+Some integer parameters are read only, because they are actually referring not to
+some internal integer register but to an engine property: \typ {deadcycles},
+\typ {insertpenalties}, \typ {parshape}, \typ {interlinepenalties}, \typ
+{clubpenalties}, \typ {widowpenalties}, \typ {displaywidowpenalties}, \typ
+{prevgraf} and \typ {spacefactor}.
-and also with:
+\subsubsection{Dimension parameters}
-\startthreecolumns
-\starttyping
-tex.textdirection
-tex.linedirection
-tex.mathdirection
-tex.pardirection
-\stoptyping
-\stopthreecolumns
+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: \ctxlua {document.filteredprimitives
+("internal_dimen")}.
+These are read|-|only: \typ {pagedepth}, \typ {pagefilllstretch}, \typ
+{pagefillstretch}, \typ {pagefilstretch}, \typ {pagegoal}, \typ {pageshrink},
+\typ {pagestretch} and \typ {pagetotal}.
-\subsubsection{Glue parameters}
+\subsubsection{Direction parameters}
-The glue parameters accept and return a userdata object that represents a \nod {glue_spec} node.
+The direction states can be queried with: \typ {gettextdir}, \typ {getlinedir},
+\typ {getmathdir} and \typ {getpardir}. You can set them with \typ
+{settextdir}, \typ {setlinedir}, \typ {setmathdir} and \typ {setpardir},
+commands that accept a number. You can also set these parameters as table
+key|/|values: \typ {textdirection}, \typ {linedirection}, \typ {mathdirection}
+and \typ {pardirection}, so the next code sets the text direction to \typ
+{r2l}:
-\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
+tex.textdirection = 1
\stoptyping
-\stopthreecolumns
-\subsubsection{Muglue parameters}
+\subsubsection{Glue parameters}
-All muglue parameters are to be used read|-|only and return a \LUA\ string.
+The internal glue parameters accept and return a userdata object that represents
+a \nod {glue_spec} node: \ctxlua {document.filteredprimitives ("internal_glue")}.
-\startthreecolumns
-\starttyping
-tex.medmuskip
-tex.thickmuskip
-tex.thinmuskip
-\stoptyping
-\stopthreecolumns
+\subsubsection{Muglue parameters}
+
+All muglue parameters are to be used read|-|only and return a \LUA\ string
+\ctxlua {document.filteredprimitives ("internal_mu_glue")}.
\subsubsection{Tokenlist parameters}
@@ -556,22 +393,8 @@ 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
+token strings. Here is the lot: \ctxlua {document.filteredprimitives
+("internal_toks")}.
\stopsubsection
@@ -580,55 +403,23 @@ tex.output
\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.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).
+supported commands at this moment are: \ctxlua {document.filteredprimitives
+("convert")}. You will get an error message if an operation is not (yet)
+permitted. Some take an string or number argument, just like at the \TEX\ end
+some extra input is expected.
\stopsubsection
-\startsubsection[title={Last item commands}]
+\startsubsection[title={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.currentgrouplevel
-tex.currentgrouptype
-tex.currentiflevel
-tex.currentiftype
-tex.currentifbranch
-\stoptyping
-\stopthreecolumns
+All so called \quote {item} commands are read|-|only and return a number. The
+complete list of these commands is: \ctxlua {document.filteredprimitives
+("some_item")}. No all are currently supported but eventually that might be the
+case. Like the lists in previous sections, there are differences between \LUATEX\
+and \LUAMETATEX, where some commands are organized differently in order to
+provide a consistent \LUA\ interface.
\stopsubsection
@@ -649,6 +440,8 @@ tex.currentifbranch
\libindex{scantoks}
+\libindex{getmark}
+
\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
@@ -734,17 +527,17 @@ We have similar setters for \type {count}, \type {dimen}, \type {muskip}, and
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 case only the width is
-returned.
+\type {setglue} function accepts upto five arguments: width, stretch, shrink,
+stretch order and shrink order. Non|-|numeric values set the property to zero.
+The \type {getglue} function reports all five properties, unless the second
+argument is \type {false} in which case only the width is returned.
Here is an example using a threesome:
\startfunctioncall
local d = tex.getdimen("foo")
-if tex.isdimen("bar") then
- tex.setdimen("bar",d)
+if tex.isdimen("oof") then
+ tex.setdimen("oof",d)
end
\stopfunctioncall
@@ -784,6 +577,15 @@ tex.scantoks("global",0,3,"$\int\limits^1_2$")
In the function-based interface, it is possible to define values globally by
using the string \type {global} as the first function argument.
+There is a dedicated getter for marks: \type {getmark} that takes two arguments.
+The first argument is one of \type {top}, \type {bottom}, \type {first}, \type
+{splitbottom} or \type {splitfirst}, and the second argument is a marks class
+number. When no arguments are given the current maximum number of classes is
+returned.
+
+When \type {tex.gettoks} gets an extra argument \type {true} it will return a
+table with userdata tokens.
+
\stopsubsection
\startsubsection[title={Character code registers: \type {[get|set]*code[s]}}]
@@ -1061,7 +863,7 @@ keep track of building page lists.
\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{contribute_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
@@ -1120,7 +922,7 @@ The known fields are:
\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{direction} \NC node \NC hmode \NC stack 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,
@@ -1524,14 +1326,15 @@ an error:
This function has two optional arguments in case a token register is passed:
\startfunctioncall
-tex.runtoks(<token register>,force,grouped)
+tex.runtoks(<token register>,force,grouped,obeymode)
\stopfunctioncall
Inside for instance an \type {\edef} the \type {runtoks} function behaves (at
least tries to) like it were an \type {\the}. This prevents unwanted side
effects: normally in such an definition tokens remain tokens and (for instance)
characters don't become nodes. With the second argument you can force the local
-main loop, no matter what. The third argument adds a level of grouping.
+main loop, no matter what. The third argument adds a level of grouping. The last
+argument tells the scanner to stay in the current mode.
You can quit the local loop with \type {\endlocalcontrol} or from the \LUA\ end
with \type {tex.quittoks}. In that case you end one level up! Of course in the
@@ -1657,20 +1460,6 @@ 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)
- local t = tex.extraprimitives(tag)
- table.sort(t)
- for i=1,#t do
- local v = t[i]
- 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
@@ -1750,7 +1539,7 @@ The understood parameters are as follows:
\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{protrudechars} \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
@@ -1781,7 +1570,7 @@ horizontal mode):
\startitemize
\startitem
- add an \quote {indent box} and perhaps a \nod {local_par} node at the start
+ add an \quote {indent box} and perhaps a \nod {par} node at the start
(only if you need them)
\stopitem
\startitem
@@ -1969,8 +1758,8 @@ texio.write(<string> s, ...)
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}.
+terminal. The optional \type {target} can be one of \type {terminal},
+\type {logfile} or \type {terminal_and_logfile}.
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
@@ -2071,6 +1860,9 @@ most intriguing.
\LL
\stoptabulate
+The integer, dimension and glue scanners take an extra optional argument that
+signals that en optional equal is permitted.
+
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 {scan_keyword}
function a normal \LUA\ string. The \type {infinity} boolean signals that we also
@@ -2080,14 +1872,19 @@ 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 \type {scan_argument} function expands the given argument. When a braced
+argument is scanned, expansion can be prohibited by passing \type {false}
+(default is \type {true}). In case of a control sequence passing \type {false}
+will result in a one|-|level expansion (the meaning of the macro).
+
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}
+\def\oof{oof}
+\def\foo{foo-\oof}
\stopbuffer
\typebuffer \getbuffer
@@ -2108,7 +1905,9 @@ expanded definition (\prm {edef}'d). In the case of the braced variant one can o
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:
+The \type {scan_word} scanner can be used to implement for instance a number
+scanner. An optional boolean argument can signal that a trailing space or \type
+{\relax} should be gobbled:
\starttyping
function token.scan_number(base)
@@ -2176,22 +1975,43 @@ a bit but for passing strings conversion to and from tokens has to be done anywa
\startsubsection[title={Picking up one token}]
-\libindex {get_next}
+\libindex {scan_next}
+\libindex {scan_next_expanded}
+\libindex {skip_next}
+\libindex {skip_next_expanded}
+\libindex {peek_next}
+\libindex {peek_next_expanded}
\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)
+input you use \type {scan_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.
+enforce expansion first you can use \type {scan_token} or the \type {_expanded}
+variants. 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.
+\starttabulate[|lT|p|]
+\DB name \BC explanation \NC \NR
+\TB
+\NC scan_next \NC get the next token \NC \NR
+\NC scan_next_expanded \NC get the next expanded token \NC \NR
+\NC skip_next \NC skip the next token \NC \NR
+\NC skip_next_expanded \NC skip the next expanded token \NC \NR
+\NC peek_next \NC get the next token and put it back in the input \NC \NR
+\NC peek_next_expanded \NC get the next expanded token and put it back in the input \NC \NR
+\LL
+\stoptabulate
+
+The peek function accept a boolean argument that triggers skipping spaces and
+alike.
+
\stopsubsection
\startsubsection[title={Creating tokens}]
@@ -2216,8 +2036,10 @@ the internal expand related function.
\libindex{get_mode}
\libindex{get_index}
\libindex{get_tok}
+\libindex{get_frozen}
+\libindex{get_user}
-\libindex{get_next}
+\libindex{scan_next}
The creator function can be used as follows:
@@ -2241,8 +2063,9 @@ primitive. The possible properties of tokens are:
\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
+\NC \type {frozen} \NC a boolean indicating if the token is a frozen command \NC \NR
+\NC \type {user} \NC a boolean indicating if the token is a user defined command \NC \NR
+\NC \type {index} \NC a number that indicated the subcommand; differs per command \NC \NR
\LL
\stoptabulate
@@ -2307,6 +2130,8 @@ need to know that boundary condition.
\libindex{set_char}
\libindex{set_lua}
\libindex{get_functions_table}
+\libindex{push_macro}
+\libindex{pop_macro}
The \type {set_macro} function can get upto 4 arguments:
@@ -2356,20 +2181,25 @@ that you can access with \type {lua.get_functions_table}. It is the companion
to \lpr {luadef}. When the first (and only) argument is true the size will preset
to the value of \type {texconfig.function_size}.
+The \type {push_macro} and \type {pop_macro} function are very experimental and
+can be used to get and set an existing macro. The push call returns a user data
+object and the pop takes such a userdata object. These object have no accessors
+and are to be seen as abstractions.
+
\stopsubsection
\startsubsection[title={Pushing back}]
-\libindex{get_next}
+\libindex{scan_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()
+local t1 = token.scan_next()
+local t2 = token.scan_next()
+local t3 = token.scan_next()
+local t4 = token.scan_next()
-- watch out, we flush in sequence
token.put_next { t1, t2 }
-- but this one gets pushed in front
@@ -2410,28 +2240,28 @@ When scanning for the next token you need to keep in mind that we're not scannin
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:
-\pushmacro\bar \let\bar\undefined
+\pushmacro\oof \let\oof\undefined
\starttyping
-\bar
+\oof
\stoptyping
-but \type {\bar} is undefined. Normally \TEX\ will then issue an error message.
+but \type {\oof} is undefined. Normally \TEX\ will then issue an error message.
However, when we have:
\starttyping
-\def\foo{\bar}
+\def\foo{\oof}
\stoptyping
-We get no error, unless we expand \type {\foo} while \type {\bar} is still
+We get no error, unless we expand \type {\foo} while \type {\oof} 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.
+\type {\oof} really exists but can be in an undefined state.
\startbuffer[demo]
-bar : \directlua{tex.print(token.scan_csname())}\bar
+oof : \directlua{tex.print(token.scan_csname())}\oof
foo : \directlua{tex.print(token.scan_csname())}\foo
-myfirstbar : \directlua{tex.print(token.scan_csname())}\myfirstbar
+myfirstoof : \directlua{tex.print(token.scan_csname())}\myfirstoof
\stopbuffer
\startlines
@@ -2442,8 +2272,8 @@ 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.
+The reason that you see \type {oof} reported and not \type {myfirstoof} is that
+\type {\oof} was already used in a previous paragraph.
If we now say:
@@ -2462,7 +2292,7 @@ we get:
And if we say
\startbuffer
-\def\foo{\bar}
+\def\foo{\oof}
\stopbuffer
\typebuffer \getbuffer
@@ -2477,9 +2307,9 @@ 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
+\directlua{local t = token.scan_next() tex.print(t.id.." "..t.tok)}\myfirstoof
+\directlua{local t = token.scan_next() tex.print(t.id.." "..t.tok)}\mysecondoof
+\directlua{local t = token.scan_next() tex.print(t.id.." "..t.tok)}\mythirdoof
\stopbuffer
\startlines
@@ -2494,7 +2324,7 @@ 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.
-\popmacro\bar
+\popmacro\oof
\stopsubsection