[latex3-commits] [latex3/latex3] l3sys-query: Add macro interface for l3sys-query (2b6ead393)

github at latex-project.org github at latex-project.org
Sun Mar 10 12:28:01 CET 2024


Repository : https://github.com/latex3/latex3
On branch  : l3sys-query
Link       : https://github.com/latex3/latex3/commit/2b6ead3932400889f2fc4142a1f7c9cd7ff9b88d

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

commit 2b6ead3932400889f2fc4142a1f7c9cd7ff9b88d
Author: Joseph Wright <joseph at texdev.net>
Date:   Wed Mar 6 13:26:44 2024 +0000

    Add macro interface for l3sys-query


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

2b6ead3932400889f2fc4142a1f7c9cd7ff9b88d
 l3experimental/l3sys-shell/l3sys-shell.dtx         |   3 +-
 .../l3sys-shell/testfiles/m3sys-shell001.tlg       |   1 -
 l3kernel/CHANGELOG.md                              |   3 +
 l3kernel/l3sys.dtx                                 | 145 +++++++++++++++++++++
 l3kernel/testfiles/m3expl001.ptex.tlg              |   1 -
 l3kernel/testfiles/m3expl001.uptex.tlg             |   1 -
 l3kernel/testfiles/m3expl003.ptex.tlg              |   1 -
 l3kernel/testfiles/m3expl003.uptex.tlg             |   1 -
 8 files changed, 149 insertions(+), 7 deletions(-)

diff --git a/l3experimental/l3sys-shell/l3sys-shell.dtx b/l3experimental/l3sys-shell/l3sys-shell.dtx
index 186a03d87..d308208d7 100644
--- a/l3experimental/l3sys-shell/l3sys-shell.dtx
+++ b/l3experimental/l3sys-shell/l3sys-shell.dtx
@@ -329,11 +329,10 @@
 %    \end{macrocode}
 % \end{macro}
 %
-% \begin{variable}{\l_@@_tmp_seq, \l_@@_tmp_tl}
+% \begin{variable}{\l_@@_tmp_seq}
 %   Scratch space.
 %    \begin{macrocode}
 \seq_new:N \l_@@_tmp_seq
-\tl_new:N \l_@@_tmp_tl
 %    \end{macrocode}
 % \end{variable}
 %
diff --git a/l3experimental/l3sys-shell/testfiles/m3sys-shell001.tlg b/l3experimental/l3sys-shell/testfiles/m3sys-shell001.tlg
index 8794e21ff..94b57cfc8 100644
--- a/l3experimental/l3sys-shell/testfiles/m3sys-shell001.tlg
+++ b/l3experimental/l3sys-shell/testfiles/m3sys-shell001.tlg
@@ -18,7 +18,6 @@ Defining \sys_shell_mv:nn on line ...
 Defining \sys_shell_rm:n on line ...
 Defining \sys_shell_rmdir:n on line ...
 Defining \l__sys_tmp_seq on line ...
-Defining \l__sys_tmp_tl on line ...
 Defining \sys_get_shell_pwd:N on line ...
 Defining \sys_shell_split_ls:nN on line ...
 )
diff --git a/l3kernel/CHANGELOG.md b/l3kernel/CHANGELOG.md
index ba3ccfe71..3827dbf79 100644
--- a/l3kernel/CHANGELOG.md
+++ b/l3kernel/CHANGELOG.md
@@ -7,6 +7,9 @@ this project uses date-based 'snapshot' version identifiers.
 
 ## [Unreleased]
 
+### Added
+- Macro interface for `l3sys-query`
+
 ### Changed
 - Require that `expl3` is loaded at top level in generic mode
 
diff --git a/l3kernel/l3sys.dtx b/l3kernel/l3sys.dtx
index 9a0fb8dcf..aece8bf85 100644
--- a/l3kernel/l3sys.dtx
+++ b/l3kernel/l3sys.dtx
@@ -324,6 +324,54 @@
 %   Execute \meta{tokens} through shell escape at shipout.
 % \end{function}
 %
+% \section{System queries}
+%
+% Some queries can be made about the file system, etc., without needing to
+% use unrestricted shell escape. This is carried out using the script
+% \texttt{l3sys-query}, which is documented separately. The wrappers here
+% use this script, if available, to obtain system information that is
+% not directly available within the \TeX{} run. Note that if restricted
+% shell escape is disabled, no results can be obtained.
+%
+% \begin{function}[added = 2024-03-08]
+%   {\sys_get_query:nN, \sys_get_query:nnN, \sys_get_query:nnnN}
+%   \begin{syntax}
+%     \cs{sys_get_query:nN} \Arg{cmd} \Arg{tl var}
+%     \cs{sys_get_query:nnN} \Arg{cmd} \Arg{spec} \Arg{tl var}
+%     \cs{sys_get_query:nnnN} \Arg{cmd} \Arg{options} \Arg{spec} \Arg{tl var}
+%   \end{syntax}
+%   Sets the \meta{tl var} to the information returned by the
+%   \texttt{l3sys-query} \meta{cmd}, potentially supplying the \meta{options}
+%   and \meta{spec} to the query call. The valid \meta{cmd} names are at present
+%   \begin{itemize}
+%     \item \texttt{pwd} Returns the present working directory
+%     \item \texttt{ls} Returns a directory listing, using the \meta{spec} to
+%       select files and applying the \meta{options} if given
+%   \end{itemize}
+%   The \meta{spec} should be a file glob and will automatically be passed to
+%   the script without shell expansion. In a glob is needed within the
+%   \meta{options}, this will need to be protected from shell expansion
+%   using |'| tokens.
+%
+%   If more than one line of text is returned by the \meta{cmd}, these will be
+%   separated by character~13 (|^^M|) tokens of category code~12. In most
+%   cases, \cs{sys_split_query:nnnN} should be preferred when multi-line
+%   output is expected.
+% \end{function}
+%
+% \begin{function}[added = 2024-03-08]
+%   {\sys_split_query:nN, \sys_split_query:nnN, \sys_split_query:nnnN}
+%   \begin{syntax}
+%     \cs{sys_split_query:nN} \Arg{cmd} \Arg{seq}
+%     \cs{sys_split_query:nnN} \Arg{cmd} \Arg{spec} \Arg{seq}
+%     \cs{sys_split_query:nnnN} \Arg{cmd} \Arg{options} \Arg{spec} \Arg{seq}
+%   \end{syntax}
+%   Works as described for \cs{sys_split_query:nnnN}, but sets the \meta{seq}
+%   to contain one entry for each line returned by \texttt{l3sys-query}.
+%   This function should therefore be preferred where multi-line return is
+%   expected, e.g.~for the \texttt{ls} command.
+% \end{function}
+%
 % \section{Loading configuration data}
 %
 % \begin{function}[added = 2019-09-12]{\sys_load_backend:n}
@@ -390,6 +438,12 @@
 %<*tex>
 %    \end{macrocode}
 %
+% \begin{macro}{\l_@@_tmp_tl}
+%    \begin{macrocode}
+\tl_new:N \l_@@_tmp_tl
+%    \end{macrocode}
+% \end{macro}
+%
 % \subsubsection{Detecting the engine}
 %
 % \begin{macro}{\@@_const:nn}
@@ -1083,6 +1137,97 @@ end
 %    \end{macrocode}
 % \end{macro}
 %
+% \subsection{System queries}
+%
+% \begin{macro}{\sys_get_query:nN}
+% \begin{macro}{\sys_get_query:nnN}
+% \begin{macro}{\sys_get_query:nnnN, \@@_get_query:nnnN, \@@_get_query:neeN}
+%   Calling the query system is quite straight-forward: most of the effort is
+%   in making the read-back catcode-safe. We also want to trim off the trailing
+%   |^^M| from the last line.
+%    \begin{macrocode}
+\cs_new_protected:Npn \sys_get_query:nN #1#2
+  { \sys_query:nnnN {#1} { } { } #2 }
+\cs_new_protected:Npn \sys_get_query:nnN #1#2#3
+  { \sys_query:nnnN {#1} { } {#2} #3 }
+\cs_new_protected:Npn \sys_get_query:nnnN #1#2#3#4
+  {
+    \str_clear:N #4
+    \@@_get_query:neeN {#1}
+      { \tl_if_blank:nF {#2} { \exp_not:n { ~ #2 } } }
+      {
+        \tl_if_blank:nF {#3}
+          {
+            \c_space_tl
+            \sys_if_shell_restricted:F '
+            \exp_not:n {#3}
+            \sys_if_shell_restricted:F '
+          }
+      }
+      #4
+  }
+\cs_new_protected:Npn \@@_get_query:nnnN #1#2#3#4
+  {
+    \sys_if_shell:T
+      {
+        \sys_get_shell:nnN
+          { l3sys-query~#1 #2 #3 }
+          {
+            \int_step_inline:nnn { 0 } { `a - 1 }
+              { \char_set_catcode_other:n {##1} }
+            \int_step_inline:nnn { `Z + 1 } { 127 }
+              { \char_set_catcode_other:n {##1} }
+            \tex_endlinechar:D 13 \scan_stop:
+          }
+        \l_@@_tmp_tl
+        \tl_if_empty:NF \l_@@_tmp_tl
+          {
+            \exp_after:wN \@@_get_query:Nw \exp_after:wN #4
+              \l_@@_tmp_tl \q_stop
+          }
+      }
+  }
+\cs_generate_variant:Nn \@@_get_query:nnnN { nee }
+\group_begin:
+  \tex_lccode:D `\* = 13 \scan_stop:
+  \tex_lowercase:D
+    {
+      \group_end:
+      \cs_new_protected:Npn \@@_get_query:Nw #1#2 * \q_stop
+    }
+    { \tl_set:Nn #1 {#2} }
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\sys_split_query:nN}
+% \begin{macro}{\sys_split_query:nnN}
+% \begin{macro}{\sys_split_query:nnnN}
+%   A wrapper for convenience.
+%    \begin{macrocode}
+\cs_new_protected:Npn \sys_split_query:nN #1#2
+  { \sys_split_query:nnnN {#1} { } { } #2 }
+\cs_new_protected:Npn \sys_split_query:nnN #1#2#3
+  { \sys_split_query:nnnN {#1} { } {#2} #3 }
+\group_begin:
+  \tex_lccode:D `\* = 13 \scan_stop:
+  \tex_lowercase:D
+    {
+      \group_end:
+      \cs_new_protected:Npn \sys_split_query:nnnN #1#2#3#4
+        {
+          \seq_clear:N #4
+          \sys_get_query:nnnN {#1} {#2} {#3} \l_@@_tmp_tl
+          \tl_if_empty:NF \l_@@_tmp_tl
+            { \seq_set_split:NnV #4 * \l_@@_tmp_tl }
+         }
+    }
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
 % \subsubsection{Held over from \pkg{l3file}}
 %
 % \begin{variable}{\g_file_curr_name_str}
diff --git a/l3kernel/testfiles/m3expl001.ptex.tlg b/l3kernel/testfiles/m3expl001.ptex.tlg
index 27758664f..aaff39a22 100644
--- a/l3kernel/testfiles/m3expl001.ptex.tlg
+++ b/l3kernel/testfiles/m3expl001.ptex.tlg
@@ -41,7 +41,6 @@ Defining \__color_backend_select_separation:nn on line ...
 Defining \__color_backend_select_devicen:nn on line ...
 Defining \__color_backend_select_iccbased:nn on line ...
 Defining \__color_backend_separation_init:nnnnn on line ...
-Defining \exp_args:Nnee on line ...
 Defining \__color_backend_separation_init:neenn on line ...
 Defining \__color_backend_separation_init_aux:nnnnnn on line ...
 Defining \__color_backend_separation_init_/DeviceCMYK:nnn on line ...
diff --git a/l3kernel/testfiles/m3expl001.uptex.tlg b/l3kernel/testfiles/m3expl001.uptex.tlg
index 27758664f..aaff39a22 100644
--- a/l3kernel/testfiles/m3expl001.uptex.tlg
+++ b/l3kernel/testfiles/m3expl001.uptex.tlg
@@ -41,7 +41,6 @@ Defining \__color_backend_select_separation:nn on line ...
 Defining \__color_backend_select_devicen:nn on line ...
 Defining \__color_backend_select_iccbased:nn on line ...
 Defining \__color_backend_separation_init:nnnnn on line ...
-Defining \exp_args:Nnee on line ...
 Defining \__color_backend_separation_init:neenn on line ...
 Defining \__color_backend_separation_init_aux:nnnnnn on line ...
 Defining \__color_backend_separation_init_/DeviceCMYK:nnn on line ...
diff --git a/l3kernel/testfiles/m3expl003.ptex.tlg b/l3kernel/testfiles/m3expl003.ptex.tlg
index 27758664f..aaff39a22 100644
--- a/l3kernel/testfiles/m3expl003.ptex.tlg
+++ b/l3kernel/testfiles/m3expl003.ptex.tlg
@@ -41,7 +41,6 @@ Defining \__color_backend_select_separation:nn on line ...
 Defining \__color_backend_select_devicen:nn on line ...
 Defining \__color_backend_select_iccbased:nn on line ...
 Defining \__color_backend_separation_init:nnnnn on line ...
-Defining \exp_args:Nnee on line ...
 Defining \__color_backend_separation_init:neenn on line ...
 Defining \__color_backend_separation_init_aux:nnnnnn on line ...
 Defining \__color_backend_separation_init_/DeviceCMYK:nnn on line ...
diff --git a/l3kernel/testfiles/m3expl003.uptex.tlg b/l3kernel/testfiles/m3expl003.uptex.tlg
index 27758664f..aaff39a22 100644
--- a/l3kernel/testfiles/m3expl003.uptex.tlg
+++ b/l3kernel/testfiles/m3expl003.uptex.tlg
@@ -41,7 +41,6 @@ Defining \__color_backend_select_separation:nn on line ...
 Defining \__color_backend_select_devicen:nn on line ...
 Defining \__color_backend_select_iccbased:nn on line ...
 Defining \__color_backend_separation_init:nnnnn on line ...
-Defining \exp_args:Nnee on line ...
 Defining \__color_backend_separation_init:neenn on line ...
 Defining \__color_backend_separation_init_aux:nnnnnn on line ...
 Defining \__color_backend_separation_init_/DeviceCMYK:nnn on line ...





More information about the latex3-commits mailing list.