diff options
author | Karl Berry <karl@freefriends.org> | 2024-03-14 20:24:49 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2024-03-14 20:24:49 +0000 |
commit | 7bad9b14c550da9ae08669e681e2d94c11bddd9e (patch) | |
tree | ed81b7a7d34eb2da325026d3977131cdb8044c00 /Master/texmf-dist/source/latex/l3kernel/l3sys.dtx | |
parent | 2bb8d5e07c328b2737d7e4ba46365bffa060b64f (diff) |
l3 (14mar24)
git-svn-id: svn://tug.org/texlive/trunk@70637 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3sys.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex/l3kernel/l3sys.dtx | 161 |
1 files changed, 160 insertions, 1 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3sys.dtx b/Master/texmf-dist/source/latex/l3kernel/l3sys.dtx index 9a0fb8dcf3f..feec1232fd0 100644 --- a/Master/texmf-dist/source/latex/l3kernel/l3sys.dtx +++ b/Master/texmf-dist/source/latex/l3kernel/l3sys.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2024-02-20} +% \date{Released 2024-03-14} % % \maketitle % @@ -324,6 +324,58 @@ % 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} is likely to contain the wildcards |*| or |?|, +% 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. +% +% The \meta{spec} and \meta{options}, if given, are expanded fully +% before passing to the underlying script. +% +% 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 +442,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 +1141,107 @@ 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_auxi:nnnN, \@@_get_query_auxi:neeN, +% \@@_get_query_auxii:nnnN, \@@_get_query_auxii: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_get_query:nnnN {#1} { } { } #2 } +\cs_new_protected:Npn \sys_get_query:nnN #1#2#3 + { \sys_get_query:nnnN {#1} { } {#2} #3 } +\cs_new_protected:Npn \sys_get_query:nnnN #1#2#3#4 + { + \str_clear:N #4 + \@@_get_query_auxi:neeN {#1} {#2} {#3} #4 + } +\cs_new:Npn \@@_get_query_auxi:nnnN #1#2#3#4 + { + \@@_get_query_auxii:neeN {#1} + { \tl_if_blank:nF {#2} { \tl_to_str:n { ~ #2 } } } + { + \tl_if_blank:nF {#3} + { + \c_space_tl + \sys_if_shell_restricted:F ' + \tl_to_str:n {#3} + \sys_if_shell_restricted:F ' + } + } + #4 + } +\cs_generate_variant:Nn \@@_get_query_auxi:nnnN { nee } +\cs_new_protected:Npn \@@_get_query_auxii: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_auxii: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} |