diff options
author | Karl Berry <karl@freefriends.org> | 2018-04-30 22:39:09 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2018-04-30 22:39:09 +0000 |
commit | a28e1bfccd6fe522fcd296426e4d89c7fb4f19b6 (patch) | |
tree | b72347e08575b56fcfed87c4d837b48dcfd1e02a /Master/texmf-dist/source/latex/l3kernel/l3msg.dtx | |
parent | b40c37a9e22b8235ff9c0bc256d00f7af94304c3 (diff) |
l3 (30apr18)
git-svn-id: svn://tug.org/texlive/trunk@47516 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 | 272 |
1 files changed, 83 insertions, 189 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3msg.dtx b/Master/texmf-dist/source/latex/l3kernel/l3msg.dtx index 2314178cf11..c73c38da8ab 100644 --- a/Master/texmf-dist/source/latex/l3kernel/l3msg.dtx +++ b/Master/texmf-dist/source/latex/l3kernel/l3msg.dtx @@ -41,7 +41,7 @@ % }^^A % } % -% \date{Released 2018/03/05} +% \date{Released 2018-04-30} % % \maketitle % @@ -524,174 +524,6 @@ % documentation for the latter should be consulted for full details. % \end{function} % -% \section{Kernel-specific functions} -% -% Messages from \LaTeX3 itself are handled by the general message system, -% but have their own functions. This allows some text to be pre-defined, -% and also ensures that serious errors can be handled properly. -% -% \begin{function}[added = 2017-12-17] -% {\__kernel_msg_new:nnnn, \__kernel_msg_new:nnn} -% \begin{syntax} -% \cs{__kernel_msg_new:nnnn} \Arg{module} \Arg{message} \Arg{text} \Arg{more text} -% \end{syntax} -% Creates a kernel \meta{message} for a given \meta{module}. -% The message is defined to first give \meta{text} and then -% \meta{more text} if the user requests it. If no \meta{more text} is -% 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 and expanded at the time the message is used. -% An error is raised if the \meta{message} already exists. -% \end{function} -% -% \begin{function}[added = 2017-12-17] -% {\__kernel_msg_set:nnnn, \__kernel_msg_set:nnn} -% \begin{syntax} -% \cs{__kernel_msg_set:nnnn} \Arg{module} \Arg{message} \Arg{text} \Arg{more text} -% \end{syntax} -% Sets up the text for a kernel \meta{message} for a given \meta{module}. -% The message is defined to first give \meta{text} and then -% \meta{more text} if the user requests it. If no \meta{more text} is -% 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 and expanded at the time the message is used. -% \end{function} -% -% \begin{function}[added = 2017-12-17] -% { -% \__kernel_msg_fatal:nnnnnn , -% \__kernel_msg_fatal:nnnnn , -% \__kernel_msg_fatal:nnnn , -% \__kernel_msg_fatal:nnn , -% \__kernel_msg_fatal:nn , -% \__kernel_msg_fatal:nnxxxx , -% \__kernel_msg_fatal:nnxxx , -% \__kernel_msg_fatal:nnxx , -% \__kernel_msg_fatal:nnx -% } -% \begin{syntax} -% \cs{__kernel_msg_fatal:nnnnnn} \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 -% fatal error the \TeX{} run halts. Cannot be redirected. -% \end{function} -% -% \begin{function}[added = 2017-12-17] -% { -% \__kernel_msg_error:nnnnnn , -% \__kernel_msg_error:nnnnn , -% \__kernel_msg_error:nnnn , -% \__kernel_msg_error:nnn , -% \__kernel_msg_error:nn , -% \__kernel_msg_error:nnxxxx , -% \__kernel_msg_error:nnxxx , -% \__kernel_msg_error:nnxx , -% \__kernel_msg_error:nnx -% } -% \begin{syntax} -% \cs{__kernel_msg_error:nnnnnn} \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. The error -% stops processing and issues the text at the terminal. After user input, -% the run continues. Cannot be redirected. -% \end{function} -% -% \begin{function}[added = 2017-12-17] -% { -% \__kernel_msg_warning:nnnnnn , -% \__kernel_msg_warning:nnnnn , -% \__kernel_msg_warning:nnnn , -% \__kernel_msg_warning:nnn , -% \__kernel_msg_warning:nn , -% \__kernel_msg_warning:nnxxxx , -% \__kernel_msg_warning:nnxxx , -% \__kernel_msg_warning:nnxx , -% \__kernel_msg_warning:nnx -% } -% \begin{syntax} -% \cs{__kernel_msg_warning:nnnnnn} \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 -% \meta{arg four} to the text-creating functions. The warning text -% is added to the log file, but the \TeX{} run is not interrupted. -% \end{function} -% -% \begin{function}[added = 2017-12-17] -% { -% \__kernel_msg_info:nnnnnn , -% \__kernel_msg_info:nnnnn , -% \__kernel_msg_info:nnnn , -% \__kernel_msg_info:nnn , -% \__kernel_msg_info:nn , -% \__kernel_msg_info:nnxxxx , -% \__kernel_msg_info:nnxxx , -% \__kernel_msg_info:nnxx , -% \__kernel_msg_info:nnx -% } -% \begin{syntax} -% \cs{__kernel_msg_info:nnnnnn} \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. -% The information text is added to the log file. -% \end{function} -% -% \section{Expandable errors} -% -% In a few places, the \LaTeX3 kernel needs to produce errors in an -% 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, with the important caveat that the -% message text and arguments are not expanded, and messages should be -% very short. -% -% \begin{function}[EXP, added = 2017-12-17] -% { -% \__kernel_msg_expandable_error:nnnnnn, -% \__kernel_msg_expandable_error:nnnnn, -% \__kernel_msg_expandable_error:nnnn, -% \__kernel_msg_expandable_error:nnn, -% \__kernel_msg_expandable_error:nn -% } -% \begin{syntax} -% \cs{__kernel_msg_expandable_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 much shorter than a line, otherwise it is 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} -% \end{syntax} -% Issues an \enquote{Undefined error} message from \TeX{} itself, -% and prints the \meta{error message}. The \meta{error message} -% must be short: it is cropped at the end of one line. -% \begin{texnote} -% This function expands to an empty token list after two steps. -% Tokens inserted in response to \TeX{}'s prompt are read with -% the current category code setting, and inserted just after -% the place where the error message was issued. -% \end{texnote} -% \end{function} -% -% \section{Internal \pkg{l3msg} functions} -% -% \begin{variable}{\c__msg_coding_error_text_tl} -% The text -% \begin{verbatim} -% This is a coding error. -% \end{verbatim} -% used by kernel functions when erroneous programming input is encountered. -% \end{variable} -% % \end{documentation} % % \begin{implementation} @@ -747,13 +579,16 @@ % \end{macrocode} % \end{macro} % -% \begin{macro}{\__chk_if_free_msg:nn} -% This auxiliary is similar to \cs{__chk_if_free_cs:N}, and is used when +% \begin{macro}{\@@_chk_if_free:nn} +% This auxiliary is similar to \cs{__kernel_chk_if_free_cs:N}, and is used when % defining messages with \cs{msg_new:nnnn}. % \begin{macrocode} \__kernel_patch:nnNNpn { } - { \__kernel_debug_log:x { Defining~message~ #1 / #2 ~\msg_line_context: } } -\cs_new_protected:Npn \__chk_if_free_msg:nn #1#2 + { + \__kernel_debug_log:x + { Defining~message~ #1 / #2 ~\msg_line_context: } + } +\cs_new_protected:Npn \@@_chk_free:nn #1#2 { \msg_if_exist:nnT {#1} {#2} { @@ -772,7 +607,7 @@ % \begin{macrocode} \cs_new_protected:Npn \msg_new:nnnn #1#2 { - \__chk_if_free_msg:nn {#1} {#2} + \@@_chk_free:nn {#1} {#2} \msg_gset:nnnn {#1} {#2} } \cs_new_protected:Npn \msg_new:nnn #1#2#3 @@ -932,7 +767,7 @@ % inserted by typing |I| in the command-line are inserted after % the message is entirely cleaned up. % -% The \cs{__iow_with:Nnn} auxiliary, defined in \pkg{l3file}, expects +% The \cs{__kernel_iow_with:Nnn} auxiliary, defined in \pkg{l3file}, expects % an \meta{integer variable}, an integer \meta{value}, and some % \meta{code}. It runs the \meta{code} after ensuring that the % \meta{integer variable} takes the given \meta{value}, then restores @@ -961,9 +796,9 @@ \iow_newline: ! } - \__iow_with:Nnn \tex_newlinechar:D { `\^^J } + \__kernel_iow_with:Nnn \tex_newlinechar:D { `\^^J } { - \__iow_with:Nnn \tex_errorcontextlines:D { -1 } + \__kernel_iow_with:Nnn \tex_errorcontextlines:D { -1 } { \group_begin: \cs_set_protected:Npn & @@ -1316,7 +1151,7 @@ % \msg_show:nnxx , % \msg_show:nnx % } -% \begin{macro}[aux]{\@@_show:n, \@@_show:w, \@@_show_dot:w, \@@_show:nn} +% \begin{macro}{\@@_show:n, \@@_show:w, \@@_show_dot:w, \@@_show:nn} % The \texttt{show} message type is used for \cs{seq_show:N} and % similar complicated data structures. Wrap the given text with a % trailing dot (important later) then pass it to \cs{@@_show:n}. If @@ -1353,9 +1188,9 @@ \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 } + \__kernel_iow_with:Nnn \tex_newlinechar:D { 10 } { - \__iow_with:Nnn \tex_errorcontextlines:D { -1 } + \__kernel_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 } @@ -1400,8 +1235,8 @@ % \end{variable} % % \begin{variable}{\l_@@_hierarchy_seq} -% During redirection, split the message name into a sequence with -% items |{/module/submodule}|, |{/module}|, and |{}|. +% During redirection, split the message name into a sequence: +% |{/module/submodule}|, |{/module}|, and |{}|. % \begin{macrocode} \seq_new:N \l_@@_hierarchy_seq % \end{macrocode} @@ -1426,9 +1261,13 @@ % assignment to \cs{@@_use_code:} is similar to \cs{tl_set:Nn}. % The message is eventually produced with whatever \cs{l_@@_class_tl} % is when \cs{@@_use_code:} is called. +% Here is also a good place to suppress tracing output if the +% \pkg{trace} package is loaded since all (non-expandable) messages go +% through this auxiliary. % \begin{macrocode} \cs_new_protected:Npn \@@_use:nnnnnnn #1#2#3#4#5#6#7 { +%<package> \use:c { conditionally@traceoff } \msg_if_exist:nnTF {#2} {#3} { \@@_class_chk_exist:nT {#1} @@ -1446,12 +1285,14 @@ } } { \__kernel_msg_error:nnxx { kernel } { message-unknown } {#2} {#3} } +%<package> \use:c { conditionally@traceon } } \cs_new_protected:Npn \@@_use_code: { } % \end{macrocode} % The first check is for a individual message redirection. If this % applies then no further redirection is attempted. Otherwise, split -% the message name into \texttt{module/submodule/message} (with an +% the message name into \meta{module}, \meta{submodule} and \meta{message} +% (with an % arbitrary number of slashes), and store |{/module/submodule}|, % |{/module}| and |{}| into \cs{l_@@_hierarchy_seq}. We then % map through this sequence, applying the most specific redirection. @@ -1793,7 +1634,8 @@ } % \end{macrocode} % -% Messages for earlier kernel modules. +% Messages for earlier kernel modules plus a few for \pkg{l3keys} which +% cover coding errors. % \begin{macrocode} \__kernel_msg_new:nnnn { kernel } { bad-number-of-arguments } { Function~'#1'~cannot~be~defined~with~#2~arguments. } @@ -1885,6 +1727,8 @@ LaTeX~has~been~asked~to~define~'#1'~as~a~protected~predicate.~ Only~expandable~tests~can~have~a~predicate~version. } +\__kernel_msg_new:nnn { kernel } { randint-backward-range } + { Bounds~ordered~backwards~in~\int_rand:nn {#1}~{#2}. } \__kernel_msg_new:nnnn { kernel } { conditional-form-unknown } { Conditional~form~'#1'~for~function~'#2'~unknown. } { @@ -1892,6 +1736,35 @@ LaTeX~has~been~asked~to~define~the~conditional~form~'#1'~of~ the~function~'#2',~but~only~'TF',~'T',~'F',~and~'p'~forms~exist. } +\__kernel_msg_new:nnnn { kernel } { key-no-property } + { No~property~given~in~definition~of~key~'#1'. } + { + \c_@@_coding_error_text_tl + Inside~\keys_define:nn each~key~name~ + needs~a~property: \\ \\ + \iow_indent:n { #1 .<property> } \\ \\ + LaTeX~did~not~find~a~'.'~to~indicate~the~start~of~a~property. + } +\__kernel_msg_new:nnnn { kernel } { key-property-boolean-values-only } + { The~property~'#1'~accepts~boolean~values~only. } + { + \c_@@_coding_error_text_tl + The~property~'#1'~only~accepts~the~values~'true'~and~'false'. + } +\__kernel_msg_new:nnnn { kernel } { key-property-requires-value } + { The~property~'#1'~requires~a~value. } + { + \c_@@_coding_error_text_tl + LaTeX~was~asked~to~set~property~'#1'~for~key~'#2'.\\ + No~value~was~given~for~the~property,~and~one~is~required. + } +\__kernel_msg_new:nnnn { kernel } { key-property-unknown } + { The~key~property~'#1'~is~unknown. } + { + \c_@@_coding_error_text_tl + LaTeX~has~been~asked~to~set~the~property~'#1'~for~key~'#2':~ + this~property~is~not~defined. + } \__kernel_msg_new:nnnn { kernel } { scanmark-already-defined } { Scan~mark~#1~already~defined. } { @@ -1922,6 +1795,14 @@ with~a~signature~starting~with~'#1',~but~cannot~change~an~argument~ from~type~'#3'~to~type~'#4'. } +\__kernel_msg_new:nnnn { kernel } { invalid-exp-args } + { Invalid~variant~specifier~'#1'~in~'#2'. } + { + \c_@@_coding_error_text_tl + LaTeX~has~been~asked~to~create~an~\iow_char:N\\exp_args:N...~ + function~with~signature~'N#2'~but~'#1'~is~not~a~valid~argument~ + specifier. + } \__kernel_msg_new:nnn { kernel } { deprecated-variant } { Variant~form~'#1'~deprecated~for~base~form~'#2'.~ @@ -1941,7 +1822,7 @@ % In format mode the error is somewhat different. % \begin{macrocode} %<*package> -\bool_if:NTF \l@expl@enable@debug@bool +\__kernel_if_debug:TF { \__kernel_msg_new:nnnn { kernel } { debug } { The~debugging~option~'#1'~does~not~exist~\msg_line_context:. } @@ -1955,14 +1836,19 @@ { Inconsistent~local/global~assignment } { \c_@@_coding_error_text_tl - \if:w l #2 Local \else: Global \fi: \ + \if:w l #2 Local \else: Global \fi: \ % assignment~to~a~ - \if:w l #1 local \else: \if:w g #1 global \else: constant \fi: \fi: \ + \if:w l #1 local + \else: + \if:w g #1 global \else: constant \fi: + \fi: + \ % variable~'#3'. } \__kernel_msg_new:nnnn { kernel } { non-declared-variable } { The~variable~#1~has~not~been~declared~\msg_line_context:. } { + \c_@@_coding_error_text_tl Checking~is~active,~and~you~have~tried~do~so~something~like: \\ \ \ \tl_set:Nn ~ #1 ~ \{ ~ ... ~ \} \\ without~first~having: \\ @@ -2103,10 +1989,14 @@ % \__kernel_msg_expandable_error:nnnnn, % \__kernel_msg_expandable_error:nnnn, % \__kernel_msg_expandable_error:nnn, -% \__kernel_msg_expandable_error:nn +% \__kernel_msg_expandable_error:nn, +% \__kernel_msg_expandable_error:nnffff, +% \__kernel_msg_expandable_error:nnfff, +% \__kernel_msg_expandable_error:nnff, +% \__kernel_msg_expandable_error:nnf, % } % The command built from the csname -% |\c_@@_text_prefix_tl LaTeX / #1 / #2| +% \cs{c_@@_text_prefix_tl} |LaTeX / #1 / #2| % takes four arguments and builds the error text, which is fed to % \cs{@@_expandable_error:n}. % \begin{macrocode} @@ -2139,6 +2029,10 @@ \__kernel_msg_expandable_error:nnnnnn {#1} {#2} { } { } { } { } } +\cs_generate_variant:Nn \__kernel_msg_expandable_error:nnnnnn { nnffff } +\cs_generate_variant:Nn \__kernel_msg_expandable_error:nnnnn { nnfff } +\cs_generate_variant:Nn \__kernel_msg_expandable_error:nnnn { nnff } +\cs_generate_variant:Nn \__kernel_msg_expandable_error:nnn { nnf } % \end{macrocode} % \end{macro} % |