[latex3-commits] [latex3/latex3] l3sys-query: Add macro interface for l3sys-query (b92916132)
github at latex-project.org
github at latex-project.org
Fri Mar 8 13:41:35 CET 2024
Repository : https://github.com/latex3/latex3
On branch : l3sys-query
Link : https://github.com/latex3/latex3/commit/b929161323c62520edf30b3e0fa518787bc210a5
>---------------------------------------------------------------
commit b929161323c62520edf30b3e0fa518787bc210a5
Author: Joseph Wright <joseph at texdev.net>
Date: Wed Mar 6 13:26:44 2024 +0000
Add macro interface for l3sys-query
>---------------------------------------------------------------
b929161323c62520edf30b3e0fa518787bc210a5
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..5d9673af0 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:TF
+ { \exp_not:n { :#3: } }
+ { \exp_not:n { '#3' } }
+ }
+ }
+ #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
+ \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.