summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/l3kernel/l3file.dtx
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2023-12-12 03:00:44 +0000
committerNorbert Preining <norbert@preining.info>2023-12-12 03:00:44 +0000
commit20d530d28645a91e4362d87f1b7559a67cfd0e31 (patch)
tree7f82e96b8af3f57651baf0464c5bee8061e0b7f5 /macros/latex/contrib/l3kernel/l3file.dtx
parent2bc01316d114d0fb18dec7c0f6f7b0aba6c21d66 (diff)
CTAN sync 202312120300
Diffstat (limited to 'macros/latex/contrib/l3kernel/l3file.dtx')
-rw-r--r--macros/latex/contrib/l3kernel/l3file.dtx190
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}