[latex3-commits] [git/LaTeX3-latex3-latex2e] options: Implement David's suggestions (329807db)

Joseph Wright joseph.wright at morningstar2.co.uk
Wed Jan 12 18:27:10 CET 2022


Repository : https://github.com/latex3/latex2e
On branch  : options
Link       : https://github.com/latex3/latex2e/commit/329807db3607786881b52a5c8e1563fb93fb5d27

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

commit 329807db3607786881b52a5c8e1563fb93fb5d27
Author: Joseph Wright <joseph.wright at morningstar2.co.uk>
Date:   Wed Dec 1 20:59:46 2021 +0000

    Implement David's suggestions


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

329807db3607786881b52a5c8e1563fb93fb5d27
 base/doc/ltnews35.tex          | 12 ++---
 base/ltclass.dtx               |  2 +-
 base/ltkeys.dtx                | 99 ++++++++++++++++++------------------------
 base/testfiles/github-0710.lvt | 12 ++---
 base/testfiles/github-0710.tlg |  4 +-
 5 files changed, 58 insertions(+), 71 deletions(-)

diff --git a/base/doc/ltnews35.tex b/base/doc/ltnews35.tex
index d050b567..58c0a9c7 100644
--- a/base/doc/ltnews35.tex
+++ b/base/doc/ltnews35.tex
@@ -207,31 +207,31 @@ package options. This ability has now been integrated directly into the kernel.
 As part of this integration, the syntax for processing keyval options has been
 refined, such that
 \begin{verbatim}
-\ProcessKeysOptions
+\ProcessKeyOptions
 \end{verbatim}
 will now automatically pick up the package name as the key \emph{family}, which
 can otherwise be given as an optional argument
 \begin{verbatim}
-\ProcessKeysOptions[family]
+\ProcessKeyOptions[family]
 \end{verbatim}
 A version which does not consider global options,
-\cs{ProcessKeysPackageOptions}, is also available.
+\cs{ProcessKeyPackageOptions}, is also available.
 
 To support creating key options in for this mechanism, the new command
-\cs{DeclareKeysOptions} has been added. This works using the same general
+\cs{DeclareKeys} has been added. This works using the same general
 approach as \pkg{l3keys} or \pkg{pgfkeys}: each key has one or more
 \emph{properties} which define its behavior.
 
 Options for packages which use this new approach will not be checked for
 clashes by the kernel. Instead, each time a \cs{usepackage} or
 \cs{RequirePackage} line is encountered, the list of options given will be
-passed to \cs{ProcessKeysPackageOptions}. Options which can only be given
+passed to \cs{ProcessKeyPackageOptions}. Options which can only be given
 the first time a package is loaded can be marked using the property
 \texttt{.usage = load}, and will result in a warning if used in a subsequent
 package loading line.
 
 Package options defined in this way can also be set within a package using
-the new command \cs{SetKeysOptions}, which again takes an optional argument
+the new command \cs{SetKeys}, which again takes an optional argument
 to specify the \emph{family}, plus a mandatory one for the options themselves.
 
 \subsection{Floating point and integer calculations}
diff --git a/base/ltclass.dtx b/base/ltclass.dtx
index 6fbbc91b..62e5b35d 100644
--- a/base/ltclass.dtx
+++ b/base/ltclass.dtx
@@ -2185,7 +2185,7 @@
         {\@onefilewithoptions at clashchk{#2}}
         {%
           \@namedef{opt@\@currname.\@currext}{#2}%
-          \expandafter\expandafter\expandafter\ProcessKeysPackageOptions
+          \expandafter\expandafter\expandafter\ProcessKeyPackageOptions
             \expandafter\expandafter\expandafter
               [\csname opt at fam@\@currname.\@currext\endcsname]%
         }%
diff --git a/base/ltkeys.dtx b/base/ltkeys.dtx
index ddc08919..91cc649f 100644
--- a/base/ltkeys.dtx
+++ b/base/ltkeys.dtx
@@ -57,13 +57,18 @@
 % as general key--value settings: this will depend on the nature of the
 % underlying code.
 %
-% \begin{function}{\DeclareKeysOptions}
+% \begin{function}{\DeclareKeys}
 %   \begin{syntax}
-%     \cs{DeclareKeysOptions} \oarg{family} \marg{declarations}
+%     \cs{DeclareKeys} \oarg{family} \marg{declarations}
 %   \end{syntax}
 %   Creates a series of options from a comma-separated \meta{declarations} list.
-%   Each entry in this list is a key--value pair, in which the \meta{key} should
-%   have a \meta{property}, taken from the list
+%   Each entry in this list is a key--value pair, with the \meta{key} having one
+%   or more \meta{properties}. A small number of \enquote{basic}
+%   \meta{properties} are described below. The full range of properties,
+%   provided by \pkg{l3keys}, can also be used for more powerful processing.
+%   See \texttt{interface3} for the full details.
+%   
+%   The basic properties provided here are
 %   \begin{itemize}
 %     \item \texttt{.if} --- sets a \TeX{} \cs{if...} switch
 %     \item \texttt{.store} --- stores a value in a macro
@@ -77,7 +82,7 @@
 %
 %   For example, with
 %   \begin{verbatim}
-%     \DeclareKeysOptions[mypkg]
+%     \DeclareKeys[mypkg]
 %       {
 %         draft.if          = @mypkg at draft      ,
 %         draft.usage       = preamble          ,
@@ -92,37 +97,40 @@
 %   save whatever value it is given in \cs{@mypkg at name}. Finally, the option
 %   \texttt{second-name} can be given anywhere, and will save its value in
 %   \cs{@mypkg at other@name}.
+%
+%   Keys created \emph{before} the use of
+%   \cs{ProcessKeyOptions}/\cs{ProcessKeyPackageOptions} act as package options.
 % \end{function}
 %
-% \begin{function}{\ProcessKeysOptions}
+% \begin{function}{\ProcessKeyOptions}
 %   \begin{syntax}
-%     \cs{ProcessKeysOptions} \oarg{family}
+%     \cs{ProcessKeyOptions} \oarg{family}
 %   \end{syntax}
-%   The \cs{ProcessKeysOptions} function is used to check the current
+%   The \cs{ProcessKeyOptions} function is used to check the current
 %   option list against the keys defined for \meta{family}. Global (class)
 %   options and local (package) options are checked when this function
 %   is called in a package.
 % \end{function}
 %
-% \begin{function}{\ProcessKeysPackageOptions}
+% \begin{function}{\ProcessKeyPackageOptions}
 %   \begin{syntax}
-%     \cs{ProcessKeysPackageOptions} \oarg{family}
+%     \cs{ProcessKeyPackageOptions} \oarg{family}
 %   \end{syntax}
-%   This function works in a similar manner to \cs{ProcessKeysOptions}.
-%   When used in a package, \cs{ProcessKeysPackageOptions}
+%   This function works in a similar manner to \cs{ProcessKeyOptions}.
+%   When used in a package, \cs{ProcessKeyPackageOptions}
 %   will not examine any global (class) class options available. In contrast,
-%   \cs{ProcessKeysOptions} does parse class options (in common with the
+%   \cs{ProcessKeyOptions} does parse class options (in common with the
 %   classical \cs{ProcessOptions} command).
 % \end{function}
 %
-% \begin{function}{\SetKeysOptions}
+% \begin{function}{\SetKeys}
 %   \begin{syntax}
-%     \cs{SetKeysOptions} \oarg{family} \Arg{keyvals}
+%     \cs{SetKeys} \oarg{family} \Arg{keyvals}
 %   \end{syntax}
-%   Sets (applies) the explict list of \meta{keyvals}  for the \meta{family}:
+%   Sets (applies) the explicit list of \meta{keyvals}  for the \meta{family}:
 %   it the latter is not given, the value of \cs{@currname} used. This command
 %   may be used within a package to set options before or after using
-%   \cs{ProcessKeysOptions}/\cs{ProcessKeysPackageOptions}.
+%   \cs{ProcessKeyOptions}/\cs{ProcessKeyPackageOptions}.
 % \end{function}
 %
 % \StopEventually{}
@@ -161,7 +169,7 @@
 %    \end{macrocode}
 % \end{variable}
 %
-% \begin{macro}{\@@_options:Nn}
+% \begin{macro}{\@@_options:Nn, \@@_options:NV}
 % \begin{macro}{\@@_options_end:}
 %   The main function calls functions to collect up the global and local
 %   options into \cs{l_@@_options_clist} before calling the
@@ -198,7 +206,9 @@
     \bool_set_false:N \l_@@_options_loading_bool
     \cs_set_eq:NN \@unprocessedoptions \scan_stop:
     \@@_option_end:
+    \@@_options_loaded:n {#2}
   }
+\cs_generate_variant:Nn \@@_options:Nn { NV }
 \msg_new:nnnn { keys } { option-unknown }
   { Unknown~option~'#1'~for~package~#2. }
   {
@@ -316,65 +326,42 @@
 %
 % \subsection{The document interfaces}
 %
-% \begin{macro}{\DeclareKeysOptions}
-% \begin{macro}{\@@_options_define:nn}
+% \begin{macro}{\DeclareKeys}
 %   Defining key options is quite straight-forward: we have an intermediate
 %   function to allow for potential set-up steps.
 %    \begin{macrocode}
-\NewDocumentCommand \DeclareKeysOptions { o +m }
+\NewDocumentCommand \DeclareKeys { o +m }
   {
     \IfNoValueTF {#1}
-      { \exp_args:NV \@@_options_define:nn \@currname }
-      { \@@_options_define:nn {#1} }
+      { \exp_args:NV \keys_define:nn \@currname }
+      { \keys_define:nn {#1} }
         {#2}
   }
-\cs_new_protected:Npn \@@_options_define:nn #1#2
-  {
-    \keys_define:nn {#1} {#2}
-  }
 %    \end{macrocode}
 % \end{macro}
-% \end{macro}
 %
-% \begin{macro}{\ProcessKeysOptions}
-% \begin{macro}{\ProcessKeysPackageOptions}
+% \begin{macro}{\ProcessKeyOptions, \ProcessKeyPackageOptions}
 %   We need to deal with the older interface from \pkg{l3keys2e} here: it had
 %   a mandatory argument. We can mop that up using a look-ahead, and then
 %   exploit that information to determine whether the package option handling
 %   is set up for the new approach for clash handling.
 %    \begin{macrocode}
-\NewDocumentCommand \ProcessKeysOptions { o }
+\NewDocumentCommand \ProcessKeyOptions { o }
   {
     \IfNoValueTF {#1}
-      { \@@_options_group_check:N \c_true_bool }
-      {
-        \@@_options:Nn \c_true_bool {#1}
-        \@@_options_loaded:n {#1}
-      }
+      { \@@_options:NV \c_true_bool \@currname }
+      { \@@_options:Nn \c_true_bool {#1} }
   }
-\NewDocumentCommand \ProcessKeysPackageOptions { o }
+\NewDocumentCommand \ProcessKeyPackageOptions { o }
   {
     \IfNoValueTF {#1}
-      { \@@_options_group_check:N \c_false_bool }
-      {
-        \@@_options:Nn \c_false_bool {#1}
-        \@@_options_loaded:n {#1}
-      }
-  }
-\@onlypreamble \ProcessKeysOptions
-\@onlypreamble \ProcessKeysPackageOptions
-\cs_new_protected:Npn \@@_options_group_check:N #1
-  {
-    \peek_meaning:NTF \c_group_begin_token
-      { \@@_options:Nn #1 }
-      {
-        \exp_args:NNV \@@_options:Nn #1 \@currname
-        \exp_args:NV \@@_options_loaded:n \@currname
-      }
+      { \@@_options:NV \c_false_bool \@currname }
+      { \@@_options:Nn \c_false_bool {#1} }
   }
+\@onlypreamble \ProcessKeyOptions
+\@onlypreamble \ProcessKeyPackageOptions
 %    \end{macrocode}
 % \end{macro}
-% \end{macro}
 %
 % \subsection{Option usage scope}
 %
@@ -445,10 +432,10 @@
 %
 % \subsection{General key setting}
 %
-% \begin{macro}{\SetKeysOptions}
+% \begin{macro}{\SetKeys}
 %   A simple wrapper.
 %    \begin{macrocode}
-\NewDocumentCommand \SetKeysOptions { o +m }
+\NewDocumentCommand \SetKeys { o +m }
   {
     \IfNoValueTF {#1}
       { \keys_set:Vn \@currname }
diff --git a/base/testfiles/github-0710.lvt b/base/testfiles/github-0710.lvt
index 89a7f8af..539ce925 100644
--- a/base/testfiles/github-0710.lvt
+++ b/base/testfiles/github-0710.lvt
@@ -1,6 +1,6 @@
 \documentclass{article}
-\begin{filecontents}{mypkg.sty}
-\DeclareKeysOptions{
+\begin{filecontents}[overwrite]{mypkg.sty}
+\DeclareKeys{
   load-option-A .store = \my at A ,
   load-option-A .usage = load  ,
   load-option-B .store = \my at B ,
@@ -9,7 +9,7 @@
   preamble-option-D .store = \my at D ,
   preamble-option-D .usage = preamble
 }
-\ProcessKeysOptions
+\ProcessKeyOptions
 \newcommand\mypkgtest{%
   \begingroup
     \edef\x{\my at A:\my at B:\my at C:\my at D}%
@@ -32,18 +32,18 @@
 \mypkgtest
 \usepackage[load-option-B = 555]{mypkg}                           % 5
 \mypkgtest
-\SetKeysOptions[mypkg]{load-option-A = 666}                       % 6 
+\SetKeys[mypkg]{load-option-A = 666}                       % 6 
 \mypkgtest
 \usepackage[preamble-option-D = 777]{mypkg}                       % 7
 \mypkgtest
-\SetKeysOptions[mypkg]{preamble-option-D = 888}                   % 8 
+\SetKeys[mypkg]{preamble-option-D = 888}                   % 8 
 \mypkgtest
 
 \OMIT
 \begin{document}
 \TIMO
 
-\SetKeysOptions[mypkg]{general-option-C = 999,
+\SetKeys[mypkg]{general-option-C = 999,
   preamble-option-D = 999} % 9 
 \mypkgtest
 
diff --git a/base/testfiles/github-0710.tlg b/base/testfiles/github-0710.tlg
index 19861ba8..58c2c762 100644
--- a/base/testfiles/github-0710.tlg
+++ b/base/testfiles/github-0710.tlg
@@ -37,8 +37,8 @@ l. ...\mypkgtest
 (LaTeX3)        package "mypkg".
 For immediate help type H <return>.
  ...                                              
-l. ...\SetKeysOptions[mypkg]{load-option-A = 666}
-                                                                       % 6
+l. ...\SetKeys[mypkg]{load-option-A = 666}
+                                                                % 6
 LaTeX was asked to set a key called "load-option-A", but this is only allowed
 in the optional argument when loading package "mypkg".
 > \x=macro:





More information about the latex3-commits mailing list.