diff options
author | Norbert Preining <norbert@preining.info> | 2023-12-12 03:00:44 +0000 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2023-12-12 03:00:44 +0000 |
commit | 20d530d28645a91e4362d87f1b7559a67cfd0e31 (patch) | |
tree | 7f82e96b8af3f57651baf0464c5bee8061e0b7f5 /macros/latex/contrib/l3kernel/l3file.dtx | |
parent | 2bc01316d114d0fb18dec7c0f6f7b0aba6c21d66 (diff) |
CTAN sync 202312120300
Diffstat (limited to 'macros/latex/contrib/l3kernel/l3file.dtx')
-rw-r--r-- | macros/latex/contrib/l3kernel/l3file.dtx | 190 |
1 files changed, 101 insertions, 89 deletions
diff --git a/macros/latex/contrib/l3kernel/l3file.dtx b/macros/latex/contrib/l3kernel/l3file.dtx index 8545a83947..d33fe899d8 100644 --- a/macros/latex/contrib/l3kernel/l3file.dtx +++ b/macros/latex/contrib/l3kernel/l3file.dtx @@ -44,7 +44,7 @@ % }^^A % } % -% \date{Released 2023-12-08} +% \date{Released 2023-12-11} % % \maketitle % @@ -673,7 +673,9 @@ % \end{texnote} % \end{function} % -% \section{File operation functions} +% \section{File opertions} +% +% \subsection{Basic file operations} % % \begin{variable}[added = 2017-06-21] % { @@ -722,94 +724,13 @@ % \cs{l_file_search_path_seq}. % \end{function} % -% \begin{function}[noTF, added = 2019-01-16, updated = 2019-02-16] -% {\file_get:nnN, \file_get:VnN} -% \begin{syntax} -% \cs{file_get:nnN} \Arg{file name} \Arg{setup} \meta{tl} -% \cs{file_get:nnNTF} \Arg{file name} \Arg{setup} \meta{tl} \Arg{true code} \Arg{false code} -% \end{syntax} -% Defines \meta{tl} to the contents of \meta{file name}. -% Category codes may need to be set appropriately via the \meta{setup} -% argument. -% The non-branching version sets the \meta{tl} to \cs{q_no_value} if the file is -% not found. The branching version runs the \meta{true code} after the -% assignment to \meta{tl} if the file is found, and \meta{false code} -% otherwise. -% \end{function} -% -% \begin{function}[noTF, updated = 2019-02-16] -% {\file_get_full_name:nN, \file_get_full_name:VN} -% \begin{syntax} -% \cs{file_get_full_name:nN} \Arg{file name} \meta{tl} -% \cs{file_get_full_name:nNTF} \Arg{file name} \meta{tl} \Arg{true code} \Arg{false code} -% \end{syntax} -% Searches for \meta{file name} in the path as detailed for -% \cs{file_if_exist:nTF}, and if found sets the \meta{tl var} the -% fully-qualified name of the file, \emph{i.e.}~the path and file name. -% This includes an extension |.tex| when the given \meta{file name} -% has no extension but the file found has that extension. -% In the non-branching version, the \meta{tl var} will be set to -% \cs{q_no_value} in the case that the file does not exist. -% \end{function} -% -% \begin{function}[added = 2019-09-03, rEXP]{\file_full_name:n, \file_full_name:V} -% \begin{syntax} -% \cs{file_full_name:n} \Arg{file name} -% \end{syntax} -% Searches for \meta{file name} in the path as detailed for -% \cs{file_if_exist:nTF}, and if found leaves the -% fully-qualified name of the file, \emph{i.e.}~the path and file name, -% in the input stream. -% This includes an extension |.tex| when the given \meta{file name} -% has no extension but the file found has that extension. -% If the file is not found on the path, the expansion is empty. -% \end{function} +% \subsection{Information about files and file contents} % -% \begin{function}[added = 2017-06-23, updated = 2020-06-24] -% {\file_parse_full_name:nNNN, \file_parse_full_name:VNNN} -% \begin{syntax} -% \cs{file_parse_full_name:nNNN} \Arg{full name} \meta{dir} \meta{name} \meta{ext} -% \end{syntax} -% Parses the \meta{full name} and splits it into three parts, each of -% which is returned by setting the appropriate local string variable: -% \begin{itemize} -% \item The \meta{dir}: everything up to the last |/| (path separator) -% in the \meta{file path}. As with system \texttt{PATH} variables -% and related functions, the \meta{dir} does \emph{not} include the -% trailing |/| unless it points to the root directory. If there is no path (only -% a file name), \meta{dir} is empty. -% \item The \meta{name}: everything after the last |/| up to the last |.|, -% where both of those characters are optional. The \meta{name} may -% contain multiple |.| characters. It is empty if \meta{full name} -% consists only of a directory name. -% \item The \meta{ext}: everything after the last |.| (including the dot). -% The \meta{ext} is empty if there is no |.| after the last |/|. -% \end{itemize} -% -% Before parsing, the \meta{full name} is expanded until only non-expandable -% tokens remain, except that active characters are also not expanded. -% Quotes (|"|) are invalid in file names and are discarded from the input. -% \end{function} -% -% \begin{function}[EXP, added = 2020-06-24] -% {\file_parse_full_name:n, \file_parse_full_name:V} -% \begin{syntax} -% \cs{file_parse_full_name:n} \Arg{full name} -% \end{syntax} -% Parses the \meta{full name} as described for \cs{file_parse_full_name:nNNN}, -% and leaves \meta{dir}, \meta{name}, and \meta{ext} in the input stream, -% each inside a pair of braces. -% \end{function} -% -% \begin{function}[EXP, added = 2020-06-24] -% {\file_parse_full_name_apply:nN, \file_parse_full_name_apply:VN} -% \begin{syntax} -% \cs{file_parse_full_name_apply:nN} \Arg{full name} \meta{function} -% \end{syntax} -% Parses the \meta{full name} as described for \cs{file_parse_full_name:nNNN}, -% and passes \meta{dir}, \meta{name}, and \meta{ext} as arguments to \meta{function}, -% as an \texttt{n}-type argument each, in this order. -% \end{function} +% Functions in this section return information about files as \pkg{expl3} +% \texttt{str} data, \emph{except} that the non-expandable functions set their +% return \emph{token list} to \cs{q_no_value} if the file requested is not +% found. As such, comparison of file names, hashes, sizes, etc., should use +% \cs{str_if_eq:nnTF} rather than \cs{tl_if_eq:nnTF} and so on. % % \begin{function}[rEXP, added = 2019-11-19] % { @@ -947,6 +868,97 @@ % This is not available in older versions of \XeTeX{}. % \end{function} % +% \begin{function}[noTF, updated = 2019-02-16] +% {\file_get_full_name:nN, \file_get_full_name:VN} +% \begin{syntax} +% \cs{file_get_full_name:nN} \Arg{file name} \meta{tl} +% \cs{file_get_full_name:nNTF} \Arg{file name} \meta{tl} \Arg{true code} \Arg{false code} +% \end{syntax} +% Searches for \meta{file name} in the path as detailed for +% \cs{file_if_exist:nTF}, and if found sets the \meta{tl var} the +% fully-qualified name of the file, \emph{i.e.}~the path and file name. +% This includes an extension |.tex| when the given \meta{file name} +% has no extension but the file found has that extension. +% In the non-branching version, the \meta{tl var} will be set to +% \cs{q_no_value} in the case that the file does not exist. +% \end{function} +% +% \begin{function}[added = 2019-09-03, rEXP]{\file_full_name:n, \file_full_name:V} +% \begin{syntax} +% \cs{file_full_name:n} \Arg{file name} +% \end{syntax} +% Searches for \meta{file name} in the path as detailed for +% \cs{file_if_exist:nTF}, and if found leaves the +% fully-qualified name of the file, \emph{i.e.}~the path and file name, +% in the input stream. +% This includes an extension |.tex| when the given \meta{file name} +% has no extension but the file found has that extension. +% If the file is not found on the path, the expansion is empty. +% \end{function} +% +% \begin{function}[added = 2017-06-23, updated = 2020-06-24] +% {\file_parse_full_name:nNNN, \file_parse_full_name:VNNN} +% \begin{syntax} +% \cs{file_parse_full_name:nNNN} \Arg{full name} \meta{dir} \meta{name} \meta{ext} +% \end{syntax} +% Parses the \meta{full name} and splits it into three parts, each of +% which is returned by setting the appropriate local string variable: +% \begin{itemize} +% \item The \meta{dir}: everything up to the last |/| (path separator) +% in the \meta{file path}. As with system \texttt{PATH} variables +% and related functions, the \meta{dir} does \emph{not} include the +% trailing |/| unless it points to the root directory. If there is no path (only +% a file name), \meta{dir} is empty. +% \item The \meta{name}: everything after the last |/| up to the last |.|, +% where both of those characters are optional. The \meta{name} may +% contain multiple |.| characters. It is empty if \meta{full name} +% consists only of a directory name. +% \item The \meta{ext}: everything after the last |.| (including the dot). +% The \meta{ext} is empty if there is no |.| after the last |/|. +% \end{itemize} +% +% Before parsing, the \meta{full name} is expanded until only non-expandable +% tokens remain, except that active characters are also not expanded. +% Quotes (|"|) are invalid in file names and are discarded from the input. +% \end{function} +% +% \begin{function}[EXP, added = 2020-06-24] +% {\file_parse_full_name:n, \file_parse_full_name:V} +% \begin{syntax} +% \cs{file_parse_full_name:n} \Arg{full name} +% \end{syntax} +% Parses the \meta{full name} as described for \cs{file_parse_full_name:nNNN}, +% and leaves \meta{dir}, \meta{name}, and \meta{ext} in the input stream, +% each inside a pair of braces. +% \end{function} +% +% \begin{function}[EXP, added = 2020-06-24] +% {\file_parse_full_name_apply:nN, \file_parse_full_name_apply:VN} +% \begin{syntax} +% \cs{file_parse_full_name_apply:nN} \Arg{full name} \meta{function} +% \end{syntax} +% Parses the \meta{full name} as described for \cs{file_parse_full_name:nNNN}, +% and passes \meta{dir}, \meta{name}, and \meta{ext} as arguments to \meta{function}, +% as an \texttt{n}-type argument each, in this order. +% \end{function} +% +% \subsection{Accessing file contents} +% +% \begin{function}[noTF, added = 2019-01-16, updated = 2019-02-16] +% {\file_get:nnN, \file_get:VnN} +% \begin{syntax} +% \cs{file_get:nnN} \Arg{file name} \Arg{setup} \meta{tl} +% \cs{file_get:nnNTF} \Arg{file name} \Arg{setup} \meta{tl} \Arg{true code} \Arg{false code} +% \end{syntax} +% Defines \meta{tl} to the contents of \meta{file name}. +% Category codes may need to be set appropriately via the \meta{setup} +% argument. +% The non-branching version sets the \meta{tl} to \cs{q_no_value} if the file is +% not found. The branching version runs the \meta{true code} after the +% assignment to \meta{tl} if the file is found, and \meta{false code} +% otherwise. The file content will be tokenized using the current +% category code régime, +% \end{function} % % \begin{function}[updated = 2017-06-26]{\file_input:n, \file_input:V} % \begin{syntax} |