Skip to content

Commit

Permalink
Base "show" functions on \tl_show:n and new \msg_show:nn (see #419)
Browse files Browse the repository at this point in the history 
This drastically reduces the use of \__msg functions and should give good
clean examples for the few package writers who misused the internals.
  • Loading branch information
Bruno Le Floch committed Dec 5, 2017
1 parent 11681d3 commit e1a7c43
Show file tree
Hide file tree
Showing 33 changed files with 677 additions and 659 deletions.
71 changes: 31 additions & 40 deletions l3kernel/l3basics.dtx
View file
Expand Up @@ -3454,80 +3454,71 @@
{
\__msg_kernel_error:nnx { kernel } { variable-not-defined }
{ \token_to_str:N #1 }
\bool_gset_false:N \g__msg_log_next_bool
}
}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_register_show:N, \@@_register_show:c}
% \begin{macro}{\@@_register_show_aux:n}
% \begin{macro}
% {\@@_register_show:N, \@@_register_show:c, \@@_register_log:N, \@@_register_log:c}
% \begin{macro}{\@@_register_show_aux:NN, \@@_register_show_aux:nNN}
% Simply using the \tn{showthe} primitive does not allow for
% line-wrapping, so instead use \cs{__msg_show_wrap:n} (defined
% in \pkg{l3msg}). This displays
% line-wrapping, so instead use \cs{tl_show:n} and \cs{tl_log:n} (defined
% in \pkg{l3tl} and that performs line-wrapping). This displays
% |>~|\meta{variable}|=|\meta{value}. We expand the value before-hand
% as otherwise some integers (such as \tn{currentgrouplevel} or
% \tn{currentgrouptype}) altered by the line-wrapping code would show
% wrong values.
% \begin{macrocode}
\cs_new_protected:Npn \@@_register_show:N #1
{
\@@_check_defined:NT #1
{ \exp_args:No \@@_register_show_aux:nN { \tex_the:D #1 } #1 }
}
\cs_new_protected:Npn \@@_register_show_aux:nN #1#2
{ \__msg_show_wrap:n { > ~ \token_to_str:N #2 = \tl_to_str:n {#1} } }
\cs_new_protected:Npn \@@_register_show:N
{ \@@_register_show_aux:NN \tl_show:n }
\cs_new_protected:Npn \@@_register_show:c
{ \exp_args:Nc \@@_register_show:N }
% \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\@@_register_log:N, \@@_register_log:c}
% Redirect the output of \cs{@@_register_show:N} to the log.
% \begin{macrocode}
\cs_new_protected:Npn \@@_register_log:N
{ \__msg_log_next: \@@_register_show:N }
{ \@@_register_show_aux:NN \tl_log:n }
\cs_new_protected:Npn \@@_register_log:c
{ \exp_args:Nc \@@_register_log:N }
\cs_new_protected:Npn \@@_register_show_aux:NN #1#2
{
\@@_check_defined:NT #2
{
\exp_args:No \@@_register_show_aux:nNN
{ \tex_the:D #2 } #2 #1
}
}
\cs_new_protected:Npn \@@_register_show_aux:nNN #1#2#3
{ \exp_args:No #3 { \token_to_str:N #2 = #1 } }
% \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\cs_show:N, \cs_show:c}
% \begin{macro}{\cs_show:N, \cs_show:c, \cs_log:N, \cs_log:c, \@@_show:NN}
% Some control sequences have a very long name or meaning. Thus,
% simply using \TeX{}'s primitive \tn{show} could lead to overlong
% lines. The output of this primitive is mimicked to some extent,
% then the re-built string is given to \cs{iow_wrap:nnnN} for
% then the re-built string is given to \cs{tl_show:n} or \cs{tl_log:n} for
% line-wrapping. We must expand the meaning before passing it to the
% wrapping code as otherwise we would wrongly see the definitions that
% are in place there. To get correct escape characters, set the
% \tn{escapechar} in a group; this also localizes the assignment
% performed by \texttt{x}-expansion. The \cs{cs_show:c} command also
% converts its argument to a control sequence within a group to avoid
% performed by \texttt{x}-expansion. The \cs{cs_show:c} and \cs{cs_log:c} commands
% convert their argument to a control sequence within a group to avoid
% showing \tn{relax} for undefined control sequences.
% \begin{macrocode}
\cs_new_protected:Npn \cs_show:N #1
\cs_new_protected:Npn \cs_show:N { \@@_show:NN \tl_show:n }
\cs_new_protected:Npn \cs_show:c
{ \group_begin: \exp_args:NNc \group_end: \cs_show:N }
\cs_new_protected:Npn \cs_log:N { \@@_show:NN \tl_log:n }
\cs_new_protected:Npn \cs_log:c
{ \group_begin: \exp_args:NNc \group_end: \cs_log:N }
\cs_new_protected:Npn \@@_show:NN #1#2
{
\group_begin:
\int_set:Nn \tex_escapechar:D { `\\ }
\exp_args:NNx
\group_end:
\__msg_show_wrap:n { > ~ \token_to_str:N #1 = \cs_meaning:N #1 }
#1 { \token_to_str:N #2 = \cs_meaning:N #2 }
}
\cs_new_protected:Npn \cs_show:c
{ \group_begin: \exp_args:NNc \group_end: \cs_show:N }
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\cs_log:N, \cs_log:c}
% Use \cs{cs_show:N} or \cs{cs_show:c} after calling
% \cs{__msg_log_next:} to redirect their output to the log file only.
% Note that \cs{cs_log:c} is not just a variant of \cs{cs_log:N} as
% the csname should be turned to a control sequence within a group
% (see \cs{cs_show:c}).
% \begin{macrocode}
\cs_new_protected:Npn \cs_log:N { \__msg_log_next: \cs_show:N }
\cs_new_protected:Npn \cs_log:c { \__msg_log_next: \cs_show:c }
% \end{macrocode}
% \end{macro}
%
Expand Down
127 changes: 33 additions & 94 deletions l3kernel/l3candidates.dtx
View file
Expand Up @@ -381,16 +381,30 @@
% |1+2| then this logs |> 1+2=3.|
% \end{function}
%
% \begin{function}[added = 2017-12-04]{
% \msg_show_list:nnnnnn, \msg_show_list:nnxxxx,
% \msg_log_list:nnnnnn, \msg_log_list:nnxxxx}
% \begin{function}[added = 2017-12-04]
% {
% \msg_show:nnnnnn ,
% \msg_show:nnnnn ,
% \msg_show:nnnn ,
% \msg_show:nnn ,
% \msg_show:nn ,
% \msg_show:nnxxxx ,
% \msg_show:nnxxx ,
% \msg_show:nnxx ,
% \msg_show:nnx
% }
% \begin{syntax}
% \cs{msg_show_list:nnnnnn} \Arg{module} \Arg{message} \Arg{arg1} \Arg{arg2} \Arg{arg3} \Arg{arg4}
% \cs{msg_show:nnnnnn} \Arg{module} \Arg{message} \Arg{arg one} \Arg{arg two} \Arg{arg three} \Arg{arg four}
% \end{syntax}
% Shows or logs the \meta{message} from \meta{module} without
% formatting. This should be used in conjunction with
% \cs{msg_show_item:n} and similar functions to print complex variable
% contents completely.
% Issues \meta{module} information \meta{message}, passing \meta{arg
% one} to \meta{arg four} to the text-creating functions. The
% information text is shown on the terminal and the \TeX{} run is
% interrupted in a manner similar to \cs{tl_show:n}. This is used in
% conjunction with \cs{msg_show_item:n} and similar functions to print
% complex variable contents completely. If the formatted text does
% not contain |>~| at the start of a line, an additional line |>~.|
% will be put at the end. In addition, a final period is added if not
% present.
% \end{function}
%
% \begin{function}[EXP, added = 2017-12-04]
Expand All @@ -399,11 +413,10 @@
% \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_list:nnnnnn} to show
% or log a list of items or key--value pairs. The one-argument
% functions are used for sequences, clist or token lists and the
% others for property lists. These functions turn their arguments to
% strings.
% Used in the text of messages for \cs{msg_show:nnxxxx} to show or log
% a list of items or key--value pairs. The one-argument functions are
% used for sequences, clist or token lists and the others for property
% lists. These functions turn their arguments to strings.
% \end{function}
%
% \section{Additions to \pkg{l3prg}}
Expand Down Expand Up @@ -2009,11 +2022,10 @@
% \end{macro}
% \end{macro}
%
% \begin{macro}{\msg_show_eval:Nn, \@@_show_eval:nn}
% \begin{macro}{\msg_show_eval:Nn, \msg_log_eval:Nn, \@@_show_eval:nnN}
% A short-hand used for \cs{int_show:n} and similar 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
% 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
Expand All @@ -2022,85 +2034,12 @@
% with the usual escape character, hence within the wrapping code.
% \begin{macrocode}
\cs_new_protected:Npn \msg_show_eval:Nn #1#2
{ \exp_args:Nf \@@_show_eval:nn { #1 {#2} } {#2} }
\cs_new_protected:Npn \msg_log_eval:Nn
{ \@@_log_next: \msg_show_eval:Nn }
\cs_new_protected:Npn \@@_show_eval:nn #1#2
{ \@@_show_wrap:n { \tl_to_str:n { > ~ #2 = #1 } } }
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{
% \msg_show_list:nnnnnn, \msg_show_list:nnxxxx,
% \msg_log_list:nnnnnn, \msg_log_list:nnxxxx}
% \begin{macro}[aux]
% {\@@_show_list:n, \@@_show_list:w, \@@_show_list_aux:w, \@@_show_list:nn}
% Wrap the given text with a trailing dot (important later) then pass
% it to \cs{@@_show_list:n}. Logging is easy, just reset the relevant
% boolean. For showing, if there is |\\>~| (or if the whole thing
% starts with |>~|) we split there, print the first part and show the
% second part using \tn{showtokens} (the \cs{exp_after:wN} ensure a
% nice display). Note that that primitive adds a leading |>~| and
% trailing dot. That is why we included a trailing dot before
% wrapping and removed it afterwards. If there is no |\\>~| do the
% same but with an empty second part which adds a spurious but
% inevitable |>~.|
% \begin{macrocode}
\cs_new_protected:Npn \msg_show_list:nnnnnn #1#2#3#4#5#6
{
\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_list:n
}
\cs_generate_variant:Nn \msg_show_list:nnnnnn { nnxxxx }
\cs_new_protected:Npn \msg_log_list:nnnnnn
{ \@@_log_next: \msg_show_list:nnnnnn }
\cs_generate_variant:Nn \msg_log_list:nnnnnn { nnxxxx }
\cs_new_protected:Npn \@@_show_list:n #1
{
\bool_if:NTF \g_@@_log_next_bool
{
\iow_log:n {#1}
\bool_gset_false:N \g_@@_log_next_bool
}
{
\exp_args:Noo \tl_if_in:nnTF
{ \iow_newline: #1 }
{ \iow_newline: > ~ }
{ \exp_after:wN \@@_show_list:w }
{ \exp_after:wN \@@_show_list_aux:w }
\iow_newline: #1 \q_stop
}
}
\exp_last_unbraced:NNNNo
\cs_new:Npn \@@_show_list:w #1 \iow_newline: > ~ #2 . \q_stop
{ \@@_show_list:nn {#1} {#2} }
\cs_new:Npn \@@_show_list_aux:w #1 . \q_stop
{ \@@_show_list:nn {#1} { } }
\cs_new_protected:Npn \@@_show_list:nn #1#2
{
\tl_if_empty:nF {#1}
{ \exp_args:No \iow_term:n { \use_none:n #1 } }
\tl_set:Nn \l_@@_internal_tl {#2}
\__iow_with:Nnn \tex_newlinechar:D { 10 }
{
\__iow_with:Nnn \tex_errorcontextlines:D { -1 }
{
\etex_showtokens:D \exp_after:wN \exp_after:wN \exp_after:wN
{ \exp_after:wN \l_@@_internal_tl }
}
}
}
{ \exp_args:Nf \@@_show_eval:nnN { #1 {#2} } {#2} \tl_show:n }
\cs_new_protected:Npn \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}
% \end{macro}
%
% \begin{macro}[EXP]{\msg_show_item:n}
% \begin{macro}[EXP]{\msg_show_item_unbraced:n}
Expand Down
14 changes: 5 additions & 9 deletions l3kernel/l3clist.dtx
View file
Expand Up @@ -1824,13 +1824,11 @@
%
% \begin{macro}{\clist_show:N, \clist_show:c, \clist_log:N, \clist_log:c, \@@_show:NN}
% Apply the general \cs{__kernel_check_defined:NT} and
% \cs{msg_show_list:nnnnnn}.
% \cs{msg_show:nnnnnn}.
% \begin{macrocode}
\cs_new_protected:Npn \clist_show:N
{ \@@_show:NN \msg_show_list:nnxxxx }
\cs_new_protected:Npn \clist_show:N { \@@_show:NN \msg_show:nnxxxx }
\cs_generate_variant:Nn \clist_show:N { c }
\cs_new_protected:Npn \clist_log:N
{ \@@_show:NN \msg_log_list:nnxxxx }
\cs_new_protected:Npn \clist_log:N { \@@_show:NN \msg_log:nnxxxx }
\cs_generate_variant:Nn \clist_log:N { c }
\cs_new_protected:Npn \@@_show:NN #1#2
{
Expand All @@ -1849,10 +1847,8 @@
% A variant of the above: no existence check, empty first argument for
% the message.
% \begin{macrocode}
\cs_new_protected:Npn \clist_show:n
{ \@@_show:Nn \msg_show_list:nnxxxx }
\cs_new_protected:Npn \clist_log:n
{ \@@_show:Nn \msg_log_list:nnxxxx }
\cs_new_protected:Npn \clist_show:n { \@@_show:Nn \msg_show:nnxxxx }
\cs_new_protected:Npn \clist_log:n { \@@_show:Nn \msg_log:nnxxxx }
\cs_new_protected:Npn \@@_show:Nn #1#2
{
#1 { LaTeX/kernel } { show-clist }
Expand Down
41 changes: 21 additions & 20 deletions l3kernel/l3coffins.dtx
View file
Expand Up @@ -1656,40 +1656,41 @@
% \end{macro}
% \end{macro}
%
% \begin{macro}{\coffin_show_structure:N, \coffin_show_structure:c}
% \begin{macro}
% {
% \coffin_show_structure:N, \coffin_show_structure:c,
% \coffin_log_structure:N, \coffin_log_structure:c,
% \@@_show_structure:NN
% }
% For showing the various internal structures attached to a coffin in
% a way that keeps things relatively readable. If there is no apparent
% structure then the code complains.
% \begin{macrocode}
\cs_new_protected:Npn \coffin_show_structure:N #1
\cs_new_protected:Npn \coffin_show_structure:N
{ \@@_show_structure:NN \msg_show:nnxxxx }
\cs_generate_variant:Nn \coffin_show_structure:N { c }
\cs_new_protected:Npn \coffin_log_structure:N
{ \@@_show_structure:NN \msg_log:nnxxxx }
\cs_generate_variant:Nn \coffin_log_structure:N { c }
\cs_new_protected:Npn \@@_show_structure:NN #1#2
{
\@@_if_exist:NT #1
\@@_if_exist:NT #2
{
\msg_show_list:nnxxxx { LaTeX / kernel } { show-coffin }
{ \token_to_str:N #1 }
#1 { LaTeX / kernel } { show-coffin }
{ \token_to_str:N #2 }
{
\iow_newline: >~ ht ~=~ \dim_eval:n { \coffin_ht:N #1 }
\iow_newline: >~ dp ~=~ \dim_eval:n { \coffin_dp:N #1 }
\iow_newline: >~ wd ~=~ \dim_eval:n { \coffin_wd:N #1 }
\iow_newline: >~ ht ~=~ \dim_eval:n { \coffin_ht:N #2 }
\iow_newline: >~ dp ~=~ \dim_eval:n { \coffin_dp:N #2 }
\iow_newline: >~ wd ~=~ \dim_eval:n { \coffin_wd:N #2 }
}
{
\prop_map_function:cN
{ l_@@_poles_ \__int_value:w #1 _prop }
{ l_@@_poles_ \int_eval:n {#2} _prop }
\msg_show_item_unbraced:nn
}
{ }
}
}
\cs_generate_variant:Nn \coffin_show_structure:N { c }
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\coffin_log_structure:N, \coffin_log_structure:c}
% Redirect output of \cs{coffin_show_structure:N} to the log.
% \begin{macrocode}
\cs_new_protected:Npn \coffin_log_structure:N
{ \__msg_log_next: \coffin_show_structure:N }
\cs_generate_variant:Nn \coffin_log_structure:N { c }
% \end{macrocode}
% \end{macro}
%
Expand Down Expand Up @@ -1717,7 +1718,7 @@
\__msg_kernel_new:nnn { kernel } { show-coffin }
{
Size~of~coffin~#1 : #2 \\
Poles~of~coffin~#1 : #3
Poles~of~coffin~#1 : #3 .
}
% \end{macrocode}
%
Expand Down

0 comments on commit e1a7c43

Please sign in to comment.