summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/l3kernel/l3msg.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3msg.dtx')
-rw-r--r--Master/texmf-dist/source/latex/l3kernel/l3msg.dtx324
1 files changed, 220 insertions, 104 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3msg.dtx b/Master/texmf-dist/source/latex/l3kernel/l3msg.dtx
index c644a10cec6..601d5cf0564 100644
--- a/Master/texmf-dist/source/latex/l3kernel/l3msg.dtx
+++ b/Master/texmf-dist/source/latex/l3kernel/l3msg.dtx
@@ -37,7 +37,7 @@
\documentclass[full]{l3doc}
%</driver>
%<*driver|package>
-\GetIdInfo$Id: l3msg.dtx 5537 2015-02-26 21:25:23Z joseph $
+\GetIdInfo$Id: l3msg.dtx 5891 2015-08-25 08:00:59Z mittelba $
{L3 Messages}
%</driver|package>
%<*driver>
@@ -708,40 +708,68 @@
%
% The following functions are used in several kernel modules.
%
-% \begin{function}
+% \begin{function}[added = 2015-08-05]{\__msg_log_next:}
+% \begin{syntax}
+% \cs{__msg_log_next:} \meta{show-command}
+% \end{syntax}
+% Causes the next \meta{show-command} to send its output to the log
+% file instead of the terminal. This allows for instance
+% \cs{cs_log:N} to be defined as \cs{__msg_log_next:} \cs{cs_show:N}.
+% The effect of this command lasts until the next use of
+% \cs{__msg_show_wrap:Nn} or \cs{__msg_show_wrap:n} or
+% \cs{__msg_show_variable:NNNnn}, in other words until the next time
+% the \eTeX{} primitive \tn{showtokens} would have been used for
+% showing to the terminal or until the next
+% \texttt{variable-not-defined} error.
+% \end{function}
+%
+% \begin{function}[added = 2015-08-05]
% {
-% \__msg_term:nnnnnn,
-% \__msg_term:nnnnnV,
-% \__msg_term:nnnnn,
-% \__msg_term:nnn ,
-% \__msg_term:nn
+% \__msg_show_pre:nnnnnn,
+% \__msg_show_pre:nnxxxx,
+% \__msg_show_pre:nnnnnV
% }
% \begin{syntax}
-% \cs{__msg_term:nnnnnn} \Arg{module} \Arg{message} \Arg{arg one} \Arg{arg two} \Arg{arg three} \Arg{arg four}
+% \cs{__msg_show_pre:nnnnnn} \Arg{module} \Arg{message} \Arg{arg one} \Arg{arg two} \Arg{arg three} \Arg{arg four}
+% \end{syntax}
+% Prints the \meta{message} from \meta{module} in the terminal (or
+% log file if \cs{__msg_log_next:} was issued) without formatting.
+% Used in messages which print complex variable contents completely.
+% \end{function}
+%
+% \begin{function}[added = 2015-08-04]{\__msg_show_variable:NNNnn}
+% \begin{syntax}
+% \cs{__msg_show_variable:NNNnn} \meta{variable} \meta{if-exist} \meta{if-empty} \Arg{msg} \Arg{formatted content}
% \end{syntax}
-% Prints the \meta{message} from \meta{module} in the terminal without
-% formatting. Used in messages which print complex variable contents
-% completely.
+% If the \meta{variable} does not exist according to \meta{if-exist}
+% (typically \cs{cs_if_exist:NTF}) then throw an error and do nothing
+% more. Otherwise, if \meta{msg} is not empty, display the message
+% |LaTeX/kernel/show-|\meta{msg} with \cs{token_to_str:N}
+% \meta{variable} as a first argument, and a second argument that is
+% |?| or empty depending on the result of \meta{if-empty} (typically
+% \cs{tl_if_empty:NTF}) on the \meta{variable}. Then display the
+% \meta{formatted content} by giving it as an argument to
+% \cs{__msg_show_wrap:n}.
% \end{function}
%
-% \begin{function}[updated = 2012-09-09]{\__msg_show_variable:Nnn}
+% \begin{function}[added = 2015-08-03, updated = 2015-08-07]{\__msg_show_wrap:Nn}
% \begin{syntax}
-% \cs{__msg_show_variable:Nnn} \meta{variable} \Arg{type} \Arg{formatted content}
+% \cs{__msg_show_wrap:Nn} \meta{function} \Arg{expression}
% \end{syntax}
-% Displays the \meta{formatted content} of the \meta{variable} of
-% \meta{type} in the terminal. The \meta{formatted content} will be
-% processed as the first argument in a call to \cs{iow_wrap:nnnN},
-% hence |\\|, \verb*|\ | and other formatting sequences can be used.
-% Once expanded and processed, the \meta{formatted content} must
-% either be empty or contain |>|; everything until the first |>| will
-% be removed.
+% Shows or logs the \meta{expression} (turned into a string), an
+% equal sign, and the result of applying the \meta{function} to the
+% \Arg{expression}. For instance, if the \meta{function} is
+% \cs{int_eval:n} and the \meta{expression} is |1+2| then this will
+% log |> 1+2=3.| The case where the \meta{function} is
+% \cs{tl_to_str:n} is special: then the string representation of the
+% \meta{expression} is only logged once.
% \end{function}
%
-% \begin{function}[updated = 2012-09-09]{\__msg_show_variable:n}
+% \begin{function}[added = 2015-08-03]{\__msg_show_wrap:n}
% \begin{syntax}
-% \cs{__msg_show_variable:n} \Arg{formatted text}
+% \cs{__msg_show_wrap:n} \Arg{formatted text}
% \end{syntax}
-% Shows the \meta{formatted text} on the terminal. After expansion,
+% Shows or logs the \meta{formatted text}. After expansion,
% unless it is empty, the \meta{formatted text} must contain |>|,
% and the part of \meta{formatted text} before the first |>| is
% removed. Failure to do so causes low-level \TeX{} errors.
@@ -753,8 +781,9 @@
% \cs{__msg_show_item:n} \meta{item}
% \cs{__msg_show_item:nn} \meta{item-key} \meta{item-value}
% \end{syntax}
-% Auxiliary functions used within the argument of
-% \cs{__msg_show_variable:Nnn} to format variable items correctly for
+% Auxiliary functions used within the last argument of
+% \cs{__msg_show_variable:NNNnn} or \cs{__msg_show_wrap:n}
+% to format variable items correctly for
% display. The \cs{__msg_show_item:n} version is used for simple lists,
% the \cs{__msg_show_item:nn} and \cs{__msg_show_item_unbraced:nn} versions
% for key--value like data structures.
@@ -831,7 +860,7 @@
}
}
%<*package>
-\tex_ifodd:D \l@expl@log@functions@bool
+\if_bool:N \l@expl@log@functions@bool
\cs_gset_protected:Npn \__chk_if_free_msg:nn #1#2
{
\msg_if_exist:nnT {#1} {#2}
@@ -839,7 +868,7 @@
\@@_kernel_error:nnxx { kernel } { message-already-defined }
{#1} {#2}
}
- \iow_log:x { Defining~message~ #1 / #2 ~\msg_line_context: }
+ \__chk_log:x { Defining~message~ #1 / #2 ~\msg_line_context: }
}
\fi:
%</package>
@@ -847,7 +876,7 @@
% \end{macro}
%
% \begin{macro}{\msg_new:nnnn, \msg_new:nnn}
-% \begin{macro}{\msg_gset:nnnn,\msg_gset:nnn}
+% \begin{macro}{\msg_gset:nnnn, \msg_gset:nnn}
% \begin{macro}{\msg_set:nnnn, \msg_set:nnn}
% Setting a message simply means saving the appropriate text
% into two functions. A sanity check first.
@@ -1924,30 +1953,36 @@
% \begin{macrocode}
\@@_kernel_new:nnn { kernel } { show-clist }
{
- The~comma~list~
- \str_if_eq:nnF {#1} { \l__clist_internal_clist } { \token_to_str:N #1~}
- \clist_if_empty:NTF #1
+ The~comma~list~ \tl_if_empty:nF {#1} { #1 ~ }
+ \tl_if_empty:nTF {#2}
{ is~empty }
{ contains~the~items~(without~outer~braces): }
}
\@@_kernel_new:nnn { kernel } { show-prop }
{
- The~property~list~\token_to_str:N #1~
- \prop_if_empty:NTF #1
+ The~property~list~#1~
+ \tl_if_empty:nTF {#2}
{ is~empty }
{ contains~the~pairs~(without~outer~braces): }
}
\@@_kernel_new:nnn { kernel } { show-seq }
{
- The~sequence~\token_to_str:N #1~
- \seq_if_empty:NTF #1
+ The~sequence~#1~
+ \tl_if_empty:nTF {#2}
{ is~empty }
{ contains~the~items~(without~outer~braces): }
}
-\@@_kernel_new:nnn { kernel } { show-no-stream }
- { No~ #1 ~streams~are~open }
-\@@_kernel_new:nnn { kernel } { show-open-streams }
- { The~following~ #1 ~streams~are~in~use: }
+\@@_kernel_new:nnn { kernel } { show-streams }
+ {
+ \tl_if_empty:nTF {#2} { No~ } { The~following~ }
+ \str_case:nn {#1}
+ {
+ { ior } { input ~ }
+ { iow } { output ~ }
+ }
+ streams~are~
+ \tl_if_empty:nTF {#2} { open } { in~use: }
+ }
% \end{macrocode}
%
% \subsection{Expandable errors}
@@ -1968,9 +2003,9 @@
% is an extra subtlety: if the user inserts tokens for error recovery,
% they should be kept. Thus we also use an odd space character
% (with category code $7$) and keep tokens until that space character,
-% dropping everything else until \cs{q_stop}. The \cs{c_zero} prevents
+% dropping everything else until \cs{q_stop}. The \cs{exp_end:} prevents
% losing braces around the user-inserted text if any, and stops the
-% expansion of \tn{romannumeral}.
+% expansion of \cs{exp:w}.
% \begin{macrocode}
\group_begin:
\char_set_catcode_math_superscript:N \^
@@ -1984,11 +2019,11 @@
{
\exp_not:n
{
- \tex_romannumeral:D
+ \exp:w
\exp_after:wN \exp_after:wN
\exp_after:wN \@@_expandable_error:w
\exp_after:wN \exp_after:wN
- \exp_after:wN \c_zero
+ \exp_after:wN \exp_end:
}
\exp_not:N \use:n { \exp_not:c { LaTeX3~error: } ^ #1 } ^
}
@@ -2049,96 +2084,177 @@
% Functions defined in this section are used for diagnostic functions
% in \pkg{l3clist}, \pkg{l3file}, \pkg{l3prop}, \pkg{l3seq}, \pkg{xtemplate}
%
-% \begin{macro}[int]
-% {\@@_term:nnnnnn, \@@_term:nnnnnV}
-% \begin{macro}[int]{\@@_term:nnnnn}
-% \begin{macro}[int]{\@@_term:nnn}
-% \begin{macro}[int]{\@@_term:nn}
-% Print the text of a message to the terminal without formatting:
-% short cuts around \cs{iow_wrap:nnnN}.
+% \begin{variable}{\g_@@_log_next_bool}
+% \begin{macro}[int]{\@@_log_next:}
+% \begin{macrocode}
+\bool_new:N \g_@@_log_next_bool
+\cs_new_protected_nopar:Npn \@@_log_next:
+ { \bool_gset_true:N \g_@@_log_next_bool }
+% \end{macrocode}
+% \end{macro}
+% \end{variable}
+%
+% \begin{macro}[int]{\@@_show_pre:nnnnnn, \@@_show_pre:nnxxxx, \@@_show_pre:nnnnnV}
+% \begin{macro}[aux]{\@@_show_pre_aux:n}
+% Print the text of a message to the terminal or log file without
+% formatting: short cuts around \cs{iow_wrap:nnnN}. The choice of
+% terminal or log file is done by \cs{@@_show_pre_aux:n}.
% \begin{macrocode}
-\cs_new_protected:Npn \@@_term:nnnnnn #1#2#3#4#5#6
+\cs_new_protected:Npn \@@_show_pre:nnnnnn #1#2#3#4#5#6
{
- \iow_wrap:nnnN
- { \use:c { \c_@@_text_prefix_tl #1 / #2 } {#3} {#4} {#5} {#6} }
- { } { } \iow_term:n
+ \exp_args:Nx \iow_wrap:nnnN
+ {
+ \exp_not:c { \c_@@_text_prefix_tl #1 / #2 }
+ { \tl_to_str:n {#3} }
+ { \tl_to_str:n {#4} }
+ { \tl_to_str:n {#5} }
+ { \tl_to_str:n {#6} }
+ }
+ { } { } \@@_show_pre_aux:n
}
-\cs_generate_variant:Nn \@@_term:nnnnnn { nnnnnV }
-\cs_new_protected:Npn \@@_term:nnnnn #1#2#3#4#5
- { \@@_term:nnnnnn {#1} {#2} {#3} {#4} {#5} { } }
-\cs_new_protected:Npn \@@_term:nnn #1#2#3
- { \@@_term:nnnnnn {#1} {#2} {#3} { } { } { } }
-\cs_new_protected:Npn \@@_term:nn #1#2
- { \@@_term:nnnnnn {#1} {#2} { } { } { } { } }
+\cs_new_protected:Npn \@@_show_pre:nnxxxx #1#2#3#4#5#6
+ {
+ \use:x
+ { \exp_not:n { \@@_show_pre:nnnnnn {#1} {#2} } {#3} {#4} {#5} {#6} }
+ }
+\cs_generate_variant:Nn \@@_show_pre:nnnnnn { nnnnnV }
+\cs_new_protected_nopar:Npn \@@_show_pre_aux:n
+ { \bool_if:NTF \g_@@_log_next_bool { \iow_log:n } { \iow_term:n } }
% \end{macrocode}
% \end{macro}
% \end{macro}
-% \end{macro}
-% \end{macro}
%
-% \begin{macro}[int]{\@@_show_variable:Nnn}
-% \begin{macro}[int]{\@@_show_variable:n}
-% \begin{macro}[aux]{\@@_show_variable_aux:n}
-% \begin{macro}[aux, EXP]{\@@_show_variable_aux:w}
-% The arguments of \cs{@@_show_variable:Nnn} are
+% \begin{macro}[int]{\@@_show_variable:NNNnn}
+% The arguments of \cs{@@_show_variable:NNNnn} are
% \begin{itemize}
-% \item The \meta{variable} to be shown.
-% \item The type of the variable.
-% \item A mapping of the form \cs{seq_map_function:NN} \meta{variable}
-% \cs{@@_show_item:n}, which produces the formatted string.
+% \item The \meta{variable} to be shown as |#1|.
+% \item An \meta{if-exist} conditional |#2| with \texttt{NTF}
+% signature.
+% \item An \meta{if-empty} conditional |#3| or other function with
+% \texttt{NTF} signature (sometimes \cs{use_ii:nnn}).
+% \item The \meta{message} |#4| to use.
+% \item A construction |#5| which produces the formatted string
+% eventually passed to the \tn{showtokens} primitive. Typically
+% this is a mapping of the form \cs{seq_map_function:NN}
+% \meta{variable} \cs{@@_show_item:n}.
% \end{itemize}
-% As for \cs{__kernel_register_show:N}, check that the variable is
-% defined. If it is, output the introductory message, then show the
-% contents |#3| using \cs{@@_show_variable:n}. This wraps the
-% contents (with leading \verb*|> |) to a fixed number of characters
-% per line. The expansion of |#3| may either be empty or start with
-% \verb*|> |. A leading |>|, if present, is removed using a
-% \texttt{w}-type auxiliary, as well as a space following it (via
-% \texttt{f}-expansion). Note that we cannot remove the space as a
-% delimiter for the \texttt{w}-type auxiliary, because a line-break
-% may be taken there, and the space would then disappear. Finally,
-% the resulting token list \cs{l_@@_internal_tl} is displayed to the
-% terminal, with an odd \cs{exp_after:wN} which expands the closing
-% brace to improve the output slightly.
-% The calls to \cs{__iow_with:Nnn} ensure that the \tn{newlinechar} is
-% set to~$10$ so that the \cs{iow_newline:} inserted by the
-% line-wrapping code are correctly recognized by \TeX{}, and that
-% \tn{errorcontextlines} is $-1$ to avoid printing irrelevant context.
+% If \meta{if-exist} \meta{variable} is \texttt{false}, throw an
+% error and remember to reset \cs{g_@@_log_next_bool}, which is
+% otherwise reset by \cs{@@_show_wrap:n}. If \meta{message} is not
+% empty, output the message |LaTeX/kernel/show-|\meta{message} with
+% as its arguments the \meta{variable}, and either an empty second
+% argument or |?| depending on the result of \meta{if-empty}
+% \meta{variable}. Afterwards, show the contents of |#5| using
+% \cs{@@_show_wrap:n} or \cs{@@_log_wrap:n}.
% \begin{macrocode}
-\cs_new_protected:Npn \@@_show_variable:Nnn #1#2#3
+\cs_new_protected:Npn \@@_show_variable:NNNnn #1#2#3#4#5
{
- \cs_if_exist:NTF #1
+ #2 #1
{
- \@@_term:nnn { LaTeX / kernel } { show- #2 } {#1}
- \@@_show_variable:n {#3}
+ \tl_if_empty:nF {#4}
+ {
+ \@@_show_pre:nnxxxx { LaTeX / kernel } { show- #4 }
+ { \token_to_str:N #1 } { #3 #1 { } { ? } } { } { }
+ }
+ \@@_show_wrap:n {#5}
}
{
\@@_kernel_error:nnx { kernel } { variable-not-defined }
{ \token_to_str:N #1 }
+ \bool_gset_false:N \g_@@_log_next_bool
}
}
-\cs_new_protected:Npn \@@_show_variable:n #1
- { \iow_wrap:nnnN {#1} { } { } \@@_show_variable_aux:n }
-\cs_new_protected:Npn \@@_show_variable_aux:n #1
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}[int]{\@@_show_wrap:Nn}
+% A short-hand used for \cs{int_show:n} and many other functions that
+% passes to \cs{@@_show_wrap:n} the result of applying |#1| (a
+% function such as \cs{int_eval:n}) to the expression |#2|. The
+% leading |>~| is needed by \cs{@@_show_wrap:n}. The use of
+% \texttt{x}-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}.
+% This does not lead to double expansion because the
+% \texttt{x}-expansion of |#1| |{#2}| is a string in all cases where
+% \cs{@@_show_wrap:Nn} is used.
+% \begin{macrocode}
+\cs_new_protected:Npn \@@_show_wrap:Nn #1#2
+ { \exp_args:Nx \@@_show_wrap:n { > ~ \tl_to_str:n {#2} = #1 {#2} } }
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}[int]{\@@_show_wrap:n}
+% \begin{macro}[aux]{\@@_show_wrap_aux:n}
+% \begin{macro}[aux, EXP]{\@@_show_wrap_aux:w}
+% The argument of \cs{@@_show_wrap:n} is line-wrapped using
+% \cs{iow_wrap:nnnN}. Everything before the first~|>| in the wrapped
+% text is removed, as well as an optional space following it (because
+% of \texttt{f}-expansion). In order for line-wrapping to give the
+% correct result, the first~|>| must in fact appear at the beginning
+% of a line and be followed by a space (or a line-break), so in
+% practice, the argument of \cs{@@_show_wrap:n} begins with |>~| or
+% |\\>~|.
+%
+% The line-wrapped text is then either sent to the log file through
+% \cs{iow_log:x}, or shown in the terminal using the
+% \eTeX{} primitive \tn{showtokens} after removing a leading |>~| and
+% trailing dot since those are added automatically by
+% \tn{showtokens}. The trailing dot was included in the first place
+% because its presence can affect line-wrapping. Note that the space
+% after |>| is removed through \texttt{f}-expansion rather than by
+% using an argument delimited by |>~| because the space may have been
+% replaced by a line-break when line-wrapping.
+%
+% A special case is that if the line-wrapped text is a single dot (in
+% other words if the argument of \cs{@@_show_wrap:n}
+% \texttt{x}-expands to nothing) then no |>~| should be removed.
+% This makes it unnecessary to check explicitly for emptyness when
+% using for instance \cs{seq_map_function:NN} \meta{seq~var}
+% \cs{@@_show_item:n} as the argument of \cs{@@_show_wrap:n}.
+%
+% Finally, the token list \cs{l_@@_internal_tl} containing the result
+% of all these manipulations is displayed to the terminal using
+% \cs{etex_showtokens:D} and odd \cs{exp_after:wN} which expand the
+% closing brace to improve the output slightly. The calls to
+% \cs{__iow_with:Nnn} ensure that the \tn{newlinechar} is set to~$10$
+% so that the \cs{iow_newline:} inserted by the line-wrapping code
+% are correctly recognized by \TeX{}, and that \tn{errorcontextlines}
+% is $-1$ to avoid printing irrelevant context.
+%
+% Note also that \cs{g_@@_log_next_bool} is only reset if that is
+% necessary. This allows the user of an interactive prompt to insert
+% tokens as a response to \eTeX{}'s \tn{showtokens}.
+% \begin{macrocode}
+\cs_new_protected:Npn \@@_show_wrap:n #1
+ { \iow_wrap:nnnN { #1 . } { } { } \@@_show_wrap_aux:n }
+\cs_new_protected:Npn \@@_show_wrap_aux:n #1
{
- \tl_if_empty:nTF {#1}
+ \tl_if_single:nTF {#1}
{ \tl_clear:N \l_@@_internal_tl }
- { \tl_set:Nf \l_@@_internal_tl { \@@_show_variable_aux:w #1 } }
- \__iow_with:Nnn \tex_newlinechar:D { 10 }
+ { \tl_set:Nf \l_@@_internal_tl { \@@_show_wrap_aux:w #1 \q_stop } }
+ \bool_if:NTF \g_@@_log_next_bool
+ {
+ \iow_log:x { > ~ \l_@@_internal_tl . }
+ \bool_gset_false:N \g_@@_log_next_bool
+ }
{
- \__iow_with:Nnn \tex_errorcontextlines:D \c_minus_one
+ \__iow_with:Nnn \tex_newlinechar:D { 10 }
{
- \etex_showtokens:D \exp_after:wN \exp_after:wN \exp_after:wN
- { \exp_after:wN \l_@@_internal_tl }
+ \__iow_with:Nnn \tex_errorcontextlines:D \c_minus_one
+ {
+ \etex_showtokens:D \exp_after:wN \exp_after:wN \exp_after:wN
+ { \exp_after:wN \l_@@_internal_tl }
+ }
}
}
}
-\cs_new:Npn \@@_show_variable_aux:w #1 > { }
+\cs_new:Npn \@@_show_wrap_aux:w #1 > #2 . \q_stop {#2}
% \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
-% \end{macro}
%
% \begin{macro}[int,EXP]{\@@_show_item:n}
% \begin{macro}[int,EXP]{\@@_show_item:nn}