summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/l3kernel/l3file.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3file.dtx')
-rw-r--r--Master/texmf-dist/source/latex/l3kernel/l3file.dtx202
1 files changed, 200 insertions, 2 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3file.dtx b/Master/texmf-dist/source/latex/l3kernel/l3file.dtx
index 1788f805cc0..04144df0f70 100644
--- a/Master/texmf-dist/source/latex/l3kernel/l3file.dtx
+++ b/Master/texmf-dist/source/latex/l3kernel/l3file.dtx
@@ -44,7 +44,7 @@
% }^^A
% }
%
-% \date{Released 2019-04-21}
+% \date{Released 2019-05-03}
%
% \maketitle
%
@@ -439,7 +439,7 @@
% \subsection{Wrapping lines in output}
%
% \begin{function}[added = 2012-06-28, updated = 2017-12-04]
-% {\iow_wrap:nnnN \iow_wrap:nxnN}
+% {\iow_wrap:nnnN, \iow_wrap:nxnN}
% \begin{syntax}
% \cs{iow_wrap:nnnN} \Arg{text} \Arg{run-on text} \Arg{set up} \meta{function}
% \end{syntax}
@@ -655,6 +655,51 @@
% quote (|"|) characters or is surrounded by a pair of quotes.
% \end{function}
%
+% \begin{function}[noTF, added = 2017-07-11, updated = 2019-02-16]
+% {\file_get_mdfive_hash:nN}
+% \begin{syntax}
+% \cs{file_get_mdfive_hash:nN} \Arg{file name} \meta{tl var}
+% \end{syntax}
+% Searches for \meta{file name} using the current \TeX{} search
+% path and the additional paths controlled by \cs{l_file_search_path_seq}.
+% If found, sets the \meta{tl var} to the MD5 sum generated from the
+% content of the file. The file is read as bytes, which means that in
+% contrast to most \TeX{} behaviour there will be a difference in result
+% depending on the line endings used in text files. The same file will
+% produce the same result between different engines: the algorithm used
+% is the same in all cases.
+% Where the file is not found, the \meta{tl var} will set to
+% \cs{q_no_value}.
+% \end{function}
+%
+% \begin{function}[noTF, added = 2017-07-09, updated = 2019-02-16]
+% {\file_get_size:nN}
+% \begin{syntax}
+% \cs{file_get_size:nN} \Arg{file name} \meta{tl var}
+% \end{syntax}
+% Searches for \meta{file name} using the current \TeX{} search
+% path and the additional paths controlled by \cs{l_file_search_path_seq}.
+% If found, sets the \meta{tl var} to the size of the file in bytes.
+% Where the file is not found, the \meta{tl var} will set to \cs{q_no_value}.
+% This is not available in older versions of \XeTeX{}.
+% \end{function}
+%
+% \begin{function}[noTF, added = 2017-07-09, updated = 2019-02-16]
+% {\file_get_timestamp:nN}
+% \begin{syntax}
+% \cs{file_get_timestamp:nN} \Arg{file name} \meta{tl var}
+% \end{syntax}
+% Searches for \meta{file name} using the current \TeX{} search
+% path and the additional paths controlled by \cs{l_file_search_path_seq}.
+% If found, sets the \meta{tl var} to the modification timestamp of
+% the file in the form |D:|\meta{year}\meta{month}\meta{day}\meta{hour}^^A
+% \meta{minute}\meta{second}\meta{offset}, where the latter may be |Z|
+% (UTC) or \meta{plus-minus}\meta{hours}|'|\meta{minutes}|'|.
+% Where the file is not found, the \meta{tl var} will be set to
+% \cs{q_no_value}.
+% This is not available in older versions of \XeTeX{}.
+% \end{function}
+%
% \begin{function}[updated = 2017-06-26]{\file_input:n}
% \begin{syntax}
% \cs{file_input:n} \Arg{file name}
@@ -666,6 +711,41 @@
% function. An error is raised if the file is not found.
% \end{function}
%
+% \begin{function}[added = 2014-07-02]{\file_if_exist_input:n, \file_if_exist_input:nF}
+% \begin{syntax}
+% \cs{file_if_exist_input:n} \Arg{file name}
+% \cs{file_if_exist_input:nF} \Arg{file name} \Arg{false code}
+% \end{syntax}
+% Searches for \meta{file name} using the current \TeX{} search
+% path and the additional paths controlled by
+% \cs{file_path_include:n}. If found then
+% reads in the file as additional \LaTeX{} source as described for
+% \cs{file_input:n}, otherwise inserts the \meta{false code}.
+% Note that these functions do not raise
+% an error if the file is not found, in contrast to \cs{file_input:n}.
+% \end{function}
+%
+% \begin{function}[added = 2017-07-07]{\file_input_stop:}
+% \begin{syntax}
+% \cs{file_input_stop:}
+% \end{syntax}
+% Ends the reading of a file started by \cs{file_input:n} or similar before
+% the end of the file is reached. Where the file reading is being terminated
+% due to an error, \cs[index = msg_critical:nn]{msg_critical:nn(nn)}
+% should be preferred.
+% \begin{texnote}
+% This function must be used on a line on its own: \TeX{} reads files
+% line-by-line and so any additional tokens in the \enquote{current} line
+% will still be read.
+%
+% This is also true if the function is hidden inside another function
+% (which will be the normal case), i.e., all tokens on the same line
+% in the source file are still processed. Putting it on a line by itself
+% in the definition doesn't help as it is the line where it is used that
+% counts!
+% \end{texnote}
+% \end{function}
+%
% \begin{function}{\file_show_list:, \file_log_list:}
% \begin{syntax}
% \cs{file_show_list:}
@@ -2360,6 +2440,98 @@
% \end{macro}
% \end{macro}
%
+% \begin{macro}
+% {\file_get_mdfive_hash:nN, \file_get_size:nN, \file_get_timestamp:nN}
+% \begin{macro}{\@@_get_details:nnN}
+% These are all wrappers around the \pdfTeX{} primitives doing the same
+% jobs: as we want consistent file paths to be found, they are all set up
+% using \cs{file_get_full_name:nN} and so are non-expandable \texttt{get}
+% functions. Much of the code is repetitive but we need to branch for
+% \LuaTeX{} (emulation in Lua), for the slightly different syntax
+% needed for \tn{tex_mdfivesum:D} and for the fact that primitive
+% coverage varies in other engines.
+% \begin{macrocode}
+\cs_new_protected:Npn \file_get_mdfive_hash:nN #1#2
+ { \file_get_mdfive_hash:nNF {#1} #2 { \tl_set:Nn #2 { \q_no_value } } }
+\cs_new_protected:Npn \file_get_size:nN #1#2
+ { \file_get_size:nNF {#1} #2 { \tl_set:Nn #2 { \q_no_value } } }
+\cs_new_protected:Npn \file_get_timestamp:nN #1#2
+ { \file_get_timestamp:nNF {#1} #2 { \tl_set:Nn #2 { \q_no_value } } }
+\prg_new_protected_conditional:Npnn \file_get_mdfive_hash:nN #1#2 { T , F , TF }
+ { \@@_get_details:nnN {#1} { mdfivesum } {#2} }
+\prg_new_protected_conditional:Npnn \file_get_size:nN #1#2 { T , F , TF }
+ { \@@_get_details:nnN {#1} { size } {#2} }
+\prg_new_protected_conditional:Npnn \file_get_timestamp:nN #1#2 { T , F , TF }
+ { \@@_get_details:nnN {#1} { moddate } {#2} }
+\cs_new_protected:Npn \@@_get_details:nnN #1#2#3
+ {
+ \file_get_full_name:nNTF {#1} \l_@@_full_name_tl
+ {
+ \tl_set:Nx #3
+ {
+ \use:c { tex_file #2 :D } \exp_after:wN
+ { \l_@@_full_name_tl }
+ }
+ \prg_return_true:
+ }
+ { \prg_return_false: }
+ }
+\sys_if_engine_luatex:TF
+ {
+ \cs_set_protected:Npn \@@_get_details:nnN #1#2#3
+ {
+ \file_get_full_name:nNTF {#1} \l_@@_full_name_tl
+ {
+ \tl_set:Nx #3
+ {
+ \lua_now:e
+ {
+ l3kernel.file#2
+ ( " \lua_escape:e { \l_@@_full_name_tl } " )
+ }
+ }
+ \prg_return_true:
+ }
+ { \prg_return_false: }
+ }
+ }
+ {
+ \prg_set_protected_conditional:Npnn \file_get_mdfive_hash:nN #1#2
+ { T , F , TF }
+ {
+ \file_get_full_name:nNTF {#1} \l_@@_full_name_tl
+ {
+ \tl_set:Nx #2
+ {
+ \tex_mdfivesum:D file \exp_after:wN
+ { \l_@@_full_name_tl }
+ }
+ \prg_return_true:
+ }
+ { \prg_return_false: }
+ }
+ \cs_if_exist:NF \tex_filesize:D
+ {
+ \cs_set_protected:Npn \@@_get_details:nnN #1#2#3
+ {
+ \tl_clear:N #3
+ \__kernel_msg_error:nnx
+ { kernel } { primitive-not-available }
+ { \exp_not:c { (pdf)file #2 } }
+ \prg_return_false:
+ }
+ }
+ }
+\__kernel_msg_new:nnnn { kernel } { primitive-not-available }
+ { Primitive~\token_to_str:N #1 not~available }
+ {
+ The~version~of~XeTeX~in~use~does~not~provide~functionality~equivalent~to~
+ the~\token_to_str:N #1 primitive.
+ }
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
% \begin{macro}[TF]{\file_if_exist:n}
% The test for the existence of a file is a wrapper around the function to
% add a path to a file. If the file was found, the path contains
@@ -2375,6 +2547,32 @@
% \end{macrocode}
% \end{macro}
%
+% \begin{macro}{\file_if_exist_input:n, \file_if_exist_input:nF}
+% Input of a file with a test for existence. We do not define the |T|
+% or |TF| variants because the most useful place to place the
+% \meta{true code} would be inconsistent with other conditionals.
+% \begin{macrocode}
+\cs_new_protected:Npn \file_if_exist_input:n #1
+ {
+ \file_get_full_name:nNT {#1} \l_@@_full_name_tl
+ { \@@_input:V \l_@@_full_name_tl }
+ }
+\cs_new_protected:Npn \file_if_exist_input:nF #1#2
+ {
+ \file_get_full_name:nNTF {#1} \l_@@_full_name_tl
+ { \@@_input:V \l_@@_full_name_tl }
+ {#2}
+ }
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\file_input_stop:}
+% A simple rename.
+% \begin{macrocode}
+\cs_new_protected:Npn \file_input_stop: { \tex_endinput:D }
+% \end{macrocode}
+% \end{macro}
+%
% \begin{macro}{\__kernel_file_missing:n}
% An error message for a missing file, also used in \cs{ior_open:Nn}.
% \begin{macrocode}