diff options
author | Karl Berry <karl@freefriends.org> | 2011-12-11 22:32:04 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2011-12-11 22:32:04 +0000 |
commit | 3cc0c51eddc31f37b82f651016191bf3575f3aac (patch) | |
tree | 85e3f4cfbe245c416571020e0eb1136193596550 /Master/texmf-dist/source/latex/l3kernel/l3msg.dtx | |
parent | c56f30c6154e55286a21f438d5ed545a5169f13b (diff) |
l3kernel 3036 (11dec11)
git-svn-id: svn://tug.org/texlive/trunk@24822 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3msg.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex/l3kernel/l3msg.dtx | 314 |
1 files changed, 278 insertions, 36 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3msg.dtx b/Master/texmf-dist/source/latex/l3kernel/l3msg.dtx index 0e1eb8e072e..36d9e6d9d48 100644 --- a/Master/texmf-dist/source/latex/l3kernel/l3msg.dtx +++ b/Master/texmf-dist/source/latex/l3kernel/l3msg.dtx @@ -35,7 +35,7 @@ % %<*driver|package> \RequirePackage{l3names} -\GetIdInfo$Id: l3msg.dtx 2896 2011-10-09 20:36:50Z joseph $ +\GetIdInfo$Id: l3msg.dtx 3029 2011-12-06 22:47:30Z joseph $ {L3 Experimental messages} %</driver|package> %<*driver> @@ -115,7 +115,7 @@ % line. An error will be raised if the \meta{message} already exists. % \end{function} % -% \begin{function}{\msg_set:nnnn, \msg_set:nnn} +% \begin{function}{\msg_set:nnnn, \msg_set:nnn, \msg_gset:nnnn, \msg_gset:nnn} % \begin{syntax} % \cs{msg_set:nnnn} \Arg{module} \Arg{message} \Arg{text} \Arg{more text} % \end{syntax} @@ -633,11 +633,29 @@ % \section{Expandable errors} % % In a few places, the \LaTeX3 kernel needs to produce errors in an -% expansion only context. This must be handled very differently from -% normal error messages, as none of the tools to print to the terminal -% or the log file are expandable. +% expansion only context. This must be handled internally very +% differently from normal error messages, as none of the tools +% to print to the terminal or the log file are expandable. +% However, the interface is similar. % -% \begin{function}[added = 2011-08-11, updated = 2011-08-13] +% \begin{function}[EXP, added = 2011-11-23] +% { +% \msg_expandable_kernel_error:nnnnnn, +% \msg_expandable_kernel_error:nnnnn, +% \msg_expandable_kernel_error:nnnn, +% \msg_expandable_kernel_error:nnn, +% \msg_expandable_kernel_error:nn +% } +% \begin{syntax} +% \cs{msg_expandable_kernel_error:nnnnnn} \Arg{module} \Arg{message} +% ~~\Arg{arg one} \Arg{arg two} \Arg{arg three} \Arg{arg four} +% \end{syntax} +% Issues an error, passing \meta{arg one} to \meta{arg four} +% to the text-creating functions. The resulting string must +% be shorter than a line, otherwise it will be cropped. +% \end{function} +% +% \begin{function}[EXP, added = 2011-08-11, updated = 2011-08-13] % {\msg_expandable_error:n} % \begin{syntax} % \cs{msg_expandable_error:n} \Arg{error message} @@ -653,6 +671,36 @@ % \end{texnote} % \end{function} % +% \section{Internal \pkg{l3msg} functions} +% +% The following functions are used in several kernel modules. +% +% \begin{function}{\msg_aux_use:nn, \msg_aux_use:nnxxxx} +% \begin{syntax} +% \cs{msg_aux_use:nnxx} \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, +% without formatting. +% \end{function} +% +% \begin{function}{\msg_aux_show:x} +% \begin{syntax} +% \cs{msg_aux_show:x} \Arg{formatted string} +% \end{syntax} +% Shows the \meta{formatted string} on the terminal. +% The \meta{formatted string} must start with |^^J>|, +% failure to do so causes low-level \TeX{} errors. +% \end{function} +% +% \begin{function}{\msg_aux_show:Nnx} +% \begin{syntax} +% \cs{msg_aux_show:Nnx} \meta{variable} \Arg{module} \Arg{token list} +% \end{syntax} +% Auxiliary common to \pkg{l3clist}, \pkg{l3prop} and \pkg{seq}, +% which displays an appropriate message and the contents of the variable. +% \end{function} +% % \end{documentation} % % \begin{implementation} @@ -678,7 +726,7 @@ % \end{macrocode} % \end{variable} % -%\section{Creating messages} +% \subsection{Creating messages} % % Messages are created and used separately, so there two parts to % the code here. First, a mechanism for creating message text. @@ -702,7 +750,7 @@ { \cs_if_exist:cT { \c_msg_text_prefix_tl #1 / #2 } { - \msg_kernel_error:nn { msg } { message-already-defined } + \msg_kernel_error:nnxx { msg } { message-already-defined } {#1} {#2} } \msg_gset:nnnn {#1} {#2} @@ -857,7 +905,6 @@ \group_end: } % \end{macrocode} -% \begin{macrocode} % Depending on the availability of more information there is a choice of % how to set up the further help. The extra help text has to be set % before the message itself can be issued. Everything is done using @@ -1044,7 +1091,7 @@ % \end{macro} % \end{macro} % -%\begin{macro} +% \begin{macro} % { % \msg_fatal:nnxxxx , % \msg_fatal:nnxxx , @@ -1329,7 +1376,7 @@ \cs_new_protected_nopar:Npn \msg_redirect_name:nnn #1#2#3 { \prop_put:Nnn \l_msg_redirect_names_prop { // #1 / #2 / } {#3} } % \end{macrocode} -%\end{macro} +% \end{macro} % % \subsection{Kernel-specific functions} % @@ -1513,9 +1560,8 @@ { Message~'#2'~for~module~'#1'~already~defined. } { \c_msg_coding_error_text_tl - LaTeX~was~asked~to~define~a~new~message~called~'#2' - by~the~module~'#1'~module:\\ - this~message~already~exists. + LaTeX~was~asked~to~define~a~new~message~called~'#2'\ + by~the~module~'#1':~this~message~already~exists. \c_msg_return_text_tl } \msg_kernel_new:nnnn { msg } { message-unknown } @@ -1591,34 +1637,54 @@ } % \end{macrocode} % -% \begin{macro}{\msg_kernel_bug:x} -% \begin{variable}{\c_msg_kernel_bug_text_tl, \c_msg_kernel_bug_more_text_tl} -% The \LaTeX{} coding bug error gets re-visited here. +% Some errors only appear in expandable settings, +% hence don't need a \enquote{more-text} argument. % \begin{macrocode} -\cs_set_protected:Npn \msg_kernel_bug:x #1 +\msg_kernel_new:nnn { seq } { misused } + { A~sequence~was~misused. } +\msg_kernel_new:nnn { kernel } { bad-var } + { Erroneous~variable~#1 used! } +\msg_kernel_new:nnn { prg } { zero-step } + { Zero~step~size~for~stepwise~function~#1. } +% \end{macrocode} +% +% Messages used by the \enquote{\texttt{show}} functions. +% \begin{macrocode} +\msg_kernel_new:nnn { seq } { show } { - \msg_interrupt:xxx { \c_msg_kernel_bug_text_tl } - { - #1 - \msg_see_documentation_text:n { LaTeX3 } - } - { \c_msg_kernel_bug_more_text_tl } + Sequence~\token_to_str:N #1~ + \seq_if_empty:NTF #1 + { is~empty } + { contains~the~items~(without~outer~braces): } } -\tl_const:Nn \c_msg_kernel_bug_text_tl - { This~is~a~LaTeX~bug:~check~coding! } -\tl_const:Nn \c_msg_kernel_bug_more_text_tl +\msg_kernel_new:nnn { prop } { show } { - There~is~a~coding~bug~somewhere~around~here. \\ - This~probably~needs~examining~by~an~expert. - \c_msg_return_text_tl + Property~list~\token_to_str:N #1~ + \prop_if_empty:NTF #1 + { is~empty } + { contains~the~pairs~(without~outer~braces): } } +\msg_kernel_new:nnn { clist } { show } + { + Comma~list~ + \str_if_eq:nnF {#1} { \l_clist_tmpa_clist } { \token_to_str:N #1~} + \clist_if_empty:NTF #1 + { is~empty } + { contains~the~items~(without~outer~braces): } + } +\msg_kernel_new:nnn { ior } { show-no-stream } + { No~input~streams~are~open } +\msg_kernel_new:nnn { ior } { show-open-streams } + { The~following~input~streams~are~in~use: } +\msg_kernel_new:nnn { iow } { show-no-stream } + { No~output~streams~are~open } +\msg_kernel_new:nnn { iow } { show-open-streams } + { The~following~output~streams~are~in~use: } % \end{macrocode} -% \end{variable} -% \end{macro} % % \subsection{Expandable errors} % -% \begin{macro}{\msg_expandable_error:n} +% \begin{macro}[int]{\msg_expandable_error:n} % In expansion only context, we cannot use the normal means of % reporting errors. Instead, we feed \TeX{} an undefined control % sequence, \cs{LaTeX3 error:}. It is thus interrupted, and shows @@ -1655,15 +1721,165 @@ \exp_after:wN \exp_after:wN \exp_after:wN \c_zero } - \exp_not:N \use:n { \exp_not:c { LaTeX3~error: } ^ #1 } - \exp_not:N \q_stop + \exp_not:N \use:n { \exp_not:c { LaTeX3~error: } ^ #1 } ^ } - \cs_new:Npn \msg_expandable_error_aux:w #1 ^ #2 \q_stop { #1 } + \cs_new:Npn \msg_expandable_error_aux:w #1 ^ #2 ^ { #1 } } \group_end: % \end{macrocode} % \end{macro} % +% \begin{macro} +% { +% \msg_expandable_kernel_error:nnnnnn, +% \msg_expandable_kernel_error:nnnnn, +% \msg_expandable_kernel_error:nnnn, +% \msg_expandable_kernel_error:nnn, +% \msg_expandable_kernel_error:nn +% } +% The command built from the csname +% |\c_msg_text_prefix_tl LaTeX / #1 / #2| +% takes four arguments and builds the error text, which is fed to +% \cs{msg_expandable_error:n}. +% \begin{macrocode} +\cs_new:Npn \msg_expandable_kernel_error:nnnnnn #1#2#3#4#5#6 + { + \exp_args:Nf \msg_expandable_error:n + { + \exp_args:NNc \exp_after:wN \exp_stop_f: + { \c_msg_text_prefix_tl LaTeX / #1 / #2 } + {#3} {#4} {#5} {#6} + } + } +\cs_new:Npn \msg_expandable_kernel_error:nnnnn #1#2#3#4#5 + { + \msg_expandable_kernel_error:nnnnnn + {#1} {#2} {#3} {#4} {#5} { } + } +\cs_new:Npn \msg_expandable_kernel_error:nnnn #1#2#3#4 + { + \msg_expandable_kernel_error:nnnnnn + {#1} {#2} {#3} {#4} { } { } + } +\cs_new:Npn \msg_expandable_kernel_error:nnn #1#2#3 + { + \msg_expandable_kernel_error:nnnnnn + {#1} {#2} {#3} { } { } { } + } +\cs_new:Npn \msg_expandable_kernel_error:nn #1#2 + { + \msg_expandable_kernel_error:nnnnnn + {#1} {#2} { } { } { } { } + } +% \end{macrocode} +% \end{macro} +% +% \subsection{Showing variables} +% +% Functions defined in this section are used for diagnostic functions +% in \pkg{l3clist}, \pkg{l3io}, \pkg{l3prop}, \pkg{l3seq}, \pkg{xtemplate} +% +% \begin{variable}{\l_msg_show_tl} +% Used to store the material for the diagnostic functions +% of various modules. +% \begin{macrocode} +\tl_new:N \l_msg_show_tl +% \end{macrocode} +% \end{variable} +% +% \begin{macro}[aux]{\msg_aux_use:nn} +% \begin{macro}[aux]{\msg_aux_use:nnxxxx} +% Print the text of a message to the terminal, without formatting. +% \begin{macrocode} +\cs_new_protected:Npn \msg_aux_use:nn #1#2 + { \msg_aux_use:nnxxxx {#1} {#2} { } { } { } { } } +\cs_new_protected:Npn \msg_aux_use:nnxxxx #1#2#3#4#5#6 + { + \iow_term:x + { + \use:c { \c_msg_text_prefix_tl #1 / #2 } + {#3} {#4} {#5} {#6} + } + } +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% \begin{macro}[int]{\msg_aux_show:Nnx} +% \begin{macro}[aux]{\msg_aux_show:x} +% \begin{macro}[aux,EXP]{\msg_aux_show:w} +% The arguments of \cs{msg_aux_show:Nnx} are +% \begin{itemize} +% \item The \meta{variable} to be shown. +% \item The \texttt{TF} emptyness conditional for that type of variables. +% \item The type of the variable. +% \item A mapping of the form \cs{seq_map_function:NN} \meta{variable} +% \cs{msg_aux_show:n}, which produces the formatted string. +% \end{itemize} +% We remove a new line and \verb*|> | from the first item using +% a \texttt{w}-type auxiliary, and the fact that \texttt{f}-expansion +% removes a space. To avoid a low-level \TeX{} error if there is +% an empty argument, a simple test is used to keep the output +% \enquote{clean}. The odd \cs{exp_after:wN} and trailing +% \cs{prg_do_nothing:} improve the output slightly. +% \begin{macrocode} +\cs_new_protected:Npn \msg_aux_show:Nnx #1#2#3 + { + \cs_if_exist:NTF #1 + { + \msg_aux_use:nnxxxx { LaTeX / #2 } { show } {#1} { } { } { } + \msg_aux_show:x {#3} + } + { + \msg_kernel_error:nnx { kernel } { variable-not-defined } + { \token_to_str:N #1 } + } + } +\cs_new_protected:Npn \msg_aux_show:x #1 + { + \tl_set:Nx \l_msg_show_tl {#1} + \tl_if_empty:NT \l_msg_show_tl + { \tl_set:Nx \l_msg_show_tl { > } } + \exp_args:Nf \etex_showtokens:D + { + \exp_after:wN \exp_after:wN + \exp_after:wN \msg_aux_show:w + \exp_after:wN \l_msg_show_tl + \exp_after:wN + } + \prg_do_nothing: + } +\cs_new:Npn \msg_aux_show:w #1 > { } +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \begin{macro}[aux,EXP]{\msg_aux_show:n} +% \begin{macro}[aux,EXP]{\msg_aux_show:nn} +% \begin{macro}[aux,EXP]{\msg_aux_show_unbraced:nn} +% Each item in the variable is formatted using one of +% the following functions. +% \begin{macrocode} +\cs_new:Npn \msg_aux_show:n #1 + { + \iow_newline: > \c_space_tl \c_space_tl { \exp_not:n {#1} } + } +\cs_new:Npn \msg_aux_show:nn #1#2 + { + \iow_newline: > \c_space_tl \c_space_tl { \exp_not:n {#1} } + \c_space_tl \c_space_tl => \c_space_tl \c_space_tl { \exp_not:n {#2} } + } +\cs_new:Npn \msg_aux_show_unbraced:nn #1#2 + { + \iow_newline: > \c_space_tl \c_space_tl \exp_not:n {#1} + \c_space_tl \c_space_tl => \c_space_tl \c_space_tl \exp_not:n {#2} + } +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% % \subsection{Deprecated functions} % % Deprecated on 2011-05-27, for removal by 2011-08-31. @@ -1722,6 +1938,32 @@ % \end{macro} % \end{macro} % +% \begin{macro}{\msg_kernel_bug:x} +% \begin{variable}{\c_msg_kernel_bug_text_tl, \c_msg_kernel_bug_more_text_tl} +% \begin{macrocode} +%<*deprecated> +\cs_set_protected:Npn \msg_kernel_bug:x #1 + { + \msg_interrupt:xxx { \c_msg_kernel_bug_text_tl } + { + #1 + \msg_see_documentation_text:n { LaTeX3 } + } + { \c_msg_kernel_bug_more_text_tl } + } +\tl_const:Nn \c_msg_kernel_bug_text_tl + { This~is~a~LaTeX~bug:~check~coding! } +\tl_const:Nn \c_msg_kernel_bug_more_text_tl + { + There~is~a~coding~bug~somewhere~around~here. \\ + This~probably~needs~examining~by~an~expert. + \c_msg_return_text_tl + } +%</deprecated> +% \end{macrocode} +% \end{variable} +% \end{macro} +% % \begin{macrocode} %</initex|package> % \end{macrocode} |