[latex3-commits] [latex3/latex3] main: Deprecate \keys_set_filter:nnn(nN) (d1f41d26d)

github at latex-project.org github at latex-project.org
Wed Jan 10 14:38:17 CET 2024


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

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

commit d1f41d26d5846ec6068b250f6e36588e1f6e0a28
Author: Joseph Wright <joseph.wright at morningstar2.co.uk>
Date:   Wed Jan 10 07:46:35 2024 +0000

    Deprecate \keys_set_filter:nnn(nN)


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

d1f41d26d5846ec6068b250f6e36588e1f6e0a28
 l3kernel/CHANGELOG.md            |  6 ++++
 l3kernel/doc/l3obsolete.txt      | 12 +++++++
 l3kernel/l3deprecation.dtx       | 27 ++++++++++++++++
 l3kernel/l3keys.dtx              | 68 ++++++++++++++++++++--------------------
 l3kernel/testfiles/m3keys004.lvt | 20 ++++++------
 l3kernel/testfiles/m3keys004.tlg |  4 +--
 l3trial/l3check/l3check.dtx      |  4 +--
 7 files changed, 93 insertions(+), 48 deletions(-)

diff --git a/l3kernel/CHANGELOG.md b/l3kernel/CHANGELOG.md
index 30d1e68da..deea9033a 100644
--- a/l3kernel/CHANGELOG.md
+++ b/l3kernel/CHANGELOG.md
@@ -7,10 +7,16 @@ this project uses date-based 'snapshot' version identifiers.
 
 ## [Unreleased]
 
+### Added
+- `\keys_set_exclude_groups:nnn(nN)` to replace `\keys_set_filter:nnn(nN)`
+
 ### Changed
 - Set `l3doc` option `kernel` off as-standard (issue \#1403)
 - Moved `\seq_set_filter:NNn` to stable
 
+### Deprecated
+- `\keys_set_filter:nnn(nN)` in favor of  `\keys_set_exclude_groups:nnn(nN)`
+
 ## [2024-01-04]
 
 ### Added
diff --git a/l3kernel/doc/l3obsolete.txt b/l3kernel/doc/l3obsolete.txt
index 2066ef6f0..a6a046256 100644
--- a/l3kernel/doc/l3obsolete.txt
+++ b/l3kernel/doc/l3obsolete.txt
@@ -37,6 +37,18 @@ Function                            Date deprecated
 \iow_shipout_x:cx                        2023-09-17
 \iow_shipout_x:Nn                        2023-09-17
 \iow_shipout_x:Nx                        2023-09-17
+\keys_set_filter:nnn                     2024-01-10
+\keys_set_filter:nnV                     2024-01-10
+\keys_set_filter:nnv                     2024-01-10
+\keys_set_filter:nno                     2024-01-10
+\keys_set_filter:nnnN                    2024-01-10
+\keys_set_filter:nnVN                    2024-01-10
+\keys_set_filter:nnvN                    2024-01-10
+\keys_set_filter:nnoN                    2024-01-10
+\keys_set_filter:nnnnN                   2024-01-10
+\keys_set_filter:nnVnN                   2024-01-10
+\keys_set_filter:nnvnN                   2024-01-10
+\keys_set_filter:nnonN                   2024-01-10
 \l_keys_key_tl                           2020-02-08
 \l_keys_path_tl                          2020-02-08
 \l_text_accents_tl                       2023-02-07
diff --git a/l3kernel/l3deprecation.dtx b/l3kernel/l3deprecation.dtx
index c19793808..0882fcd64 100644
--- a/l3kernel/l3deprecation.dtx
+++ b/l3kernel/l3deprecation.dtx
@@ -503,6 +503,33 @@
 % \end{macro}
 % \end{macro}
 %
+% \begin{macro}[deprecated]
+%   {
+%     \keys_set_exclude_groups:nnnN, \keys_set_exclude_groups:nnVN,
+%     \keys_set_exclude_groups:nnvN, \keys_set_exclude_groups:nnoN
+%   }
+% \begin{macro}[deprecated]
+%   {
+%     \keys_set_exclude_groups:nnnnN, \keys_set_exclude_groups:nnVnN,
+%     \keys_set_exclude_groups:nnvnN, \keys_set_exclude_groups:nnonN
+%   }
+% \begin{macro}[deprecated]
+%   {
+%     \keys_set_exclude_groups:nnn, \keys_set_exclude_groups:nnV,
+%     \keys_set_exclude_groups:nnv, \keys_set_exclude_groups:nno
+%   }
+%    \begin{macrocode}
+\cs_set_eq:NN \keys_set_filter:nnn \keys_set_exclude_groups:nnn
+\cs_generate_variant:Nn \keys_set_filter:nnn { nnV , nnv , nno }
+\cs_set_eq:NN \keys_set_filter:nnnN \keys_set_exclude_groups:nnnN
+\cs_generate_variant:Nn \keys_set_filter:nnnN { nnV , nnv , nno }
+\cs_set_eq:NN \keys_set_filter:nnnnN \keys_set_exclude_groups:nnnnN
+\cs_generate_variant:Nn \keys_set_filter:nnnnN { nnV , nnv , nno }
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
 % \subsection{Deprecated \pkg{l3pdf} functions}
 %
 %    \begin{macrocode}
diff --git a/l3kernel/l3keys.dtx b/l3kernel/l3keys.dtx
index c2fe5ae3f..e142e6b22 100644
--- a/l3kernel/l3keys.dtx
+++ b/l3kernel/l3keys.dtx
@@ -856,29 +856,29 @@
 % groups to be made \enquote{active}, or by marking one or more groups to
 % be ignored in key setting.
 %
-% \begin{function}[added = 2013-07-14, updated = 2019-01-29]
+% \begin{function}[added = 2024-01-10]
 %   {
-%     \keys_set_filter:nnn, \keys_set_filter:nnV,
-%     \keys_set_filter:nnv, \keys_set_filter:nno,
-%     \keys_set_filter:nnnN, \keys_set_filter:nnVN,
-%     \keys_set_filter:nnvN, \keys_set_filter:nnoN,
-%     \keys_set_filter:nnnnN, \keys_set_filter:nnVnN,
-%     \keys_set_filter:nnvnN, \keys_set_filter:nnonN,
+%     \keys_set_exclude_groups:nnn, \keys_set_exclude_groups:nnV,
+%     \keys_set_exclude_groups:nnv, \keys_set_exclude_groups:nno,
+%     \keys_set_exclude_groups:nnnN, \keys_set_exclude_groups:nnVN,
+%     \keys_set_exclude_groups:nnvN, \keys_set_exclude_groups:nnoN,
+%     \keys_set_exclude_groups:nnnnN, \keys_set_exclude_groups:nnVnN,
+%     \keys_set_exclude_groups:nnvnN, \keys_set_exclude_groups:nnonN,
 %   }
 %   \begin{syntax}
-%     \cs{keys_set_filter:nnn} \Arg{module} \Arg{groups} \Arg{keyval list}
-%     \cs{keys_set_filter:nnnN} \Arg{module} \Arg{groups} \Arg{keyval list} \meta{tl}
-%     \cs{keys_set_filter:nnnnN} \Arg{module} \Arg{groups} \Arg{keyval list} \meta{root} \meta{tl}
+%     \cs{keys_set_exclude_groups:nnn} \Arg{module} \Arg{groups} \Arg{keyval list}
+%     \cs{keys_set_exclude_groups:nnnN} \Arg{module} \Arg{groups} \Arg{keyval list} \meta{tl}
+%     \cs{keys_set_exclude_groups:nnnnN} \Arg{module} \Arg{groups} \Arg{keyval list} \meta{root} \meta{tl}
 %   \end{syntax}
-%   Activates key filtering in an \enquote{opt-out} sense: keys assigned to any
-%   of the \meta{groups} specified are ignored. The \meta{groups} are
+%   Sets keys by excluding those in the specificied \meta{groups}.
+%   The \meta{groups} are
 %   given as a comma-separated list. Unknown keys are not assigned to any
 %   group and are thus always set. The key--value pairs for each
 %   key which is filtered out are stored in the \meta{tl} in a
 %   comma-separated form (\emph{i.e.}~an edited version of the \meta{keyval
-%   list}). The \cs{keys_set_filter:nnn} version skips this stage.
+%   list}). The \cs{keys_set_exclude_groups:nnn} version skips this stage.
 %
-%   Use of \cs{keys_set_filter:nnnN} can be nested, with the correct residual
+%   Use of \cs{keys_set_exclude_groups:nnnN} can be nested, with the correct residual
 %   \meta{keyval list} returned at each stage. In the version which takes
 %   a \meta{root} argument, the key list is returned relative to that point
 %   in the key tree. In the cases without a \meta{root} argument, only
@@ -2887,21 +2887,21 @@
 %
 % \begin{macro}
 %   {
-%     \keys_set_filter:nnnN, \keys_set_filter:nnVN, \keys_set_filter:nnvN,
-%       \keys_set_filter:nnoN
+%     \keys_set_exclude_groups:nnnN, \keys_set_exclude_groups:nnVN,
+%     \keys_set_exclude_groups:nnvN, \keys_set_exclude_groups:nnoN
 %   }
 % \begin{macro}
 %   {
-%     \keys_set_filter:nnnnN, \keys_set_filter:nnVnN,
-%     \keys_set_filter:nnvnN, \keys_set_filter:nnonN
+%     \keys_set_exclude_groups:nnnnN, \keys_set_exclude_groups:nnVnN,
+%     \keys_set_exclude_groups:nnvnN, \keys_set_exclude_groups:nnonN
 %   }
-% \begin{macro}{\@@_set_filter:nnnnnN}
+% \begin{macro}{\@@_set_exclude_groups:nnnnnN}
 % \begin{macro}
 %   {
-%     \keys_set_filter:nnn, \keys_set_filter:nnV, \keys_set_filter:nnv,
-%       \keys_set_filter:nno
+%     \keys_set_exclude_groups:nnn, \keys_set_exclude_groups:nnV,
+%     \keys_set_exclude_groups:nnv, \keys_set_exclude_groups:nno
 %   }
-% \begin{macro}{\@@_set_filter:nnnn}
+% \begin{macro}{\@@_set_exclude_groups:nnnn}
 % \begin{macro}
 %   {
 %     \keys_set_groups:nnn, \keys_set_groups:nnV, \keys_set_groups:nnv,
@@ -2914,30 +2914,30 @@
 %   also apply here. We have a bit more shuffling to do to keep everything
 %   nestable.
 %    \begin{macrocode}
-\cs_new_protected:Npn \keys_set_filter:nnnN #1#2#3#4
+\cs_new_protected:Npn \keys_set_exclude_groups:nnnN #1#2#3#4
   {
-    \exp_args:No \@@_set_filter:nnnnnN
+    \exp_args:No \@@_set_exclude_groups:nnnnnN
       \l_@@_unused_clist
         \q_@@_no_value {#1} {#2} {#3} #4
   }
-\cs_generate_variant:Nn \keys_set_filter:nnnN { nnV , nnv , nno }
-\cs_new_protected:Npn \keys_set_filter:nnnnN #1#2#3#4#5
+\cs_generate_variant:Nn \keys_set_exclude_groups:nnnN { nnV , nnv , nno }
+\cs_new_protected:Npn \keys_set_exclude_groups:nnnnN #1#2#3#4#5
   {
-    \exp_args:No \@@_set_filter:nnnnnN
+    \exp_args:No \@@_set_exclude_groups:nnnnnN
       \l_@@_unused_clist {#4} {#1} {#2} {#3} #5
   }
-\cs_generate_variant:Nn \keys_set_filter:nnnnN { nnV , nnv , nno }
-\cs_new_protected:Npn \@@_set_filter:nnnnnN #1#2#3#4#5#6
+\cs_generate_variant:Nn \keys_set_exclude_groups:nnnnN { nnV , nnv , nno }
+\cs_new_protected:Npn \@@_set_exclude_groups:nnnnnN #1#2#3#4#5#6
   {
     \clist_clear:N \l_@@_unused_clist
-    \@@_set_filter:nnnn {#2} {#3} {#4} {#5}
+    \@@_set_exclude_groups:nnnn {#2} {#3} {#4} {#5}
     \__kernel_tl_set:Nx #6 { \exp_not:o \l_@@_unused_clist }
     \__kernel_tl_set:Nx \l_@@_unused_clist { \exp_not:n {#1} }
   }
-\cs_new_protected:Npn \keys_set_filter:nnn #1#2#3
-  {\@@_set_filter:nnnn \q_@@_no_value {#1} {#2} {#3} }
-\cs_generate_variant:Nn \keys_set_filter:nnn { nnV , nnv , nno }
-\cs_new_protected:Npn \@@_set_filter:nnnn #1#2#3#4
+\cs_new_protected:Npn \keys_set_exclude_groups:nnn #1#2#3
+  {\@@_set_exclude_groups:nnnn \q_@@_no_value {#1} {#2} {#3} }
+\cs_generate_variant:Nn \keys_set_exclude_groups:nnn { nnV , nnv , nno }
+\cs_new_protected:Npn \@@_set_exclude_groups:nnnn #1#2#3#4
   {
     \use:e
       {
diff --git a/l3kernel/testfiles/m3keys004.lvt b/l3kernel/testfiles/m3keys004.lvt
index b98fb8b67..647e2ee18 100644
--- a/l3kernel/testfiles/m3keys004.lvt
+++ b/l3kernel/testfiles/m3keys004.lvt
@@ -100,7 +100,7 @@
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
-\TEST { \keys_set_filter:nnn }
+\TEST { \keys_set_exclude_groups:nnn }
   {
     \keys_define:nn { module }
       {
@@ -112,7 +112,7 @@
         key-two   .groups:n = { b , c } ,
         key-three .groups:n = { a , c } ,
       }
-    \keys_set_filter:nnn { module }
+    \keys_set_exclude_groups:nnn { module }
       { a }
       {
         key-one   = value       ,
@@ -120,7 +120,7 @@
         key-four                ,
         key-five = unknown-value
       }
-    \keys_set_filter:nnn { module }
+    \keys_set_exclude_groups:nnn { module }
       { c , d }
       {
         key-one   = value       ,
@@ -128,7 +128,7 @@
         key-four                ,
         key-five = unknown-value
       }
-    \keys_set_filter:nnn { module }
+    \keys_set_exclude_groups:nnn { module }
       { e }
       {
         key-one   = value       ,
@@ -136,7 +136,7 @@
         key-four                ,
         key-five = unknown-value
       }
-    \keys_set_filter:nnn { module }
+    \keys_set_exclude_groups:nnn { module }
       { }
       {
         key-one   = value       ,
@@ -146,7 +146,7 @@
       }
   }
 
-\TEST { \keys_set_filter:nnnN }
+\TEST { \keys_set_exclude_groups:nnnN }
   {
     \keys_define:nn { module }
       {
@@ -158,7 +158,7 @@
         key-two   .groups:n = { b , c } ,
         key-three .groups:n = { a , c } ,
       }
-    \keys_set_filter:nnnN { module }
+    \keys_set_exclude_groups:nnnN { module }
       { a }
       {
         key-one   = value       ,
@@ -168,7 +168,7 @@
       }
       \l_tmpa_tl
     \tl_log:N \l_tmpa_tl
-    \keys_set_filter:nnnN { module }
+    \keys_set_exclude_groups:nnnN { module }
       { c , d }
       {
         key-one   = value       ,
@@ -178,7 +178,7 @@
       }
       \l_tmpa_tl
     \tl_log:N \l_tmpa_tl
-    \keys_set_filter:nnnN { module }
+    \keys_set_exclude_groups:nnnN { module }
       { e }
       {
         key-one   = value       ,
@@ -188,7 +188,7 @@
       }
       \l_tmpa_tl
     \tl_log:N \l_tmpa_tl
-    \keys_set_filter:nnnN { module }
+    \keys_set_exclude_groups:nnnN { module }
       { }
       {
         key-one   = value       ,
diff --git a/l3kernel/testfiles/m3keys004.tlg b/l3kernel/testfiles/m3keys004.tlg
index f269b544a..e527a0fed 100644
--- a/l3kernel/testfiles/m3keys004.tlg
+++ b/l3kernel/testfiles/m3keys004.tlg
@@ -52,7 +52,7 @@ Defining key module/key-two on line ...
 > \l_tmpb_tl=key-three={foo}.
 ============================================================
 ============================================================
-TEST 5: \keys_set_filter:nnn 
+TEST 5: \keys_set_exclude_groups:nnn 
 ============================================================
 Defining key module/key-one on line ...
 Defining key module/key-two on line ...
@@ -93,7 +93,7 @@ The module 'module' does not have a key called 'module/key-five'.
 Check that you have spelled the key name correctly.
 ============================================================
 ============================================================
-TEST 6: \keys_set_filter:nnnN 
+TEST 6: \keys_set_exclude_groups:nnnN 
 ============================================================
 Defining key module/key-one on line ...
 Defining key module/key-two on line ...
diff --git a/l3trial/l3check/l3check.dtx b/l3trial/l3check/l3check.dtx
index 2eddc1165..73590cd00 100644
--- a/l3trial/l3check/l3check.dtx
+++ b/l3trial/l3check/l3check.dtx
@@ -1856,10 +1856,10 @@
 % \subsubsection{\pkg{l3keys}}
 % ^^A todo: add checking of args of key properties such as |.tl_set:N|
 %
-% |\keyval_parse:NNn|, |\keys_set_known:nnN|, |\keys_set_filter:nnnN|,
+% |\keyval_parse:NNn|, |\keys_set_known:nnN|, |\keys_set_exclude_groups:nnnN|,
 %
 % |\keys_(show/log):nn|, |\keys_set:nn|, |\keys_set_known:nn(/N)|,
-% |\keys_set_filter:nnnN|, |\keys_set_groups:nnn|, could check the
+% |\keys_set_exclude_groups:nnnN|, |\keys_set_groups:nnn|, could check the
 % module is known due to |\keys_define:nn|, \emph{i.e.}, that at least
 % one key is known for this module.
 %





More information about the latex3-commits mailing list.