summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/l3kernel/l3luatex.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3luatex.dtx')
-rw-r--r--Master/texmf-dist/source/latex/l3kernel/l3luatex.dtx230
1 files changed, 192 insertions, 38 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3luatex.dtx b/Master/texmf-dist/source/latex/l3kernel/l3luatex.dtx
index b83cc86cde1..80ec22a2e2a 100644
--- a/Master/texmf-dist/source/latex/l3kernel/l3luatex.dtx
+++ b/Master/texmf-dist/source/latex/l3kernel/l3luatex.dtx
@@ -41,7 +41,7 @@
% }^^A
% }
%
-% \date{Released 2017/05/29}
+% \date{Released 2017/07/15}
%
% \maketitle
%
@@ -52,9 +52,9 @@
% 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{} or \XeTeX{} these will raise an
-% error: use \cs{sys_if_engine_luatex:T} to avoid this. Details of coding
-% the \LuaTeX{} engine are detailed in the \LuaTeX{} manual.
+% available. When used with \pdfTeX{} 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.
%
% \subsection{\TeX{} code interfaces}
%
@@ -62,12 +62,12 @@
% \begin{syntax}
% \cs{lua_now:n} \Arg{token list}
% \end{syntax}
-% The \meta{token list} is first tokenized by \TeX{}, which will include
+% 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 will execute the \meta{\Lua{} input} immediately,
+% The \Lua{} interpreter executes the \meta{\Lua{} input} immediately,
% and in an expandable manner.
%
% In the case of the \cs{lua_now_x:n} version the input is fully expanded
@@ -75,7 +75,7 @@
% fully expandable.
% \begin{texnote}
% \cs{lua_now_x:n} is a macro wrapper around \tn{directlua}: when
-% \LuaTeX{} is in use two expansions will be required to yield the
+% \LuaTeX{} is in use two expansions are required to yield the
% result of the \Lua{} code.
% \end{texnote}
% \end{function}
@@ -84,7 +84,7 @@
% \begin{syntax}
% \cs{lua_shipout:n} \Arg{token list}
% \end{syntax}
-% The \meta{token list} is first tokenized by \TeX{}, which will include
+% 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
@@ -118,7 +118,7 @@
% fully expandable.
% \begin{texnote}
% \cs{lua_escape_x:n} is a macro wrapper around \tn{luaescapestring}:
-% when \LuaTeX{} is in use two expansions will be required to yield the
+% when \LuaTeX{} is in use two expansions are required to yield the
% result of the \Lua{} code.
% \end{texnote}
% \end{function}
@@ -128,14 +128,6 @@
% As well as interfaces for \TeX{}, there are a small number of Lua functions
% provided here. Currently these are intended for internal use only.
%
-% \begin{function}{l3kernel.strcmp}
-% \begin{syntax}
-% \cs{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}
-%
% \begin{function}{l3kernel.charcat}
% \begin{syntax}
% \cs{l3kernel.charcat}|(|\meta{charcode}, \meta{catcode}|)|
@@ -144,6 +136,41 @@
% the result to \TeX{}.
% \end{function}
%
+% \begin{function}{l3kernel.filemdfivesum}
+% \begin{syntax}
+% \cs{l3kernel.filemdfivesum}|(|\meta{file}|)|
+% \end{syntax}
+% Returns the of the MD5 sum of the file contents read as bytes. If the
+% \meta{file} is not found, nothing is returned with \emph{no error raised}.
+% \end{function}
+%
+% \begin{function}{l3kernel.filemoddate}
+% \begin{syntax}
+% \cs{l3kernel.filemoddate}|(|\meta{file}|)|
+% \end{syntax}
+% Returns the of the date/time of last modification of the \meta{file} in the
+% format |D:|\meta{year}\meta{month}\meta{day}\meta{hour}\meta{minute}^^A
+% \meta{second}\meta{offset}, 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}{l3kernel.filesize}
+% \begin{syntax}
+% \cs{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.strcmp}
+% \begin{syntax}
+% \cs{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}
@@ -221,6 +248,9 @@
%<*lua>
% \end{macrocode}
%
+% Most of the emulation of \pdfTeX{} here is based heavily on Heiko Oberdiek's
+% \pkg{pdftexcmds} package.
+%
% \begin{macro}[int]{l3kernel}
% Create a table for the kernel's own use.
% \begin{macrocode}
@@ -228,29 +258,47 @@ l3kernel = l3kernel or { }
% \end{macrocode}
% \end{macro}
%
-% Various local copies of standard functions: naming convention is to retain
-% the full text but replace all |.| by |_|.
+% Local copies of global tables.
% \begin{macrocode}
-local tex_setcatcode = tex.setcatcode
-local tex_sprint = tex.sprint
-local tex_write = tex.write
-local unicode_utf8_char = unicode.utf8.char
+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 unicode = unicode
% \end{macrocode}
%
-% \begin{macro}[int]{l3kernel.strcmp}
-% String comparison which gives the same results as \pdfTeX{}'s
-% \tn{pdfstrcmp}, although the ordering should likely not be relied upon!
+% Local copies of standard functions.
% \begin{macrocode}
-local function strcmp (A, B)
- if A == B then
- tex_write("0")
- elseif A < B then
- tex_write("-1")
- else
- tex_write("1")
- end
+local abs = math.abs
+local byte = string.byte
+local floor = math.floor
+local format = string.format
+local gsub = string.gsub
+local kpse_find = kpse.find_file
+local lfs_attr = lfs.attributes
+local md5_sum = md5.sum
+local open = io.open
+local os_date = os.date
+local setcatcode = tex.setcatcode
+local str_format = string.format
+local sprint = tex.sprint
+local write = tex.write
+local utf8_char = unicode.utf8.char
+% \end{macrocode}
+%
+% \begin{macro}[aux]{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)
+ write((gsub(str, ".",
+ function (ch) return format("%02X", byte(ch)) end)))
end
-l3kernel.strcmp = strcmp
% \end{macrocode}
% \end{macro}
%
@@ -261,14 +309,120 @@ l3kernel.strcmp = strcmp
% to match an eventual allocator.
% \begin{macrocode}
local charcat_table = l3kernel.charcat_table or 1
-local function charcat (charcode, catcode)
- tex_setcatcode(charcat_table, charcode, catcode)
- tex_sprint(charcat_table, unicode_utf8_char(charcode))
+local function charcat(charcode, catcode)
+ setcatcode(charcat_table, charcode, catcode)
+ sprint(charcat_table, utf8_char(charcode))
end
l3kernel.charcat = charcat
% \end{macrocode}
% \end{macro}
%
+% \begin{macro}[int]{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{}).
+% \begin{macrocode}
+local function filemdfivesum(name)
+ local file = kpse_find(name, "tex", true)
+ if file then
+ local f = open(file, "r")
+ if f then
+ local data = f:read("*a")
+ escapehex(md5_sum(data))
+ f:close()
+ end
+ end
+end
+l3kernel.filemdfivesum = filemdfivesum
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}[int]{l3kernel.filemoddate}
+% See procedure \texttt{makepdftime} in \texttt{utils.c} of
+% \pdfTeX{}.
+% \begin{macrocode}
+local function filemoddate(name)
+ local file = kpse_find(name, "tex", true)
+ if file then
+ local date = lfs_attr(file, "modification")
+ if date then
+ local d = os_date("*t", date)
+ if d.sec >= 60 then
+ d.sec = 59
+ end
+ 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
+ local hours = floor(off / 60)
+ local mins = abs(off - hours * 60)
+ timezone = str_format("%+03d", hours)
+ .. "'" .. str_format("%02d", mins) .. "'"
+ end
+ write("D:"
+ .. str_format("%04d", d.year)
+ .. str_format("%02d", d.month)
+ .. str_format("%02d", d.day)
+ .. str_format("%02d", d.hour)
+ .. str_format("%02d", d.min)
+ .. str_format("%02d", d.sec)
+ .. timezone)
+ end
+ end
+end
+l3kernel.filemoddate = filemoddate
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}[int]{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
+ write(size)
+ end
+ end
+end
+l3kernel.filesize = filesize
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}[int]{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}
+local function strcmp(A, B)
+ if A == B then
+ write("0")
+ elseif A < B then
+ write("-1")
+ else
+ write("1")
+ end
+end
+l3kernel.strcmp = strcmp
+% \end{macrocode}
+% \end{macro}
+%
% \subsection{Generic \Lua{} and font support}
%
% \begin{macrocode}