summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/luatex/base/luatex-lua.tex
blob: f9107fa1f960ae654df469bb195986c9c2cff617 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
% language=uk

\environment luatex-style

\startcomponent luatex-lua

\startchapter[reference=lua,title={Using \LUATEX}]

\startsection[title={Initialization},reference=init]

\startsubsection[title={\LUATEX\ as a \LUA\ interpreter}]

\topicindex {initialization}
\topicindex {\LUA+interpreter}

There are some situations that make \LUATEX\ behave like a standalone \LUA\
interpreter:

\startitemize[packed]
\startitem
    if a \type {--luaonly} option is given on the commandline, or
\stopitem
\startitem
    if the executable is named \type {texlua} or \type {luatexlua}, or
\stopitem
\startitem
    if the only non|-|option argument (file) on the commandline has the extension
    \type {lua} or \type {luc}.
\stopitem
\stopitemize

In this mode, it will set \LUA's \type {arg[0]} to the found script name, pushing
preceding options in negative values and the rest of the command line in the
positive values, just like the \LUA\ interpreter.

\LUATEX\ will exit immediately after executing the specified \LUA\ script and is,
in effect, a somewhat bulky stand alone \LUA\ interpreter with a bunch of extra
preloaded libraries.

\stopsubsection

\startsubsection[title={\LUATEX\ as a \LUA\ byte compiler}]

\topicindex {\LUA+byte code}

There are two situations that make \LUATEX\ behave like the \LUA\ byte compiler:

\startitemize[packed]
\startitem if a \type {--luaconly} option is given on the command line, or \stopitem
\startitem if the executable is named \type {texluac} \stopitem
\stopitemize

In this mode, \LUATEX\ is exactly like \type {luac} from the stand alone \LUA\
distribution, except that it does not have the \type {-l} switch, and that it
accepts (but ignores) the \type {--luaconly} switch. The current version of \LUA\
can dump bytecode using \type {string.dump} so we might decide to drop this
version of \LUATEX.

\stopsubsection

\startsubsection[title={Other commandline processing}]

\topicindex {command line}

When the \LUATEX\ executable starts, it looks for the \type {--lua} command line
option. If there is no \type {--lua} option, the command line is interpreted in a
similar fashion as the other \TEX\ engines. Some options are accepted but have no
consequence. The following command|-|line options are understood:

\starttabulate[|l|p|]
\DB commandline argument                \BC explanation \NC \NR
\TB
\NC \type{--credits}                    \NC display credits and exit \NC \NR
\NC \type{--debug-format}               \NC enable format debugging \NC \NR
\NC \type{--draftmode}                  \NC switch on draft mode i.e.\ generate no output in \PDF\ mode \NC \NR
\NC \type{--[no-]file-line-error}       \NC disable/enable \type {file:line:error} style messages \NC \NR
\NC \type{--[no-]file-line-error-style} \NC aliases of \type {--[no-]file-line-error} \NC \NR
\NC \type{--fmt=FORMAT}                 \NC load the format file \type {FORMAT} \NC\NR
\NC \type{--halt-on-error}              \NC stop processing at the first error\NC \NR
\NC \type{--help}                       \NC display help and exit \NC\NR
\NC \type{--ini}                        \NC be \type {iniluatex}, for dumping formats \NC\NR
\NC \type{--interaction=STRING}         \NC set interaction mode: \type {batchmode}, \type {nonstopmode},
                                            \type {scrollmode} or \type {errorstopmode} \NC \NR
\NC \type{--jobname=STRING}             \NC set the job name to \type {STRING} \NC \NR
\NC \type{--kpathsea-debug=NUMBER}      \NC set path searching debugging flags according to the bits of
                                           \type {NUMBER} \NC \NR
\NC \type{--lua=FILE}                   \NC load and execute a \LUA\ initialization script \NC\NR
\NC \type{--[no-]mktex=FMT}             \NC disable/enable \type {mktexFMT} generation with \type {FMT} is
                                            \type {tex} or \type {tfm} \NC \NR
\NC \type{--nosocket}                   \NC disable the \LUA\ socket library \NC\NR
\NC \type{--output-comment=STRING}      \NC use \type {STRING} for \DVI\ file comment instead of date (no
                                            effect for \PDF) \NC \NR
\NC \type{--output-directory=DIR}       \NC use \type {DIR} as the directory to write files to \NC \NR
\NC \type{--output-format=FORMAT}       \NC use \type {FORMAT} for job output; \type {FORMAT} is \type {dvi}
                                            or \type {pdf} \NC \NR
\NC \type{--progname=STRING}            \NC set the program name to \type {STRING} \NC \NR
\NC \type{--recorder}                   \NC enable filename recorder \NC \NR
\NC \type{--safer}                      \NC disable easily exploitable \LUA\ commands \NC\NR
\NC \type{--[no-]shell-escape}          \NC disable/enable system calls \NC \NR
\NC \type{--shell-restricted}           \NC restrict system calls to a list of commands given in \type
                                            {texmf.cnf} \NC \NR
\NC \type{--synctex=NUMBER}             \NC enable \type {synctex} \NC \NR
\NC \type{--utc}                        \NC use utc times when applicable \NC \NR
\NC \type{--version}                    \NC display version and exit \NC \NR
\LL
\stoptabulate

We don't support \prm {write} 18 because \type {os.execute} can do the same. It
simplifies the code and makes more write targets possible.

The value to use for \prm {jobname} is decided as follows:

\startitemize
\startitem
    If \type {--jobname} is given on the command line, its argument will be the
    value for \prm {jobname}, without any changes. The argument will not be
    used for actual input so it need not exist. The \type {--jobname} switch only
    controls the \prm {jobname} setting.
\stopitem
\startitem
    Otherwise, \prm {jobname} will be the name of the first file that is read
    from the file system, with any path components and the last extension (the
    part following the last \type {.}) stripped off.
\stopitem
\startitem
    There is an exception to the previous point: if the command line goes into
    interactive mode (by starting with a command) and there are no files input
    via \prm {everyjob} either, then the \prm {jobname} is set to \type
    {texput} as a last resort.
\stopitem
\stopitemize

The file names for output files that are generated automatically are created by
attaching the proper extension (\type {log}, \type {pdf}, etc.) to the found
\prm {jobname}. These files are created in the directory pointed to by \type
{--output-directory}, or in the current directory, if that switch is not present.

Without the \type {--lua} option, command line processing works like it does in
any other \WEBC|-|based typesetting engine, except that \LUATEX\ has a few extra
switches and lacks some others. Also, if the \type {--lua} option is present,
\LUATEX\ will enter an alternative mode of command line processing in comparison
to the standard \WEBC\ programs. In this mode, a small series of actions is taken
in the following order:

\startitemize[n]

\startitem
    First, it will parse the command line as usual, but it will only interpret a
    small subset of the options immediately: \type {--safer}, \type {--nosocket},
    \type {--[no-]shell-escape}, \type {--enable-write18}, \type
    {--disable-write18}, \type {--shell-restricted}, \type {--help}, \type
    {--version}, and \type {--credits}.
\stopitem

\startitem
    Next \LUATEX\ searches for the requested \LUA\ initialization script. If it
    cannot be found using the actual name given on the command line, a second
    attempt is made by prepending the value of the environment variable \type
    {LUATEXDIR}, if that variable is defined in the environment.
\stopitem

\startitem
    Then it checks the various safety switches. You can use those to disable some
    \LUA\ commands that can easily be abused by a malicious document. At the
    moment, \type {--safer} \type {nil}s the following functions:

    \blank

    \starttabulate[|c|l|]
        \DB library     \BC functions \NC \NR
        \TB
        \NC \type {os}  \NC \type {execute} \type {exec} \type {spawn} \type {setenv}
                            \type {rename} \type {remove} \type {tmpdir} \NC \NR
        \NC \type {io}  \NC \type {popen} \type {output} \type {tmpfile} \NC \NR
        \NC \type {lfs} \NC \type {rmdir} \type {mkdir} \type {chdir} \type {lock}
                            \type {touch} \NC \NR
        \LL
    \stoptabulate

    \blank

    Furthermore, it disables loading of compiled \LUA\ libraries and it makes
    \type {io.open()} fail on files that are opened for anything besides reading.
\stopitem

\startitem
    When \LUATEX\ starts it sets the \type {locale} to a neutral value. If for
    some reason you use \type {os.locale}, you need to make sure you \type {nil}
    it afterwards because otherwise it can interfere with code that for instance
    generates dates. You can ignore the \type {locale} with:

    \starttyping
    os.setlocale(nil,nil)
    \stoptyping

    The \type {--nosocket} option makes the socket library unavailable, so that \LUA\
    cannot use networking.

    The switches \type {--[no-]shell-escape}, \type {--[enable|disable]-write18}, and
    \type {--shell-restricted} have the same effects as in \PDFTEX, and additionally
    make \type {io.popen()}, \type {os.execute}, \type {os.exec} and \type {os.spawn}
    adhere to the requested option.
\stopitem

\startitem
    Next the initialization script is loaded and executed. From within the
    script, the entire command line is available in the \LUA\ table \type {arg},
    beginning with \type {arg[0]}, containing the name of the executable. As
    consequence warnings about unrecognized options are suppressed.
\stopitem

\stopitemize

Command line processing happens very early on. So early, in fact, that none of
\TEX's initializations have taken place yet. For that reason, the tables that
deal with typesetting, like \type {tex}, \type {token}, \type {node} and
\type {pdf}, are off|-|limits during the execution of the startup file (they
are \type {nil}'d). Special care is taken that \type {texio.write} and \type
{texio.write_nl} function properly, so that you can at least report your actions
to the log file when (and if) it eventually becomes opened (note that \TEX\ does
not even know its \prm {jobname} yet at this point).

Everything you do in the \LUA\ initialization script will remain visible during
the rest of the run, with the exception of the \TEX\ specific libraries like
\type {tex}, \type {token}, \type {node} and \type {pdf} tables. These will be
initialized to their documented state after the execution of the script. You
should not store anything in variables or within tables with these four global
names, as they will be overwritten completely.

We recommend you use the startup file only for your own \TEX|-|independent
initializations (if you need any), to parse the command line, set values in the
\type {texconfig} table, and register the callbacks you need.

\LUATEX\ allows some of the command line options to be overridden by reading
values from the \type {texconfig} table at the end of script execution (see the
description of the \type {texconfig} table later on in this document for more
details on which ones exactly).

Unless the \type {texconfig} table tells \LUATEX\ not to initialize \KPATHSEA\
at all (set \type {texconfig.kpse_init} to \type {false} for that), \LUATEX\
acts on some more command line options after the initialization script is
finished: in order to initialize the built|-|in \KPATHSEA\ library properly,
\LUATEX\ needs to know the correct program name to use, and for that it needs to
check \type {--progname}, or \type {--ini} and \type {--fmt}, if \type
{--progname} is missing.

\stopsubsection

\stopsection

\startsection[title={\LUA\ behaviour}]

\startsubsection[title={The \LUA\ version}]

\topicindex {\LUA+libraries}
\topicindex {\LUA+extensions}

We currently use \LUA\ 5.3 and will follow developments of the language but
normally with some delay. Therefore the user needs to keep an eye on (subtle)
differences in successive versions of the language. Also, \LUAJITTEX\ lags behind
in the sense that \LUAJIT\ is not in sync with regular \LUA\ development. Here is
an example of one aspect.

\LUA s \type {tostring} function (and \type {string.format} may return values in
scientific notation, thereby confusing the \TEX\ end of things when it is used as
the right|-|hand side of an assignment to a \prm {dimen} or \prm {count}. The
output of these serializers also depend on the \LUA\ version, so in \LUA\ 5.3 you
can get different output than from 5.2.

\stopsubsection

\startsubsection[title={Integration in the \TDS\ ecosystem}]

The main \TEX\ distributions follow the \TEX\ directory structure (\TDS).
\LUATEX\ is able to use the kpathsea library to find \type {require()}d modules.
For this purpose, \type {package.searchers[2]} is replaced by a different loader
function, that decides at runtime whether to use kpathsea or the built|-|in core
\LUA\ function. It uses \KPATHSEA\ when that is already initialized at that point
in time, otherwise it reverts to using the normal \type {package.path} loader.

Initialization of \KPATHSEA\ can happen either implicitly (when \LUATEX\ starts
up and the startup script has not set \type {texconfig.kpse_init} to false), or
explicitly by calling the \LUA\ function \type {kpse.set_program_name()}.

\stopsubsection

\startsubsection[title={Loading libraries}]

\LUATEX\ is able to use dynamically loadable \LUA\ libraries, unless
\type {--safer} was given as an option on the command line. For this purpose,
\type {package.searchers[3]} is replaced by a different loader function, that
decides at runtime whether to use \KPATHSEA\ or the built|-|in core \LUA\
function. It uses \KPATHSEA\ when that is already initialized at that point in
time, otherwise it reverts to using the normal \type {package.cpath} loader.

This functionality required an extension to kpathsea. There is a new kpathsea
file format: \type {kpse_clua_format} that searches for files with extension
\type {.dll} and \type {.so}. The \type {texmf.cnf} setting for this variable is
\type {CLUAINPUTS}, and by default it has this value:

\starttyping
CLUAINPUTS=.:$SELFAUTOLOC/lib/{$progname,$engine,}/lua//
\stoptyping

This path is imperfect (it requires a \TDS\ subtree below the binaries
directory), but the architecture has to be in the path somewhere, and the
currently simplest way to do that is to search below the binaries directory only.
Of course it no big deal to write an alternative loader and use that in a macro
package. One level up (a \type {lib} directory parallel to \type {bin}) would
have been nicer, but that is not doable because \TEXLIVE\ uses a \type
{bin/<arch>} structure.

Loading dynamic \LUA\ libraries will fail if there are two \LUA\ libraries loaded
at the same time (which will typically happen on \type {win32}, because there is
one \LUA\ 5.3 inside \LUATEX, and another will likely be linked to the \DLL\ file
of the module itself).

\stopsubsection

\startsubsection[title={Executing programs}]

In keeping with the other \TEX|-|like programs in \TEXLIVE, the two \LUA\ functions
\type {os.execute} and \type {io.popen}, as well as the two new functions \type
{os.exec} and \type {os.spawn} that are explained below, take the value of \type
{shell_escape} and|/|or \type {shell_escape_commands} in account. Whenever
\LUATEX\ is run with the assumed intention to typeset a document (and by that we
mean that it is called as \type {luatex}, as opposed to \type {texlua}, and that
the command line option \type {--luaonly} was not given), it will only run the
four functions above if the matching \type {texmf.cnf} variable(s) or their \type
{texconfig} (see \in {section} [texconfig]) counterparts allow execution of the
requested system command. In \quote {script interpreter} runs of \LUATEX, these
settings have no effect, and all four functions have their original meaning.

Some libraries have a few more functions, either coded in \CCODE\ or in \LUA. For
instance, when we started with \LUATEX\ we added some helpers to the \type
{luafilesystem} namespace \type {lfs}. The two boolean functions \type
{lfs.isdir} and \type {lfs.isfile} were speedy and better variants of what could
be done with \type {lfs.attributes}. The additional function \type
{lfs.shortname} takes a file name and returns its short name on \type {win32}
platforms. Finally, for non|-|\type {win32} platforms only, we provided \type
{lfs.readlink} that takes an existing symbolic link as argument and returns its
name. However, the \type library evolved so we have dropped these in favour of
pure \LUA\ variants. The \type {shortname} helper is obsolete and now just
returns the name.

\stopsubsection

\startsubsection[title={Multibyte \type {string} functions}]

The \type {string} library has a few extra functions, for example \libidx
{string} {explode}. This function takes upto two arguments: \type
{string.explode(s[,m])} and returns an array containing the string argument \type
{s} split into sub-strings based on the value of the string argument \type {m}.
The second argument is a string that is either empty (this splits the string into
characters), a single character (this splits on each occurrence of that
character, possibly introducing empty strings), or a single character followed by
the plus sign \type {+} (this special version does not create empty sub-strings).
The default value for \type {m} is \quote {\type { +}} (multiple spaces). Note:
\type {m} is not hidden by surrounding braces as it would be if this function was
written in \TEX\ macros.

The \type {string} library also has six extra iterators that return strings
piecemeal: \libidx {string} {utfvalues}, \libidx {string} {utfcharacters},
\libidx {string} {characters}, \libidx {string} {characterpairs}, \libidx
{string} {bytes} and \libidx {string} {bytepairs}.

\startitemize
\startitem
    \type {string.utfvalues(s)}: an integer value in the \UNICODE\ range
\stopitem
\startitem
    \type {string.utfcharacters(s)}: a string with a single \UTF-8 token in it
\stopitem
\startitem
    \type {string.cWharacters(s)}: a string containing one byte
\stopitem
\startitem
    \type {string.characterpairs(s)}: two strings each containing one byte or an
    empty second string if the string length was odd
\stopitem
\startitem
    \type {string.bytes(s)}: a single byte value
\stopitem
\startitem
    \type {string.bytepairs(s)}: two byte values or nil instead of a number as
    its second return value if the string length was odd
\stopitem
\stopitemize

The \type {string.characterpairs()} and \type {string.bytepairs()} iterators
are useful especially in the conversion of \UTF16 encoded data into \UTF8.

There is also a two|-|argument form of \type {string.dump()}. The second argument
is a boolean which, if true, strips the symbols from the dumped data. This
matches an extension made in \type {luajit}. This is typically a function that
gets adapted as \LUA\ itself progresses.

The \type {string} library functions \type {len}, \type {lower}, \type {sub}
etc.\ are not \UNICODE|-|aware. For strings in the \UTF8 encoding, i.e., strings
containing characters above code point 127, the corresponding functions from the
\type {slnunicode} library can be used, e.g., \type {unicode.utf8.len}, \type
{unicode.utf8.lower} etc.\ The exceptions are \type {unicode.utf8.find}, that
always returns byte positions in a string, and \type {unicode.utf8.match} and
\type {unicode.utf8.gmatch}. While the latter two functions in general {\it
are} \UNICODE|-|aware, they fall|-|back to non|-|\UNICODE|-|aware behavior when
using the empty capture \type {()} but other captures work as expected. For the
interpretation of character classes in \type {unicode.utf8} functions refer to
the library sources at \hyphenatedurl {http://luaforge.net/projects/sln}.

Version 5.3 of \LUA\ provides some native \UTF8 support but we have added a few
similar helpers too: \libidx {string} {utfvalue}, \libidx {string} {utfcharacter}
and \libidx {string} {utflength}.

\startitemize
\startitem
    \type {string.utfvalue(s)}: returns the codepoints of the characters in the
    given string
\stopitem
\startitem
    \type {string.utfcharacter(c,...)}: returns a string with the characters of
    the given code points
\stopitem
\startitem
    \type {string.utflength(s)}: returns the length oif the given string
\stopitem
\stopitemize

These three functions are relative fast and don't do much checking. They can be
used as building blocks for other helpers.

\stopsubsection

\startsubsection[title={Extra \type {os} library functions}]

The \type {os} library has a few extra functions and variables: \libidx {os}
{selfdir}, \libidx {os} {exec}, \libidx {os} {spawn}, \libidx {os} {setenv},
\libidx {os} {env}, \libidx {os} {gettimeofday}, \libidx {os} {times}, \libidx
{os} {tmpdir}, \libidx {os} {type}, \libidx {os} {name} and \libidx {os} {uname},
that we will discuss here.

\startitemize

\startitem
    \type {os.selfdir} is a variable that holds the directory path of the
    actual executable. For example: \type {\directlua {tex.sprint(os.selfdir)}}.
\stopitem

\startitem
    \type {os.exec(commandline)} is a variation on \type {os.execute}. Here
    \type {commandline} can be either a single string or a single table.

    \startitemize

    \startitem
        If the argument is a table \LUATEX\ first checks if there is a value at
        integer index zero. If there is, this is the command to be executed.
        Otherwise, it will use the value at integer index one. If neither are
        present, nothing at all happens.
    \stopitem

    \startitem
        The set of consecutive values starting at integer~1 in the table are the
        arguments that are passed on to the command (the value at index~1 becomes
        \type {arg[0]}). The command is searched for in the execution path, so
        there is normally no need to pass on a fully qualified path name.
    \stopitem

    \startitem
        If the argument is a string, then it is automatically converted into a
        table by splitting on whitespace. In this case, it is impossible for the
        command and first argument to differ from each other.
    \stopitem

    \startitem
        In the string argument format, whitespace can be protected by putting
        (part of) an argument inside single or double quotes. One layer of quotes
        is interpreted by \LUATEX, and all occurrences of \type {\"}, \type {\'}
        or \type {\\} within the quoted text are unescaped. In the table format,
        there is no string handling taking place.
    \stopitem

    \stopitemize

    This function normally does not return control back to the \LUA\ script: the
    command will replace the current process. However, it will return the two
    values \type {nil} and \type {error} if there was a problem while
    attempting to execute the command.

    On \MSWINDOWS, the current process is actually kept in memory until after the
    execution of the command has finished. This prevents crashes in situations
    where \TEXLUA\ scripts are run inside integrated \TEX\ environments.

    The original reason for this command is that it cleans out the current
    process before starting the new one, making it especially useful for use in
    \TEXLUA.
\stopitem

\startitem
    \type {os.spawn(commandline)} is a returning version of \type {os.exec},
    with otherwise identical calling conventions.

    If the command ran ok, then the return value is the exit status of the
    command. Otherwise, it will return the two values \type {nil} and \type
    {error}.
\stopitem

\startitem
    \type {os.setenv(key,value)} sets a variable in the environment. Passing
    \type {nil} instead of a value string will remove the variable.
\stopitem

\startitem
    \type {os.env} is a hash table containing a dump of the variables and
    values in the process environment at the start of the run. It is writeable,
    but the actual environment is \notabene {not} updated automatically.
\stopitem

\startitem
    \type {os.gettimeofday()} returns the current \quote {\UNIX\ time}, but as a
    float. This function is not available on the \SUNOS\ platforms, so do not use
    this function for portable documents.
\stopitem

\startitem
    \type {os.times()}returns the current process times according to \ the
    \UNIX\ C library function \quote {times}. This function is not available on
    the \MSWINDOWS\ and \SUNOS\ platforms, so do not use this function for
    portable documents.
\stopitem

\startitem
    \type {os.tmpdir()} creates a directory in the \quote {current directory}
    with the name \type {luatex.XXXXXX} where the \type {X}-es are replaced by a
    unique string. The function also returns this string, so you can \type
    {lfs.chdir()} into it, or \type {nil} if it failed to create the directory.
    The user is responsible for cleaning up at the end of the run, it does not
    happen automatically.
\stopitem

\startitem
    \type {os.type} is a string that gives a global indication of the class of
    operating system. The possible values are currently \type {windows}, \type
    {unix}, and \type {msdos} (you are unlikely to find this value \quote {in the
    wild}).
\stopitem

\startitem
    \type {os.name} is a string that gives a more precise indication of the
    operating system. These possible values are not yet fixed, and for \type
    {os.type} values \type {windows} and \type {msdos}, the \type {os.name}
    values are simply \type {windows} and \type {msdos}

    The list for the type \type {unix} is more precise: \type {linux}, \type
    {freebsd}, \type {kfreebsd}, \type {cygwin}, \type {openbsd}, \type
    {solaris}, \type {sunos} (pre-solaris), \type {hpux}, \type {irix}, \type
    {macosx}, \type {gnu} (hurd), \type {bsd} (unknown, but \BSD|-|like), \type
    {sysv} (unknown, but \SYSV|-|like), \type {generic} (unknown).
\stopitem

\startitem
    \type {os.uname} returns a table with specific operating system
    information acquired at runtime. The keys in the returned table are all
    string values, and their names are: \type {sysname}, \type {machine}, \type
    {release}, \type {version}, and \type {nodename}.
\stopitem

\stopitemize

\stopsubsection

\startsubsection[title={Binary input from files with \type {fio}}]

There is a whole set of helpers for reading numbers and strings from a file:
\libidx {fio} {readcardinal1}, \libidx {fio} {readcardinal2}, \libidx {fio}
{readcardinal3}, \libidx {fio} {readcardinal4}, \libidx {fio}
{readcardinaltable}, \libidx {fio} {readinteger1}, \libidx {fio} {readinteger2},
\libidx {fio} {readinteger3}, \libidx {fio} {readinteger4}, \libidx {fio}
{readintegertable}, \libidx {fio} {readfixed2}, \libidx {fio} {readfixed4},
\libidx {fio} {read2dot14}, \libidx {fio} {setposition}, \libidx {fio}
{getposition}, \libidx {fio} {skipposition}, \libidx {fio} {readbytes}, \libidx
{fio} {readbytetable}. They work on normal \LUA\ file handles.

%libidx{fio}{readline}
%libidx{fio}{recordfilename}
%libidx{fio}{checkpermission}

This library provides a set of functions for reading numbers from a file and
in addition to the regular \type {io} library functions.

\starttabulate
\NC \type{readcardinal1(f)}         \NC a 1 byte unsigned integer \NC \NR
\NC \type{readcardinal2(f)}         \NC a 2 byte unsigned integer \NC \NR
\NC \type{readcardinal3(f)}         \NC a 3 byte unsigned integer \NC \NR
\NC \type{readcardinal4(f)}         \NC a 4 byte unsigned integer \NC \NR
\NC \type{readcardinaltable(f,n,b)} \NC \type {n} cardinals of \type {b} bytes \NC \NR
\NC \type{readinteger1(f)}          \NC a 1 byte signed integer \NC \NR
\NC \type{readinteger2(f)}          \NC a 2 byte signed integer \NC \NR
\NC \type{readinteger3(f)}          \NC a 3 byte signed integer \NC \NR
\NC \type{readinteger4(f)}          \NC a 4 byte signed integer \NC \NR
\NC \type{readintegertable(f,n,b)}  \NC \type {n} integers of \type {b} bytes \NC \NR
\NC \type{readfixed2(f)}            \NC a 2 byte float (used in font files) \NC \NR
\NC \type{readfixed4(f)}            \NC a 4 byte float (used in font files) \NC \NR
\NC \type{read2dot14(f)}            \NC a 2 byte float (used in font files) \NC \NR
\NC \type{setposition(f,p)}         \NC goto position \type {p} \NC \NR
\NC \type{getposition(f)}           \NC get the current position \NC \NR
\NC \type{skipposition(f,n)}        \NC skip \type {n} positions \NC \NR
\NC \type{readbytes(f,n)}           \NC \type {n} bytes \NC \NR
\NC \type{readbytetable(f,n)}       \NC \type {n} bytes\NC \NR
\stoptabulate

\stopsubsection

\startsubsection[title={Binary input from strings with \type {sio}}]

A similar set of function as in the \type {fio} library is available in the \type
{sio} library: \libidx {sio} {readcardinal1}, \libidx {sio} {readcardinal2},
\libidx {sio} {readcardinal3}, \libidx {sio} {readcardinal4}, \libidx {sio}
{readcardinaltable}, \libidx {sio} {readinteger1}, \libidx {sio} {readinteger2},
\libidx {sio} {readinteger3}, \libidx {sio} {readinteger4}, \libidx {sio}
{readintegertable}, \libidx {sio} {readfixed2}, \libidx {sio} {readfixed4},
\libidx {sio} {read2dot14}, \libidx {sio} {setposition}, \libidx {sio}
{getposition}, \libidx {sio} {skipposition}, \libidx {sio} {readbytes} and
\libidx {sio} {readbytetable}. Here the first argument is a string instead of a
file handle. More details can be found in the previous section.

\stopsubsection

\startsubsection[title={Hashes conform \type {sha2}}]

This library is a side effect of the \type {pdfe} library that needs such
helpers. The \libidx{sha2}{digest256}, \libidx{sha2}{digest384} and
\libidx{sha2}{digest512} functions accept a string and return a string with the
hash.

\stopsubsection

\startsubsection[title={Locales}]

\index {locales}

In stock \LUA, many things depend on the current locale. In \LUATEX, we can't do
that, because it makes documents unportable.  While \LUATEX\ is running if
forces the following locale settings:

\starttyping
LC_CTYPE=C
LC_COLLATE=C
LC_NUMERIC=C
\stoptyping

\stopsubsection

\stopsection

\startsection[title={\LUA\ modules}]

\topicindex {\LUA+libraries}
\topicindex {\LUA+modules}

Some modules that are normally external to \LUA\ are statically linked in with
\LUATEX, because they offer useful functionality:

\startitemize

\startitem
    \type {lpeg}, by Roberto Ierusalimschy, \hyphenatedurl
    {http://www.inf.puc-rio.br/~roberto/lpeg/lpeg.html}. This library is not
    \UNICODE|-|aware, but interprets strings on a byte|-|per|-|byte basis. This
    mainly means that \type {lpeg.S} cannot be used with \UTF8 characters encoded
    in more than two bytes, and thus \type {lpeg.S} will look for one of those
    two bytes when matching, not the combination of the two. The same is true for
    \type {lpeg.R}, although the latter will display an error message if used
    with multibyte characters. Therefore \type {lpeg.R('aä')} results in the
    message \type {bad argument #1 to 'R' (range must have two characters)},
    since to \type {lpeg}, \type {ä} is two 'characters' (bytes), so \type {aä}
    totals three. In practice this is no real issue and with some care you can
    deal with \UNICODE\ just fine.
\stopitem

\startitem
    \type {slnunicode}, from the \type {selene} libraries, \hyphenatedurl
    {http://luaforge.net/projects/sln}. This library has been slightly extended
    so that the \type {unicode.utf8.*} functions also accept the first 256 values
    of plane~18. This is the range \LUATEX\ uses for raw binary output, as
    explained above. We have no plans to provide more like this because you can
    basically do all that you want in \LUA.
\stopitem

\startitem
    \type {luazip}, from the kepler project, \hyphenatedurl
    {http://www.keplerproject.org/luazip/}.
\stopitem

\startitem
    \type {luafilesystem}, also from the kepler project, \hyphenatedurl
    {http://www.keplerproject.org/luafilesystem/}.
\stopitem

\startitem
    \type {lzlib}, by Tiago Dionizio, \hyphenatedurl
    {http://luaforge.net/projects/lzlib/}.
\stopitem

\startitem
    \type {md5}, by Roberto Ierusalimschy \hyphenatedurl
    {http://www.inf.puc-rio.br/~roberto/md5/md5-5/md5.html}.
\stopitem

\startitem
    \type {luasocket}, by Diego Nehab \hyphenatedurl
    {http://w3.impa.br/~diego/software/luasocket/}. The \type {.lua} support
    modules from \type {luasocket} are also preloaded inside the executable,
    there are no external file dependencies.
\stopitem

\stopitemize

\stopsection

\startsection[title={Testing}]

\topicindex {testing}
\topicindex {\PDF+date}

For development reasons you can influence the used startup date and time. This can
be done in two ways.

\startitemize[n]

\startitem
    By setting the environmment variable \type {SOURCE_DATE_EPOCH}. This will
    influence the \TEX\ parameters \type {time} and \type {date}, the random seed,
    the \PDF\ timestamp and the \PDF\ id that is derived from the time as well. This
    variable is consulted when the \KPSE\ library is enabled. Resolving is
    delegated to this library.
\stopitem

\startitem
    By setting the \type {start_time} variable in the \type {texconfig} table; as
    with other variables we use the internal name there. For compatibility
    reasons we also honour a \type {SOURCE_DATE_EPOCH} entry. It should be noted
    that there are no such variables in other engines and this method is only
    relevant in case the while setup happens in \LUA.
\stopitem

\stopitemize

When Universal Time is needed, you can pass the flag \type {utc} to the engine. This
property also works when the date and time are set by \LUATEX\ itself. It has a
complementary entry \type {use_utc_time} in the \type {texconfig} table.

There is some control possible, for instance prevent filename to be written to
the \PDF\ file. This is discussed elsewhere. In \CONTEXT\ we provide the command
line argument \type {--nodates} that does a bit more disabling of dates.

\stopsection

\stopchapter

\stopcomponent