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