% \iffalse meta-comment % %% File: l3luatex.dtx % % Copyright (C) 2010-2021 The LaTeX Project % % It may be distributed and/or modified under the conditions of the % LaTeX Project Public License (LPPL), either version 1.3c of this % license or (at your option) any later version. The latest version % of this license is in the file % % https://www.latex-project.org/lppl.txt % % This file is part of the "l3kernel bundle" (The Work in LPPL) % and all files in that bundle must be distributed together. % % ----------------------------------------------------------------------- % % The development version of the bundle can be found at % % https://github.com/latex3/latex3 % % for those people who are interested. % %<*driver> \documentclass[full,kernel]{l3doc} \begin{document} \DocInput{\jobname.dtx} \end{document} % % \fi % % \title{^^A % The \pkg{l3luatex} package: \LuaTeX-specific functions^^A % } % % \author{^^A % The \LaTeX{} Project\thanks % {^^A % E-mail: % \href{mailto:latex-team@latex-project.org} % {latex-team@latex-project.org}^^A % }^^A % } % % \date{Released 2021-10-12} % % \maketitle % % \begin{documentation} % % The \LuaTeX{} engine provides access to the \Lua{} programming language, % and with it access to the \enquote{internals} of \TeX{}. In order to use % this within the framework provided here, a family of functions is % available. When used with \pdfTeX{}, \pTeX{}, \upTeX{} or \XeTeX{} these raise an % error: use \cs{sys_if_engine_luatex:T} to avoid this. Details on using % \Lua{} with the \LuaTeX{} engine are given in the \LuaTeX{} manual. % % \section{Breaking out to \Lua{}} % % \begin{function}[EXP, added = 2018-06-18]{\lua_now:n, \lua_now:e} % \begin{syntax} % \cs{lua_now:n} \Arg{token list} % \end{syntax} % The \meta{token list} is first tokenized by \TeX{}, which includes % converting line ends to spaces in the usual \TeX{} manner and which % respects currently-applicable \TeX{} category codes. The resulting % \meta{\Lua{} input} is passed to the \Lua{} interpreter for processing. % Each \cs{lua_now:n} block is treated by \Lua{} as a separate chunk. % The \Lua{} interpreter executes the \meta{\Lua{} input} immediately, % and in an expandable manner. % \begin{texnote} % \cs{lua_now:e} is a macro wrapper around \tn{directlua}: when % \LuaTeX{} is in use two expansions are required to yield the % result of the \Lua{} code. % \end{texnote} % \end{function} % % \begin{function}[added = 2018-06-18]{\lua_shipout_e:n, \lua_shipout:n} % \begin{syntax} % \cs{lua_shipout:n} \Arg{token list} % \end{syntax} % The \meta{token list} is first tokenized by \TeX{}, which includes % converting line ends to spaces in the usual \TeX{} manner and which % respects currently-applicable \TeX{} category codes. The resulting % \meta{\Lua{} input} is passed to the \Lua{} interpreter when the % current page is finalised (\emph{i.e.}~at shipout). Each % \cs{lua_shipout:n} block is treated by \Lua{} as a separate chunk. % The \Lua{} interpreter will execute the \meta{\Lua{} input} during the % page-building routine: no \TeX{} expansion of the \meta{\Lua{} input} % will occur at this stage. % % In the case of the \cs{lua_shipout_e:n} version the input is fully % expanded by \TeX{} in an \texttt{e}-type manner during the shipout % operation. % \begin{texnote} % At a \TeX{} level, the \meta{\Lua{} input} is stored as a % \enquote{whatsit}. % \end{texnote} % \end{function} % % \begin{function}[EXP, added = 2015-06-29]{\lua_escape:n, \lua_escape:e} % \begin{syntax} % \cs{lua_escape:n} \Arg{token list} % \end{syntax} % Converts the \meta{token list} such that it can safely be passed to % \Lua{}: embedded backslashes, double and single quotes, and newlines % and carriage returns are escaped. This is done by prepending an extra % token consisting of a backslash with category code~$12$, and for the line % endings, converting them to |\n| and |\r|, respectively. % \begin{texnote} % \cs{lua_escape:e} is a macro wrapper around \tn{luaescapestring}: % when \LuaTeX{} is in use two expansions are required to yield the % result of the \Lua{} code. % \end{texnote} % \end{function} % % \section{Lua interfaces} % % As well as interfaces for \TeX{}, there are a small number of Lua functions % provided here. % % \begin{function}{ltx.utils} % Most public interfaces provided by the module are stored within the % |ltx.utils| table. % \end{function} % % \begin{function}[deprecated = 2021-12-31]{l3kernel} % For compatibility reasons, there are also some deprecated interfaces provided % in the |l3kernel| table. These do not return their result as Lua values but % instead print them to \TeX. % \end{function} % % \begin{function}{l3kernel.charcat} % \begin{syntax} % |l3kernel.charcat(|\meta{charcode}, \meta{catcode}|)| % \end{syntax} % Constructs a character of \meta{charcode} and \meta{catcode} and returns % the result to \TeX{}. % \end{function} % % \begin{function}{l3kernel.elapsedtime} % \begin{syntax} % |l3kernel.elapsedtime()| % \end{syntax} % Returns the CPU time in \meta{scaled seconds} since the start of the % \TeX{} run or since |l3kernel.resettimer| was issued. This only % measures the time used by the CPU, not the real time, e.g., waiting % for user input. % \end{function} % % \begin{function}{ltx.utils.filedump, l3kernel.filedump} % \begin{syntax} % \meta{dump}| = ltx.utils.filedump(|\meta{file}|,|\meta{offset}|,|\meta{length}|)| \\ % |l3kernel.filedump(|\meta{file}|,|\meta{offset}|,|\meta{length}|)| % \end{syntax} % Returns the uppercase hexadecimal representation of the content of the % \meta{file} read as bytes. If the \meta{length} is given, only this part % of the file is returned; similarly, one may specify the \meta{offset} from % the start of the file. If the \meta{length} is not given, the entire file % is read starting at the \meta{offset}. % \end{function} % % \begin{function}{ltx.utils.filemd5sum, l3kernel.filemdfivesum} % \begin{syntax} % \meta{hash}| = ltx.utils.filemd5sum(|\meta{file}|)| \\ % |l3kernel.filemdfivesum(|\meta{file}|)| % \end{syntax} % Returns the MD5 sum of the file contents read as bytes; note that % the result will depend on the nature of the line endings used in the file, % in contrast to normal \TeX{} behaviour. If the \meta{file} is not found, % nothing is returned with \emph{no error raised}. % \end{function} % % \begin{function}{ltx.utils.filemoddate, l3kernel.filemoddate} % \begin{syntax} % \meta{date}| = ltx.utils.filemoddate(|\meta{file}|)| \\ % |l3kernel.filemoddate(|\meta{file}|)| % \end{syntax} % Returns the date/time of last modification of the \meta{file} in the % format % \begin{quote} % |D:|\meta{year}\meta{month}\meta{day}\meta{hour}\meta{minute}^^A % \meta{second}\meta{offset} % \end{quote} % where the latter may be |Z| (UTC) or % \meta{plus-minus}\meta{hours}|'|\meta{minutes}|'|. If the \meta{file} is % not found, nothing is returned with \emph{no error raised}. % \end{function} % % \begin{function}{ltx.utils.filesize, l3kernel.filesize} % \begin{syntax} % |size = ltx.utils.filesize(|\meta{file}|)| \\ % |l3kernel.filesize(|\meta{file}|)| % \end{syntax} % Returns the size of the \meta{file} in bytes. If the \meta{file} is not % found, nothing is returned with \emph{no error raised}. % \end{function} % % \begin{function}{l3kernel.resettimer} % \begin{syntax} % |l3kernel.resettimer()| % \end{syntax} % Resets the timer used by |l3kernel.elapsetime|. % \end{function} % % \begin{function}{l3kernel.shellescape} % \begin{syntax} % |l3kernel.shellescape(|\meta{cmd}|)| % \end{syntax} % Executes the \meta{cmd} and prints to the log as for \pdfTeX{}. % \end{function} % % \begin{function}{l3kernel.strcmp} % \begin{syntax} % |l3kernel.strcmp(|\meta{str one}, \meta{str two}|)| % \end{syntax} % Compares the two strings and returns |0| to \TeX{} % if the two are identical. % \end{function} % % \end{documentation} % % \begin{implementation} % % \section{\pkg{l3luatex} implementation} % % \begin{macrocode} %<*package> % \end{macrocode} % % \subsection{Breaking out to \Lua{}} % % \begin{macrocode} %<*tex> % \end{macrocode} % % \begin{macrocode} %<@@=lua> % \end{macrocode} % % \begin{macro}[EXP]{\@@_escape:n, \@@_now:n, \@@_shipout:n} % Copies of primitives. % \begin{macrocode} \cs_new_eq:NN \@@_escape:n \tex_luaescapestring:D \cs_new_eq:NN \@@_now:n \tex_directlua:D \cs_new_eq:NN \@@_shipout:n \tex_latelua:D % \end{macrocode} % \end{macro} % % These functions are set up in \pkg{l3str} for bootstrapping: we want to % replace them with a \enquote{proper} version at this stage, so clean up. % \begin{macrocode} \cs_undefine:N \lua_escape:e \cs_undefine:N \lua_now:e % \end{macrocode} % % \begin{macro}[EXP]{\lua_now:n, \lua_now:e} % \begin{macro}{\lua_shipout_e:n, \lua_shipout:n} % \begin{macro}[EXP]{\lua_escape:n, \lua_escape:e} % Wrappers around the primitives. As with engines other than \LuaTeX{} % these have to be macros, we give them the same status in all cases. % When \LuaTeX{} is not in use, simply give an error message/ % \begin{macrocode} \cs_new:Npn \lua_now:e #1 { \@@_now:n {#1} } \cs_new:Npn \lua_now:n #1 { \lua_now:e { \exp_not:n {#1} } } \cs_new_protected:Npn \lua_shipout_e:n #1 { \@@_shipout:n {#1} } \cs_new_protected:Npn \lua_shipout:n #1 { \lua_shipout_e:n { \exp_not:n {#1} } } \cs_new:Npn \lua_escape:e #1 { \@@_escape:n {#1} } \cs_new:Npn \lua_escape:n #1 { \lua_escape:e { \exp_not:n {#1} } } \sys_if_engine_luatex:F { \clist_map_inline:nn { \lua_escape:n , \lua_escape:e , \lua_now:n , \lua_now:e } { \cs_set:Npn #1 ##1 { \msg_expandable_error:nnn { luatex } { luatex-required } { #1 } } } \clist_map_inline:nn { \lua_shipout_e:n , \lua_shipout:n } { \cs_set_protected:Npn #1 ##1 { \msg_error:nnn { luatex } { luatex-required } { #1 } } } } % \end{macrocode} % \end{macro} % \end{macro} % \end{macro} % % \subsection{Messages} % % \begin{macrocode} \msg_new:nnnn { luatex } { luatex-required } { LuaTeX~engine~not~in~use!~Ignoring~#1. } { The~feature~you~are~using~is~only~available~ with~the~LuaTeX~engine.~LaTeX3~ignored~'#1'. } % \end{macrocode} % % \begin{macrocode} % % \end{macrocode} % % \subsection{\Lua{} functions for internal use} % % \begin{macrocode} %<*lua> % \end{macrocode} % % Most of the emulation of \pdfTeX{} here is based heavily on Heiko Oberdiek's % \pkg{pdftexcmds} package. % % \begin{macro}{l3kernel} % \begin{macro}{ltx.utils} % Create a table for the kernel's own use. % \begin{macrocode} l3kernel = l3kernel or { } local l3kernel = l3kernel ltx = ltx or {utils={}} ltx.utils = ltx.utils or { } local ltxutils = ltx.utils % \end{macrocode} % \end{macro} % \end{macro} % % Local copies of global tables. % \begin{macrocode} local io = io local kpse = kpse local lfs = lfs local math = math local md5 = md5 local os = os local string = string local tex = tex local texio = texio local tonumber = tonumber % \end{macrocode} % % Local copies of standard functions. % \begin{macrocode} local abs = math.abs local byte = string.byte local floor = math.floor local format = string.format local gsub = string.gsub local lfs_attr = lfs.attributes local open = io.open local os_date = os.date local setcatcode = tex.setcatcode local sprint = tex.sprint local cprint = tex.cprint local write = tex.write local write_nl = texio.write_nl local utf8_char = utf8.char local scan_int = token.scan_int or token.scan_integer local scan_string = token.scan_string local scan_keyword = token.scan_keyword local put_next = token.put_next local true_tok = token.create'prg_return_true:' local false_tok = token.create'prg_return_false:' % \end{macrocode} % % \begin{macrocode} local function deprecated(table, name, func) table[name] = function(...) write_nl(format("Calling deprecated Lua function %s", name)) table[name] = func return func(...) end end % \end{macrocode % % Deal with Con\TeX{}t: doesn't use |kpse| library. % \begin{macrocode} local kpse_find = (resolvers and resolvers.findfile) or kpse.find_file % \end{macrocode} % % \begin{macro}[int]{escapehex} % An internal auxiliary to convert a string to the matching hex escape. % This works on a byte basis: extension to handled UTF-8 input is % covered in \pkg{pdftexcmds} but is not currently required here. % \begin{macrocode} local function escapehex(str) return (gsub(str, ".", function (ch) return format("%02X", byte(ch)) end)) end % \end{macrocode} % \end{macro} % % \begin{macro}{l3kernel.charcat} % Creating arbitrary chars using |tex.cprint|. % The alternative approach using |token.put_next(token.create(...))| % would be about 10\% slower. % \begin{macrocode} deprecated(l3kernel, 'charcat', function(charcode, catcode) cprint(catcode, utf8_char(charcode)) end) % \end{macrocode} % \end{macro} % % \begin{macro}{l3kernel.elapsedtime, l3kernel.resettimer} % Simple timing set up: give the result from the system clock in scaled % seconds. % \begin{macrocode} local os_clock = os.clock local base_clock_time = 0 local function elapsedtime() local val = (os_clock() - base_clock_time) * 65536 + 0.5 if val > 2147483647 then val = 2147483647 end write(format("%d",floor(val))) end l3kernel.elapsedtime = elapsedtime local function resettimer() base_clock_time = os_clock() end l3kernel.resettimer = resettimer % \end{macrocode} % \end{macro} % % \begin{macro}{ltx.utils.filedump} % \begin{macro}{l3kernel.filedump} % Similar comments here to the next function: read the file in binary mode % to avoid any line-end weirdness. % \begin{macrocode} local function filedump(name,offset,length) local file = kpse_find(name,"tex",true) if not file then return end local f = open(file,"rb") if not f then return end if offset and offset > 0 then f:seek("set", offset) end local data = f:read(length or 'a') f:close() return escapehex(data) end ltxutils.filedump = filedump deprecated(l3kernel, "filedump", function(name, offset, length) local dump = filedump(name, tonumber(offset), tonumber(length)) if dump then write(dump) end end) % \end{macrocode} % \end{macro} % \end{macro} % % \begin{macro}{md5.HEX} % Hash a string and return the hash in uppercase hexadecimal format. % In some engines, this is build-in. For traditional \LuaTeX{}, the conversion % to hexadecimal has to be done by us. % \begin{macrocode} local md5_HEX = md5.HEX if not md5_HEX then local md5_sum = md5.sum function md5_HEX(data) return escapehex(md5_sum(data)) end md5.HEX = md5_HEX end % \end{macrocode} % \end{macro} % \begin{macro}{ltx.utils.filemd5sum} % \begin{macro}{l3kernel.filemdfivesum} % Read an entire file and hash it: the hash function itself is a built-in. % As Lua is byte-based there is no work needed here in terms of UTF-8 % (see \pkg{pdftexcmds} and how it handles strings that have passed through % \LuaTeX{}). The file is read in binary mode so that no line ending % normalisation occurs. % \begin{macrocode} local function filemd5sum(name) local file = kpse_find(name, "tex", true) if not file then return end local f = open(file, "rb") if not f then return end local data = f:read("*a") f:close() return md5_HEX(data) end ltxutils.filemd5sum = filemd5sum deprecated(l3kernel, "filemdfivesum", function(name) local hash = filemd5sum(name) if hash then write(hash) end end) % \end{macrocode} % \end{macro} % \end{macro} % % \begin{macro}{ltx.utils.filemoddate} % \begin{macro}{l3kernel.filemoddate} % There are two cases: If the C standard library is C99 compliant, % we can use |%z| to get the timezone in almost the right format. % We only have to add primes and replace a zero or missing offset % with |Z|. % % Of course this would be boring, so Windows does things differently. % There we have to manually calculate the offset. % See procedure \texttt{makepdftime} in \texttt{utils.c} of % \pdfTeX{}. % \begin{macrocode} local filemoddate if os_date'%z':match'^[+-]%d%d%d%d$' then local pattern = lpeg.Cs(16 * (lpeg.Cg(lpeg.S'+-' * '0000' * lpeg.Cc'Z') + 3 * lpeg.Cc"'" * 2 * lpeg.Cc"'" + lpeg.Cc'Z') * -1) function filemoddate(name) local file = kpse_find(name, "tex", true) if not file then return end local date = lfs_attr(file, "modification") if not date then return end return pattern:match(os_date("D:%Y%m%d%H%M%S%z", date)) end else local function filemoddate(name) local file = kpse_find(name, "tex", true) if not file then return end local date = lfs_attr(file, "modification") if not date then return end local d = os_date("*t", date) local u = os_date("!*t", date) local off = 60 * (d.hour - u.hour) + d.min - u.min if d.year ~= u.year then if d.year > u.year then off = off + 1440 else off = off - 1440 end elseif d.yday ~= u.yday then if d.yday > u.yday then off = off + 1440 else off = off - 1440 end end local timezone if off == 0 then timezone = "Z" else if off < 0 then timezone = "-" off = -off else timezone = "+" end timezone = format("%s%02d'%02d'", timezone, hours // 60, hours % 60) end return format("D:%04d%02d%02d%02d%02d%02d%s", d.year, d.month, d.day, d.hour, d.min, d.sec, timezone) end end ltxutils.filemoddate = filemoddate deprecated(l3kernel, "filemoddate", function(name) local hash = filemoddate(name) if hash then write(hash) end end) % \end{macrocode} % \end{macro} % \end{macro} % % \begin{macro}{ltx.utils.filesize} % \begin{macro}{l3kernel.filesize} % A simple disk lookup. % \begin{macrocode} local function filesize(name) local file = kpse_find(name, "tex", true) if file then local size = lfs_attr(file, "size") if size then return size end end end ltxutils.filesize = filesize deprecated(l3kernel, "filesize", function(name) local size = filesize(name) if size then write(size) end end) % \end{macrocode} % \end{macro} % \end{macro} % % \begin{macro}{l3kernel.strcmp} % String comparison which gives the same results as \pdfTeX{}'s % \tn{pdfstrcmp}, although the ordering should likely not be relied upon! % \begin{macrocode} deprecated(l3kernel, "strcmp", function (A, B) if A == B then write("0") elseif A < B then write("-1") else write("1") end end) % \end{macrocode} % \end{macro} % % \begin{macro}{l3kernel.shellescape} % Replicating the \pdfTeX{} log interaction for shell escape. % \begin{macrocode} local os_exec = os.execute deprecated(l3kernel, "shellescape", function(cmd) local status,msg = os_exec(cmd) if status == nil then write_nl("log","runsystem(" .. cmd .. ")...(" .. msg .. ")\n") elseif status == 0 then write_nl("log","runsystem(" .. cmd .. ")...executed\n") else write_nl("log","runsystem(" .. cmd .. ")...failed " .. (msg or "") .. "\n") end end) % \end{macrocode} % \end{macro} % % \begin{macro}[int]{luadef} % An internal function for defining control sequences form Lua which behave % like primitives. This acts as a wrapper around |token.set_lua| which accepts % a function instead of an index into the functions table. % \begin{macrocode} local luacmd do local token_create = token.create local set_lua = token.set_lua local undefined_cs = token.command_id'undefined_cs' if not context and not luatexbase then require'ltluatex' end if luatexbase then local new_luafunction = luatexbase.new_luafunction local functions = lua.get_functions_table() function luacmd(name, func, ...) local id local tok = token_create(name) if tok.command == undefined_cs then id = new_luafunction(name) set_lua(name, id, ...) else id = tok.index or tok.mode end functions[id] = func end elseif context then local register = context.functions.register local functions = context.functions.known function luacmd(name, func, ...) local tok = token.create(name) if tok.command == undefined_cs then token.set_lua(name, register(func), ...) else functions[tok.index or tok.mode] = func end end end end % \end{macrocode} % \end{macro} % % \begin{macrocode} % % \end{macrocode} % % \begin{macrocode} % % \end{macrocode} % %\end{implementation} % %\PrintIndex