[latex3-commits] [git/LaTeX3-latex3-latex3] master: add documentation of keyval_parse:nnn (2eb759911)

[Joseph Wright]

Repository : https://github.com/latex3/latex3
On branch  : master
Link       : https://github.com/latex3/latex3/commit/2eb7599112ad013a56e7c81551aac290fe8588a5

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

commit 2eb7599112ad013a56e7c81551aac290fe8588a5
Author: Jonathan Spratte <jspratte at yahoo.de>
Date:   Sat Dec 19 21:45:20 2020 +0100

    add documentation of keyval_parse:nnn


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

2eb7599112ad013a56e7c81551aac290fe8588a5
 l3kernel/l3keys.dtx | 60 ++++++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 53 insertions(+), 7 deletions(-)

diff --git a/l3kernel/l3keys.dtx b/l3kernel/l3keys.dtx
index 65a2c70e9..7b8c39bd0 100644
--- a/l3kernel/l3keys.dtx
+++ b/l3kernel/l3keys.dtx
@@ -891,7 +891,45 @@
 % \end{verbatim}
 % are treated identically.
 %
-% \begin{function}[EXP,updated = 2020-02-20]{\keyval_parse:NNn}
+% \begin{function}[rEXP, added=2020-12-19]{\keyval_parse:nnn}
+%   \begin{syntax}
+%     \cs{keyval_parse:nnn} \Arg{code_1} \Arg{code_2} \Arg{key--value list}
+%   \end{syntax}
+%   Parses the \meta{key--value list} into a series of \meta{keys} and
+%   associated \meta{values}, or keys alone (if no \meta{value} was
+%   given).  \meta{code_1} receives each \meta{key} (with no \meta{value}) as a
+%   trailing brace group, whereas \meta{code_2} is appended by two brace groups,
+%   the \meta{key} and \meta{value}.
+%   The order of the \meta{keys} in the \meta{key--value list}
+%   is preserved. Thus
+%   \begin{verbatim}
+%     \keyval_parse:nnn
+%       { \use_none:nn  { code 1 } }
+%       { \use_none:nnn { code 2 } }
+%       { key1 = value1 , key2 = value2, key3 = , key4 }
+%   \end{verbatim}
+%   is converted into an input stream
+%   \begin{verbatim}
+%     \use_none:nnn { code 2 } { key1 } { value1 }
+%     \use_none:nnn { code 2 } { key2 } { value2 }
+%     \use_none:nnn { code 2 } { key3 } { }
+%     \use_none:nn  { code 1 } { key4 }
+%   \end{verbatim}
+%   Note that there is a difference between an empty value (an equals
+%   sign followed by nothing) and a missing value (no equals sign at
+%   all). Spaces are trimmed from the ends of the \meta{key} and \meta{value},
+%   then one \emph{outer} set of braces is removed from the \meta{key}
+%   and \meta{value} as part of the processing. If you need exactly the output
+%   shown above, you'll need to either \texttt{x}-type or \texttt{e}-type expand
+%   the function.
+%   \begin{texnote}
+%     The result of each list element is returned within \cs{exp_not:n}, which
+%     means that the converted input stream does not expand further when
+%     appearing in an \texttt{x}-type or \texttt{e}-type argument expansion.
+%   \end{texnote}
+% \end{function}
+%
+% \begin{function}[rEXP,updated = 2020-02-20]{\keyval_parse:NNn}
 %   \begin{syntax}
 %     \cs{keyval_parse:NNn} \meta{function_1} \meta{function_2} \Arg{key--value list}
 %   \end{syntax}
@@ -920,6 +958,9 @@
 %   all). Spaces are trimmed from the ends of the \meta{key} and \meta{value},
 %   then one \emph{outer} set of braces is removed from the \meta{key}
 %   and \meta{value} as part of the processing.
+%
+%   This shares the implementation of \cs{keyval_parse:nnn}, the difference is
+%   only semantically.
 %   \begin{texnote}
 %     The result is returned within \cs{exp_not:n}, which means that the
 %     converted input stream does not expand further when appearing in an
@@ -984,9 +1025,10 @@
 % \begin{macro}[EXP]{\@@_loop_active:nnw}
 %   First a fast test for the end of the loop is done, it'll gobble everything
 %   up to a \cs{s_@@_tail}. The loop ending macro will gobble everything to the
-%   last \cs{s_@@_mark} in this definition.
+%   last comma in this definition.
 %   If the end isn't reached yet, start the second loop splitting at other
-%   commas, and after that one iterate the current loop.
+%   commas, the next iteration of this first loop will be inserted by the end of
+%   \cs{@@_loop_other:nnw}.
 %    \begin{macrocode}
       \cs_new:Npn \@@_loop_active:nnw ##1 ##2 ##3 #1
         {
@@ -1128,7 +1170,8 @@
         { \@@_trim:nN { ##1 } \@@_split_other_auxii:w }
 %    \end{macrocode}
 %   We know that the value doesn't contain misplaced active equals signs but we
-%   have to test for others.
+%   have to test for others. Also we need to sanitise the previous test, which
+%   is done here and not earlier to avoid superfluous argument grabbing.
 %    \begin{macrocode}
       \cs_new:Npn \@@_split_other_auxii:w
           ##1 ##2 \s_@@_nil = \s_@@_mark \@@_clean_up_other:w
@@ -1170,7 +1213,8 @@
 % \begin{macro}[EXP]{\@@_misplaced_equal_after_active_error:w}
 % \begin{macro}[EXP]{\@@_misplaced_equal_in_split_error:w}
 %   All these two macros do is gobble the remainder of the current other loop
-%   execution and throw an error.
+%   execution and throw an error. Afterwards they have to insert the next loop
+%   iteration.
 %    \begin{macrocode}
       \cs_new:Npn \@@_misplaced_equal_after_active_error:w
           \s_@@_mark ##1 \s_@@_stop \s_@@_mark ##2 \s_@@_nil
@@ -1197,7 +1241,8 @@
 % \begin{macro}[EXP]{\@@_end_loop_other:w, \@@_end_loop_active:w}
 %   All that's left for the parsing loops are the macros which end the
 %   recursion. Both just gobble the remaining tokens of the respective loop
-%   including the next recursion call.
+%   including the next recursion call. \cs{@@_end_loop_other:w} also has to
+%   insert the next iteration of the active loop.
 %    \begin{macrocode}
       \cs_new:Npn \@@_end_loop_other:w
           \s_@@_tail
@@ -1228,7 +1273,8 @@
 %   These macros will be called on the parsed keys and values of the key--value
 %   list. All arguments are completely trimmed. They test for blank key names
 %   and call the functions passed to \cs{keyval_parse:nnn} inside of
-%   \cs{exp_not:n} with the correct arguments.
+%   \cs{exp_not:n} with the correct arguments. Afterwards they insert the next
+%   iteration of the other loop.
 %    \begin{macrocode}
 \cs_new:Npn \@@_pair:nnnn #1 #2 #3 #4
   {