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 | 154 |
1 files changed, 98 insertions, 56 deletions
diff --git a/doc/context/sources/general/manuals/luatex/luatex-lua.tex b/doc/context/sources/general/manuals/luatex/luatex-lua.tex index 976505189..3b2f9b1a7 100644 --- a/doc/context/sources/general/manuals/luatex/luatex-lua.tex +++ b/doc/context/sources/general/manuals/luatex/luatex-lua.tex @@ -68,40 +68,41 @@ 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 +\DB commandline argument \BC explanation \NC \NR \TB -\NC \type{--credits} \NC display credits and exit \NC \NR -\NC \type{--debug-format} \NC enable format debugging \NC \NR -\NC \type{--draftmode} \NC switch on draft mode i.e.\ generate no output in \PDF\ mode \NC \NR -\NC \type{--[no-]file-line-error} \NC disable/enable \type {file:line:error} style messages \NC \NR -\NC \type{--[no-]file-line-error-style} \NC aliases of \type {--[no-]file-line-error} \NC \NR -\NC \type{--fmt=FORMAT} \NC load the format file \type {FORMAT} \NC\NR -\NC \type{--halt-on-error} \NC stop processing at the first error\NC \NR -\NC \type{--help} \NC display help and exit \NC\NR -\NC \type{--ini} \NC be \type {iniluatex}, for dumping formats \NC\NR -\NC \type{--interaction=STRING} \NC set interaction mode: \type {batchmode}, \type {nonstopmode}, - \type {scrollmode} or \type {errorstopmode} \NC \NR -\NC \type{--jobname=STRING} \NC set the job name to \type {STRING} \NC \NR -\NC \type{--kpathsea-debug=NUMBER} \NC set path searching debugging flags according to the bits of - \type {NUMBER} \NC \NR -\NC \type{--lua=FILE} \NC load and execute a \LUA\ initialization script \NC\NR -\NC \type{--[no-]mktex=FMT} \NC disable/enable \type {mktexFMT} generation with \type {FMT} is - \type {tex} or \type {tfm} \NC \NR -\NC \type{--nosocket} \NC disable the \LUA\ socket library \NC\NR -\NC \type{--output-comment=STRING} \NC use \type {STRING} for \DVI\ file comment instead of date (no - effect for \PDF) \NC \NR -\NC \type{--output-directory=DIR} \NC use \type {DIR} as the directory to write files to \NC \NR -\NC \type{--output-format=FORMAT} \NC use \type {FORMAT} for job output; \type {FORMAT} is \type {dvi} - or \type {pdf} \NC \NR -\NC \type{--progname=STRING} \NC set the program name to \type {STRING} \NC \NR -\NC \type{--recorder} \NC enable filename recorder \NC \NR -\NC \type{--safer} \NC disable easily exploitable \LUA\ commands \NC\NR -\NC \type{--[no-]shell-escape} \NC disable/enable system calls \NC \NR -\NC \type{--shell-restricted} \NC restrict system calls to a list of commands given in \type - {texmf.cnf} \NC \NR -\NC \type{--synctex=NUMBER} \NC enable \type {synctex} \NC \NR -\NC \type{--utc} \NC use utc times when applicable \NC \NR -\NC \type{--version} \NC display version and exit \NC \NR +\NC \type{--credits} \NC display credits and exit \NC \NR +\NC \type{--debug-format} \NC enable format debugging \NC \NR +\NC \type{--draftmode} \NC switch on draft mode i.e.\ generate no output in \PDF\ mode \NC \NR +\NC \type{--[no-]file-line-error} \NC disable/enable \type {file:line:error} style messages \NC \NR +\NC \type{--[no-]file-line-error-style} \NC aliases of \type {--[no-]file-line-error} \NC \NR +\NC \type{--fmt=FORMAT} \NC load the format file \type {FORMAT} \NC\NR +\NC \type{--halt-on-error} \NC stop processing at the first error\NC \NR +\NC \type{--help} \NC display help and exit \NC\NR +\NC \type{--ini} \NC be \type {iniluatex}, for dumping formats \NC\NR +\NC \type{--interaction=STRING} \NC set interaction mode: \type {batchmode}, \type {nonstopmode}, + \type {scrollmode} or \type {errorstopmode} \NC \NR +\NC \type{--jobname=STRING} \NC set the job name to \type {STRING} \NC \NR +\NC \type{--kpathsea-debug=NUMBER} \NC set path searching debugging flags according to the bits of + \type {NUMBER} \NC \NR +\NC \type{--lua=FILE} \NC load and execute a \LUA\ initialization script \NC\NR +\NC \type{--[no-]mktex=FMT} \NC disable/enable \type {mktexFMT} generation with \type {FMT} is + \type {tex} or \type {tfm} \NC \NR +\NC \type{--nosocket} or \type{--no-socket} \NC disable the \LUA\ socket library \NC\NR +\NC \type{--socket} \NC enable the \LUA\ socket library \NC\NR +\NC \type{--output-comment=STRING} \NC use \type {STRING} for \DVI\ file comment instead of date (no + effect for \PDF) \NC \NR +\NC \type{--output-directory=DIR} \NC use \type {DIR} as the directory to write files to \NC \NR +\NC \type{--output-format=FORMAT} \NC use \type {FORMAT} for job output; \type {FORMAT} is \type {dvi} + or \type {pdf} \NC \NR +\NC \type{--progname=STRING} \NC set the program name to \type {STRING} \NC \NR +\NC \type{--recorder} \NC enable filename recorder \NC \NR +\NC \type{--safer} \NC disable easily exploitable \LUA\ commands \NC\NR +\NC \type{--[no-]shell-escape} \NC disable/enable system calls \NC \NR +\NC \type{--shell-restricted} \NC restrict system calls to a list of commands given in \type + {texmf.cnf} \NC \NR +\NC \type{--synctex=NUMBER} \NC enable \type {synctex} \NC \NR +\NC \type{--utc} \NC use utc times when applicable \NC \NR +\NC \type{--version} \NC display version and exit \NC \NR \LL \stoptabulate @@ -146,10 +147,10 @@ in the following order: \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}. + small subset of the options immediately: \type {--safer}, \type {--nosocket} + (\type {--no-socket}), \type {--socket}, \type {--[no-]shell-escape}, \type + {--enable-write18}, \type {--disable-write18}, \type {--shell-restricted}, + \type {--help}, \type {--version}, and \type {--credits}. \stopitem \startitem @@ -169,7 +170,8 @@ in the following order: \starttabulate[|c|l|] \DB library \BC functions \NC \NR \TB - \NC \type {os} \NC \type {execute} \type {exec} \type {spawn} \type {setenv} + \NC \type {os} \NC \type {execute} \type {exec} \type{kpsepopen} + \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} @@ -181,6 +183,9 @@ 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. + + Finally, it disables the \type {socket} library unconditionally (but not the + \type {mime} library which is always available). \stopitem \startitem @@ -193,13 +198,24 @@ in the following order: os.setlocale(nil,nil) \stoptyping - The \type {--nosocket} option makes the socket library unavailable, so that \LUA\ - cannot use networking. + The \type {--nosocket} (\type {--no-socket}) option makes the socket library + unavailable, so that \LUA\ cannot use networking; the \type {--socket} option + makes the socket library available. + + 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}, + \type {os.kpsepopen} and \type {os.spawn} adhere to the requested option. + + By default the socket library is not enabled: one can enable it with with + \type {--socket} or with \type {--shell-escape} (but without \type + {--shell-restricted}) and disable it with \type {--nosocket} (\type + {--no-socket}) or unconditionally with \type {--safer}. + + In case of conflictual options, the most restrictive wins. + + The \type{mime} library is always available. - 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 @@ -319,8 +335,8 @@ of the module itself). \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 +In keeping with the other \TEX|-|like programs in \TEXLIVE, the \LUA\ functions +\type {os.execute}, \type{os.kpsepopen} and \type {io.popen}, as well as the two new functions \type {os.exec} and \type {os.spawn} that are explained below, take the value of \type {shell_escape} and|/|or \type {shell_escape_commands} in account. Whenever \LUATEX\ is run with the assumed intention to typeset a document (and by that we @@ -339,7 +355,7 @@ 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 +name. However, the \type {lfs} 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. @@ -372,7 +388,7 @@ piecemeal: \libidx {string} {utfvalues}, \libidx {string} {utfcharacters}, \type {string.utfcharacters(s)}: a string with a single \UTF-8 token in it \stopitem \startitem - \type {string.cWharacters(s)}: a string containing one byte + \type {string.characters(s)}: a string containing one byte \stopitem \startitem \type {string.characterpairs(s)}: two strings each containing one byte or an @@ -421,7 +437,7 @@ and \libidx {string} {utflength}. the given code points \stopitem \startitem - \type {string.utflength(s)}: returns the length oif the given string + \type {string.utflength(s)}: returns the length of the given string \stopitem \stopitemize @@ -432,10 +448,14 @@ used as building blocks for other helpers. \startsubsection[title={Extra \type {os} library functions}] -The \type {os} library has a few extra functions and variables: \libidx {os} -{selfdir}, \libidx {os} {exec}, \libidx {os} {spawn}, \libidx {os} {setenv}, -\libidx {os} {env}, \libidx {os} {gettimeofday}, \libidx {os} {times}, \libidx -{os} {tmpdir}, \libidx {os} {type}, \libidx {os} {name} and \libidx {os} {uname}, +The \type {os} library has a few extra functions and +variables: \libidx {os} {selfdir}, \libidx {os} {exec}, +\libidx {os} {kpsepopen}, +\libidx {os} {socketgettime}, \libidx {os} {socketsleep}, +\libidx {os} {spawn}, \libidx {os} {setenv}, +\libidx {os} {env}, \libidx {os} {gettimeofday}, \libidx {os} {times}, +\libidx {os} {sleep}, \libidx {os} {tmpdir}, \libidx {os} {type}, +\libidx {os} {name} and \libidx {os} {uname},{os} {uname}, that we will discuss here. \startitemize @@ -496,6 +516,18 @@ that we will discuss here. \stopitem \startitem + \type {os.kpsepopen(commandline,[opt])} is similar to \type {io.popen} + but with a preliminary check of the commandline; + if the check is ok then the return value is the same as in \type{io.popen}; + Otherwise it will return the two values \type {nil} and \type {error}. +\stopitem + +\startitem + \type {os.socketgettime} and \type {os.socketsleep} are the same as for + \type{socket.gettime} and \type{socket.sleep} but they are always available. +\stopitem + +\startitem \type {os.spawn(commandline)} is a returning version of \type {os.exec}, with otherwise identical calling conventions. @@ -522,19 +554,29 @@ that we will discuss here. \stopitem \startitem - \type {os.times()}returns the current process times according to \ the + \type {os.times()}returns the current process times according to the \UNIX\ C library function \quote {times}. This function is not available on the \MSWINDOWS\ and \SUNOS\ platforms, so do not use this function for portable documents. \stopitem \startitem - \type {os.tmpdir()} creates a directory in the \quote {current directory} + \type {os.sleep(interval[, unit])} suspends the execution of the current run for + a given number of seconds. If the optional argument \type {unit} is present, the + function waits \type {interval / units} seconds. \type {os.sleep(1, 1000)} + for example pauses the program for one millisecond. +\stopitem + +\startitem + \type {os.tmpdir([template])} creates a directory in the \quote {current directory} with the name \type {luatex.XXXXXX} where the \type {X}-es are replaced by a unique string. The function also returns this string, so you can \type {lfs.chdir()} into it, or \type {nil} if it failed to create the directory. The user is responsible for cleaning up at the end of the run, it does not - happen automatically. + happen automatically. You can also use your own \type {template} for the name + of the temporary folder. However, the passed string must end with six capital + \type {X}-es. For example, the template \type {tmp.XXXXXX} could result in the + folder name \type {tmp.vX3gPo}. \stopitem \startitem |