diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3msg.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex/l3kernel/l3msg.dtx | 549 |
1 files changed, 308 insertions, 241 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3msg.dtx b/Master/texmf-dist/source/latex/l3kernel/l3msg.dtx index 472196ac62a..89362b7e7d4 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 3470 2012-02-26 19:10:24Z bruno $ +\GetIdInfo$Id: l3msg.dtx 3568 2012-04-23 13:23:58Z joseph $ {L3 Experimental messages} %</driver|package> %<*driver> @@ -91,6 +91,8 @@ % % \section{Creating new messages} % +% ^^A Wrong: "\msg_new:nnnn" is (as it should) global. +% ^^A However, redirections are indeed local. % All messages have to be created before they can be used. All message % setting is local, with the general assumption that messages will % be managed as part of module set up outside of any \TeX{} grouping. @@ -99,6 +101,19 @@ % available in the console. As a result, formatting is only needed % where it will help to show meaning. In particular, |\\| may be % used to force a new line and \verb*|\ | forces an explicit space. +% Additionally, |\{|, |\#|, |\}|, |\%| and |\~| can be used to produce +% the corresponding character. +% +% Messages may be subdivided \emph{by one level} using the~|/| +% character. This is used within the message filtering system to allow +% for example the \LaTeX{} kernel messages to belong to the module +% \texttt{LaTeX} while still being filterable at a more granular level. +% Thus for example +% \begin{verbatim} +% \msg_new:nnnn { mymodule } { submodule / message } ... +% \end{verbatim} +% will allow only those messages from the \texttt{submodule} to be filtered +% out. % % \begin{function}[updated = 2011-08-16]{\msg_new:nnnn, \msg_new:nnn} % \begin{syntax} @@ -110,9 +125,8 @@ % available then a standard text is given instead. Within \meta{text} % and \meta{more text} four parameters (|#1| to |#4|) can be used: % these will be supplied at the time the message is used. The -% parameters will be expanded when the message is used. Within the -% \meta{text} and \meta{more text} |\\| can be used to start a new -% line. An error will be raised if the \meta{message} already exists. +% parameters will be expanded when the message is used. An error will +% be raised if the \meta{message} already exists. % \end{function} % % \begin{function}{\msg_set:nnnn, \msg_set:nnn, \msg_gset:nnnn, \msg_gset:nnn} @@ -125,9 +139,16 @@ % available then a standard text is given instead. Within \meta{text} % and \meta{more text} four parameters (|#1| to |#4|) can be used: % these will be supplied at the time the message is used. The -% parameters will be expanded when the message is used. Within the -% \meta{text} and \meta{more text} |\\| can be used to start a new -% line. +% parameters will be expanded when the message is used. +% \end{function} +% +% \begin{function}[EXP,pTF, added=2012-03-03]{\msg_if_exist:nn} +% \begin{syntax} +% \cs{msg_if_exist_p:nn} \Arg{module} \Arg{message} +% \cs{msg_if_exist:nnTF} \Arg{module} \Arg{message} \Arg{true code} \Arg{false code} +% \end{syntax} +% Tests whether the \meta{message} for the \meta{module} is currently +% defined. % \end{function} % % \section{Contextual information for messages} @@ -176,7 +197,7 @@ % Fatal <module> error % \end{verbatim} % This function can be redefined to alter the language in which the -% message is give, using |#1| as the name of the \meta{module} to +% message is given, using |#1| as the name of the \meta{module} to % be included. % \end{function} % @@ -189,7 +210,7 @@ % Critical <module> error % \end{verbatim} % This function can be redefined to alter the language in which the -% message is give, using |#1| as the name of the \meta{module} to +% message is given, using |#1| as the name of the \meta{module} to % be included. % \end{function} % @@ -202,7 +223,7 @@ % <module> error % \end{verbatim} % This function can be redefined to alter the language in which the -% message is give, using |#1| as the name of the \meta{module} to +% message is given, using |#1| as the name of the \meta{module} to % be included. % \end{function} % @@ -215,7 +236,7 @@ % <module> warning % \end{verbatim} % This function can be redefined to alter the language in which the -% message is give, using |#1| as the name of the \meta{module} to +% message is given, using |#1| as the name of the \meta{module} to % be included. % \end{function} % @@ -228,7 +249,7 @@ % <module> info % \end{verbatim} % This function can be redefined to alter the language in which the -% message is give, using |#1| as the name of the \meta{module} to +% message is given, using |#1| as the name of the \meta{module} to % be included. % \end{function} % @@ -242,22 +263,26 @@ % \cs{tl_to_str:n} or \cs{token_to_str:N} to prevent unwanted expansion % of the material. % -% \begin{function}{\msg_class_set:nn} +% \begin{function}[updated = 2012-04-12]{\msg_class_set:nn} % \begin{syntax} % \cs{msg_class_set:nn} \Arg{class} \Arg{code} % \end{syntax} % Sets a \meta{class} to output a message, using \meta{code} % to process the message text. The \meta{class} should be a text % value, while the \meta{code} may be any arbitrary material. -% The \meta{code} will receive $6$ arguments: the module +% The \meta{code} will receive~$6$ arguments: the module % name (|#1|), the message name (|#2|) and the four arguments % taken by the message text (|#3| to |#6|). +% ^^A Add an example? An application could be that an IDE redirects +% ^^A classes from 'error' to 'IDEerror', 'warning' to 'IDEwarning', +% ^^A etc, and defines 'IDEerror' and 'IDEwarning' to produce messages +% ^^A which are simpler to parse. % \end{function} % % The kernel defines several common message classes. The following % describes the standard behaviour of each class if no redirection of % the class or message is active. In all cases, the message may be -% issued supplying $0$ to $4$ arguments. The code will +% issued supplying~$0$ to~$4$ arguments. The code will % ensure that there an no errors if the number of arguments supplied % here does not match the number in the definition of the message % (although of course the sense of the message may be impaired). @@ -271,8 +296,7 @@ % \msg_fatal:nn % } % \begin{syntax} -% \cs{msg_fatal:nnxxxx} \Arg{module} \Arg{message} \Arg{arg one} -% ~~\Arg{arg two} \Arg{arg three} \Arg{arg four} +% \cs{msg_fatal:nnxxxx} \Arg{module} \Arg{message} \Arg{arg one} \Arg{arg two} \Arg{arg three} \Arg{arg four} % \end{syntax} % Issues \meta{module} error \meta{message}, passing \meta{arg one} to % \meta{arg four} to the text-creating functions. After issuing a @@ -281,15 +305,14 @@ % % \begin{function} % { -% \msg_critical:nnxxxx , -% \msg_critical:nnxxx , -% \msg_critical:nnxx , -% \msg_critical:nnx , -% \msg_critical:nn -% } +% \msg_critical:nnxxxx , +% \msg_critical:nnxxx , +% \msg_critical:nnxx , +% \msg_critical:nnx , +% \msg_critical:nn +% } % \begin{syntax} -% \cs{msg_critical:nnxxxx} \Arg{module} \Arg{message} \Arg{arg one} -% ~~\Arg{arg two} \Arg{arg three} \Arg{arg four} +% \cs{msg_critical:nnxxxx} \Arg{module} \Arg{message} \Arg{arg one} \Arg{arg two} \Arg{arg three} \Arg{arg four} % \end{syntax} % Issues \meta{module} error \meta{message}, passing \meta{arg one} to % \meta{arg four} to the text-creating functions. After issuing the @@ -297,6 +320,8 @@ % the \TeX{} run (if the current file is the main file) or % may abort reading a sub-file. % \end{function} +% ^^A Perhaps add detection that we are in the main file to really do +% ^^A '\tex_end:D' in that case? % % \begin{function} % { @@ -307,8 +332,7 @@ % \msg_error:nn % } % \begin{syntax} -% \cs{msg_error:nnxxxx} \Arg{module} \Arg{message} \Arg{arg one} -% ~~\Arg{arg two} \Arg{arg three} \Arg{arg four} +% \cs{msg_error:nnxxxx} \Arg{module} \Arg{message} \Arg{arg one} \Arg{arg two} \Arg{arg three} \Arg{arg four} % \end{syntax} % Issues \meta{module} error \meta{message}, passing \meta{arg one} to % \meta{arg four} to the text-creating functions. The error will @@ -325,8 +349,7 @@ % \msg_warning:nn % } % \begin{syntax} -% \cs{msg_warning:nnxxxx} \Arg{module} \Arg{message} \Arg{arg one} -% ~~\Arg{arg two} \Arg{arg three} \Arg{arg four} +% \cs{msg_warning:nnxxxx} \Arg{module} \Arg{message} \Arg{arg one} \Arg{arg two} \Arg{arg three} \Arg{arg four} % \end{syntax} % Issues \meta{module} warning \meta{message}, passing \meta{arg one} to % \meta{arg four} to the text-creating functions. The warning text @@ -343,8 +366,7 @@ % \msg_info:nn % } % \begin{syntax} -% \cs{msg_info:nnxxxx} \Arg{module} \Arg{message} \Arg{arg one} -% ~~\Arg{arg two} \Arg{arg three} \Arg{arg four} +% \cs{msg_info:nnxxxx} \Arg{module} \Arg{message} \Arg{arg one} \Arg{arg two} \Arg{arg three} \Arg{arg four} % \end{syntax} % Issues \meta{module} information \meta{message}, passing % \meta{arg one} to \meta{arg four} to the text-creating functions. @@ -360,8 +382,7 @@ % \msg_log:nn % } % \begin{syntax} -% \cs{msg_log:nnxxxx} \Arg{module} \Arg{message} \Arg{arg one} -% ~~\Arg{arg two} \Arg{arg three} \Arg{arg four} +% \cs{msg_log:nnxxxx} \Arg{module} \Arg{message} \Arg{arg one} \Arg{arg two} \Arg{arg three} \Arg{arg four} % \end{syntax} % Issues \meta{module} information \meta{message}, passing % \meta{arg one} to \meta{arg four} to the text-creating functions. @@ -378,8 +399,7 @@ % \msg_none:nn % } % \begin{syntax} -% \cs{msg_none:nnxxxx} \Arg{module} \Arg{message} \Arg{arg one} -% ~~\Arg{arg two} \Arg{arg three} \Arg{arg four} +% \cs{msg_none:nnxxxx} \Arg{module} \Arg{message} \Arg{arg one} \Arg{arg two} \Arg{arg three} \Arg{arg four} % \end{syntax} % Does nothing: used as a message class to prevent any output at % all (see the discussion of message redirection). @@ -405,13 +425,16 @@ % \begin{verbatim} % \msg_redirect_module:nnn { module } { error } { warning } % \end{verbatim} -% to alter just those messages for module, or even +% to alter only messages from that module, or even % \begin{verbatim} % \msg_redirect_name:nnn { module } { my-message } { warning } % \end{verbatim} -% to target just one message. +% to target just one message. Redirection applies first to individual messages, +% then to messages from one module and finally to messages of one class. Thus +% it is possible to select out an individual message for special treatment +% even if the entire class is already redirected. % -% \begin{function}{\msg_redirect_class:nn} +% \begin{function}[updated = 2012-04-12]{\msg_redirect_class:nn} % \begin{syntax} % \cs{msg_redirect_class:nn} \Arg{class one} \Arg{class two} % \end{syntax} @@ -422,7 +445,7 @@ % rather than at the point of redirection. % \end{function} % -% \begin{function}{\msg_redirect_module:nnn} +% \begin{function}[updated = 2012-04-12]{\msg_redirect_module:nnn} % \begin{syntax} % \cs{msg_redirect_module:nnn} \Arg{module} \Arg{class one} \Arg{class two} % \end{syntax} @@ -437,9 +460,9 @@ % \end{verbatim} % \end{function} % -% \begin{function}{\msg_redirect_name:nnn} +% \begin{function}[updated = 2012-04-12]{\msg_redirect_name:nnn} % \begin{syntax} -% \cs{msg_redirect_name:nn} \Arg{module} \Arg{message} \Arg{class} +% \cs{msg_redirect_name:nnn} \Arg{module} \Arg{message} \Arg{class} % \end{syntax} % Redirects a specific \meta{message} from a specific \meta{module} % to act as a member of \meta{class} of messages. This function can @@ -538,9 +561,8 @@ % available then a standard text is given instead. Within \meta{text} % and \meta{more text} four parameters (|#1| to |#4|) can be used: % these will be supplied at the time the message is used. The -% parameters will be expanded when the message is used. Within the -% \meta{text} and \meta{more text} |\\| can be used to start a new -% line. An error will be raised if the \meta{message} already exists. +% parameters will be expanded when the message is used. An error will +% be raised if the \meta{message} already exists. % \end{function} % % \begin{function}{\msg_kernel_set:nnnn, \msg_kernel_set:nnn} @@ -553,9 +575,7 @@ % available then a standard text is given instead. Within \meta{text} % and \meta{more text} four parameters (|#1| to |#4|) can be used: % these will be supplied at the time the message is used. The -% parameters will be expanded when the message is used. Within the -% \meta{text} and \meta{more text} |\\| can be used to start a new -% line. +% parameters will be expanded when the message is used. % \end{function} % % \begin{function} @@ -567,8 +587,7 @@ % \msg_kernel_fatal:nn % } % \begin{syntax} -% \cs{msg_kernel_fatal:nnxxxx} \Arg{module} \Arg{message} \Arg{arg one} -% ~~\Arg{arg two} \Arg{arg three} \Arg{arg four} +% \cs{msg_kernel_fatal:nnxxxx} \Arg{module} \Arg{message} \Arg{arg one} \Arg{arg two} \Arg{arg three} \Arg{arg four} % \end{syntax} % Issues kernel \meta{module} error \meta{message}, passing \meta{arg one} % to \meta{arg four} to the text-creating functions. After issuing a @@ -584,8 +603,7 @@ % \msg_kernel_error:nn % } % \begin{syntax} -% \cs{msg_kernel_error:nnxxxx} \Arg{module} \Arg{message} \Arg{arg one} -% ~~\Arg{arg two} \Arg{arg three} \Arg{arg four} +% \cs{msg_kernel_error:nnxxxx} \Arg{module} \Arg{message} \Arg{arg one} \Arg{arg two} \Arg{arg three} \Arg{arg four} % \end{syntax} % Issues kernel \meta{module} error \meta{message}, passing \meta{arg one} % to @@ -603,8 +621,7 @@ % \msg_kernel_warning:nn % } % \begin{syntax} -% \cs{msg_kernel_warning:nnxxxx} \Arg{module} \Arg{message} \Arg{arg one} -% ~~\Arg{arg two} \Arg{arg three} \Arg{arg four} +% \cs{msg_kernel_warning:nnxxxx} \Arg{module} \Arg{message} \Arg{arg one} \Arg{arg two} \Arg{arg three} \Arg{arg four} % \end{syntax} % Issues kernel \meta{module} warning \meta{message}, passing % \meta{arg one} to @@ -622,8 +639,7 @@ % \msg_kernel_info:nn % } % \begin{syntax} -% \cs{msg_kernel_info:nnxxxx} \Arg{module} \Arg{message} \Arg{arg one} -% ~~\Arg{arg two} \Arg{arg three} \Arg{arg four} +% \cs{msg_kernel_info:nnxxxx} \Arg{module} \Arg{message} \Arg{arg one} \Arg{arg two} \Arg{arg three} \Arg{arg four} % \end{syntax} % Issues kernel \meta{module} information \meta{message}, passing % \meta{arg one} to \meta{arg four} to the text-creating functions. @@ -636,7 +652,9 @@ % 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. +% However, the interface is similar, with the important caveat that the +% message text and arguments are not expanded, and messages should be +% very short. % % \begin{function}[EXP, added = 2011-11-23] % { @@ -647,8 +665,7 @@ % \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} +% \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 @@ -677,8 +694,7 @@ % % \begin{function}{\msg_aux_use:nn, \msg_aux_use:nnxxxx} % \begin{syntax} -% \cs{msg_aux_use:nnxxxx} \Arg{module} \Arg{message} -% ~~\Arg{arg one} \Arg{arg two} \Arg{arg three} \Arg{arg four} +% \cs{msg_aux_use:nnxxxx} \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. @@ -733,7 +749,7 @@ % the code here. First, a mechanism for creating message text. % This is pretty simple, as there is not actually a lot to do. % -%\begin{variable}{\c_msg_text_prefix_tl, \c_msg_more_text_prefix_tl} +% \begin{variable}{\c_msg_text_prefix_tl, \c_msg_more_text_prefix_tl} % Locations for the text of messages. % \begin{macrocode} \tl_const:Nn \c_msg_text_prefix_tl { msg~text~>~ } @@ -741,6 +757,18 @@ % \end{macrocode} % \end{variable} % +% \begin{macro}[EXP,pTF]{\msg_if_exist:nn} +% Test whether the control sequence containing the message text exists +% or not. +% \begin{macrocode} +\prg_new_conditional:Npnn \msg_if_exist:nn #1#2 { p , T , F , TF } + { + \cs_if_exist:cTF { \c_msg_text_prefix_tl #1 / #2 } + { \prg_return_true: } { \prg_return_false: } + } +% \end{macrocode} +% \end{macro} +% % \begin{macro}[aux]{\chk_if_free_msg:nn} % This auxiliary is similar to \cs{chk_if_free_cs:N}, and is used when % defining messages with \cs{msg_new:nnnn}. It could be inlined in @@ -750,7 +778,7 @@ % \begin{macrocode} \cs_new_protected:Npn \chk_if_free_msg:nn #1#2 { - \cs_if_free:cF { \c_msg_text_prefix_tl #1 / #2 } + \msg_if_exist:nnT {#1} {#2} { \msg_kernel_error:nnxx { msg } { message-already-defined } {#1} {#2} @@ -760,7 +788,7 @@ \tex_ifodd:D \l@expl@log@functions@bool \cs_gset_protected:Npn \chk_if_free_msg:nn #1#2 { - \cs_if_free:cF { \c_msg_text_prefix_tl #1 / #2 } + \msg_if_exist:nnT {#1} {#2} { \msg_kernel_error:nnxx { msg } { message-already-defined } {#1} {#2} @@ -867,12 +895,12 @@ % \end{macrocode} % \end{macro} % -% \begin{macro}{\msg_line_number:} -% \begin{macro}{\msg_line_context:} -% For writing the line number nicely. +% \begin{macro}{\msg_line_number, \msg_line_context:} +% For writing the line number nicely. \cs{msg_line_context:} was set up +% earlier, so this is not \texttt{new}. % \begin{macrocode} \cs_new_nopar:Npn \msg_line_number: { \int_use:N \tex_inputlineno:D } -\cs_set_nopar:Npn \msg_line_context: +\cs_gset_nopar:Npn \msg_line_context: { \c_msg_on_line_text_tl \c_space_tl @@ -880,116 +908,87 @@ } % \end{macrocode} % \end{macro} -% \end{macro} % % \subsection{Showing messages: low level mechanism} % -% \begin{variable}{\c_msg_hide_tl} -% \begin{variable}{\c_msg_hide_tl<dots>} -% An empty variable with a number of (category code 11) periods at the -% end of its name. This is used to push the \TeX{} part of an error -% message \enquote{off the screen}. Using two variables here means that -% later life is a little easier. -% \begin{macrocode} -\char_set_catcode_letter:N \. -\tl_new:N - \c_msg_hide_tl.......................................................... -\tl_const:Nn \c_msg_hide_tl - { \c_msg_hide_tl.......................................................... } -\char_set_catcode_other:N \. -% \end{macrocode} -% \end{variable} -% \end{variable} -% -% \begin{variable}{\l_msg_text_tl} -% For wrapping message text. -% \begin{macrocode} -\tl_new:N \l_msg_text_tl -% \end{macrocode} -%\end{variable} -% % \begin{macro}{\msg_interrupt:xxx} -% \begin{macro}[aux]{\msg_interrupt_no_details:xx} -% \begin{macro}[aux]{\msg_interrupt_details:xxx} -% \begin{macro}[aux]{\msg_interrupt_text:n} -% \begin{macro}[aux]{\msg_interrupt_more_text:n} -% \begin{macro}[aux]{\msg_interrupt_aux:} -% The low-level interruption macro is rather opaque, unfortunately. The -% idea here is to create a a message which hides all of \TeX{}'s own -% information by filling the output up with dots. To achieve this, -% dots have to be letters. The odd -% \cs{c_msg_hide_tl<dots>} actually does the hiding: it is the -% large run of dots in the name that is important here. The meaning -% of |\\| is altered so that the explanation text is a simple run -% whilst the initial error has line-continuation shown. +% The low-level interruption macro is rather opaque, unfortunately. +% Depending on the availability of more information there is a choice +% of how to set up the further help. We feed the extra help text and +% the message itself to a wrapping auxiliary, in this order because we +% must first setup \TeX{}'s \tn{errhelp} register before issuing an +% \tn{errmessage}. % \begin{macrocode} \cs_new_protected:Npn \msg_interrupt:xxx #1#2#3 { - \group_begin: - \tl_if_empty:nTF {#3} - { \msg_interrupt_no_details:xx {#1} {#2} } - { \msg_interrupt_details:xxx {#1} {#2} {#3} } - \msg_interrupt_aux: - \group_end: + \tl_if_empty:nTF {#3} + { + \msg_interrupt_wrap:xx { \\ \c_msg_no_info_text_tl } + {#1 \\\\ #2 \\\\ \c_msg_continue_text_tl } + } + { + \msg_interrupt_wrap:xx { \\ #3 } + {#1 \\\\ #2 \\\\ \c_msg_help_text_tl } + } } % \end{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 -% \texttt{x}-type expansion as the new line markers are different for -% the two type of text and need to be correctly set up. +% \end{macro} +% +% \begin{macro}[aux]{\msg_interrupt_wrap:xx} +% \begin{macro}[aux]{\msg_interrupt_more_text:n} +% First setup \TeX{}'s \tn{errhelp} register with the extra help |#1|, +% then build a nice-looking error message with |#2|. Everything is +% done using \texttt{x}-type expansion as the new line markers are +% different for the two type of text and need to be correctly set up. +% The auxiliary \cs{msg_interrupt_more_text:n} recieves its argument +% as a line-wrapped string, which is thus unaffected by expansion. % \begin{macrocode} -\cs_new_protected:Npn \msg_interrupt_no_details:xx #1#2 +\cs_new_protected:Npn \msg_interrupt_wrap:xx #1#2 { - \iow_wrap:xnnnN - { \\ \c_msg_no_info_text_tl } - { |~ } { 2 } { } \msg_interrupt_more_text:n - \iow_wrap:xnnnN { #1 \\ \\ #2 \\ \\ \c_msg_continue_text_tl } - { ! ~ } { 2 } {} \msg_interrupt_text:n - } -\cs_new_protected:Npn \msg_interrupt_details:xxx #1#2#3 - { - \iow_wrap:xnnnN - { \\ #3 } - { |~ } { 2 } { } \msg_interrupt_more_text:n - \iow_wrap:xnnnN { #1 \\ \\ #2 \\ \\ \c_msg_help_text_tl } - { ! ~ } { 2 } { } \msg_interrupt_text:n + \iow_wrap:xnnnN {#1} { | ~ } { 2 } { } \msg_interrupt_more_text:n + \iow_wrap:xnnnN {#2} { ! ~ } { 2 } { } \msg_interrupt_text:n } -\cs_new_protected:Npn \msg_interrupt_text:n #1 - { \tl_set:Nn \l_msg_text_tl {#1} } \cs_new_protected:Npn \msg_interrupt_more_text:n #1 { -%<*initex> - \tl_set:Nx \l_msg_internal_tl -%</initex> -%<*package> - \protected@edef \l_msg_internal_tl -%</package> - { - |''''''''''''''''''''''''''''''''''''''''''''''' - #1 - \msg_newline: - |............................................... - } - \tex_errhelp:D \exp_after:wN { \l_msg_internal_tl } + \exp_args:Nx \tex_errhelp:D + { + |''''''''''''''''''''''''''''''''''''''''''''''' + #1 \iow_newline: + |............................................... + } } % \end{macrocode} +% \end{macro} +% \end{macro} +% +% \begin{macro}[aux]{\msg_interrupt_text:n} +% \begin{variable}{\c_msg_hide_tl<dots>} % The business end of the process starts by producing some visual -% separation of the message from the main part of the log. It then -% adds the hiding text to the message to print. The error message needs -% to be printed with everything made \enquote{invisible}: this is where -% the strange business with |&| comes in: this is made into another -% |!|. There is also a closing brace that will show up in the output, -% which is turned into a blank space. +% separation of the message from the main part of the log. The error +% message needs to be printed with everything made +% \enquote{invisible}: \TeX{}'s own information involves the macro in +% which \tn{errmessage} is called, and the end of the argument of the +% \tn{errmessage}, including the closing brace. We use an active |!| +% to call the \tn{errmessage} primitive, and end its argument with an +% odd \cs{c_msg_hide_tl<dots>} which fills the output with dots. The +% trailing closing brace is turned into a space to hide it as well. +% The group in which we alter the definition of the active |!| is +% closed before producing the message: this ensures that tokens +% inserted by typing |I| in the command-line will bee inserted after +% the message is entirely cleaned up. % \begin{macrocode} -\group_begin: % { +\group_begin: + \char_set_lccode:nn {`\{} {`\ } \char_set_lccode:nn {`\}} {`\ } \char_set_lccode:nn {`\&} {`\!} \char_set_catcode_active:N \& + \char_set_catcode_letter:N \. + \tl_new:N + \c_msg_hide_tl............................................ \tl_to_lowercase:n { \group_end: - \cs_new_protected:Npn \msg_interrupt_aux: + \cs_new_protected:Npn \msg_interrupt_text:n #1 { \iow_term:x { @@ -998,18 +997,22 @@ \iow_newline: ! } - \tl_put_right:No \l_msg_text_tl { \c_msg_hide_tl } - \cs_set_protected_nopar:Npx & - { \tex_errmessage:D { \exp_not:o { \l_msg_text_tl } } } + \group_begin: + \cs_set_protected_nopar:Npn & + { + \tex_errmessage:D + { + #1 + \c_msg_hide_tl............................................ + } + } + \exp_after:wN + \group_end: & } } % \end{macrocode} -% \end{macro} -% \end{macro} -% \end{macro} -% \end{macro} -% \end{macro} +% \end{variable} % \end{macro} % % \begin{macro}{\msg_log:x} @@ -1034,11 +1037,12 @@ % \end{macrocode} % \end{macro} % \end{macro} +% % \subsection{Displaying messages} % % \LaTeX{} is handling error messages and so the \TeX{} ones are disabled. % \begin{macrocode} -\int_set:Nn \tex_errorcontextlines:D { -1 } +\int_gset:Nn \tex_errorcontextlines:D { -1 } % \end{macrocode} % % \begin{macro} @@ -1068,15 +1072,6 @@ % \end{macrocode} % \end{macro} % -% \begin{variable}{\l_msg_redirect_classes_prop, \l_msg_redirect_names_prop} -% For filtering messages, a list of all messages and of those which have -% to be modified is required. -% \begin{macrocode} -\prop_new:N \l_msg_redirect_classes_prop -\prop_new:N \l_msg_redirect_names_prop -% \end{macrocode} -% \end{variable} -% % \begin{macro}{\msg_class_set:nn} % Setting up a message class does two tasks. Any existing redirection % is cleared, and the various message functions are created @@ -1103,6 +1098,7 @@ % \begin{macro}[aux]{\msg_no_more_text:xxxx} % A test to see if any more text is available, using a % permanently-empty text function. +% ^^A It would be more efficient to not define the more-text when absent. % \begin{macrocode} \prg_new_conditional:Npnn \msg_if_more_text:N #1 { p , T , F , TF } { @@ -1278,102 +1274,117 @@ % \end{macrocode} % \end{macro} % -% \begin{variable} -% { -% \l_msg_redirect_classes_seq , -% \l_msg_class_tl , -% \l_msg_current_class_tl , -% \l_msg_current_module_tl -% } +% \begin{variable}{\l_msg_class_tl, \l_msg_current_class_tl} % Support variables needed for the redirection system. % \begin{macrocode} -\seq_new:N \l_msg_redirect_classes_seq \tl_new:N \l_msg_class_tl \tl_new:N \l_msg_current_class_tl -\tl_new:N \l_msg_current_module_tl % \end{macrocode} -%\end{variable} +% \end{variable} +% +% \begin{variable}{\l_msg_redirect_classes_prop, \l_msg_redirect_names_prop} +% For filtering messages, a list of all messages and of those which have +% to be modified is required. +% \begin{macrocode} +\prop_new:N \l_msg_redirect_classes_prop +\prop_new:N \l_msg_redirect_names_prop +% \end{macrocode} +% \end{variable} +% +% \begin{variable}{\l_msg_redirect_prop} +% For redirection of individually-named messages +% \begin{macrocode} +\prop_new:N \l_msg_redirect_prop +% \end{macrocode} +% \end{variable} +% +% \begin{variable}{\l_msg_use_direct_bool} +% Used to force redirection when a name is given directly. +% \begin{macrocode} +\bool_new:N \l_msg_use_direct_bool +% \end{macrocode} +% \end{variable} % % \begin{macro}[int]{\msg_use:nnnnxxxx} -% \begin{macro}[aux]{\msg_use_aux:nnn} -% \begin{macro}[aux]{\msg_use_aux:nn} -% \begin{macro}[aux]{\msg_use_loop_check:nn} -% \begin{macro}[aux]{\msg_use_code:} -% \begin{macro}[aux]{\msg_use_loop:n, \msg_use_loop:o} -% The main message-using macro creates two auxiliary functions: one -% containing the code for the message, and the second a loop function. -% There is then a hand-off to the system for checking if redirection is -% needed. +% \begin{macro}[aux]{\msg_use_code:, \msg_use_or_change_class:} +% \begin{macro}[aux]{\msg_use_aux_i:nn, \msg_use_aux_ii:nn} +% \begin{macro}[aux]{\msg_use_aux_iii:w} +% \begin{macro}[aux]{\msg_use_aux_iv:w} +% \begin{macro}[aux]{\msg_use_aux_v:} +% Actually using a message is a multi-step process. First, some safety +% checks on the message and class requested. The code and arguments are +% then stored to avoid passing them around. % \begin{macrocode} \cs_new_protected:Npn \msg_use:nnnnxxxx #1#2#3#4#5#6#7#8 { - \cs_set_protected_nopar:Npx \msg_use_code: - { - \seq_clear:N \exp_not:N \l_msg_redirect_classes_seq - \exp_not:n {#2} - } - \cs_set_protected:Npx \msg_use_loop:n ##1 + \msg_if_exist:nnTF {#3} {#4} { - \seq_if_in:NnTF \exp_not:n \l_msg_redirect_classes_seq {#1} - { \msg_kernel_error:nn { msg } { message-loop } {#1} } + \cs_if_exist:cTF { msg_ #1 :nnxxxx } { - \seq_put_right:Nn \exp_not:N \l_msg_redirect_classes_seq {#1} - \exp_not:N \cs_if_exist:cTF { msg_ ##1 :nnxxxx } + \tl_set:Nn \l_msg_current_class_tl {#1} + \cs_set_protected_nopar:Npx \msg_use_code: { \exp_not:n {#2} } + \cs_set_protected_nopar:Npn \msg_use_or_change_class: { - \exp_not:N \use:c { msg_ ##1 :nnxxxx } - \exp_not:n { {#3} {#4} {#5} {#6} {#7} {#8} } + \tl_if_eq:NNTF \l_msg_current_class_tl \l_msg_class_tl + { \msg_use_code: } + { + \use:c { msg_ \l_msg_class_tl :nnxxxx } + {#3} {#4} {#5} {#6} {#7} {#8} + } } + \bool_if:NTF \l_msg_use_direct_bool { - \msg_kernel_error:nnx { msg } { message-class-unknown } {##1} + \bool_set_false:N \l_msg_use_direct_bool + \msg_use_code: } + { \msg_use_aux_i:nn {#3} {#4} } } + { \msg_kernel_error:nnx { msg } { message-class-unknown } {#1} } } - \cs_if_exist:cTF { \c_msg_text_prefix_tl #3 / #4 } - { \msg_use_aux:nnn {#1} {#3} {#4} } { \msg_kernel_error:nnxx { msg } { message-unknown } {#3} {#4} } } +\cs_new_protected_nopar:Npn \msg_use_code: { } +\cs_new_protected_nopar:Npn \msg_use_or_change_class: { } % \end{macrocode} -% The first auxiliary macro looks for a match by name: the most -% restrictive check. +% The first check is for a individual message redirection. If this applies +% then no further redirection is attempted. % \begin{macrocode} -\cs_new_protected:Npn \msg_use_aux:nnn #1#2#3 +\cs_new_protected:Npn \msg_use_aux_i:nn #1#2 { - \tl_set:Nn \l_msg_current_class_tl {#1} - \tl_set:Nn \l_msg_current_module_tl {#2} - \prop_if_in:NnTF \l_msg_redirect_names_prop { // #2 / #3 / } - { \msg_use_loop_check:nn { names } { // #2 / #3 / } } - { \msg_use_aux:nn {#1} {#2} } + \prop_get:NnNTF \l_msg_redirect_prop { #1 / #2 } \l_msg_class_tl + { + \bool_set_true:N \l_msg_use_direct_bool + \msg_use_or_change_class: + } + { \msg_use_aux_ii:nn {#1} {#2} } } % \end{macrocode} -% The second function checks for general matches by module or for -% all modules. +% Next check if there is a redirection by module or by submodule. % \begin{macrocode} -\cs_new_protected:Npn \msg_use_aux:nn #1#2 +\cs_new_protected:Npn \msg_use_aux_ii:nn #1#2 { - \prop_if_in:cnTF { l_msg_redirect_ #1 _prop } {#2} - { \msg_use_loop_check:nn {#1} {#2} } + \prop_get:coNTF { l_msg_redirect_ \l_msg_current_class_tl _ prop } + { \msg_use_aux_iii:w #1 / #2 / \q_stop } \l_msg_class_tl + { \msg_use_or_change_class: } { - \prop_if_in:cnTF { l_msg_redirect_ #1 _prop } { * } - { \msg_use_loop_check:nn {#1} { * } } - { \msg_use_code: } + \prop_get:coNTF { l_msg_redirect_ \l_msg_current_class_tl _ prop } + { \msg_use_aux_iv:w #1 / #2 \q_stop } \l_msg_class_tl + { \msg_use_or_change_class: } + { \msg_use_aux_v: } } } +\cs_new:Npn \msg_use_aux_iii:w #1 / #2 / #3 \q_stop { #1 / #2 } +\cs_new:Npn \msg_use_aux_iv:w #1 / #2 \q_stop { #1 } % \end{macrocode} -% When checking whether to loop, the same code is needed in a few -% places. +% Finally test for redirection of an entire class. % \begin{macrocode} -\cs_new_protected:Npn \msg_use_loop_check:nn #1#2 +\cs_new_protected:Npn \msg_use_aux_v: { - \prop_get:cnN { l_msg_redirect_ #1 _prop } {#2} \l_msg_class_tl - \tl_if_eq:NNTF \l_msg_current_class_tl \l_msg_class_tl - { - { \msg_use_code: } - { \msg_use_loop:o \l_msg_class_tl } - } + \prop_get:cnNF { l_msg_redirect_ \l_msg_current_class_tl _ prop } + { * } \l_msg_class_tl + { \tl_set_eq:NN \l_msg_class_tl \l_msg_current_class_tl } + \msg_use_or_change_class: } -\cs_new_protected_nopar:Npn \msg_use_code: { } -\cs_new_protected:Npn \msg_use_loop:n #1 { } -\cs_generate_variant:Nn \msg_use_loop:n { o } % \end{macrocode} % \end{macro} % \end{macro} @@ -1383,26 +1394,80 @@ % \end{macro} % % \begin{macro}{\msg_redirect_class:nn} +% \begin{macro}[aux]{\msg_redirect_class_aux:nnn, \msg_redirect_class_aux:nVn} % Converts class one into class two. % \begin{macrocode} \cs_new_protected:Npn \msg_redirect_class:nn #1#2 - { \prop_put:cnn { l_msg_redirect_ #1 _prop } { * } {#2} } + { + \cs_if_exist:cTF { msg_ #1 :nnxxxx } + { + \cs_if_exist:cTF { msg_ #2 :nnxxxx } + { + \tl_set:Nn \l_msg_current_class_tl {#1} + \msg_redirect_class_aux:nnn {#1} {#2} {#2} + } + { \msg_kernel_error:nnx { msg } { message-class-unknown } {#2} } + } + { \msg_kernel_error:nnx { msg } { message-class-unknown } {#1} } + } +\cs_new_protected:Npn \msg_redirect_class_aux:nnn #1#2#3 + { + \prop_get:cnNTF { l_msg_redirect_ #2 _prop } { * } \l_msg_class_tl + { + \tl_if_eq:NNTF \l_msg_class_tl \l_msg_current_class_tl + { \msg_kernel_error:nnxx { msg } { message-loop } {#1} {#3} } + { \msg_redirect_class_aux:nVn {#1} \l_msg_class_tl {#3} } + } + { \prop_put:cnn { l_msg_redirect_ #1 _prop } { * } {#3} } + } +\cs_generate_variant:Nn \msg_redirect_class_aux:nnn { nV } % \end{macrocode} % \end{macro} +% \end{macro} % % \begin{macro}{\msg_redirect_module:nnn} +% \begin{macro}[aux] +% {\msg_redirect_module_aux:nnnn, \msg_redirect_module_aux:nnVn} % For when all messages of a class should be altered for a given module. % \begin{macrocode} \cs_new_protected:Npn \msg_redirect_module:nnn #1#2#3 - { \prop_put:cnn { l_msg_redirect_ #2 _prop } {#1} {#3} } + { + \cs_if_exist:cTF { msg_ #2 :nnxxxx } + { + \cs_if_exist:cTF { msg_ #3 :nnxxxx } + { + \tl_set:Nn \l_msg_current_class_tl {#1} + \msg_redirect_module_aux:nnnn {#1} {#2} {#3} {#3} + } + { \msg_kernel_error:nnx { msg } { message-class-unknown } {#3} } + } + { \msg_kernel_error:nnx { msg } { message-class-unknown } {#2} } + } +\cs_new_protected:Npn \msg_redirect_module_aux:nnnn #1#2#3#4 + { + \prop_get:cnNTF { l_msg_redirect_ #3 _prop } {#1} \l_msg_class_tl + { + \tl_if_eq:NNTF \l_msg_class_tl \l_msg_current_class_tl + { \msg_kernel_error:nnxx { msg } { message-loop } {#2} {#4} } + { \msg_redirect_moduel_aux:nVn {#1} {#2} \l_msg_class_tl {#4} } + } + { \prop_put:cnn { l_msg_redirect_ #2 _prop } {#1} {#4} } + } +\cs_generate_variant:Nn \msg_redirect_module_aux:nnnn { nnV } % \end{macrocode} % \end{macro} +% \end{macro} % % \begin{macro}{\msg_redirect_name:nnn} -% Named message will always use the given class. +% Named message will always use the given class even if that class is +% redirected further. % \begin{macrocode} \cs_new_protected:Npn \msg_redirect_name:nnn #1#2#3 - { \prop_put:Nnn \l_msg_redirect_names_prop { // #1 / #2 / } {#3} } + { + \cs_if_exist:cTF { msg_ #3 :nnxxxx } + { \prop_put:Nnn \l_msg_redirect_prop { #1 / #2 } {#3} } + { \msg_kernel_error:nnx { msg } { message-class-unknown } {#3} } + } % \end{macrocode} % \end{macro} % @@ -1469,7 +1534,7 @@ % \begin{macro}{\msg_kernel_error:nnxx} % \begin{macro}{\msg_kernel_error:nnx} % \begin{macro}{\msg_kernel_error:nn} -% Neither can kernel errors. +% Neither can kernel errors. % \begin{macrocode} \cs_new_protected:Npn \msg_kernel_error:nnxxxx #1#2#3#4#5#6 { @@ -1500,11 +1565,11 @@ } \cs_new_protected:Npn \msg_kernel_error:nnxxx #1#2#3#4#5 {\msg_kernel_error:nnxxxx {#1} {#2} {#3} {#4} {#5} { } } -\cs_set_protected:Npn \msg_kernel_error:nnxx #1#2#3#4 +\cs_gset_protected:Npn \msg_kernel_error:nnxx #1#2#3#4 { \msg_kernel_error:nnxxxx {#1} {#2} {#3} {#4} { } { } } -\cs_set_protected:Npn \msg_kernel_error:nnx #1#2#3 +\cs_gset_protected:Npn \msg_kernel_error:nnx #1#2#3 { \msg_kernel_error:nnxxxx {#1} {#2} {#3} { } { } { } } -\cs_set_protected:Npn \msg_kernel_error:nn #1#2 +\cs_gset_protected:Npn \msg_kernel_error:nn #1#2 { \msg_kernel_error:nnxxxx {#1} {#2} { } { } { } { } } % \end{macrocode} % \end{macro} @@ -1690,6 +1755,8 @@ { Zero~step~size~for~stepwise~function~#1. } \msg_kernel_new:nnn { prg } { replicate-neg } { Negative~argument~for~\prg_replicate:nn. } +\msg_kernel_new:nnn { kernel } { unknown-comparison } + { Relation~symbol~'#1'~unknown:~use~=,~<,~>,~==,~!=,~<=,~>=. } % \end{macrocode} % % Messages used by the \enquote{\texttt{show}} functions. |