[latex3-commits] [git/LaTeX3-latex3-latex3] master: Doc e-type at start of interfaces3, and new variable types (fixes #528) [ci-skip] (1a7615e)

[Bruno Le Floch]

Repository : https://github.com/latex3/latex3
On branch  : master
Link       : https://github.com/latex3/latex3/commit/1a7615eff82b19221be21c2ba27a0e9b8f060567

>---------------------------------------------------------------

commit 1a7615eff82b19221be21c2ba27a0e9b8f060567
Author: Bruno Le Floch <bruno at le-floch.fr>
Date:   Sun Feb 10 21:22:38 2019 +0100

    Doc e-type at start of interfaces3, and new variable types (fixes #528) [ci-skip]
    
    Worth discussing: the split I made between variable types for which v/V-type
    expansion works (int,fp,dim,skip,muskip,tl,str,clist,seq) and doesn't work
    (bool,box,coffin,flag,fparray,intarray,ior,iow,prop,regex).  Notice I put
    seq in the first list and prop in the second, because it is plausible that
    we one day decide to store items of a prop in different csnames, in which
    case the single expansion of exp_args:V would not unpack the value.


>---------------------------------------------------------------

1a7615eff82b19221be21c2ba27a0e9b8f060567
 l3kernel/source3body.tex |   56 +++++++++++++++++++++++++++++++---------------
 1 file changed, 38 insertions(+), 18 deletions(-)

diff --git a/l3kernel/source3body.tex b/l3kernel/source3body.tex
index 2776b79..51f9542 100644
--- a/l3kernel/source3body.tex
+++ b/l3kernel/source3body.tex
@@ -134,10 +134,6 @@ take no arguments, this will be blank and the function name will end
 \texttt{:}. Most functions take one or more arguments, and use the
 following argument specifiers:
 \begin{description}
-  \item[\texttt{D}] The \texttt{D} specifier means \emph{do not use}.
-    All of the \TeX{} primitives are initially \cs{let} to a \texttt{D}
-    name, and some are then given a second name.  Only the kernel
-    team should use anything with a \texttt{D} specifier!
   \item[\texttt{N} and \texttt{n}] These mean \emph{no manipulation},
     of a single token for \texttt{N} and of a set of tokens given in
     braces for \texttt{n}. Both pass the argument through exactly as
@@ -163,8 +159,13 @@ following argument specifiers:
     expansion}: every token in the argument is fully expanded until only
     unexpandable ones remain. The \TeX{} \tn{edef} primitive carries out
     this type of expansion. Functions which feature an \texttt{x}-type
-    argument are in general \emph{not} expandable, unless specifically
-    noted.
+    argument are \emph{not} expandable.
+  \item[\texttt{e}] The \texttt{e} specifier is in many respects
+    identical to \texttt{x}, but with a very different implementation.
+    Functions which feature an \texttt{e}-type argument may be
+    expandable.  The drawback is that \texttt{e} is extremely slow
+    (often more than $200$ times slower) in older engines, more
+    precisely in non-\LuaTeX{} engines older than 2019.
   \item[\texttt{f}] The \texttt{f} specifier stands for \emph{full
     expansion}, and in contrast to \texttt{x} stops at the first
     non-expandable item (reading the argument from left to right) without
@@ -188,7 +189,11 @@ following argument specifiers:
   \item[\texttt{w}] Finally, there is the \texttt{w} specifier for
     \emph{weird} arguments. This covers everything else, but mainly
     applies to delimited values (where the argument must be terminated
-    by some arbitrary string).
+    by some specified string).
+  \item[\texttt{D}] The \texttt{D} specifier means \emph{do not use}.
+    All of the \TeX{} primitives are initially \cs{let} to a \texttt{D}
+    name, and some are then given a second name.  Only the kernel
+    team should use anything with a \texttt{D} specifier!
 \end{description}
 Notice that the argument specifier describes how the argument is
 processed prior to being passed to the underlying function. For example,
@@ -215,22 +220,35 @@ function, typically starting with the module\footnote{The module names are
 and then a descriptive part.
 Variables end with a short identifier to show the variable type:
 \begin{description}
-  \item[\texttt{bool}] Either true or false.
-  \item[\texttt{box}] Box register.
   \item[\texttt{clist}] Comma separated list.
-  \item[\texttt{coffin}] a \enquote{box with handles} --- a higher-level data
-     type for carrying out |box| alignment operations.
   \item[\texttt{dim}] \enquote{Rigid} lengths.
-  \item[\texttt{fp}] floating-point values;
+  \item[\texttt{fp}] Floating-point values;
   \item[\texttt{int}] Integer-valued count register.
-  \item[\texttt{prop}] Property list.
-  \item[\texttt{seq}] \enquote{Sequence}: a data-type used to implement lists
-    (with access at both ends) and stacks.
+  \item[\texttt{muskip}] \enquote{Rubber} lengths for use in
+    mathematics.
+  \item[\texttt{seq}] \enquote{Sequence}: a data-type used to implement
+    lists (with access at both ends) and stacks.
   \item[\texttt{skip}] \enquote{Rubber} lengths.
-  \item[\texttt{stream}] An input or output stream (for reading from or
-    writing to, respectively).
+  \item[\texttt{str}] String variables: contain character data.
   \item[\texttt{tl}] Token list variables: placeholder for a token list.
 \end{description}
+Applying \texttt{V}-type or \texttt{v}-type expansion to variables of
+one of the above types is supported, while it is not supported for the
+following variable types:
+\begin{description}
+  \item[\texttt{bool}] Either true or false.
+  \item[\texttt{box}] Box register.
+  \item[\texttt{coffin}] A \enquote{box with handles} --- a higher-level
+    data type for carrying out \texttt{box} alignment operations.
+  \item[\texttt{flag}] Integer that can be incremented expandably.
+  \item[\texttt{fparray}] Fixed-size array of floating point values.
+  \item[\texttt{intarray}] Fixed-size array of integers.
+  \item[\texttt{ior}/\texttt{iow}] An input or output stream, for
+    reading from or writing to, respectively.
+  \item[\texttt{prop}] Property list: analogue of dictionary or
+    associative arrays in other languages.
+  \item[\texttt{regex}] Regular expression.
+\end{description}
 
 \subsection{Terminological inexactitude}
 
@@ -242,7 +260,9 @@ is a macro processor, and functions are simply macros that may or may not take
 arguments and expand to their replacement text.  Many of the common variables
 are \emph{also} macros, and if placed into the input stream will simply expand
 to their definition as well~--- a \enquote{function} with no arguments and a
-\enquote{token list variable} are in truth one and the same.  On the other
+\enquote{token list variable} are almost the same.\footnote{\TeX{}nically,
+functions with no arguments are \tn{long} while token list variables are not.}
+On the other
 hand, some \enquote{variables} are actually registers that must be
 initialised and their values set and retrieved with specific functions.