diff options
Diffstat (limited to 'macros/latex/required/l3kernel/l3kernel-functions.dtx')
-rw-r--r-- | macros/latex/required/l3kernel/l3kernel-functions.dtx | 739 |
1 files changed, 739 insertions, 0 deletions
diff --git a/macros/latex/required/l3kernel/l3kernel-functions.dtx b/macros/latex/required/l3kernel/l3kernel-functions.dtx new file mode 100644 index 0000000000..6779a3ca6c --- /dev/null +++ b/macros/latex/required/l3kernel/l3kernel-functions.dtx @@ -0,0 +1,739 @@ +% \iffalse meta-comment +% +%% File: l3kernel-functions.dtx +% +% Copyright (C) 2018-2024 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} module\\ 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 2024-05-08} +% +% \maketitle +% +% \begin{documentation} +% +% \end{documentation} +% +% \begin{implementation} +% +% \section{\pkg{l3kernel-functions}: kernel-reserved functions} +% +% \subsection{Internal \pkg{l3debug} kernel functions} +% \label{sec:l3kernel-functions:l3debug-internals} +% +% These function are only created if debugging is enabled, hence they are +% actually defined in \pkg{l3debug}. +% +% \begin{function}{\__kernel_chk_var_local:N, \__kernel_chk_var_global:N} +% \begin{syntax} +% \cs{__kernel_chk_var_local:N} \meta{var} +% \cs{__kernel_chk_var_global:N} \meta{var} +% \end{syntax} +% Applies \cs{__kernel_chk_var_exist:N} \meta{var} as well as +% \cs{__kernel_chk_var_scope:NN} \meta{scope} \meta{var}, where +% \meta{scope} is |l| or~|g|. +% \end{function} +% +% \begin{function}{\__kernel_chk_var_scope:NN} +% \begin{syntax} +% \cs{__kernel_chk_var_scope:NN} \meta{scope} \meta{var} +% \end{syntax} +% Checks the \meta{var} has the correct \meta{scope}, and if not +% raises a kernel-level error. +% The \meta{scope} is a single letter |l|, |g|, +% |c| denoting local variables, global variables, or constants. More +% precisely, if the variable name starts with a letter and an +% underscore (normal \pkg{expl3} convention) the function checks that +% this single letter matches the \meta{scope}. Otherwise the function +% cannot know the scope \meta{var} the first time: instead, it defines +% |\__debug_chk_/|\meta{var name} to store that information for the +% next call. Thus, if a given \meta{var} is subject to assignments of +% different scopes a kernel error will result. +% \end{function} +% +% \begin{function} +% { +% \__kernel_chk_cs_exist:N, +% \__kernel_chk_cs_exist:c, +% \__kernel_chk_var_exist:N +% } +% \begin{syntax} +% \cs{__kernel_chk_cs_exist:N} \meta{cs} +% \cs{__kernel_chk_var_exist:N} \meta{var} +% \end{syntax} +% Checks that their argument is defined according to the criteria for +% \cs{cs_if_exist_p:N}, +% and if not raises a kernel-level error. Error messages are +% different. +% \end{function} +% +% \begin{function}[EXP]{\__kernel_chk_flag_exist:NN} +% \begin{syntax} +% \cs{__kernel_chk_flag_exist:NN} +% \meta{function} \meta{flag} +% \end{syntax} +% Checks that the \meta{flag} is defined according to the criterion for +% \cs{flag_if_exist_p:N}, and if not raises a kernel-level error and +% calls the function with the argument \cs{l_tmpa_flag} to proceed +% somehow without producing too many errors. +% \end{function} +% +% \begin{function}{\__kernel_debug_log:e} +% \begin{syntax} +% \cs{__kernel_debug_log:e} \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:e}. +% Otherwise, the \meta{message text} is ignored using \cs{use_none:n}. +% \end{function} +% +% \subsection{Internal kernel functions} +% +% \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_chk_tl_type:NnnT} +% \begin{syntax}\parskip=0pt\obeylines +% \cs{__kernel_chk_tl_type:NnnT} \meta{control sequence} \Arg{specific type} \\ +% | |\Arg{reconstruction} \Arg{true code} +% \end{syntax} +% Helper to test that the \meta{control sequence} is a variable of the +% given \meta{specific type} of token list. Produces suitable error +% messages if the \meta{control sequence} does not exist, or if it is +% not a token list variable at all, or if the \meta{control sequence} +% differs from the result of |e|-expanding \meta{reconstruction}. If +% all of these tests succeed then the \meta{true code} is run. +% \end{function} +% +% \begin{function}[EXP]{\__kernel_codepoint_to_bytes:n} +% \begin{syntax} +% \cs{__kernel_codepoint_to_bytes:n} \Arg{codepoint} +% \end{syntax} +% Converts the \meta{codepoint} to UTF-8 bytes. The expansion +% of this function comprises four brace groups, each of which will contain +% a hexadecimal value: the appropriate byte. As UTF-8 is a variable-length, +% one or more of the groups may be empty: the bytes read in the logical order, +% such that a two-byte codepoint will have groups |#1| and |#2| filled +% and |#3| and |#4| empty. +% \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:n} and \cs{debug_off:n}. +% \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:n} then +% produces an error message indicating that this file was not found. +% \end{function} +% +% \begin{function}[EXP,updated = 2021-04-17]{\__kernel_file_name_sanitize:n} +% \begin{syntax} +% \cs{__kernel_file_name_sanitize:n} \Arg{name} +% \end{syntax} +% Expands the file name using a \tn{csname}-based approach, and +% relies on active characters (for example from UTF-8 characters) +% being properly set up to expand to a expansion-safe version using +% \cs{ifcsname}. This is less conservative than the token-by-token +% approach used before, but it is much faster. +% \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{ior_shell_open:Nn}. +% \end{function} +% +% \begin{function}{\__kernel_iow_open:Nn, \__kernel_iow_open:No} +% \begin{syntax} +% \cs{__kernel_iow_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{iow_shell_open: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_show_eval:Nn, \__kernel_msg_log_eval:Nn} +% \begin{syntax} +% \cs{__kernel_msg_show_eval:Nn} \meta{function} \Arg{expression} +% \end{syntax} +% Shows or logs the \meta{expression} (turned into a string), an equal +% sign, and the result of applying the \meta{function} to the +% \Arg{expression} (with \texttt{f}-expansion). For instance, if the +% \meta{function} is \cs{int_eval:n} and the \meta{expression} is +% |1+2| then this logs |> 1+2=3.| +% \end{function} +% +% \begin{function}[EXP]{\__kernel_pdf_object_id:n, \__kernel_pdf_object_id_indexed:nn} +% \begin{syntax} +% \cs{__kernel_pdf_object_id:n} \Arg{object} +% \cs{__kernel_pdf_object_id_indexed:nn} \Arg{class} \Arg{number} +% \end{syntax} +% Expands to the ID of \meta{object} (or object of \meta{number} within +% the \meta{class}), in for example page resource allocation. Depending on +% the backend, the result may be the same as +% \cs{pdf_object_id:n}/\cs{pdf_object_id_indexed:nn}. +% \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[index=quark_if_nil:NTF]{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{function}{\__kernel_sys_everyjob:} +% \begin{syntax} +% \cs{__kernel_sys_everyjob:} +% \end{syntax} +% Inserts the internal token list required at the start of every run (job). +% \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} +% +% \begin{function}[EXP]{\__kernel_codepoint_data:nn} +% \begin{syntax} +% \cs{__kernel_codepoint_data:nn} \Arg{type} \Arg{codepoint} +% \end{syntax} +% Expands to the appropriate value for the \meta{type} of data +% requested for a \meta{codepoint}. The current list of \meta{types} and +% results are +% \begin{description} +% \item[\texttt{lowercase}] The \emph{single} codepoint specified by +% \texttt{UnicodeData.txt} for lowercase mapping of the codepoint: +% will be equal to the input \meta{codepoint} if there is no mapping +% specified in \texttt{UnicodeData.txt} +% \item[\texttt{uppercase}] The \emph{single} codepoint specified by +% \texttt{UnicodeData.txt} for uppercase mapping of the codepoint: +% will be equal to the input \meta{codepoint} if there is no mapping +% specified in \texttt{UnicodeData.txt} +% \end{description} +% \end{function} +% +% \begin{function}[EXP]{\__kernel_codepoint_case:nn} +% \begin{syntax} +% \cs{__kernel_codepoint_case:nn} \Arg{mapping} \Arg{codepoint} +% \end{syntax} +% Expands to a list of three balanced text, of which at least the first +% will contain a codepoint. This list of up to three codepoints specifies +% the full case mapping for the input \meta{codepoint}. The \meta{mapping} +% should be one of +% \begin{itemize} +% \item \texttt{casefold} +% \item \texttt{lowercase} +% \item \texttt{titlecase} +% \item \texttt{uppercase} +% \end{itemize} +% \end{function} +% +% \subsection{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:e +% } +% \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:e +% } +% \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:e +% } +% \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:e +% } +% \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:e +% } +% \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:e +% } +% \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 |