diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3msg.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex/l3kernel/l3msg.dtx | 324 |
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} |