summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/l3kernel/l3basics.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3basics.dtx')
-rw-r--r--Master/texmf-dist/source/latex/l3kernel/l3basics.dtx417
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}