summaryrefslogtreecommitdiff
path: root/systems/doc/luatex/luatex-lua.tex
diff options
context:
space:
mode:
Diffstat (limited to 'systems/doc/luatex/luatex-lua.tex')
-rw-r--r--systems/doc/luatex/luatex-lua.tex1520
1 files changed, 760 insertions, 760 deletions
diff --git a/systems/doc/luatex/luatex-lua.tex b/systems/doc/luatex/luatex-lua.tex
index 3d6d20c35d..f9107fa1f9 100644
--- a/systems/doc/luatex/luatex-lua.tex
+++ b/systems/doc/luatex/luatex-lua.tex
@@ -1,760 +1,760 @@
-% language=uk
-
-\environment luatex-style
-
-\startcomponent luatex-lua
-
-\startchapter[reference=lua,title={Using \LUATEX}]
-
-\startsection[title={Initialization},reference=init]
-
-\startsubsection[title={\LUATEX\ as a \LUA\ interpreter}]
-
-\topicindex {initialization}
-\topicindex {\LUA+interpreter}
-
-There are some situations that make \LUATEX\ behave like a standalone \LUA\
-interpreter:
-
-\startitemize[packed]
-\startitem
- if a \type {--luaonly} option is given on the commandline, or
-\stopitem
-\startitem
- if the executable is named \type {texlua} or \type {luatexlua}, or
-\stopitem
-\startitem
- if the only non|-|option argument (file) on the commandline has the extension
- \type {lua} or \type {luc}.
-\stopitem
-\stopitemize
-
-In this mode, it will set \LUA's \type {arg[0]} to the found script name, pushing
-preceding options in negative values and the rest of the command line in the
-positive values, just like the \LUA\ interpreter.
-
-\LUATEX\ will exit immediately after executing the specified \LUA\ script and is,
-in effect, a somewhat bulky stand alone \LUA\ interpreter with a bunch of extra
-preloaded libraries.
-
-\stopsubsection
-
-\startsubsection[title={\LUATEX\ as a \LUA\ byte compiler}]
-
-\topicindex {\LUA+byte code}
-
-There are two situations that make \LUATEX\ behave like the \LUA\ byte compiler:
-
-\startitemize[packed]
-\startitem if a \type {--luaconly} option is given on the command line, or \stopitem
-\startitem if the executable is named \type {texluac} \stopitem
-\stopitemize
-
-In this mode, \LUATEX\ is exactly like \type {luac} from the stand alone \LUA\
-distribution, except that it does not have the \type {-l} switch, and that it
-accepts (but ignores) the \type {--luaconly} switch. The current version of \LUA\
-can dump bytecode using \type {string.dump} so we might decide to drop this
-version of \LUATEX.
-
-\stopsubsection
-
-\startsubsection[title={Other commandline processing}]
-
-\topicindex {command line}
-
-When the \LUATEX\ executable starts, it looks for the \type {--lua} command line
-option. If there is no \type {--lua} option, the command line is interpreted in a
-similar fashion as the other \TEX\ engines. Some options are accepted but have no
-consequence. The following command|-|line options are understood:
-
-\starttabulate[|l|p|]
-\DB commandline argument \BC explanation \NC \NR
-\TB
-\NC \type{--credits} \NC display credits and exit \NC \NR
-\NC \type{--debug-format} \NC enable format debugging \NC \NR
-\NC \type{--draftmode} \NC switch on draft mode i.e.\ generate no output in \PDF\ mode \NC \NR
-\NC \type{--[no-]file-line-error} \NC disable/enable \type {file:line:error} style messages \NC \NR
-\NC \type{--[no-]file-line-error-style} \NC aliases of \type {--[no-]file-line-error} \NC \NR
-\NC \type{--fmt=FORMAT} \NC load the format file \type {FORMAT} \NC\NR
-\NC \type{--halt-on-error} \NC stop processing at the first error\NC \NR
-\NC \type{--help} \NC display help and exit \NC\NR
-\NC \type{--ini} \NC be \type {iniluatex}, for dumping formats \NC\NR
-\NC \type{--interaction=STRING} \NC set interaction mode: \type {batchmode}, \type {nonstopmode},
- \type {scrollmode} or \type {errorstopmode} \NC \NR
-\NC \type{--jobname=STRING} \NC set the job name to \type {STRING} \NC \NR
-\NC \type{--kpathsea-debug=NUMBER} \NC set path searching debugging flags according to the bits of
- \type {NUMBER} \NC \NR
-\NC \type{--lua=FILE} \NC load and execute a \LUA\ initialization script \NC\NR
-\NC \type{--[no-]mktex=FMT} \NC disable/enable \type {mktexFMT} generation with \type {FMT} is
- \type {tex} or \type {tfm} \NC \NR
-\NC \type{--nosocket} \NC disable the \LUA\ socket library \NC\NR
-\NC \type{--output-comment=STRING} \NC use \type {STRING} for \DVI\ file comment instead of date (no
- effect for \PDF) \NC \NR
-\NC \type{--output-directory=DIR} \NC use \type {DIR} as the directory to write files to \NC \NR
-\NC \type{--output-format=FORMAT} \NC use \type {FORMAT} for job output; \type {FORMAT} is \type {dvi}
- or \type {pdf} \NC \NR
-\NC \type{--progname=STRING} \NC set the program name to \type {STRING} \NC \NR
-\NC \type{--recorder} \NC enable filename recorder \NC \NR
-\NC \type{--safer} \NC disable easily exploitable \LUA\ commands \NC\NR
-\NC \type{--[no-]shell-escape} \NC disable/enable system calls \NC \NR
-\NC \type{--shell-restricted} \NC restrict system calls to a list of commands given in \type
- {texmf.cnf} \NC \NR
-\NC \type{--synctex=NUMBER} \NC enable \type {synctex} \NC \NR
-\NC \type{--utc} \NC use utc times when applicable \NC \NR
-\NC \type{--version} \NC display version and exit \NC \NR
-\LL
-\stoptabulate
-
-We don't support \prm {write} 18 because \type {os.execute} can do the same. It
-simplifies the code and makes more write targets possible.
-
-The value to use for \prm {jobname} is decided as follows:
-
-\startitemize
-\startitem
- If \type {--jobname} is given on the command line, its argument will be the
- value for \prm {jobname}, without any changes. The argument will not be
- used for actual input so it need not exist. The \type {--jobname} switch only
- controls the \prm {jobname} setting.
-\stopitem
-\startitem
- Otherwise, \prm {jobname} will be the name of the first file that is read
- from the file system, with any path components and the last extension (the
- part following the last \type {.}) stripped off.
-\stopitem
-\startitem
- There is an exception to the previous point: if the command line goes into
- interactive mode (by starting with a command) and there are no files input
- via \prm {everyjob} either, then the \prm {jobname} is set to \type
- {texput} as a last resort.
-\stopitem
-\stopitemize
-
-The file names for output files that are generated automatically are created by
-attaching the proper extension (\type {log}, \type {pdf}, etc.) to the found
-\prm {jobname}. These files are created in the directory pointed to by \type
-{--output-directory}, or in the current directory, if that switch is not present.
-
-Without the \type {--lua} option, command line processing works like it does in
-any other \WEBC|-|based typesetting engine, except that \LUATEX\ has a few extra
-switches and lacks some others. Also, if the \type {--lua} option is present,
-\LUATEX\ will enter an alternative mode of command line processing in comparison
-to the standard \WEBC\ programs. In this mode, a small series of actions is taken
-in the following order:
-
-\startitemize[n]
-
-\startitem
- First, it will parse the command line 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}.
-\stopitem
-
-\startitem
- Next \LUATEX\ searches for the requested \LUA\ initialization script. If it
- cannot be found using the actual name given on the command line, a second
- attempt is made by prepending the value of the environment variable \type
- {LUATEXDIR}, if that variable is defined in the environment.
-\stopitem
-
-\startitem
- 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, \type {--safer} \type {nil}s the following functions:
-
- \blank
-
- \starttabulate[|c|l|]
- \DB library \BC functions \NC \NR
- \TB
- \NC \type {os} \NC \type {execute} \type {exec} \type {spawn} \type {setenv}
- \type {rename} \type {remove} \type {tmpdir} \NC \NR
- \NC \type {io} \NC \type {popen} \type {output} \type {tmpfile} \NC \NR
- \NC \type {lfs} \NC \type {rmdir} \type {mkdir} \type {chdir} \type {lock}
- \type {touch} \NC \NR
- \LL
- \stoptabulate
-
- \blank
-
- Furthermore, it disables loading of compiled \LUA\ libraries and it makes
- \type {io.open()} fail on files that are opened for anything besides reading.
-\stopitem
-
-\startitem
- When \LUATEX\ starts it sets the \type {locale} to a neutral value. If for
- some reason you use \type {os.locale}, you need to make sure you \type {nil}
- it afterwards because otherwise it can interfere with code that for instance
- generates dates. You can ignore the \type {locale} with:
-
- \starttyping
- os.setlocale(nil,nil)
- \stoptyping
-
- The \type {--nosocket} option 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.
-\stopitem
-
-\startitem
- Next the initialization script is loaded and executed. From within the
- script, the entire command line is available in the \LUA\ table \type {arg},
- beginning with \type {arg[0]}, containing the name of the executable. As
- consequence warnings about unrecognized options are suppressed.
-\stopitem
-
-\stopitemize
-
-Command line 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 \type {tex}, \type {token}, \type {node} and
-\type {pdf}, are off|-|limits during the execution of the startup file (they
-are \type {nil}'d). Special care is taken that \type {texio.write} and \type
-{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 \prm {jobname} yet at this point).
-
-Everything you do in the \LUA\ initialization script will remain visible during
-the rest of the run, with the exception of the \TEX\ specific libraries like
-\type {tex}, \type {token}, \type {node} and \type {pdf} tables. These will be
-initialized to their documented state after the execution of the script. You
-should not store anything in variables or within tables with these 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 command line, set values in the
-\type {texconfig} table, and register the callbacks you need.
-
-\LUATEX\ allows some of the command line options to be overridden by reading
-values from the \type {texconfig} table at the end of script execution (see the
-description of the \type {texconfig} table later on in this document for more
-details on which ones exactly).
-
-Unless the \type {texconfig} table tells \LUATEX\ not to initialize \KPATHSEA\
-at all (set \type {texconfig.kpse_init} to \type {false} for that), \LUATEX\
-acts on some more command line options after the initialization script is
-finished: 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.
-
-\stopsubsection
-
-\stopsection
-
-\startsection[title={\LUA\ behaviour}]
-
-\startsubsection[title={The \LUA\ version}]
-
-\topicindex {\LUA+libraries}
-\topicindex {\LUA+extensions}
-
-We currently use \LUA\ 5.3 and will follow developments of the language but
-normally with some delay. Therefore the user needs to keep an eye on (subtle)
-differences in successive versions of the language. Also, \LUAJITTEX\ lags behind
-in the sense that \LUAJIT\ is not in sync with regular \LUA\ development. Here is
-an example of one aspect.
-
-\LUA s \type {tostring} function (and \type {string.format} may return values in
-scientific notation, thereby confusing the \TEX\ end of things when it is used as
-the right|-|hand side of an assignment to a \prm {dimen} or \prm {count}. The
-output of these serializers also depend on the \LUA\ version, so in \LUA\ 5.3 you
-can get different output than from 5.2.
-
-\stopsubsection
-
-\startsubsection[title={Integration in the \TDS\ ecosystem}]
-
-The main \TEX\ distributions follow the \TEX\ directory structure (\TDS).
-\LUATEX\ is able to use the kpathsea library to find \type {require()}d modules.
-For this purpose, \type {package.searchers[2]} is replaced by a different loader
-function, that decides at runtime whether to use kpathsea or the built|-|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()}.
-
-\stopsubsection
-
-\startsubsection[title={Loading libraries}]
-
-\LUATEX\ is able to use dynamically loadable \LUA\ libraries, unless
-\type {--safer} was given as an option on the command line. For this purpose,
-\type {package.searchers[3]} is replaced by a different loader function, that
-decides at runtime whether to use \KPATHSEA\ or the built|-|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.cpath} loader.
-
-This functionality required an extension to kpathsea. 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 is
-\type {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 binaries directory only.
-Of course it no big deal to write an alternative loader and use that in a macro
-package. 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.
-
-Loading dynamic \LUA\ libraries will fail if there are two \LUA\ libraries loaded
-at the same time (which will typically happen on \type {win32}, because there is
-one \LUA\ 5.3 inside \LUATEX, and another will likely be linked to the \DLL\ file
-of the module itself).
-
-\stopsubsection
-
-\startsubsection[title={Executing programs}]
-
-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 assumed intention to typeset a document (and by that we
-mean that it is called as \type {luatex}, as opposed to \type {texlua}, and that
-the command line option \type {--luaonly} was not given), it will only run the
-four functions above if the matching \type {texmf.cnf} variable(s) or their \type
-{texconfig} (see \in {section} [texconfig]) counterparts allow execution of the
-requested system command. In \quote {script interpreter} runs of \LUATEX, these
-settings have no effect, and all four functions have their original meaning.
-
-Some libraries have a few more functions, either coded in \CCODE\ or in \LUA. For
-instance, when we started with \LUATEX\ we added some helpers to the \type
-{luafilesystem} namespace \type {lfs}. The two boolean functions \type
-{lfs.isdir} and \type {lfs.isfile} were speedy and better variants of what could
-be done with \type {lfs.attributes}. The additional function \type
-{lfs.shortname} takes a file name and returns its short name on \type {win32}
-platforms. Finally, for non|-|\type {win32} platforms only, we provided \type
-{lfs.readlink} that takes an existing symbolic link as argument and returns its
-name. However, the \type library evolved so we have dropped these in favour of
-pure \LUA\ variants. The \type {shortname} helper is obsolete and now just
-returns the name.
-
-\stopsubsection
-
-\startsubsection[title={Multibyte \type {string} functions}]
-
-The \type {string} library has a few extra functions, for example \libidx
-{string} {explode}. This function takes upto two arguments: \type
-{string.explode(s[,m])} and returns an array containing the string argument \type
-{s} split into sub-strings based on the value of the string argument \type {m}.
-The second argument is a string that is either empty (this splits the string into
-characters), a single character (this splits on each occurrence of that
-character, possibly introducing empty strings), or a single character followed by
-the plus sign \type {+} (this special version does not create empty sub-strings).
-The default value for \type {m} is \quote {\type { +}} (multiple spaces). Note:
-\type {m} is not hidden by surrounding braces as it would be if this function was
-written in \TEX\ macros.
-
-The \type {string} library also has six extra iterators that return strings
-piecemeal: \libidx {string} {utfvalues}, \libidx {string} {utfcharacters},
-\libidx {string} {characters}, \libidx {string} {characterpairs}, \libidx
-{string} {bytes} and \libidx {string} {bytepairs}.
-
-\startitemize
-\startitem
- \type {string.utfvalues(s)}: an integer value in the \UNICODE\ range
-\stopitem
-\startitem
- \type {string.utfcharacters(s)}: a string with a single \UTF-8 token in it
-\stopitem
-\startitem
- \type {string.cWharacters(s)}: a string containing one byte
-\stopitem
-\startitem
- \type {string.characterpairs(s)}: two strings each containing one byte or an
- empty second string if the string length was odd
-\stopitem
-\startitem
- \type {string.bytes(s)}: a single byte value
-\stopitem
-\startitem
- \type {string.bytepairs(s)}: two byte values or nil instead of a number as
- its second return value if the string length was odd
-\stopitem
-\stopitemize
-
-The \type {string.characterpairs()} and \type {string.bytepairs()} iterators
-are useful especially in the conversion of \UTF16 encoded data into \UTF8.
-
-There is also a two|-|argument form of \type {string.dump()}. The second argument
-is a boolean which, if true, strips the symbols from the dumped data. This
-matches an extension made in \type {luajit}. This is typically a function that
-gets adapted as \LUA\ itself progresses.
-
-The \type {string} library functions \type {len}, \type {lower}, \type {sub}
-etc.\ are not \UNICODE|-|aware. For strings in the \UTF8 encoding, i.e., strings
-containing characters above code point 127, the corresponding functions from the
-\type {slnunicode} library can be used, e.g., \type {unicode.utf8.len}, \type
-{unicode.utf8.lower} etc.\ The exceptions are \type {unicode.utf8.find}, that
-always returns byte positions in a string, and \type {unicode.utf8.match} and
-\type {unicode.utf8.gmatch}. While the latter two functions in general {\it
-are} \UNICODE|-|aware, they fall|-|back to non|-|\UNICODE|-|aware behavior when
-using the empty capture \type {()} but other captures work as expected. For the
-interpretation of character classes in \type {unicode.utf8} functions refer to
-the library sources at \hyphenatedurl {http://luaforge.net/projects/sln}.
-
-Version 5.3 of \LUA\ provides some native \UTF8 support but we have added a few
-similar helpers too: \libidx {string} {utfvalue}, \libidx {string} {utfcharacter}
-and \libidx {string} {utflength}.
-
-\startitemize
-\startitem
- \type {string.utfvalue(s)}: returns the codepoints of the characters in the
- given string
-\stopitem
-\startitem
- \type {string.utfcharacter(c,...)}: returns a string with the characters of
- the given code points
-\stopitem
-\startitem
- \type {string.utflength(s)}: returns the length oif the given string
-\stopitem
-\stopitemize
-
-These three functions are relative fast and don't do much checking. They can be
-used as building blocks for other helpers.
-
-\stopsubsection
-
-\startsubsection[title={Extra \type {os} library functions}]
-
-The \type {os} library has a few extra functions and variables: \libidx {os}
-{selfdir}, \libidx {os} {exec}, \libidx {os} {spawn}, \libidx {os} {setenv},
-\libidx {os} {env}, \libidx {os} {gettimeofday}, \libidx {os} {times}, \libidx
-{os} {tmpdir}, \libidx {os} {type}, \libidx {os} {name} and \libidx {os} {uname},
-that we will discuss here.
-
-\startitemize
-
-\startitem
- \type {os.selfdir} is a variable that holds the directory path of the
- actual executable. For example: \type {\directlua {tex.sprint(os.selfdir)}}.
-\stopitem
-
-\startitem
- \type {os.exec(commandline)} is a variation on \type {os.execute}. Here
- \type {commandline} can be either a single string or a single table.
-
- \startitemize
-
- \startitem
- If the argument is a table \LUATEX\ first checks if there is a value at
- integer index zero. If there is, this is the command to be executed.
- Otherwise, it will use the value at integer index one. If neither are
- present, nothing at all happens.
- \stopitem
-
- \startitem
- The set of consecutive values starting at integer~1 in the table are the
- arguments that are passed on to the command (the value at index~1 becomes
- \type {arg[0]}). The command is searched for in the execution path, so
- there is normally no need to pass on a fully qualified path name.
- \stopitem
-
- \startitem
- If the argument is a string, then it is automatically converted into a
- table by splitting on whitespace. In this case, it is impossible for the
- command and first argument to differ from each other.
- \stopitem
-
- \startitem
- In the string argument format, whitespace can be protected by putting
- (part of) an argument inside single or double quotes. One layer of quotes
- is interpreted by \LUATEX, and all occurrences of \type {\"}, \type {\'}
- or \type {\\} within the quoted text are unescaped. In the table format,
- there is no string handling taking place.
- \stopitem
-
- \stopitemize
-
- This function normally does not return control back to the \LUA\ script: the
- command will replace the current process. However, it will return the two
- values \type {nil} and \type {error} if there was a problem while
- attempting to execute the command.
-
- On \MSWINDOWS, the current process is actually kept in memory until after the
- execution of the command has finished. This prevents crashes in situations
- where \TEXLUA\ scripts are run inside integrated \TEX\ environments.
-
- The original reason for this command is that it cleans out the current
- process before starting the new one, making it especially useful for use in
- \TEXLUA.
-\stopitem
-
-\startitem
- \type {os.spawn(commandline)} is a returning version of \type {os.exec},
- with otherwise identical calling conventions.
-
- If the command ran ok, then the return value is the exit status of the
- command. Otherwise, it will return the two values \type {nil} and \type
- {error}.
-\stopitem
-
-\startitem
- \type {os.setenv(key,value)} sets a variable in the environment. Passing
- \type {nil} instead of a value string will remove the variable.
-\stopitem
-
-\startitem
- \type {os.env} is a hash table containing a dump of the variables and
- values in the process environment at the start of the run. It is writeable,
- but the actual environment is \notabene {not} updated automatically.
-\stopitem
-
-\startitem
- \type {os.gettimeofday()} returns the current \quote {\UNIX\ time}, but as a
- float. This function is not available on the \SUNOS\ platforms, so do not use
- this function for portable documents.
-\stopitem
-
-\startitem
- \type {os.times()}returns the current process times according to \ the
- \UNIX\ C library function \quote {times}. This function is not available on
- the \MSWINDOWS\ and \SUNOS\ platforms, so do not use this function for
- portable documents.
-\stopitem
-
-\startitem
- \type {os.tmpdir()} creates a directory in the \quote {current directory}
- with the name \type {luatex.XXXXXX} where the \type {X}-es are replaced by a
- unique string. The function also returns this string, so you can \type
- {lfs.chdir()} into it, or \type {nil} if it failed to create the directory.
- The user is responsible for cleaning up at the end of the run, it does not
- happen automatically.
-\stopitem
-
-\startitem
- \type {os.type} is a string that gives a global indication of the class of
- operating system. The possible values are currently \type {windows}, \type
- {unix}, and \type {msdos} (you are unlikely to find this value \quote {in the
- wild}).
-\stopitem
-
-\startitem
- \type {os.name} is a string that gives a more precise indication of the
- operating system. These possible values are not yet fixed, and for \type
- {os.type} values \type {windows} and \type {msdos}, the \type {os.name}
- values are simply \type {windows} and \type {msdos}
-
- The list for the type \type {unix} is more precise: \type {linux}, \type
- {freebsd}, \type {kfreebsd}, \type {cygwin}, \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).
-\stopitem
-
-\startitem
- \type {os.uname} returns a table with specific operating system
- information acquired at runtime. The keys in the returned table are all
- string values, and their names are: \type {sysname}, \type {machine}, \type
- {release}, \type {version}, and \type {nodename}.
-\stopitem
-
-\stopitemize
-
-\stopsubsection
-
-\startsubsection[title={Binary input from files with \type {fio}}]
-
-There is a whole set of helpers for reading numbers and strings from a file:
-\libidx {fio} {readcardinal1}, \libidx {fio} {readcardinal2}, \libidx {fio}
-{readcardinal3}, \libidx {fio} {readcardinal4}, \libidx {fio}
-{readcardinaltable}, \libidx {fio} {readinteger1}, \libidx {fio} {readinteger2},
-\libidx {fio} {readinteger3}, \libidx {fio} {readinteger4}, \libidx {fio}
-{readintegertable}, \libidx {fio} {readfixed2}, \libidx {fio} {readfixed4},
-\libidx {fio} {read2dot14}, \libidx {fio} {setposition}, \libidx {fio}
-{getposition}, \libidx {fio} {skipposition}, \libidx {fio} {readbytes}, \libidx
-{fio} {readbytetable}. They work on normal \LUA\ file handles.
-
-%libidx{fio}{readline}
-%libidx{fio}{recordfilename}
-%libidx{fio}{checkpermission}
-
-This library provides a set of functions for reading numbers from a file and
-in addition to the regular \type {io} library functions.
-
-\starttabulate
-\NC \type{readcardinal1(f)} \NC a 1 byte unsigned integer \NC \NR
-\NC \type{readcardinal2(f)} \NC a 2 byte unsigned integer \NC \NR
-\NC \type{readcardinal3(f)} \NC a 3 byte unsigned integer \NC \NR
-\NC \type{readcardinal4(f)} \NC a 4 byte unsigned integer \NC \NR
-\NC \type{readcardinaltable(f,n,b)} \NC \type {n} cardinals of \type {b} bytes \NC \NR
-\NC \type{readinteger1(f)} \NC a 1 byte signed integer \NC \NR
-\NC \type{readinteger2(f)} \NC a 2 byte signed integer \NC \NR
-\NC \type{readinteger3(f)} \NC a 3 byte signed integer \NC \NR
-\NC \type{readinteger4(f)} \NC a 4 byte signed integer \NC \NR
-\NC \type{readintegertable(f,n,b)} \NC \type {n} integers of \type {b} bytes \NC \NR
-\NC \type{readfixed2(f)} \NC a 2 byte float (used in font files) \NC \NR
-\NC \type{readfixed4(f)} \NC a 4 byte float (used in font files) \NC \NR
-\NC \type{read2dot14(f)} \NC a 2 byte float (used in font files) \NC \NR
-\NC \type{setposition(f,p)} \NC goto position \type {p} \NC \NR
-\NC \type{getposition(f)} \NC get the current position \NC \NR
-\NC \type{skipposition(f,n)} \NC skip \type {n} positions \NC \NR
-\NC \type{readbytes(f,n)} \NC \type {n} bytes \NC \NR
-\NC \type{readbytetable(f,n)} \NC \type {n} bytes\NC \NR
-\stoptabulate
-
-\stopsubsection
-
-\startsubsection[title={Binary input from strings with \type {sio}}]
-
-A similar set of function as in the \type {fio} library is available in the \type
-{sio} library: \libidx {sio} {readcardinal1}, \libidx {sio} {readcardinal2},
-\libidx {sio} {readcardinal3}, \libidx {sio} {readcardinal4}, \libidx {sio}
-{readcardinaltable}, \libidx {sio} {readinteger1}, \libidx {sio} {readinteger2},
-\libidx {sio} {readinteger3}, \libidx {sio} {readinteger4}, \libidx {sio}
-{readintegertable}, \libidx {sio} {readfixed2}, \libidx {sio} {readfixed4},
-\libidx {sio} {read2dot14}, \libidx {sio} {setposition}, \libidx {sio}
-{getposition}, \libidx {sio} {skipposition}, \libidx {sio} {readbytes} and
-\libidx {sio} {readbytetable}. Here the first argument is a string instead of a
-file handle. More details can be found in the previous section.
-
-\stopsubsection
-
-\startsubsection[title={Hashes conform \type {sha2}}]
-
-This library is a side effect of the \type {pdfe} library that needs such
-helpers. The \libidx{sha2}{digest256}, \libidx{sha2}{digest384} and
-\libidx{sha2}{digest512} functions accept a string and return a string with the
-hash.
-
-\stopsubsection
-
-\startsubsection[title={Locales}]
-
-\index {locales}
-
-In stock \LUA, many things depend on the current locale. In \LUATEX, we can't do
-that, because it makes documents unportable. While \LUATEX\ is running if
-forces the following locale settings:
-
-\starttyping
-LC_CTYPE=C
-LC_COLLATE=C
-LC_NUMERIC=C
-\stoptyping
-
-\stopsubsection
-
-\stopsection
-
-\startsection[title={\LUA\ modules}]
-
-\topicindex {\LUA+libraries}
-\topicindex {\LUA+modules}
-
-Some modules that are normally external to \LUA\ are statically linked in with
-\LUATEX, because they offer useful functionality:
-
-\startitemize
-
-\startitem
- \type {lpeg}, by Roberto Ierusalimschy, \hyphenatedurl
- {http://www.inf.puc-rio.br/~roberto/lpeg/lpeg.html}. This library is not
- \UNICODE|-|aware, but interprets strings on a byte|-|per|-|byte basis. This
- mainly means that \type {lpeg.S} cannot be used with \UTF8 characters encoded
- in more than two bytes, and thus \type {lpeg.S} will look for one of those
- two bytes when matching, not the combination of the two. The same is true for
- \type {lpeg.R}, although the latter will display an error message if used
- with multibyte characters. Therefore \type {lpeg.R('aä')} results in the
- message \type {bad argument #1 to 'R' (range must have two characters)},
- since to \type {lpeg}, \type {ä} is two 'characters' (bytes), so \type {aä}
- totals three. In practice this is no real issue and with some care you can
- deal with \UNICODE\ just fine.
-\stopitem
-
-\startitem
- \type {slnunicode}, from the \type {selene} libraries, \hyphenatedurl
- {http://luaforge.net/projects/sln}. This library has been slightly extended
- so that the \type {unicode.utf8.*} functions also accept the first 256 values
- of plane~18. This is the range \LUATEX\ uses for raw binary output, as
- explained above. We have no plans to provide more like this because you can
- basically do all that you want in \LUA.
-\stopitem
-
-\startitem
- \type {luazip}, from the kepler project, \hyphenatedurl
- {http://www.keplerproject.org/luazip/}.
-\stopitem
-
-\startitem
- \type {luafilesystem}, also from the kepler project, \hyphenatedurl
- {http://www.keplerproject.org/luafilesystem/}.
-\stopitem
-
-\startitem
- \type {lzlib}, by Tiago Dionizio, \hyphenatedurl
- {http://luaforge.net/projects/lzlib/}.
-\stopitem
-
-\startitem
- \type {md5}, by Roberto Ierusalimschy \hyphenatedurl
- {http://www.inf.puc-rio.br/~roberto/md5/md5-5/md5.html}.
-\stopitem
-
-\startitem
- \type {luasocket}, by Diego Nehab \hyphenatedurl
- {http://w3.impa.br/~diego/software/luasocket/}. The \type {.lua} support
- modules from \type {luasocket} are also preloaded inside the executable,
- there are no external file dependencies.
-\stopitem
-
-\stopitemize
-
-\stopsection
-
-\startsection[title={Testing}]
-
-\topicindex {testing}
-\topicindex {\PDF+date}
-
-For development reasons you can influence the used startup date and time. This can
-be done in two ways.
-
-\startitemize[n]
-
-\startitem
- By setting the environmment variable \type {SOURCE_DATE_EPOCH}. This will
- influence the \TEX\ parameters \type {time} and \type {date}, the random seed,
- the \PDF\ timestamp and the \PDF\ id that is derived from the time as well. This
- variable is consulted when the \KPSE\ library is enabled. Resolving is
- delegated to this library.
-\stopitem
-
-\startitem
- By setting the \type {start_time} variable in the \type {texconfig} table; as
- with other variables we use the internal name there. For compatibility
- reasons we also honour a \type {SOURCE_DATE_EPOCH} entry. It should be noted
- that there are no such variables in other engines and this method is only
- relevant in case the while setup happens in \LUA.
-\stopitem
-
-\stopitemize
-
-When Universal Time is needed, you can pass the flag \type {utc} to the engine. This
-property also works when the date and time are set by \LUATEX\ itself. It has a
-complementary entry \type {use_utc_time} in the \type {texconfig} table.
-
-There is some control possible, for instance prevent filename to be written to
-the \PDF\ file. This is discussed elsewhere. In \CONTEXT\ we provide the command
-line argument \type {--nodates} that does a bit more disabling of dates.
-
-\stopsection
-
-\stopchapter
-
-\stopcomponent
+% language=uk
+
+\environment luatex-style
+
+\startcomponent luatex-lua
+
+\startchapter[reference=lua,title={Using \LUATEX}]
+
+\startsection[title={Initialization},reference=init]
+
+\startsubsection[title={\LUATEX\ as a \LUA\ interpreter}]
+
+\topicindex {initialization}
+\topicindex {\LUA+interpreter}
+
+There are some situations that make \LUATEX\ behave like a standalone \LUA\
+interpreter:
+
+\startitemize[packed]
+\startitem
+ if a \type {--luaonly} option is given on the commandline, or
+\stopitem
+\startitem
+ if the executable is named \type {texlua} or \type {luatexlua}, or
+\stopitem
+\startitem
+ if the only non|-|option argument (file) on the commandline has the extension
+ \type {lua} or \type {luc}.
+\stopitem
+\stopitemize
+
+In this mode, it will set \LUA's \type {arg[0]} to the found script name, pushing
+preceding options in negative values and the rest of the command line in the
+positive values, just like the \LUA\ interpreter.
+
+\LUATEX\ will exit immediately after executing the specified \LUA\ script and is,
+in effect, a somewhat bulky stand alone \LUA\ interpreter with a bunch of extra
+preloaded libraries.
+
+\stopsubsection
+
+\startsubsection[title={\LUATEX\ as a \LUA\ byte compiler}]
+
+\topicindex {\LUA+byte code}
+
+There are two situations that make \LUATEX\ behave like the \LUA\ byte compiler:
+
+\startitemize[packed]
+\startitem if a \type {--luaconly} option is given on the command line, or \stopitem
+\startitem if the executable is named \type {texluac} \stopitem
+\stopitemize
+
+In this mode, \LUATEX\ is exactly like \type {luac} from the stand alone \LUA\
+distribution, except that it does not have the \type {-l} switch, and that it
+accepts (but ignores) the \type {--luaconly} switch. The current version of \LUA\
+can dump bytecode using \type {string.dump} so we might decide to drop this
+version of \LUATEX.
+
+\stopsubsection
+
+\startsubsection[title={Other commandline processing}]
+
+\topicindex {command line}
+
+When the \LUATEX\ executable starts, it looks for the \type {--lua} command line
+option. If there is no \type {--lua} option, the command line is interpreted in a
+similar fashion as the other \TEX\ engines. Some options are accepted but have no
+consequence. The following command|-|line options are understood:
+
+\starttabulate[|l|p|]
+\DB commandline argument \BC explanation \NC \NR
+\TB
+\NC \type{--credits} \NC display credits and exit \NC \NR
+\NC \type{--debug-format} \NC enable format debugging \NC \NR
+\NC \type{--draftmode} \NC switch on draft mode i.e.\ generate no output in \PDF\ mode \NC \NR
+\NC \type{--[no-]file-line-error} \NC disable/enable \type {file:line:error} style messages \NC \NR
+\NC \type{--[no-]file-line-error-style} \NC aliases of \type {--[no-]file-line-error} \NC \NR
+\NC \type{--fmt=FORMAT} \NC load the format file \type {FORMAT} \NC\NR
+\NC \type{--halt-on-error} \NC stop processing at the first error\NC \NR
+\NC \type{--help} \NC display help and exit \NC\NR
+\NC \type{--ini} \NC be \type {iniluatex}, for dumping formats \NC\NR
+\NC \type{--interaction=STRING} \NC set interaction mode: \type {batchmode}, \type {nonstopmode},
+ \type {scrollmode} or \type {errorstopmode} \NC \NR
+\NC \type{--jobname=STRING} \NC set the job name to \type {STRING} \NC \NR
+\NC \type{--kpathsea-debug=NUMBER} \NC set path searching debugging flags according to the bits of
+ \type {NUMBER} \NC \NR
+\NC \type{--lua=FILE} \NC load and execute a \LUA\ initialization script \NC\NR
+\NC \type{--[no-]mktex=FMT} \NC disable/enable \type {mktexFMT} generation with \type {FMT} is
+ \type {tex} or \type {tfm} \NC \NR
+\NC \type{--nosocket} \NC disable the \LUA\ socket library \NC\NR
+\NC \type{--output-comment=STRING} \NC use \type {STRING} for \DVI\ file comment instead of date (no
+ effect for \PDF) \NC \NR
+\NC \type{--output-directory=DIR} \NC use \type {DIR} as the directory to write files to \NC \NR
+\NC \type{--output-format=FORMAT} \NC use \type {FORMAT} for job output; \type {FORMAT} is \type {dvi}
+ or \type {pdf} \NC \NR
+\NC \type{--progname=STRING} \NC set the program name to \type {STRING} \NC \NR
+\NC \type{--recorder} \NC enable filename recorder \NC \NR
+\NC \type{--safer} \NC disable easily exploitable \LUA\ commands \NC\NR
+\NC \type{--[no-]shell-escape} \NC disable/enable system calls \NC \NR
+\NC \type{--shell-restricted} \NC restrict system calls to a list of commands given in \type
+ {texmf.cnf} \NC \NR
+\NC \type{--synctex=NUMBER} \NC enable \type {synctex} \NC \NR
+\NC \type{--utc} \NC use utc times when applicable \NC \NR
+\NC \type{--version} \NC display version and exit \NC \NR
+\LL
+\stoptabulate
+
+We don't support \prm {write} 18 because \type {os.execute} can do the same. It
+simplifies the code and makes more write targets possible.
+
+The value to use for \prm {jobname} is decided as follows:
+
+\startitemize
+\startitem
+ If \type {--jobname} is given on the command line, its argument will be the
+ value for \prm {jobname}, without any changes. The argument will not be
+ used for actual input so it need not exist. The \type {--jobname} switch only
+ controls the \prm {jobname} setting.
+\stopitem
+\startitem
+ Otherwise, \prm {jobname} will be the name of the first file that is read
+ from the file system, with any path components and the last extension (the
+ part following the last \type {.}) stripped off.
+\stopitem
+\startitem
+ There is an exception to the previous point: if the command line goes into
+ interactive mode (by starting with a command) and there are no files input
+ via \prm {everyjob} either, then the \prm {jobname} is set to \type
+ {texput} as a last resort.
+\stopitem
+\stopitemize
+
+The file names for output files that are generated automatically are created by
+attaching the proper extension (\type {log}, \type {pdf}, etc.) to the found
+\prm {jobname}. These files are created in the directory pointed to by \type
+{--output-directory}, or in the current directory, if that switch is not present.
+
+Without the \type {--lua} option, command line processing works like it does in
+any other \WEBC|-|based typesetting engine, except that \LUATEX\ has a few extra
+switches and lacks some others. Also, if the \type {--lua} option is present,
+\LUATEX\ will enter an alternative mode of command line processing in comparison
+to the standard \WEBC\ programs. In this mode, a small series of actions is taken
+in the following order:
+
+\startitemize[n]
+
+\startitem
+ First, it will parse the command line 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}.
+\stopitem
+
+\startitem
+ Next \LUATEX\ searches for the requested \LUA\ initialization script. If it
+ cannot be found using the actual name given on the command line, a second
+ attempt is made by prepending the value of the environment variable \type
+ {LUATEXDIR}, if that variable is defined in the environment.
+\stopitem
+
+\startitem
+ 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, \type {--safer} \type {nil}s the following functions:
+
+ \blank
+
+ \starttabulate[|c|l|]
+ \DB library \BC functions \NC \NR
+ \TB
+ \NC \type {os} \NC \type {execute} \type {exec} \type {spawn} \type {setenv}
+ \type {rename} \type {remove} \type {tmpdir} \NC \NR
+ \NC \type {io} \NC \type {popen} \type {output} \type {tmpfile} \NC \NR
+ \NC \type {lfs} \NC \type {rmdir} \type {mkdir} \type {chdir} \type {lock}
+ \type {touch} \NC \NR
+ \LL
+ \stoptabulate
+
+ \blank
+
+ Furthermore, it disables loading of compiled \LUA\ libraries and it makes
+ \type {io.open()} fail on files that are opened for anything besides reading.
+\stopitem
+
+\startitem
+ When \LUATEX\ starts it sets the \type {locale} to a neutral value. If for
+ some reason you use \type {os.locale}, you need to make sure you \type {nil}
+ it afterwards because otherwise it can interfere with code that for instance
+ generates dates. You can ignore the \type {locale} with:
+
+ \starttyping
+ os.setlocale(nil,nil)
+ \stoptyping
+
+ The \type {--nosocket} option 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.
+\stopitem
+
+\startitem
+ Next the initialization script is loaded and executed. From within the
+ script, the entire command line is available in the \LUA\ table \type {arg},
+ beginning with \type {arg[0]}, containing the name of the executable. As
+ consequence warnings about unrecognized options are suppressed.
+\stopitem
+
+\stopitemize
+
+Command line 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 \type {tex}, \type {token}, \type {node} and
+\type {pdf}, are off|-|limits during the execution of the startup file (they
+are \type {nil}'d). Special care is taken that \type {texio.write} and \type
+{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 \prm {jobname} yet at this point).
+
+Everything you do in the \LUA\ initialization script will remain visible during
+the rest of the run, with the exception of the \TEX\ specific libraries like
+\type {tex}, \type {token}, \type {node} and \type {pdf} tables. These will be
+initialized to their documented state after the execution of the script. You
+should not store anything in variables or within tables with these 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 command line, set values in the
+\type {texconfig} table, and register the callbacks you need.
+
+\LUATEX\ allows some of the command line options to be overridden by reading
+values from the \type {texconfig} table at the end of script execution (see the
+description of the \type {texconfig} table later on in this document for more
+details on which ones exactly).
+
+Unless the \type {texconfig} table tells \LUATEX\ not to initialize \KPATHSEA\
+at all (set \type {texconfig.kpse_init} to \type {false} for that), \LUATEX\
+acts on some more command line options after the initialization script is
+finished: 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.
+
+\stopsubsection
+
+\stopsection
+
+\startsection[title={\LUA\ behaviour}]
+
+\startsubsection[title={The \LUA\ version}]
+
+\topicindex {\LUA+libraries}
+\topicindex {\LUA+extensions}
+
+We currently use \LUA\ 5.3 and will follow developments of the language but
+normally with some delay. Therefore the user needs to keep an eye on (subtle)
+differences in successive versions of the language. Also, \LUAJITTEX\ lags behind
+in the sense that \LUAJIT\ is not in sync with regular \LUA\ development. Here is
+an example of one aspect.
+
+\LUA s \type {tostring} function (and \type {string.format} may return values in
+scientific notation, thereby confusing the \TEX\ end of things when it is used as
+the right|-|hand side of an assignment to a \prm {dimen} or \prm {count}. The
+output of these serializers also depend on the \LUA\ version, so in \LUA\ 5.3 you
+can get different output than from 5.2.
+
+\stopsubsection
+
+\startsubsection[title={Integration in the \TDS\ ecosystem}]
+
+The main \TEX\ distributions follow the \TEX\ directory structure (\TDS).
+\LUATEX\ is able to use the kpathsea library to find \type {require()}d modules.
+For this purpose, \type {package.searchers[2]} is replaced by a different loader
+function, that decides at runtime whether to use kpathsea or the built|-|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()}.
+
+\stopsubsection
+
+\startsubsection[title={Loading libraries}]
+
+\LUATEX\ is able to use dynamically loadable \LUA\ libraries, unless
+\type {--safer} was given as an option on the command line. For this purpose,
+\type {package.searchers[3]} is replaced by a different loader function, that
+decides at runtime whether to use \KPATHSEA\ or the built|-|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.cpath} loader.
+
+This functionality required an extension to kpathsea. 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 is
+\type {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 binaries directory only.
+Of course it no big deal to write an alternative loader and use that in a macro
+package. 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.
+
+Loading dynamic \LUA\ libraries will fail if there are two \LUA\ libraries loaded
+at the same time (which will typically happen on \type {win32}, because there is
+one \LUA\ 5.3 inside \LUATEX, and another will likely be linked to the \DLL\ file
+of the module itself).
+
+\stopsubsection
+
+\startsubsection[title={Executing programs}]
+
+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 assumed intention to typeset a document (and by that we
+mean that it is called as \type {luatex}, as opposed to \type {texlua}, and that
+the command line option \type {--luaonly} was not given), it will only run the
+four functions above if the matching \type {texmf.cnf} variable(s) or their \type
+{texconfig} (see \in {section} [texconfig]) counterparts allow execution of the
+requested system command. In \quote {script interpreter} runs of \LUATEX, these
+settings have no effect, and all four functions have their original meaning.
+
+Some libraries have a few more functions, either coded in \CCODE\ or in \LUA. For
+instance, when we started with \LUATEX\ we added some helpers to the \type
+{luafilesystem} namespace \type {lfs}. The two boolean functions \type
+{lfs.isdir} and \type {lfs.isfile} were speedy and better variants of what could
+be done with \type {lfs.attributes}. The additional function \type
+{lfs.shortname} takes a file name and returns its short name on \type {win32}
+platforms. Finally, for non|-|\type {win32} platforms only, we provided \type
+{lfs.readlink} that takes an existing symbolic link as argument and returns its
+name. However, the \type library evolved so we have dropped these in favour of
+pure \LUA\ variants. The \type {shortname} helper is obsolete and now just
+returns the name.
+
+\stopsubsection
+
+\startsubsection[title={Multibyte \type {string} functions}]
+
+The \type {string} library has a few extra functions, for example \libidx
+{string} {explode}. This function takes upto two arguments: \type
+{string.explode(s[,m])} and returns an array containing the string argument \type
+{s} split into sub-strings based on the value of the string argument \type {m}.
+The second argument is a string that is either empty (this splits the string into
+characters), a single character (this splits on each occurrence of that
+character, possibly introducing empty strings), or a single character followed by
+the plus sign \type {+} (this special version does not create empty sub-strings).
+The default value for \type {m} is \quote {\type { +}} (multiple spaces). Note:
+\type {m} is not hidden by surrounding braces as it would be if this function was
+written in \TEX\ macros.
+
+The \type {string} library also has six extra iterators that return strings
+piecemeal: \libidx {string} {utfvalues}, \libidx {string} {utfcharacters},
+\libidx {string} {characters}, \libidx {string} {characterpairs}, \libidx
+{string} {bytes} and \libidx {string} {bytepairs}.
+
+\startitemize
+\startitem
+ \type {string.utfvalues(s)}: an integer value in the \UNICODE\ range
+\stopitem
+\startitem
+ \type {string.utfcharacters(s)}: a string with a single \UTF-8 token in it
+\stopitem
+\startitem
+ \type {string.cWharacters(s)}: a string containing one byte
+\stopitem
+\startitem
+ \type {string.characterpairs(s)}: two strings each containing one byte or an
+ empty second string if the string length was odd
+\stopitem
+\startitem
+ \type {string.bytes(s)}: a single byte value
+\stopitem
+\startitem
+ \type {string.bytepairs(s)}: two byte values or nil instead of a number as
+ its second return value if the string length was odd
+\stopitem
+\stopitemize
+
+The \type {string.characterpairs()} and \type {string.bytepairs()} iterators
+are useful especially in the conversion of \UTF16 encoded data into \UTF8.
+
+There is also a two|-|argument form of \type {string.dump()}. The second argument
+is a boolean which, if true, strips the symbols from the dumped data. This
+matches an extension made in \type {luajit}. This is typically a function that
+gets adapted as \LUA\ itself progresses.
+
+The \type {string} library functions \type {len}, \type {lower}, \type {sub}
+etc.\ are not \UNICODE|-|aware. For strings in the \UTF8 encoding, i.e., strings
+containing characters above code point 127, the corresponding functions from the
+\type {slnunicode} library can be used, e.g., \type {unicode.utf8.len}, \type
+{unicode.utf8.lower} etc.\ The exceptions are \type {unicode.utf8.find}, that
+always returns byte positions in a string, and \type {unicode.utf8.match} and
+\type {unicode.utf8.gmatch}. While the latter two functions in general {\it
+are} \UNICODE|-|aware, they fall|-|back to non|-|\UNICODE|-|aware behavior when
+using the empty capture \type {()} but other captures work as expected. For the
+interpretation of character classes in \type {unicode.utf8} functions refer to
+the library sources at \hyphenatedurl {http://luaforge.net/projects/sln}.
+
+Version 5.3 of \LUA\ provides some native \UTF8 support but we have added a few
+similar helpers too: \libidx {string} {utfvalue}, \libidx {string} {utfcharacter}
+and \libidx {string} {utflength}.
+
+\startitemize
+\startitem
+ \type {string.utfvalue(s)}: returns the codepoints of the characters in the
+ given string
+\stopitem
+\startitem
+ \type {string.utfcharacter(c,...)}: returns a string with the characters of
+ the given code points
+\stopitem
+\startitem
+ \type {string.utflength(s)}: returns the length oif the given string
+\stopitem
+\stopitemize
+
+These three functions are relative fast and don't do much checking. They can be
+used as building blocks for other helpers.
+
+\stopsubsection
+
+\startsubsection[title={Extra \type {os} library functions}]
+
+The \type {os} library has a few extra functions and variables: \libidx {os}
+{selfdir}, \libidx {os} {exec}, \libidx {os} {spawn}, \libidx {os} {setenv},
+\libidx {os} {env}, \libidx {os} {gettimeofday}, \libidx {os} {times}, \libidx
+{os} {tmpdir}, \libidx {os} {type}, \libidx {os} {name} and \libidx {os} {uname},
+that we will discuss here.
+
+\startitemize
+
+\startitem
+ \type {os.selfdir} is a variable that holds the directory path of the
+ actual executable. For example: \type {\directlua {tex.sprint(os.selfdir)}}.
+\stopitem
+
+\startitem
+ \type {os.exec(commandline)} is a variation on \type {os.execute}. Here
+ \type {commandline} can be either a single string or a single table.
+
+ \startitemize
+
+ \startitem
+ If the argument is a table \LUATEX\ first checks if there is a value at
+ integer index zero. If there is, this is the command to be executed.
+ Otherwise, it will use the value at integer index one. If neither are
+ present, nothing at all happens.
+ \stopitem
+
+ \startitem
+ The set of consecutive values starting at integer~1 in the table are the
+ arguments that are passed on to the command (the value at index~1 becomes
+ \type {arg[0]}). The command is searched for in the execution path, so
+ there is normally no need to pass on a fully qualified path name.
+ \stopitem
+
+ \startitem
+ If the argument is a string, then it is automatically converted into a
+ table by splitting on whitespace. In this case, it is impossible for the
+ command and first argument to differ from each other.
+ \stopitem
+
+ \startitem
+ In the string argument format, whitespace can be protected by putting
+ (part of) an argument inside single or double quotes. One layer of quotes
+ is interpreted by \LUATEX, and all occurrences of \type {\"}, \type {\'}
+ or \type {\\} within the quoted text are unescaped. In the table format,
+ there is no string handling taking place.
+ \stopitem
+
+ \stopitemize
+
+ This function normally does not return control back to the \LUA\ script: the
+ command will replace the current process. However, it will return the two
+ values \type {nil} and \type {error} if there was a problem while
+ attempting to execute the command.
+
+ On \MSWINDOWS, the current process is actually kept in memory until after the
+ execution of the command has finished. This prevents crashes in situations
+ where \TEXLUA\ scripts are run inside integrated \TEX\ environments.
+
+ The original reason for this command is that it cleans out the current
+ process before starting the new one, making it especially useful for use in
+ \TEXLUA.
+\stopitem
+
+\startitem
+ \type {os.spawn(commandline)} is a returning version of \type {os.exec},
+ with otherwise identical calling conventions.
+
+ If the command ran ok, then the return value is the exit status of the
+ command. Otherwise, it will return the two values \type {nil} and \type
+ {error}.
+\stopitem
+
+\startitem
+ \type {os.setenv(key,value)} sets a variable in the environment. Passing
+ \type {nil} instead of a value string will remove the variable.
+\stopitem
+
+\startitem
+ \type {os.env} is a hash table containing a dump of the variables and
+ values in the process environment at the start of the run. It is writeable,
+ but the actual environment is \notabene {not} updated automatically.
+\stopitem
+
+\startitem
+ \type {os.gettimeofday()} returns the current \quote {\UNIX\ time}, but as a
+ float. This function is not available on the \SUNOS\ platforms, so do not use
+ this function for portable documents.
+\stopitem
+
+\startitem
+ \type {os.times()}returns the current process times according to \ the
+ \UNIX\ C library function \quote {times}. This function is not available on
+ the \MSWINDOWS\ and \SUNOS\ platforms, so do not use this function for
+ portable documents.
+\stopitem
+
+\startitem
+ \type {os.tmpdir()} creates a directory in the \quote {current directory}
+ with the name \type {luatex.XXXXXX} where the \type {X}-es are replaced by a
+ unique string. The function also returns this string, so you can \type
+ {lfs.chdir()} into it, or \type {nil} if it failed to create the directory.
+ The user is responsible for cleaning up at the end of the run, it does not
+ happen automatically.
+\stopitem
+
+\startitem
+ \type {os.type} is a string that gives a global indication of the class of
+ operating system. The possible values are currently \type {windows}, \type
+ {unix}, and \type {msdos} (you are unlikely to find this value \quote {in the
+ wild}).
+\stopitem
+
+\startitem
+ \type {os.name} is a string that gives a more precise indication of the
+ operating system. These possible values are not yet fixed, and for \type
+ {os.type} values \type {windows} and \type {msdos}, the \type {os.name}
+ values are simply \type {windows} and \type {msdos}
+
+ The list for the type \type {unix} is more precise: \type {linux}, \type
+ {freebsd}, \type {kfreebsd}, \type {cygwin}, \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).
+\stopitem
+
+\startitem
+ \type {os.uname} returns a table with specific operating system
+ information acquired at runtime. The keys in the returned table are all
+ string values, and their names are: \type {sysname}, \type {machine}, \type
+ {release}, \type {version}, and \type {nodename}.
+\stopitem
+
+\stopitemize
+
+\stopsubsection
+
+\startsubsection[title={Binary input from files with \type {fio}}]
+
+There is a whole set of helpers for reading numbers and strings from a file:
+\libidx {fio} {readcardinal1}, \libidx {fio} {readcardinal2}, \libidx {fio}
+{readcardinal3}, \libidx {fio} {readcardinal4}, \libidx {fio}
+{readcardinaltable}, \libidx {fio} {readinteger1}, \libidx {fio} {readinteger2},
+\libidx {fio} {readinteger3}, \libidx {fio} {readinteger4}, \libidx {fio}
+{readintegertable}, \libidx {fio} {readfixed2}, \libidx {fio} {readfixed4},
+\libidx {fio} {read2dot14}, \libidx {fio} {setposition}, \libidx {fio}
+{getposition}, \libidx {fio} {skipposition}, \libidx {fio} {readbytes}, \libidx
+{fio} {readbytetable}. They work on normal \LUA\ file handles.
+
+%libidx{fio}{readline}
+%libidx{fio}{recordfilename}
+%libidx{fio}{checkpermission}
+
+This library provides a set of functions for reading numbers from a file and
+in addition to the regular \type {io} library functions.
+
+\starttabulate
+\NC \type{readcardinal1(f)} \NC a 1 byte unsigned integer \NC \NR
+\NC \type{readcardinal2(f)} \NC a 2 byte unsigned integer \NC \NR
+\NC \type{readcardinal3(f)} \NC a 3 byte unsigned integer \NC \NR
+\NC \type{readcardinal4(f)} \NC a 4 byte unsigned integer \NC \NR
+\NC \type{readcardinaltable(f,n,b)} \NC \type {n} cardinals of \type {b} bytes \NC \NR
+\NC \type{readinteger1(f)} \NC a 1 byte signed integer \NC \NR
+\NC \type{readinteger2(f)} \NC a 2 byte signed integer \NC \NR
+\NC \type{readinteger3(f)} \NC a 3 byte signed integer \NC \NR
+\NC \type{readinteger4(f)} \NC a 4 byte signed integer \NC \NR
+\NC \type{readintegertable(f,n,b)} \NC \type {n} integers of \type {b} bytes \NC \NR
+\NC \type{readfixed2(f)} \NC a 2 byte float (used in font files) \NC \NR
+\NC \type{readfixed4(f)} \NC a 4 byte float (used in font files) \NC \NR
+\NC \type{read2dot14(f)} \NC a 2 byte float (used in font files) \NC \NR
+\NC \type{setposition(f,p)} \NC goto position \type {p} \NC \NR
+\NC \type{getposition(f)} \NC get the current position \NC \NR
+\NC \type{skipposition(f,n)} \NC skip \type {n} positions \NC \NR
+\NC \type{readbytes(f,n)} \NC \type {n} bytes \NC \NR
+\NC \type{readbytetable(f,n)} \NC \type {n} bytes\NC \NR
+\stoptabulate
+
+\stopsubsection
+
+\startsubsection[title={Binary input from strings with \type {sio}}]
+
+A similar set of function as in the \type {fio} library is available in the \type
+{sio} library: \libidx {sio} {readcardinal1}, \libidx {sio} {readcardinal2},
+\libidx {sio} {readcardinal3}, \libidx {sio} {readcardinal4}, \libidx {sio}
+{readcardinaltable}, \libidx {sio} {readinteger1}, \libidx {sio} {readinteger2},
+\libidx {sio} {readinteger3}, \libidx {sio} {readinteger4}, \libidx {sio}
+{readintegertable}, \libidx {sio} {readfixed2}, \libidx {sio} {readfixed4},
+\libidx {sio} {read2dot14}, \libidx {sio} {setposition}, \libidx {sio}
+{getposition}, \libidx {sio} {skipposition}, \libidx {sio} {readbytes} and
+\libidx {sio} {readbytetable}. Here the first argument is a string instead of a
+file handle. More details can be found in the previous section.
+
+\stopsubsection
+
+\startsubsection[title={Hashes conform \type {sha2}}]
+
+This library is a side effect of the \type {pdfe} library that needs such
+helpers. The \libidx{sha2}{digest256}, \libidx{sha2}{digest384} and
+\libidx{sha2}{digest512} functions accept a string and return a string with the
+hash.
+
+\stopsubsection
+
+\startsubsection[title={Locales}]
+
+\index {locales}
+
+In stock \LUA, many things depend on the current locale. In \LUATEX, we can't do
+that, because it makes documents unportable. While \LUATEX\ is running if
+forces the following locale settings:
+
+\starttyping
+LC_CTYPE=C
+LC_COLLATE=C
+LC_NUMERIC=C
+\stoptyping
+
+\stopsubsection
+
+\stopsection
+
+\startsection[title={\LUA\ modules}]
+
+\topicindex {\LUA+libraries}
+\topicindex {\LUA+modules}
+
+Some modules that are normally external to \LUA\ are statically linked in with
+\LUATEX, because they offer useful functionality:
+
+\startitemize
+
+\startitem
+ \type {lpeg}, by Roberto Ierusalimschy, \hyphenatedurl
+ {http://www.inf.puc-rio.br/~roberto/lpeg/lpeg.html}. This library is not
+ \UNICODE|-|aware, but interprets strings on a byte|-|per|-|byte basis. This
+ mainly means that \type {lpeg.S} cannot be used with \UTF8 characters encoded
+ in more than two bytes, and thus \type {lpeg.S} will look for one of those
+ two bytes when matching, not the combination of the two. The same is true for
+ \type {lpeg.R}, although the latter will display an error message if used
+ with multibyte characters. Therefore \type {lpeg.R('aä')} results in the
+ message \type {bad argument #1 to 'R' (range must have two characters)},
+ since to \type {lpeg}, \type {ä} is two 'characters' (bytes), so \type {aä}
+ totals three. In practice this is no real issue and with some care you can
+ deal with \UNICODE\ just fine.
+\stopitem
+
+\startitem
+ \type {slnunicode}, from the \type {selene} libraries, \hyphenatedurl
+ {http://luaforge.net/projects/sln}. This library has been slightly extended
+ so that the \type {unicode.utf8.*} functions also accept the first 256 values
+ of plane~18. This is the range \LUATEX\ uses for raw binary output, as
+ explained above. We have no plans to provide more like this because you can
+ basically do all that you want in \LUA.
+\stopitem
+
+\startitem
+ \type {luazip}, from the kepler project, \hyphenatedurl
+ {http://www.keplerproject.org/luazip/}.
+\stopitem
+
+\startitem
+ \type {luafilesystem}, also from the kepler project, \hyphenatedurl
+ {http://www.keplerproject.org/luafilesystem/}.
+\stopitem
+
+\startitem
+ \type {lzlib}, by Tiago Dionizio, \hyphenatedurl
+ {http://luaforge.net/projects/lzlib/}.
+\stopitem
+
+\startitem
+ \type {md5}, by Roberto Ierusalimschy \hyphenatedurl
+ {http://www.inf.puc-rio.br/~roberto/md5/md5-5/md5.html}.
+\stopitem
+
+\startitem
+ \type {luasocket}, by Diego Nehab \hyphenatedurl
+ {http://w3.impa.br/~diego/software/luasocket/}. The \type {.lua} support
+ modules from \type {luasocket} are also preloaded inside the executable,
+ there are no external file dependencies.
+\stopitem
+
+\stopitemize
+
+\stopsection
+
+\startsection[title={Testing}]
+
+\topicindex {testing}
+\topicindex {\PDF+date}
+
+For development reasons you can influence the used startup date and time. This can
+be done in two ways.
+
+\startitemize[n]
+
+\startitem
+ By setting the environmment variable \type {SOURCE_DATE_EPOCH}. This will
+ influence the \TEX\ parameters \type {time} and \type {date}, the random seed,
+ the \PDF\ timestamp and the \PDF\ id that is derived from the time as well. This
+ variable is consulted when the \KPSE\ library is enabled. Resolving is
+ delegated to this library.
+\stopitem
+
+\startitem
+ By setting the \type {start_time} variable in the \type {texconfig} table; as
+ with other variables we use the internal name there. For compatibility
+ reasons we also honour a \type {SOURCE_DATE_EPOCH} entry. It should be noted
+ that there are no such variables in other engines and this method is only
+ relevant in case the while setup happens in \LUA.
+\stopitem
+
+\stopitemize
+
+When Universal Time is needed, you can pass the flag \type {utc} to the engine. This
+property also works when the date and time are set by \LUATEX\ itself. It has a
+complementary entry \type {use_utc_time} in the \type {texconfig} table.
+
+There is some control possible, for instance prevent filename to be written to
+the \PDF\ file. This is discussed elsewhere. In \CONTEXT\ we provide the command
+line argument \type {--nodates} that does a bit more disabling of dates.
+
+\stopsection
+
+\stopchapter
+
+\stopcomponent