diff options
Diffstat (limited to 'Master/texmf-dist/doc/luatex/base/luatex-lua.tex')
-rw-r--r-- | Master/texmf-dist/doc/luatex/base/luatex-lua.tex | 1520 |
1 files changed, 760 insertions, 760 deletions
diff --git a/Master/texmf-dist/doc/luatex/base/luatex-lua.tex b/Master/texmf-dist/doc/luatex/base/luatex-lua.tex index 3d6d20c35dd..f9107fa1f96 100644 --- a/Master/texmf-dist/doc/luatex/base/luatex-lua.tex +++ b/Master/texmf-dist/doc/luatex/base/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 |