diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3file.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex/l3kernel/l3file.dtx | 202 |
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} |