[latex3-commits] [latex3/l3sys-query] main: Document wildcard handling details (aa5c393)

[github at latex-project.org]

Repository : https://github.com/latex3/l3sys-query
On branch  : main
Link       : https://github.com/latex3/l3sys-query/commit/aa5c3938436f08bf469e9506b9bd4d1398a57805

>---------------------------------------------------------------

commit aa5c3938436f08bf469e9506b9bd4d1398a57805
Author: Joseph Wright <joseph at texdev.net>
Date:   Fri Mar 8 09:33:18 2024 +0000

    Document wildcard handling details


>---------------------------------------------------------------

aa5c3938436f08bf469e9506b9bd4d1398a57805
 l3sys-query.tex | 64 +++++++++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 58 insertions(+), 6 deletions(-)

diff --git a/l3sys-query.tex b/l3sys-query.tex
index b3dd690..9f0bdf7 100644
--- a/l3sys-query.tex
+++ b/l3sys-query.tex
@@ -130,14 +130,15 @@ order of results will be determined by the underlying operating system process:
 unless requested \emph{via} an option, no sorting takes place.
 
 As standard, the \meta{args} are treated as a file/path name potentially
-including |?| and |*| as wildcards, for example |*.png| or |file?.txt|. To
-prevent wildcards from being expanded at the wrong time, they should always be
-surround by |'| characters,\footnote{On Windows, the shell does not expand
-wildcards, but \texttt{texlua} does: using \texttt{'} is a platform-neutral way
-to avoid any expansion.} for example
+including |?| and |*| as wildcards, for example |*.png| or |file?.txt|.
 \begin{verbatim}
   l3sys-query ls '*.png'
 \end{verbatim}
+Some care is needed in preventing expansion of such wildcards by the shell or
+\texttt{texlua} process: these are detailed in Section~\ref{sec:wildcard}. In
+this section, |'| is used to indicate a character being used to suppress
+expansion: this is for example normal on macOS and Linux.
+
 Removal of entries from the listing can be achieved using the |--exclude|
 option, which should be given with a \meta{xarg}, for example
 \begin{verbatim}
@@ -200,7 +201,58 @@ main file, assuming a command such as
 \end{verbatim}
 The \texttt{pwd} command is unaffected by any options.
 
-\section{The \LaTeX{} interface}
+\section{Wildcard expansion handling\label{sec:wildcard}}
+
+The handling of wildcards needs some further comment for those using
+\texttt{l3sys-query} from the command line: the \pkg{expl3} interface described
+in Section~\ref{sec:expl3} handles this aspect automatically for the user.
+
+\subsection{Shell use}
+
+On macOS and Linux, the shell normally expands globs, which include the
+wildcards |*| and |?|, before passing arguments to the appropriate command. This
+can be suppressed by surrounding the argument with |'| characters, hence the
+formulation
+\begin{verbatim}
+  l3sys-query ls '*.png'
+\end{verbatim}
+earlier.
+
+On Windows, the shell does no expansion, and thus arguments are passed as-is to
+the relevant command. However, in the \TeX{}~Live implementation of
+\texttt{texlua}, the script interpreter expands |*| and |?| \emph{before} they
+are made available to the script itself. This can only be suppressed by
+including one or more characters that prevent a match: this causes the
+\emph{entire} argument to be passed to the script, including whatever
+\enquote{extra} characters are used. Importantly, |'| has no special meaning
+here.
+
+To allow quoting of wildcards from the shell in a platform-neutral manner,
+\texttt{l3sys-query} will strip exactly one set of |'| characters around
+each argument before further processing.
+
+\subsection{Calls \emph{via} restricted shell escape}
+
+Restricted shell escape prevents shell expansion of wildcards entirely, but
+also strips out all |'| characters from arguments. Thus on macOS and
+Linux, a \TeX{} call such as
+\begin{verbatim}
+  \input|"l3sys-query ls '*.png'"
+\end{verbatim}
+will work as it is converted to one without the |'| characters (the surrounding
+|"| are needed to allow space-separated arguments to be passed as a whole to
+|\input|).
+
+On Windows, the rules of restricted shell escape mean that |'| cannot be
+used here to prevent expansion of |*| and |?|. Rather, the character |:|
+should be used: this is reserved on Windows in any case. Thus one would use
+\begin{verbatim}
+  \input|"l3sys-query ls :*.png:"
+\end{verbatim}
+on Windows; \texttt{l3sys-query} and strips out exactly one set of surrounding
+|:| characters.
+
+\section{The \LaTeX{} interface\label{sec:expl3}}
 
 Using \texttt{l3sys-query} is not tied to access \emph{via} \pkg{expl3}, but
 this is the preferred approach for the \LaTeX{} Team. Details of how to use