diff options
| author | Taco Hoekwater <taco@elvenkind.com> | 2010-05-13 07:38:40 +0000 |
|---|---|---|
| committer | Taco Hoekwater <taco@elvenkind.com> | 2010-05-13 07:38:40 +0000 |
| commit | efabee1b742bcf1a583b63f9212e285dbb308e21 (patch) | |
| tree | 0d981eac6cf04b4c7c488813826a96ecd876f217 | |
| parent | bcbec8522a4973bfbd5bb14d500001aebed96435 (diff) | |
new luatex manual (matching 0.60.1)
git-svn-id: svn://tug.org/texlive/trunk@18226 c570f23f-e606-0410-a88d-b1316a301751
| -rw-r--r-- | Master/texmf-dist/doc/luatex/base/luatexref-env.tex | 2 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/luatex/base/luatexref-t.pdf | bin | 646592 -> 499752 bytes | |||
| -rw-r--r-- | Master/texmf-dist/doc/luatex/base/luatexref-t.tex | 6286 |
3 files changed, 3531 insertions, 2757 deletions
diff --git a/Master/texmf-dist/doc/luatex/base/luatexref-env.tex b/Master/texmf-dist/doc/luatex/base/luatexref-env.tex index a7c9ba6bcc9..328247679a2 100644 --- a/Master/texmf-dist/doc/luatex/base/luatexref-env.tex +++ b/Master/texmf-dist/doc/luatex/base/luatexref-env.tex @@ -335,7 +335,7 @@ [chapter,section,subsection] \setuplist - [chapter,section,subsection] + [chapter,section,subsection,subsubsection] [interaction=all] % Hans doesn't like the bookmarks opening by default diff --git a/Master/texmf-dist/doc/luatex/base/luatexref-t.pdf b/Master/texmf-dist/doc/luatex/base/luatexref-t.pdf Binary files differindex 977c2fe8b56..9e1a76da041 100644 --- a/Master/texmf-dist/doc/luatex/base/luatexref-t.pdf +++ b/Master/texmf-dist/doc/luatex/base/luatexref-t.pdf diff --git a/Master/texmf-dist/doc/luatex/base/luatexref-t.tex b/Master/texmf-dist/doc/luatex/base/luatexref-t.tex index efb17c50aa3..e4743e6cdee 100644 --- a/Master/texmf-dist/doc/luatex/base/luatexref-t.tex +++ b/Master/texmf-dist/doc/luatex/base/luatexref-t.tex @@ -1,4 +1,4 @@ -% engine=luatex language=uk +% engine=luatex language=uk % TODO: fix layout of function legend descriptions % check numbers @@ -7,7 +7,7 @@ %\nopdfcompression %\loggingall \environment luatexref-env - +\logo[DFONT] {dfont} \logo[CFF] {cff} \logo[CMAP] {CMap} \logo[PATGEN] {patgen} @@ -22,7 +22,7 @@ \setvariables [document] - [beta=0.40.6] + [beta=0.60.1] \starttext @@ -36,7 +36,7 @@ \chapter{Introduction} -\startframedtext[framecolor=red,foregroundcolor=red,width=\hsize,font=\tfa] +\startframedtext[framecolor=red,foregroundcolor=red,width=\hsize,style=\tfa] This book will eventually become the reference manual of \LUATEX. At the moment, it simply reports the behaviour of the executable @@ -58,11 +58,10 @@ notice. \blank -\bf If you are not willing to deal with this situation, you should -wait for the stable version. Currently we expect the first release -with (some) fixed interfaces to be available sometime in the autumn -of~2008. Full stabilization will not happen soon, the TODO list is -still very large. +{\bf If you are not willing to deal with this situation, you should +wait for the stable version. Currently we expect the 1.0 release to +happen in spring 2012. Full stabilization will not happen soon, the +TODO list is still large.} \stopframedtext @@ -72,8 +71,8 @@ still very large. distinguishable parts: \startitemize[packed] -\item \PDFTEX\ version 1.40.9 -\item \ALEPH\ RC4 (from the \TEXLIVE\ repository) +\item \PDFTEX\ version 1.40.9, converted to C. +\item \ALEPH\ RC4 converted to C. \item \LUA\ 5.1.4 ($+$ coco 1.1.5 $+$ portable bytecode) \item dedicated \LUA\ libraries \item various \TEX\ extensions @@ -93,12 +92,12 @@ implemented in \LUA\ instead. \section{Introduction} From day one, \LUATEX\ has offered extra functionality when compared -to the superset of pdftex and Aleph. That has not been limited to +to the superset of \PDFTEX\ and Aleph. That has not been limited to the possibility to execute lua code via \type{\directlua}, but \LUATEX\ also adds functionality via new \TEX-side primitives. However, starting with beta \type{0.39.0}, most of that functionality -will be hidden by default. When \LUATEX\ 0.40.0 starts up in +is hidden by default. When \LUATEX\ 0.40.0 starts up in \quote{iniluatex} mode (\type{luatex -ini}), it defines only the primitive commands known by \TEX82 and the one extra command \type{\directlua}. @@ -123,8 +122,11 @@ so it may be needed to put these assignments before the above line. More fine-grained primitives control is possible, you can look the details in -\in{section}[luaprimitives]. For simplicity's sake, this manual -assumes that you have executed the lua command given above. +\in{section}[luaprimitives]. For simplicity's sake, this manual assumes +that you have executed the \type{\directlua} command as given above. + +The startup behavior documented above is considered stable in the sense +that there will not be backward-incompatible changes any more. \section{Version information} @@ -147,7 +149,7 @@ The official \LUATEX\ version is defined follows: \startitemize \item The major version is the integer result of \tex{luatexversion} divided by 100. - The primitive is and \quote{internal variable}, so you may need to prefix it + The primitive is an \quote{internal variable}, so you may need to prefix its use with \type{\the} depending on the context. \item The minor version is the two-digit result of \tex{luatexversion} modulo 100. \item The revision is the given by \tex{luatexrevision}. This primitive expands to a @@ -158,7 +160,7 @@ The official \LUATEX\ version is defined follows: Note that the \tex{luatexdatestamp} depends on both the compilation -time and compilation place of the current executable, it is defined in +time and compilation place of the current executable; it is defined in terms of the local time. The purpose of this primitive is solely to be an aid in the development process, do not use it for anything besides debugging. @@ -245,7 +247,11 @@ The glyph properties (like \type {\efcode}) introduced in \PDFTEX\ that deal with font expansion (hz) and character protruding are also 16~bit. Because font memory management has been rewritten, these character properties are no longer shared among fonts -instances that originate from the same metric file +instances that originate from the same metric file. + +The behavior documented in the above section is considered stable +in the sense that there will not be backward-incompatible changes any +more. \section{Attribute registers} @@ -273,11 +279,14 @@ Attributes can be used as extra counter values, but their usefulness comes mostly from the fact that the numbers and values of all \quote{set} attributes are attached to all nodes created in their scope. These can then be queried from any \LUA\ code that deals with node -processing. Future versions of -\LUATEX\ will probably be using specific negative attribute ids for -internal use. Further information about how to use attributes for node +processing. Further information about how to use attributes for node list processing from \LUA\ is given in~\in{chapter}[nodes]. +The behavior documented in the above subsection is considered stable +in the sense that there will not be backward-incompatible changes any +more. + + \subsection{Box attributes} Nodes typically receive the list of attributes that is in effect when @@ -345,13 +354,6 @@ The syntax is \directlua <16-bit number> <general text> \stopsyntax -{\bf Up until beta 0.36, there was support for multiple lua states, -and to make that possible, the \type{\directlua} and \type{\latelua} -command required an integer argument to be given always. Such integer -values are still accepted for the moment, although they generate a -(rather pesky) warning. This backward compatibility support will be -removed starting with beta \type{0.41.0}.} - The last \syntax{<general text>} is expanded fully, and then fed into the \LUA\ interpreter. After reading and expansion has been applied to the \syntax{<general text>}, the resulting token list is converted to a @@ -360,10 +362,10 @@ side, each \type{\directlua} block is treated as a separate chunk. In such a chunk you can use the \type {local} directive to keep your variables from interfering with those used by the macro package. -The conversion from and to a token list means that you normally can +The conversion to and from a token list means that you normally can not use \LUA\ line comments (starting with \type{--}) within the -argument, as there typically will be only one \quote{line}, so that comment -will then run on until the end of the input. You will either need to +argument. As there typically will be only one \quote{line} the first +line comment will run on until the end of the input. You will either need to use \TEX-style line comments (starting with \%), or change the \TEX\ category codes locally. Another possibility is to say: @@ -394,10 +396,6 @@ chunk, but in this case the name will be taken from the \type{lua.name} array (see the documentation of the \type{lua} table further in this manual). This syntax is new in version 0.36.0. -Backward compatibility note: when there is a valid name in -\type{lua.name[<16-bit number>]}, the potential warning about -a superfluous integer will be suppressed. - The chunk name should not start with a \type{@}, or it will be displayed as a file name (this is a quirk in the current \LUA\ implementation). @@ -418,7 +416,7 @@ will result in Because the \syntax{<general text>} is a chunk, the normal \LUA\ error handling is triggered if there is a problem in the included code. The \LUA\ error messages should be clear enough, but the contextual -information is still pretty bad. Typically, you will only see the line +information is still pretty bad. Often, you will only see the line number of the right brace at the end of the code. While on the subject of errors: some of the things you can do inside @@ -426,13 +424,17 @@ While on the subject of errors: some of the things you can do inside while working with the node list interface, you may even end up with assertion errors from within the \TEX\ portion of the executable. +The behavior documented in the above subsection is considered stable +in the sense that there will not be backward-incompatible changes any +more. + \subsection{\tex{latelua}} \tex{latelua} stores \LUA\ code in a whatsit that will be processed inside the output routine. Its intended use is a cross between \tex{pdfliteral} and \tex{write}. -Within the \LUA\ code, you can print \PDF\ -statements directly to the \PDF\ file via \type{tex.print}, +Within the \LUA\ code you can print \PDF\ +statements directly to the \PDF\ file via \type{pdf.print}, or you can write to other output streams via \type{texio.write} or simply using lua's I/O routines. @@ -442,13 +444,6 @@ or simply using lua's I/O routines. \latelua <16-bit number> <general text> \stopsyntax -{\bf Up until beta 0.36, there was support for multiple lua states, -and to make that possible, the \type{\directlua} and \type{\latelua} -command required an integer argument to be given always. Such integer -values are still accepted for the moment, although they generate a -(rather pesky) warning. This backward compatibility support will be -removed starting with beta \type{0.41.0}.} - Expansion of macros etcetera in the final \type{<general text>} is delayed until just before the whatsit is executed (like in \tex{write}). With regard to PDF output stream \tex{latelua} behaves as \tex{pdfliteral page}. @@ -533,6 +528,20 @@ differences are: conditional is still incomplete. \stopitemize +\subsection {Verbose versions of single-character aligments commands (0.45)} + +\LUATEX\ defines two new primitives that have the same function as +\type{#} and \type{&} in aligments: + +\starttabulate[|l|l|l|l|] +\NC \bf primitive \NC \bf explanation \NC\NR +\NC \tex{alignmark} \NC Duplicates the functionality of \char`\#~ + inside alignment preambles\NC\NR +\NC \tex{aligntab} \NC Duplicates the functionality of \char`\&~ + inside alignments (and preambles)\NC\NR +\stoptabulate + + \subsection{Catcode tables} Catcode tables are a new feature that allows you to switch to a @@ -658,7 +667,7 @@ was simply ignored. That behaviour has now reverted back to be \stopsyntax This new integer parameter allows you to alter the number of the box -that will be used to store the page to be shipped out in. It's default +that will be used to store the page to be shipped out in. Its default value is 255, and the acceptable range is from 0 to 65535. @@ -673,11 +682,48 @@ value is 255, and the acceptable range is from 0 to 65535. This allows for embedded spaces, without the need for double quotes. Macro expansion takes place inside the argument. +\subsection{File syntax (0.45)} + +\LUATEX\ will accept a braced argument as a file name: + +\starttyping +\input {plain} +\openin 0 {plain} +\stoptyping + +This allows for embedded spaces, without the need for double quotes. +Macro expansion takes place inside the argument. + +\subsection{Images and Forms} + +\LUATEX\ accepts optional dimension parameters for \type{\pdfrefximage} +and \type{\pdfrefxform} in the same format as for \type{\pdfximage}. +With images, these dimensions are then used +instead of the ones given to \type{\pdfximage}; +but the original dimensions are not overwritten, +so that a \type{\pdfrefximage} without dimensions still provides +the image with dimensions defined by \type{\pdfximage}. +These optional parameters are not implemented for \type{\pdfxform}. + +\starttyping +\pdfrefximage width 20mm height 10mm depth 5mm \pdflastximage +\pdfrefxform width 20mm height 10mm depth 5mm \pdflastxform +\stoptyping + \section{Debugging} If \tex{tracingonline} is larger than~2, the node list display will also print the node number of the nodes. +\section{Global leaders} + +There is a new experimental primitive: \type{\gleaders} (a \LUATEX\ +extension, added in 0.43). This type of leaders is anchored to the +origin of the box to be shipped out. So they are like normal +\type{\leaders} in that they align nicely, except that the alignment +is based on the {\it largest\/} enclosing box instead of the +{\it smallest\/}. + \chapter {\LUA\ general} \section[init]{Initialization} @@ -722,29 +768,68 @@ and that it accepts (but ignores) the \type{--luaconly} switch. When the \LUATEX\ executable starts, it looks for the \type{--lua} commandline option. If there is no \type{--lua} option, the commandline is interpreted in a similar fashion as in traditional -\PDFTEX\ and \ALEPH. But if the option is present, \LUATEX\ will enter an -alternative mode of commandline parsing in comparison to the standard -web2c programs. +\PDFTEX\ and \ALEPH. -In this mode, a small series of actions is taken in order. At first, -it will only interpret a small subset of the commandline directly: +The following command-line switches are understood. \starttabulate[|lT|p|] -\NC --lua=s \NC load and execute a \LUA\ initialization script \NC\NR +\NC --fmt=FORMAT \NC load the format file FORMAT \NC\NR +\NC --lua=s \NC load and execute a \LUA\ initialization script\NC\NR \NC --safer \NC disable easily exploitable \LUA\ commands \NC\NR \NC --nosocket \NC disable the \LUA\ socket library \NC\NR \NC --help \NC display help and exit \NC\NR -\NC --version \NC display version and exit \NC\NR -\stoptabulate +\NC --ini \NC be iniluatex, for dumping formats \NC\NR +\NC --interaction=STRING \NC set interaction mode (STRING=batchmode/nonstopmode/\crlf + scrollmode/errorstopmode) \NC \NR +\NC --halt-on-error \NC stop processing at the first error\NC \NR +\NC --kpathsea-debug=NUMBER \NC set path searching debugging flags according to + the bits of NUMBER \NC \NR +\NC --progname=STRING \NC set the program name to STRING \NC \NR +\NC --version \NC display version and exit \NC\NR +\NC --credits \NC display credits and exit \NC\NR +\NC --recorder \NC enable filename recorder \NC \NR +\NC --etex \NC ignored\NC \NR +\NC --output-comment=STRING \NC use STRING for DVI file comment instead of date + (no effect for PDF)\NC \NR +\NC --output-directory=DIR \NC use DIR as the directory to write files to \NC \NR +\NC --draftmode \NC switch on draft mode (generates no output PDF)\NC \NR +\NC --output-format=FORMAT \NC use FORMAT for job output; FORMAT is 'dvi' or 'pdf' \NC \NR +\NC --[no-]shell-escape \NC disable/enable \type{\write18{SHELL COMMAND}} \NC \NR +\NC --enable-write18 \NC enable \type{\write18{SHELL COMMAND}} \NC \NR +\NC --disable-write18 \NC disable \type{\write18{SHELL COMMAND}} \NC \NR +\NC --shell-restricted \NC restrict \type{\write18} to a list of commands + given in texmf.cnf \NC \NR +\NC --debug-format \NC enable format debugging \NC \NR +\NC --[no-]file-line-error \NC disable/enable file:line:error style messages \NC \NR +\NC --[no-]file-line-error-style \NC aliases of --[no-]file-line-error \NC \NR +\NC --jobname=STRING \NC set the job name to STRING \NC \NR +\NC --[no-]parse-first-line \NC disable/enable parsing of the first line of the + input file \NC \NR +\NC --translate-file= \NC ignored \NC \NR +\NC --default-translate-file= \NC ignored \NC \NR +\NC --8bit \NC ignored \NC \NR +\NC --[no-]mktex=FMT \NC disable/enable mktexFMT generation (FMT=tex/tfm)\NC \NR +\NC --synctex=NUMBER \NC enable synctex \NC \NR +\stoptabulate + +But if the option is present, \LUATEX\ will enter an alternative mode +of commandline processing in comparison to the standard web2c +programs. + +In this mode, a small series of actions is taken in order. First, +it will parse the commandline as usual, but it will only interpret +a small subset of the options immediately: \type{--safer}, \type{--nosocket}, +\type{--[no-]shell-escape}, \type{--enable-write18}, \type{--disable-write18}, +\type{--shell-restricted}, \type{--help}, \type{--version}, and \type{--credits}. Now it searches for the requested \LUA\ initialization script. If it can not be found using the actual name given on the commandline, a second attempt is made by prepending the value of the environment variable \type{LUATEXDIR}, if that variable is defined. -Then it checks the \type{--safer} switch. You can use that to disable +Then it checks the various safety switches. You can use those to disable some \LUA\ commands that can easily be abused by a malicious document. At -the moment, this switch \type{nil}s the following functions: +the moment, \type{--safer} \type{nil}s the following functions: \starttabulate[|l|l|] \NC \bf library \NC \bf functions \NC \NR @@ -753,8 +838,18 @@ the moment, this switch \type{nil}s the following functions: \NC \tt lfs \NC \tt rmdir mkdir chdir lock touch \NC \NR \stoptabulate -And it makes \lua{io.open()} fail on files that are opened for -anything besides reading. +Furthermore, it disables loading of compiled \LUA\ libraries (support +for these was added in 0.46.0), and it makes \lua{io.open()} fail on +files that are opened for anything besides reading. + +\type{--nosocket} makes the socket library unavailable, so that +\LUA\ cannot use networking. + +The switches \type{--[no-]shell-escape}, \type{--[enable|disable]-write18}, and +\type{--shell-restricted} have the same +effects as in \PDFTEX, and additionally make +\type{io.popen()}, \type{os.execute}, \type{os.exec} and \type{os.spawn} +adhere to the requested option. Next the initialization script is loaded and executed. From within the script, the entire commandline is available in the \LUA\ table @@ -764,8 +859,7 @@ Commandline processing happens very early on. So early, in fact, that none of \TEX's initializations have taken place yet. For that reason, the tables that deal with typesetting, like \luatex{tex}, \luatex{token}, \luatex{node} and \luatex{pdf}, are off|-|limits during the execution -of the startup file (they are -nilled). Special care is taken that \luatex{texio.write} and +of the startup file (they are nilled). Special care is taken that \luatex{texio.write} and \luatex{texio.write_nl} function properly, so that you can at least report your actions to the log file when (and if) it eventually becomes opened (note that \TEX\ does not even know its \tex{jobname} @@ -784,8 +878,10 @@ four global names, as they will be overwritten completely. We recommend you use the startup file only for your own \TEX|-|independent initializations (if you need any), to parse the commandline, set values in the \luatex{texconfig} table, and register -the callbacks you need. \LUATEX\ will fetch some of the other -commandline options from the \luatex{texconfig} table at the end of +the callbacks you need. + +\LUATEX\ allows some of the commandline opiotns to be overridden +by reading values from the \luatex{texconfig} table at the end of script execution (see the description of the \luatex{texconfig} table later on in this document for more details on which ones exactly). @@ -794,24 +890,69 @@ Unless the \luatex{texconfig} table tells \LUATEX\ not to initialize \LUATEX\ acts on three more commandline options after the initialization script is finished: -\starttabulate[|l|l|] -\NC \bf flag \NC \bf meaning \NC \NR -\NC \tt --fmt=s \NC set the format name \NC \NR -\NC \tt --progname=s \NC set the progname (only for \KPATHSEA) \NC \NR -\NC \tt --ini \NC enable \INITEX\ mode \NC \NR -\stoptabulate - -In order to initialize the built|-|in \KPATHSEA\ library properly, -\LUATEX\ needs to know the correct \type{progname} to use, and for that it -needs to check \type{--progname} (and \type{--ini} and \type{--fmt}, if -\type{--progname} is missing). +in order to initialize the built|-|in \KPATHSEA\ library properly, +\LUATEX\ needs to know the correct program name to use, and for that it +needs to check \type{--progname}, or \type{--ini} and \type{--fmt}, if +\type{--progname} is missing. \section{\LUA\ changes} -The C coroutine (\COCO) patches from luajit are applied to the \LUA\ core, the used -version is 1.1.3. See \hyphenatedurl{http://luajit.org/coco.html} for details. +The C coroutine (\COCO) patches from luajit are applied to the \LUA\ +core, the used version is 1.1.5. See \hyphenatedurl{http://luajit.org/coco.html} +for details. This functionality currently (0.45) does not work on +non-intel OpenBSD platforms nor on powerpc Linux-es. Additional note: +\type{coroutines.wrap()} under Windows does not inherit the state +of the random generator, it always has an implicit +\type{math.randomseed(1)} that is added by the Windows kernel. + +Starting from version 0.45, \LUATEX\ is able to use the kpathsea +library to find \type{require()}d modules. For this purpose, +\type{package.loaders[2]} is replaced by a different loader function, +that decides at runtime whether to use kpathsea or the build-in core +lua function. It uses \KPATHSEA\ when that is already initialized at +that point in time, otherwise it reverts to using the normal +\type{package.path} loader. + +Initialization of \KPATHSEA\ can happen either implicitly (when +\LUATEX\ starts up and the startup script has not set +\type{texconfig.kpse_init} to false), or explicitly by calling the +\LUA\ function \type{kpse.set_program_name()}. + + +Starting from version 0.46.0 (as an {\bf experimental} feature!) \LUATEX\ is +also able to use dynamically loadable \LUA\ libraries, unless +\type{--safer} was given as an option on the command line. + +For this purpose, \type{package.loaders[3]} is replaced by a different +loader function, that decides at runtime whether to use kpathsea or +the build-in core lua function. As in the previous paragraph, it uses +\KPATHSEA\ when that is already initialized at that point in time, +otherwise it reverts to using the normal \type{package.cpath} loader. + +This functionality required an extension to kpathsea: + +\startnarrower +There is a new kpathsea file format: \type{kpse_clua_format} that +searches for files with extension \type{.dll} and \type{.so}. The +\type{texmf.cnf} setting for this variable \type{is CLUAINPUTS}, and +by default it has this value: + +\starttyping +CLUAINPUTS=.:$SELFAUTOLOC/lib/{$progname,$engine,}/lua// +\stoptyping %$ + +This path is imperfect (it requires a TDS subtree below the binaries +directory), but the architecture has to be in the path somewhere, and +the currently simplest way to do that is to search below the binary +directory only. -In keeping with the other \TEX-like programs in \TEXLIVE, the two \LUA\ functions +One level up (a \type{lib} directory parallel to \type{bin}) would +have been nicer, but that is not doable because texlive uses a +\type{bin/<arch>} structure. +\stopnarrower + +In keeping with the other \TEX-like programs in \TEXLIVE, the two +\LUA\ functions \type{os.execute} and \type{io.popen} (as well as the two new functions \type{os.exec} and \type{os.spawn} that are explained below) take the value of \type{shell_escape} and/or \type{shell_escape_commands} in account. Whenever \LUATEX\ is run with the @@ -830,16 +971,21 @@ adjusted so that it is line|-|ending neutral: any of \type{LF}, \type {CR} or \type{CR+LF} are acceptable line endings. The \lua{tostring()} printer for numbers has been changed so that it -returns~\type{0} instead of something like~\hbox{\type{2e-5}} (which confused \TEX\ -enormously) when the value is so small that \TEX\ cannot distinguish -it from zero. - -Dynamic loading of \type{.so} and \type{.dll} files is disabled on -all platforms. - -\lua{luafilesystem} has been extended with two extra boolean functions -(\luatex{isdir(filename)} and \luatex{isfile(filename)}) and one extra -string field in its attributes table (\type{permissions}). +returns~\type{0.00000000000001} instead of~\hbox{\type{1e-14}} (which +confused \TEX\ enormously). Even values with an even smaller exponent +print simply as~\type{0}. + +\lua{luafilesystem} has been extended: there are two extra boolean functions +(\luatex{lfs.isdir(filename)} and \luatex{lfs.isfile(filename)}) and +one extra string field in its attributes table +(\type{permissions}). There is an additional function (added in 0.51) +\type{lfs.shortname()} which takes a file name and returns its short +name on WIN32 platforms. On other platforms, it just returns the given +argument. The file name is not tested for existence. Finally, for +non-WIN32 platforms only, there is the new function +\type{lfs.readlink()} (added in 0.51) that takes an existing symbolic +link as argument and returns its content. It returns an error on +WIN32. The \lua{string} library has an extra function: \luatex{string.explode(s[,m])}. This function returns an array containing @@ -874,16 +1020,30 @@ number as its second return value if the string length was odd. The \luatex{string.characterpairs()} and \luatex{string.bytepairs()} are useful especially in the conversion of UTF-16 encoded data into UTF-8. -Note: The \lua{string} library functions \luatex{find} etc. are not -\UNICODE|-|aware. In cases where this is required (i.\,e.\ because the -pattern used for searching contains characters above code point 127), -the corresponding functions from \lua{unicode.utf8} should be used. - +Note: The \lua{string} library functions \luatex{len}, \luatex{lower}, +\luatex{sub} etc. are not \UNICODE|-|aware. For strings in the UTF-8 +encoding, i.e., strings containing characters above code point 127, the +corresponding functions from the \lua{slnunicode} library can be used, +e.g., \luatex{unicode.utf8.len}, \luatex{unicode.utf8.lower} etc. The +exceptions are \luatex{unicode.utf8.find}, that always returns byte +positions in a string, and \luatex{unicode.utf8.match} and +\luatex{unicode.utf8.gmatch}. While the latter two functions in general +{\it are} \UNICODE|-|aware, they fall-back to non|-|\UNICODE|-|aware +behaviour when using the empty capture \lua{()} (other captures work as +expected). For the interpretation of character classes in +\luatex{unicode.utf8} functions refer to the library sources at +\hyphenatedurl{http://luaforge.net/projects/sln}. The \lua{slnunicode} +library will be replaced by an internal \UNICODE\ library in a future +\LUATEX\ version. \blank The \lua{os} library has a few extra functions and variables: \startitemize +\item \luatex{os.selfdir} is a variable that holds the directory path +of \type{argv[0]}. For example: {\tt \directlua{tex.sprint(os.selfdir)}} +(present since 0.27.0). + \item \luatex{os.exec(commandline)} is a variation on \lua{os.execute}. The \type{commandline} can be either a single string or a single table. @@ -964,12 +1124,20 @@ system. These possible values are not yet fixed, and for \type{os.type} values \type{windows} and \type{msdos} The list for the type \type{unix} is more precise: \type{linux}, -\type{freebsd}, \type{openbsd}, \type{solaris}, \type{sunos} (pre-solaris), -\type{hpux}, \type{irix}, \type{macosx}, \type{bsd} (unknown, but \BSD|-|like), +\type{freebsd}, \type{kfreebsd} (since 0.51), \type{cygwin} (since +0.53), \type{openbsd}, \type{solaris}, \type{sunos} (pre-solaris), +\type{hpux}, \type{irix}, \type{macosx}, \type{gnu} (hurd), \type{bsd} (unknown, but \BSD|-|like), \type{sysv} (unknown, but \SYSV|-|like), \type{generic} (unknown). (\type{os.version} is planned as a future extension) +\item \luatex{os.uname()} +This function returns a table with specific operating system +information acquired at runtime. The keys in the returned table are +all string valued, and their names are: \type{sysname}, \type{machine}, +\type{release}, \type{version}, and \type{nodename}. + + \stopitemize In stock \LUA, many things depend on the current locale. In \LUATEX, we can't do @@ -1033,2082 +1201,7 @@ scripts to query and change a number of \TEX's internal variables, run various internal functions \TEX, and set up \LUATEX's hooks to execute \LUA\ code. -\section{The \luatex{tex} library} - -The \luatex{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 \tex{the} -\item It is a single token. -\item Some special others, see the list below -\stopitemize - -This excludes parameters that need extra arguments, like -\tex{the}\tex{scriptfont}. - -The subset comprising simple integer and dimension registers are -writable as well as readable (stuff like \tex{tracingcommands} and -\tex{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 (<string> n, ...) -tex.set ('global', <string> n, ...) -... = tex.get (<string> n) -\stopfunctioncall - -\subsubsection{Integer parameters} - -The integer parameters accept and return \LUA\ numbers. - -Read-write: - -\startcolumns[n=2] -\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.pdfadjustinterwordglue -tex.pdfadjustspacing -tex.pdfappendkern -tex.pdfcompresslevel -tex.pdfdecimaldigits -tex.pdfgamma -tex.pdfgentounicode -tex.pdfimageapplygamma -tex.pdfimagegamma -tex.pdfimagehicolor -tex.pdfimageresolution -tex.pdfinclusionerrorlevel -tex.pdfminorversion -tex.pdfobjcompresslevel -tex.pdfoutput -tex.pdfpagebox -tex.pdfpkresolution -tex.pdfprependkern -tex.pdfprotrudechars -tex.pdftracingfonts -tex.pdfuniqueresname -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 -\stopcolumns - -Read|-|only: - -\startcolumns[n=3] -\starttyping -tex.deadcycles -tex.insertpenalties -tex.parshape -tex.prevgraf -tex.spacefactor -\stoptyping -\stopcolumns - -\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: - -\startcolumns[n=3] -\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.pdfdestmargin -tex.pdfeachlinedepth -tex.pdfeachlineheight -tex.pdffirstlineheight -tex.pdfhorigin -tex.pdflastlinedepth -tex.pdflinkmargin -tex.pdfpageheight -tex.pdfpagewidth -tex.pdfpxdimen -tex.pdfthreadmargin -tex.pdfvorigin -tex.predisplaysize -tex.scriptspace -tex.splitmaxdepth -tex.vfuzz -tex.voffset -tex.vsize -\stoptyping -\stopcolumns - -Read|-|only: - -\startcolumns[n=3] -\starttyping -tex.pagedepth -tex.pagefilllstretch -tex.pagefillstretch -tex.pagefilstretch -tex.pagegoal -tex.pageshrink -tex.pagestretch -tex.pagetotal -tex.prevdepth -\stoptyping -\stopcolumns - -\subsubsection{Direction parameters} - -The direction parameters are read|-|only and return a \LUA\ string. - -\startcolumns[n=3] -\starttyping -tex.bodydir -tex.mathdir -tex.pagedir -tex.pardir -tex.textdir -\stoptyping -\stopcolumns - -\subsubsection{Glue parameters} - -All glue parameters are read|-|only and return a userdata object that -represents a \type{glue_spec} node. - -\startcolumns[n=3] -\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 -\stopcolumns - -\subsubsection{Muglue parameters} - -All muglue parameters are read|-|only and return a \LUA\ string. - -\startcolumns[n=3] -\starttyping -tex.medmuskip -tex.thickmuskip -tex.thinmuskip -\stoptyping -\stopcolumns - -\subsubsection{Tokenlist parameters} - -All tokenlist parameters are read|-|only and return a \LUA\ string. - -\startcolumns[n=3] -\starttyping -tex.errhelp -tex.everycr -tex.everydisplay -tex.everyeof -tex.everyhbox -tex.everyjob -tex.everymath -tex.everypar -tex.everyvbox -tex.output -tex.pdfpageattr -tex.pdfpageresources -tex.pdfpagesattr -tex.pdfpkmode -\stoptyping -\stopcolumns - -\subsection{Convert commands} - -All \quote{convert} commands are read|-|only and return a \LUA\ string. -The supported commands at this moment are: - -\startcolumns[n=2] -\starttyping -tex.AlephVersion -tex.Alephrevision -tex.OmegaVersion -tex.Omegarevision -tex.eTeXVersion -tex.eTeXrevision -tex.formatname -tex.jobname -tex.luatexrevision -tex.luatexdatestamp -tex.pdfnormaldeviate -tex.pdftexbanner -tex.pdftexrevision -tex.fontname(number) -tex.pdffontname(number) -tex.pdffontobjnum(number) -tex.pdffontsize(number) -tex.uniformdeviate(number) -tex.number(number) -tex.romannumeral(number) -tex.pdfpageref(number) -tex.pdfxformname(number) -tex.fontidentifier(number) -\stoptyping -\stopcolumns - -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). - -\subsection{Last item commands} - -All \quote{last item} commands are read|-|only and return a number. - -The supported commands at this moment are: - -\startcolumns[n=3] -\starttyping -tex.lastpenalty -tex.lastkern -tex.lastskip -tex.lastnodetype -tex.inputlineno -tex.badness -tex.pdftexversion -tex.pdflastobj -tex.pdflastxform -tex.pdflastximage -tex.pdflastximagepages -tex.pdflastannot -tex.pdflastxpos -tex.pdflastypos -tex.pdfrandomseed -tex.pdflastlink -tex.luatexversion -tex.Alephversion -tex.Omegaversion -tex.Alephminorversion -tex.Omegaminorversion -tex.eTeXminorversion -tex.eTeXversion -tex.currentgrouplevel -tex.currentgrouptype -tex.currentiflevel -tex.currentiftype -tex.currentifbranch -tex.pdflastximagecolordepth -\stoptyping -\stopcolumns - -\subsection{Attribute, count, dimension, skip and token registers} - -\TEX's attributes (\tex{attribute}), counters (\tex{count}), -dimensions (\tex{dimen}), skips (\tex{skip}) and token (\tex{toks}) -registers can be accessed and written to using two times five virtual -sub|-|tables of the \luatex{tex} table: - -\startcolumns[n=3] -\starttyping -tex.attribute -tex.count -tex.dimen -tex.skip -tex.toks -\stoptyping -\stopcolumns - -It is possible to use the names of relevant \tex{attributedef}, \tex{countdef}, -\tex{dimendef}, \tex{skipdef}, or \tex{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 \tex{countdef} (or \tex{attributedef}, or -\tex{dimendef}, or \tex{skipdef}, or \tex{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 \tex{the}\tex{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 (<number> n, <node> s) -tex.setskip (<string> s, <node> s) -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 - -In the function-based interface, it is possible to define values -globally by using the string \type{'global'} as the first function argument. - -\subsection{Box registers} - -The current dimensions of \tex{box} registers can be read and -altered using three other virtual sub|-|tables : - -\starttyping -tex.wd -tex.ht -tex.dp -\stoptyping - -Boxes are indexed by number or by name. In macro packages -\type {chardef} is normally used to refer to allocated box registers and -\LUATEX\ is able to deal with these symbolic names. - -The box size registers accept \LUA\ numbers (in scaled points) -or strings (with included dimension). The result is always a number -in scaled points. - -As an alternative to array addressing, there are also three sets of -accessor functions defined (like above): - -\startfunctioncall -tex.setboxwd(<number> n, <number> n) -tex.setboxwd('global',<number> n, <number> n) -<number> n = tex.getboxwd(<number> n) -\stopfunctioncall - -In the function-based interface, it is possible to define values -globally by using the string \type{'global'} as the first function argument. - -It is also possible to set and query actual boxes, using the node -interface as defined in the \luatex{node} library: - -\starttyping -tex.box -\stoptyping - -for array access, or - -\starttyping -tex.setbox(<number> n, <node> s) -tex.setbox('global', <number> n, <node> s) -<node> n = tex.getbox(<number> n) -\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 -\tex{box2} will be cleared by \TEX\ commands later on, the contents -of \tex{box0} becomes invalid as well. To prevent this from -happening, always use \luatex{node.copy_list()} unless you are -assigning to a temporary variable: - -\starttyping -tex.box[0] = node.copy_list(tex.box[2]) -\stoptyping - -\subsection{Math parameters} - -It is possible to set and query the internal math parameters -using: - -\startfunctioncall -tex.setmath(<string> n, <string> t, <number> n) -tex.setmath('global', <string> n, <string> t, <number> n) -<number> n = tex.getmath(<string> n, <string> t) -\stopfunctioncall - -As before an optional first parameter of \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 - - -\subsection{Special list heads} - -The virtual table \luatex{tex.lists} contains the set of internal -registers that keep track of building page lists. - - -\starttabulate[|lT|p|] -\NC \bf field \NC \bf description \NC \NR -\NC page_ins_head \NC circular list of pending insertions \NC \NR -\NC contrib_head \NC the recent contributions \NC \NR -\NC page_head \NC the page-so-far \NC \NR -%\NC temp_head \NC \NC \NR -\NC hold_head \NC used for held-over items for next page\NC \NR -\NC adjust_head \NC head of the current \tex{adjust} list \NC \NR -\NC pre_adjust_head \NC head of the current \tex{adjust pre} list\NC \NR -% \NC align_head \NC \NC \NR -\stoptabulate - -\subsection{Print functions} - -The \luatex{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 \tex{directlua}. - -The total amount of returnable text from a \tex{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{\luatex{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). This syntax was added in 0.36. - - -The optional parameter can be used to print the strings using the -catcode regime defined by \tex{catcodetable}~\type{n}. 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 \luatex{tex.print()} command in a -\tex{directlua} will not have the \tex{endlinechar} appended, all -others do. - -\subsubsection{\luatex{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] -\item \TEX\ does not switch to the \quote{new line} state, so - that leading spaces are not ignored. -\item No \tex{endlinechar} is inserted. -\item 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{inbetween} will be gobbled as a result of -the \quote{normal} scanning of \tex{relax}. -\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). This syntax was added in 0.36. - -\subsubsection{\luatex{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 is 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 \tex{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). This syntax was added in 0.36. - - -\subsection{Helper functions} - -\subsubsection{\luatex{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{\luatex{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. - -\subsubsection{\luatex{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). - -\subsection[luaprimitives]{Functions for dealing with primitives } - -\subsubsection{\luatex{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 -and actual primitive (it must be returned by one of the -\type{tex.extraprimitives()} calls explained above, 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. - -Second example: - -\starttyping - tex.enableprimitives('Omega',tex.extraprimitives ('omega')) -\stoptyping - -will define a whole series of csnames like \type{\Omegatextdir}, -\type{\Omegapardir}, etc., but it will stick with \type{\OmegaVersion} -instead of creating the doubly-prefixed \type{\OmegaOmegaVersion}. - -Starting with version 0.39.0 (and this is why the above two functions -are needed), \LUATEX\ in \type{--ini} mode contains only the \TEX82 -primitives and \type{\directlua}, no extra primitives {\bf at all}. - -So, if you want to have all the new functionality available using -their default names, as it is now, you will have to add - -\starttyping - \expandafter\ifx\csname directlua\endcsname \relax \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 runtime. - - -\subsubsection{\luatex{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 out_prim (a) - for _,n in pairs(tex.extraprimitives(a)) do - tex.print(n .. '\\hskip 4pt plus 5em') - end -end -\stopluacode - -\starttabulate[|l|p|] -\NC \bf name\NC \bf values \NC \NR -\NC tex \NC \ctxlua{out_prim('tex') } \NC \NR -\NC core \NC \ctxlua{out_prim('core') } \NC \NR -\NC etex \NC \ctxlua{out_prim('etex') } \NC \NR -\NC pdftex \NC \ctxlua{out_prim('pdftex') } \NC \NR -\NC omega \NC \ctxlua{out_prim('omega') } \NC \NR -\NC aleph \NC \ctxlua{out_prim('aleph') } \NC \NR -\NC luatex \NC \ctxlua{out_prim('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'}. - -Running \type{tex.extraprimitives()} will give you the complete list -of primitives that are not defined at \LUATEX\ 0.39.0 \type{-ini} -startup. It is exactly equivalent to \type{tex.extraprimitives('etex', -'pdftex', 'omega', 'aleph', 'luatex')} - -\subsubsection{\luatex{tex.primitives}} - -\startfunctioncall -<table> t = tex.primitives() -\stopfunctioncall - -This function returns a hash table listing all primitives that \LUATEX\ -knows about. The keys in the hash are primitives names, the values are -tables representing tokens (see~\in{section }[luatokens]). The third value -is always zero. - - - -\section[luatokens]{The \luatex{token} library} - -The \luatex{token} table contains interface functions to \TEX's -handling of tokens. These functions are most useful when combined with -the \luatex{token_filter} callback, but they could be used standalone -as well. - -A token is represented in \LUA\ as a small table. For the moment, this -table consists of three numeric entries: - -\starttabulate[|l|l|p|] -\NC \bf index\NC \bf meaning \NC \bf description \NC \NR -\NC 1 \NC command code \NC this is a value between~$0$ and~$130$ (approximately)\NC \NR -\NC 2 \NC command modifier \NC this is a value between~$0$ and~$2^{21}$ \NC \NR -\NC 3 \NC control sequence id \NC for commands that are not the result of control - sequences, like letters and characters, it is zero, - otherwise, it is a number pointing into the \quote - {equivalence table} \NC \NR -\stoptabulate - -\subsection{\luatex{token.get_next}} - -\startfunctioncall -token t = token.get_next() -\stopfunctioncall - -This fetches the next input token from the current input source, -without expansion. - -\subsection{\luatex{token.is_expandable}} - -\startfunctioncall -<boolean> b = token.is_expandable(token t) -\stopfunctioncall - -This tests if the token \type{t} could be expanded. - -\subsection{\luatex{token.expand}} - -\startfunctioncall -token.expand() -\stopfunctioncall - -If a token is expandable, this will expand one level of it, so that -the first token of the expansion will now be the next token to be read -by \luatex{token.get_next()}. - -\subsection{\luatex{token.is_activechar}} - -\startfunctioncall -<boolean> b = token.is_activechar(token t) -\stopfunctioncall - -This is a special test that is sometimes handy. Discovering whether -some control sequence is the result of an active character turned out -to be very hard otherwise. - -\subsection{\luatex{token.create}} - -\startfunctioncall -token t = token.create(<string> csname) -token t = token.create(<number> charcode) -token t = token.create(<number> charcode, <number> catcode) -\stopfunctioncall - -This is the token factory. If you feed it a string, then it is the -name of a control sequence (without leading backslash), and it will be -looked up in the equivalence table. - -If you feed it number, then this is assumed to be an input character, -and an optional second number gives its category code. This means it -is possible to overrule a character's category code, with a few -exceptions: the category codes~0 (escape), 9~(ignored), 13~(active), -14~(comment), and 15 (invalid) cannot occur inside a token. The values~0, 9, 14 -and~15 are therefore illegal as input to \luatex{token.create()}, and -active characters will be resolved immediately. - -Note: unknown string sequences and never defined active characters -will result in a token representing an \quote{undefined control sequence} -with a near|-|random name. It is {\em not} possible to define brand -new control sequences using \luatex{token.create}! - -\subsection{\luatex{token.command_name}} - -\startfunctioncall -<string> commandname = token.command_name(<token> t) -\stopfunctioncall - -This returns the name associated with the \quote{command} value of the token -in \LUATEX. There is not always a direct connection between these names and -primitives. For instance, all \tex{ifxxx} tests are grouped under -\type {if_fest}, and the \quote{command modifier} defines which test is to be run. - -\subsection{\luatex{token.command_id}} - -\startfunctioncall -<number> i = token.command_id(<string> commandname) -\stopfunctioncall - -This returns a number that is the inverse operation of the previous -command, to be used as the first item in a token table. - -\subsection{\luatex{token.csname_name}} - -\startfunctioncall -<string> csname = token.csname_name(<token> t) -\stopfunctioncall - -This returns the name associated with the \quote{equivalence table} value of -the token in \LUATEX. It returns the string value of the command used -to create the current token, or an empty string if there is no -associated control sequence. - -Keep in mind that there are potentially two control sequences that -return the same csname string: single character control sequences -and active characters have the same \quote{name}. - -\subsection{\luatex{token.csname_id}} - -\startfunctioncall -<number> i = token.csname_id(<string> csname) -\stopfunctioncall - -This returns a number that is the inverse operation of the previous -command, to be used as the third item in a token table. - -\section{The \luatex{node} library} - -The \luatex{node} library contains functions that facilitate dealing -with (lists of) nodes and their values. They allow you to create, alter, -copy, delete, and insert \LUATEX\ node objects, the core -objects within the typesetter. - -\LUATEX\ nodes are represented in \LUA\ as userdata with -the metadata type \luatex{luatex.node}. The various parts within -a node can be accessed using named fields. - -Each node has at least the three fields \type{next}, \type{id}, and -\type{subtype}: - -\startitemize[intro] - -\item The \type{next} field returns the userdata -object for the next node in a linked list of nodes, or -nil, if there is no next node. - -\item The \type{id} indicates \TEX's \quote{node type}. The field \type{id} -has a numeric value for efficiency reasons, but some of the library -functions also accept a string value instead of \type{id}. - -\item The \type{subtype} is another number. It often gives further information -about a node of a particular \type{id}, but it is most important when dealing -with \quote{whatsits}, because they are differentiated solely based on their -\type{subtype}. -\stopitemize - -The other available fields depend on the \type{id} (and for \quote{whatsits}, the -\type{subtype}) of the node. Further details on the various fields and their -meanings are given in~\in{chapter}[nodes]. - -Support for \type{unset} (alignment) nodes is partial: -they can be queried and modified from \LUA\ code, but not created. - -Nodes can be compared to each other, but: you are actually comparing -indices into the node memory. This means that equality tests can only -be trusted under very limited conditions. It will not work correctly -in any situation where one of the two nodes has been freed and|/|or -reallocated: in that case, there will be false positives. - -At the moment, memory management of nodes should still be done -explicitly by the user. Nodes are not \quote{seen} by the \LUA\ -garbage collector, so you have to call the node freeing functions -yourself when you are no longer in need of a node (list). Nodes form -linked lists without reference counting, so you have to be careful -that when control returns back to \LUATEX\ itself, you have not -deleted nodes that are still referenced from a \type{next} pointer -elsewhere, and that you did not create nodes that are referenced more -than once. - -There are statistics available with regards to the allocated node memory, -which can be handy for tracing. - -\subsection{Node handling functions} - -\subsubsection{\luatex{node.types}} - -\startfunctioncall -table t = node.types() -\stopfunctioncall - -This function returns an array that maps node id numbers to node type -strings, providing an overview of the possible top|-|level \type{id} -types. - -\subsubsection{\luatex{node.whatsits}} - -\startfunctioncall -table t = node.whatsits() -\stopfunctioncall - -\TEX's \quote{whatsits} all have the same \type{id}. The various subtypes -are defined by their \type{subtype}. The function is much like -\luatex{node.types}, except that it provides an array of \type{subtype} -mappings. - -\subsubsection{\luatex{node.id}} - -\startfunctioncall -<number> id = node.id(<string> type) -\stopfunctioncall - -This converts a single type name to its internal numeric -representation. - -\subsubsection{\luatex{node.subtype}} - -\startfunctioncall -<number> subtype = node.subtype(<string> type) -\stopfunctioncall - -This converts a single whatsit name to its internal numeric -representation (\type{subtype}). - -\subsubsection{\luatex{node.type}} - -\startfunctioncall -<string> type = node.type(<number> id) -\stopfunctioncall - -This converts a internal numeric representation to an external string -representation. - -\subsubsection{\luatex{node.fields}} - -\startfunctioncall -table t = node.fields(<number> id) -table t = node.fields(<number> id, <number> subtype) -\stopfunctioncall - -This function returns an array of valid field names for a particular -type of node. If you want to get the valid fields for a -\quote{whatsit}, you have to supply the second argument also. In other -cases, any given second argument will be silently ignored. - -This function accepts string \type{id} and \type{subtype} values as -well. - -\subsubsection{\luatex{node.has_field}} - -\startfunctioncall -<boolean> t = node.has_field(<node> n, <string> field) -\stopfunctioncall - -This function returns a boolean that is only true if \type{n} is -actually a node, and it has the field. - -\subsubsection{\luatex{node.new}} - -\startfunctioncall -<node> n = node.new(<number> id) -<node> n = node.new(<number> id, <number> subtype) -\stopfunctioncall - -Creates a new node. All of the new node's fields are initialized to -either zero or nil except for \type{id} and \type{subtype} (if -supplied). If you want to create a new whatsit, then the second -argument is required, otherwise it need not be present. As with all -node functions, this function creates a node on the \TEX\ level. - -This function accepts string \type{id} and \type{subtype} values as -well. - -\subsubsection{\luatex{node.free}} - -\startfunctioncall -node.free(<node> n) -\stopfunctioncall - -Removes the node \type{n} from \TEX's memory. Be careful: no checks -are done on whether this node is still pointed to from a register or some -\type{next} field: it is up to you to make sure that the internal data -structures remain correct. - -\subsubsection{\luatex{node.flush_list}} - -\startfunctioncall -node.flush_list(<node> n) -\stopfunctioncall - -Removes the node list \type{n} and the complete node list following -\type{n} from \TEX's memory. Be careful: no checks are done on whether -any of these nodes is still pointed to from a register or some -\type{next} field: it is up to you to make sure that the internal data -structures remain correct. - -\subsubsection{\luatex{node.copy}} - -\startfunctioncall -<node> m = node.copy(<node> n) -\stopfunctioncall - -Creates a deep copy of node \type{n}, including all nested lists as in -the case of a hlist or vlist node. Only the \type{next} field is not -copied. - -\subsubsection{\luatex{node.copy_list}} - -\startfunctioncall -<node> m = node.copy_list(<node> n) -\stopfunctioncall - -Creates a deep copy of the node list that starts at \type{n}. - -\subsubsection{\luatex{node.hpack}} - -\startfunctioncall -<node> h = node.hpack(<node> n) -<node> h = node.hpack(<node> n, <number> w, <string> info) -\stopfunctioncall - -This function creates a new hlist by packaging the list that begins at node -\type{n} into a horizontal box. With only a single argument, this box -is created using the natural width of its components. In the three -argument form, \type{info} must be either \type{additional} or -\type{exactly}, and \type{w} is the additional (\tex{hbox spread}) -or exact (\tex{hbox to}) width to be used. - -Caveat: at this moment, there can be unexpected side|-|effects to this -function, like updating some of the \tex{marks} and \tex{inserts}. -Also note that the content of \type{h} is the original node list -\type{n}: if you call \type{node.free(h)} you will also free the -node list itself, unless you explicitly set the \type{list} field -to \type{nil} beforehand. And in a similar way, calling -\type{node.free(n)} will invalidate \type{h} as well! - - -\subsubsection{\luatex{node.mlist_to_hlist}} - -\startfunctioncall -<node> h = node.mlist_to_hlist(<node> n, - <string> displaytype, <boolean> penalties) -\stopfunctioncall - -This runs the internal mlist to hlist conversion, converting the math list in -\type{n} into the horizontal list \type{h}. The interface is exactly the same as -for the callback \type{mlist_to_hlist}.) - -\subsubsection{\luatex{node.slide}} - -\startfunctioncall -<node> m = node.slide(<node> n) -\stopfunctioncall - -Returns the last node of the node list that starts at \type{n}. As a -side|-|effect, it also creates a reverse chain of \type{prev} pointers -between nodes. - -\subsubsection{\luatex{node.length}} - -\startfunctioncall -<number> i = node.length(<node> n) -<number> i = node.length(<node> n, <node> m) -\stopfunctioncall - -Returns the number of nodes contained in the node list that starts at -\type{n}. If \type{m} is also supplied it stops at \type{m} instead of -at the end of the list. The node \type{m} is not counted. - -\subsubsection{\luatex{node.count}} - -\startfunctioncall -<number> i = node.count(<number> id, <node> n) -<number> i = node.count(<number> id, <node> n, <node> m) -\stopfunctioncall - -Returns the number of nodes contained in the node list that starts at -\type{n} that have an matching \type{id} field. -If \type{m} is also supplied, counting stops at \type{m} instead of at -the end of the list. The node \type{m} is not counted. - -This function also accept string \type{id}'s. - -\subsubsection{\luatex{node.traverse}} - -\startfunctioncall -<node> t = node.traverse(<node> n) -\stopfunctioncall - -This is an iterator that loops over the node list that starts at \type{n}. - -\subsubsection{\luatex{node.traverse_id}} - -\startfunctioncall -<node> t = node.traverse_id(<number> id, <node> n) -\stopfunctioncall - -This is an iterator that loops over all the nodes in the list that -starts at \type{n} that have a matching \type{id} field. - -\subsubsection{\luatex{node.remove}} - -\startfunctioncall -<node> head, current = node.remove(<node> head, <node> current) -\stopfunctioncall - -This function removes the node \type{current} from the list following -\type{head}. It is your responsibility to make sure it is really part -of that list. The return values are the new \type{head} and -\type{current} nodes. The returned \type{current} is the -node in the calling argument, and is only passed back as a convenience -(its \type{next} field will be cleared). The returned \type{head} is -more important, because if the function is called with \type{current} -equal to \type{head}, it will be changed. - -\subsubsection{\luatex{node.insert_before}} - -\startfunctioncall -<node> head, new = node.insert_before(<node> head, <node> current, <node> new) -\stopfunctioncall - -This function inserts the node \type{new} before \type{current} into -the list following \type{head}. It is your responsibility to make sure -that \type{current} is really part of that list. The return values are -the (potentially mutated) \type{head} and the \type{new}, set up to -be part of the list (with correct \type{next} field). If \type{head} -is initially \type{nil}, it will become \type{new}. - -\subsubsection{\luatex{node.insert_after}} - -\startfunctioncall -<node> head, new = node.insert_after(<node> head, <node> current, <node> new) -\stopfunctioncall - -This function inserts the node \type{new} after \type{current} into -the list following \type{head}. It is your responsibility to make sure -that \type{current} is really part of that list. The return values are -the \type{head} and the \type{new}, set up to be part of the list -(with correct \type{next} field). If \type{head} is initially -\type{nil}, it will become \type{new}. - -\subsubsection{\luatex{node.first_character}} - -\startfunctioncall -<node> n = node.first_character(<node> n) -<node> n = node.first_character(<node> n, <node> m) -\stopfunctioncall - -Returns the first node that is a glyph node with a subtype indicating -it is a character, or \type{nil}. - -\subsubsection{\luatex{node.ligaturing}} - -\startfunctioncall -<node> h, <node> t, <boolean> success = node.ligaturing(<node> n) -<node> h, <node> t, <boolean> success = node.ligaturing(<node> n, <node> m) -\stopfunctioncall - -Apply \TEX-style ligaturing to the specified nodelist. The tail node -\type{m} is optional. The two returned nodes \type{h} and \type{t} are -the new head and tail (both \type{n} and \type{m} can change into -a new ligature). - -\subsubsection{\luatex{node.kerning}} - -\startfunctioncall -<node> h, <node> t, <boolean> success = node.kerning(<node> n) -<node> h, <node> t, <boolean> success = node.kerning(<node> n, <node> m) -\stopfunctioncall - -Apply \TEX|-|style kerning to the specified nodelist. The tail node -\type{m} is optional. The two returned nodes \type{h} and \type{t} are -the head and tail (either one of these can be an inserted kern node, -because special kernings with word boundaries are possible). - -\subsubsection{\luatex{node.unprotect_glyphs}} - -\startfunctioncall -node.unprotect_glyphs(<node> n) -\stopfunctioncall - -Subtracts 256 from all glyph node subtypes. This and the next -function are helpers to convert from \type{characters} to -\type{glyphs} during node processing. - -\subsubsection{\luatex{node.protect_glyphs}} - -\startfunctioncall -node.protect_glyphs(<node> n) -\stopfunctioncall - -Adds 256 to all glyph node subtypes in the node list starting at -\type{n}, except that if the value is 1, it adds only 255. The special -handling of 1 means that \type{characters} will become \type{glyphs} -after subtraction of 256. - -\subsubsection{\luatex{node.last_node}} - -\startfunctioncall -<node> n = node.last_node() -\stopfunctioncall - -This function pops the last node from \TEX's \quote{current list}. -It returns that node, or \type{nil} if the current list is empty. - -\subsubsection{\luatex{node.write}} - -\startfunctioncall -node.write(<node> n) -\stopfunctioncall - -This is an experimental function that will append a node list to -\TEX's \quote {current list} (the node list is not deep-copied -any more since version 0.38). There is no error checking yet! - -\subsection{Attribute handling} - -Attributes appear as linked list of userdata objects in the -\type{attr} field of individual nodes. They can be handled -individually, but it is much safer and more efficient to use the -dedicated functions associated with them. - -\subsubsection{\luatex{node.has_attribute}} - -\startfunctioncall -<number> v = node.has_attribute(<node> n, <number> id) -<number> v = node.has_attribute(<node> n, <number> id, <number> val) -\stopfunctioncall - -Tests if a node has the attribute with number \type{id} set. If -\type{val} is also supplied, also tests if the value matches \type{val}. -It returns the value, or, if no match is found, nil. - -\subsubsection{\luatex{node.set_attribute}} - -\startfunctioncall -node.set_attribute(<node> n, <number> id, <number> val) -\stopfunctioncall - -Sets the attribute with number \type{id} to the value -\type{val}. Duplicate assignments are ignored. {\em [needs explanation]} - -\subsubsection{\luatex{node.unset_attribute}} - -\startfunctioncall -<number> v = node.unset_attribute(<node> n, <number> id, <number> val) -<number> v = node.unset_attribute(<node> n, <number> id) -\stopfunctioncall - -Unsets the attribute with number \type{id}. If \type{val} is also supplied, -it will only perform this operation if the value matches \type{val}. -Missing attributes or attribute|-|value pairs are ignored. - -If the attribute was actually deleted, returns its old -value. Otherwise, returns nil. - -\section{The \luatex{texio} library} - -This library takes care of the low|-|level I/O interface. - -\subsection{Printing functions} - -\subsubsection{\luatex{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 -\tex{batchmode} is in effect, it writes only to the log, -otherwise it writes to the log and the terminal. - -The optional \type{target} can be one of three possibilities: -\type{term}, \type{log} or \type {term and log}. - -Note: If several strings are given, and if the first of these strings -is or might be one of the targets above, the \type{target} must be -specified explicitly to prevent \LUA\ from interpreting the first -string as the target. - -\subsubsection{\luatex{texio.write_nl}} - -\startfunctioncall -texio.write_nl(<string> target, <string> s, ...) -texio.write_nl(<string> s, ...) -\stopfunctioncall - -This function behaves like \luatex{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. - -\section{The \luatex{pdf} library} - -This table contains the current \type{h} and \type{v} values that -define the location on the output page. The values can be queried -and set using scaled points as units. - -\starttyping -pdf.v -pdf.h -\stoptyping - -The associated function calls are - -\startfunctioncall -pdf.setv(<number> n) -<number> n = pdf.getv() -pdf.seth(<number> n) -<number> n = pdf.geth() -\stopfunctioncall - -It also holds a print function to write stuff to the \PDF\ document -that can be used from within a \tex{latelua} argument. This function -is not to be used inside \tex{directlua} unless you know {\it -exactly} what you are doing. - -\subsubsubject{\luatex{pdf.print}} - -\startfunctioncall -pdf.print(<string> s) -pdf.print(<string> type, <string> s) -\stopfunctioncall - -The optional parameter can be used to mimic the behavior of -\tex{pdfliteral}: the \type{type} is \type{direct} or \type{page}. - -\section{The \luatex{img} library} - -The \type{img} library can be used as an alternative to -\tex{pdfximage} and \tex{pdfrefximage}, and the associated \quote {satellite} -commands like \tex{pdfximagebbox}. -Image objects can also be used within virtual fonts -via the \type{image} command listed in~\in{section}[virtualfonts]. - -\subsubsubject{\luatex{img.new}} - -\startfunctioncall -<image> var = img.new() -<image> var = img.new(image_spec) -\stopfunctioncall - -This function creates a userdata object of type \quote {image}. The -\type{image_spec} argument is optional. If it is given, it must be -a table, and that table must contain a \type{filename} key. A number of -other keys can also be useful, these are explained below. - -You can either say - -\starttyping -a=img.new() -\stoptyping - -followed by - -\starttyping -a.filename="foo.png" -\stoptyping - -or you can put the file name (and some or all of the other keys) -into a table directly, like so: - -\starttyping -a=img.new{filename='foo.pdf',page=1} -\stoptyping - -The generated \type{<image>} userdata object allows access to a set of -user|-|specified values as well as a set of values that are normally -filled in and updated automatically by \LUATEX\ itself. Some of those -are derived from the actual image file, others are updated to reflect -the \PDF\ output status of the object. - -There is one required user-specified field: the file name -(\type{filename}). It can optionally be augmented by the requested -image dimensions (\type{width}, \type{depth}, \type{height}), -user-specified image attributes (\type{attr}), the requested \PDF\ page -identifier (\type{page}), the requested boundingbox (\type{pagebox}) -for \PDF\ inclusion, the requested color space object (\type{colorspace}). - -The function \type{img.new} does not access the actual image file, it -just creates the \type{<image>} userdata object and initializes some -memory structures. The \type{<image>} object and its internal -structures are automatically garbage collected. - -Once the image is scanned, all the values in the -\type{<image>} become frozen, and you cannot change them any more. - -\subsubsubject{\luatex{img.keys}} - -\startfunctioncall -<table> keys = img.keys() -\stopfunctioncall - -This function returns a list of all the possible \type{image_spec} -keys, both user-supplied and automatic ones. - -% hahe: i need to add r/w ro column... -\starttabulate[|l|l|p|] -\NC \bf field name\NC \bf type \NC description \NC \NR -\NC depth \NC number \NC the image depth for \LUATEX\ (in scaled points)\NC \NR -\NC height \NC number \NC the image height for \LUATEX\ (in scaled points)\NC \NR -\NC width \NC number \NC the image width for \LUATEX\ (in scaled points)\NC \NR -\NC transform \NC number \NC the image transform, integer number 0..7\NC \NR -\NC attr \NC string \NC the image attributes for \LUATEX \NC \NR -\NC filename \NC string \NC the image file name \NC \NR -\NC stream \NC string \NC the raw stream data for an \type{/Xobject} \type{/Form} object\NC \NR -\NC page \NC ?? \NC the identifier for the requested image - page (type is number or string, - default is the number 1)\NC \NR -\NC pagebox \NC string \NC the requested bounding box, - one of \type {none}, \type {media}, \type {crop}, \type {bleed}, \type {trim}, \type {art} \NC \NR -\NC bbox \NC table \NC table with 4 boundingbox dimensions \type{llx}, \type{lly}, - \type{urx}, and \type{ury} overruling the \type{pagebox} entry\NC \NR -\NC filepath \NC string \NC the full (expanded) file name of the image \NC \NR -\NC colordepth \NC number \NC the number of bits used by the color space \NC \NR -\NC colorspace \NC number \NC the color space object number \NC \NR -\NC imagetype \NC string \NC one of \type {pdf}, \type {png}, \type {jpg}, \type {jbig2}, or \type{nil} \NC \NR -\NC objnum \NC number \NC the \PDF\ image object number \NC \NR -\NC index \NC number \NC the \PDF\ image name suffix \NC \NR -\NC pages \NC number \NC the total number of available pages \NC \NR -\NC xsize \NC number \NC the natural image width \NC \NR -\NC ysize \NC number \NC the natural image height \NC \NR -\NC xres \NC number \NC the horizontal natural image resolution (in \DPI) \NC \NR -\NC yres \NC number \NC the vertical natural image resolution (in \DPI) \NC \NR -\stoptabulate - -A running (undefined) dimension in \type{width}, \type{height}, or \type{depth} is -represented as \type{nil} in \LUA, so if you want to load an image at -its \quote {natural} size, you do not have to specify any of those three fields. - -The \type{stream} parameter allows to fabricate an \type{/XObject} \type{/Form} -object from a string giving the stream contents, -e.\,g., for a filled rectangle: - -\startfunctioncall -a.stream = "0 0 20 10 re f" -\stopfunctioncall - -When writing the image, an \type{/Xobject} \type{/Form} object is created, -like with embedded \PDF\ file writing. The object is written out only once. -The \type{stream} key requires that also the \type{bbox} table is given. -The \type{stream} key conflicts with the \type{filename} key. -The \type{transform} key works as usual also with \type{stream}. - -The \type{bbox} key needs a table with four boundingbox values, e.\,g.: - -\startfunctioncall -a.bbox = {"30bp", 0, "225bp", "200bp"} -\stopfunctioncall - -This replaces and overrules any given \type{pagebox} value; -with given \type{bbox} the box dimensions coming with an embedded \PDF\ file -are ignored. -The \type{xsize} and \type{ysize} dimensions are set accordingly, -when the image is scaled. -The \type{bbox} parameter is ignored for non-\PDF\ images. - -The \type{transform} allows to mirror and rotate the image in steps of 90~deg. -The default value~0 gives an unmirrored, unrotated image. -Values 1|--|3 give counterclockwise rotation by 90, 180, or 270~degrees, -whereas with values 4|--|7 the image is first mirrored -and then rotated counterclockwise by 90, 180, or 270~degrees. -The \type{transform} operation gives the same visual result -as if you would externally preprocess the image by a graphics tool -and then use it by \LUATEX. -If a \PDF\ file to be embedded already contains a \type{/Rotate} specification, -the rotation result is the combination of the \type{/Rotate} rotation -followed by the \type{transform} operation. - -\subsubsubject{\luatex{img.scan}} - -\startfunctioncall -<image> var = img.scan(<image> var) -<image> var = img.scan(image_spec) -\stopfunctioncall - -When you say \type{img.scan(a)} for a new image, the file is scanned, -and variables such as \type{xsize}, \type{ysize}, image \type{type}, number of -\type{pages}, and the resolution are extracted. Each of the \type{width}, -\type{height}, \type{depth} fields are set up according to the image dimensions, -if they were not given an explicit value already. -An image file will never be scanned more than once for a given image variable. -With all subsequent \type{img.scan(a)} calls only the dimensions are again -set up (if they have been changed by the user in the meantime). - -For ease of use, you can do right-away a - -\starttyping -<image> a = img.scan { filename = "foo.png" } -\stoptyping - -without a prior \type{img.new}. - -Nothing is written yet at this point, so you can do \type{a=img.scan}, -retrieve the available info like image width and height, and then -throw away \type{a} again by saying \type{a=nil}. In that case no -image object will be reserved in the PDF, and the used memory will be -cleaned up automatically. - -\subsubsubject{\luatex{img.copy}} - -\startfunctioncall -<image> var = img.copy(<image> var) -<image> var = img.copy(image_spec) -\stopfunctioncall - -If you say \type{a = b}, then both variables point to the same -\type{<image>} object. if you want to write out an image with -different sizes, you can do a \type{b=img.copy(a)}. - -Afterwards, \type{a} and \type{b} still reference the same actual -image dictionary, but the dimensions for \type{b} can now be changed -from their initial values that were just copies from \type{a}. - -% Hartmut, I don't know if this makes sense. An example of what -% can, and what cannot be changed would be helpful. -% -- will think about it... - -\subsubsubject{\luatex{img.write}} - -\startfunctioncall -<image> var = img.write(<image> var) -<image> var = img.write(image_spec) -\stopfunctioncall - -By \type{img.write(a)} a \PDF\ object number is allocated, -and a whatsit node of subtype \type{pdf_refximage} is generated -and put into the output list. -By this the image \type{a} is placed into the page stream, -and the image file is written out into an image stream object -after the shipping of the current page is finished. - -Again you can do a terse call like - -\starttyping -img.write { filename = "foo.png" } -\stoptyping - -The \type{<image>} variable is returned in case you want it for later -processing. - -\subsubsubject{\luatex{img.immediatewrite}} - -\startfunctioncall -<image> var = img.immediatewrite(<image> var) -<image> var = img.immediatewrite(image_spec) -\stopfunctioncall - -By \type{img.immediatewrite(a)} a \PDF\ object number is -allocated, and the image file for image \type{a} is written out -immediately into the \PDF\ file as an image stream object (like -with \tex{immediate}\tex{pdfximage}). The object number of the image -stream dictionary is then available by the \type{objnum} key. No -\type{pdf_refximage} whatsit node is generated. You will need an -\luatex{img.write(a)} or \luatex{img.node(a)} call to let the -image appear on the page, or reference it by another trick; else -you will have a dangling image object in the \PDF\ file. - -Also here you can do a terse call like - -\starttyping -a = img.immediatewrite { filename = "foo.png" } -\stoptyping - -The \type{<image>} variable is returned and you will most likely need it. - -\subsubsubject{\luatex{img.node}} - -\startfunctioncall -<node> n = img.node(<image> var) -<node> n = img.node(image_spec) -\stopfunctioncall - -This function allocates a \PDF\ object number and returns a -whatsit node of subtype \type{pdf_refximage}, filled with the -image parameters \type{width}, \type{height}, \type{depth}, and -\type{objnum}. Also here you can do a terse call like: - -\starttyping -n = img.node { filename = "foo.png" } -\stoptyping - -This example outputs an image: - -\starttyping -node.write(img.node{filename="foo.png"}) -\stoptyping - -\subsubsubject{\luatex{img.types}} - -\startfunctioncall -<table> types = img.types() -\stopfunctioncall - -This function returns a list with the supported image file type names, -currently these are \type {pdf}, \type {png}, \type {jpg}, and \type {jbig2}. - -\subsubsubject{\luatex{img.boxes}} - -\startfunctioncall -<table> boxes = img.boxes() -\stopfunctioncall - -This function returns a list with the supported \PDF\ page box names, -currently these are \type {media}, \type {crop}, \type {bleed}, \type {trim}, and \type {art} -(all in lowercase letters). - - -\section{The \luatex{mplib} library} - -The \MP\ library interface registers itself in the table \type{mplib}. It -is based on \MPLIB\ version \ctxlua{tex.sprint(mplib.version())}. - -\subsection{\luatex{mplib.new}} - -To create a new \METAPOST\ instance, call - -\startfunctioncall -<mpinstance> mp = mplib.new({...}) -\stopfunctioncall - -This creates the \type{mp} instance object. The argument hash can have a number of -different fields, as follows: - -\starttabulate[|lT|l|p|p|] -\NC \ssbf name \NC \bf type \NC \bf description \NC \bf default \NC\NR -\NC error_line \NC number \NC error line width \NC 79 \NC\NR -\NC print_line \NC number \NC line length in ps output \NC 100\NC\NR -\NC main_memory \NC number \NC total memory size \NC 5000\NC\NR -\NC hash_size \NC number \NC hash size \NC 16384 \NC\NR -\NC param_size \NC number \NC max. active macro parameters\NC 150\NC\NR -\NC max_in_open \NC number \NC max. input file nestings \NC 10\NC\NR -\NC random_seed \NC number \NC the initial random seed \NC variable\NC\NR -\NC interaction \NC string \NC the interaction mode, one of -\type {batch}, \type {nonstop}, \type {scroll}, \type {errorstop} \NC \type {errorstop}\NC\NR -\NC ini_version \NC boolean \NC the --ini switch \NC true \NC\NR -\NC mem_name \NC string \NC \type {--mem} \NC \type {plain} \NC\NR -\NC job_name \NC string \NC \type {--jobname} \NC \type {mpout} \NC\NR -\NC find_file \NC function \NC a function to find files \NC only local files\NC\NR -\stoptabulate - -The \type{find_file} function should be of this form: - -\starttyping -<string> found = finder (<string> name, <string> mode, <string> type) -\stoptyping - -with: - -\starttabulate[|lT|l|p|] -\NC \bf name \NC \bf the requested file \NC \NR -\NC mode \NC the file mode: \type {r} or \type {w} \NC \NR -\NC type \NC the kind of file, one of: \type {mp}, \type {mem}, \type {tfm}, \type {map}, \type {pfb}, \type {enc} \NC \NR -\stoptabulate - -Return either the full pathname of the found file, or \type{nil} if -the file cannot be found. - -\subsection{\luatex{mp:statistics}} - -You can request statistics with: - -\startfunctioncall -<table> stats = mp:statistics() -\stopfunctioncall - -This function returns the vital statistics for an \MPLIB\ instance. There are four -fields, giving the maximum number of used items in each of the four -statically allocated object classes: - -\starttabulate[|lT|l|p|] -\NC main_memory \NC number \NC memory size \NC\NR -\NC hash_size \NC number \NC hash size\NC\NR -\NC param_size \NC number \NC simultaneous macro parameters\NC\NR -\NC max_in_open \NC number \NC input file nesting levels\NC\NR -\stoptabulate - -\subsection{\luatex{mp:execute}} - -You can ask the \METAPOST\ interpreter to run a chunk of code by calling - -\startfunctioncall -local rettable = mp:execute('metapost language chunk') -\stopfunctioncall - -for various bits of \METAPOST\ language input. Be sure to check the -\type{rettable.status} (see below) because when a fatal \METAPOST\ -error occurs the \MPLIB\ instance will become unusable thereafter. - -Generally speaking, it is best to keep your chunks small, but beware -that all chunks have to obey proper syntax, like each of them is a -small file. For instance, you cannot split a single statement over -multiple chunks. - -In contrast with the normal standalone \type{mpost} command, there is -{\em no\/} implied \quote{input} at the start of the first chunk. - -\subsection{\luatex{mp:finish}} - -\startfunctioncall -local rettable = mp:finish() -\stopfunctioncall - -If for some reason you want to stop using an \MPLIB\ instance while -processing is not yet actually done, you can call \type{mp:finish}. -Eventually, used memory will be freed and open files will be closed by -the \LUA\ garbage collector, but an explicit \type{mp:finish} is the -only way to capture the final part of the output streams. - -\subsection{Result table} - -The return value of \type{mp:execute} and \type{mp:finish} is a table -with a few possible keys (only \type {status} is always guaranteed to be present). - -\starttabulate[|l|l|p|] -\NC log \NC string \NC output to the \quote {log} stream \NC \NR -\NC term \NC string \NC output to the \quote {term} stream \NC \NR -\NC error \NC string \NC output to the \quote {error} stream (only used for \quote {out of memory})\NC \NR -\NC status \NC number \NC the return value: 0=good, 1=warning, 2=errors, 3=fatal error \NC \NR -\NC fig \NC table \NC an array of generated figures (if any)\NC \NR -\stoptabulate - -When \type{status} equals~3, you should stop using this \MPLIB\ instance -immediately, it is no longer capable of processing input. - -If it is present, each of the entries in the \type{fig} array is a -userdata representing a figure object, and each of those has a number of -object methods you can call: - -\starttabulate[|l|l|p|] -\NC boundingbox \NC function \NC returns the bounding box, as an array of 4 values\NC \NR -\NC postscript \NC function \NC return a string that is the ps output of the \type{fig}. - this function accepts two optional integer arguments for - specifying the values of \type{prologues} (first argument) - and \type{procset} (second argument)\NC \NR -\NC svg \NC function \NC return a string that is the svg output of the \type{fig}. - this function accepts an optional integer arguments for - specifying the value of \type{prologues}\NC \NR -\NC objects \NC function \NC returns the actual array of graphic objects in this \type{fig} \NC \NR -\NC copy_objects \NC function \NC returns a deep copy of the array of graphic objects in this \type{fig} \NC \NR -\NC filename \NC function \NC the filename this \type{fig}'s \POSTSCRIPT\ output - would have written to in standalone mode\NC \NR -\NC width \NC function \NC the \type{charwd} value \NC \NR -\NC height \NC function \NC the \type{charht} value \NC \NR -\NC depth \NC function \NC the \type{chardp} value \NC \NR -\NC italcorr \NC function \NC the \type{charit} value \NC \NR -\NC charcode \NC function \NC the (rounded) \type{charcode} value \NC \NR -\stoptabulate - -{\bf NOTE:} you can call \type{fig:objects()} only once for any one \type{fig} object! - -When the boundingbox represents a \quote {negated rectangle}, i.e.\ when the first set -of coordinates is larger than the second set, the picture is empty. - -Graphical objects come in various types that each have a different list of -accessible values. The types are: \type{fill}, \type{outline}, \type{text}, -\type{start_clip}, \type{stop_clip}, \type{start_bounds}, \type{stop_bounds}, \type{special}. - -There is helper function (\type{mplib.fields(obj)}) to get the list of -accessible values for a particular object, but you can just as easily -use the tables given below). - -All graphical objects have a field \type{type} that gives the object -type as a string value, that not explicit mentioned in the tables. In -the following, \type{number}s are \POSTSCRIPT\ points represented as -a floating point number, unless stated otherwise. Field values that -are of \type{table} are explained in the next section. - -\subsubsection{fill} - -\starttabulate[|l|l|p|] -\NC path \NC table \NC the list of knots \NC \NR -\NC htap \NC table \NC the list of knots for the reversed trajectory \NC \NR -\NC pen \NC table \NC knots of the pen \NC \NR -\NC color \NC table \NC the object's color \NC \NR -\NC linejoin \NC number \NC line join style (bare number)\NC \NR -\NC miterlimit \NC number \NC miterlimit\NC \NR -\NC prescript \NC string \NC the prescript text \NC \NR -\NC postscript \NC string \NC the postscript text \NC \NR -\stoptabulate - -The entries \type{htap} and \type{pen} are optional. - -There is helper function (\type{mplib.pen_info(obj)}) that returns -a table containing a bunch of vital characteristics of the used pen -(all values are floats): - -\starttabulate[|l|l|p|] -\NC width \NC number \NC width of the pen\NC \NR -\NC rx \NC number \NC $x$ scale \NC \NR -\NC sx \NC number \NC $xy$ multiplier \NC \NR -\NC sy \NC number \NC $yx$ multiplier \NC \NR -\NC ry \NC number \NC $y$ scale \NC \NR -\NC tx \NC number \NC $x$ offset \NC \NR -\NC ty \NC number \NC $y$ offset \NC \NR -\stoptabulate - -\subsubsection{outline} - -\starttabulate[|l|l|p|] -\NC path \NC table \NC the list of knots \NC \NR -\NC pen \NC table \NC knots of the pen \NC \NR -\NC color \NC table \NC the object's color \NC \NR -\NC linejoin \NC number \NC line join style (bare number)\NC \NR -\NC miterlimit \NC number \NC miterlimit \NC \NR -\NC linecap \NC number \NC line cap style (bare number)\NC \NR -\NC dash \NC table \NC representation of a dash list\NC \NR -\NC prescript \NC string \NC the prescript text \NC \NR -\NC postscript \NC string \NC the postscript text \NC \NR -\stoptabulate - -The entry \type{dash} is optional. - -\subsubsection{text} - -\starttabulate[|l|l|p|] -\NC text \NC string \NC the text \NC \NR -\NC font \NC string \NC font tfm name \NC \NR -\NC dsize \NC number \NC font size\NC \NR -\NC color \NC table \NC the object's color \NC \NR -\NC width \NC number \NC \NC \NR -\NC height \NC number \NC \NC \NR -\NC depth \NC number \NC \NC \NR -\NC transform \NC table \NC a text transformation \NC \NR -\NC prescript \NC string \NC the prescript text \NC \NR -\NC postscript \NC string \NC the postscript text \NC \NR -\stoptabulate - -\subsubsection{special} - -\starttabulate[|l|l|p|] -\NC prescript \NC string \NC special text \NC \NR -\stoptabulate - -\subsubsection{start_bounds, start_clip} - -\starttabulate[|l|l|p|] -\NC path \NC table \NC the list of knots \NC \NR -\stoptabulate - -\subsubsection{stop_bounds, stop_clip} - -Here are no fields available. - -\subsection{Subsidiary table formats} - -\subsubsection{Paths and pens} - -Paths and pens (that are really just a special type of paths as far as -\MPLIB\ is concerned) are represented by an array where each entry -is a table that represents a knot. - -\starttabulate[|lT|l|p|] -\NC left_type \NC string \NC when present: 'endpoint', but usually absent \NC \NR -\NC right_type \NC string \NC like \type{left_type}\NC \NR -\NC x_coord \NC number \NC X coordinate of this knot\NC \NR -\NC y_coord \NC number \NC Y coordinate of this knot\NC \NR -\NC left_x \NC number \NC X coordinate of the precontrol point of this knot\NC \NR -\NC left_y \NC number \NC Y coordinate of the precontrol point of this knot\NC \NR -\NC right_x \NC number \NC X coordinate of the postcontrol point of this knot\NC \NR -\NC right_y \NC number \NC Y coordinate of the postcontrol point of this knot\NC \NR -\stoptabulate - -There is one special case: pens that are (possibly transformed) -ellipses have an extra string-valued key \type{type} with value -\type{elliptical} besides the array part containing the knot list. - -\subsubsection{Colors} - -A color is an integer array with 0, 1, 3 or 4 values: - -\starttabulate[|l|l|p|] -\NC 0 \NC marking only \NC no values \NC\NR -\NC 1 \NC greyscale \NC one value in the range $(0,1)$, \quote {black} is $0$ \NC\NR -\NC 3 \NC \RGB \NC three values in the range $(0,1)$, \quote {black} is $0,0,0$ \NC\NR -\NC 4 \NC \CMYK \NC four values in the range $(0,1)$, \quote {black} is $0,0,0,1$ \NC\NR -\stoptabulate - -If the color model of the internal object was \type{uninitialized}, then -it was initialized to the values representing \quote {black} in the colorspace -\type{defaultcolormodel} that was in effect at the time of the \type{shipout}. - -\subsubsection{Transforms} - -Each transform is a six-item array. - -\starttabulate[|l|l|p|] -\NC 1 \NC number \NC represents x \NC\NR -\NC 2 \NC number \NC represents y \NC\NR -\NC 3 \NC number \NC represents xx \NC\NR -\NC 4 \NC number \NC represents yx \NC\NR -\NC 5 \NC number \NC represents xy \NC\NR -\NC 6 \NC number \NC represents yy \NC\NR -\stoptabulate - -Note that the translation (index 1 and 2) comes first. This differs -from the ordering in \POSTSCRIPT, where the translation comes last. - -\subsubsection{Dashes} - -Each \type{dash} is two-item hash, using the same model as \POSTSCRIPT\ -for the representation of the dashlist. \type{dashes} is an array of -\quote {on} and \quote {off}, values, and \type{offset} is the phase of the pattern. - -\starttabulate[|l|l|p|] -\NC dashes \NC hash \NC an array of on-off numbers \NC\NR -\NC offset \NC number \NC the starting offset value \NC\NR -\stoptabulate - -\subsection{Character size information} - -These functions find the size of a glyph in a defined font. The -\type{fontname} is the same name as the argument to \type{infont}; -the \type{char} is a glyph id in the range 0 to 255; the returned -\type{w} is in AFM units. - -\subsubsection{\luatex{mp.char_width}} - -\startfunctioncall -<number> w = mp.char_width(<string> fontname, <number> char) -\stopfunctioncall - -\subsubsection{\luatex{mp.char_height}} - -\startfunctioncall -<number> w = mp.char_height(<string> fontname, <number> char) -\stopfunctioncall - -\subsubsection{\luatex{mp.char_depth}} - -\startfunctioncall -<number> w = mp.char_depth(<string> fontname, <number> char) -\stopfunctioncall - +The following sections are in alphabetical order. \section{The \luatex{callback} library} @@ -3157,6 +1250,9 @@ If the callback is not set, \luatex{callback.find} returns \type{nil}. \subsection{File discovery callbacks} +The behavior documented in this subsection is considered stable in the +sense that there will not be backward-incompatible changes any more. + \subsubsection{\luatex{find_read_file} and \luatex{find_write_file}} Your callback function should have the following conventions: @@ -3303,6 +1399,9 @@ is considered the name of a valid file by your operating system. \subsection[iocallback]{File reading callbacks} +The behavior documented in this subsection is considered stable in the +sense that there will not be backward-incompatible changes any more. + \subsubsection{\luatex{open_read_file}} Your callback function should have the following conventions: @@ -3438,6 +1537,26 @@ that. This callback does not replace any internal code. +\subsubsection{\luatex{process_output_buffer} (0.43)} + +This callback allows you to change the contents of the line output +buffer just before \LUATEX\ actually starts writing it to a file as the +result of a \tex{write} command. It is only called for output to an +actual file (that is, excluding the log, the terminal, and \tex{write18} +calls). + +\startfunctioncall +function(<string> buffer) + return <string> adjusted_buffer +end +\stopfunctioncall + +If you return \type{nil}, \LUATEX\ will pretend like your callback +never happened. You can gain a small amount of processing time from +that. + +This callback does not replace any internal code. + \subsubsection{\luatex{token_filter}} This callback allows you to replace the way \LUATEX\ fetches @@ -3594,7 +1713,8 @@ horizontal mode material. Math items and line boxes are ignored at the moment. \startfunctioncall -function(<node> head, <string> groupcode, <number> size, <string> packtype) +function(<node> head, <string> groupcode, <number> size, + <string> packtype [, <string> direction]) return true | false | <node> newhead end \stopfunctioncall @@ -3604,6 +1724,10 @@ The \type{packtype} is either \type{additional} or \type{exactly}. If argument. If \type{exactly}, then the \type{size} is a \tex{hbox to ...}. In both cases, the number is in scaled points. +The \type{direction} is either one of the three-letter direction specifier +strings, or nil (added in 0.45). + + This callback does not replace any internal code. \subsubsection{\luatex{vpack_filter}} @@ -3616,7 +1740,8 @@ the fact that it is called at different moments, there is an extra variable that matches \TEX's \tex{maxdepth} setting. \startfunctioncall -function(<node> head, <string> groupcode, <number> size, <string> packtype, <number> maxdepth) +function(<node> head, <string> groupcode, <number> size, <string> + packtype, <number> maxdepth [, <string> direction]) return true | false | <node> newhead end \stopfunctioncall @@ -3629,7 +1754,8 @@ This callback is called when \TEX\ is ready to start boxing the box 255 for \tex{output}. \startfunctioncall -function(<node> head, <string> groupcode, <number> size, <string> packtype, <number> maxdepth) +function(<node> head, <string> groupcode, <number> size, <string> packtype, + <number> maxdepth [, <string> direction]) return true | false | <node> newhead end \stopfunctioncall @@ -3813,427 +1939,6 @@ later \LUA\ code to use. Setting this callback to \type{false} is pointless as it will prevent font loading completely but will nevertheless generate errors. -\section{The \luatex{lua} library} - -This library contains one read|-|only item: - -\starttyping -<string> s = lua.version -\stoptyping - -This returns a \LUATEX\ version identifier string. The value is -currently \directlua {tex.print('lua.version')}, but it is soon to be -replaced by something more elaborate. - -\subsection{\LUA\ bytecode registers} - -\LUA\ registers can be used to communicate \LUA\ functions across \LUA\ -chunks. The accepted values for assignments are functions and -nil. Likewise, the retrieved value is either a function or \type{nil}. - -\starttyping -lua.bytecode[n] = function () .. end -lua.bytecode[n]() -\stoptyping - -The contents of the \luatex{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 \luatex{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 -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 \luatex{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. The object oriented interface and \type{kpse.new} have been added -in \LUATEX\ 0.37. - -\subsection{\luatex{kpse.set_program_name} and \luatex{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 \luatex{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{\luatex{find_file}} - -The most often used function in the library is 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: - -\startsimplecolumns -\starttyping -'gf' -'pk' -'bitmap font' -'tfm' -'afm' -'base' -'bib' -'bst' -'cnf' -'ls-R' -'fmt' -'map' -'mem' -'mf' -'mfpool' -'mft' -'mp' -'mppool' -'MetaPost support' -'ocp' -'ofm' -'opl' -'otp' -'ovf' -'ovp' -'graphic/figure' -'tex' -'TeX system documentation' -'texpool' -'TeX system sources' -'PostScript header' -'Troff fonts' -'type1 fonts' -'vf' -'dvips config' -'ist' -'truetype fonts' -'type42 fonts' -'web2c files' -'other text files' -'other binary files' -'misc fonts' -'web' -'cweb' -'enc files' -'cmap files' -'subfont definition files' -'opentype fonts' -'pdftex config' -'lig files' -'texmfscripts' -'lua', -'font feature files', -'cid maps', -'mlbib', -'mlbst', -\stoptyping -\stopsimplecolumns - -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. The last four types: -'font feature files', 'cid maps', 'mlbib', 'mlbst' were new -additions in \LUATEX\ 0.40.2. - - -\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{\luatex{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{\luatex{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 \lua {nil} if the file does not exist or is not readable. - -\subsection{\luatex{expand_path}} - -Like kpsewhich's \type {-expand-path}: - -\startfunctioncall -<string> r = kpse.expand_path(<string> s) -\stopfunctioncall - -\subsection{\luatex{expand_var}} - -Like kpsewhich's \type{-expand-var}: - -\startfunctioncall -<string> r = kpse.expand_var(<string> s) -\stopfunctioncall - -\subsection{\luatex{expand_braces}} - -Like kpsewhich's \type{-expand-braces}: - -\startfunctioncall -<string> r = kpse.expand_braces(<string> s) -\stopfunctioncall - -\subsection{\luatex{show_path}} - -Like kpsewhich's \type{-show-path}: - -\startfunctioncall -<string> r = kpse.show_path(<string> ftype) -\stopfunctioncall - - -\subsection{\luatex{var_value}} - -Like kpsewhich's \type{-var-value}: - -\startfunctioncall -<string> r = kpse.var_value(<string> s) -\stopfunctioncall - -\section{The \luatex{status} library} - -This contains a number of run|-|time configuration items that -you may find useful in message reporting, as well as an iterator -function that gets all of the names and values as a table. - -\startfunctioncall -<table> info = status.list() -\stopfunctioncall - -The keys in the table are the known items, the value is the -current value. Almost all of the values in \type{status} are -fetched through a metatable at run|-|time whenever they are -accessed, so you cannot use \type{pairs} on \type{status}, but you -{\it can\/} use \type{pairs} on \type{info}, of course. If you do -not need the full list, you can also ask for a single item by -using its name as an index into \type{status}. - -The current list is: - -\starttabulate[|lT|p|] -\NC \ssbf key \NC \bf explanation \NC\NR -\NC pdf_gone\NC written \PDF\ bytes \NC \NR -\NC pdf_ptr\NC not yet written \PDF\ bytes \NC \NR -\NC dvi_gone\NC written \DVI\ bytes \NC \NR -\NC dvi_ptr\NC not yet written \DVI\ bytes \NC \NR -\NC total_pages\NC number of written pages \NC \NR -\NC output_file_name\NC name of the \PDF\ or \DVI\ file \NC \NR -\NC log_name\NC name of the log file \NC \NR -\NC banner\NC terminal display banner \NC \NR -\NC var_used\NC variable (one|-|word) memory in use \NC \NR -\NC dyn_used\NC token (multi|-|word) memory in use \NC \NR -\NC str_ptr\NC number of strings \NC \NR -\NC init_str_ptr\NC number of \INITEX\ strings \NC \NR -\NC max_strings\NC maximum allowed strings \NC \NR -\NC pool_ptr\NC string pool index \NC \NR -\NC init_pool_ptr\NC \INITEX\ string pool index \NC \NR -\NC pool_size\NC current size allocated for string characters \NC \NR -\NC node_mem_usage\NC a string giving insight into currently used nodes\NC\NR -\NC var_mem_max\NC number of allocated words for nodes\NC \NR -\NC fix_mem_max\NC number of allocated words for tokens\NC \NR -\NC fix_mem_end\NC maximum number of used tokens\NC \NR -\NC cs_count\NC number of control sequences \NC \NR -\NC hash_size\NC size of hash \NC \NR -\NC hash_extra\NC extra allowed hash \NC \NR -\NC font_ptr\NC number of active fonts \NC \NR -\NC max_in_stack\NC max used input stack entries \NC \NR -\NC max_nest_stack\NC max used nesting stack entries \NC \NR -\NC max_param_stack\NC max used parameter stack entries \NC \NR -\NC max_buf_stack\NC max used buffer position \NC \NR -\NC max_save_stack\NC max used save stack entries \NC \NR -\NC stack_size\NC input stack size \NC \NR -\NC nest_size\NC nesting stack size \NC \NR -\NC param_size\NC parameter stack size \NC \NR -\NC buf_size\NC current allocated size of the line buffer \NC \NR -\NC save_size\NC save stack size \NC \NR -\NC obj_ptr\NC max \PDF\ object pointer \NC \NR -\NC obj_tab_size\NC \PDF\ object table size \NC \NR -\NC pdf_os_cntr\NC max \PDF\ object stream pointer \NC \NR -\NC pdf_os_objidx\NC \PDF\ object stream index \NC \NR -\NC pdf_dest_names_ptr\NC max \PDF\ destination pointer \NC \NR -\NC dest_names_size\NC \PDF\ destination table size \NC \NR -\NC pdf_mem_ptr\NC max \PDF\ memory used \NC \NR -\NC pdf_mem_size\NC \PDF\ memory size \NC \NR -\NC largest_used_mark\NC max referenced marks class \NC \NR -\NC filename\NC name of the current input file \NC \NR -\NC inputid\NC numeric id of the current input \NC \NR -\NC linenumber\NC location in the current input file\NC \NR -\NC lasterrorstring\NC last error string\NC \NR -\NC luabytecodes\NC number of active \LUA\ bytecode registers\NC \NR -\NC luabytecode_bytes\NC number of bytes in \LUA\ bytecode registers\NC \NR -\NC luastate_bytes\NC number of bytes in use by \LUA\ interpreters\NC \NR -\NC output_active\NC \type{true} if the \tex{output} routine is active\NC \NR -\NC callbacks\NC total number of executed callbacks so far\NC \NR -\NC indirect_callbacks\NC number of those that were themselves - a result of other callbacks (e.g. file readers)\NC \NR -\NC luatex_version\NC the luatex version number (added in 0.38)\NC\NR -\NC luatex_revision\NC the luatex revision string (added in 0.38)\NC\NR -\NC ini_version\NC \type{true} if this is an \INITEX\ run (added in 0.38)\NC\NR -\stoptabulate - -\section[texconfig]{The \luatex{texconfig} table} - -This is a table that is created empty. A startup \LUA\ script could -fill this table with a number of settings that are read out by -the executable after loading and executing the startup file. - -\starttabulate[|lT|l|l|p|] -\NC \ssbf key \NC \bf type \NC \bf default \NC \bf explanation \NC\NR -\NC kpse_init \NC boolean \NC true \NC \type{false} totally disables \KPATHSEA\ initialisation, - and enables interpretation of the following numeric key--value pairs. - (only ever unset this if you implement {\it all\/} file - find callbacks!)\NC \NR -\NC shell_escape \NC string\NC \type{'f'}\NC Use \type{'y'} or \type{'t'} or \type{'1'} to enable \type{\write18} unconditionally, - \type{'p'} to enable the commands that are listed in \type{shell_escape_commands} (new in 0.37)\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 (new in 0.37)\NC\NR -\NC string_vacancies \NC number\NC 75000\NC cf.\ web2c docs \NC \NR -\NC pool_free \NC number\NC 5000\NC cf.\ web2c docs \NC \NR -\NC max_strings \NC number\NC 15000\NC cf.\ web2c docs \NC \NR -\NC strings_free \NC number\NC 100\NC cf.\ web2c docs \NC \NR -\NC nest_size \NC number\NC 50\NC cf.\ web2c docs \NC \NR -\NC max_in_open \NC number\NC 15\NC cf.\ web2c docs \NC \NR -\NC param_size \NC number\NC 60\NC cf.\ web2c docs \NC \NR -\NC save_size \NC number\NC 4000\NC cf.\ web2c docs \NC \NR -\NC stack_size \NC number\NC 300\NC cf.\ web2c docs \NC \NR -\NC dvi_buf_size \NC number\NC 16384\NC cf.\ web2c docs \NC \NR -\NC error_line \NC number\NC 79\NC cf.\ web2c docs \NC \NR -\NC half_error_line \NC number\NC 50\NC cf.\ web2c docs \NC \NR -\NC max_print_line \NC number\NC 79\NC cf.\ web2c docs \NC \NR -\NC ocp_list_size \NC number\NC 1000\NC cf.\ web2c docs \NC \NR -\NC ocp_buf_size \NC number\NC 1000\NC cf.\ web2c docs \NC \NR -\NC ocp_stack_size \NC number\NC 1000\NC cf.\ web2c docs \NC \NR -\NC hash_extra \NC number\NC 0\NC cf.\ web2c docs \NC \NR -\NC pk_dpi \NC number\NC 72\NC cf.\ web2c docs \NC \NR -\NC trace_file_names \NC boolean \NC true \NC \type{false} disables \TEX's normal file open|-|close - feedback (the assumption is that callbacks will take care of - that) \NC \NR -\NC file_line_error \NC boolean \NC false \NC do \type{file:line} style error messages\NC \NR -\NC halt_on_error \NC boolean \NC false \NC abort run on the first encountered error\NC \NR -\NC formatname \NC string \NC \NC if no format name was given - on the commandline, this key will be tested first - instead of simply quitting\NC \NR -\NC jobname \NC string \NC \NC if no input file name was given - on the commandline, this key will be tested first - instead of simply giving up\NC \NR -\stoptabulate - -{\bf 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 \luatex{font} library} The font library provides the interface into the internals of the font @@ -4244,6 +1949,9 @@ the next section. \subsection{Loading a \TFM\ file} +The behavior documented in this subsection is considered stable in the +sense that there will not be backward-incompatible changes any more. + \startfunctioncall <table> fnt = font.read_tfm(<string> name, <number> s) \stopfunctioncall @@ -4261,6 +1969,9 @@ explained in \in{chapter}[fonts]. \subsection{Loading a \VF\ file} +The behavior documented in this subsection is considered stable in the +sense that there will not be backward-incompatible changes any more. + \startfunctioncall <table> vf_fnt = font.read_vf(<string> name, <number> s) \stopfunctioncall @@ -4321,7 +2032,7 @@ raised. The table is a font structure, as explained in \subsection{Projected next font id} \startfunctioncall -number i = font.nextid(); +<number> i = font.nextid(); \stopfunctioncall This returns the font id number that would be returned by a @@ -4329,7 +2040,14 @@ This returns the font id number that would be returned by a flow. This is useful for virtual fonts that need to reference themselves. +\subsection{Font id (0.47)} + +\startfunctioncall +<number> i = font.id(<string> csname); +\stopfunctioncall +This returns the font id associated with \type{csname} string, or $-1$ +if \type{csname} is not defined, new in 0.47. \subsection{Currently active font} @@ -4427,15 +2145,20 @@ reported by fontloader while opening the font. In normal typesetting, you would probably ignore the second argument, but it can be useful for debugging purposes. -For \TRUETYPE\ collections (when filename ends in 'ttc'), you have to -use a second string argument to specify which font you want from the -collection. Use one of the \type{fullname} strings that are returned -by \type{fontloader.info} for that. +For \TRUETYPE\ collections (when filename ends in 'ttc') and \DFONT\ +collections, you have to use a second string argument to specify which +font you want from the collection. Use the \type{fontname} +strings that are returned by \type{fontloader.info} for that. \startfunctioncall -f, w = fontloader.open('filename','fullname') +f, w = fontloader.open('filename','fontname') \stopfunctioncall +Do not forget to store the \type{fontname} value in the \type{psname} +field of the metrics table to be returned to \LUATEX, otherwise the +font inclusion backend will not be able to find the correct font in +the collection. + The font file is parsed and partially interpreted by the font loading routines from \FONTFORGE. The file format can be \OPENTYPE, @@ -4496,11 +2219,11 @@ if it exists in the same directory as the file \type{font.pfb}. In that case, there is no need for an explicit call to \type{apply_afmfile()}. -\section{Fontloader font tables} +\subsection{Fontloader font tables} -\subsection{Table types} +\subsubsection{Table types} -\subsubsection{Top-level} +\subsubsubsection{Top-level} The top|-|level keys in the returned table are (the explanations in this part of the documentation are not yet finished): @@ -4509,7 +2232,7 @@ this part of the documentation are not yet finished): \NC \ssbf key \NC \bf type \NC \bf explanation \NC\NR \NC table_version \NC number \NC indicates the metrics version (currently~0.3)\NC\NR \NC fontname \NC string \NC \POSTSCRIPT\ font name\NC\NR -\NC fullname \NC string \NC official font name\NC\NR +\NC fullname \NC string \NC official (human-oriented) font name\NC\NR \NC familyname \NC string \NC family name\NC\NR \NC weight \NC string \NC weight indicator\NC\NR \NC copyright \NC string \NC copyright information\NC\NR @@ -4570,8 +2293,7 @@ this part of the documentation are not yet finished): \NC design_range_bottom \NC number \NC \NC\NR \NC design_range_top \NC number \NC \NC\NR \NC strokewidth \NC float \NC \NC\NR -\NC mark_classes \NC array \NC \NC\NR -\NC mark_class_names \NC array \NC \NC\NR +\NC mark_classes \NC table \NC \NC\NR \NC creationtime \NC number \NC \NC\NR \NC modificationtime \NC number \NC \NC\NR \NC os2_version \NC number \NC \NC\NR @@ -4583,7 +2305,7 @@ this part of the documentation are not yet finished): \NC extrema_bound \NC number \NC \NC\NR \stoptabulate -\subsubsection{Glyph items} +\subsubsubsection{Glyph items} The \type{glyphs} is an array containing the per|-|character information (quite a few of these are only present if nonzero). @@ -4592,7 +2314,7 @@ information (quite a few of these are only present if nonzero). \NC \ssbf key \NC \bf type \NC \bf explanation \NC\NR \NC name \NC string \NC the glyph name\NC\NR \NC unicode \NC number \NC unicode code point, or -1\NC\NR -\NC boundingbox \NC array \NC array of four numbers\NC\NR +\NC boundingbox \NC array \NC array of four numbers, see note below\NC\NR \NC width \NC number \NC only for horizontal fonts\NC\NR \NC vwidth \NC number \NC only for vertical fonts\NC\NR \NC lsidebearing \NC number \NC only if nonzero and not equal to boundingbox[1]\NC\NR @@ -4615,6 +2337,16 @@ information (quite a few of these are only present if nonzero). \NC mathkern \NC table \NC \NC \NR \stoptabulate +On \type{boundingbox}: The boundingbox information for \TRUETYPE\ fonts and \TRUETYPE-based \OTF\ fonts is read +directly from the font file. \POSTSCRIPT-based fonts do not have this information, so the boundingbox of +traditional \POSTSCRIPT\ fonts is generated by interpreting the actual bezier curves to find the exact +boundingbox. This can be a slow process, so starting from \LUATEX\ 0.45, the boundingboxes of \POSTSCRIPT-based +\OTF\ fonts (and raw \CFF\ fonts) are calculated using an approximation of the glyph shape based on the actual +glyph points only, instead of taking the whole curve into account. This means that glyphs that have missing +points at extrema will have a too-tight boundingbox, but the processing is so much faster that in our opinion +the tradeoff is worth it. + + The \type{kerns} and \type{vkerns} are linear arrays of small hashes: \starttabulate[|lT|l|p|] @@ -4712,7 +2444,7 @@ For clarification, an anchor table could for example look like this : } \stoptyping -\subsubsection{map table} +\subsubsubsection{map table} The top|-|level map is a list of encoding mappings. Each of those is a table itself. @@ -4765,12 +2497,12 @@ The \type{enc} table is a bit more verbose: \NC iso_2022_escape \NC string \NC \NC\NR \stoptabulate -\subsubsection{private table} +\subsubsubsection{private table} This is the font's private \POSTSCRIPT\ dictionary, if any. Keys and values are both strings. -\subsubsection{cidinfo table} +\subsubsubsection{cidinfo table} \starttabulate[|lT|l|p|] \NC \ssbf key \NC \bf type \NC \bf explanation \NC\NR @@ -4780,7 +2512,7 @@ values are both strings. \NC version \NC number \NC \NC\NR \stoptabulate -\subsubsection{pfminfo table} +\subsubsubsection{pfminfo table} The \type{pfminfo} table contains most of the OS/2 information: @@ -4853,7 +2585,7 @@ The \type{panose} subtable has exactly 10 string keys: \NC xheight \NC string \NC id. \NC\NR \stoptabulate -\subsubsection{names table} +\subsubsubsection{names table} Each item has two top|-|level keys: @@ -4893,7 +2625,7 @@ possible keys are: \NC wwssubfamily \NC \NC\NR \stoptabulate -\subsubsection{anchor_classes table} +\subsubsubsection{anchor_classes table} The anchor_classes classes: @@ -4907,7 +2639,7 @@ The anchor_classes classes: % type is actually a lookup subtype, not a feature name. Officially, these strings % should be gpos_mark2mark etc. -\subsubsection{gpos table} +\subsubsubsection{gpos table} Th gpos table has one array entry for each lookup. (The \type {gpos_} prefix is somewhat redundant.) @@ -4915,7 +2647,7 @@ Th gpos table has one array entry for each lookup. (The \type {gpos_} prefix is \NC \ssbf key \NC \bf type \NC \bf explanation \NC\NR \NC type \NC string \NC one of \type {gpos_single}, \type {gpos_pair}, \type {gpos_cursive}, - \type {gpos_mark2base}, \type {gpos_mark2ligature}, \type {gpos_mark2mark}, \type {gpos_context}, + \type {gpos_mark2base},\crlf \type {gpos_mark2ligature}, \type {gpos_mark2mark}, \type {gpos_context},\crlf \type {gpos_contextchain} \NC\NR \NC flags \NC table \NC \NC\NR @@ -4933,6 +2665,7 @@ actually set: \NC ignorebaseglyphs \NC boolean \NC \NC\NR \NC ignoreligatures \NC boolean \NC \NC\NR \NC ignorecombiningmarks \NC boolean \NC \NC\NR +\NC mark_class \NC string \NC (new in 0.44)\NC\NR \stoptabulate @@ -4979,7 +2712,7 @@ The kernclass with subtables table has: %\NC kcid \NC number \NC ? \NC\NR \stoptabulate -\subsubsection{gsub table} +\subsubsubsection{gsub table} This has identical layout to the \type{gpos} table, except for the type: @@ -4987,13 +2720,13 @@ type: \starttabulate[|lT|l|p|] \NC \ssbf key \NC \bf type \NC \bf explanation \NC\NR \NC type \NC string \NC one of \type {gsub_single}, \type {gsub_multiple}, \type {gsub_alternate}, - \type {gsub_ligature}, \type {gsub_context}, \type {gsub_contextchain}, \type {gsub_reversecontextchain} + \type {gsub_ligature},\crlf \type {gsub_context}, \type {gsub_contextchain}, \type {gsub_reversecontextchain} \NC\NR \stoptabulate -\subsubsection{ttf_tables and ttf_tab_saved tables} +\subsubsubsection{ttf_tables and ttf_tab_saved tables} \starttabulate[|lT|l|p|] \NC \ssbf key \NC \bf type \NC \bf explanation \NC\NR @@ -5003,7 +2736,7 @@ type: \NC data \NC number \NC \NC\NR \stoptabulate -\subsubsection{sm table} +\subsubsubsection{sm table} \starttabulate[|lT|l|p|] \NC \ssbf key \NC \bf type \NC \bf explanation \NC\NR @@ -5032,7 +2765,7 @@ applies if the \type{sm.type} = \type{kern}.\NC\NR \stoptabulate -\subsubsection{features table} +\subsubsubsection{features table} % handle_macfeat @@ -5058,7 +2791,7 @@ The \type{settings} are: macnames are like otfnames except that they also have an 'enc' field \NC \NR \stoptabulate -\subsubsection{mm table} +\subsubsubsection{mm table} \starttabulate[|lT|l|p|] \NC \ssbf key \NC \bf type \NC \bf explanation \NC\NR @@ -5097,7 +2830,15 @@ The \type{named_instances} is an array of instances: \stoptabulate -\subsubsection{math table} +\subsubsubsection{mark_classes table (0.44)} + +The keys in this table are mark class names, and the values +are a space-separated string of glyph names in this class. + +Note: This table is indeed new in 0.44. The manual said it existed +before then, but in practise it was missing due to a bug. + +\subsubsubsection{math table} \starttabulate[|lT|p|] \NC ScriptPercentScaleDown \NC \NC \NR @@ -5157,9 +2898,11 @@ The \type{named_instances} is an array of instances: \NC RadicalKernAfterDegree \NC \NC \NR \NC RadicalDegreeBottomRaisePercent \NC \NC \NR \NC MinConnectorOverlap \NC \NC \NR +\NC FractionDelimiterSize \NC (new in 0.47.0)\NC \NR +\NC FractionDelimiterDisplayStyleSize \NC (new in 0.47.0)\NC \NR \stoptabulate -\subsubsection{validation_state table} +\subsubsubsection{validation_state table} \starttabulate[|lT|p|] \NC \ssbf key \NC \bf explanation \NC\NR @@ -5175,7 +2918,7 @@ The \type{named_instances} is an array of instances: \NC bad_sfnt_header \NC \NC \NR \stoptabulate -\subsubsection{horiz_base and vert_base table} +\subsubsubsection{horiz_base and vert_base table} \starttabulate[|lT|l|p|] \NC \ssbf key \NC \bf type \NC \bf explanation \NC\NR @@ -5207,7 +2950,7 @@ The \type{lang} subtable: The \type{features} points to an array of tables with the same layout except that in those nested tables, the tag represents a language. -\subsubsection{altuni table} +\subsubsubsection{altuni table} An array of alternate \UNICODE\ values. Inside that array are hashes with: @@ -5218,7 +2961,7 @@ are hashes with: \NC variant \NC number \NC \NC \NR \stoptabulate -\subsubsection{vert_variants and horiz_variants table} +\subsubsubsection{vert_variants and horiz_variants table} \starttabulate[|lT|l|p|] \NC \ssbf key \NC \bf type \NC \bf explanation \NC\NR @@ -5239,7 +2982,7 @@ The \type{parts} table is an array of smaller tables: \stoptabulate -\subsubsection{mathkern table} +\subsubsubsection{mathkern table} \starttabulate[|lT|l|p|] \NC \ssbf key \NC \bf type \NC \bf explanation \NC\NR @@ -5257,15 +3000,15 @@ Each of the subtables is an array of small hashes with two keys: \NC kern \NC number \NC \NC \NR \stoptabulate -\subsubsection{kerns table} +\subsubsubsection{kerns table} Substructure is identical to the per|-|glyph subtable. -\subsubsection{vkerns table} +\subsubsubsection{vkerns table} Substructure is identical to the per|-|glyph subtable. -\subsubsection{texdata table} +\subsubsubsection{texdata table} \starttabulate[|lT|l|p|] @@ -5274,7 +3017,7 @@ Substructure is identical to the per|-|glyph subtable. \NC params \NC array \NC 22 font numeric parameters\NC\NR \stoptabulate -\subsubsection{lookups table} +\subsubsubsection{lookups table} Top|-|level \type{lookups} is quite different from the ones at character level. The keys in this hash are strings, the values the @@ -5339,6 +3082,542 @@ reversecoverage: \NC replacements \NC string \NC \NC\NR \stoptabulate +%*********************************************************************** + +\section{The \luatex{img} library} + +The \type{img} library can be used as an alternative to +\tex{pdfximage} and \tex{pdfrefximage}, and the associated \quote {satellite} +commands like \tex{pdfximagebbox}. +Image objects can also be used within virtual fonts +via the \type{image} command listed in~\in{section}[virtualfonts]. + +\subsubsubject{\luatex{img.new}} + +\startfunctioncall +<image> var = img.new() +<image> var = img.new(image_spec) +\stopfunctioncall + +This function creates a userdata object of type \quote {image}. The +\type{image_spec} argument is optional. If it is given, it must be +a table, and that table must contain a \type{filename} key. A number of +other keys can also be useful, these are explained below. + +You can either say + +\starttyping +a=img.new() +\stoptyping + +followed by + +\starttyping +a.filename="foo.png" +\stoptyping + +or you can put the file name (and some or all of the other keys) +into a table directly, like so: + +\starttyping +a=img.new{filename='foo.pdf',page=1} +\stoptyping + +The generated \type{<image>} userdata object allows access to a set of +user|-|specified values as well as a set of values that are normally +filled in and updated automatically by \LUATEX\ itself. Some of those +are derived from the actual image file, others are updated to reflect +the \PDF\ output status of the object. + +There is one required user-specified field: the file name +(\type{filename}). It can optionally be augmented by the requested +image dimensions (\type{width}, \type{depth}, \type{height}), +user-specified image attributes (\type{attr}), the requested \PDF\ page +identifier (\type{page}), the requested boundingbox (\type{pagebox}) +for \PDF\ inclusion, the requested color space object (\type{colorspace}). + +The function \type{img.new} does not access the actual image file, it +just creates the \type{<image>} userdata object and initializes some +memory structures. The \type{<image>} object and its internal +structures are automatically garbage collected. + +Once the image is scanned, all the values in the +\type{<image>} become frozen, and you cannot change them any more. + +\subsubsubject{\luatex{img.keys}} + +\startfunctioncall +<table> keys = img.keys() +\stopfunctioncall + +This function returns a list of all the possible \type{image_spec} +keys, both user-supplied and automatic ones. + +% hahe: i need to add r/w ro column... +\starttabulate[|l|l|p|] +\NC \bf field name\NC \bf type \NC description \NC \NR +\NC depth \NC number \NC the image depth for \LUATEX\ (in scaled points)\NC \NR +\NC height \NC number \NC the image height for \LUATEX\ (in scaled points)\NC \NR +\NC width \NC number \NC the image width for \LUATEX\ (in scaled points)\NC \NR +\NC transform \NC number \NC the image transform, integer number 0..7\NC \NR +\NC attr \NC string \NC the image attributes for \LUATEX \NC \NR +\NC filename \NC string \NC the image file name \NC \NR +\NC stream \NC string \NC the raw stream data for an \type{/Xobject} \type{/Form} object\NC \NR +\NC page \NC ?? \NC the identifier for the requested image + page (type is number or string, + default is the number 1)\NC \NR +\NC pagebox \NC string \NC the requested bounding box, + one of \type {none}, \type {media}, \type {crop}, \type {bleed}, \type {trim}, \type {art} \NC \NR +\NC bbox \NC table \NC table with 4 boundingbox dimensions \type{llx}, \type{lly}, + \type{urx}, and \type{ury} overruling the \type{pagebox} entry\NC \NR +\NC filepath \NC string \NC the full (expanded) file name of the image \NC \NR +\NC colordepth \NC number \NC the number of bits used by the color space \NC \NR +\NC colorspace \NC number \NC the color space object number \NC \NR +\NC imagetype \NC string \NC one of \type {pdf}, \type {png}, \type {jpg}, \type {jbig2}, or \type{nil} \NC \NR +\NC objnum \NC number \NC the \PDF\ image object number \NC \NR +\NC index \NC number \NC the \PDF\ image name suffix \NC \NR +\NC pages \NC number \NC the total number of available pages \NC \NR +\NC xsize \NC number \NC the natural image width \NC \NR +\NC ysize \NC number \NC the natural image height \NC \NR +\NC xres \NC number \NC the horizontal natural image resolution (in \DPI) \NC \NR +\NC yres \NC number \NC the vertical natural image resolution (in \DPI) \NC \NR +\stoptabulate + +A running (undefined) dimension in \type{width}, \type{height}, or \type{depth} is +represented as \type{nil} in \LUA, so if you want to load an image at +its \quote {natural} size, you do not have to specify any of those three fields. + +The \type{stream} parameter allows to fabricate an \type{/XObject} \type{/Form} +object from a string giving the stream contents, +e.\,g., for a filled rectangle: + +\startfunctioncall +a.stream = "0 0 20 10 re f" +\stopfunctioncall + +When writing the image, an \type{/Xobject} \type{/Form} object is created, +like with embedded \PDF\ file writing. The object is written out only once. +The \type{stream} key requires that also the \type{bbox} table is given. +The \type{stream} key conflicts with the \type{filename} key. +The \type{transform} key works as usual also with \type{stream}. + +The \type{bbox} key needs a table with four boundingbox values, e.\,g.: + +\startfunctioncall +a.bbox = {"30bp", 0, "225bp", "200bp"} +\stopfunctioncall + +This replaces and overrules any given \type{pagebox} value; +with given \type{bbox} the box dimensions coming with an embedded \PDF\ file +are ignored. +The \type{xsize} and \type{ysize} dimensions are set accordingly, +when the image is scaled. +The \type{bbox} parameter is ignored for non-\PDF\ images. + +The \type{transform} allows to mirror and rotate the image in steps of 90~deg. +The default value~0 gives an unmirrored, unrotated image. +Values 1|--|3 give counterclockwise rotation by 90, 180, or 270~degrees, +whereas with values 4|--|7 the image is first mirrored +and then rotated counterclockwise by 90, 180, or 270~degrees. +The \type{transform} operation gives the same visual result +as if you would externally preprocess the image by a graphics tool +and then use it by \LUATEX. +If a \PDF\ file to be embedded already contains a \type{/Rotate} specification, +the rotation result is the combination of the \type{/Rotate} rotation +followed by the \type{transform} operation. + +\subsubsubject{\luatex{img.scan}} + +\startfunctioncall +<image> var = img.scan(<image> var) +<image> var = img.scan(image_spec) +\stopfunctioncall + +When you say \type{img.scan(a)} for a new image, the file is scanned, +and variables such as \type{xsize}, \type{ysize}, image \type{type}, number of +\type{pages}, and the resolution are extracted. Each of the \type{width}, +\type{height}, \type{depth} fields are set up according to the image dimensions, +if they were not given an explicit value already. +An image file will never be scanned more than once for a given image variable. +With all subsequent \type{img.scan(a)} calls only the dimensions are again +set up (if they have been changed by the user in the meantime). + +For ease of use, you can do right-away a + +\starttyping +<image> a = img.scan { filename = "foo.png" } +\stoptyping + +without a prior \type{img.new}. + +Nothing is written yet at this point, so you can do \type{a=img.scan}, +retrieve the available info like image width and height, and then +throw away \type{a} again by saying \type{a=nil}. In that case no +image object will be reserved in the PDF, and the used memory will be +cleaned up automatically. + +\subsubsubject{\luatex{img.copy}} + +\startfunctioncall +<image> var = img.copy(<image> var) +<image> var = img.copy(image_spec) +\stopfunctioncall + +If you say \type{a = b}, then both variables point to the same +\type{<image>} object. if you want to write out an image with +different sizes, you can do a \type{b=img.copy(a)}. + +Afterwards, \type{a} and \type{b} still reference the same actual +image dictionary, but the dimensions for \type{b} can now be changed +from their initial values that were just copies from \type{a}. + +% Hartmut, I don't know if this makes sense. An example of what +% can, and what cannot be changed would be helpful. +% -- will think about it... + +\subsubsubject{\luatex{img.write}} + +\startfunctioncall +<image> var = img.write(<image> var) +<image> var = img.write(image_spec) +\stopfunctioncall + +By \type{img.write(a)} a \PDF\ object number is allocated, +and a whatsit node of subtype \type{pdf_refximage} is generated +and put into the output list. +By this the image \type{a} is placed into the page stream, +and the image file is written out into an image stream object +after the shipping of the current page is finished. + +Again you can do a terse call like + +\starttyping +img.write { filename = "foo.png" } +\stoptyping + +The \type{<image>} variable is returned in case you want it for later +processing. + +\subsubsubject{\luatex{img.immediatewrite}} + +\startfunctioncall +<image> var = img.immediatewrite(<image> var) +<image> var = img.immediatewrite(image_spec) +\stopfunctioncall + +By \type{img.immediatewrite(a)} a \PDF\ object number is +allocated, and the image file for image \type{a} is written out +immediately into the \PDF\ file as an image stream object (like +with \tex{immediate}\tex{pdfximage}). The object number of the image +stream dictionary is then available by the \type{objnum} key. No +\type{pdf_refximage} whatsit node is generated. You will need an +\luatex{img.write(a)} or \luatex{img.node(a)} call to let the +image appear on the page, or reference it by another trick; else +you will have a dangling image object in the \PDF\ file. + +Also here you can do a terse call like + +\starttyping +a = img.immediatewrite { filename = "foo.png" } +\stoptyping + +The \type{<image>} variable is returned and you will most likely need it. + +\subsubsubject{\luatex{img.node}} + +\startfunctioncall +<node> n = img.node(<image> var) +<node> n = img.node(image_spec) +\stopfunctioncall + +This function allocates a \PDF\ object number and returns a +whatsit node of subtype \type{pdf_refximage}, filled with the +image parameters \type{width}, \type{height}, \type{depth}, and +\type{objnum}. Also here you can do a terse call like: + +\starttyping +n = img.node { filename = "foo.png" } +\stoptyping + +This example outputs an image: + +\starttyping +node.write(img.node{filename="foo.png"}) +\stoptyping + +\subsubsubject{\luatex{img.types}} + +\startfunctioncall +<table> types = img.types() +\stopfunctioncall + +This function returns a list with the supported image file type names, +currently these are \type {pdf}, \type {png}, \type {jpg}, and \type {jbig2}. + +\subsubsubject{\luatex{img.boxes}} + +\startfunctioncall +<table> boxes = img.boxes() +\stopfunctioncall + +This function returns a list with the supported \PDF\ page box names, +currently these are \type {media}, \type {crop}, \type {bleed}, \type {trim}, and \type {art} +(all in lowercase letters). + + +\section{The \luatex{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. The object oriented interface and \type{kpse.new} have been added +in \LUATEX\ 0.37. + +\subsection{\luatex{kpse.set_program_name} and \luatex{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 \luatex{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{\luatex{find_file}} + +The most often used function in the library is 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: + +\startsimplecolumns +\starttyping +'gf' +'pk' +'bitmap font' +'tfm' +'afm' +'base' +'bib' +'bst' +'cnf' +'ls-R' +'fmt' +'map' +'mem' +'mf' +'mfpool' +'mft' +'mp' +'mppool' +'MetaPost support' +'ocp' +'ofm' +'opl' +'otp' +'ovf' +'ovp' +'graphic/figure' +'tex' +'TeX system documentation' +'texpool' +'TeX system sources' +'PostScript header' +'Troff fonts' +'type1 fonts' +'vf' +'dvips config' +'ist' +'truetype fonts' +'type42 fonts' +'web2c files' +'other text files' +'other binary files' +'misc fonts' +'web' +'cweb' +'enc files' +'cmap files' +'subfont definition files' +'opentype fonts' +'pdftex config' +'lig files' +'texmfscripts' +'lua', +'font feature files', +'cid maps', +'mlbib', +'mlbst', +'clua', +\stoptyping +\stopsimplecolumns + +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. The last four types: +'font feature files', 'cid maps', 'mlbib', 'mlbst' were new +additions in \LUATEX\ 0.40.2. + + +\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{\luatex{lookup}} + +A more powerful (but slower) generic method for finding files is also +available (since 0.51). + +\startfunctioncall +<string> f, ... = kpse.lookup(<string> filename, <table> options) +\stopfunctioncall + +The options match commandline arguments from \type{kpsewhich}: + +\starttabulate[|l|l|p|] +\NC \ssbf key \NC \ssbf type \NC \ssbf description \NC \NR +\NC debug \NC number \NC set debugging flags for this lookup\NC \NR +\NC format \NC string \NC use specific file type (see list above)\NC \NR +\NC dpi \NC number \NC use this resolution for this lookup; default 600\NC \NR +\NC path \NC string \NC search in the given path\NC \NR +\NC all \NC boolean \NC output all matches, not just the first\NC \NR +\NC must-exist\NC boolean \NC search the disk as well as ls-R if necessary\NC \NR +\NC mktexpk \NC boolean \NC disable/enable mktexpk generation for this lookup\NC \NR +\NC mktextex \NC boolean \NC disable/enable mktextex generation for this lookup\NC \NR +\NC mktexmf \NC boolean \NC disable/enable mktexmf generation for this lookup\NC \NR +\NC mktextfm \NC boolean \NC disable/enable mktextfm generation for this lookup\NC \NR +\NC subdir \NC string + or table \NC only output matches whose directory part + ends with the given string(s) \NC \NR +\stoptabulate + +\subsection{\luatex{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{\luatex{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 \lua {nil} if the file does not exist or is not readable. + +\subsection{\luatex{expand_path}} + +Like kpsewhich's \type {-expand-path}: + +\startfunctioncall +<string> r = kpse.expand_path(<string> s) +\stopfunctioncall + +\subsection{\luatex{expand_var}} + +Like kpsewhich's \type{-expand-var}: + +\startfunctioncall +<string> r = kpse.expand_var(<string> s) +\stopfunctioncall + +\subsection{\luatex{expand_braces}} + +Like kpsewhich's \type{-expand-braces}: + +\startfunctioncall +<string> r = kpse.expand_braces(<string> s) +\stopfunctioncall + +\subsection{\luatex{show_path}} + +Like kpsewhich's \type{-show-path}: + +\startfunctioncall +<string> r = kpse.show_path(<string> ftype) +\stopfunctioncall + + +\subsection{\luatex{var_value}} + +Like kpsewhich's \type{-var-value}: + +\startfunctioncall +<string> r = kpse.var_value(<string> s) +\stopfunctioncall + +\subsection{\luatex{version}} + +Returns the kpathsea version string (new in 0.51) + +\startfunctioncall +<string> r = kpse.version() +\stopfunctioncall + + \section{The \luatex{lang} library} This library provides the interface to \LUATEX's structure @@ -5384,8 +3663,8 @@ Clears the exception dictionary for this language. \stopfunctioncall Creates a hyphenation key from the supplied hyphenation value. The -syntax of the argument string is explained in the next -chapter,~\in{section}[patternsexceptions]. This function is useful if +syntax of the argument string is explained~\in{section}[patternsexceptions]. +This function is useful if you want to do something else based on the words in a dictionary file, like spell-checking. @@ -5395,8 +3674,7 @@ lang.patterns(<language> l, <string> n) \stopfunctioncall Adds additional patterns for this language object, or returns the -current set. The syntax of this string is explained in the next -chapter,~\in{section}[patternsexceptions]. +current set. The syntax of this string is explained in~\in{section}[patternsexceptions]. \startfunctioncall lang.clear_patterns(<language> l) @@ -5456,6 +3734,2449 @@ modes with different subtypes are not processed. See \in{section~}[charsandglyphs] for more details. +\section{The \luatex{lua} library} + +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 +nil. Likewise, the retrieved value is either a function or \type{nil}. + +\starttyping +lua.bytecode[n] = function () .. end +lua.bytecode[n]() +\stoptyping + +The contents of the \luatex{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 \luatex{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 +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 \luatex{mplib} library} + +The \MP\ library interface registers itself in the table \type{mplib}. It +is based on \MPLIB\ version \ctxlua{tex.sprint(mplib.version())}. + +\subsection{\luatex{mplib.new}} + +To create a new \METAPOST\ instance, call + +\startfunctioncall +<mpinstance> mp = mplib.new({...}) +\stopfunctioncall + +This creates the \type{mp} instance object. The argument hash can have a number of +different fields, as follows: + +\starttabulate[|lT|l|p|p|] +\NC \ssbf name \NC \bf type \NC \bf description \NC \bf default \NC\NR +\NC error_line \NC number \NC error line width \NC 79 \NC\NR +\NC print_line \NC number \NC line length in ps output \NC 100\NC\NR +\NC main_memory \NC number \NC total memory size \NC 5000\NC\NR +\NC hash_size \NC number \NC hash size \NC 16384 \NC\NR +\NC param_size \NC number \NC max. active macro parameters\NC 150\NC\NR +\NC max_in_open \NC number \NC max. input file nestings \NC 10\NC\NR +\NC random_seed \NC number \NC the initial random seed \NC variable\NC\NR +\NC interaction \NC string \NC the interaction mode, one of +\type {batch}, \type {nonstop}, \type {scroll}, \type {errorstop} \NC \type {errorstop}\NC\NR +\NC ini_version \NC boolean \NC the --ini switch \NC true \NC\NR +\NC mem_name \NC string \NC \type {--mem} \NC \type {plain} \NC\NR +\NC job_name \NC string \NC \type {--jobname} \NC \type {mpout} \NC\NR +\NC find_file \NC function \NC a function to find files \NC only local files\NC\NR +\stoptabulate + +The \type{find_file} function should be of this form: + +\starttyping +<string> found = finder (<string> name, <string> mode, <string> type) +\stoptyping + +with: + +\starttabulate[|lT|l|p|] +\NC \bf name \NC \bf the requested file \NC \NR +\NC mode \NC the file mode: \type {r} or \type {w} \NC \NR +\NC type \NC the kind of file, one of: \type {mp}, \type {mem}, \type {tfm}, \type {map}, \type {pfb}, \type {enc} \NC \NR +\stoptabulate + +Return either the full pathname of the found file, or \type{nil} if +the file cannot be found. + +\subsection{\luatex{mp:statistics}} + +You can request statistics with: + +\startfunctioncall +<table> stats = mp:statistics() +\stopfunctioncall + +This function returns the vital statistics for an \MPLIB\ instance. There are four +fields, giving the maximum number of used items in each of the four +statically allocated object classes: + +\starttabulate[|lT|l|p|] +\NC main_memory \NC number \NC memory size \NC\NR +\NC hash_size \NC number \NC hash size\NC\NR +\NC param_size \NC number \NC simultaneous macro parameters\NC\NR +\NC max_in_open \NC number \NC input file nesting levels\NC\NR +\stoptabulate + +\subsection{\luatex{mp:execute}} + +You can ask the \METAPOST\ interpreter to run a chunk of code by calling + +\startfunctioncall +local rettable = mp:execute('metapost language chunk') +\stopfunctioncall + +for various bits of \METAPOST\ language input. Be sure to check the +\type{rettable.status} (see below) because when a fatal \METAPOST\ +error occurs the \MPLIB\ instance will become unusable thereafter. + +Generally speaking, it is best to keep your chunks small, but beware +that all chunks have to obey proper syntax, like each of them is a +small file. For instance, you cannot split a single statement over +multiple chunks. + +In contrast with the normal standalone \type{mpost} command, there is +{\em no\/} implied \quote{input} at the start of the first chunk. + +\subsection{\luatex{mp:finish}} + +\startfunctioncall +local rettable = mp:finish() +\stopfunctioncall + +If for some reason you want to stop using an \MPLIB\ instance while +processing is not yet actually done, you can call \type{mp:finish}. +Eventually, used memory will be freed and open files will be closed by +the \LUA\ garbage collector, but an explicit \type{mp:finish} is the +only way to capture the final part of the output streams. + +\subsection{Result table} + +The return value of \type{mp:execute} and \type{mp:finish} is a table +with a few possible keys (only \type {status} is always guaranteed to be present). + +\starttabulate[|l|l|p|] +\NC log \NC string \NC output to the \quote {log} stream \NC \NR +\NC term \NC string \NC output to the \quote {term} stream \NC \NR +\NC error \NC string \NC output to the \quote {error} stream (only used for \quote {out of memory})\NC \NR +\NC status \NC number \NC the return value: 0=good, 1=warning, 2=errors, 3=fatal error \NC \NR +\NC fig \NC table \NC an array of generated figures (if any)\NC \NR +\stoptabulate + +When \type{status} equals~3, you should stop using this \MPLIB\ instance +immediately, it is no longer capable of processing input. + +If it is present, each of the entries in the \type{fig} array is a +userdata representing a figure object, and each of those has a number of +object methods you can call: + +\starttabulate[|l|l|p|] +\NC boundingbox \NC function \NC returns the bounding box, as an array of 4 values\NC \NR +\NC postscript \NC function \NC return a string that is the ps output of the \type{fig}. + this function accepts two optional integer arguments for + specifying the values of \type{prologues} (first argument) + and \type{procset} (second argument)\NC \NR +\NC svg \NC function \NC return a string that is the svg output of the \type{fig}. + this function accepts an optional integer arguments for + specifying the value of \type{prologues}\NC \NR +\NC objects \NC function \NC returns the actual array of graphic objects in this \type{fig} \NC \NR +\NC copy_objects \NC function \NC returns a deep copy of the array of graphic objects in this \type{fig} \NC \NR +\NC filename \NC function \NC the filename this \type{fig}'s \POSTSCRIPT\ output + would have written to in standalone mode\NC \NR +\NC width \NC function \NC the \type{charwd} value \NC \NR +\NC height \NC function \NC the \type{charht} value \NC \NR +\NC depth \NC function \NC the \type{chardp} value \NC \NR +\NC italcorr \NC function \NC the \type{charit} value \NC \NR +\NC charcode \NC function \NC the (rounded) \type{charcode} value \NC \NR +\stoptabulate + +{\bf NOTE:} you can call \type{fig:objects()} only once for any one \type{fig} object! + +When the boundingbox represents a \quote {negated rectangle}, i.e.\ when the first set +of coordinates is larger than the second set, the picture is empty. + +Graphical objects come in various types that each have a different list of +accessible values. The types are: \type{fill}, \type{outline}, \type{text}, +\type{start_clip}, \type{stop_clip}, \type{start_bounds}, \type{stop_bounds}, \type{special}. + +There is helper function (\type{mplib.fields(obj)}) to get the list of +accessible values for a particular object, but you can just as easily +use the tables given below). + +All graphical objects have a field \type{type} that gives the object +type as a string value, that not explicit mentioned in the tables. In +the following, \type{number}s are \POSTSCRIPT\ points represented as +a floating point number, unless stated otherwise. Field values that +are of \type{table} are explained in the next section. + +\subsubsection{fill} + +\starttabulate[|l|l|p|] +\NC path \NC table \NC the list of knots \NC \NR +\NC htap \NC table \NC the list of knots for the reversed trajectory \NC \NR +\NC pen \NC table \NC knots of the pen \NC \NR +\NC color \NC table \NC the object's color \NC \NR +\NC linejoin \NC number \NC line join style (bare number)\NC \NR +\NC miterlimit \NC number \NC miterlimit\NC \NR +\NC prescript \NC string \NC the prescript text \NC \NR +\NC postscript \NC string \NC the postscript text \NC \NR +\stoptabulate + +The entries \type{htap} and \type{pen} are optional. + +There is helper function (\type{mplib.pen_info(obj)}) that returns +a table containing a bunch of vital characteristics of the used pen +(all values are floats): + +\starttabulate[|l|l|p|] +\NC width \NC number \NC width of the pen\NC \NR +\NC rx \NC number \NC $x$ scale \NC \NR +\NC sx \NC number \NC $xy$ multiplier \NC \NR +\NC sy \NC number \NC $yx$ multiplier \NC \NR +\NC ry \NC number \NC $y$ scale \NC \NR +\NC tx \NC number \NC $x$ offset \NC \NR +\NC ty \NC number \NC $y$ offset \NC \NR +\stoptabulate + +\subsubsection{outline} + +\starttabulate[|l|l|p|] +\NC path \NC table \NC the list of knots \NC \NR +\NC pen \NC table \NC knots of the pen \NC \NR +\NC color \NC table \NC the object's color \NC \NR +\NC linejoin \NC number \NC line join style (bare number)\NC \NR +\NC miterlimit \NC number \NC miterlimit \NC \NR +\NC linecap \NC number \NC line cap style (bare number)\NC \NR +\NC dash \NC table \NC representation of a dash list\NC \NR +\NC prescript \NC string \NC the prescript text \NC \NR +\NC postscript \NC string \NC the postscript text \NC \NR +\stoptabulate + +The entry \type{dash} is optional. + +\subsubsection{text} + +\starttabulate[|l|l|p|] +\NC text \NC string \NC the text \NC \NR +\NC font \NC string \NC font tfm name \NC \NR +\NC dsize \NC number \NC font size\NC \NR +\NC color \NC table \NC the object's color \NC \NR +\NC width \NC number \NC \NC \NR +\NC height \NC number \NC \NC \NR +\NC depth \NC number \NC \NC \NR +\NC transform \NC table \NC a text transformation \NC \NR +\NC prescript \NC string \NC the prescript text \NC \NR +\NC postscript \NC string \NC the postscript text \NC \NR +\stoptabulate + +\subsubsection{special} + +\starttabulate[|l|l|p|] +\NC prescript \NC string \NC special text \NC \NR +\stoptabulate + +\subsubsection{start_bounds, start_clip} + +\starttabulate[|l|l|p|] +\NC path \NC table \NC the list of knots \NC \NR +\stoptabulate + +\subsubsection{stop_bounds, stop_clip} + +Here are no fields available. + +\subsection{Subsidiary table formats} + +\subsubsection{Paths and pens} + +Paths and pens (that are really just a special type of paths as far as +\MPLIB\ is concerned) are represented by an array where each entry +is a table that represents a knot. + +\starttabulate[|lT|l|p|] +\NC left_type \NC string \NC when present: 'endpoint', but usually absent \NC \NR +\NC right_type \NC string \NC like \type{left_type}\NC \NR +\NC x_coord \NC number \NC X coordinate of this knot\NC \NR +\NC y_coord \NC number \NC Y coordinate of this knot\NC \NR +\NC left_x \NC number \NC X coordinate of the precontrol point of this knot\NC \NR +\NC left_y \NC number \NC Y coordinate of the precontrol point of this knot\NC \NR +\NC right_x \NC number \NC X coordinate of the postcontrol point of this knot\NC \NR +\NC right_y \NC number \NC Y coordinate of the postcontrol point of this knot\NC \NR +\stoptabulate + +There is one special case: pens that are (possibly transformed) +ellipses have an extra string-valued key \type{type} with value +\type{elliptical} besides the array part containing the knot list. + +\subsubsection{Colors} + +A color is an integer array with 0, 1, 3 or 4 values: + +\starttabulate[|l|l|p|] +\NC 0 \NC marking only \NC no values \NC\NR +\NC 1 \NC greyscale \NC one value in the range $(0,1)$, \quote {black} is $0$ \NC\NR +\NC 3 \NC \RGB \NC three values in the range $(0,1)$, \quote {black} is $0,0,0$ \NC\NR +\NC 4 \NC \CMYK \NC four values in the range $(0,1)$, \quote {black} is $0,0,0,1$ \NC\NR +\stoptabulate + +If the color model of the internal object was \type{uninitialized}, then +it was initialized to the values representing \quote {black} in the colorspace +\type{defaultcolormodel} that was in effect at the time of the \type{shipout}. + +\subsubsection{Transforms} + +Each transform is a six-item array. + +\starttabulate[|l|l|p|] +\NC 1 \NC number \NC represents x \NC\NR +\NC 2 \NC number \NC represents y \NC\NR +\NC 3 \NC number \NC represents xx \NC\NR +\NC 4 \NC number \NC represents yx \NC\NR +\NC 5 \NC number \NC represents xy \NC\NR +\NC 6 \NC number \NC represents yy \NC\NR +\stoptabulate + +Note that the translation (index 1 and 2) comes first. This differs +from the ordering in \POSTSCRIPT, where the translation comes last. + +\subsubsection{Dashes} + +Each \type{dash} is two-item hash, using the same model as \POSTSCRIPT\ +for the representation of the dashlist. \type{dashes} is an array of +\quote {on} and \quote {off}, values, and \type{offset} is the phase of the pattern. + +\starttabulate[|l|l|p|] +\NC dashes \NC hash \NC an array of on-off numbers \NC\NR +\NC offset \NC number \NC the starting offset value \NC\NR +\stoptabulate + +\subsection{Character size information} + +These functions find the size of a glyph in a defined font. The +\type{fontname} is the same name as the argument to \type{infont}; +the \type{char} is a glyph id in the range 0 to 255; the returned +\type{w} is in AFM units. + +\subsubsection{\luatex{mp.char_width}} + +\startfunctioncall +<number> w = mp.char_width(<string> fontname, <number> char) +\stopfunctioncall + +\subsubsection{\luatex{mp.char_height}} + +\startfunctioncall +<number> w = mp.char_height(<string> fontname, <number> char) +\stopfunctioncall + +\subsubsection{\luatex{mp.char_depth}} + +\startfunctioncall +<number> w = mp.char_depth(<string> fontname, <number> char) +\stopfunctioncall + +\section{The \luatex{node} library} + +The \luatex{node} library contains functions that facilitate dealing +with (lists of) nodes and their values. They allow you to create, alter, +copy, delete, and insert \LUATEX\ node objects, the core +objects within the typesetter. + +\LUATEX\ nodes are represented in \LUA\ as userdata with +the metadata type \luatex{luatex.node}. The various parts within +a node can be accessed using named fields. + +Each node has at least the three fields \type{next}, \type{id}, and +\type{subtype}: + +\startitemize[intro] + +\item The \type{next} field returns the userdata +object for the next node in a linked list of nodes, or +nil, if there is no next node. + +\item The \type{id} indicates \TEX's \quote{node type}. The field \type{id} +has a numeric value for efficiency reasons, but some of the library +functions also accept a string value instead of \type{id}. + +\item The \type{subtype} is another number. It often gives further information +about a node of a particular \type{id}, but it is most important when dealing +with \quote{whatsits}, because they are differentiated solely based on their +\type{subtype}. +\stopitemize + +The other available fields depend on the \type{id} (and for \quote{whatsits}, the +\type{subtype}) of the node. Further details on the various fields and their +meanings are given in~\in{chapter}[nodes]. + +Support for \type{unset} (alignment) nodes is partial: +they can be queried and modified from \LUA\ code, but not created. + +Nodes can be compared to each other, but: you are actually comparing +indices into the node memory. This means that equality tests can only +be trusted under very limited conditions. It will not work correctly +in any situation where one of the two nodes has been freed and|/|or +reallocated: in that case, there will be false positives. + +At the moment, memory management of nodes should still be done +explicitly by the user. Nodes are not \quote{seen} by the \LUA\ +garbage collector, so you have to call the node freeing functions +yourself when you are no longer in need of a node (list). Nodes form +linked lists without reference counting, so you have to be careful +that when control returns back to \LUATEX\ itself, you have not +deleted nodes that are still referenced from a \type{next} pointer +elsewhere, and that you did not create nodes that are referenced more +than once. + +There are statistics available with regards to the allocated node memory, +which can be handy for tracing. + +\subsection{Node handling functions} + +\subsubsection{\luatex{node.types}} + +\startfunctioncall +table t = node.types() +\stopfunctioncall + +This function returns an array that maps node id numbers to node type +strings, providing an overview of the possible top|-|level \type{id} +types. + +\subsubsection{\luatex{node.whatsits}} + +\startfunctioncall +table t = node.whatsits() +\stopfunctioncall + +\TEX's \quote{whatsits} all have the same \type{id}. The various subtypes +are defined by their \type{subtype}. The function is much like +\luatex{node.types}, except that it provides an array of \type{subtype} +mappings. + +\subsubsection{\luatex{node.id}} + +\startfunctioncall +<number> id = node.id(<string> type) +\stopfunctioncall + +This converts a single type name to its internal numeric +representation. + +\subsubsection{\luatex{node.subtype}} + +\startfunctioncall +<number> subtype = node.subtype(<string> type) +\stopfunctioncall + +This converts a single whatsit name to its internal numeric +representation (\type{subtype}). + +\subsubsection{\luatex{node.type}} + +\startfunctioncall +<string> type = node.type(<number> id) +\stopfunctioncall + +This converts a internal numeric representation to an external string +representation. + +\subsubsection{\luatex{node.fields}} + +\startfunctioncall +table t = node.fields(<number> id) +table t = node.fields(<number> id, <number> subtype) +\stopfunctioncall + +This function returns an array of valid field names for a particular +type of node. If you want to get the valid fields for a +\quote{whatsit}, you have to supply the second argument also. In other +cases, any given second argument will be silently ignored. + +This function accepts string \type{id} and \type{subtype} values as +well. + +\subsubsection{\luatex{node.has_field}} + +\startfunctioncall +<boolean> t = node.has_field(<node> n, <string> field) +\stopfunctioncall + +This function returns a boolean that is only true if \type{n} is +actually a node, and it has the field. + +\subsubsection{\luatex{node.new}} + +\startfunctioncall +<node> n = node.new(<number> id) +<node> n = node.new(<number> id, <number> subtype) +\stopfunctioncall + +Creates a new node. All of the new node's fields are initialized to +either zero or nil except for \type{id} and \type{subtype} (if +supplied). If you want to create a new whatsit, then the second +argument is required, otherwise it need not be present. As with all +node functions, this function creates a node on the \TEX\ level. + +This function accepts string \type{id} and \type{subtype} values as +well. + +\subsubsection{\luatex{node.free}} + +\startfunctioncall +node.free(<node> n) +\stopfunctioncall + +Removes the node \type{n} from \TEX's memory. Be careful: no checks +are done on whether this node is still pointed to from a register or some +\type{next} field: it is up to you to make sure that the internal data +structures remain correct. + +\subsubsection{\luatex{node.flush_list}} + +\startfunctioncall +node.flush_list(<node> n) +\stopfunctioncall + +Removes the node list \type{n} and the complete node list following +\type{n} from \TEX's memory. Be careful: no checks are done on whether +any of these nodes is still pointed to from a register or some +\type{next} field: it is up to you to make sure that the internal data +structures remain correct. + +\subsubsection{\luatex{node.copy}} + +\startfunctioncall +<node> m = node.copy(<node> n) +\stopfunctioncall + +Creates a deep copy of node \type{n}, including all nested lists as in +the case of a hlist or vlist node. Only the \type{next} field is not +copied. + +\subsubsection{\luatex{node.copy_list}} + +\startfunctioncall +<node> m = node.copy_list(<node> n) +<node> m = node.copy_list(<node> n, <node> m) +\stopfunctioncall + +Creates a deep copy of the node list that starts at \type{n}. If +\type{m} is also given, the copy stops just before node \type{m}. + +\subsubsection{\luatex{node.hpack}} + +\startfunctioncall +<node> h, <number> b = node.hpack(<node> n) +<node> h, <number> b = node.hpack(<node> n, <number> w, <string> info) +<node> h, <number> b = node.hpack(<node> n, <number> w, <string> info, <string> dir) +\stopfunctioncall + +This function creates a new hlist by packaging the list that begins at node +\type{n} into a horizontal box. With only a single argument, this box +is created using the natural width of its components. In the three +argument form, \type{info} must be either \type{additional} or +\type{exactly}, and \type{w} is the additional (\tex{hbox spread}) +or exact (\tex{hbox to}) width to be used. + +Direction support added in \LUATEX\ 0.45. + +The second return value is the badness of the generated box, +this extension was added in 0.51. + +Caveat: at this moment, there can be unexpected side|-|effects to this +function, like updating some of the \tex{marks} and \tex{inserts}. +Also note that the content of \type{h} is the original node list +\type{n}: if you call \type{node.free(h)} you will also free the +node list itself, unless you explicitly set the \type{list} field +to \type{nil} beforehand. And in a similar way, calling +\type{node.free(n)} will invalidate \type{h} as well! + +\subsubsection{\luatex{node.vpack} (since 0.36)} + +\startfunctioncall +<node> h, <number> b = node.vpack(<node> n) +<node> h, <number> b = node.vpack(<node> n, <number> w, <string> info) +<node> h, <number> b = node.vpack(<node> n, <number> w, <string> info, <string> dir) +\stopfunctioncall + +This function creates a new vlist by packaging the list that begins at node +\type{n} into a vertical box. With only a single argument, this box +is created using the natural width of its components. In the three +argument form, \type{info} must be either \type{additional} or +\type{exactly}, and \type{w} is the additional (\tex{vbox spread}) or exact (\tex{vbox to}) height to be used. + +Direction support added in \LUATEX\ 0.45. + +The second return value is the badness of the generated box, +this extension was added in 0.51. + +See the description of \type{node.hpack()} for a few memory allocation +caveats. + +\subsubsection{\luatex{node.dimensions} (0.43)} + +\startfunctioncall +<number> w, <number> h, <number> d = node.dimensions(<node> n) +<number> w, <number> h, <number> d = node.dimensions(<node> n, <node> t) +\stopfunctioncall + +This function calculates the natural in-line dimensions of the node +list starting at node \type{n} and terminating just before node \type{t} +(or nil, if there is no second argument). The return values are scaled +points. An alternative format that starts with glue parameters as the +first three arguments is also possible: + +\startfunctioncall +<number> w, <number> h, <number> d = + node.dimensions(<number> glue_set, <number> glue_sign, + <number> glue_order, <node> n) +<number> w, <number> h, <number> d = + node.dimensions(<number> glue_set, <number> glue_sign, + <number> glue_order, <node> n, <string> dir) +<number> w, <number> h, <number> d = + node.dimensions(<number> glue_set, <number> glue_sign, + <number> glue_order, <node> n, <node> t) +<number> w, <number> h, <number> d = + node.dimensions(<number> glue_set, <number> glue_sign, + <number> glue_order, <node> n, <node> t, <string> dir) +\stopfunctioncall + +This calling method takes glue settings into account and is especially +useful for finding the actual width of a sublist of nodes that are +already boxed, for example in code like this, which prints the +width of the space inbetween the \type{a} and \type{b} as it would +be if \type{\box0} was used as-is: + +\starttyping +\setbox0 = \hbox to 20pt {a b} + +\directlua{print (node.dimensions(tex.box[0].glue_set, + tex.box[0].glue_sign, + tex.box[0].glue_order, + tex.box[0].list.next, + node.tail(tex.box[0].list))) } +\stoptyping + +Direction support added in \LUATEX\ 0.45. + +\subsubsection{\luatex{node.mlist_to_hlist}} + +\startfunctioncall +<node> h = node.mlist_to_hlist(<node> n, + <string> displaytype, <boolean> penalties) +\stopfunctioncall + +This runs the internal mlist to hlist conversion, converting the math list in +\type{n} into the horizontal list \type{h}. The interface is exactly the same as +for the callback \type{mlist_to_hlist}.) + +\subsubsection{\luatex{node.slide}} + +\startfunctioncall +<node> m = node.slide(<node> n) +\stopfunctioncall + +Returns the last node of the node list that starts at \type{n}. As a +side|-|effect, it also creates a reverse chain of \type{prev} pointers +between nodes. + +\subsubsection{\luatex{node.tail}} + +\startfunctioncall +<node> m = node.tail(<node> n) +\stopfunctioncall + +Returns the last node of the node list that starts at \type{n}. + + +\subsubsection{\luatex{node.length}} + +\startfunctioncall +<number> i = node.length(<node> n) +<number> i = node.length(<node> n, <node> m) +\stopfunctioncall + +Returns the number of nodes contained in the node list that starts at +\type{n}. If \type{m} is also supplied it stops at \type{m} instead of +at the end of the list. The node \type{m} is not counted. + +\subsubsection{\luatex{node.count}} + +\startfunctioncall +<number> i = node.count(<number> id, <node> n) +<number> i = node.count(<number> id, <node> n, <node> m) +\stopfunctioncall + +Returns the number of nodes contained in the node list that starts at +\type{n} that have an matching \type{id} field. +If \type{m} is also supplied, counting stops at \type{m} instead of at +the end of the list. The node \type{m} is not counted. + +This function also accept string \type{id}'s. + +\subsubsection{\luatex{node.traverse}} + +\startfunctioncall +<node> t = node.traverse(<node> n) +\stopfunctioncall + +This is an iterator that loops over the node list that starts at \type{n}. + +\subsubsection{\luatex{node.traverse_id}} + +\startfunctioncall +<node> t = node.traverse_id(<number> id, <node> n) +\stopfunctioncall + +This is an iterator that loops over all the nodes in the list that +starts at \type{n} that have a matching \type{id} field. + +\subsubsection{\luatex{node.remove}} + +\startfunctioncall +<node> head, current = node.remove(<node> head, <node> current) +\stopfunctioncall + +This function removes the node \type{current} from the list following +\type{head}. It is your responsibility to make sure it is really part +of that list. The return values are the new \type{head} and +\type{current} nodes. The returned \type{current} is the +node in the calling argument, and is only passed back as a convenience +(its \type{next} field will be cleared). The returned \type{head} is +more important, because if the function is called with \type{current} +equal to \type{head}, it will be changed. + +\subsubsection{\luatex{node.insert_before}} + +\startfunctioncall +<node> head, new = node.insert_before(<node> head, <node> current, <node> new) +\stopfunctioncall + +This function inserts the node \type{new} before \type{current} into +the list following \type{head}. It is your responsibility to make sure +that \type{current} is really part of that list. The return values are +the (potentially mutated) \type{head} and the \type{new}, set up to +be part of the list (with correct \type{next} field). If \type{head} +is initially \type{nil}, it will become \type{new}. + +\subsubsection{\luatex{node.insert_after}} + +\startfunctioncall +<node> head, new = node.insert_after(<node> head, <node> current, <node> new) +\stopfunctioncall + +This function inserts the node \type{new} after \type{current} into +the list following \type{head}. It is your responsibility to make sure +that \type{current} is really part of that list. The return values are +the \type{head} and the \type{new}, set up to be part of the list +(with correct \type{next} field). If \type{head} is initially +\type{nil}, it will become \type{new}. + +\subsubsection{\luatex{node.first_character}} + +\startfunctioncall +<node> n = node.first_character(<node> n) +<node> n = node.first_character(<node> n, <node> m) +\stopfunctioncall + +Returns the first node that is a glyph node with a subtype indicating +it is a character, or \type{nil}. + +\subsubsection{\luatex{node.ligaturing}} + +\startfunctioncall +<node> h, <node> t, <boolean> success = node.ligaturing(<node> n) +<node> h, <node> t, <boolean> success = node.ligaturing(<node> n, <node> m) +\stopfunctioncall + +Apply \TEX-style ligaturing to the specified nodelist. The tail node +\type{m} is optional. The two returned nodes \type{h} and \type{t} are +the new head and tail (both \type{n} and \type{m} can change into +a new ligature). + +\subsubsection{\luatex{node.kerning}} + +\startfunctioncall +<node> h, <node> t, <boolean> success = node.kerning(<node> n) +<node> h, <node> t, <boolean> success = node.kerning(<node> n, <node> m) +\stopfunctioncall + +Apply \TEX|-|style kerning to the specified nodelist. The tail node +\type{m} is optional. The two returned nodes \type{h} and \type{t} are +the head and tail (either one of these can be an inserted kern node, +because special kernings with word boundaries are possible). + +\subsubsection{\luatex{node.unprotect_glyphs}} + +\startfunctioncall +node.unprotect_glyphs(<node> n) +\stopfunctioncall + +Subtracts 256 from all glyph node subtypes. This and the next +function are helpers to convert from \type{characters} to +\type{glyphs} during node processing. + +\subsubsection{\luatex{node.protect_glyphs}} + +\startfunctioncall +node.protect_glyphs(<node> n) +\stopfunctioncall + +Adds 256 to all glyph node subtypes in the node list starting at +\type{n}, except that if the value is 1, it adds only 255. The special +handling of 1 means that \type{characters} will become \type{glyphs} +after subtraction of 256. + +\subsubsection{\luatex{node.last_node}} + +\startfunctioncall +<node> n = node.last_node() +\stopfunctioncall + +This function pops the last node from \TEX's \quote{current list}. +It returns that node, or \type{nil} if the current list is empty. + +\subsubsection{\luatex{node.write}} + +\startfunctioncall +node.write(<node> n) +\stopfunctioncall + +This is an experimental function that will append a node list to +\TEX's \quote {current list} (the node list is not deep-copied +any more since version 0.38). There is no error checking yet! + +\subsubsection{\luatex{node.protrusion_skippable} (0.60.1)} +\startfunctioncall +boolean <yes> = node.protrusion_skippable(<node> n) +\stopfunctioncall + +Returns \type{true} if this node can be skipped for glyph protrusion +line boundary discovery. + +\subsubsection{\luatex{node.protrusion_skipable} (0.53)} + +Older version of \type{node.protrusion_skippable}, with typing error. +This alias will go away soon, please use the version with two p's. + +\subsection{Attribute handling} + +Attributes appear as linked list of userdata objects in the +\type{attr} field of individual nodes. They can be handled +individually, but it is much safer and more efficient to use the +dedicated functions associated with them. + +\subsubsection{\luatex{node.has_attribute}} + +\startfunctioncall +<number> v = node.has_attribute(<node> n, <number> id) +<number> v = node.has_attribute(<node> n, <number> id, <number> val) +\stopfunctioncall + +Tests if a node has the attribute with number \type{id} set. If +\type{val} is also supplied, also tests if the value matches \type{val}. +It returns the value, or, if no match is found, nil. + +\subsubsection{\luatex{node.set_attribute}} + +\startfunctioncall +node.set_attribute(<node> n, <number> id, <number> val) +\stopfunctioncall + +Sets the attribute with number \type{id} to the value +\type{val}. Duplicate assignments are ignored. {\em [needs explanation]} + +\subsubsection{\luatex{node.unset_attribute}} + +\startfunctioncall +<number> v = node.unset_attribute(<node> n, <number> id, <number> val) +<number> v = node.unset_attribute(<node> n, <number> id) +\stopfunctioncall + +Unsets the attribute with number \type{id}. If \type{val} is also supplied, +it will only perform this operation if the value matches \type{val}. +Missing attributes or attribute|-|value pairs are ignored. + +If the attribute was actually deleted, returns its old +value. Otherwise, returns nil. + +\section{The \luatex{pdf} library} + +This contains variables and functions that are related to the \PDF\ backend. + +%*********************************************************************** + +\subsubsubject{\luatex{pdf.mapfile()}, \luatex{pdf.mapline()} (new in 0.53.0)} + +These two functions can be used to replace primitives \type{\pdfmapfile} +and \type{\pdfmapline} from \PDFTEX. They expect a string as only parameter +and have no return value. + +The functions replace also the former variables +\luatex{pdf.pdfmapfile} and \luatex{pdf.pdfmapline}. + +%*********************************************************************** + +\subsubsubject{\luatex{pdf.catalog}, \luatex{pdf.info}, + \luatex{pdf.names}, \luatex{pdf.trailer} (new in 0.53.0)} + +These variables offer a read-write interface to the corresponding +\PDFTEX\ token lists. The value types are strings. + +The corresponding \quote{\type{pdf}} parameter names +\luatex{pdf.pdfcatalog}, \luatex{pdf.pdfinfo}, \luatex{pdf.pdfnames}, +and \luatex{pdf.pdftrailer} (all new in 0.47.0) +still work, but are obsolescent (since 0.53.0). + +Note: this interface will almost certainly change in the future. + +%*********************************************************************** + +\subsubsubject{\luatex{pdf.pageattributes}, \luatex{pdf.pageresources}, + \luatex{pdf.pagesattributes} (new in 0.53.0)} + +These variables offer a read-write interface to related +token lists. The value types are strings. The variables have no +interaction with the corresponding \PDFTEX\ token registers +\tex{pageattrib}, \tex{pageresources}, and \tex{pagesattrib}, +but they are written out to the \PDF\ file directly after +the \PDFTEX\ token registers. + +%*********************************************************************** + +\subsubsubject{\luatex{pdf.h}, \luatex{pdf.v}} + +These are the \type{h} and \type{v} values +that define the current location on the output page, +measured from its lower left corner. +The values can be queried % and set +using scaled points as units. + +\starttyping +pdf.h +pdf.v +\stoptyping + +Note: this interface will almost certainly change in the future. + +% not implemented yet: +% \subsubsubject{\luatex{pdf.seth()}, \luatex{pdf.setv()}} +% +% The function calls for position setting, +% associated with \type{pdf.h} and \type{pdf.v} are +% +% \startfunctioncall +% pdf.seth(<number> n) +% <number> n = pdf.h +% pdf.setv(<number> n) +% <number> n = pdf.v +% \stopfunctioncall + +\subsubsubject{\luatex{pdf.print()}} + +A print function to write stuff to the \PDF\ document +that can be used from within a \tex{latelua} argument. +This function is not to be used inside \tex{directlua} +unless you know {\it exactly} what you are doing. + +\startfunctioncall +pdf.print(<string> s) +pdf.print(<string> type, <string> s) +\stopfunctioncall + +The optional parameter can be used to mimic the behavior of +\tex{pdfliteral}: the \type{type} is \type{direct} or \type{page}. + +\subsubsubject{\luatex{pdf.immediateobj()}} + +This function creates a \PDF\ object +and immediately write it to the \PDF\ file. +It is modelled after \PDFTEX's \tex{immediate}\tex{pdfobj} primitives. +All function variants return the object number +of the newly generated object. + +\startfunctioncall +n = pdf.immediateobj(<string> objtext) +n = pdf.immediateobj("file", <string> filename) +n = pdf.immediateobj("stream", <string> streamtext {, <string> attrtext}) +n = pdf.immediateobj("streamfile", <string> filename, {, <string> attrtext}) +\stopfunctioncall + +The 1st version puts the \type{objtext} raw into an object. +Only the object wrapper is automatically generated, +but any internal structure (like \type{<< >>} dictionary markers) +needs to provided by the user. +The 2nd version with keyword \type{"file"} as 1st argument +puts the contents of the file with name \type{filename} raw into the object. +The 3rd version with keyword \type{"stream"} creates a stream object +and puts the \type{streamtext} raw into the stream. +The stream length is automatically calculated. +The optional \type{attrtext} goes into the dictionary of that object. +The 4th version with keyword \type{"streamfile"} does the same as the 3rd one, +it just reads the stream data raw from a file. + +An optional first argument can be given to make the function use a +previously reserved \PDF\ object. + +\startfunctioncall +n = pdf.immediateobj(<integer n>, <string> objtext) +n = pdf.immediateobj(<integer n>, "file", <string> filename) +n = pdf.immediateobj(<integer n>, "stream", <string> streamtext {, <string> attrtext}) +n = pdf.immediateobj(<integer n>, "streamfile", <string> filename, {, <string> attrtext}) +\stopfunctioncall + +\subsubsubject{\luatex{pdf.obj()}} + +This function creates a \PDF\ object, +which is written to the \PDF\ file only when referenced. + +All function variants return the object number of the newly generated +object, and there are two separate calling modes. + +The first mode is modelled after \PDFTEX's \tex{pdfobj} primitive. + +\startfunctioncall +n = pdf.obj(<string> objtext) +n = pdf.obj("file", <string> filename) +n = pdf.obj("stream", <string> streamtext {, <string> attrtext}) +n = pdf.obj("streamfile", <string> filename, {, <string> attrtext}) +\stopfunctioncall + +An optional first argument can be given to make the function use a +previously reserved \PDF\ object. + +\startfunctioncall +n = pdf.obj(<integer> n, <string> objtext) +n = pdf.obj(<integer> n, "file", <string> filename) +n = pdf.obj(<integer> n, "stream", <string> streamtext {, <string> attrtext}) +n = pdf.obj(<integer> n, "streamfile", <string> filename, {, <string> attrtext}) +\stopfunctioncall + +The second mode accepts a single argument table with key--value pairs. + +\startfunctioncall +n = pdf.obj{ type = <string>, + immmediate = <boolean>, + objnum = <number>, + attr = <string>, + compresslevel = <number>, + objcompression = <boolean>, + file = <string>, + string = <string>} +\stopfunctioncall + +The \type{string} field can have the values \type{raw} and +\type{stream}, this field is required, the others are optional +(within constraints). + +Note: this mode makes \type{pdf.obj} look more flexible than it +actually is: the constraints from the separate parameter version +still apply, so for example you can't have both \type{string} and +\type{file} at the same time. + +\subsubsubject{\luatex{pdf.reserveobj()}} + +This function creates an empty \PDF\ object and returns its number. + +\startfunctioncall +n = pdf.reserveobj() +n = pdf.reserveobj("annot") +\stopfunctioncall + +\subsubsubject{\luatex{pdf.registerannot()} (new in 0.47.0)} + +This function adds an object number to the \type{/Annots} array for the +current page without doing anything else. This function can only be +used from within \type{\latelua}. + +\startfunctioncall +pdf.registerannot (<number> objnum) +\stopfunctioncall + + +\section{The \luatex{status} library} + +This contains a number of run|-|time configuration items that +you may find useful in message reporting, as well as an iterator +function that gets all of the names and values as a table. + +\startfunctioncall +<table> info = status.list() +\stopfunctioncall + +The keys in the table are the known items, the value is the +current value. Almost all of the values in \type{status} are +fetched through a metatable at run|-|time whenever they are +accessed, so you cannot use \type{pairs} on \type{status}, but you +{\it can\/} use \type{pairs} on \type{info}, of course. If you do +not need the full list, you can also ask for a single item by +using its name as an index into \type{status}. + +The current list is: + +\starttabulate[|lT|p|] +\NC \ssbf key \NC \bf explanation \NC\NR +\NC pdf_gone\NC written \PDF\ bytes \NC \NR +\NC pdf_ptr\NC not yet written \PDF\ bytes \NC \NR +\NC dvi_gone\NC written \DVI\ bytes \NC \NR +\NC dvi_ptr\NC not yet written \DVI\ bytes \NC \NR +\NC total_pages\NC number of written pages \NC \NR +\NC output_file_name\NC name of the \PDF\ or \DVI\ file \NC \NR +\NC log_name\NC name of the log file \NC \NR +\NC banner\NC terminal display banner \NC \NR +\NC var_used\NC variable (one|-|word) memory in use \NC \NR +\NC dyn_used\NC token (multi|-|word) memory in use \NC \NR +\NC str_ptr\NC number of strings \NC \NR +\NC init_str_ptr\NC number of \INITEX\ strings \NC \NR +\NC max_strings\NC maximum allowed strings \NC \NR +\NC pool_ptr\NC string pool index \NC \NR +\NC init_pool_ptr\NC \INITEX\ string pool index \NC \NR +\NC pool_size\NC current size allocated for string characters \NC \NR +\NC node_mem_usage\NC a string giving insight into currently used nodes\NC\NR +\NC var_mem_max\NC number of allocated words for nodes\NC \NR +\NC fix_mem_max\NC number of allocated words for tokens\NC \NR +\NC fix_mem_end\NC maximum number of used tokens\NC \NR +\NC cs_count\NC number of control sequences \NC \NR +\NC hash_size\NC size of hash \NC \NR +\NC hash_extra\NC extra allowed hash \NC \NR +\NC font_ptr\NC number of active fonts \NC \NR +\NC max_in_stack\NC max used input stack entries \NC \NR +\NC max_nest_stack\NC max used nesting stack entries \NC \NR +\NC max_param_stack\NC max used parameter stack entries \NC \NR +\NC max_buf_stack\NC max used buffer position \NC \NR +\NC max_save_stack\NC max used save stack entries \NC \NR +\NC stack_size\NC input stack size \NC \NR +\NC nest_size\NC nesting stack size \NC \NR +\NC param_size\NC parameter stack size \NC \NR +\NC buf_size\NC current allocated size of the line buffer \NC \NR +\NC save_size\NC save stack size \NC \NR +\NC obj_ptr\NC max \PDF\ object pointer \NC \NR +\NC obj_tab_size\NC \PDF\ object table size \NC \NR +\NC pdf_os_cntr\NC max \PDF\ object stream pointer \NC \NR +\NC pdf_os_objidx\NC \PDF\ object stream index \NC \NR +\NC pdf_dest_names_ptr\NC max \PDF\ destination pointer \NC \NR +\NC dest_names_size\NC \PDF\ destination table size \NC \NR +\NC pdf_mem_ptr\NC max \PDF\ memory used \NC \NR +\NC pdf_mem_size\NC \PDF\ memory size \NC \NR +\NC largest_used_mark\NC max referenced marks class \NC \NR +\NC filename\NC name of the current input file \NC \NR +\NC inputid\NC numeric id of the current input \NC \NR +\NC linenumber\NC location in the current input file\NC \NR +\NC lasterrorstring\NC last error string\NC \NR +\NC luabytecodes\NC number of active \LUA\ bytecode registers\NC \NR +\NC luabytecode_bytes\NC number of bytes in \LUA\ bytecode registers\NC \NR +\NC luastate_bytes\NC number of bytes in use by \LUA\ interpreters\NC \NR +\NC output_active\NC \type{true} if the \tex{output} routine is active\NC \NR +\NC callbacks\NC total number of executed callbacks so far\NC \NR +\NC indirect_callbacks\NC number of those that were themselves + a result of other callbacks (e.g. file readers)\NC \NR +\NC luatex_svn\NC the luatex repository id (added in 0.51)\NC\NR +\NC luatex_version\NC the luatex version number (added in 0.38)\NC\NR +\NC luatex_revision\NC the luatex revision string (added in 0.38)\NC\NR +\NC ini_version\NC \type{true} if this is an \INITEX\ run (added in 0.38)\NC\NR +\stoptabulate + + +\section{The \luatex{tex} library} + +The \luatex{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 \tex{the} +\item It is a single token. +\item Some special others, see the list below +\stopitemize + +This excludes parameters that need extra arguments, like +\tex{the}\tex{scriptfont}. + +The subset comprising simple integer and dimension registers are +writable as well as readable (stuff like \tex{tracingcommands} and +\tex{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 (<string> n, ...) +tex.set ('global', <string> n, ...) +... = tex.get (<string> n) +\stopfunctioncall + +\subsubsection{Integer parameters} + +The integer parameters accept and return \LUA\ numbers. + +Read-write: + +\startcolumns[n=2] +\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.pdfadjustspacing +tex.pdfcompresslevel +tex.pdfdecimaldigits +tex.pdfgamma +tex.pdfgentounicode +tex.pdfimageapplygamma +tex.pdfimagegamma +tex.pdfimagehicolor +tex.pdfimageresolution +tex.pdfinclusionerrorlevel +tex.pdfminorversion +tex.pdfobjcompresslevel +tex.pdfoutput +tex.pdfpagebox +tex.pdfpkresolution +tex.pdfprotrudechars +tex.pdftracingfonts +tex.pdfuniqueresname +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 +\stopcolumns + +Read|-|only: + +\startcolumns[n=3] +\starttyping +tex.deadcycles +tex.insertpenalties +tex.parshape +tex.prevgraf +tex.spacefactor +\stoptyping +\stopcolumns + +\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: + +\startcolumns[n=3] +\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.pdfdestmargin +tex.pdfeachlinedepth +tex.pdfeachlineheight +tex.pdffirstlineheight +tex.pdfhorigin +tex.pdflastlinedepth +tex.pdflinkmargin +tex.pdfpageheight +tex.pdfpagewidth +tex.pdfpxdimen +tex.pdfthreadmargin +tex.pdfvorigin +tex.predisplaysize +tex.scriptspace +tex.splitmaxdepth +tex.vfuzz +tex.voffset +tex.vsize +\stoptyping +\stopcolumns + +Read|-|only: + +\startcolumns[n=3] +\starttyping +tex.pagedepth +tex.pagefilllstretch +tex.pagefillstretch +tex.pagefilstretch +tex.pagegoal +tex.pageshrink +tex.pagestretch +tex.pagetotal +tex.prevdepth +\stoptyping +\stopcolumns + +\subsubsection{Direction parameters} + +The direction parameters are read|-|only and return a \LUA\ string. + +\startcolumns[n=3] +\starttyping +tex.bodydir +tex.mathdir +tex.pagedir +tex.pardir +tex.textdir +\stoptyping +\stopcolumns + +\subsubsection{Glue parameters} + +All glue parameters are to be used read|-|only and return a userdata object that +represents a \type{glue_spec} node. + +\startcolumns[n=3] +\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 +\stopcolumns + +\subsubsection{Muglue parameters} + +All muglue parameters are to be used read|-|only and return a \LUA\ string. + +\startcolumns[n=3] +\starttyping +tex.medmuskip +tex.thickmuskip +tex.thinmuskip +\stoptyping +\stopcolumns + +\subsubsection{Tokenlist parameters} + +The tokenlist parameters accept and return \LUA\ strings. \LUA\ strings are +converted to and from token lists using \tex{the}\tex{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. + +\startcolumns[n=3] +\starttyping +tex.errhelp +tex.everycr +tex.everydisplay +tex.everyeof +tex.everyhbox +tex.everyjob +tex.everymath +tex.everypar +tex.everyvbox +tex.output +tex.pdfpageattr +tex.pdfpageresources +tex.pdfpagesattr +tex.pdfpkmode +\stoptyping +\stopcolumns + + +\subsection{Convert commands} + +All \quote{convert} commands are read|-|only and return a \LUA\ string. +The supported commands at this moment are: + +\startcolumns[n=2] +\starttyping +tex.AlephVersion +tex.Alephrevision +tex.OmegaVersion +tex.Omegarevision +tex.eTeXVersion +tex.eTeXrevision +tex.formatname +tex.jobname +tex.luatexrevision +tex.luatexdatestamp +tex.pdfnormaldeviate +tex.pdftexbanner +tex.pdftexrevision +tex.fontname(number) +tex.pdffontname(number) +tex.pdffontobjnum(number) +tex.pdffontsize(number) +tex.uniformdeviate(number) +tex.number(number) +tex.romannumeral(number) +tex.pdfpageref(number) +tex.pdfxformname(number) +tex.fontidentifier(number) +\stoptyping +\stopcolumns + +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). + +\subsection{Last item commands} + +All \quote{last item} commands are read|-|only and return a number. + +The supported commands at this moment are: + +\startcolumns[n=3] +\starttyping +tex.lastpenalty +tex.lastkern +tex.lastskip +tex.lastnodetype +tex.inputlineno +tex.pdftexversion +tex.pdflastobj +tex.pdflastxform +tex.pdflastximage +tex.pdflastximagepages +tex.pdflastannot +tex.pdflastxpos +tex.pdflastypos +tex.pdfrandomseed +tex.pdflastlink +tex.luatexversion +tex.Alephversion +tex.Omegaversion +tex.Alephminorversion +tex.Omegaminorversion +tex.eTeXminorversion +tex.eTeXversion +tex.currentgrouplevel +tex.currentgrouptype +tex.currentiflevel +tex.currentiftype +tex.currentifbranch +tex.pdflastximagecolordepth +\stoptyping +\stopcolumns + +\subsection{Attribute, count, dimension, skip and token registers} + +\TEX's attributes (\tex{attribute}), counters (\tex{count}), +dimensions (\tex{dimen}), skips (\tex{skip}) and token (\tex{toks}) +registers can be accessed and written to using two times five virtual +sub|-|tables of the \luatex{tex} table: + +\startcolumns[n=3] +\starttyping +tex.attribute +tex.count +tex.dimen +tex.skip +tex.toks +\stoptyping +\stopcolumns + +It is possible to use the names of relevant \tex{attributedef}, \tex{countdef}, +\tex{dimendef}, \tex{skipdef}, or \tex{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 \tex{countdef} (or \tex{attributedef}, or +\tex{dimendef}, or \tex{skipdef}, or \tex{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 \tex{the}\tex{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 (<number> n, <node> s) +tex.setskip (<string> s, <node> s) +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 + +In the function-based interface, it is possible to define values +globally by using the string \type{'global'} as the first function argument. + +\subsection{Box registers} + +The current dimensions of \tex{box} registers can be read and +altered using three other virtual sub|-|tables : + +\starttyping +tex.wd +tex.ht +tex.dp +\stoptyping + +{\bf note: these three virtual tables are deprecated and will +be removed in luatex 0.70. You should switch to using \type{tex.box[].width} +etc. instead, see below.} + +\blank + +It is also possible to set and query actual boxes, using the node +interface as defined in the \luatex{node} library: + +\starttyping +tex.box +\stoptyping + +for array access, or + +\starttyping +tex.setbox(<number> n, <node> s) +tex.setbox('global', <number> n, <node> s) +<node> n = tex.getbox(<number> n) +\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 +\tex{box2} will be cleared by \TEX\ commands later on, the contents +of \tex{box0} becomes invalid as well. To prevent this from +happening, always use \luatex{node.copy_list()} unless you are +assigning to a temporary variable: + +\starttyping +tex.box[0] = node.copy_list(tex.box[2]) +\stoptyping + +\subsection{Math parameters} + +It is possible to set and query the internal math parameters +using: + +\startfunctioncall +tex.setmath(<string> n, <string> t, <number> n) +tex.setmath('global', <string> n, <string> t, <number> n) +<number> n = tex.getmath(<string> n, <string> t) +\stopfunctioncall + +As before an optional first parameter of \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 + + +\subsection{Special list heads} + +The virtual table \luatex{tex.lists} contains the set of internal +registers that keep track of building page lists. + + +\starttabulate[|lT|p|] +\NC \bf field \NC \bf description \NC \NR +\NC page_ins_head \NC circular list of pending insertions \NC \NR +\NC contrib_head \NC the recent contributions \NC \NR +\NC page_head \NC the page-so-far \NC \NR +%\NC temp_head \NC \NC \NR +\NC hold_head \NC used for held-over items for next page\NC \NR +\NC adjust_head \NC head of the current \tex{adjust} list \NC \NR +\NC pre_adjust_head \NC head of the current \tex{adjust pre} list\NC \NR +% \NC align_head \NC \NC \NR +\stoptabulate + +\subsection{Semantic nest levels (0.51)} + +The virtual table \luatex{tex.nest} contains the currently active +semantic nesting state. It has two main parts: an 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 assing to the individual values inside the array +items, e.g. \type{tex.nest[tex.nest.ptr].prevdepth}. + +\type{tex.nest[tex.nest.ptr]} is the current nest state, \type{tex.nest[0]} +the outermost (main vertical list) level. + +The known fields are: + +\starttabulate[|lT|l|l|p|] +\NC \ssbf key \NC \bf type \NC \bf modes \NC \bf explanation \NC\NR +\NC mode \NC number \NC all \NC The current mode. This is a number representing the + main mode at this level:\crlf + 0 == no mode (this happens during \type{\write})\crlf + 1 == vertical,\crlf + 127 = horizontal,\crlf + 253 = display math.\crlf + $-1$ == internal vertical,\crlf + $-127$ = restricted horizontal,\crlf + $-253$ = inline math.\NC\NR +\NC modeline \NC number \NC all \NC source input line where this mode was entered in, + negative inside the output routine.\NC\NR +\NC head \NC node \NC all \NC the head of the current list\NC\NR +\NC tail \NC node \NC all \NC the tail of the current list\NC\NR +\NC prevgraf \NC number \NC vmode \NC number of lines in the previous paragraph\NC\NR +\NC prevdepth \NC number \NC vmode \NC depth of the previous paragraph (equal to \type{\pdfignoreddimen} + when it is to be ignored)\NC\NR +\NC spacefactor \NC number \NC hmode \NC the current space factor\NC\NR +\NC dirs \NC node \NC hmode \NC used for temporary storage by the line break algorithm\NC\NR +\NC noad \NC node \NC mmode \NC used for temporary storage of a pending fraction numerator, + for \type{\over} etc.\NC\NR +\NC delimptr \NC node \NC mmode \NC used for temporary storage of the previous math delimiter, + for \type{\middle}.\NC\NR +\NC mathdir \NC boolean \NC mmode \NC true when during math processing the \type{\mathdir} is not + the same as the surrounding \type{\textdir}\NC\NR +\NC mathstyle \NC number \NC mmode \NC the current \type{\mathstyle} \NC\NR +\stoptabulate + + +\subsection{Print functions} + +The \luatex{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 \tex{directlua}. + +The total amount of returnable text from a \tex{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{\luatex{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). This syntax was added in 0.36. + + +The optional parameter can be used to print the strings using the +catcode regime defined by \tex{catcodetable}~\type{n}. If \type{n} is +$-1$, the currently active catcode regime is used. If \type{n} is +$-2$, the resulting catcodes are in the result of \type{\the}: 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 \luatex{tex.print()} command in a +\tex{directlua} will not have the \tex{endlinechar} appended, all +others do. + +\subsubsection{\luatex{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] +\item \TEX\ does not switch to the \quote{new line} state, so + that leading spaces are not ignored. +\item No \tex{endlinechar} is inserted. +\item 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{inbetween} will be gobbled as a result of +the \quote{normal} scanning of \tex{relax}. +\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). This syntax was added in 0.36. + +\subsubsection{\luatex{tex.tprint}} + +\startfunctioncall +tex.tprint({<number> n, <string> s, ...}, {...}) +\stopfunctioncall + +This function is basically a shortcut for repeated calls to +\luatex{tex.sprint(<number> n, <string> s, ...)}, once for each of +the supplied argument tables. + +\subsubsection{\luatex{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 is 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 \tex{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). This syntax was added in 0.36. + + +\subsection{Helper functions} + +\subsubsection{\luatex{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{\luatex{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{\luatex{tex.sp} (0.51)} + +\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] +\item only explicit values are allowed, control sequences are not handled +\item infinite dimension units (\type{fil...}) are forbidden +\item \type{mu} units do not generate an error (but may not be useful either) +\stopitemize + +\subsubsection{\luatex{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). + +\subsection[luaprimitives]{Functions for dealing with primitives } + +\subsubsection{\luatex{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 +and actual primitive (it must be returned by one of the +\type{tex.extraprimitives()} calls explained above, 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. + +Second example: + +\starttyping + tex.enableprimitives('Omega',tex.extraprimitives ('omega')) +\stoptyping + +will define a whole series of csnames like \type{\Omegatextdir}, +\type{\Omegapardir}, etc., but it will stick with \type{\OmegaVersion} +instead of creating the doubly-prefixed \type{\OmegaOmegaVersion}. + +Starting with version 0.39.0 (and this is why the above two functions +are needed), \LUATEX\ in \type{--ini} mode contains only the \TEX82 +primitives and \type{\directlua}, no extra primitives {\bf at all}. + +So, if you want to have all the new functionality available using +their default names, as it is now, you will have to add + +\starttyping + \expandafter\ifx\csname directlua\endcsname \relax \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 runtime. + + +\subsubsection{\luatex{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 out_prim (a) + for _,n in pairs(tex.extraprimitives(a)) do + tex.print(n .. '\\hskip 4pt plus 5em') + end +end +\stopluacode + +\starttabulate[|l|p|] +\NC \bf name\NC \bf values \NC \NR +\NC tex \NC \ctxlua{out_prim('tex') } \NC \NR +\NC core \NC \ctxlua{out_prim('core') } \NC \NR +\NC etex \NC \ctxlua{out_prim('etex') } \NC \NR +\NC pdftex \NC \ctxlua{out_prim('pdftex') } \NC \NR +\NC omega \NC \ctxlua{out_prim('omega') } \NC \NR +\NC aleph \NC \ctxlua{out_prim('aleph') } \NC \NR +\NC luatex \NC \ctxlua{out_prim('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'}. + +Running \type{tex.extraprimitives()} will give you the complete list +of primitives that are not defined at \LUATEX\ 0.39.0 \type{-ini} +startup. It is exactly equivalent to \type{tex.extraprimitives('etex', +'pdftex', 'omega', 'aleph', 'luatex')} + +\subsubsection{\luatex{tex.primitives}} + +\startfunctioncall +<table> t = tex.primitives() +\stopfunctioncall + +This function returns a hash table listing all primitives that \LUATEX\ +knows about. The keys in the hash are primitives names, the values are +tables representing tokens (see~\in{section }[luatokens]). The third value +is always zero. + +\subsection{Core functionality interfaces} + +\subsubsection{\luatex{tex.badness} (0.53)} + +\startfunctioncall +<number> b = tex.badness(<number> f, <number> s) +\stopfunctioncall + +This helper function is useful +during linebreak calculations. \type{f} and \type{s} are scaled values; the function +returns the badness for when total \type{f} 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{\luatex{tex.linebreak} (0.53)} + +\startfunctioncall +local <node> nodelist, <table> info = + tex.linebreak(<node> listhead, <table> parameters) +\stopfunctioncall + +The understood parameters are as follows: + +\starttabulate[|l|l|p|] +\NC \bf name \NC \bf type \NC \bf description \NC \NR +\NC pardir \NC string \NC \NC \NR +\NC pretolerance \NC number \NC \NC \NR +\NC tracingparagraphs \NC number \NC \NC \NR +\NC tolerance \NC number \NC \NC \NR +\NC looseness \NC number \NC \NC \NR +\NC hyphenpenalty \NC number \NC \NC \NR +\NC exhyphenpenalty \NC number \NC \NC \NR +\NC pdfadjustspacing \NC number \NC \NC \NR +\NC adjdemerits \NC number \NC \NC \NR +\NC pdfprotrudechars \NC number \NC \NC \NR +\NC linepenalty \NC number \NC \NC \NR +\NC lastlinefit \NC number \NC \NC \NR +\NC doublehyphendemerits \NC number \NC \NC \NR +\NC finalhyphendemerits \NC number \NC \NC \NR +\NC hangafter \NC number \NC \NC \NR +\NC interlinepenalty \NC number or table \NC if a table, then it is an array like \type{\interlinepenalties}\NC \NR +\NC clubpenalty \NC number or table \NC if a table, then it is an array like \type{\clubpenalties}\NC \NR +\NC widowpenalty \NC number or table \NC if a table, then it is an array like \type{\widowpenalties}\NC \NR +\NC brokenpenalty \NC number \NC \NC \NR +\NC emergencystretch \NC number \NC in scaled points \NC \NR +\NC hangindent \NC number \NC in scaled points \NC \NR +\NC hsize \NC number \NC in scaled points \NC \NR +\NC leftskip \NC glue_spec node \NC \NC \NR +\NC rightskip \NC glue_spec node \NC \NC \NR +\NC pdfeachlineheight \NC number \NC in scaled points \NC \NR +\NC pdfeachlinedepth \NC number \NC in scaled points \NC \NR +\NC pdffirstlineheight \NC number \NC in scaled points \NC \NR +\NC pdflastlinedepth \NC number \NC in scaled points \NC \NR +\NC pdfignoreddimen \NC number \NC in scaled points \NC \NR +\NC parshape \NC table \NC \NC \NR +\stoptabulate + +Note that there is no interface for \type{\displaywidowpenalties}, you +have to pass the right choice for \type{widowpenalties} yourself. + +The meaning of the various keys should be fairly obvious from the +table (the names match the \TEX\ and \PDFTEX\ primitives) except for +the last 5 entries. The four \type{pdf...line...} keys are ignored if +their value equals \type{pdfignoreddimen}. + +It is your own job to make sure that \type{listhead} is a proper +paragraph list: this function does not add any nodes to it. To be +exact, if you want to replace the core line breaking, you may have to +do the following (when you are not actually working in the +\type{pre_line_break} or \type{line_break} callback, or when the +original list starting at listhead was generated in horizontal mode): + +\startitemize +\item add an \quote{indent box} and perhaps a \type{local_par} node at + the start (only if you need them) +\item replace any found final glue by an infinite penalty (or add such + a penalty, if the last node is not a glue) +\item add a glue node for the \type{\parfillskip} after that penalty node +\item make sure all the \type{prev} pointers are OK +\stopitemize + +The result is a node list, it still needs to be vpacked if you +want to assign it to a box. + + +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{\luatex{tex.shipout} (0.51)} + +\startfunctioncall +tex.shipout(<number> n) +\stopfunctioncall + +Ships out box number \type{n} to the output file, and clears the box +register. + + +\section[texconfig]{The \luatex{texconfig} table} + +This is a table that is created empty. A startup \LUA\ script could +fill this table with a number of settings that are read out by +the executable after loading and executing the startup file. + +\starttabulate[|lT|l|l|p|] +\NC \ssbf key \NC \bf type \NC \bf default \NC \bf explanation \NC\NR +\NC kpse_init \NC boolean \NC true \NC \type{false} totally disables \KPATHSEA\ initialisation, + and enables interpretation of the following numeric key--value pairs. + (only ever unset this if you implement {\it all\/} file + find callbacks!)\NC \NR +\NC shell_escape \NC string\NC \type{'f'}\NC Use \type{'y'} or \type{'t'} or \type{'1'} to enable \type{\write18} unconditionally, + \type{'p'} to enable the commands that are listed in \type{shell_escape_commands} (new in 0.37)\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 (new in 0.37)\NC\NR +\NC string_vacancies \NC number\NC 75000\NC cf.\ web2c docs \NC \NR +\NC pool_free \NC number\NC 5000\NC cf.\ web2c docs \NC \NR +\NC max_strings \NC number\NC 15000\NC cf.\ web2c docs \NC \NR +\NC strings_free \NC number\NC 100\NC cf.\ web2c docs \NC \NR +\NC nest_size \NC number\NC 50\NC cf.\ web2c docs \NC \NR +\NC max_in_open \NC number\NC 15\NC cf.\ web2c docs \NC \NR +\NC param_size \NC number\NC 60\NC cf.\ web2c docs \NC \NR +\NC save_size \NC number\NC 4000\NC cf.\ web2c docs \NC \NR +\NC stack_size \NC number\NC 300\NC cf.\ web2c docs \NC \NR +\NC dvi_buf_size \NC number\NC 16384\NC cf.\ web2c docs \NC \NR +\NC error_line \NC number\NC 79\NC cf.\ web2c docs \NC \NR +\NC half_error_line \NC number\NC 50\NC cf.\ web2c docs \NC \NR +\NC max_print_line \NC number\NC 79\NC cf.\ web2c docs \NC \NR +\NC ocp_list_size \NC number\NC 1000\NC cf.\ web2c docs \NC \NR +\NC ocp_buf_size \NC number\NC 1000\NC cf.\ web2c docs \NC \NR +\NC ocp_stack_size \NC number\NC 1000\NC cf.\ web2c docs \NC \NR +\NC hash_extra \NC number\NC 0\NC cf.\ web2c docs \NC \NR +\NC pk_dpi \NC number\NC 72\NC cf.\ web2c docs \NC \NR +\NC trace_file_names \NC boolean \NC true \NC \type{false} disables \TEX's normal file open|-|close + feedback (the assumption is that callbacks will take care of + that) \NC \NR +\NC file_line_error \NC boolean \NC false \NC do \type{file:line} style error messages\NC \NR +\NC halt_on_error \NC boolean \NC false \NC abort run on the first encountered error\NC \NR +\NC formatname \NC string \NC \NC if no format name was given + on the commandline, this key will be tested first + instead of simply quitting\NC \NR +\NC jobname \NC string \NC \NC if no input file name was given + on the commandline, this key will be tested first + instead of simply giving up\NC \NR +\stoptabulate + +{\bf 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 \luatex{texio} library} + +This library takes care of the low|-|level I/O interface. + +\subsection{Printing functions} + +\subsubsection{\luatex{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 +\tex{batchmode} is in effect, it writes only to the log, +otherwise it writes to the log and the terminal. +The optional \type{target} can be one of three possibilities: +\type{term}, \type{log} or \type {term and log}. + +Note: If several strings are given, and if the first of these strings +is or might be one of the targets above, the \type{target} must be +specified explicitly to prevent \LUA\ from interpreting the first +string as the target. + +\subsubsection{\luatex{texio.write_nl}} + +\startfunctioncall +texio.write_nl(<string> target, <string> s, ...) +texio.write_nl(<string> s, ...) +\stopfunctioncall + +This function behaves like \luatex{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. + +%*********************************************************************** + +\section[luatokens]{The \luatex{token} library} + +The \luatex{token} table contains interface functions to \TEX's +handling of tokens. These functions are most useful when combined with +the \luatex{token_filter} callback, but they could be used standalone +as well. + +A token is represented in \LUA\ as a small table. For the moment, this +table consists of three numeric entries: + +\starttabulate[|l|l|p|] +\NC \bf index\NC \bf meaning \NC \bf description \NC \NR +\NC 1 \NC command code \NC this is a value between~$0$ and~$130$ (approximately)\NC \NR +\NC 2 \NC command modifier \NC this is a value between~$0$ and~$2^{21}$ \NC \NR +\NC 3 \NC control sequence id \NC for commands that are not the result of control + sequences, like letters and characters, it is zero, + otherwise, it is a number pointing into the \quote + {equivalence table} \NC \NR +\stoptabulate + +\subsection{\luatex{token.get_next}} + +\startfunctioncall +token t = token.get_next() +\stopfunctioncall + +This fetches the next input token from the current input source, +without expansion. + +\subsection{\luatex{token.is_expandable}} + +\startfunctioncall +<boolean> b = token.is_expandable(token t) +\stopfunctioncall + +This tests if the token \type{t} could be expanded. + +\subsection{\luatex{token.expand}} + +\startfunctioncall +token.expand() +\stopfunctioncall + +If a token is expandable, this will expand one level of it, so that +the first token of the expansion will now be the next token to be read +by \luatex{token.get_next()}. + +\subsection{\luatex{token.is_activechar}} + +\startfunctioncall +<boolean> b = token.is_activechar(token t) +\stopfunctioncall + +This is a special test that is sometimes handy. Discovering whether +some control sequence is the result of an active character turned out +to be very hard otherwise. + +\subsection{\luatex{token.create}} + +\startfunctioncall +token t = token.create(<string> csname) +token t = token.create(<number> charcode) +token t = token.create(<number> charcode, <number> catcode) +\stopfunctioncall + +This is the token factory. If you feed it a string, then it is the +name of a control sequence (without leading backslash), and it will be +looked up in the equivalence table. + +If you feed it number, then this is assumed to be an input character, +and an optional second number gives its category code. This means it +is possible to overrule a character's category code, with a few +exceptions: the category codes~0 (escape), 9~(ignored), 13~(active), +14~(comment), and 15 (invalid) cannot occur inside a token. The values~0, 9, 14 +and~15 are therefore illegal as input to \luatex{token.create()}, and +active characters will be resolved immediately. + +Note: unknown string sequences and never defined active characters +will result in a token representing an \quote{undefined control sequence} +with a near|-|random name. It is {\em not} possible to define brand +new control sequences using \luatex{token.create}! + +\subsection{\luatex{token.command_name}} + +\startfunctioncall +<string> commandname = token.command_name(<token> t) +\stopfunctioncall + +This returns the name associated with the \quote{command} value of the token +in \LUATEX. There is not always a direct connection between these names and +primitives. For instance, all \tex{ifxxx} tests are grouped under +\type {if_fest}, and the \quote{command modifier} defines which test is to be run. + +\subsection{\luatex{token.command_id}} + +\startfunctioncall +<number> i = token.command_id(<string> commandname) +\stopfunctioncall + +This returns a number that is the inverse operation of the previous +command, to be used as the first item in a token table. + +\subsection{\luatex{token.csname_name}} + +\startfunctioncall +<string> csname = token.csname_name(<token> t) +\stopfunctioncall + +This returns the name associated with the \quote{equivalence table} value of +the token in \LUATEX. It returns the string value of the command used +to create the current token, or an empty string if there is no +associated control sequence. + +Keep in mind that there are potentially two control sequences that +return the same csname string: single character control sequences +and active characters have the same \quote{name}. + +\subsection{\luatex{token.csname_id}} + +\startfunctioncall +<number> i = token.csname_id(<string> csname) +\stopfunctioncall + +This returns a number that is the inverse operation of the previous +command, to be used as the third item in a token table. + + \chapter[math]{Math} The handling of mathematics in \LUATEX\ differs quite a bit from how @@ -5740,9 +6461,9 @@ font dimension parameter. For math fonts, this should be set to zero. \starttabulate[|l|l|l|p|] \NC \bf variable \NC \bf style \NC \bf default value opentype \NC \bf default value tfm \NC\NR \NC \tex{Umathaxis} \NC -- \NC AxisHeight \NC axis_height \NC\NR -\NC \tex{Umathoperatorsize} \NC D, D' \NC DisplayOperatorMinHeight \NC $^6$ \NC\NR -\NC \tex{Umathfractiondelsize} \NC D, D' \NC 0$^1$ \NC delim1 \NC\NR -\NC " \NC T, T', S, S', SS, SS' \NC 0$^1$ \NC delim2 \NC\NR +\NC \tex{Umathoperatorsize} \NC D, D' \NC DisplayOperatorMinHeight \NC $^6$ \NC\NR +\NC \tex{Umathfractiondelsize} \NC D, D' \NC FractionDelimiterDisplaySize$^9$ \NC delim1 \NC\NR +\NC " \NC T, T', S, S', SS, SS' \NC FractionDelimiterSize$^9$ \NC delim2 \NC\NR \NC \tex{Umathfractiondenomdown}\NC D, D' \NC FractionDenominatorDisplayStyleShiftDown \NC denom1 \NC\NR \NC " \NC T, T', S, S', SS, SS' \NC FractionDenominatorShiftDown \NC denom2 \NC\NR \NC \tex{Umathfractiondenomvgap}\NC D, D' \NC FractionDenominatorDisplayStyleGapMin \NC 3*default_rule_thickness \NC\NR @@ -5802,7 +6523,7 @@ font dimension parameter. For math fonts, this should be set to zero. \stop -Note 1: \OPENTYPE\ fonts set \tex{Umathfractiondelsize}, \tex{Umathlimitabovekern}, +Note 1: \OPENTYPE\ fonts set \tex{Umathlimitabovekern} and \tex{Umathlimitbelowkern} to zero and set \tex{Umathquad} to the font size of the used font, because these are not supported in the MATH table, @@ -5834,6 +6555,10 @@ expressed in a percentage instead of as a number of scaled points. Note 8: \type{SubscriptShiftDownWithSuperscript} does not actually exist in the \quote{standard} Opentype Math font Cambria, but it is useful enough to be added. New in version 0.38. +Note 9: \type{FractionDelimiterDisplaySize} and \type{FractionDelimiterSize} do not actually exist in the \quote{standard} +Opentype Math font Cambria, but were useful enough to be added. New in version 0.47. + + \section{Math spacing setting} Besides the parameters mentioned in the previous sections, there are @@ -6521,11 +7246,14 @@ The top|-|level keys in the table are as follows: \NC characters \NC yes \NC yes \NC yes \NC table \NC the defined glyphs of this font \NC \NR \NC checksum \NC yes \NC yes \NC no \NC number \NC default: 0 \NC \NR \NC designsize \NC no \NC yes \NC yes \NC number \NC expected size (default: 655360 == 10pt) \NC \NR -\NC direction \NC no \NC yes \NC yes \NC number \NC default: 0 (LTR) \NR +\NC direction \NC no \NC yes \NC yes \NC number \NC default: 0 (TLT) \NC \NR \NC encodingbytes \NC no \NC no \NC yes \NC number \NC default: depends on \type {format}\NC\NR \NC encodingname \NC no \NC no \NC yes \NC string \NC encoding name\NC\NR \NC fonts \NC yes \NC no \NC yes \NC table \NC locally used fonts\NC \NR -\NC fullname \NC no \NC no \NC yes \NC string \NC actual (\POSTSCRIPT) name\NC\NR +\NC psname \NC no \NC no \NC yes \NC string +\NC actual (\POSTSCRIPT) name (this is the PS fontname in the +incoming font source, also used as fontname identifier in the \PDF\ output, new in 0.43)\NC\NR +\NC fullname \NC no \NC no \NC yes \NC string \NC output font name, used as a fallback in the \PDF\ output if the psname is not set\NC\NR \NC header \NC yes \NC no \NC no \NC string \NC header comments, if any\NC \NR \NC hyphenchar \NC no \NC no \NC yes \NC number \NC default: TeX's \tex{hyphenchar} \NC \NR \NC parameters \NC no \NC yes \NC yes \NC hash \NC default: 7 parameters, all zero \NC \NR @@ -6540,7 +7268,7 @@ The top|-|level keys in the table are as follows: \NC stretch \NC no \NC no \NC yes \NC number \NC the \quote {stretch} value from \tex{pdffontexpand}\NC\NR \NC shrink \NC no \NC no \NC yes \NC number \NC the \quote {shrink} value from \tex{pdffontexpand}\NC\NR \NC step \NC no \NC no \NC yes \NC number \NC the \quote {step} value from \tex{pdffontexpand}\NC\NR -\NC auto_expand \NC no \NC no \NC yes \NC boolean\NC the \quote {autoexpand} keyword from \tex{pdffontexpand}\NC\NR +\NC auto_expand \NC no \NC no \NC yes \NC boolean\NC the \quote {autoexpand} keyword from\crlf \tex{pdffontexpand}\NC\NR \NC expansion_factor \NC no \NC no \NC no \NC number \NC the actual expansion factor of an expanded font\NC\NR \NC attributes \NC no \NC no \NC yes \NC string \NC the \tex{pdffontattr}\NC\NR \NC cache \NC no \NC no \NC yes \NC string \NC this key controls caching of the lua table on the \type{tex} @@ -6550,7 +7278,16 @@ The top|-|level keys in the table are as follows: \type{renew}: don't store the table reference, but save a reference to the table that is created at the first access to one of its fields in font.fonts. - (new in 0.40.0, before that caching was always \type{yes})\NC\NR + (new in 0.40.0, before that caching was always \type{yes}). +Note: the saved reference is thread-local, so be careful when you are using coroutines: an error will be thrown if the table +has been cached in one thread, but you reference it from another thread ($\approx$ coroutine)\NC\NR +\NC nomath \NC no \NC no \NC yes \NC boolean\NC this key allows a minor speedup for text fonts. if it is + present and true, then \LUATEX\ will not check the + character enties for math-specific keys. (0.42.0)\NC\NR +\NC slant \NC no \NC no \NC yes \NC number \NC This has the same semantics as the \type{SlantFont} operator + in font map files. (0.47.0)\NC\NR +\NC extent \NC no \NC no \NC yes \NC number \NC This has the same semantics as the \type{ExtendFont} operator + in font map files. (0.50.0)\NC\NR \stoptabulate The key \type{name} is always required. The keys \type{stretch}, @@ -7052,9 +7789,14 @@ The current return value of \luatex{node.types()} is: tex.print('\\type{' .. v .. '} (' .. _ .. '), ') end end -} but as already mentioned, the math and alignment nodes -in this list are not supported at the moment. The useful list -is described in the next sections. +}. + +NOTE: The \type {\lastnodetype} primitive is \ETEX\ compliant. The valid +range is still -1 .. 15 and glyph nodes have number 0 (used to be +char node) and ligature nodes are mapped to 7. That way macro +packages can use the same symbolic names as in traditional \ETEX. +Keep in mind that the internal node numbers are different and that +there are more node types that 15. \subsection{Auxiliary items} @@ -7077,12 +7819,14 @@ accessible fields: \NC stretch_order \NC number \NC \NC\NR \NC shrink \NC number \NC \NC\NR \NC shrink_order \NC number \NC \NC\NR +\NC writable \NC boolean \NC If this is true, you can't assign to this \type{glue_spec} + because it is one of the preallocated special cases. New in 0.52\NC\NR \stoptabulate These objects are reference counted, so there is actually an extra field named \type {ref_count} as well. This item type will likely disappear in the future, and the glue fields themselves will -become part of the nodes referencing glue items. +become part of the nodes referencing glue items. \subsubsection{attribute\_list and attribute items} @@ -7166,7 +7910,8 @@ Valid fields: \showfields{hlist} \starttabulate[|lT|l|p|] \NC \ssbf field \NC \bf type \NC \bf explanation \NC\NR -\NC subtype \NC number \NC unused\NC\NR +\NC subtype \NC number \NC 0 = unknown origin, 1 = created by +linebreaking, 2 = explict box command. (0.46.0)\NC\NR \NC attr \NC \syntax{<node>} \NC The head of the associated attribute list \NC\NR \NC width \NC number \NC \NC\NR \NC height \NC number \NC \NC\NR @@ -7181,6 +7926,11 @@ Valid fields: \showfields{hlist} \NC dir \NC string \NC the direction of this box. see~\in{}[dirnodes]\NC\NR \stoptabulate +A warning: never assign a node list to the list field +unless you are sure its internal link structure is correct, otherwise +an error may be result. + + \subsubsection{vlist nodes} Valid fields: As for hlist, except that \quote{shift} is a displacement @@ -7216,6 +7966,11 @@ Valid fields: \showfields{ins} \NC spec \NC \syntax{<node>} \NC a pointer to the \tex{splittopskip} glue spec\NC\NR \stoptabulate +A warning: never assign a node list to the list field +unless you are sure its internal link structure is correct, otherwise +an error may be result. + + \subsubsection{mark nodes} Valid fields: \showfields{mark} @@ -7239,6 +7994,12 @@ Valid fields: \showfields{adjust} \NC list \NC \syntax{<node>} \NC adjusted material\NC\NR \stoptabulate + +A warning: never assign a node list to the list field +unless you are sure its internal link structure is correct, otherwise +an error may be result. + + \subsubsection{disc nodes} Valid fields: \showfields{disc} @@ -7260,6 +8021,10 @@ Valid fields: \showfields{disc} The subtype numbers~4 and~5 belong to the \quote{of-f-ice} explanation given elsewhere. +A warning: never assign a node list to the pre, post or replace field +unless you are sure its internal link structure is correct, otherwise +an error may be result. + \subsubsection{math nodes} Valid fields: \showfields{math} @@ -7279,14 +8044,39 @@ Valid fields: \showfields{glue} \NC \ssbf field \NC \bf type \NC \bf explanation \NC\NR \NC subtype \NC number \NC 0 = \tex{skip}, 1--18 = internal glue parameters, - 100 = \tex{leaders}, - 101 = \tex{cleaders}, - 102 = \tex{xleaders} \NC\NR + 100-103 = \quote{leader} subtypes \NC\NR \NC attr \NC \syntax{<node>} \NC \NC\NR \NC spec \NC \syntax{<node>} \NC pointer to a glue\_spec item \NC\NR \NC leader \NC \syntax{<node>} \NC pointer to a box or rule for leaders\NC\NR \stoptabulate +The exact meanings of the subtypes are as follows: + +\starttabulate[|rT|l|] +\NC 1 \NC \tex{lineskip} \NC \NR +\NC 2 \NC \tex{baselineskip} \NC \NR +\NC 3 \NC \tex{parskip} \NC \NR +\NC 4 \NC \tex{abovedisplayskip} \NC \NR +\NC 5 \NC \tex{belowdisplayskip} \NC \NR +\NC 6 \NC \tex{abovedisplayshortskip} \NC \NR +\NC 7 \NC \tex{belowdisplayshortskip} \NC \NR +\NC 8 \NC \tex{leftskip} \NC \NR +\NC 9 \NC \tex{rightskip} \NC \NR +\NC 10 \NC \tex{topskip} \NC \NR +\NC 11 \NC \tex{splittopskip} \NC \NR +\NC 12 \NC \tex{tabskip} \NC \NR +\NC 13 \NC \tex{spaceskip} \NC \NR +\NC 14 \NC \tex{xspaceskip} \NC \NR +\NC 15 \NC \tex{parfillskip} \NC \NR +\NC 16 \NC \tex{thinmuskip} \NC \NR +\NC 17 \NC \tex{medmuskip} \NC \NR +\NC 18 \NC \tex{thickmuskip} \NC \NR +\NC 100 \NC \tex{leaders} \NC \NR +\NC 101 \NC \tex{cleaders} \NC \NR +\NC 102 \NC \tex{xleaders} \NC \NR +\NC 103 \NC \tex{aleaders} \NC \NR +\stoptabulate + \subsubsection{kern nodes} Valid fields: \showfields{kern} @@ -7329,8 +8119,15 @@ Valid fields: \showfields{glyph} \NC components \NC \syntax{<node>} \NC pointer to ligature components\NC\NR \NC xoffset \NC number \NC \NC\NR \NC yoffset \NC number \NC \NC\NR +\NC width \NC number \NC (new in 0.53)\NC\NR +\NC height \NC number \NC (new in 0.53)\NC\NR +\NC depth \NC number \NC (new in 0.53)\NC\NR \stoptabulate +A warning: never assign a node list to the components field +unless you are sure its internal link structure is correct, otherwise +an error may be result. + Valid bits for the \type{subtype} field are: \starttabulate[|c|l|] @@ -7408,6 +8205,10 @@ These two subnode types are used for subsidiary list items. For hbox. For \type{sub_mlist}, the \type{list} points to a math list that is yet to be converted. +A warning: never assign a node list to the components field +unless you are sure its internal link structure is correct, otherwise +an error may be result. + \subsubsection{Math delimiter subnode} There is a fifth subnode type that is used exclusively for delimiter @@ -7454,7 +8255,7 @@ Valid fields: \showfields{noad} Operators are a bit special because they occupy three subtypes. \type{subtype}. -\starttabulate[|lT|l|p|] +\starttabulate[|lT|p|] \NC \ssbf number \NC \bf node sub type \NC\NR \NC 0 \NC Ord \NC\NR \NC 1 \NC Op, \type{\displaylimits} \NC\NR @@ -7512,6 +8313,10 @@ Valid fields: \showfields{choice} \NC scriptscript \NC \syntax{<node>}\NC \NC\NR \stoptabulate +A warning: never assign a node list to the display, text, script, or +scriptscript field unless you are sure its internal link structure is +correct, otherwise an error may be result. + \subsubsubsection{radical nodes} Valid fields: \showfields{radical} @@ -7526,6 +8331,11 @@ Valid fields: \showfields{radical} \NC degree \NC \syntax{<kernel>}\NC Only set by \type{\Uroot} \NC \NR \stoptabulate +A warning: never assign a node list to the nucleus, sub, sup, left, or +degree field +unless you are sure its internal link structure is correct, otherwise +an error may be result. + \subsubsubsection{fraction nodes} Valid fields: \showfields{fraction} @@ -7540,6 +8350,10 @@ Valid fields: \showfields{fraction} \NC right \NC \syntax{<delim>}\NC \NC \NR \stoptabulate +A warning: never assign a node list to the num, or denom field +unless you are sure its internal link structure is correct, otherwise +an error may be result. + \subsubsubsection{fence nodes} Valid fields: \showfields{fence} @@ -7553,13 +8367,15 @@ Valid fields: \showfields{fence} \NC delim \NC \syntax{<delim>}\NC \NC \NR \stoptabulate - \subsection{whatsit nodes} Whatsit nodes come in many subtypes that you can ask for by running \luatex{node.whatsits()}: -\ctxlua {for _,v in pairs(node.whatsits()) do -tex.print('\\type{' .. v .. '} (' .. _ .. '), ') end } +\ctxlua {for n,name in table.sortedpairs(node.whatsits()) do + if (n<100) then + if (n>0) then tex.sprint (', ') end + tex.sprint('\\type{' .. name .. '} (' .. n .. ')') end +end } \subsubsection{open nodes} @@ -7629,6 +8445,13 @@ Valid fields: \showfields{whatsit,local_par} \NC box_right_width\NC number\NC width of the \tex{localrightbox}\NC\NR \stoptabulate +A warning: never assign a node list to the box_left or box_right field +unless you are sure its internal link structure is correct, otherwise +an error may be result. + + + + \subsubsection[dirnodes]{dir nodes} Valid fields: \showfields{whatsit,dir} @@ -7652,9 +8475,8 @@ These are built up out of three separate items: \item the third is the direction of the \quote{top} of glyphs. \stopitemize -Each of the three items can have 4 separate values, but the directions -of the first and second items always have to be perpendicular to -each other, which limits the total to 16. +However, only four combinations are accepted: \type{TLT}, \type{TRT}, +\type{RTT}, and \type{LTL}. Inside actual \type{dir} whatsit nodes, the representation of \type{dir} is not a three-letter but a four-letter combination. The @@ -7890,7 +8712,7 @@ Valid fields: \showfields{whatsit,user_defined} The \type{type} can have one of five distinct values: -\starttabulate[|lT|l|p|] +\starttabulate[|lT|p|] \NC \ssbf value \NC \bf explanation \NC\NR \NC 97 \NC the value is an attribute node list \NC\NR \NC 100 \NC the value is a number \NC\NR @@ -7911,6 +8733,8 @@ necessary to clean up the internal interfaces. \startitemize +\item The current code base is written in C, not Pascal web (as of \LUATEX~0.42.0). + \item See~\in{chapter}[languages] for many small changes related to paragraph building, language handling, and hyphenation. Most important change: adding a brace group in the middle of a word (like in \type{of{}fice}) @@ -7921,9 +8745,7 @@ necessary to clean up the internal interfaces. \item \type {plus 1 fillll} does not generate an error. The extra \quote{l} is simply typeset. -\item The \tex{endlinechar} can be either added (values 0 or more), or not -(negative values). If it is added, the character is always decimal 13 a/k/a -\type{^^M} a/k/a carriage return (This change may be temporary). +\item The upper limit to \tex{endlinechar} and \tex{newlinechar} is 127. \stopitemize @@ -8003,6 +8825,19 @@ as well as the five supporting primitives \tex{knbscode}, \tex{stbscode}, \stoptyping \stopcolumns +\item The four primitives that were already marked obsolete in \PDFTEX~1.40 +have been removed since \LUATEX~0.42: + +\startcolumns[n=2] +\starttyping +\pdfoptionalwaysusepdfpagebox +\pdfoptionpdfinclusionerrorlevel +\pdfforcepagebox +\pdfmovechars +\stoptyping +\stopcolumns + + \item A few other experimental primitives are also provided without the extra \luatex {pdf} prefix, so they can also be called like this: @@ -8022,12 +8857,26 @@ as well as the five supporting primitives \tex{knbscode}, \tex{stbscode}, \item LFS (\PDF\ Files larger than 2GiB) support is not working yet. +\item \LUATEX~0.45.0 introduces two extra token lists, \tex{pdfxformresources} +and \tex{pdfxformattr}, as an alternative to \tex{pdfxform} keywords. + +\item As of \LUATEX~0.50.0 is no longer possible for fonts from embedded pdf files + to be replaced by / merged with the document fonts of the enveloping + pdf document. This regression may be temporary, depending on how the + rewritten font backend will look after beta 0.60. + + \stopitemize \section{Changes from \ALEPH\ RC4} \startitemize +\item \LUATEX\ only understands 4~of the 16~direction +specifiers of \ALEPH: \type{TLT} (latin), \type{TRT} (arabic), +\type{RTT} (cjk), \type{LTL} (mongolian). All other direction +specifiers generate an error (\LUATEX\ 0.45). + \item The input translations from \ALEPH\ are not implemented, the related primitives are not available: @@ -8062,10 +8911,6 @@ removing the need for an explicit fix to \tex{hoffset} \item A bug causing \tex{fam} to fail for family numbers above 15 is fixed. -\item Some bits of \ALEPH\ assumed \type{0} and \type{null} were identical. -This resulted for instance in a bug that sometimes caused an eternal -loop when trying to \tex{show} a box. - \item A fair amount of other minor bugs are fixed as well, most of these related to \tex{tracingcommands} output. @@ -8074,7 +8919,8 @@ smaller than their maximum \ALEPH\ value (around 5000 fonts and 30000 ocps / ocplists). \item The internal function \type{scan_dir()} has been renamed to -\type{scan_direction()} to prevent a naming clash. +\type{scan_direction()} to prevent a naming clash, and it now allows +an optional space after the direction is completely parsed. \item The \type{^^} notation can come in five and six item repetitions also, to insert characters that do not fit in the BMP. @@ -8149,17 +8995,16 @@ memory} errors can still occur, but the limiting factor is now the amount of RAM in your system, not a predefined limit. Also, the memory (de)allocation routines for nodes are completely -rewritten. The relevant code now lives in the C file \type{luanode.c}, -and basically uses a dozen or so avail lists instead of a +rewritten. The relevant code now lives in the C file \type{texnode.c}, +and basically uses a dozen or so \quote{avail} lists instead of a doubly|-|linked model. An extra function layer is added so that the code can ask for nodes by type instead of directly requisitioning a certain amount of memory words. -Because of the split into two arrays and the resulting differences in -the data structures, some of the Pascal \WEB\ macros have been -duplicated. For instance, there are now \type{vlink} and \type{vinfo} -as well as \type{link} and \type{info}. All access to the variable -memory array is now hidden behind a macro called \type{vmem}. +Because of the split into two arrays and the resulting differences in the data +structures, some of the macros have been duplicated. For instance, there are now +\type{vlink} and \type{vinfo} as well as \type{token_link} and \type{token_info}. All +access to the variable memory array is now hidden behind a macro called \type{vmem}. The implementation of the growth of two arrays (via reallocation) introduces a potential pitfall: the memory arrays should never be used @@ -8179,9 +9024,9 @@ the \TEX\ \quote{equivalence table} and because each had 1.1 million entries with a few memory words each, this makes a major difference in memory usage. -These assignments do not yet show up when using the etex tracing -routines \tex{tracingassigns} and \tex{tracingrestores} (code -simply not written yet). +The \tex{catcode}, \tex{sfcode}, \tex{lccode} and \tex{uccode} assignments +do not yet show up when using the etex tracing routines \tex{tracingassigns} +and \tex{tracingrestores} (code simply not written yet). A side|-|effect of the current implementation is that \tex{global} is now more expensive in terms of processing than non|-|global assignments. @@ -8202,6 +9047,10 @@ The code that displays control sequences explicitly checks if the length is one when it has to decide whether or not to add a trailing space. +Active characters are internally implemented as a special type +of multi-letter control sequences that uses a prefix that is +otherwise impossible to obtain. + \section{Compressed format} The format is passed through zlib, allowing it to shrink to roughly @@ -8219,85 +9068,10 @@ contents. While this uses more memory than the previous code (that mostly used \type{getc} calls), it can be quite a bit faster (depending on your I/O subsystem). -\chapter{Known bugs and limitations} - -The bugs below are going to be fixed eventually. - -The top ones will be fixed soon, but in the later items either the -actual problem is hard to find, or the code that causes the bug is -going to be replaced by a new subsystem soon anyway, or it may not -be worth the hassle and the limitations will eventually be documented. - -\startitemize - -\item The current linebreaking implementation still does not yet take all -possible breakpoints into account where ligatures are involved in the -process. This means that line breaks may change in future versions of -\LUATEX, in situations where exotic fonts (with ligatures with 3 parts -or more) are combined with languages with exotic hyphenation patterns -(where multiple hyphenation points can happen within one such -ligature). - -\item \luatex{tex.print()} and \luatex{tex.sprint()} do not work if -\tex{directlua} is used in an \OTP\ file (in the output of an -\type{expression} rule). - -\item When used inside \tex{directlua}, \type{pdf.print()} should create a -literal node instead of flushing immediately. - -\item Not all of \ALEPH's direction commands are handled properly in -\PDF\ mode, and especially the vertical scripts support is missing -almost completely (only \type {TRT} and \type {TLT} are routinely tested). +\chapter{Known bugs and limitations, TODO} -\item Node pointers are not always checked for validity, so if you make a -mistake in the node list processing, \LUATEX\ may terminate itself with an -assertion error or \quote{Emergency stop}. - -\item In \DVI\ generation mode, using a \tex{textdir} switch inside the -preamble of a \tex{halign} results in overprinted text in the \DVI\ file, -because the column width is not taken into account during the final -placement phase (this is a bug inherited from \ALEPH). Also, \ALEPH\ -apparently dislikes having more than one non-grouped \tex{textdir} -command in a single lined paragraph. - -\stopitemize - - -\chapter{TODO} - -On top of the \quote{normal} extensions that are planned, there -are some more specific small feature requests. Whether these will -all be included is not certain yet. New requests are welcome but -should fit into our ideas, i.e.\ no new hard coded solutions. Beware, -this is not the roadmap, which is somewhat more ambitious. - -\startitemize - -\item Implement the \TEX\ primitive \tex{dimension}, cf.\ \tex{number}. - -\item Do something about \tex{withoutpt} and/or a new register type \tex{real}? - -\item Create callback for the automatic creation of missing -characters in fonts. - -\item Do boxes with dual baselines. - -\item Make the number of the output box configurable. - -\item Switch all the node lists to a double|-|linked list. - -\item Finish the interface from \LUA\ to \TeX's internals, specially the hash and -equivalence table (a small subpart is implementing \tex{csname} -lookups for \type{tex.box} access). - -\item Use of Type1C for embedded PostScript font subsets in -traditional 8-bit encodings. - -\item Support font reencoding of 8-bit fonts via char index instead of -via map files. - -\item Attempt to parse \OFM\ level~0 fonts that are masquerading as level~1. - -\stopitemize +There used to be a lists of bugs and planned features below here, but that did not +work out too well. There are lists of open bugs and feature requests in the tracker at +\hyphenatedurl{http://tracker.luatex.org}. \stoptext |