manual/luatex-lua.tex

   1 % language=uk
   2
   3 \environment luatex-style
   4 \environment luatex-logos
   5
   6 \startcomponent luatex-lua
   7
   8 \startchapter[reference=lua,title={\LUA\ general}]
   9
  10 \section[init]{Initialization}
  11
  12 \subsection{\LUATEX\ as a \LUA\ interpreter}
  13
  14 There are some situations that make \LUATEX\ behave like a standalone \LUA\
  15 interpreter:
  16
  17 \startitemize[packed]
  18 \startitem
  19     if a \type {--luaonly} option is given on the commandline, or
  20 \stopitem
  21 \startitem
  22     if the executable is named \type {texlua} or \type {luatexlua}, or
  23 \stopitem
  24 \startitem
  25     if the only non|-|option argument (file) on the commandline has the extension
  26     \type {lua} or \type {luc}.
  27 \stopitem
  28 \stopitemize
  29
  30 In this mode, it will set \LUA's \type {arg[0]} to the found script name, pushing
  31 preceding options in negative values and the rest of the command line in the
  32 positive values, just like the \LUA\ interpreter.
  33
  34 \LUATEX\ will exit immediately after executing the specified \LUA\ script and is,
  35 in effect, a somewhat bulky stand alone \LUA\ interpreter with a bunch of extra
  36 preloaded libraries.
  37
  38 \subsection{\LUATEX\ as a \LUA\ byte compiler}
  39
  40 There are two situations that make \LUATEX\ behave like the \LUA\ byte compiler:
  41
  42 \startitemize[packed]
  43 \startitem if a \type {--luaconly} option is given on the command line, or \stopitem
  44 \startitem if the executable is named \type {texluac} \stopitem
  45 \stopitemize
  46
  47 In this mode, \LUATEX\ is exactly like \type {luac} from the stand alone \LUA\
  48 distribution, except that it does not have the \type {-l} switch, and that it
  49 accepts (but ignores) the \type {--luaconly} switch.
  50
  51 \subsection{Other commandline processing}
  52
  53 When the \LUATEX\ executable starts, it looks for the \type {--lua} command line
  54 option. If there is no \type {--lua} option, the command line is interpreted in a
  55 similar fashion as the other \TEX\ engines. Some options are accepted but have no
  56 consequence. The following command|-|line options are understood:
  57
  58 \starttabulate[|lT|p|]
  59 \NC --credits                    \NC display credits and exit \NC \NR
  60 \NC --debug-format               \NC enable format debugging \NC \NR
  61 \NC --draftmode                  \NC switch on draft mode i.e.\ generate no output in \PDF\ mode \NC \NR
  62 \NC --[no-]file-line-error       \NC disable/enable \type {file:line:error} style messages \NC \NR
  63 \NC --[no-]file-line-error-style \NC aliases of \type {--[no-]file-line-error} \NC \NR
  64 \NC --fmt=FORMAT                 \NC load the format file \type {FORMAT} \NC\NR
  65 \NC --halt-on-error              \NC stop processing at the first error\NC \NR
  66 \NC --help                       \NC display help and exit \NC\NR
  67 \NC --ini                        \NC be \type {iniluatex}, for dumping formats \NC\NR
  68 \NC --interaction=STRING         \NC set interaction mode: \type {batchmode}, \type {nonstopmode}, \type {scrollmode} or \type {errorstopmode} \NC \NR
  69 \NC --jobname=STRING             \NC set the job name to \type {STRING} \NC \NR
  70 \NC --kpathsea-debug=NUMBER      \NC set path searching debugging flags according to the bits of \type {NUMBER} \NC \NR
  71 \NC --lua=FILE                   \NC load and execute a \LUA\ initialization script \NC\NR
  72 \NC --[no-]mktex=FMT             \NC disable/enable \type {mktexFMT} generation with \type {FMT} is \type {tex} or \type {tfm} \NC \NR
  73 \NC --nosocket                   \NC disable the \LUA\ socket library \NC\NR
  74 \NC --output-comment=STRING      \NC use \type {STRING} for \DVI\ file comment instead of date (no effect for \PDF) \NC \NR
  75 \NC --output-directory=DIR       \NC use \type {DIR} as the directory to write files to \NC \NR
  76 \NC --output-format=FORMAT       \NC use \type {FORMAT} for job output; \type {FORMAT} is \type {dvi} or \type {pdf} \NC \NR
  77 \NC --progname=STRING            \NC set the program name to \type {STRING} \NC \NR
  78 \NC --recorder                   \NC enable filename recorder \NC \NR
  79 \NC --safer                      \NC disable easily exploitable \LUA\ commands \NC\NR
  80 \NC --[no-]shell-escape          \NC disable/enable system calls \NC \NR
  81 \NC --shell-restricted           \NC restrict system calls to a list of commands given in \type {texmf.cnf} \NC \NR
  82 \NC --synctex=NUMBER             \NC enable \type {synctex} \NC \NR
  83 \NC --utc                        \NC use utc times when applicable \NC \NR
  84 \NC --version                    \NC display version and exit \NC \NR
  85 \stoptabulate
  86
  87 Some of the traditional flags are just ignored: \type {--etex}, \type
  88 {--translate-file}, \type {--8bit}. \type {--[no-]parse-first-line}, \type
  89 {--default-translate-file}. Also, we no longer support write18 because \type
  90 {os.execute} can do the same.
  91
  92 The value to use for \type {\jobname} is decided as follows:
  93
  94 \startitemize
  95 \startitem
  96     If \type {--jobname} is given on the command line, its argument will be the
  97     value for \type {\jobname}, without any changes. The argument will not be
  98     used for actual input so it need not exist. The \type {--jobname} switch only
  99     controls the \type {\jobname} setting.
 100 \stopitem
 101 \startitem
 102     Otherwise, \type {\jobname} will be the name of the first file that is read
 103     from the file system, with any path components and the last extension (the
 104     part following the last \type {.}) stripped off.
 105 \stopitem
 106 \startitem
 107     An exception to the previous point: if the command line goes into interactive
 108     mode (by starting with a command) and there are no files input via \type
 109     {\everyjob} either, then the \type {\jobname} is set to \type {texput} as a
 110     last resort.
 111 \stopitem
 112 \stopitemize
 113
 114 The file names for output files that are generated automatically are created by
 115 attaching the proper extension (\type {log}, \type {pdf}, etc.) to the found
 116 \type {\jobname}. These files are created in the directory pointed to by \type
 117 {--output-directory}, or in the current directory, if that switch is not present.
 118
 119 \blank
 120
 121 Without the \type {--lua} option, command line processing works like it does in
 122 any other web2c-based typesetting engine, except that \LUATEX\ has a few extra
 123 switches.
 124
 125 If the \type {--lua} option is present, \LUATEX\ will enter an alternative mode
 126 of command line processing in comparison to the standard web2c programs.
 127
 128 In this mode, a small series of actions is taken in order. First, it will parse
 129 the command line as usual, but it will only interpret a small subset of the
 130 options immediately: \type {--safer}, \type {--nosocket}, \type
 131 {--[no-]shell-escape}, \type {--enable-write18}, \type {--disable-write18}, \type
 132 {--shell-restricted}, \type {--help}, \type {--version}, and \type {--credits}.
 133
 134 Next \LUATEX\ searches for the requested \LUA\ initialization script. If it
 135 cannot be found using the actual name given on the command line, a second attempt
 136 is made by prepending the value of the environment variable \type {LUATEXDIR}, if
 137 that variable is defined in the environment.
 138
 139 Then it checks the various safety switches. You can use those to disable some
 140 \LUA\ commands that can easily be abused by a malicious document. At the moment,
 141 \type {--safer} \type {nil}s the following functions:
 142
 143 \starttabulate[|l|l|]
 144 \NC \bf library \NC \bf functions \NC \NR
 145 \NC \type {os}   \NC \type {execute} \type {exec} \type {spawn} \type {setenv} \type {rename} \type {remove} \type {tmpdir} \NC \NR
 146 \NC \type {io}   \NC \type {popen} \type {output} \type {tmpfile} \NC \NR
 147 \NC \type {lfs}  \NC \type {rmdir} \type {mkdir} \type {chdir} \type {lock} \type {touch} \NC \NR
 148 \stoptabulate
 149
 150 Furthermore, it disables loading of compiled \LUA\ libraries and it makes \type
 151 {io.open()} fail on files that are opened for anything besides reading.
 152
 153 When \LUATEX\ starts it set the locale to a neutral value. If for some reason you
 154 use \type {os.locale}, you need to make sure you \type {nil} it afterwards
 155 because otherwise it can interfere with code that for instance generates dates.
 156 You can nil the locale with
 157
 158 \starttyping
 159 os.setlocale(nil.nil)
 160 \stoptyping
 161
 162 The \type {--nosocket} option makes the socket library unavailable, so that \LUA\
 163 cannot use networking.
 164
 165 The switches \type {--[no-]shell-escape}, \type {--[enable|disable]-write18}, and
 166 \type {--shell-restricted} have the same effects as in \PDFTEX, and additionally
 167 make \type {io.popen()}, \type {os.execute}, \type {os.exec} and \type {os.spawn}
 168 adhere to the requested option.
 169
 170 Next the initialization script is loaded and executed. From within the script,
 171 the entire command line is available in the \LUA\ table \type {arg}, beginning with
 172 \type {arg[0]}, containing the name of the executable. As consequence warnings
 173 about unrecognized options are suppressed.
 174
 175 Command line processing happens very early on. So early, in fact, that none of
 176 \TEX's initializations have taken place yet. For that reason, the tables that
 177 deal with typesetting, like \type {tex}, \type {token}, \type {node} and
 178 \type {pdf}, are off|-|limits during the execution of the startup file (they
 179 are \type {nil}'d). Special care is taken that \type {texio.write} and \type
 180 {texio.write_nl} function properly, so that you can at least report your actions
 181 to the log file when (and if) it eventually becomes opened (note that \TEX\ does
 182 not even know its \type {\jobname} yet at this point). See \in {chapter} [libraries]
 183 for more information about the \LUATEX-specific \LUA\ extension tables.
 184
 185 Everything you do in the \LUA\ initialization script will remain visible during
 186 the rest of the run, with the exception of the \TEX\ specific libraries like
 187 \type {tex}, \type {token}, \type {node} and \type {pdf} tables. These will be
 188 initialized to their documented state after the execution of the script. You
 189 should not store anything in variables or within tables with these four global
 190 names, as they will be overwritten completely.
 191
 192 We recommend you use the startup file only for your own \TEX|-|independent
 193 initializations (if you need any), to parse the command line, set values in the
 194 \type {texconfig} table, and register the callbacks you need.
 195
 196 \LUATEX\ allows some of the command line options to be overridden by reading
 197 values from the \type {texconfig} table at the end of script execution (see the
 198 description of the \type {texconfig} table later on in this document for more
 199 details on which ones exactly).
 200
 201 Unless the \type {texconfig} table tells \LUATEX\ not to initialize \KPATHSEA\
 202 at all (set \type {texconfig.kpse_init} to \type {false} for that), \LUATEX\
 203 acts on some more command line options after the initialization script is
 204 finished: in order to initialize the built|-|in \KPATHSEA\ library properly,
 205 \LUATEX\ needs to know the correct program name to use, and for that it needs to
 206 check \type {--progname}, or \type {--ini} and \type {--fmt}, if \type
 207 {--progname} is missing.
 208
 209 \section{\LUA\ behaviour}
 210
 211 \LUA s \type {tostring} function (and \type {string.format} may return values in
 212 scientific notation, thereby confusing the \TEX\ end of things when it is used as
 213 the right|-|hand side of an assignment to a \type {\dimen} or \type {\count}.
 214
 215 Loading dynamic \LUA\ libraries will fail if there are two \LUA\ libraries loaded
 216 at the same time (which will typically happen on \type {win32}, because there is
 217 one \LUA\ 5.2 inside \LUATEX, and another will likely be linked to the \DLL\ file
 218 of the module itself).
 219
 220 \LUATEX\ is able to use the kpathsea library to find \type {require()}d modules.
 221 For this purpose, \type {package.searchers[2]} is replaced by a different loader
 222 function, that decides at runtime whether to use kpathsea or the built|-|in core
 223 \LUA\ function. It uses \KPATHSEA\ when that is already initialized at that point
 224 in time, otherwise it reverts to using the normal \type {package.path} loader.
 225
 226 Initialization of \KPATHSEA\ can happen either implicitly (when \LUATEX\ starts
 227 up and the startup script has not set \type {texconfig.kpse_init} to false), or
 228 explicitly by calling the \LUA\ function \type {kpse.set_program_name()}.
 229
 230 \LUATEX\ is able to use dynamically loadable \LUA\ libraries, unless
 231 \type {--safer} was given as an option on the command line. For this purpose,
 232 \type {package.searchers[3]} is replaced by a different loader function, that
 233 decides at runtime whether to use \KPATHSEA\ or the built|-|in core \LUA\
 234 function. It uses \KPATHSEA\ when that is already initialized at that point in
 235 time, otherwise it reverts to using the normal \type {package.cpath} loader.
 236
 237 This functionality required an extension to kpathsea:
 238
 239 \startnarrower
 240 There is a new kpathsea file format: \type {kpse_clua_format} that searches for
 241 files with extension \type {.dll} and \type {.so}. The \type {texmf.cnf} setting
 242 for this variable is \type {CLUAINPUTS}, and by default it has this value:
 243
 244 \starttyping
 245 CLUAINPUTS=.:$SELFAUTOLOC/lib/{$progname,$engine,}/lua//
 246 \stoptyping
 247
 248 This path is imperfect (it requires a \TDS\ subtree below the binaries
 249 directory), but the architecture has to be in the path somewhere, and the
 250 currently simplest way to do that is to search below the binaries directory only.
 251 Of course it no big deal to write an alternative loader and use that in a macro
 252 package.
 253
 254 One level up (a \type {lib} directory parallel to \type {bin}) would have been
 255 nicer, but that is not doable because \TEXLIVE\ uses a \type {bin/<arch>}
 256 structure.
 257 \stopnarrower
 258
 259 In keeping with the other \TEX|-|like programs in \TEXLIVE, the two \LUA\ functions
 260 \type {os.execute} and \type {io.popen}, as well as the two new functions \type
 261 {os.exec} and \type {os.spawn} that are explained below, take the value of \type
 262 {shell_escape} and|/|or \type {shell_escape_commands} in account. Whenever
 263 \LUATEX\ is run with the assumed intention to typeset a document (and by that we
 264 mean that it is called as \type {luatex}, as opposed to \type {texlua}, and that
 265 the command line option \type {--luaonly} was not given), it will only run the
 266 four functions above if the matching \type {texmf.cnf} variable(s) or their \type
 267 {texconfig} (see \in {section} [texconfig]) counterparts allow execution of the
 268 requested system command. In \quote {script interpreter} runs of \LUATEX, these
 269 settings have no effect, and all four functions function as normal.
 270
 271 The \type {f:read("*line")} and \type {f:lines()} functions from the io library
 272 have been adjusted so that they are line|-|ending neutral: any of \type {LF},
 273 \type {CR} or \type {CR+LF} are acceptable line endings.
 274
 275 \type {luafilesystem} has been extended: there are two extra boolean functions
 276 (\type {lfs.isdir(filename)} and \type {lfs.isfile(filename)}) and one extra
 277 string field in its attributes table (\type {permissions}). There is an
 278 additional function \type {lfs.shortname()} which takes a file name and returns
 279 its short name on \type {win32} platforms. On other platforms, it just returns
 280 the given argument. The file name is not tested for existence. Finally, for
 281 non|-|\type {win32} platforms only, there is the new function \type
 282 {lfs.readlink()} hat takes an existing symbolic link as argument and returns its
 283 content. It returns an error on \type {win32}.
 284
 285 The \type {string} library has an extra function: \type {string.explode(s[,m])}.
 286 This function returns an array containing the string argument \type {s} split
 287 into sub-strings based on the value of the string argument \type {m}. The second
 288 argument is a string that is either empty (this splits the string into
 289 characters), a single character (this splits on each occurrence of that
 290 character, possibly introducing empty strings), or a single character followed by
 291 the plus sign \type {+} (this special version does not create empty sub-strings).
 292 The default value for \type {m} is \quote {\type { +}} (multiple spaces). Note:
 293 \type {m} is not hidden by surrounding braces as it would be if this function was
 294 written in \TEX\ macros.
 295
 296 The \type {string} library also has six extra iterators that return strings
 297 piecemeal:
 298
 299 \startitemize
 300 \startitem
 301     \type {string.utfvalues(s)}: an integer value in the \UNICODE\ range
 302 \stopitem
 303 \startitem
 304     \type {string.utfcharacters(s)}: a string with a single \UTF-8 token in it
 305 \stopitem
 306 \startitem
 307     \type {string.characters(s)} \NC a string containing one byte
 308 \stopitem
 309 \startitem
 310     \type {string.characterpairs(s)} two strings each containing one byte or an
 311     empty second string if the string length was odd
 312 \stopitem
 313 \startitem
 314     \type {string.bytes(s)} a single byte value
 315 \stopitem
 316 \startitem
 317     \type {string.bytepairs(s)} two byte values or nil instead of a number as
 318     its second return value if the string length was odd
 319 \stopitem
 320 \stopitemize
 321
 322 The \type {string.characterpairs()} and \type {string.bytepairs()} iterators
 323 are useful especially in the conversion of \UTF16 encoded data into \UTF8.
 324
 325 There is also a two|-|argument form of \type {string.dump()}. The second argument
 326 is a boolean which, if true, strips the symbols from the dumped data. This
 327 matches an extension made in \type {luajit}.
 328
 329 The \type {string} library functions \type {len}, \type {lower}, \type {sub}
 330 etc.\ are not \UNICODE|-|aware. For strings in the \UTF8 encoding, i.e., strings
 331 containing characters above code point 127, the corresponding functions from the
 332 \type {slnunicode} library can be used, e.g., \type {unicode.utf8.len}, \type
 333 {unicode.utf8.lower} etc.\ The exceptions are \type {unicode.utf8.find}, that
 334 always returns byte positions in a string, and \type {unicode.utf8.match} and
 335 \type {unicode.utf8.gmatch}. While the latter two functions in general {\it
 336 are} \UNICODE|-|aware, they fall|-|back to non|-|\UNICODE|-|aware behavior when
 337 using the empty capture \type {()} but other captures work as expected. For the
 338 interpretation of character classes in \type {unicode.utf8} functions refer to
 339 the library sources at \hyphenatedurl {http://luaforge.net/projects/sln}. Version
 340 5.3 of \LUA\ will provide some native \UTF8 support.
 341
 342 \blank
 343
 344 The \type {os} library has a few extra functions and variables:
 345
 346 \startitemize
 347
 348 \startitem
 349     \type {os.selfdir} is a variable that holds the directory path of the
 350     actual executable. For example: \type {\directlua {tex.sprint(os.selfdir)}}.
 351 \stopitem
 352
 353 \startitem
 354     \type {os.exec(commandline)} is a variation on \type {os.execute}. Here
 355     \type {commandline} can be either a single string or a single table.
 356
 357     If the argument is a table \LUATEX\ first checks if there is a value at
 358     integer index zero. If there is, this is the command to be executed.
 359     Otherwise, it will use the value at integer index one. If neither are
 360     present, nothing at all happens.
 361
 362     The set of consecutive values starting at integer~1 in the table are the
 363     arguments that are passed on to the command (the value at index~1 becomes
 364     \type {arg[0]}). The command is searched for in the execution path, so there
 365     is normally no need to pass on a fully qualified path name.
 366
 367     If the argument is a string, then it is automatically converted into a table
 368     by splitting on whitespace. In this case, it is impossible for the command
 369     and first argument to differ from each other.
 370
 371     In the string argument format, whitespace can be protected by putting (part
 372     of) an argument inside single or double quotes. One layer of quotes is
 373     interpreted by \LUATEX, and all occurrences of \type {\"}, \type {\'} or \type
 374     {\\} within the quoted text are unescaped. In the table format, there is no
 375     string handling taking place.
 376
 377     This function normally does not return control back to the \LUA\ script: the
 378     command will replace the current process. However, it will return the two
 379     values \type {nil} and \type {error} if there was a problem while
 380     attempting to execute the command.
 381
 382     On \MSWINDOWS, the current process is actually kept in memory until after the
 383     execution of the command has finished. This prevents crashes in situations
 384     where \TEXLUA\ scripts are run inside integrated \TEX\ environments.
 385
 386     The original reason for this command is that it cleans out the current
 387     process before starting the new one, making it especially useful for use in
 388     \TEXLUA.
 389 \stopitem
 390
 391 \startitem
 392     \type {os.spawn(commandline)} is a returning version of \type {os.exec},
 393     with otherwise identical calling conventions.
 394
 395     If the command ran ok, then the return value is the exit status of the
 396     command. Otherwise, it will return the two values \type {nil} and \type
 397     {error}.
 398 \stopitem
 399
 400 \startitem
 401     \type {os.setenv(key,value)} sets a variable in the environment. Passing
 402     \type {nil} instead of a value string will remove the variable.
 403 \stopitem
 404
 405 \startitem
 406     \type {os.env} is a hash table containing a dump of the variables and
 407     values in the process environment at the start of the run. It is writeable,
 408     but the actual environment is {\em not\/} updated automatically.
 409 \stopitem
 410
 411 \startitem
 412     \type {os.gettimeofday()} returns the current \quote {\UNIX\ time}, but as a
 413     float. This function is not available on the \SUNOS\ platforms, so do not use
 414     this function for portable documents.
 415 \stopitem
 416
 417 \startitem
 418     \type {os.times()}returns the current process times according to \ the
 419     \UNIX\ C library function \quote {times}. This function is not available on
 420     the \MSWINDOWS\ and \SUNOS\ platforms, so do not use this function for
 421     portable documents.
 422 \stopitem
 423
 424 \startitem
 425     \type {os.tmpdir()} creates a directory in the \quote {current directory}
 426     with the name \type {luatex.XXXXXX} where the \type {X}-es are replaced by a
 427     unique string. The function also returns this string, so you can \type
 428     {lfs.chdir()} into it, or \type {nil} if it failed to create the directory.
 429     The user is responsible for cleaning up at the end of the run, it does not
 430     happen automatically.
 431 \stopitem
 432
 433 \startitem
 434     \type {os.type} is a string that gives a global indication of the class of
 435     operating system. The possible values are currently \type {windows}, \type
 436     {unix}, and \type {msdos} (you are unlikely to find this value \quote {in the
 437     wild}).
 438 \stopitem
 439
 440 \startitem
 441     \type {os.name} is a string that gives a more precise indication of the
 442     operating system. These possible values are not yet fixed, and for \type
 443     {os.type} values \type {windows} and \type {msdos}, the \type {os.name}
 444     values are simply \type {windows} and \type {msdos}
 445
 446     The list for the type \type {unix} is more precise: \type {linux}, \type
 447     {freebsd}, \type {kfreebsd}, \type {cygwin}, \type {openbsd}, \type
 448     {solaris}, \type {sunos} (pre-solaris), \type {hpux}, \type {irix}, \type
 449     {macosx}, \type {gnu} (hurd), \type {bsd} (unknown, but \BSD|-|like), \type
 450     {sysv} (unknown, but \SYSV|-|like), \type {generic} (unknown).
 451 \stopitem
 452
 453 \startitem
 454     \type {os.uname()} returns a table with specific operating system
 455     information acquired at runtime. The keys in the returned table are all
 456     string valued, and their names are: \type {sysname}, \type {machine}, \type
 457     {release}, \type {version}, and \type {nodename}.
 458 \stopitem
 459
 460 \stopitemize
 461
 462 In stock \LUA, many things depend on the current locale. In \LUATEX, we can't do
 463 that, because it makes documents unportable.  While \LUATEX\ is running if
 464 forces the following locale settings:
 465
 466 \starttyping
 467 LC_CTYPE=C
 468 LC_COLLATE=C
 469 LC_NUMERIC=C
 470 \stoptyping
 471
 472 \section {\LUA\ modules}
 473
 474 Some modules that are normally external to \LUA\ are statically linked in with
 475 \LUATEX, because they offer useful functionality:
 476
 477 \startitemize
 478
 479 \startitem
 480     \type {slnunicode}, from the \type {selene} libraries, \hyphenatedurl
 481     {http://luaforge.net/projects/sln}. This library has been slightly extended
 482     so that the \type {unicode.utf8.*} functions also accept the first 256 values
 483     of plane~18. This is the range \LUATEX\ uses for raw binary output, as
 484     explained above.
 485 \stopitem
 486
 487 \startitem
 488     \type {luazip}, from the kepler project, \hyphenatedurl
 489     {http://www.keplerproject.org/luazip/}.
 490 \stopitem
 491
 492 \startitem
 493     \type {luafilesystem}, also from the kepler project, \hyphenatedurl
 494     {http://www.keplerproject.org/luafilesystem/}.
 495 \stopitem
 496
 497 \startitem
 498     \type {lpeg}, by Roberto Ierusalimschy, \hyphenatedurl
 499     {http://www.inf.puc-rio.br/~roberto/lpeg/lpeg.html}. This library is not
 500     \UNICODE|-|aware, but interprets strings on a byte|-|per|-|byte basis. This
 501     mainly means that \type {lpeg.S} cannot be used with \UTF8 characters encoded
 502     in more than two bytes, and thus \type {lpeg.S} will look for one of those
 503     two bytes when matching, not the combination of the two. The same is true for
 504     \type {lpeg.R}, although the latter will display an error message if used
 505     with multibyte characters. Therefore \type {lpeg.R('aä')} results in the
 506     message \type {bad argument #1 to 'R' (range must have two characters)},
 507     since to \type {lpeg}, \type {ä} is two 'characters' (bytes), so \type {aä}
 508     totals three. In practice this is no real issue.
 509 \stopitem
 510
 511 \startitem
 512     \type {lzlib}, by Tiago Dionizio, \hyphenatedurl
 513     {http://luaforge.net/projects/lzlib/}.
 514 \stopitem
 515
 516 \startitem
 517     \type {md5}, by Roberto Ierusalimschy \hyphenatedurl
 518     {http://www.inf.puc-rio.br/~roberto/md5/md5-5/md5.html}.
 519 \stopitem
 520
 521 \startitem
 522     \type {luasocket}, by Diego Nehab \hyphenatedurl
 523     {http://w3.impa.br/~diego/software/luasocket/}. The \type {.lua} support
 524     modules from \type {luasocket} are also preloaded inside the executable,
 525     there are no external file dependencies.
 526 \stopitem
 527
 528 \stopitemize
 529
 530 At some point (this also depends on distributions) \LUATEX\ might have these
 531 libraries loaded on demand. For this reason you can best use \type {require} to
 532 make sure they are loaded.
 533
 534 \section{Testing}
 535
 536 For development reasons you can influence the used startup date and time. This can
 537 be done in two ways.
 538
 539 \startitemize[n]
 540
 541 \startitem
 542     By setting the environmment variable \type {SOURCE_DATE_EPOCH}. This will
 543     influence the \TEX\ parameters \type {time} and \type {date}, the random seed,
 544     the \PDF\ timestamp and the \PDF\ id that is derived from the time as well. This
 545     variable is consulted when the \KPSE\ library is enabled. Resolving is
 546     delegated to this library.
 547 \stopitem
 548
 549 \startitem
 550     By setting the \type {start_time} variable in the \type {texconfig} table; as
 551     with other variables we use the internal name there. For compatibility
 552     reasons we also honour a \type {SOURCE_DATE_EPOCH} entry. It should be noted
 553     that there are no such variables in other engines and this method is only
 554     relevant in case the while setup happens in \LUA.
 555 \stopitem
 556
 557 \stopitemize
 558
 559 When Universal Time is needed, you can pass the flag \type {utc} to the engine. This
 560 property also works when the date and time are set by \LUATEX\ itself. It has a
 561 complementary entry \type {use_utc_time} in the \type {texconfig} table.
 562
 563 {\em To some extend a cleaner solution would be to have a flag that disables all
 564 variable data in one go (like filenames and so) but we just follow the method
 565 implemented in \PDFTEX\ where primitives are used to influence other properties.}
 566
 567 {\em In \CONTEXT\ we provide the command line argument \type {--nodates} that
 568 does bit more disabling of dates.}
 569
 570 \stopchapter
 571
 572 \stopcomponent