[latex3-commits] [git/LaTeX3-latex3-latex3] main: added prop_to_keyval:N (1a1cf19fe)

[Joseph Wright]

Repository : https://github.com/latex3/latex3
On branch  : main
Link       : https://github.com/latex3/latex3/commit/1a1cf19fef45d7f9727470048680abcd0ad30bd8

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

commit 1a1cf19fef45d7f9727470048680abcd0ad30bd8
Author: Jonathan Spratte <jspratte at yahoo.de>
Date:   Sun Nov 15 21:12:33 2020 +0100

    added prop_to_keyval:N


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

1a1cf19fef45d7f9727470048680abcd0ad30bd8
 l3kernel/l3prop.dtx | 86 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 86 insertions(+)

diff --git a/l3kernel/l3prop.dtx b/l3kernel/l3prop.dtx
index 4d40ecd4a..392aac58e 100644
--- a/l3kernel/l3prop.dtx
+++ b/l3kernel/l3prop.dtx
@@ -311,6 +311,19 @@
 %   the input stream as an \meta{integer denotation}.
 % \end{function}
 %
+% \begin{function}[EXP]{\prop_to_keyval:N}
+%   \begin{syntax}
+%     \cs{prop_to_keyval:N} \meta{property list}
+%   \end{syntax}
+%   Expands to the \meta{property list} in a key--value notation.
+%   \begin{texnote}
+%     The result is returned within the \tn{unexpanded} primitive
+%     (\cs{exp_not:n}), which means that the key--value list does not expand
+%     further when appearing in an \texttt{x}-type argument expansion.
+%     It also needs exactly two steps of expansion.
+%   \end{texnote}
+% \end{function}
+%
 % \section{Modifying property lists}
 %
 % \begin{function}[added = 2012-05-12]
@@ -1055,6 +1068,79 @@
 % \end{macro}
 % \end{macro}
 %
+% \begin{macro}[EXP]{\prop_to_keyval:N}
+% \begin{macro}[EXP]
+%   {\@@_to_keyval_aux:w, \@@_to_keyval_aux:nn, % \@@_to_keyval_aux:nnw}
+%   Each property name and value pair will be returned in the form
+%   \meta{name}\verb*|= |\marg{value}. As one of the main use cases for this
+%   macro is to pass the \meta{property list} on to a key--value parser, we have
+%   to make sure that the behaviour is as good as possible. Using a space before
+%   the opening brace we get the correct brace stripping behaviour for most of
+%   the key--value parsers available in \LaTeX.
+%   If \cs{tex_expanded:D} is available this function makes use of it, so there
+%   are two different implementations here. They both start with
+%   \cs{__kernel_exp_not:w} to start the expansion context to expand in two
+%   steps. If the \meta{property list} is empty they just leave an empty set of
+%   braces in the input stream for \cs{__kernel_exp_not:w}.
+%   In order to not have to read the contents of the \meta{property list} more
+%   often than necessary, in both versions an unmatched closing brace is used to
+%   mark the end of the result. Once we're done we can then leave an unmatched
+%   opening brace in the input stream so that \cs{__kernel_exp_not:w} grabs its
+%   argument.
+%    \begin{macrocode}
+\cs_if_exist:NTF \tex_expanded:D
+  {
+%    \end{macrocode}
+%   The variant using \cs{tex_expanded:D} can just iterate over the
+%   \meta{property list} and remove the leading comma afterwards.
+%    \begin{macrocode}
+    \cs_new:Npn \prop_to_keyval:N #1
+      {
+        \__kernel_exp_not:w
+          \prop_if_empty:NTF #1
+            { {} }
+            {
+              \if_false: { \fi:
+                \exp_after:wN \@@_to_keyval_aux:w
+                \tex_expanded:D
+                  { \prop_map_function:NN #1 \@@_to_keyval_aux:nn }
+              }
+            }
+      }
+    \cs_new:Npn \@@_to_keyval_aux:w ,
+      { \exp_after:wN { \if_false: } \fi: }
+    \cs_new:Npn \@@_to_keyval_aux:nn #1#2
+      { , \exp_not:n { #1 =~ {#2} } }
+  }
+%    \end{macrocode}
+%   The other variant will iterate over the \meta{property list} and has to
+%   output the result behind a marker. As a result this is considerably slower
+%   than the \cs{tex_expanded:D} using variant.
+%   After the loop the leading comma can be gobbled.
+%    \begin{macrocode}
+  {
+    \cs_new:Npn \prop_to_keyval:N #1
+      {
+        \__kernel_exp_not:w
+          \prop_if_empty:NTF #1
+            { {} }
+            {
+              \if_false: { \fi:
+                \prop_map_function:NN #1 \@@_to_keyval_aux:nnw
+                \@@_to_keyval_aux:w
+                \s_@@_mark
+              }
+            }
+      }
+    \cs_new:Npn \@@_to_keyval_aux:w \s_@@_mark ,
+      { \exp_after:wN { \if_false: } \fi: }
+    \cs_new:Npn \@@_to_keyval_aux:nnw #1#2#3 \s_@@_mark
+      { #3 \s_@@_mark , #1 =~ {#2} }
+  }
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
 % \begin{macro}[TF, tested = m3prop004]
 %   {\prop_pop:NnN, \prop_pop:cnN, \prop_gpop:NnN, \prop_gpop:cnN}
 %   Popping an item from a property list, keeping track of whether