summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/l3kernel/l3msg.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/l3kernel/l3msg.dtx')
-rw-r--r--macros/latex/contrib/l3kernel/l3msg.dtx84
1 files changed, 83 insertions, 1 deletions
diff --git a/macros/latex/contrib/l3kernel/l3msg.dtx b/macros/latex/contrib/l3kernel/l3msg.dtx
index e8f3723833..f2705cf8bc 100644
--- a/macros/latex/contrib/l3kernel/l3msg.dtx
+++ b/macros/latex/contrib/l3kernel/l3msg.dtx
@@ -43,7 +43,7 @@
% }^^A
% }
%
-% \date{Released 2023-04-20}
+% \date{Released 2023-05-05}
%
% \maketitle
%
@@ -496,6 +496,35 @@
% present.
% \end{function}
%
+% \begin{function}[EXP, added = 2017-12-04]
+% {\msg_show_item:n, \msg_show_item_unbraced:n, \msg_show_item:nn, \msg_show_item_unbraced:nn}
+% \begin{syntax}
+% \cs{seq_map_function:NN} \meta{seq} \cs{msg_show_item:n}
+% \cs{prop_map_function:NN} \meta{prop} \cs{msg_show_item:nn}
+% \end{syntax}
+% Used in the text of messages for \cs{msg_show:nnxxxx} to show or log
+% a list of items or key--value pairs. The output of
+% \cs{msg_show_item:n} produces a newline, the prefix |>|, two spaces,
+% then the braced string representation of its argument.
+% The two-argument versions separates the key and value using
+% \verb*| => |, and the \texttt{unbraced} versions don't print the
+% surrounding braces.
+%
+% These functions are suitable for usage with iterator functions like
+% \cs{seq_map_function:NN}, \cs{prop_map_function:NN}, etc. For
+% example, with a sequence \cs[no-index]{l_tmpa_seq} containing |a|,
+% |{b}| and |\c|,
+% \begin{verbatim}
+% \seq_map_function:NN \l_tmpa_seq \msg_show_item:n
+% \end{verbatim}
+% would expand to three lines:
+% \begin{quotation}
+% \noindent\verb*|> {a}|\\
+% \verb*|> {{b}}|\\
+% \verb*|> {\c }|
+% \end{quotation}
+% \end{function}
+%
% \subsection{Expandable error messages}
%
% In very rare cases it may be necessary to produce errors in an
@@ -1382,6 +1411,40 @@
\group_end:
% \end{macrocode}
%
+% \begin{macro}[EXP]{\msg_show_item:n}
+% \begin{macro}[EXP]{\msg_show_item_unbraced:n}
+% \begin{macro}[EXP]{\msg_show_item:nn}
+% \begin{macro}[EXP]{\msg_show_item_unbraced:nn}
+% Each item in the variable is formatted using one of the following
+% functions. We cannot use |\\| and so on because these short-hands
+% cannot be used inside the arguments of messages, only when defining
+% the messages. We need to use |^^J| here directly as \pkg{l3file} is
+% not yet loaded.
+% \begin{macrocode}
+\cs_new:Npx \msg_show_item:n #1
+ { ^^J > ~ \c_space_tl \exp_not:N \tl_to_str:n { {#1} } }
+\cs_new:Npx \msg_show_item_unbraced:n #1
+ { ^^J > ~ \c_space_tl \exp_not:N \tl_to_str:n {#1} }
+\cs_new:Npx \msg_show_item:nn #1#2
+ {
+ ^^J > \use:nn { ~ } { ~ }
+ \exp_not:N \tl_to_str:n { {#1} }
+ \use:nn { ~ } { ~ } => \use:nn { ~ } { ~ }
+ \exp_not:N \tl_to_str:n { {#2} }
+ }
+\cs_new:Npx \msg_show_item_unbraced:nn #1#2
+ {
+ ^^J > \use:nn { ~ } { ~ }
+ \exp_not:N \tl_to_str:n {#1}
+ \use:nn { ~ } { ~ } => \use:nn { ~ } { ~ }
+ \exp_not:N \tl_to_str:n {#2}
+ }
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
% \begin{macro}{\@@_class_chk_exist:nT}
% Checking that a message class exists. We build this from
% \cs{cs_if_free:cTF} rather than \cs{cs_if_exist:cTF} because that
@@ -1634,6 +1697,25 @@
%
% \subsection{Kernel-specific functions}
%
+% \begin{macro}{\__kernel_msg_show_eval:Nn, \__kernel_msg_log_eval:Nn, \@@_show_eval:nnN}
+% A short-hand used for \cs{int_show:n} and similar functions that
+% passes to \cs{tl_show:n} the result of applying |#1| (a
+% function such as \cs{int_eval:n}) to the expression |#2|. The use of
+% \texttt{f}-expansion ensures that |#1| is expanded in the scope in which the
+% show command is called, rather than in the group created by
+% \cs{iow_wrap:nnnN}. This is only important for expressions
+% involving the \tn{currentgrouplevel} or \tn{currentgrouptype}.
+% On the other hand we want the expression to be converted to a string
+% with the usual escape character, hence within the wrapping code.
+% \begin{macrocode}
+\cs_new_protected:Npn \__kernel_msg_show_eval:Nn #1#2
+ { \exp_args:Nf \@@_show_eval:nnN { #1 {#2} } {#2} \tl_show:n }
+\cs_new_protected:Npn \__kernel_msg_log_eval:Nn #1#2
+ { \exp_args:Nf \@@_show_eval:nnN { #1 {#2} } {#2} \tl_log:n }
+\cs_new_protected:Npn \@@_show_eval:nnN #1#2#3 { #3 { #2 = #1 } }
+% \end{macrocode}
+% \end{macro}
+%
% These are all retained purely for older \pkg{xparse} support.
%
% \begin{macro}{\__kernel_msg_new:nnnn, \__kernel_msg_new:nnn}