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