Source Browser ?

1% language=us engine=luatex runpath=texruns:manuals/luatex
2
3\environment luatex-style
4
5\startcomponent luatex-lua
6
7\startchapter[reference=lua,title={Using \LUATEX}]
8
9\startsection[title={Initialization},reference=init]
10
11\startsubsection[title={\LUATEX\ as a \LUA\ interpreter}]
12
13\topicindex {initialization}
14\topicindex {\LUA+interpreter}
15
16There are some situations that make \LUATEX\ behave like a standalone \LUA\
17interpreter:
18
19\startitemize[packed]
20\startitem
21    if a \type {--luaonly} option is given on the commandline, or
22\stopitem
23\startitem
24    if the executable is named \type {texlua} or \type {luatexlua}, or
25\stopitem
26\startitem
27    if the only non|-|option argument (file) on the commandline has the extension
28    \type {lua} or \type {luc}.
29\stopitem
30\stopitemize
31
32In this mode, it will set \LUA's \type {arg[0]} to the found script name, pushing
33preceding options in negative values and the rest of the command line in the
34positive values, just like the \LUA\ interpreter.
35
36\LUATEX\ will exit immediately after executing the specified \LUA\ script and is,
37in effect, a somewhat bulky stand alone \LUA\ interpreter with a bunch of extra
38preloaded libraries.
39
40\stopsubsection
41
42\startsubsection[title={\LUATEX\ as a \LUA\ byte compiler}]
43
44\topicindex {\LUA+byte code}
45
46There are two situations that make \LUATEX\ behave like the \LUA\ byte compiler:
47
48\startitemize[packed]
49\startitem if a \type {--luaconly} option is given on the command line, or \stopitem
50\startitem if the executable is named \type {texluac} \stopitem
51\stopitemize
52
53In this mode, \LUATEX\ is exactly like \type {luac} from the stand alone \LUA\
54distribution, except that it does not have the \type {-l} switch, and that it
55accepts (but ignores) the \type {--luaconly} switch. The current version of \LUA\
56can dump bytecode using \type {string.dump} so we might decide to drop this
57version of \LUATEX.
58
59\stopsubsection
60
61\startsubsection[title={Other commandline processing}]
62
63\topicindex {command line}
64
65When the \LUATEX\ executable starts, it looks for the \type {--lua} command line
66option. If there is no \type {--lua} option, the command line is interpreted in a
67similar fashion as the other \TEX\ engines. Some options are accepted but have no
68consequence. The following command|-|line options are understood:
69
70\starttabulate[|l|p|]
71\DB commandline argument                \BC explanation \NC \NR
72\TB
73\NC \type{--credits}                    \NC display credits and exit \NC \NR
74\NC \type{--debug-format}               \NC enable format debugging \NC \NR
75\NC \type{--draftmode}                  \NC switch on draft mode i.e.\ generate no output in \PDF\ mode \NC \NR
76\NC \type{--[no-]check-dvi-total-pages} \NC exit when DVI exceeds 65535 pages (default: check) \NC \NR
77\NC \type{--[no-]file-line-error}       \NC disable/enable \type {file:line:error} style messages \NC \NR
78\NC \type{--[no-]file-line-error-style} \NC aliases of \type {--[no-]file-line-error} \NC \NR
79\NC \type{--fmt=FORMAT}                 \NC load the format file \type {FORMAT} \NC\NR
80\NC \type{--halt-on-error}              \NC stop processing at the first error\NC \NR
81\NC \type{--help}                       \NC display help and exit \NC\NR
82\NC \type{--ini}                        \NC be \type {iniluatex}, for dumping formats \NC\NR
83\NC \type{--interaction=STRING}         \NC set interaction mode: \type {batchmode}, \type {nonstopmode},
84                                            \type {scrollmode} or \type {errorstopmode} \NC \NR
85\NC \type{--jobname=STRING}             \NC set the job name to \type {STRING} \NC \NR
86\NC \type{--kpathsea-debug=NUMBER}      \NC set path searching debugging flags according to the bits of
87                                           \type {NUMBER} \NC \NR
88\NC \type{--lua=FILE}                   \NC load and execute a \LUA\ initialization script \NC\NR
89\NC \type{--luadebug}                   \NC enable the \type{debug} library\NC\NR
90\NC \type{--[no-]mktex=FMT}             \NC disable/enable \type {mktexFMT} generation with \type {FMT} is
91                                            \type {tex} or \type {tfm} \NC \NR
92\NC \type{--nosocket}                   \NC disable the \LUA\ socket library \NC\NR
93\NC \type{--no-socket}                  \NC disable the \LUA\ socket library \NC\NR
94\NC \type{--socket}                     \NC enable the \LUA\ socket library \NC\NR
95\NC \type{--output-comment=STRING}      \NC use \type {STRING} for \DVI\ file comment instead of date (no
96                                            effect for \PDF) \NC \NR
97\NC \type{--output-directory=DIR}       \NC use \type {DIR} as the directory to write files to \NC \NR
98\NC \type{--output-format=FORMAT}       \NC use \type {FORMAT} for job output; \type {FORMAT} is \type {dvi}
99                                            or \type {pdf} \NC \NR
100\NC \type{--progname=STRING}            \NC set the program name to \type {STRING} \NC \NR
101\NC \type{--recorder}                   \NC enable filename recorder \NC \NR
102\NC \type{--safer}                      \NC disable easily exploitable \LUA\ commands \NC\NR
103\NC \type{--[no-]shell-escape}          \NC disable/enable system calls \NC \NR
104\NC \type{--shell-restricted}           \NC restrict system calls to a list of commands given in \type
105                                            {texmf.cnf} \NC \NR
106\NC \type{--synctex=NUMBER}             \NC enable \type {synctex} \NC \NR
107\NC \type{--utc}                        \NC use utc times when applicable \NC \NR
108\NC \type{--version}                    \NC display version and exit \NC \NR
109\LL
110\stoptabulate
111
112We don't support \prm {write} 18 because \type {os.execute} can do the same. It
113simplifies the code and makes more write targets possible.
114
115The value to use for \prm {jobname} is decided as follows:
116
117\startitemize
118\startitem
119    If \type {--jobname} is given on the command line, its argument will be the
120    value for \prm {jobname}, without any changes. The argument will not be
121    used for actual input so it need not exist. The \type {--jobname} switch only
122    controls the \prm {jobname} setting.
123\stopitem
124\startitem
125    Otherwise, \prm {jobname} will be the name of the first file that is read
126    from the file system, with any path components and the last extension (the
127    part following the last \type {.}) stripped off.
128\stopitem
129\startitem
130    There is an exception to the previous point: if the command line goes into
131    interactive mode (by starting with a command) and there are no files input
132    via \prm {everyjob} either, then the \prm {jobname} is set to \type
133    {texput} as a last resort.
134\stopitem
135\stopitemize
136
137The file names for output files that are generated automatically are created by
138attaching the proper extension (\type {log}, \type {pdf}, etc.) to the found
139\prm {jobname}. These files are created in the directory pointed to by \type
140{--output-directory}, or in the current directory, if that switch is not present.
141If \type{--output-directory} is not empty, its value it's copied to the
142\type{TEXMF_OUTPUT_DIRECTORY} env. variable; if it's empty, the value of
143\type{TEXMF_OUTPUT_DIRECTORY} is the value of the output directory.
144
145
146Without the \type {--lua} option, command line processing works like it does in
147any other \WEBC|-|based typesetting engine, except that \LUATEX\ has a few extra
148switches and lacks some others. Also, if the \type {--lua} option is present,
149\LUATEX\ will enter an alternative mode of command line processing in comparison
150to the standard \WEBC\ programs. In this mode, a small series of actions is taken
151in the following order:
152
153\startitemize[n]
154
155\startitem
156    First, it will parse the command line as usual, but it will only interpret a
157    small subset of the options immediately: \type {--safer}, \type {--nosocket},
158    \type {--no-socket},
159    \type {--socket}, \type {--[no-]shell-escape}, \type {--enable-write18}, \type
160    {--disable-write18}, \type {--shell-restricted}, \type {--help}, \type
161    {--version}, and \type {--credits}.
162\stopitem
163
164\startitem
165    Next \LUATEX\ searches for the requested \LUA\ initialization script. If it
166    cannot be found using the actual name given on the command line, a second
167    attempt is made by prepending the value of the environment variable \type
168    {LUATEXDIR}, if that variable is defined in the environment.
169\stopitem
170
171\startitem
172    Then it checks the various safety switches. You can use those to disable some
173    \LUA\ commands that can easily be abused by a malicious document. Currently
174    \type {--safer} nils the following functions:
175
176    \blank
177
178    \starttabulate[|c|l|]
179        \DB library     \BC functions \NC \NR
180        \TB
181        \NC \type {os}  \NC \type {execute} \type {exec} \type{kpsepopen}
182                            \type {spawn} \type {setenv}
183                            \type {rename} \type {remove} \type {tmpdir} \NC \NR
184        \NC \type {io}  \NC \type {popen} \type {output} \type {tmpfile} \NC \NR
185        \NC \type {lfs} \NC \type {rmdir} \type {mkdir} \type {mkdirp} \type {chdir}
186                            \type {lock}  \type {touch} \NC \NR
187        \LL
188    \stoptabulate
189
190    \blank
191
192    Furthermore, it disables loading of compiled \LUA\ libraries and it makes
193    \type {io.open()} fail on files that are opened for anything besides reading.
194
195    Finally, it disables the \type {socket} library unconditionally (but not the
196    \type {mime} library which is always available).
197
198    From version 1.18.0  and if  \KPATHSEA\ is used, with the exception of \type{debug.traceback}
199    the \type{debug} library is not enabled by default; it can be enabled with the \type
200    {--luadebug} switch. The \type{debug} library is always enabled in shell-escape mode.
201
202   Also from version 1.18.0 and if  \KPATHSEA\ is used, the functions
203   \type{os.rename},\type{os.remove}, \type{lfs.attributes}, \type{lfs.chdir},
204   \type{lfs.lock_dir}, \type{lfs.dir}, \type{lfs.link}, \type{lfs.mkdir}, \type{lfs.mkdirp},
205   \type{lfs.rmdir}, \type{lfs.symlinkattributes}, \type{lfs.touch}
206   return \type{true} if both \type{kpse.in_name_ok_silent_extended} and
207   \type{kpse.out_name_ok_silent_extended} validate the pathname;
208   \type{lfs.attributes}, \type{lfs.dir} and  \type{lfs.symlinkattributes} are validated
209   only against \type{kpse.in_name_ok_silent_extended}.
210
211
212
213\stopitem
214
215\startitem
216    When \LUATEX\ starts it sets the \type {locale} to a neutral value. If for
217    some reason you use \type {os.setlocale}, you need to make sure you \type {nil}
218    it afterwards because otherwise it can interfere with code that for instance
219    generates dates. You can ignore the \type {locale} with:
220
221    \starttyping
222    os.setlocale(nil,nil)
223    \stoptyping
224
225    The \type {--nosocket} or \type {--no-socket} option makes the socket library
226    unavailable, so that \LUA\ cannot use networking. The \type {--socket} option
227    makes the socket library available.
228
229    The switches \type {--[no-]shell-escape}, \type {--[enable|disable]-write18}, and
230    \type {--shell-restricted} have the same effects as in \PDFTEX, and additionally
231    make \type {io.popen()}, \type {os.execute}, \type {os.exec}, \type {os.kpsepopen}
232    and \type {os.spawn} adhere to the requested option.
233
234    By default the socket library is not enabled: one can enable it with with \type
235    {--socket} or with \type {--shell-escape}  (but without  \type {--shell-restricted})
236    and disable it with \type {--nosocket} (or \type {--no-socket}) or unconditionally
237    with \type {--safer}.
238
239    In case of conflictual options, the most restrictive wins.
240
241    The \type{mime} library is always available.
242
243\stopitem
244
245\startitem
246    Next the initialization script is loaded and executed. From within the
247    script, the entire command line is available in the \LUA\ table \type {arg},
248    beginning with \type {arg[0]}, containing the name of the executable. As
249    consequence warnings about unrecognized options are suppressed.
250\stopitem
251
252\stopitemize
253
254Command line processing happens very early on. So early, in fact, that none of
255\TEX's initializations have taken place yet. For that reason, the tables that
256deal with typesetting, like \type {tex}, \type {token}, \type {node} and
257\type {pdf}, are off|-|limits during the execution of the startup file (they
258are \type {nil}'d). Special care is taken that \type {texio.write} and \type
259{texio.write_nl} function properly, so that you can at least report your actions
260to the log file when (and if) it eventually becomes opened (note that \TEX\ does
261not even know its \prm {jobname} yet at this point).
262
263Everything you do in the \LUA\ initialization script will remain visible during
264the rest of the run, with the exception of the \TEX\ specific libraries like
265\type {tex}, \type {token}, \type {node} and \type {pdf} tables. These will be
266initialized to their documented state after the execution of the script. You
267should not store anything in variables or within tables with these four global
268names, as they will be overwritten completely.
269
270We recommend you use the startup file only for your own \TEX|-|independent
271initializations (if you need any), to parse the command line, set values in the
272\type {texconfig} table, and register the callbacks you need.
273
274\LUATEX\ allows some of the command line options to be overridden by reading
275values from the \type {texconfig} table at the end of script execution (see the
276description of the \type {texconfig} table later on in this document for more
277details on which ones exactly).
278
279Unless the \type {texconfig} table tells \LUATEX\ not to initialize \KPATHSEA\
280at all (set \type {texconfig.kpse_init} to \type {false} for that), \LUATEX\
281acts on some more command line options after the initialization script is
282finished: in order to initialize the built|-|in \KPATHSEA\ library properly,
283\LUATEX\ needs to know the correct program name to use, and for that it needs to
284check \type {--progname}, or \type {--ini} and \type {--fmt}, if \type
285{--progname} is missing.
286
287From version 1.17.1, in \DVI\ mode the new commandline switch \type {--check-dvi-total-pages},
288enabled by default, checks  that the total number of pages does not exceeds 65535,
289and in case the run abort. This breaks the compatibility with \PDFTEX\ where, as in \TEX,
290when the total number of pages is greater than 65535 the file will lie. The previous behaviour
291can be restored with \type {--[no-]check-dvi-total-pages}.
292
293\stopsubsection
294
295\stopsection
296
297\startsection[title={\LUA\ behaviour}]
298
299\startsubsection[title={The \LUA\ version}]
300
301\topicindex {\LUA+libraries}
302\topicindex {\LUA+extensions}
303
304We currently use \LUA\ 5.3 and will follow developments of the language but
305normally with some delay. Therefore the user needs to keep an eye on (subtle)
306differences in successive versions of the language. Also, \LUAJITTEX\ lags behind
307in the sense that \LUAJIT\ is not in sync with regular \LUA\ development. Here is
308an example of one aspect.
309
310\LUA s \type {tostring} function (and \type {string.format} may return values in
311scientific notation, thereby confusing the \TEX\ end of things when it is used as
312the right|-|hand side of an assignment to a \prm {dimen} or \prm {count}. The
313output of these serializers also depend on the \LUA\ version, so in \LUA\ 5.3 you
314can get different output than from 5.2.
315
316\stopsubsection
317
318\startsubsection[title={Integration in the \TDS\ ecosystem}]
319
320The main \TEX\ distributions follow the \TEX\ directory structure (\TDS).
321\LUATEX\ is able to use the kpathsea library to find \type {require()}d modules.
322For this purpose, \type {package.searchers[2]} is replaced by a different loader
323function, that decides at runtime whether to use kpathsea or the built|-|in core
324\LUA\ function. It uses \KPATHSEA\ when that is already initialized at that point
325in time, otherwise it reverts to using the normal \type {package.path} loader.
326
327Initialization of \KPATHSEA\ can happen either implicitly (when \LUATEX\ starts
328up and the startup script has not set \type {texconfig.kpse_init} to false), or
329explicitly by calling the \LUA\ function \type {kpse.set_program_name()}.
330
331\stopsubsection
332
333\startsubsection[title={Loading libraries}]
334
335\LUATEX\ is able to use dynamically loadable \LUA\ libraries, unless
336\type {--safer} was given as an option on the command line. For this purpose,
337\type {package.searchers[3]} is replaced by a different loader function, that
338decides at runtime whether to use \KPATHSEA\ or the built|-|in core \LUA\
339function. It uses \KPATHSEA\ when that is already initialized at that point in
340time, otherwise it reverts to using the normal \type {package.cpath} loader.
341
342This functionality required an extension to kpathsea. There is a new kpathsea
343file format: \type {kpse_clua_format} that searches for files with extension
344\type {.dll} and \type {.so}. The \type {texmf.cnf} setting for this variable is
345\type {CLUAINPUTS}, and by default it has this value:
346
347\starttyping
348CLUAINPUTS=.:$SELFAUTOLOC/lib/{$progname,$engine,}/lua//
349\stoptyping
350
351This path is imperfect (it requires a \TDS\ subtree below the binaries
352directory), but the architecture has to be in the path somewhere, and the
353currently simplest way to do that is to search below the binaries directory only.
354Of course it no big deal to write an alternative loader and use that in a macro
355package. One level up (a \type {lib} directory parallel to \type {bin}) would
356have been nicer, but that is not doable because \TEXLIVE\ uses a \type
357{bin/<arch>} structure.
358
359Loading dynamic \LUA\ libraries will fail if there are two \LUA\ libraries loaded
360at the same time (which will typically happen on \type {win32}, because there is
361one \LUA\ 5.3 inside \LUATEX, and another will likely be linked to the \DLL\ file
362of the module itself).
363
364\stopsubsection
365
366\startsubsection[title={Executing programs}]
367
368In keeping with the other \TEX|-|like programs in \TEXLIVE, the \LUA\ functions
369\type {os.execute}, \type{os.kpsepopen} and \type {io.popen}, as well as the two new functions \type
370{os.exec} and \type {os.spawn} that are explained below, take the value of \type
371{shell_escape} and|/|or \type {shell_escape_commands} in account. Whenever
372\LUATEX\ is run with the assumed intention to typeset a document (and by that we
373mean that it is called as \type {luatex}, as opposed to \type {texlua}, and that
374the command line option \type {--luaonly} was not given), it will only run the
375four functions above if the matching \type {texmf.cnf} variable(s) or their \type
376{texconfig} (see \in {section} [texconfig]) counterparts allow execution of the
377requested system command. In \quote {script interpreter} runs of \LUATEX, these
378settings have no effect, and all four functions have their original meaning.
379
380Some libraries have a few more functions, either coded in \CCODE\ or in \LUA. For
381instance, when we started with \LUATEX\ we added some helpers to the \type
382{luafilesystem} namespace \type {lfs}. The two boolean functions \type
383{lfs.isdir} and \type {lfs.isfile} were speedy and better variants of what could
384be done with \type {lfs.attributes}. The additional function \type
385{lfs.shortname} takes a file name and returns its short name on \type {win32}
386platforms; \type{lfs.mkdirp} is like \type{lfs.mkdir} but make parent directories
387as needed (it is a \LUA\ wrapper function). Finally, for non|-|\type {win32}
388platforms only, we provided \type {lfs.readlink} that takes an existing symbolic
389link as argument and returns its name. However, the \type {lfs} library evolved so
390we have dropped these in favour of pure \LUA\ variants. The \type {shortname}
391helper is obsolete and now just returns the name.
392
393\stopsubsection
394
395\startsubsection[title={Multibyte \type {string} functions}]
396
397The \type {string} library has a few extra functions, for example \libidx
398{string} {explode}. This function takes upto two arguments: \type
399{string.explode(s[,m])} and returns an array containing the string argument \type
400{s} split into sub-strings based on the value of the string argument \type {m}.
401The second argument is a string that is either empty (this splits the string into
402characters), a single character (this splits on each occurrence of that
403character, possibly introducing empty strings), or a single character followed by
404the plus sign \type {+} (this special version does not create empty sub-strings).
405The default value for \type {m} is \quote {\type { +}} (multiple spaces). Note:
406\type {m} is not hidden by surrounding braces as it would be if this function was
407written in \TEX\ macros.
408
409The \type {string} library also has six extra iterators that return strings
410piecemeal: \libidx {string} {utfvalues}, \libidx {string} {utfcharacters},
411\libidx {string} {characters}, \libidx {string} {characterpairs}, \libidx
412{string} {bytes} and \libidx {string} {bytepairs}.
413
414\startitemize
415\startitem
416    \type {string.utfvalues(s)}: an integer value in the \UNICODE\ range
417\stopitem
418\startitem
419    \type {string.utfcharacters(s)}: a string with a single \UTF-8 token in it
420\stopitem
421\startitem
422    \type {string.characters(s)}: a string containing one byte
423\stopitem
424\startitem
425    \type {string.characterpairs(s)}: two strings each containing one byte or an
426    empty second string if the string length was odd
427\stopitem
428\startitem
429    \type {string.bytes(s)}: a single byte value
430\stopitem
431\startitem
432    \type {string.bytepairs(s)}: two byte values or nil instead of a number as
433    its second return value if the string length was odd
434\stopitem
435\stopitemize
436
437The \type {string.characterpairs()} and \type {string.bytepairs()} iterators
438are useful especially in the conversion of \UTF16 encoded data into \UTF8.
439
440There is also a two|-|argument form of \type {string.dump()}. The second argument
441is a boolean which, if true, strips the symbols from the dumped data. This
442matches an extension made in \type {luajit}. This is typically a function that
443gets adapted as \LUA\ itself progresses.
444
445The \type {string} library functions \type {len}, \type {lower}, \type {sub}
446etc.\ are not \UNICODE|-|aware. For strings in the \UTF8 encoding, i.e., strings
447containing characters above code point 127, the corresponding functions from the
448\type {slnunicode} library can be used, e.g., \type {unicode.utf8.len}, \type
449{unicode.utf8.lower} etc.\ The exceptions are \type {unicode.utf8.find}, that
450always returns byte positions in a string, and \type {unicode.utf8.match} and
451\type {unicode.utf8.gmatch}. While the latter two functions in general {\it
452are} \UNICODE|-|aware, they fall|-|back to non|-|\UNICODE|-|aware behavior when
453using the empty capture \type {()} but other captures work as expected. For the
454interpretation of character classes in \type {unicode.utf8} functions refer to
455the library sources at \hyphenatedurl {http://luaforge.net/projects/sln}.
456
457Version 5.3 of \LUA\ provides some native \UTF8 support but we have added a few
458similar helpers too: \libidx {string} {utfvalue}, \libidx {string} {utfcharacter}
459and \libidx {string} {utflength}.
460
461\startitemize
462\startitem
463    \type {string.utfvalue(s)}: returns the codepoints of the characters in the
464    given string
465\stopitem
466\startitem
467    \type {string.utfcharacter(c,...)}: returns a string with the characters of
468    the given code points
469\stopitem
470\startitem
471    \type {string.utflength(s)}: returns the length of the given string
472\stopitem
473\stopitemize
474
475These three functions are relative fast and don't do much checking. They can be
476used as building blocks for other helpers.
477
478\stopsubsection
479
480\startsubsection[title={Extra \type {os} library functions}]
481
482The \type {os} library has a few extra functions and
483variables: \libidx {os} {selfdir}, \libidx {os} {exec},
484\libidx {os} {kpsepopen},
485\libidx {os} {socketgettime}, \libidx {os} {socketsleep},
486\libidx {os} {spawn}, \libidx {os} {setenv},
487\libidx {os} {env}, \libidx {os} {gettimeofday}, \libidx {os} {times},
488\libidx {os} {sleep}, \libidx {os} {tmpdir}, \libidx {os} {type},
489\libidx {os} {name} and \libidx {os} {uname},{os} {uname},
490that we will discuss here.
491
492\startitemize
493
494\startitem
495    \type {os.selfdir} is a variable that holds the directory path of the
496    actual executable. For example: \type {\directlua {tex.sprint(os.selfdir)}}.
497\stopitem
498
499\startitem
500    \type {os.exec(commandline)} is a variation on \type {os.execute}. Here
501    \type {commandline} can be either a single string or a single table.
502
503    \startitemize
504
505    \startitem
506        If the argument is a table \LUATEX\ first checks if there is a value at
507        integer index zero. If there is, this is the command to be executed.
508        Otherwise, it will use the value at integer index one. If neither are
509        present, nothing at all happens.
510    \stopitem
511
512    \startitem
513        The set of consecutive values starting at integer~1 in the table are the
514        arguments that are passed on to the command (the value at index~1 becomes
515        \type {arg[0]}). The command is searched for in the execution path, so
516        there is normally no need to pass on a fully qualified path name.
517    \stopitem
518
519    \startitem
520        If the argument is a string, then it is automatically converted into a
521        table by splitting on whitespace. In this case, it is impossible for the
522        command and first argument to differ from each other.
523    \stopitem
524
525    \startitem
526        In the string argument format, whitespace can be protected by putting
527        (part of) an argument inside single or double quotes. One layer of quotes
528        is interpreted by \LUATEX, and all occurrences of \type {\"}, \type {\'}
529        or \type {\\} within the quoted text are unescaped. In the table format,
530        there is no string handling taking place.
531    \stopitem
532
533    \stopitemize
534
535    This function normally does not return control back to the \LUA\ script: the
536    command will replace the current process. However, it will return the two
537    values \type {nil} and \type {error} if there was a problem while
538    attempting to execute the command.
539
540    On \MSWINDOWS, the current process is actually kept in memory until after the
541    execution of the command has finished. This prevents crashes in situations
542    where \TEXLUA\ scripts are run inside integrated \TEX\ environments.
543
544    The original reason for this command is that it cleans out the current
545    process before starting the new one, making it especially useful for use in
546    \TEXLUA.
547\stopitem
548
549\startitem
550    \type {os.kpsepopen(commandline,[opt])} is similar to \type {io.popen}
551    but with a preliminary check of the  commandline;
552    if the check is ok then the return value is the same as in \type{io.popen};
553    Otherwise it will return the two values \type {nil} and \type {error}.
554\stopitem
555
556\startitem
557    \type {os.socketgettime} and \type {os.socketsleep} are the same as for
558    \type{socket.gettime} and \type{socket.sleep} but they are always available.
559\stopitem
560
561\startitem
562    \type {os.spawn(commandline)} is a returning version of \type {os.exec},
563    with otherwise identical calling conventions.
564
565    If the command ran ok, then the return value is the exit status of the
566    command. Otherwise, it will return the two values \type {nil} and \type
567    {error}.
568
569    The \type {os.spawn()} function takes an optional second argument, a table of
570    key-value pairs for the environment of the spawned process. Note that if you
571    do pass this table, it will be used as the \notabene {complete} environment
572    for the spawned process, so you'll likely want to start from \type {os.env}
573    and add or remove keys as needed.
574\stopitem
575
576\startitem
577    \type {os.setenv(key,value)} sets a variable in the environment. Passing
578    \type {nil} instead of a value string will remove the variable.
579\stopitem
580
581\startitem
582    \type {os.env} is a hash table containing a dump of the variables and
583    values in the process environment at the start of the run. It is writeable,
584    but the actual environment is \notabene {not} updated automatically.
585\stopitem
586
587\startitem
588    \type {os.gettimeofday()} returns the current \quote {\UNIX\ time}, but as a
589    float. This function is not available on the \SUNOS\ platforms, so do not use
590    this function for portable documents.
591\stopitem
592
593\startitem
594    \type {os.times()}returns the current process times according to the
595    \UNIX\ C library function \quote {times}. This function is not available on
596    the \MSWINDOWS\ and \SUNOS\ platforms, so do not use this function for
597    portable documents.
598\stopitem
599
600\startitem
601    \type {os.sleep(interval[, unit])} suspends the execution of the current run for
602    a given number of seconds. If the optional argument \type {unit} is present, the
603    function waits \type {interval / units} seconds. \type {os.sleep(1, 1000)}
604    for example pauses the program for one millisecond.
605\stopitem
606
607\startitem
608    \type {os.tmpdir([template])} creates a directory in the \quote {current directory}
609    with the name \type {luatex.XXXXXX} where the \type {X}-es are replaced by a
610    unique string. The function also returns this string, so you can \type
611    {lfs.chdir()} into it, or \type {nil} if it failed to create the directory.
612    The user is responsible for cleaning up at the end of the run, it does not
613    happen automatically. You can also use your own \type {template} for the name
614    of the temporary folder. However, the passed string must end with six capital
615    \type {X}-es. For example, the template \type {tmp.XXXXXX} could result in the
616    folder name \type {tmp.vX3gPo}.
617\stopitem
618
619\startitem
620    \type {os.type} is a string that gives a global indication of the class of
621    operating system. The possible values are currently \type {windows}, \type
622    {unix}, and \type {msdos} (you are unlikely to find this value \quote {in the
623    wild}).
624\stopitem
625
626\startitem
627    \type {os.name} is a string that gives a more precise indication of the
628    operating system. These possible values are not yet fixed, and for \type
629    {os.type} values \type {windows} and \type {msdos}, the \type {os.name}
630    values are simply \type {windows} and \type {msdos}
631
632    The list for the type \type {unix} is more precise: \type {linux}, \type
633    {freebsd}, \type {kfreebsd}, \type {cygwin}, \type {openbsd}, \type
634    {solaris}, \type {sunos} (pre-solaris), \type {hpux}, \type {irix}, \type
635    {macosx}, \type {gnu} (hurd), \type {bsd} (unknown, but \BSD|-|like), \type
636    {sysv} (unknown, but \SYSV|-|like), \type {generic} (unknown).
637\stopitem
638
639\startitem
640    \type {os.uname} returns a table with specific operating system
641    information acquired at runtime. The keys in the returned table are all
642    string values, and their names are: \type {sysname}, \type {machine}, \type
643    {release}, \type {version}, and \type {nodename}.
644\stopitem
645
646\stopitemize
647
648\stopsubsection
649
650\startsubsection[title={Binary input from files with \type {fio}}]
651
652There is a whole set of helpers for reading numbers and strings from a file:
653\libidx {fio} {readcardinal1}, \libidx {fio} {readcardinal2}, \libidx {fio}
654{readcardinal3}, \libidx {fio} {readcardinal4}, \libidx {fio}
655{readcardinaltable}, \libidx {fio} {readinteger1}, \libidx {fio} {readinteger2},
656\libidx {fio} {readinteger3}, \libidx {fio} {readinteger4}, \libidx {fio}
657{readintegertable}, \libidx {fio} {readfixed2}, \libidx {fio} {readfixed4},
658\libidx {fio} {read2dot14}, \libidx {fio} {setposition}, \libidx {fio}
659{getposition}, \libidx {fio} {skipposition}, \libidx {fio} {readbytes}, \libidx
660{fio} {readbytetable}. They work on normal \LUA\ file handles.
661
662%libidx{fio}{readline}
663%libidx{fio}{recordfilename}
664%libidx{fio}{checkpermission}
665
666This library provides a set of functions for reading numbers from a file and
667in addition to the regular \type {io} library functions.
668
669\starttabulate
670\NC \type{readcardinal1(f)}         \NC a 1 byte unsigned integer \NC \NR
671\NC \type{readcardinal2(f)}         \NC a 2 byte unsigned integer \NC \NR
672\NC \type{readcardinal3(f)}         \NC a 3 byte unsigned integer \NC \NR
673\NC \type{readcardinal4(f)}         \NC a 4 byte unsigned integer \NC \NR
674\NC \type{readcardinaltable(f,n,b)} \NC \type {n} cardinals of \type {b} bytes \NC \NR
675\NC \type{readinteger1(f)}          \NC a 1 byte signed integer \NC \NR
676\NC \type{readinteger2(f)}          \NC a 2 byte signed integer \NC \NR
677\NC \type{readinteger3(f)}          \NC a 3 byte signed integer \NC \NR
678\NC \type{readinteger4(f)}          \NC a 4 byte signed integer \NC \NR
679\NC \type{readintegertable(f,n,b)}  \NC \type {n} integers of \type {b} bytes \NC \NR
680\NC \type{readfixed2(f)}            \NC a 2 byte float (used in font files) \NC \NR
681\NC \type{readfixed4(f)}            \NC a 4 byte float (used in font files) \NC \NR
682\NC \type{read2dot14(f)}            \NC a 2 byte float (used in font files) \NC \NR
683\NC \type{setposition(f,p)}         \NC goto position \type {p} \NC \NR
684\NC \type{getposition(f)}           \NC get the current position \NC \NR
685\NC \type{skipposition(f,n)}        \NC skip \type {n} positions \NC \NR
686\NC \type{readbytes(f,n)}           \NC \type {n} bytes \NC \NR
687\NC \type{readbytetable(f,n)}       \NC \type {n} bytes\NC \NR
688\stoptabulate
689
690There are eight additional little endian variants for the \type {cardinal[1-4]}
691and \type {integer[1-4]} readers: \type {cardinal[1-4]le} and \type
692{integer[1-4]le}.
693
694\stopsubsection
695
696\startsubsection[title={Binary input from strings with \type {sio}}]
697
698A similar set of function as in the \type {fio} library is available in the \type
699{sio} library: \libidx {sio} {readcardinal1}, \libidx {sio} {readcardinal2},
700\libidx {sio} {readcardinal3}, \libidx {sio} {readcardinal4}, \libidx {sio}
701{readcardinaltable}, \libidx {sio} {readinteger1}, \libidx {sio} {readinteger2},
702\libidx {sio} {readinteger3}, \libidx {sio} {readinteger4}, \libidx {sio}
703{readintegertable}, \libidx {sio} {readfixed2}, \libidx {sio} {readfixed4},
704\libidx {sio} {read2dot14}, \libidx {sio} {setposition}, \libidx {sio}
705{getposition}, \libidx {sio} {skipposition}, \libidx {sio} {readbytes} and
706\libidx {sio} {readbytetable}. Here the first argument is a string instead of a
707file handle. More details can be found in the previous section.
708
709\stopsubsection
710
711\startsubsection[title={Hashes conform \type {sha2}}]
712
713This library is a side effect of the \type {pdfe} library that needs such
714helpers. The \libidx{sha2}{digest256}, \libidx{sha2}{digest384} and
715\libidx{sha2}{digest512} functions accept a string and return a string with the
716hash.
717
718\stopsubsection
719
720\startsubsection[title={Locales}]
721
722\index {locales}
723
724In stock \LUA, many things depend on the current locale. In \LUATEX, we can't do
725that, because it makes documents unportable.  While \LUATEX\ is running if
726forces the following locale settings:
727
728\starttyping
729LC_CTYPE=C
730LC_COLLATE=C
731LC_NUMERIC=C
732\stoptyping
733
734\stopsubsection
735
736\stopsection
737
738\startsection[title={\LUA\ modules}]
739
740\topicindex {\LUA+libraries}
741\topicindex {\LUA+modules}
742
743Some modules that are normally external to \LUA\ are statically linked in with
744\LUATEX, because they offer useful functionality:
745
746\startitemize
747
748\startitem
749    \type {lpeg}, by Roberto Ierusalimschy, \hyphenatedurl
750    {http://www.inf.puc-rio.br/~roberto/lpeg/lpeg.html}. This library is not
751    \UNICODE|-|aware, but interprets strings on a byte|-|per|-|byte basis. This
752    mainly means that \type {lpeg.S} cannot be used with \UTF8 characters encoded
753    in more than two bytes, and thus \type {lpeg.S} will look for one of those
754    two bytes when matching, not the combination of the two. The same is true for
755    \type {lpeg.R}, although the latter will display an error message if used
756    with multibyte characters. Therefore \type {lpeg.R('aä')} results in the
757    message \type {bad argument #1 to 'R' (range must have two characters)},
758    since to \type {lpeg}, \type {ä} is two 'characters' (bytes), so \type {aä}
759    totals three. In practice this is no real issue and with some care you can
760    deal with \UNICODE\ just fine.
761\stopitem
762
763\startitem
764    \type {slnunicode}, from the \type {selene} libraries, \hyphenatedurl
765    {http://luaforge.net/projects/sln}. This library has been slightly extended
766    so that the \type {unicode.utf8.*} functions also accept the first 256 values
767    of plane~18. This is the range \LUATEX\ uses for raw binary output, as
768    explained above. We have no plans to provide more like this because you can
769    basically do all that you want in \LUA.
770\stopitem
771
772\startitem
773    \type {luazip}, from the kepler project, \hyphenatedurl
774    {http://www.keplerproject.org/luazip/}.
775\stopitem
776
777\startitem
778    \type {luafilesystem}, also from the kepler project, \hyphenatedurl
779    {http://www.keplerproject.org/luafilesystem/}.
780\stopitem
781
782\startitem
783    \type {lzlib}, by Tiago Dionizio, \hyphenatedurl
784    {http://luaforge.net/projects/lzlib/}.
785\stopitem
786
787\startitem
788    \type {md5}, by Roberto Ierusalimschy \hyphenatedurl
789    {http://www.inf.puc-rio.br/~roberto/md5/md5-5/md5.html}.
790\stopitem
791
792\startitem
793    \type {luasocket}, by Diego Nehab \hyphenatedurl
794    {http://w3.impa.br/~diego/software/luasocket/}. The \type {.lua} support
795    modules from \type {luasocket} are also preloaded inside the executable,
796    there are no external file dependencies.
797\stopitem
798
799\stopitemize
800
801\stopsection
802
803\startsection[title={Testing}]
804
805\topicindex {testing}
806\topicindex {\PDF+date}
807
808For development reasons you can influence the used startup date and time. This can
809be done in two ways.
810
811\startitemize[n]
812
813\startitem
814    By setting the environmment variable \type {SOURCE_DATE_EPOCH}. This will
815    influence the \TEX\ parameters \type {time} and \type {date}, the random seed,
816    the \PDF\ timestamp and the \PDF\ id that is derived from the time as well. This
817    variable is consulted when the \KPSE\ library is enabled. Resolving is
818    delegated to this library.
819\stopitem
820
821\startitem
822    By setting the \type {start_time} variable in the \type {texconfig} table; as
823    with other variables we use the internal name there. For compatibility
824    reasons we also honour a \type {SOURCE_DATE_EPOCH} entry. It should be noted
825    that there are no such variables in other engines and this method is only
826    relevant in case the while setup happens in \LUA.
827\stopitem
828
829\stopitemize
830
831When Universal Time is needed, you can pass the flag \type {utc} to the engine. This
832property also works when the date and time are set by \LUATEX\ itself. It has a
833complementary entry \type {use_utc_time} in the \type {texconfig} table.
834
835There is some control possible, for instance prevent filename to be written to
836the \PDF\ file. This is discussed elsewhere. In \CONTEXT\ we provide the command
837line argument \type {--nodates} that does a bit more disabling of dates.
838
839\stopsection
840
841\stopchapter
842
843\stopcomponent
844