diff options
author | Karl Berry <karl@freefriends.org> | 2018-04-30 22:39:09 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2018-04-30 22:39:09 +0000 |
commit | a28e1bfccd6fe522fcd296426e4d89c7fb4f19b6 (patch) | |
tree | b72347e08575b56fcfed87c4d837b48dcfd1e02a /Master/texmf-dist/source/latex/l3kernel/l3kernel-functions.dtx | |
parent | b40c37a9e22b8235ff9c0bc256d00f7af94304c3 (diff) |
l3 (30apr18)
git-svn-id: svn://tug.org/texlive/trunk@47516 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3kernel-functions.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex/l3kernel/l3kernel-functions.dtx | 481 |
1 files changed, 481 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3kernel-functions.dtx b/Master/texmf-dist/source/latex/l3kernel/l3kernel-functions.dtx new file mode 100644 index 00000000000..aa4e288b59d --- /dev/null +++ b/Master/texmf-dist/source/latex/l3kernel/l3kernel-functions.dtx @@ -0,0 +1,481 @@ +% \iffalse meta-comment +% +%% File: l3kernel-functions.dtx Copyright (C) 2018 The LaTeX3 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 \LaTeX3 Project\thanks +% {^^A +% E-mail: +% \href{mailto:latex-team@latex-project.org} +% {latex-team@latex-project.org}^^A +% }^^A +% } +% +% \date{Released 2018-04-30} +% +% \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{etex_mutoglue:D}, used for internal +% purposes. +% \end{function} +% +% \begin{function}{\__kernel_chk_var_exist:N} +% \begin{syntax} +% \cs{__kernel_chk_var_exist:N} \meta{var} +% \end{syntax} +% This function is only created if debugging is enabled. It checks +% that \meta{var} is defined 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_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. This function is only created if +% debugging is enabled. 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_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}, and assuming that is +% true applies +% \cs{__kernel_chk_var_scope:NN} \meta{scope} \meta{var}, where +% \meta{scope} is |l| or~|g|. +% \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_if_debug:TF} +% \begin{syntax} +% \cs{__kernel_if_debug:TF} \Arg{true code} \Arg{false code} +% \end{syntax} +% Runs the \meta{true code} if debugging is enabled, namely only in +% \LaTeXe{} package mode with one of the options +% \texttt{check-declarations}, \texttt{enable-debug}, or +% \texttt{log-functions}. Otherwise runs the \meta{false code}. The +% |T| and |F| variants are not provided for this low-level +% conditional. +% \end{function} +% +% \begin{function}{\__kernel_debug_log:x} +% \begin{syntax} +% \cs{__kernel_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}. +% This function is only created if debugging is enabled. +% \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{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 that 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}{\__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{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_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{function}{\__kernel_patch:nnNNpn} +% \begin{syntax} +% \cs{__kernel_patch:nnNNpn} \Arg{before} \Arg{after} +% \meta{definition} \meta{function} \meta{parameters} \Arg{code} +% \end{syntax} +% If debugging is not enabled, this function ignores the \meta{before} +% and \meta{after} code and performs the \meta{definition} with no +% patching. Otherwise it replaces \meta{code} by \meta{before} +% \meta{code} \meta{after} (which can involve |#1| and so on) in the +% \meta{definition} that follows. The \meta{definition} must start +% with \cs{cs_new:Npn} or \cs{cs_set:Npn} or \cs{cs_gset:Npn} or their +% \texttt{_protected} counterparts. Other cases can be added as +% needed. +% \end{function} +% +% \begin{function}{\__kernel_patch_conditional:nNNpnn} +% \begin{syntax} +% \cs{__kernel_patch_conditional:nNNpnn} \Arg{before} +% \meta{definition} \meta{conditional} \meta{parameters} \Arg{type} \Arg{code} +% \end{syntax} +% Similar to \cs{__kernel_patch:nnNNpn} for conditionals, namely +% \meta{definition} must be \cs{prg_new_conditional:Npnn} or its +% \texttt{_protected} counterpart. There is no \meta{after} code +% because that would interfere with the action of the conditional. +% \end{function} +% +% \begin{function} +% {\__kernel_patch_args:nNNpn, \__kernel_patch_conditional_args:nNNpnn} +% \begin{syntax} +% \cs{__kernel_patch_args:nNNpn} \Arg{arguments} +% \meta{definition} \meta{function} \meta{parameters} \Arg{code} +% \end{syntax} +% Like \cs{__kernel_patch:nnNNpn}, this tweaks the following +% definition, but from the \enquote{inside out} (and if debugging is +% not enabled, the \meta{arguments} are ignored). It replaces |#1|, +% |#2| and so on in the \meta{code} of the definition as indicated by +% the \meta{arguments}. More precisely, a temporary function is +% defined using the \meta{definition} with the \meta{parameters} and +% \meta{code}, then the result of expanding that function once in +% front of the \meta{arguments} is used instead of the \meta{code} +% when defining the actual function. For instance, +% \begin{quote} +% \cs{__kernel_patch_args:nNNpn} |{ { (#1) } }| \\ +% \cs{cs_new:Npn} \cs{int_eval:n} |#1| \\ +% ~~|{ \int_value:w \__int_eval:w #1 \__int_eval_end: }| +% \end{quote} +% would replace |#1| by |(#1)| in the definition of \cs{int_eval:n} when +% debugging is enabled. This fails if the \meta{code} contains~|##|. +% The \cs{__kernel_patch_conditional_args:nNNpnn} function is for use +% before \cs{prg_new_conditional:Npnn} or its \texttt{_protected} +% counterpart. +% \end{function} +% +% \begin{function} +% {\__kernel_patch_args:nnnNNpn, \__kernel_patch_conditional_args:nnnNNpnn} +% \begin{syntax} +% \cs{__kernel_patch_args:nnnNNpn} \Arg{before} \Arg{after} \Arg{arguments} +% \meta{definition} \meta{function} \meta{parameters} \Arg{code} +% \end{syntax} +% A combination of \cs{__kernel_patch:nnNNpn} and +% \cs{__kernel_patch_args:nNNpn}. +% \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_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} +% +% \end{implementation} +% +% \PrintIndex |