diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3basics.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex/l3kernel/l3basics.dtx | 417 |
1 files changed, 265 insertions, 152 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3basics.dtx b/Master/texmf-dist/source/latex/l3kernel/l3basics.dtx index f37f4bcc4b4..260e328e5c8 100644 --- a/Master/texmf-dist/source/latex/l3kernel/l3basics.dtx +++ b/Master/texmf-dist/source/latex/l3kernel/l3basics.dtx @@ -41,7 +41,7 @@ % }^^A % } % -% \date{Released 2017/05/29} +% \date{Released 2017/07/15} % % \maketitle % @@ -98,11 +98,11 @@ % \end{syntax} % Adds \meta{token} to the list of \meta{tokens} to be inserted % when the current group level ends. The list of \meta{tokens} to be -% inserted will be empty at the beginning of a group: multiple +% inserted is empty at the beginning of a group: multiple % applications of \cs{group_insert_after:N} may be used to build % the inserted list one \meta{token} at a time. The current group % level may be closed by a \cs{group_end:} function or by a token -% with category code $2$ (close-group). The later will be a ^^A{ +% with category code $2$ (close-group), namely a ^^A{ % |}| if standard category codes apply. % \end{function} % @@ -115,7 +115,7 @@ % arguments absorbed by the function. In the following, \meta{code} % is therefore used as a shorthand for \enquote{replacement text}. % -% Functions which are not \enquote{protected} will be fully expanded +% Functions which are not \enquote{protected} are fully expanded % inside an \texttt{x} expansion. In contrast, \enquote{protected} % functions are not expanded within \texttt{x} expansions. % @@ -124,7 +124,7 @@ % Functions can be created with no requirement that they are declared % first (in contrast to variables, which must always be declared). % Declaring a function before setting up the code means that the name -% chosen will be checked and an error raised if it is already in use. +% chosen is checked and an error raised if it is already in use. % The name of a function can be checked at the point of definition using % the \cs[no-index]{cs_new\ldots} functions: this is recommended for all % functions which are defined for the first time. @@ -136,17 +136,17 @@ % \begin{description} % \item[\texttt{new}] % Create a new function with the \texttt{new} scope, -% such as \cs{cs_new:Npn}. The definition is global and will result in +% such as \cs{cs_new:Npn}. The definition is global and results in % an error if it is already defined. % \item[\texttt{set}] % Create a new function with the \texttt{set} scope, % such as \cs{cs_set:Npn}. The definition is restricted to the current -% \TeX{} group and will not result in an error if the function is already +% \TeX{} group and does not result in an error if the function is already % defined. % \item[\texttt{gset}] % Create a new function with the \texttt{gset} scope, % such as \cs{cs_gset:Npn}. The definition is global and -% will not result in an error if the function is already defined. +% does not result in an error if the function is already defined. % \end{description} % % Within each set of scope there are different ways to define a function. @@ -193,7 +193,7 @@ % Creates \meta{function} to expand to \meta{code} as replacement text. % Within the \meta{code}, the \meta{parameters} (|#1|, |#2|, % \emph{etc.}) will be replaced by those absorbed by the function. -% The definition is global and an error will result if the +% The definition is global and an error results if the % \meta{function} is already defined. % \end{function} % @@ -210,7 +210,7 @@ % \emph{etc.}) will be replaced by those absorbed by the function. % When the \meta{function} is used the \meta{parameters} absorbed % cannot contain \cs{par} tokens. The definition is global and -% an error will result if the \meta{function} is already defined. +% an error results if the \meta{function} is already defined. % \end{function} % % \begin{function} @@ -225,7 +225,7 @@ % Within the \meta{code}, the \meta{parameters} (|#1|, |#2|, % \emph{etc.}) will be replaced by those absorbed by the function. % The \meta{function} will not expand within an \texttt{x}-type -% argument. The definition is global and an error will result if the +% argument. The definition is global and an error results if the % \meta{function} is already defined. % \end{function} % @@ -243,7 +243,7 @@ % When the \meta{function} is used the \meta{parameters} absorbed % cannot contain \cs{par} tokens. The \meta{function} will not % expand within an \texttt{x}-type argument. The definition is global -% and an error will result if the \meta{function} is already defined. +% and an error results if the \meta{function} is already defined. % \end{function} % % \begin{function}{\cs_set:Npn, \cs_set:cpn, \cs_set:Npx, \cs_set:cpx} @@ -388,7 +388,7 @@ % automatically from the function signature. These \meta{parameters} % (|#1|, |#2|, \emph{etc.}) will be replaced by those absorbed by the % function. The definition is global and -% an error will result if the \meta{function} is already defined. +% an error results if the \meta{function} is already defined. % \end{function} % % \begin{function} @@ -405,7 +405,7 @@ % (|#1|, |#2|, \emph{etc.}) will be replaced by those absorbed by the % function. When the \meta{function} is used the \meta{parameters} % absorbed cannot contain \cs{par} tokens. The definition is global and -% an error will result if the \meta{function} is already defined. +% an error results if the \meta{function} is already defined. % \end{function} % % \begin{function} @@ -422,7 +422,7 @@ % (|#1|, |#2|, \emph{etc.}) will be replaced by those absorbed by the % function. The \meta{function} will not expand within an \texttt{x}-type % argument. The definition is global and -% an error will result if the \meta{function} is already defined. +% an error results if the \meta{function} is already defined. % \end{function} % % \begin{function} @@ -440,7 +440,7 @@ % function. When the \meta{function} is used the \meta{parameters} % absorbed cannot contain \cs{par} tokens. The \meta{function} will not % expand within an \texttt{x}-type argument. The definition is global and -% an error will result if the \meta{function} is already defined. +% an error results if the \meta{function} is already defined. % \end{function} % % \begin{function} @@ -670,8 +670,7 @@ % \cs{cs_meaning:N} \meta{control sequence} % \end{syntax} % This function expands to the \emph{meaning} of the \meta{control sequence} -% control sequence. This will show the \meta{replacement text} for a -% macro. +% control sequence. For a macro, this includes the \meta{replacement text}. % \begin{texnote} % This is \TeX{}'s \tn{meaning} primitive. % The \texttt{c} variant correctly reports undefined arguments. @@ -710,8 +709,8 @@ % The content for \meta{control sequence name} may be literal % material or from other expandable functions. The % \meta{control sequence name} must, when fully expanded, consist -% of character tokens which are not active: typically, they will -% be of category code $10$ (space), $11$ (letter) +% of character tokens which are not active: typically +% of category code $10$ (space), $11$ (letter) % or $12$ (other), or a mixture of these. % \end{function} % @@ -752,8 +751,8 @@ % The content for \meta{control sequence name} may be literal % material or from other expandable functions. The % \meta{control sequence name} must, when fully expanded, consist -% of character tokens which are not active: typically, they will -% be of category code $10$ (space), $11$ (letter) +% of character tokens which are not active: typically +% of category code $10$ (space), $11$ (letter) % or $12$ (other), or a mixture of these. % \begin{texnote} % These are the \TeX{} primitives \tn{csname} and \tn{endcsname}. @@ -782,22 +781,22 @@ % \end{syntax} % Converts the given \meta{control sequence} into a series of % characters with category code $12$ (other), except spaces, -% of category code $10$. The sequence will \emph{not} include -% the current escape token, \emph{cf.}~\cs{token_to_str:N}. +% of category code $10$. The result does \emph{not} include +% the current escape token, contrarily to \cs{token_to_str:N}. % Full expansion of this function requires exactly $2$ expansion % steps, and so an \texttt{x}-type expansion, or two -% \texttt{o}-type expansions will be required to +% \texttt{o}-type expansions are required to % convert the \meta{control sequence} to a sequence of characters % in the input stream. In most cases, an \texttt{f}-expansion -% will be correct as well, but this loses a space at the start +% is correct as well, but this loses a space at the start % of the result. % \end{function} % % \section{Using or removing tokens and arguments} % % Tokens in the input can be read and used or read and discarded. -% If one or more tokens are wrapped in braces then in absorbing them -% the outer set will be removed. At the same time, the category code +% If one or more tokens are wrapped in braces then when absorbing them +% the outer set is removed. At the same time, the category code % of each token is set when the token is read by a function (if it % is read more than once, the category code is determined by % the situation in force when first function absorbs the token). @@ -809,21 +808,21 @@ % \cs{use:nnn} \Arg{group_1} \Arg{group_2} \Arg{group_3} % \cs{use:nnnn} \Arg{group_1} \Arg{group_2} \Arg{group_3} \Arg{group_4} % \end{syntax} -% As illustrated, these functions will absorb between one and four +% As illustrated, these functions absorb between one and four % arguments, as indicated by the argument specifier. The braces -% surrounding each argument will be removed leaving the remaining -% tokens in the input stream. The category code of these tokens will -% also be fixed by this process (if it has not already been by some +% surrounding each argument are removed and the remaining tokens are +% left in the input stream. The category code of these tokens is +% also fixed by this process (if it has not already been by some % other absorption). All of these functions require only a single % expansion to operate, so that one expansion of % \begin{verbatim} % \use:nn { abc } { { def } } % \end{verbatim} -% will result in the input stream containing +% results in the input stream containing % \begin{verbatim} % abc { def } % \end{verbatim} -% \emph{i.e.} only the outer braces will be removed. +% \emph{i.e.} only the outer braces are removed. % \end{function} % % \begin{function}[EXP]{\use_i:nn, \use_ii:nn} @@ -836,7 +835,7 @@ % the first argument and leaves the content of the second argument in % the input stream. % The category code -% of these tokens will also be fixed (if it has not already been by +% of these tokens is also fixed (if it has not already been by % some other absorption). A single expansion is needed for the % functions to take effect. % \end{function} @@ -851,7 +850,7 @@ % \cs{use_ii:nnn} and \cs{use_iii:nnn} work similarly, leaving the % content of second or third arguments in the input stream, respectively. % The category code -% of these tokens will also be fixed (if it has not already been by +% of these tokens is also fixed (if it has not already been by % some other absorption). A single expansion is needed for the % functions to take effect. % \end{function} @@ -868,7 +867,7 @@ % \cs{use_ii:nnnn}, \cs{use_iii:nnnn} and \cs{use_iv:nnnn} work similarly, % leaving the content of second, third or fourth arguments in the input % stream, respectively. The category code -% of these tokens will also be fixed (if it has not already been by +% of these tokens is also fixed (if it has not already been by % some other absorption). A single expansion is needed for the % functions to take effect. % \end{function} @@ -877,20 +876,20 @@ % \begin{syntax} % \cs{use_i_ii:nnn} \Arg{arg_1} \Arg{arg_2} \Arg{arg_3} % \end{syntax} -% This functions will absorb three arguments and leave the content of the +% This function absorbs three arguments and leaves the content of the % first and second in the input stream. The category code of -% these tokens will also be fixed (if it has not already been by +% these tokens is also fixed (if it has not already been by % some other absorption). A single expansion is needed for the -% functions to take effect. An example: +% function to take effect. An example: % \begin{verbatim} % \use_i_ii:nnn { abc } { { def } } { ghi } % \end{verbatim} -% will result in the input stream containing +% results in the input stream containing % \begin{verbatim} % abc { def } % \end{verbatim} -% \emph{i.e.} the outer braces will be removed and the third group -% will be removed. +% \emph{i.e.} the outer braces are removed and the third group +% is removed. % \end{function} % % \begin{function}[EXP] @@ -974,17 +973,17 @@ % \begin{quote} % |\cs_if_free:cTF {abc}| \Arg{true code} \Arg{false code} % \end{quote} -% a function that will turn the first argument into a control sequence +% a function that turns the first argument into a control sequence % (since it's marked as |c|) then checks whether this control sequence -% is still free and then depending on the result carry out the code in +% is still free and then depending on the result carries out the code in % the second argument (true case) or in the third argument (false % case). % % These type of functions are known as \enquote{conditionals}; -% whenever a |TF| function is defined it will usually be accompanied by +% whenever a |TF| function is defined it is usually accompanied by % |T| and |F| functions as well. These are provided for convenience when % the branch only needs to go a single way. Package writers are free to -% choose which types to define but the kernel definitions will always +% choose which types to define but the kernel definitions always % provide all three versions. % % Important to note is that these branching conditionals with \meta{true @@ -993,7 +992,7 @@ % the input stream. % % These conditional functions may or may not be fully expandable, but if -% they are expandable they will be accompanied by a \enquote{predicate} +% they are expandable they are accompanied by a \enquote{predicate} % for the same test as described below. % % \item[Predicates] @@ -1016,8 +1015,8 @@ % \Arg{true code} \Arg{false code} % \end{quote} % -% For each predicate defined, a \enquote{branching conditional} will -% also exist that behaves like a conditional described above. +% For each predicate defined, a \enquote{branching conditional} +% also exists that behaves like a conditional described above. % % \item[Primitive conditionals] % There is a third variety of conditional, which is the original @@ -1052,7 +1051,7 @@ % \end{syntax} % Tests whether the \meta{control sequence} is currently defined % (whether as a function or another control sequence type). Any -% valid definition of \meta{control sequence} will evaluate as +% valid definition of \meta{control sequence} evaluates as % \texttt{true}. % \end{function} % @@ -1062,7 +1061,7 @@ % \cs{cs_if_free:NTF} \meta{control sequence} \Arg{true code} \Arg{false code} % \end{syntax} % Tests whether the \meta{control sequence} is currently free to -% be defined. This test will be \texttt{false} if the +% be defined. This test is \texttt{false} if the % \meta{control sequence} currently exists (as defined by % \cs{cs_if_exist:N}). % \end{function} @@ -1071,13 +1070,13 @@ % % The \eTeX{} engine itself provides many different conditionals. Some % expand whatever comes after them and others don't. Hence the names -% for these underlying functions will often contain a |:w| part but +% for these underlying functions often contains a |:w| part but % higher level functions are often available. See for instance % \cs{int_compare_p:nNn} which is a wrapper for \cs{if_int_compare:w}. % % Certain conditionals deal with specific data types like boxes and % fonts and are described there. The ones described below are either -% the universal conditionals or deal with control sequences. We will +% the universal conditionals or deal with control sequences. We % prefix primitive conditionals with |\if_|. % % \begin{function}[EXP] @@ -1116,7 +1115,7 @@ % "\if:w" <token_1> <token_2> <true code> "\else:" <false code> "\fi:" \\ % "\if_catcode:w" <token_1> <token_2> <true code> "\else:" <false code> "\fi:" % \end{syntax} -% These conditionals will expand any following tokens until two +% These conditionals expand any following tokens until two % unexpandable tokens are left. If you wish to prevent this expansion, % prefix the token in question with "\exp_not:N". "\if_catcode:w" % tests if the category codes of the two tokens are the same whereas @@ -1178,21 +1177,39 @@ % \texttt{check-declarations} is active. % \end{function} % -% \begin{function}{\__chk_log:x} +% \begin{function}{\__debug_log:x} % \begin{syntax} -% \cs{__chk_log:x} \Arg{message text} +% \cs{__debug_log:x} \Arg{message text} % \end{syntax} -% If the \texttt{log-functions} option is active, this function writes -% the \meta{message text} to the log file using \cs{iow_log:x}. -% Otherwise, the \meta{message text} is ignored using \cs{use_none:n}. +% Only defined when debugging is enabled (hence only in package mode +% with the right options). If the \texttt{log-functions} option is +% active, this function writes the \meta{message text} to the log file +% using \cs{iow_log:x}. Otherwise, the \meta{message text} is ignored +% using \cs{use_none:n}. % \end{function} % -% \begin{function}{\__chk_suspend_log:, \__chk_resume_log:} +% \begin{function}{\__debug_suspend_log:, \__debug_resume_log:} % \begin{syntax} -% \cs{__chk_suspend_log:} \ldots{} \cs{__chk_log:x} \ldots{} \cs{__chk_resume_log:} +% \cs{__debug_suspend_log:} \ldots{} \cs{__debug_log:x} \ldots{} \cs{__debug_resume_log:} % \end{syntax} -% Any \cs{__chk_log:x} command between \cs{__chk_suspend_log:} and -% \cs{__chk_resume_log:} is suppressed. These commands can be nested. +% Any \cs{__debug_log:x} command between \cs{__debug_suspend_log:} and +% \cs{__debug_resume_log:} is suppressed. These two commands can be +% nested and do nothing when debugging is disabled. +% \end{function} +% +% \begin{function}{\__debug_patch:nnNw} +% \begin{syntax} +% \cs{__debug_patch:nnNw} \Arg{before} \Arg{after} \meta{definition} \ldots{} +% \end{syntax} +% If debugging is enabled (by one of few \pkg{expl3} options that +% imply \texttt{enable-debug}), adds the \meta{before} and +% \meta{after} tokens (which can involve |#1| and so on) in the +% \meta{definition} that follows. Otherwise ignore the \meta{before} +% and \meta{after} code and perform the \meta{definition} with no +% patching. The \meta{definition} must start with \cs{cs_new:Npn} or +% \cs{cs_set:Npn} or \cs{cs_gset:Npn} or \cs{prg_new_conditional:Npnn} +% or their protected counterparts. Other cases could be added as +% needed. % \end{function} % % \begin{function}[EXP]{\__cs_count_signature:N, \__cs_count_signature:c} @@ -1216,7 +1233,7 @@ % \meta{processor} function in three parts: the \meta{name}, the % \meta{signature} and a logic token indicating if a colon was found % (to differentiate variables from function names). The \meta{name} -% will not include the escape character, and both the \meta{name} and +% does not include the escape character, and both the \meta{name} and % \meta{signature} are made up of tokens with category code $12$ % (other). The \meta{processor} should be a function with argument % specification \texttt{:nnN} (plus any trailing arguments needed). @@ -1291,7 +1308,7 @@ % % Having given all the \TeX{} primitives a consistent name, we need to % give sensible names to the ones we actually want to use. -% These will be defined as needed in the appropriate modules, but +% These will be defined as needed in the appropriate modules, but we % do a few now, just to get started.\footnote{This renaming gets expensive % in terms of csname usage, an alternative scheme would be to just use % the \cs[no-index]{tex_\ldots:D} name in the cases where no good alternative exists.} @@ -1633,7 +1650,7 @@ % following the |:| in the name. Although we could define functions to % remove ten arguments or more using separate calls of % \cs{use_none:nnnnn}, this is very non-intuitive to the programmer -% who will assume that expanding such a function once will take care +% who will assume that expanding such a function once takes care % of gobbling all the tokens in one go. % \begin{macrocode} \cs_set:Npn \use_none:n #1 { } @@ -1673,9 +1690,9 @@ % interface. % % \begin{macro}[EXP]{\prg_return_true:, \prg_return_false:} -% The idea here is that \cs{exp:w} will expand fully any -% \cs{else:} and the \cs{fi:} that are waiting to be discarded, -% before reaching the \cs{exp_end:} which will leave the expansion null. +% The idea here is that \cs{exp:w} expands fully any +% \cs{else:} and \cs{fi:} that are waiting to be discarded, +% before reaching the \cs{exp_end:} which leaves an empty expansion. % The code can then leave either the first or second argument in the % input stream. This means that all of the branching code has to contain % at least two tokens: see how the logical tests are actually implemented @@ -1688,7 +1705,7 @@ % \end{macrocode} % An extended state space could be implemented by including a more % elaborate function in place of \cs{use_i:nn}/\cs{use_ii:nn}. Provided -% two arguments are absorbed then the code will work. +% two arguments are absorbed then the code would work. % \end{macro} % % \begin{macro} @@ -1853,7 +1870,7 @@ % text (or empty), 6: replacement. Remember that the logic-returning % functions expect two arguments to be present after \cs{exp_end:}: % notice the construction of the different variants relies on this, -% and that the |TF| variant will be slightly faster than the |T| +% and that the |TF| and |F| variants will be slightly faster than the |T| % version. The |p| form is only valid for expandable tests, we check % for that by making sure that the second argument is empty. % \begin{macrocode} @@ -2261,7 +2278,7 @@ % \end{macrocode} % \end{macro} % -% \subsection{Defining and checking (new) functions} +% \subsection{Checking and patching (new) functions} % % We provide two kinds of functions that can be used to define % control sequences. On the one hand we have functions that check @@ -2269,63 +2286,10 @@ % |\..._new|. The second type of defining functions doesn't check % if the argument is already defined. % -% Before we can define them, we need some auxiliary macros that -% allow us to generate error messages. The definitions here are +% Before we can define them, we need some auxiliary macros that allow +% us to generate error messages. The next few definitions here are % only temporary, they will be redefined later on. % -% \begin{macro}[documented-as=\iow_log:n]{\iow_log:x, \iow_term:x} -% We define a routine to write only to the log file. And a -% similar one for writing to both the log file and the terminal. -% These will be redefined later by \pkg{l3io}. -% \begin{macrocode} -\cs_set_protected:Npn \iow_log:x - { \tex_immediate:D \tex_write:D -1 } -\cs_set_protected:Npn \iow_term:x - { \tex_immediate:D \tex_write:D 16 } -% \end{macrocode} -% \end{macro} -% -% \begin{macro}[int]{\__chk_log:x, \__chk_suspend_log:, \__chk_resume_log:} -% This function is used to write some information to the \texttt{log} -% file in case the |log-function| option is set. Otherwise its -% argument is ignored. Using this function rather than directly using -% \cs{iow_log:x} allows for \cs{__chk_suspend_log:} which disables -% such messages until the matching \cs{__chk_resume_log:}. These two -% commands are used to improve the logging for complicated datatypes. -% They should come in pairs, which can be nested. The function -% \cs{exp_not:o} is defined in \pkg{l3expan} later on but -% \cs{__chk_suspend_log:} and \cs{__chk_resume_log:} are not used -% before that point. -% \begin{macrocode} -%<*initex> -\cs_set_protected:Npn \__chk_log:x { \use_none:n } -\cs_set_protected:Npn \__chk_suspend_log: { } -\cs_set_protected:Npn \__chk_resume_log: { } -%</initex> -%<*package> -\tex_ifodd:D \l@expl@log@functions@bool - \cs_set_protected:Npn \__chk_log:x { \iow_log:x } - \cs_set_protected:Npn \__chk_suspend_log: - { - \cs_set_protected:Npx \__chk_resume_log: - { - \cs_set_protected:Npn \__chk_resume_log: - { \exp_not:o { \__chk_resume_log: } } - \cs_set_protected:Npn \__chk_log:x - { \exp_not:o { \__chk_log:x } } - } - \cs_set_protected:Npn \__chk_log:x { \use_none:n } - } - \cs_set_protected:Npn \__chk_resume_log: { } -\else: - \cs_set_protected:Npn \__chk_log:x { \use_none:n } - \cs_set_protected:Npn \__chk_suspend_log: { } - \cs_set_protected:Npn \__chk_resume_log: { } -\fi: -%</package> -% \end{macrocode} -% \end{macro} -% % \begin{macro}[int] % {\__msg_kernel_error:nnxx, \__msg_kernel_error:nnx, \__msg_kernel_error:nn} % If an internal error occurs before \LaTeX3 has loaded \pkg{l3msg} then @@ -2362,6 +2326,142 @@ % \end{macrocode} % \end{macro} % +% \begin{macro}[documented-as=\iow_log:n]{\iow_log:x, \iow_term:x} +% We define a routine to write only to the log file. And a +% similar one for writing to both the log file and the terminal. +% These will be redefined later by \pkg{l3io}. +% \begin{macrocode} +\cs_set_protected:Npn \iow_log:x + { \tex_immediate:D \tex_write:D -1 } +\cs_set_protected:Npn \iow_term:x + { \tex_immediate:D \tex_write:D 16 } +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\debug_log_functions_on:, \debug_log_functions_off:} +% \begin{macro}[int]{\__debug_log:x, \__debug_suspend_log:, \__debug_resume_log:} +% When debugging is not enabled at all (including in the format), the +% \cs[index=debug_log_functions_on:]{debug_log_functions_on/off:} +% functions simply produce errors, while \cs{__debug_suspend_log:} and +% \cs{__debug_resume_log:} do nothing. +% \begin{macrocode} +\cs_set_protected:Npn \debug_log_functions_on: + { + \__msg_kernel_error:nnx { kernel } { enable-debug } + { \token_to_str:N \debug_log_functions_on: } + } +\cs_set_protected:Npn \debug_log_functions_off: + { + \__msg_kernel_error:nnx { kernel } { enable-debug } + { \token_to_str:N \debug_log_functions_off: } + } +\cs_set_protected:Npn \__debug_suspend_log: { } +\cs_set_protected:Npn \__debug_resume_log: { } +% \end{macrocode} +% Otherwise, they set up \cs{__debug_log:x}, +% \cs{__debug_suspend_log:}, and \cs{__debug_resume_log:} to have the +% following behaviour. The function \cs{__debug_log:x} is used to +% write some information to the \texttt{log} file in case the +% \texttt{log-function} option is active and to otherwise ignore its +% argument. Using this function rather than directly using +% \cs{iow_log:x} allows for \cs{__debug_suspend_log:} which disables +% such messages until the matching \cs{__debug_resume_log:}. These +% two commands are used to improve the logging for datatypes with +% multiple parts (currently only coffins). They should come in pairs, +% which can be nested. The function \cs{exp_not:o} is defined in +% \pkg{l3expan} later on but \cs{__debug_suspend_log:} and +% \cs{__debug_resume_log:} are not used before that point. Once +% everything is defined, turn logging on or off depending on what +% option was given. +% \begin{macrocode} +%<*package> +\tex_ifodd:D \l@expl@enable@debug@bool + \cs_set_protected:Npn \debug_log_functions_on: + { + \cs_set_protected:Npn \__debug_log:x { \iow_log:x } + \cs_set_protected:Npn \__debug_suspend_log: + { + \cs_set_protected:Npx \__debug_resume_log: + { + \cs_set_protected:Npn \__debug_resume_log: + { \exp_not:o { \__debug_resume_log: } } + \cs_set_protected:Npn \__debug_log:x + { \exp_not:o { \__debug_log:x } } + } + \cs_set_protected:Npn \__debug_log:x { \use_none:n } + } + \cs_set_protected:Npn \__debug_resume_log: { } + } + \cs_set_protected:Npn \debug_log_functions_off: + { + \cs_set_protected:Npn \__debug_log:x { \use_none:n } + \cs_set_protected:Npn \__debug_suspend_log: { } + \cs_set_protected:Npn \__debug_resume_log: { } + } + \tex_ifodd:D \l@expl@log@functions@bool + \debug_log_functions_on: + \else: + \debug_log_functions_off: + \fi: +\fi: +%</package> +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% \begin{macro}[int]{\__debug_patch:nnNw} +% \begin{macro}[aux] +% { +% \__debug_patch_param:NNnnNnp, +% \__debug_patch_new:nnNNnn, +% \__debug_patch_new_conditional:nnNNnnn +% } +% When debugging is not enabled, \cs{__debug_patch:nnNw} throws the +% patch away. Otherwise it can be followed by \cs{cs_new:Npn} or +% \cs{prg_new_conditional:Npnn} or their protected counterparts. In +% each case, grab the name of the function to be defined and its +% parameters using \cs{__debug_patch_param:w} then insert tokens +% before and after the definition. Of course for a conditional one +% should likely not insert anything after the code. +% \begin{macrocode} +\cs_set_protected:Npn \__debug_patch:nnNw #1#2 { } +%<*package> +\tex_ifodd:D \l@expl@enable@debug@bool + \cs_set_protected:Npn \__debug_patch:nnNw #1#2#3 + { + \tex_ifcase:D + \if_meaning:w #3 \cs_new_protected:Npn 1~ \fi: + \if_meaning:w #3 \cs_new:Npn 1~ \fi: + \if_meaning:w #3 \cs_set_protected:Npn 1~ \fi: + \if_meaning:w #3 \cs_set:Npn 1~ \fi: + \if_meaning:w #3 \cs_gset_protected:Npn 1~ \fi: + \if_meaning:w #3 \cs_gset:Npn 1~ \fi: + \if_meaning:w #3 \prg_new_protected_conditional:Npnn 2~ \fi: + \if_meaning:w #3 \prg_new_conditional:Npnn 2~ \fi: + \__msg_kernel_error:nnx { kernel } { debug-unpatchable } + { \token_to_str:N #3 } + \or: + \exp_after:wN \__debug_patch_param:NNnnNnp + \exp_after:wN \__debug_patch_new:nnNNnn + \else: + \exp_after:wN \__debug_patch_param:NNnnNnp + \exp_after:wN \__debug_patch_new_conditional:nnNNnnn + \fi: + \use_none:nn {#1} {#2} #3 + } + \cs_set_protected:Npn \__debug_patch_param:NNnnNnp #1#2#3#4#5#6#7# + { #1 {#3} {#4} #5 #6 {#7} } + \cs_set_protected:Npn \__debug_patch_new:nnNNnn #1#2#3#4#5#6 + { #3 #4 #5 { #1 #6 #2 } } + \cs_set_protected:Npn \__debug_patch_new_conditional:nnNNnnn + #1#2#3#4#5#6#7 + { #3 #4 #5 {#6} { #1 #7 #2 } } +\fi: +%</package> +% \end{macrocode} +% \end{macro} +% \end{macro} +% % \begin{macro}[int]{\__chk_if_free_cs:N, \__chk_if_free_cs:c} % This command is called by \cs{cs_new_nopar:Npn} and \cs{cs_new_eq:NN} % \emph{etc.}\ @@ -2371,6 +2471,8 @@ % issued. We have to make sure we don't put the argument into the % conditional processing since it may be an |\if...| type function! % \begin{macrocode} +\__debug_patch:nnNw { } + { \__debug_log:x { Defining~\token_to_str:N #1~ \msg_line_context: } } \cs_set_protected:Npn \__chk_if_free_cs:N #1 { \cs_if_free:NF #1 @@ -2378,43 +2480,54 @@ \__msg_kernel_error:nnxx { kernel } { command-already-defined } { \token_to_str:N #1 } { \token_to_meaning:N #1 } } -} -%<*package> -\tex_ifodd:D \l@expl@log@functions@bool - \cs_set_protected:Npn \__chk_if_free_cs:N #1 - { - \cs_if_free:NF #1 - { - \__msg_kernel_error:nnxx { kernel } { command-already-defined } - { \token_to_str:N #1 } { \token_to_meaning:N #1 } - } - \__chk_log:x { Defining~\token_to_str:N #1~ \msg_line_context: } - } -\fi: -%</package> + } \cs_set_protected:Npn \__chk_if_free_cs:c { \exp_args:Nc \__chk_if_free_cs:N } % \end{macrocode} % \end{macro} % +% \begin{macro}{\debug_check_declarations_on:, \debug_check_declarations_off:} % \begin{macro}[int]{\__chk_if_exist_var:N} -% Create the checking function for variable definitions when the option -% is set. +% When debugging is not active these two user functions produce an +% error. Otherwise they set up \cs{__chk_if_exist_var:N}, a function +% which when \texttt{check-declarations} is active tests that a given +% variable is defined. % \begin{macrocode} +\cs_set_protected:Npn \debug_check_declarations_on: + { + \__msg_kernel_error:nnx { kernel } { enable-debug } + { \token_to_str:N \debug_check_declarations_on: } + } +\cs_set_protected:Npn \debug_check_declarations_off: + { + \__msg_kernel_error:nnx { kernel } { enable-debug } + { \token_to_str:N \debug_check_declarations_off: } + } %<*package> -\tex_ifodd:D \l@expl@check@declarations@bool - \cs_set_protected:Npn \__chk_if_exist_var:N #1 +\tex_ifodd:D \l@expl@enable@debug@bool + \cs_set_protected:Npn \debug_check_declarations_on: { - \cs_if_exist:NF #1 + \cs_set_protected:Npn \__chk_if_exist_var:N ##1 { - \__msg_kernel_error:nnx { check } { non-declared-variable } - { \token_to_str:N #1 } + \cs_if_exist:NF ##1 + { + \__msg_kernel_error:nnx { check } { non-declared-variable } + { \token_to_str:N ##1 } + } } } + \cs_set_protected:Npn \debug_check_declarations_off: + { \cs_set_protected:Npn \__chk_if_exist_var:N ##1 { } } + \tex_ifodd:D \l@expl@check@declarations@bool + \debug_check_declarations_on: + \else: + \debug_check_declarations_off: + \fi: \fi: %</package> % \end{macrocode} % \end{macro} +% \end{macro} % % \begin{macro}[int]{\__chk_if_exist_cs:N, \__chk_if_exist_cs:c} % This function issues an error message when the control sequence @@ -2433,7 +2546,7 @@ % \end{macrocode} % \end{macro} % -% \subsection{More new definitions} +% \subsection{Defining new functions} % % \begin{macro} % { @@ -2478,8 +2591,8 @@ % stands for csname argument, see the expansion module). Global % versions are also provided. % -% \cs{cs_set_nopar:cpn}\meta{string}\meta{rep-text} will turn \meta{string} -% into a csname and then assign \meta{rep-text} to it by using +% \cs{cs_set_nopar:cpn}\meta{string}\meta{rep-text} turns \meta{string} +% into a csname and then assigns \meta{rep-text} to it by using % \cs{cs_set_nopar:Npn}. This means that there might be a parameter % string between the two arguments. % \begin{macrocode} |