path: root/Master/texmf-dist/source/latex/l3kernel/l3kernel-functions.dtx

% \iffalse meta-comment
%
%% File: l3kernel-functions.dtx
%
% Copyright (C) 2018-2021 The LaTeX Project
%
% It may be distributed and/or modified under the conditions of the
% LaTeX Project Public License (LPPL), either version 1.3c of this
% license or (at your option) any later version.  The latest version
% of this license is in the file
%
%    https://www.latex-project.org/lppl.txt
%
% This file is part of the "l3kernel bundle" (The Work in LPPL)
% and all files in that bundle must be distributed together.
%
% -----------------------------------------------------------------------
%
% The development version of the bundle can be found at
%
%    https://github.com/latex3/latex3
%
% for those people who are interested.
%
%<*driver>
\documentclass[full,kernel]{l3doc}
\begin{document}
  \DocInput{\jobname.dtx}
\end{document}
%</driver>
% \fi
%
% \title{^^A
%   The \pkg{l3kernel-functions} package\\ Kernel-reserved functions^^A
% }
%
% \author{^^A
%  The \LaTeX{} Project\thanks
%    {^^A
%      E-mail:
%        \href{mailto:latex-team@latex-project.org}
%          {latex-team@latex-project.org}^^A
%    }^^A
% }
%
% \date{Released 2021-02-06}
%
% \maketitle
%
% \begin{documentation}
%
% \end{documentation}
%
% \begin{implementation}
%
% \section{Internal kernel functions}
%
% \begin{function}{\__kernel_chk_cs_exist:N, \__kernel_chk_cs_exist:c}
%   \begin{syntax}
%     \cs{__kernel_chk_cs_exist:N} \meta{cs}
%   \end{syntax}
%   This function is only created if debugging is enabled.  It checks
%   that \meta{cs} exists according to the criteria for
%   \cs{cs_if_exist_p:N}, and if not raises a kernel-level error.
% \end{function}
%
% \begin{function}{\__kernel_chk_defined:NT}
%   \begin{syntax}
%     \cs{__kernel_chk_defined:NT} \meta{variable} \Arg{true code}
%   \end{syntax}
%   If \meta{variable} is not defined (according to
%   \cs{cs_if_exist:NTF}), this triggers an error, otherwise the
%   \meta{true code} is run.
% \end{function}
%
% \begin{function}{\__kernel_chk_expr:nNnN}
%   \begin{syntax}
%     \cs{__kernel_chk_expr:nNnN} \Arg{expr} \meta{eval} \Arg{convert} \meta{caller}
%   \end{syntax}
%   This function is only created if debugging is enabled.  By default
%   it is equivalent to \cs{use_i:nnnn}.  When expression checking is
%   enabled, it leaves in the input stream the result of \cs{tex_the:D}
%   \meta{eval} \meta{expr} \cs{tex_relax:D} after checking that no
%   token was left over.  If any token was not taken as part of the
%   expression, there is an error message displaying the result of the
%   evaluation as well as the \meta{caller}.  For instance \meta{eval}
%   can be \cs{__int_eval:w} and \meta{caller} can be \cs{int_eval:n} or
%   \cs{int_set:Nn}.  The argument \meta{convert} is empty except for mu
%   expressions where it is \cs{tex_mutoglue:D}, used for internal
%   purposes.
% \end{function}
%
% \begin{function}{\__kernel_cs_parm_from_arg_count:nnF}
%   \begin{syntax}
%     \cs{__kernel_cs_parm_from_arg_count:nnF} \Arg{follow-on} \Arg{args} \Arg{false code}
%   \end{syntax}
%   Evaluates the number of \meta{args} and leaves the \meta{follow-on} code
%   followed by a brace group containing the required number of primitive
%   parameter markers (|#1|, \emph{etc}.). If the number of \meta{args} is outside
%   the range $[0,9]$, the \meta{false code} is inserted \emph{instead} of
%   the \meta{follow-on}.
% \end{function}
%
% \begin{function}{
%     \__kernel_dependency_version_check:Nn,
%     \__kernel_dependency_version_check:nn,
%   }
%   \begin{syntax}
%     \cs{__kernel_dependency_version_check:Nn} \Arg{\cs{date}} \Arg{file}
%     \cs{__kernel_dependency_version_check:nn} \Arg{date} \Arg{file}
%   \end{syntax}
%   Checks if the loaded version of the \pkg{expl3} kernel is at least \meta{date},
%   required by \meta{file}.  If the kernel date is older than \meta{date}, the
%   loading of \meta{file} is aborted and an error is raised.
% \end{function}
%
% \begin{function}{\__kernel_deprecation_code:nn}
%   \begin{syntax}
%     \cs{__kernel_deprecation_code:nn} \Arg{error code} \Arg{working code}
%   \end{syntax}
%   Stores both an \meta{error} and \meta{working} definition for given material
%   such that they can be exchanged by \cs{debug_on:} and \cs{debug_off:}.
% \end{function}
%
% \begin{function}[EXP]{\__kernel_exp_not:w}
%   \begin{syntax}
%     \cs{__kernel_exp_not:w} \meta{expandable tokens} \Arg{content}
%   \end{syntax}
%   Carries out expansion on the \meta{expandable tokens} before preventing
%   further expansion of the \meta{content} as for \cs{exp_not:n}. Typically,
%   the \meta{expandable tokens} will alter the nature of the \meta{content},
%   \emph{i.e.}~allow it to be generated in some way.
% \end{function}
%
% \begin{variable}{\l__kernel_expl_bool}
%   A boolean which records the current code syntax status: \texttt{true} if
%   currently inside a code environment. This variable should only be
%   set by \cs{ExplSyntaxOn}/\cs{ExplSyntaxOff}.
% \end{variable}
%
% \begin{variable}{\c__kernel_expl_date_tl}
%   A token list containing the release date of the \pkg{l3kernel} preloaded
%   in \LaTeXe{} used to check if dependencies match.
% \end{variable}
%
% \begin{function}{\__kernel_file_missing:n}
%   \begin{syntax}
%     \cs{__kernel_file_missing:n} \Arg{name}
%   \end{syntax}
%   Expands the \meta{name} as per \cs{__kernel_file_name_sanitize:nN} then
%   produces an error message indicating that this file was not found.
% \end{function}
%
% \begin{function}{\__kernel_file_name_sanitize:nN}
%   \begin{syntax}
%     \cs{__kernel_file_name_sanitize:nN} \Arg{name} \meta{str var}
%   \end{syntax}
%   For converting a \meta{name} to a string where active characters are treated
%   as strings.
% \end{function}
%
% \begin{function}{\__kernel_file_input_push:n, \__kernel_file_input_pop:}
%   \begin{syntax}
%     \cs{__kernel_file_input_push:n} \Arg{name}
%     \cs{__kernel_file_input_pop:}
%   \end{syntax}
%   Used to push and pop data from the internal file stack: needed only
%   in package mode, where interfacing with the \LaTeXe{} kernel is necessary.
% \end{function}
%
% \begin{function}[EXP]{\__kernel_int_add:nnn}
%   \begin{syntax}
%     \cs{__kernel_int_add:nnn} \Arg{integer_1} \Arg{integer_2} \Arg{integer_3}
%   \end{syntax}
%   Expands to the result of adding the three \meta{integers} (which
%   must be suitable input for \cs{int_eval:w}), avoiding intermediate
%   overflow.  Overflow occurs only if the overall result is outside
%   $[-2^{31}+1,2^{31}-1]$.  The \meta{integers} may be of the form
%   \cs{int_eval:w} \dots{} \cs{scan_stop:} but may be evaluated more
%   than once.
% \end{function}
%
% \begin{function}[added = 2018-03-31]{\__kernel_intarray_gset:Nnn}
%   \begin{syntax}
%     \cs{__kernel_intarray_gset:Nnn} \meta{intarray~var} \Arg{index} \Arg{value}
%   \end{syntax}
%   Faster version of \cs{intarray_gset:Nnn}.  Stores the \meta{value}
%   into the \meta{integer array variable} at the \meta{position}.  The
%   \meta{index} and \meta{value} must be suitable for a direct
%   assignment to a \TeX{} count register, for instance expanding to an
%   integer denotation or obtained through the primitive \tn{numexpr}
%   (which may be un-terminated).  No bound checking is performed: the
%   caller is responsible for ensuring that the \meta{position} is
%   between $1$ and the \cs{intarray_count:N}, and the \meta{value}'s
%   absolute value is at most $2^{30}-1$.  Assignments are always
%   global.
% \end{function}
%
% \begin{function}[EXP, added = 2018-03-31]{\__kernel_intarray_item:Nn}
%   \begin{syntax}
%     \cs{__kernel_intarray_item:Nn} \meta{intarray~var} \Arg{index}
%   \end{syntax}
%   Faster version of \cs{intarray_item:Nn}.  Expands to the integer
%   entry stored at the \meta{index} in the \meta{integer array
%   variable}.  The \meta{index} must be suitable for a direct
%   assignment to a \TeX{} count register and must be between $1$ and
%   the \cs{intarray_count:N}, lest a low-level \TeX{} error occur.
% \end{function}
%
% \begin{function}[rEXP, added = 2020-07-12]{\__kernel_intarray_range_to_clist:Nnn}
%   \begin{syntax}
%     \cs{__kernel_intarray_range_to_clist:Nnn} \meta{intarray~var} \Arg{start index} \Arg{end index}
%   \end{syntax}
%   Converts to integer denotations separated by commas the entries of
%   the \meta{intarray} from positions \meta{start index} to \meta{end
%   index} included.  The \meta{start index} and \meta{end index} must
%   be suitable for a direct assignment to a \TeX{} count register, must
%   be between $1$ and the \cs{intarray_count:N}, and be suitably
%   ordered.  All tokens have category code other.
% \end{function}
%
% \begin{function}[added = 2020-07-12]{\__kernel_intarray_gset_range_from_clist:Nnn}
%   \begin{syntax}
%     \cs{__kernel_intarray_gset_range_from_clist:Nnn} \meta{intarray~var} \Arg{start index} \Arg{integer clist}
%   \end{syntax}
%   Stores the entries of the \meta{clist} as entries of the
%   \meta{intarray~var} starting from the \meta{start index}, upwards.
%   This is done without any bound checking.  The \meta{start index} and
%   all entries of the \meta{integer comma list} (which do not undergo
%   space trimming and brace stripping as in normal clist mappings) must
%   be suitable for a direct assignment to a \TeX{} count register.  An
%   empty entry may stop the loop.
% \end{function}
%
% \begin{function}{\__kernel_ior_open:Nn, \__kernel_ior_open:No}
%   \begin{syntax}
%     \cs{__kernel_ior_open:Nn} \meta{stream} \Arg{file name}
%   \end{syntax}
%   This function has identical syntax to the public version. However,
%   is does not take precautions against active characters in the
%   \meta{file name}, and it does not attempt to add a \meta{path} to
%   the \meta{file name}: it is therefore intended to be used by
%   higher-level
%   functions which have already fully expanded the \meta{file name} and which
%   need to perform multiple open or close operations. See for example the
%   implementation of \cs{file_get_full_name:nN},
% \end{function}
%
% \begin{function}{\__kernel_iow_with:Nnn}
%   \begin{syntax}
%     \cs{__kernel_iow_with:Nnn} \meta{integer} \Arg{value} \Arg{code}
%   \end{syntax}
%   If the \meta{integer} is equal to the \meta{value} then this
%   function simply runs the \meta{code}.  Otherwise it saves the
%   current value of the \meta{integer}, sets it to the \meta{value},
%   runs the \meta{code}, and restores the \meta{integer} to its former
%   value.  This is used to ensure that the \tn{newlinechar} is~$10$
%   when writing to a stream, which lets \cs{iow_newline:} work, and
%   that \tn{errorcontextlines} is $-1$ when displaying a message.
% \end{function}
%
% \begin{variable}{\__kernel_kern:n}
%   \begin{syntax}
%     \cs{__kernel_kern:n} \Arg{length}
%   \end{syntax}
%   Inserts a kern of the specified \meta{length}, a dimension expression.
% \end{variable}
%
% \begin{function}
%   {\__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}
%   {\__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}
%   {
%     \__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}
%   {
%     \__kernel_msg_critical:nnnnnn ,
%     \__kernel_msg_critical:nnnnn  ,
%     \__kernel_msg_critical:nnnn   ,
%     \__kernel_msg_critical:nnn    ,
%     \__kernel_msg_critical:nn     ,
%     \__kernel_msg_critical:nnxxxx ,
%     \__kernel_msg_critical:nnxxx  ,
%     \__kernel_msg_critical:nnxx   ,
%     \__kernel_msg_critical:nnx
%   }
%   \begin{syntax}
%     \cs{__kernel_msg_critical: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
%   critical error, \TeX{} stops reading the current input file.
%   Cannot be redirected.
% \end{function}
%
% \begin{function}
%   {
%     \__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}
%   {
%     \__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}
%   {
%     \__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}
%
% \begin{function}[EXP]
%   {
%     \__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,
%     \__kernel_msg_expandable_error:nnffff,
%     \__kernel_msg_expandable_error:nnfff,
%     \__kernel_msg_expandable_error:nnff,
%     \__kernel_msg_expandable_error:nnf,
%   }
%   \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{variable}{\g__kernel_prg_map_int}
%   This integer is used by non-expandable mapping functions to track
%   the level of nesting in force.  The functions
%   \cs[no-index]{\meta{type}_map_1:w},
%   \cs[no-index]{\meta{type}_map_2:w}, \emph{etc.}, labelled by
%   \cs{g__kernel_prg_map_int}
%   hold functions to be mapped over various list datatypes in inline
%   and variable mappings.
% \end{variable}
%
% \begin{function}{\__kernel_quark_new_test:N}
%   \begin{syntax}
%     \cs{__kernel_quark_new_test:N} \cs[no-index]{\meta{name}:\meta{arg spec}}
%   \end{syntax}
%   Defines a quark-test function \cs[no-index]{\meta{name}:\meta{arg spec}}
%   which tests if its argument is \cs[no-index]{q__\meta{namespace}_recursion_tail},
%   then acts accordingly, as described below for each possible
%   \meta{arg spec}.
%
%   The \meta{namespace} is determined as the first (nonempty)
%   |_|-delimited word in \meta{name} and is used internally
%   in the definition of auxiliaries.  The function
%   \cs{__kernel_quark_new_test:N} does \emph{not} define
%   the \cs[no-index]{q__\meta{namespace}_recursion_tail} and
%   \cs[no-index]{q__\meta{namespace}_recursion_stop} quarks.
%   They should be manually defined with \cs{quark_new:N}.
%
%   There are $6$ different types of quark-test functions. Which one is
%   defined depends on the \meta{arg spec}, which \emph{must} be one of
%   the options listed now.  Four of them are modeled after
%   \cs[no-index]{quark_if_recursion_tail:(N|n)} and
%   \cs[no-index]{quark_if_recursion_tail_do:(N|n)n}.
%   \begin{description}
%     \def\makelabel#1{\texttt{#1}}
%     \item[n]  defines \cs[no-index]{\meta{name}:n}  such that it
%       checks if |#1| contains only \cs[no-index]{q__\meta{namespace}_recursion_tail}, and
%       if so consumes all tokens up to \cs[no-index]{q__\meta{namespace}_recursion_stop}
%       (\emph{c.f.}~\cs{quark_if_recursion_tail_stop:n}).
%     \item[nn] defines \cs[no-index]{\meta{name}:nn} such that it
%       checks if |#1| contains only \cs[no-index]{q__\meta{namespace}_recursion_tail}, and
%       if so consumes all tokens up to \cs[no-index]{q__\meta{namespace}_recursion_stop},
%       then executes the code |#2| after that
%       (\emph{c.f.}~\cs{quark_if_recursion_tail_stop_do:nn}).
%     \item[N]  defines \cs[no-index]{\meta{name}:N}  such that it
%       checks if |#1| is \cs[no-index]{q__\meta{namespace}_recursion_tail}, and if so consumes
%       all tokens up to \cs[no-index]{q__\meta{namespace}_recursion_stop}
%       (\emph{c.f.}~\cs{quark_if_recursion_tail_stop:N}).
%     \item[Nn] defines \cs[no-index]{\meta{name}:Nn} such that it
%       checks if |#1| is \cs[no-index]{q__\meta{namespace}_recursion_tail}, and if so consumes
%       all tokens up to \cs[no-index]{q__\meta{namespace}_recursion_stop}, then executes
%       the code |#2| after that
%       (\emph{c.f.}~\cs{quark_if_recursion_tail_stop_do:Nn}).
%   \end{description}
%   The last two are modeled after
%   \cs[no-index]{quark_if_recursion_tail_break:(n|N)N}, and in those
%   cases the quark \cs[no-index]{q__\meta{namespace}_recursion_stop} is
%   not used (and thus needs not be defined).
%   \begin{description}
%     \def\makelabel#1{\texttt{#1}}
%     \item[nN] defines \cs[no-index]{\meta{name}:nN} such that it
%       checks if |#1| contains only \cs[no-index]{q__\meta{namespace}_recursion_tail}, and
%       if so uses the \cs[no-index]{\meta{type}_map_break:} function |#2|.
%     \item[NN] defines \cs[no-index]{\meta{name}:NN} such that it
%       checks if |#1| is \cs[no-index]{q__\meta{namespace}_recursion_tail}, and if so uses
%       the \cs[no-index]{\meta{type}_map_break:} function |#2|.
%   \end{description}
%   Any other signature, as well as a function without signature
%   are errors, and in such case the definition is aborted.
% \end{function}
%
% \begin{function}{\__kernel_quark_new_conditional:Nn}
%   \begin{syntax}
%     \cs{__kernel_quark_new_conditional:Nn} \cs[no-index]{__\meta{namespace}_quark_if_\meta{name}:\meta{arg spec}} \Arg{conditions}
%   \end{syntax}
%   Defines a collection of quark conditionals that test if their
%   argument is the quark \cs[no-index]{q__\meta{namespace}_\meta{name}}
%   and perform suitable actions.  The \meta{conditions} are a
%   comma-separated list of one or more of |p|, |T|, |F|, and |TF|, and
%   one conditional is defined for each \meta{condition} in the list, as
%   described for \cs{prg_new_conditional:Npnn}.  The conditionals are
%   defined using \cs{prg_new_conditional:Npnn}, so that their name is
%   obtained by adding |p|, |T|, |F|, or |TF| to the base name
%   \cs[no-index]{__\meta{namespace}_quark_if_\meta{name}:\meta{arg spec}}.
%
%   The first argument of \cs{__kernel_quark_new_conditional:Nn} must
%   contain |_quark_if_| and |:|, as these markers are used to determine
%   the \meta{name} of the quark
%   \cs[no-index]{q__\meta{namespace}_\meta{name}} to be tested.  This
%   quark should be manually defined with \cs{quark_new:N}, as
%   \cs{__kernel_quark_new_conditional:Nn} does \emph{not} define it.
%
%   The function \cs{__kernel_quark_new_conditional:Nn} can define $2$
%   different types of quark conditionals.  Which one is defined depends
%   on the \meta{arg spec}, which \emph{must} be one of the following
%   options, modeled after \cs[no-index]{quark_if_nil:(N|n)(TF)}.
%   \begin{description}
%     \def\makelabel#1{\texttt{#1}}
%     \item[n]  defines \cs[no-index]{__\meta{namespace}_quark_if_\meta{name}:n(TF)}  such that it
%       checks if |#1| contains only \cs[no-index]{q__\meta{namespace}_\meta{name}}, and
%       executes the proper conditional branch.
%     \item[N]  defines \cs[no-index]{__\meta{namespace}_quark_if_\meta{name}:N(TF)}  such that it
%       checks if |#1| is \cs[no-index]{q__\meta{namespace}_\meta{name}}, and
%       executes the proper conditional branch.
%   \end{description}
%   Any other signature, as well as a function without signature
%   are errors, and in such case the definition is aborted.
% \end{function}
%
% \begin{variable}{\c__kernel_randint_max_int}
%   Maximal allowed argument to \cs{__kernel_randint:n}.  Equal to
%   $2^{17}-1$.
% \end{variable}
%
% \begin{function}{\__kernel_randint:n}
%   \begin{syntax}
%     \cs{__kernel_randint:n} \Arg{max}
%   \end{syntax}
%   Used in an integer expression this gives a pseudo-random number
%   between $1$ and $\meta{max}$ included.  One must have
%   $\meta{max}\leq 2^{17}-1$.  The \meta{max} must be suitable for
%   \cs{int_value:w} (and any \cs{int_eval:w} must be terminated by
%   \cs{scan_stop:} or equivalent).
% \end{function}
%
% \begin{function}{\__kernel_randint:nn}
%   \begin{syntax}
%     \cs{__kernel_randint:nn} \Arg{min} \Arg{max}
%   \end{syntax}
%   Used in an integer expression this gives a pseudo-random number
%   between $\meta{min}$ and $\meta{max}$ included.  The \meta{min} and
%   \meta{max} must be suitable for \cs{int_value:w} (and any
%   \cs{int_eval:w} must be terminated by \cs{scan_stop:} or
%   equivalent).  For small ranges
%   $R=\meta{max}-\meta{min}+1\leq 2^{17}-1$,
%   $\meta{min} - 1 + \cs{__kernel_randint:n} |{|R|}|$ is faster.
% \end{function}
%
% \begin{function}{\__kernel_register_show:N, \__kernel_register_show:c}
%   \begin{syntax}
%     \cs{__kernel_register_show:N} \meta{register}
%   \end{syntax}
%   Used to show the contents of a \TeX{} register at the terminal, formatted
%   such that internal parts of the mechanism are not visible.
% \end{function}
%
% \begin{function}
%   {\__kernel_register_log:N, \__kernel_register_log:c}
%   \begin{syntax}
%     \cs{__kernel_register_log:N} \meta{register}
%   \end{syntax}
%   Used to write the contents of a \TeX{} register to the log file in a
%   form similar to \cs{__kernel_register_show:N}.
% \end{function}
%
% \begin{function}[EXP]{\__kernel_str_to_other:n}
%   \begin{syntax}
%     \cs{__kernel_str_to_other:n} \Arg{token list}
%   \end{syntax}
%   Converts the \meta{token list} to a \meta{other string}, where
%   spaces have category code \enquote{other}.  This function can be
%   \texttt{f}-expanded without fear of losing a leading space, since
%   spaces do not have category code $10$ in its result.  It takes a
%   time quadratic in the character count of the string.
% \end{function}
%
% \begin{function}[rEXP]{\__kernel_str_to_other_fast:n}
%   \begin{syntax}
%     \cs{__kernel_str_to_other_fast:n} \Arg{token list}
%   \end{syntax}
%   Same behaviour \cs{__kernel_str_to_other:n} but only restricted-expandable.
%   It takes a time linear in the character count of the string.
% \end{function}
%
% \begin{function}[EXP]{\__kernel_tl_to_str:w}
%   \begin{syntax}
%     \cs{__kernel_tl_to_str:w} \meta{expandable tokens} \Arg{tokens}
%   \end{syntax}
%   Carries out expansion on the \meta{expandable tokens} before conversion of
%   the \meta{tokens} to a string as describe for \cs{tl_to_str:n}. Typically,
%   the \meta{expandable tokens} will alter the nature of the \meta{tokens},
%   \emph{i.e.}~allow it to be generated in some way. This function requires
%   only a single expansion.
% \end{function}
%
% \begin{function}{\__kernel_tl_set:Nx, \__kernel_tl_gset:Nx}
%   \begin{syntax}
%     \cs{__kernel_tl_set:Nx} \meta{tl~var} \Arg{tokens}
%   \end{syntax}
%   Fully expands \meta{tokens} and assigns the result to \meta{tl~var}.
%   \meta{tokens} must be given in braces and there must be no token between
%   \meta{tl~var} and \meta{tokens}.
% \end{function}
%
% \section{Kernel backend functions}
%
% These functions are required to pass information to the backend. The nature
% of these means that they are defined only when the relevant backend is in
% use.
%
% \begin{function}
%  {
%    \__kernel_backend_literal:n,
%    \__kernel_backend_literal:e,
%    \__kernel_backend_literal:x
%  }
%   \begin{syntax}
%     \cs{__kernel_backend_literal:n} \Arg{content}
%   \end{syntax}
%   Adds the \meta{content} literally to the current vertical list as a
%   whatsit. The nature of the \meta{content} will depend on the backend in
%   use.
% \end{function}
%
% \begin{function}
%  {
%    \__kernel_backend_literal_postscript:n,
%    \__kernel_backend_literal_postscript:x
%  }
%   \begin{syntax}
%     \cs{__kernel_backend_literal_postscript:n} \Arg{PostScript}
%   \end{syntax}
%   Adds the \meta{PostScript} literally to the current vertical list as a
%   whatsit. No positioning is applied.
% \end{function}
%
% \begin{function}
%  {
%    \__kernel_backend_literal_pdf:n,
%    \__kernel_backend_literal_pdf:x
%  }
%   \begin{syntax}
%     \cs{__kernel_backend_literal_pdf:n} \Arg{PDF instructions}
%   \end{syntax}
%   Adds the \meta{PDF instructions} literally to the current vertical list as
%   a whatsit. No positioning is applied.
% \end{function}
%
% \begin{function}
%  {
%    \__kernel_backend_literal_svg:n,
%    \__kernel_backend_literal_svg:x
%  }
%   \begin{syntax}
%     \cs{__kernel_backend_literal_svg:n} \Arg{SVG instructions}
%   \end{syntax}
%   Adds the \meta{SVG instructions} literally to the current vertical list as
%   a whatsit. No positioning is applied.
% \end{function}
%
% \begin{function}
%  {
%    \__kernel_backend_postscript:n,
%    \__kernel_backend_postscript:x
%  }
%   \begin{syntax}
%     \cs{__kernel_backend_postscript:n} \Arg{PostScript}
%   \end{syntax}
%   Adds the \meta{PostScript} to the current vertical list as a
%   whatsit. The PostScript reference point is adjusted to match the
%   current position. The PostScript is inserted inside a |SDict begin|/|end|
%   pair.
% \end{function}
%
% \begin{function}{\__kernel_backend_align_begin:, \__kernel_backend_align_end:}
%   \begin{syntax}
%     \cs{__kernel_backend_align_begin:}
%     \meta{PostScript literals}
%     \cs{__kernel_backend_align_end:}
%   \end{syntax}
%   Arranges to align the PostScript and DVI current positions and scales.
% \end{function}
%
% \begin{function}{\__kernel_backend_scope_begin:, \__kernel_backend_scope_end:}
%   \begin{syntax}
%     \cs{__kernel_backend_scope_begin:}
%     \meta{content}
%     \cs{__kernel_backend_scope_end:}
%   \end{syntax}
%   Creates a scope for instructions at the backend level.
% \end{function}
%
% \begin{function}
%  {
%    \__kernel_backend_matrix:n,
%    \__kernel_backend_matrix:x
%  }
%   \begin{syntax}
%     \cs{__kernel_backend_matrix:n} \Arg{matrix}
%   \end{syntax}
%   Applies the \meta{matrix} to the current transformation matrix.
% \end{function}
%
% \begin{function}{\g__kernel_backend_header_bool}
%   Specifies whether to write headers for the backend.
% \end{function}
%
% \begin{function}{\l__kernel_color_stack_int}
%   The color stack used in \pdfTeX{} and \LuaTeX{} for the main color.
% \end{function}
%
% \end{implementation}
%
% \PrintIndex