manual/luatex-lua.tex

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