Debian Codegraph @

texmf-dist/doc/luatex/base/luatex-lua.tex

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