[latex3-commits] [git/LaTeX3-latex3-latex2e] options: First implementation for \DeclareKeysOptions (c258bf87)

[Joseph Wright]

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

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

commit c258bf87eb6460ef8145ace8314111a65e8ebbb5
Author: Joseph Wright <joseph.wright at morningstar2.co.uk>
Date:   Fri Nov 26 13:28:33 2021 +0000

    First implementation for \DeclareKeysOptions


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

c258bf87eb6460ef8145ace8314111a65e8ebbb5
 base/doc/ltnews35.tex |  5 +++++
 base/ltkeys.dtx       | 61 ++++++++++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 65 insertions(+), 1 deletion(-)

diff --git a/base/doc/ltnews35.tex b/base/doc/ltnews35.tex
index 7b535667..d0e215d6 100644
--- a/base/doc/ltnews35.tex
+++ b/base/doc/ltnews35.tex
@@ -161,6 +161,11 @@ can otherwise be given as an optional argument
 \ProcessKeysOptions[family]
 \end{verbatim}
 
+To support creating key options in for this mechanism, the new command
+\cs{DeclareKeysOptions} 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.
+
 \subsection{???}
 %
 \githubissue{???}
diff --git a/base/ltkeys.dtx b/base/ltkeys.dtx
index 4cea46da..eaf3ea6b 100644
--- a/base/ltkeys.dtx
+++ b/base/ltkeys.dtx
@@ -53,7 +53,46 @@
 %
 % As with any key--value input, using key--value pairs as package or
 % class options has two parts: creating the key options and setting (using)
-% them.
+% them. Options created in this way \emph{may} be used after package loading
+% as general key--value settings: this will depend on the nature of the
+% underlying code.
+%
+% \begin{function}{\DeclareKeysOptions}
+%   \begin{syntax}
+%     \cs{DeclareKeysOptions} \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 \meat{property}, taken from the list
+%   \begin{itemize}
+%     \item \texttt{.if} --- sets a \TeX{} \cs{if...} switch
+%     \item \texttt{.store} --- stores a value in a macro
+%     \item \texttt{.usage} -- defines whether the option can be given only
+%       when loading (\texttt{load}), in the preamble (\texttt{preamble}) or
+%       has no limitation on scope (\texttt{general})
+%   \end{itemize}
+%   The part of the \meta{key} before the \meta{property} is the \meta{name},
+%   with the \meta{value} working with the \meta{property} to define the
+%   behaviour of the option.
+%
+%   For example, with
+%   \begin{verbatim}
+%     \DeclareKeysOptions[mypkg]
+%       {
+%         draft.if          = @mypkg at draft      ,
+%         draft.usage       = preamble          ,
+%         name.store        = \@mypkg at name      ,
+%         name.usage        = load              ,
+%         second-name.store = \@mypkg at other@name
+%       }
+%   \end{verbatim}
+%   three options would be create. The option \texttt{draft} can be given
+%   anywhere in the preamble, and will set a switch called \cs{if at mypkg@draft}.
+%   The option \texttt{name} can only be given during package loading, and will
+%   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}.
+% \end{function}
 %
 % \begin{function}{\ProcessKeysOptions}
 %   \begin{syntax}
@@ -247,6 +286,26 @@
 %
 % \subsection{The document interfaces}
 %
+% \begin{macro}{\DeclareKeysOption}
+% \begin{macro}{\@@_options_define:nn}
+%   Defining key options is quite straight-forward: we have an intermediate
+%   function to allow for potential set-up steps.
+%    \begin{macrocode}
+\NewDocumentCommand \DeclareKeysOption { o +m }
+  {
+    \IfNoValueTF {#1}
+      { \exp_args:NV \@@_options_define:nn \@currname }
+      { \@@_options_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}
 %   We need to deal with the older interface from \pkg{l3keys2e} here: it had