Add \expandableinput

latex3 · Feb 26, 2025 · c913848 · c913848
1 parent f9b36cc
commit c913848
Show file tree

Hide file tree

Showing 4 changed files with 56 additions and 2 deletions.
diff --git a/base/changes.txt b/base/changes.txt
@@ -6,6 +6,10 @@ to completeness or accuracy and it contains some references to files that are
 not part of the distribution.
 ================================================================================
 
+2025-01-26  Joseph Wright  <[email protected]>
+	* ltexpl.dtx, usrguide.tex
+	Add \expandableinput
+
 2025-02-21 Ulrike Fischer <[email protected]>
 	* lttagging.dtx: move declaration of marginpar sockets from latex-lab into lttagging.
 

diff --git a/base/doc/ltnews41.tex b/base/doc/ltnews41.tex
@@ -545,6 +545,20 @@ \subsection{Improving the handling of \cs{label}, \cs{index}, and \cs{glossary}}
 %
 \githubissue{311}
 
+\subsection{A version of \cs{input} for expansion contexts}
+
+The \LaTeX{} definition of \cs{input} cannot be used in places where \TeX{} is
+performing expansion: the classic example is at the start of a tabular cell.
+There are a number of reasons for this: the key ones are that \cs{input}
+records which files are read and provides pre- and post-file hooks.
+
+To support the need to carry out file input in expansion contexts, we have now
+added \cs{expandableinput}: this skips recording the file name and any file
+hooks, but otherwise behaves like \cs{input}. In particular, it sill uses
+\cs{input@path} when doing file lookup (contrasting with the \TeX{} primitive,
+saved in \LaTeX as \cs{@@input}).
+%
+\githubissue{514}
 
 \section{Bug fixes}
 

diff --git a/base/doc/usrguide.tex b/base/doc/usrguide.tex
@@ -43,7 +43,7 @@
     \texttt{usrguide.tex} for full details.}%
 }
 
-\date{2025-02-01}
+\date{2025-02-26}
 
 \NewDocumentCommand\cs{m}{\texttt{\textbackslash\detokenize{#1}}}
 \NewDocumentCommand\marg{m}{\arg{#1}}
@@ -1312,6 +1312,21 @@ \section{Expandable floating point (and other) calculations}
 the values \cs{topskip} (\dimeval{\topskip}) and \cs{baselineskip}
 (\dimeval{\baselineskip}) in the current document.
 
+\section{Expandable \cs{input} equivalent}
+
+\begin{decl}
+  |\expandableinput| \arg{filename} \\
+\end{decl}
+The \LaTeX{} definition of \cs{input} cannot be used in places where \TeX{} is
+performing expansion: the classic example is at the start of a tabular cell.
+There are a number of reasons for this: the key ones are that \cs{input}
+records which files are read and provides pre- and post-file hooks.
+
+To support the need to carry out file input in expansion contexts, the command
+\cs{expandableinput} is available: this skips recording the file name and any
+file hooks, but otherwise behaves like \cs{input}. In particular, it sill uses
+\cs{input@path} when doing file lookup.
+
 \section{Case changing}
 
 \begin{decl}

diff --git a/base/ltexpl.dtx b/base/ltexpl.dtx
@@ -33,7 +33,7 @@
 %<*driver>
 % \fi
 \ProvidesFile{ltexpl.dtx}
-             [2024/04/17 v1.3h LaTeX Kernel (expl3-dependent code)]
+             [2025/02/26 v1.3i LaTeX Kernel (expl3-dependent code)]
 % \iffalse
 \documentclass{ltxdoc}
 \GetFileInfo{ltexpl.dtx}
@@ -549,4 +549,25 @@
 %<latexrelease>\EndIncludeInRelease
 %    \end{macrocode}
 %
+% \begin{macro}{\expandableinput}
+% \changes{v1.3i}{2025/02/26}{Added document level name for \cs{file_input_raw:n} (gh/514)}
+%    \begin{macrocode}
+%<*2ekernel|latexrelease>
+%<latexrelease>\IncludeInRelease{2025/06/01}%
+%<latexrelease>                 {\expandableinput}{Expandable input}%
+\ExplSyntaxOn
+\cs_new_eq:NN \expandableinput \file_input_raw:n
+%    \end{macrocode}
+% \end{macro}
+%
+%    \begin{macrocode}
+%</2ekernel|latexrelease>
+%<latexrelease>\EndIncludeInRelease
+%<latexrelease>\IncludeInRelease{0000/00/00}%
+%<latexrelease>                 {\expandableinput}{Expandable input}%
+%<latexrelease>
+%<latexrelease>\let\expandableinput\@undefined
+%<latexrelease>\EndIncludeInRelease
+%    \end{macrocode}
+%
 % \Finale