diff options
Diffstat (limited to 'doc/context/sources/general/manuals/luatex/luatex-lua.tex')
| -rw-r--r-- | doc/context/sources/general/manuals/luatex/luatex-lua.tex | 508 |
1 files changed, 336 insertions, 172 deletions
diff --git a/doc/context/sources/general/manuals/luatex/luatex-lua.tex b/doc/context/sources/general/manuals/luatex/luatex-lua.tex index 82b060440..f9107fa1f 100644 --- a/doc/context/sources/general/manuals/luatex/luatex-lua.tex +++ b/doc/context/sources/general/manuals/luatex/luatex-lua.tex @@ -1,15 +1,17 @@ % language=uk \environment luatex-style -\environment luatex-logos \startcomponent luatex-lua -\startchapter[reference=lua,title={\LUA\ general}] +\startchapter[reference=lua,title={Using \LUATEX}] -\section[init]{Initialization} +\startsection[title={Initialization},reference=init] -\subsection{\LUATEX\ as a \LUA\ interpreter} +\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: @@ -35,7 +37,11 @@ positive values, just like the \LUA\ interpreter. in effect, a somewhat bulky stand alone \LUA\ interpreter with a bunch of extra preloaded libraries. -\subsection{\LUATEX\ as a \LUA\ byte compiler} +\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: @@ -46,9 +52,15 @@ There are two situations that make \LUATEX\ behave like the \LUA\ byte compiler: 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. +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. -\subsection{Other commandline processing} +\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 @@ -56,6 +68,8 @@ similar fashion as the other \TEX\ engines. Some options are accepted but have n 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 @@ -65,112 +79,137 @@ consequence. The following command|-|line options are understood: \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{--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{--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{--[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-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{--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{--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 -Some of the traditional flags are just ignored: \type {--etex}, \type -{--translate-file}, \type {--8bit}. \type {--[no-]parse-first-line}, \type -{--default-translate-file}. Also, we no longer support write18 because \type -{os.execute} can do the same. +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 \type {\jobname} is decided as follows: +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 \type {\jobname}, without any changes. The argument will not be + 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 \type {\jobname} setting. + controls the \prm {jobname} setting. \stopitem \startitem - Otherwise, \type {\jobname} will be the name of the first file that is read + 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 - 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 \type - {\everyjob} either, then the \type {\jobname} is set to \type {texput} as a - last resort. + 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 -\type {\jobname}. These files are created in the directory pointed to by \type +\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. -\blank - Without the \type {--lua} option, command line processing works like it does in -any other web2c-based typesetting engine, except that \LUATEX\ has a few extra -switches. - -If the \type {--lua} option is present, \LUATEX\ will enter an alternative mode -of command line processing in comparison to the standard web2c programs. - -In this mode, a small series of actions is taken in order. 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}. - -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. - -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: - -\starttabulate[|l|l|] -\BC library \BC functions \NC \NR -\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 -\stoptabulate +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: -Furthermore, it disables loading of compiled \LUA\ libraries and it makes \type -{io.open()} fail on files that are opened for anything besides reading. +\startitemize[n] -When \LUATEX\ starts it set the 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 nil the locale with +\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 -\starttyping -os.setlocale(nil.nil) -\stoptyping +\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 -The \type {--nosocket} option makes the socket library unavailable, so that \LUA\ -cannot use networking. + \blank -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. + 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: -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. + \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 @@ -179,7 +218,7 @@ deal with typesetting, like \type {tex}, \type {token}, \type {node} and 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 \type {\jobname} yet at this point). +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 @@ -205,17 +244,34 @@ finished: in order to initialize the built|-|in \KPATHSEA\ library properly, check \type {--progname}, or \type {--ini} and \type {--fmt}, if \type {--progname} is missing. -\section{\LUA\ behaviour} +\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 \type {\dimen} or \type {\count}. +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. -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={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 @@ -226,6 +282,10 @@ 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 @@ -233,12 +293,10 @@ 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: - -\startnarrower -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: +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// @@ -248,12 +306,18 @@ 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. +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). -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. -\stopnarrower +\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 @@ -265,26 +329,29 @@ 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 function as normal. - -The \type {f:read("*line")} and \type {f:lines()} functions from the io library -have been adjusted so that they are line|-|ending neutral: any of \type {LF}, -\type {CR} or \type {CR+LF} are acceptable line endings. - -\type {luafilesystem} has been extended: there are two extra boolean functions -(\type {lfs.isdir(filename)} and \type {lfs.isfile(filename)}) and one extra -string field in its attributes table (\type {permissions}). There is an -additional function \type {lfs.shortname()} which takes a file name and returns -its short name on \type {win32} platforms. On other platforms, it just returns -the given argument. The file name is not tested for existence. Finally, for -non|-|\type {win32} platforms only, there is the new function \type -{lfs.readlink()} hat takes an existing symbolic link as argument and returns its -content. It returns an error on \type {win32}. - -The \type {string} library has an extra function: \type {string.explode(s[,m])}. -This function 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 +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). @@ -293,7 +360,9 @@ The default value for \type {m} is \quote {\type { +}} (multiple spaces). Note: written in \TEX\ macros. The \type {string} library also has six extra iterators that return strings -piecemeal: +piecemeal: \libidx {string} {utfvalues}, \libidx {string} {utfcharacters}, +\libidx {string} {characters}, \libidx {string} {characterpairs}, \libidx +{string} {bytes} and \libidx {string} {bytepairs}. \startitemize \startitem @@ -303,7 +372,7 @@ piecemeal: \type {string.utfcharacters(s)}: a string with a single \UTF-8 token in it \stopitem \startitem - \type {string.characters(s)}: a string containing one byte + \type {string.cWharacters(s)}: a string containing one byte \stopitem \startitem \type {string.characterpairs(s)}: two strings each containing one byte or an @@ -323,7 +392,8 @@ 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}. +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 @@ -338,7 +408,8 @@ 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: +similar helpers too: \libidx {string} {utfvalue}, \libidx {string} {utfcharacter} +and \libidx {string} {utflength}. \startitemize \startitem @@ -354,13 +425,18 @@ similar helpers too: \stopitem \stopitemize -These three functions are relative fast and don't do much checking. They can be used -as building blocks for other helpers. +These three functions are relative fast and don't do much checking. They can be +used as building blocks for other helpers. +\stopsubsection -\blank +\startsubsection[title={Extra \type {os} library functions}] -The \type {os} library has a few extra functions and variables: +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 @@ -373,25 +449,37 @@ The \type {os} library has a few extra functions and variables: \type {os.exec(commandline)} is a variation on \type {os.execute}. Here \type {commandline} can be either a single string or a single table. - 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. - - 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. - - 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. - - 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. + \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 @@ -470,14 +558,86 @@ The \type {os} library has a few extra functions and variables: \stopitem \startitem - \type {os.uname()} returns a table with specific operating system + \type {os.uname} returns a table with specific operating system information acquired at runtime. The keys in the returned table are all - string valued, and their names are: \type {sysname}, \type {machine}, \type + 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: @@ -488,7 +648,14 @@ LC_COLLATE=C LC_NUMERIC=C \stoptyping -\section {\LUA\ modules} +\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: @@ -496,11 +663,27 @@ Some modules that are normally external to \LUA\ are statically linked in with \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. + explained above. We have no plans to provide more like this because you can + basically do all that you want in \LUA. \stopitem \startitem @@ -514,20 +697,6 @@ Some modules that are normally external to \LUA\ are statically linked in with \stopitem \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. -\stopitem - -\startitem \type {lzlib}, by Tiago Dionizio, \hyphenatedurl {http://luaforge.net/projects/lzlib/}. \stopitem @@ -546,11 +715,12 @@ Some modules that are normally external to \LUA\ are statically linked in with \stopitemize -At some point (this also depends on distributions) \LUATEX\ might have these -libraries loaded on demand. For this reason you can best use \type {require} to -make sure they are loaded. +\stopsection -\section{Testing} +\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. @@ -579,17 +749,11 @@ When Universal Time is needed, you can pass the flag \type {utc} to the engine. 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. -\startnotabene - To some extend a cleaner solution would be to have a flag that disables all - variable data in one go (like filenames and so) but we just follow the method - implemented in \PDFTEX\ where primitives are used to influence other - properties. -\stopnotabene - -\startnotabene - In \CONTEXT\ we provide the command line argument \type {--nodates} that does - bit more disabling of dates. -\stopnotabene +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 |