[latex3-commits] [git/LaTeX3-latex3-latex2e] options: Implement David's suggestions (a58735ae)
Joseph Wright
joseph.wright at morningstar2.co.uk
Wed Dec 1 21:59:46 CET 2021
Repository : https://github.com/latex3/latex2e
On branch : options
Link : https://github.com/latex3/latex2e/commit/a58735ae0a72864ff1acbb801a9407ecbe09e9a8
>---------------------------------------------------------------
commit a58735ae0a72864ff1acbb801a9407ecbe09e9a8
Author: Joseph Wright <joseph.wright at morningstar2.co.uk>
Date: Wed Dec 1 20:59:46 2021 +0000
Implement David's suggestions
>---------------------------------------------------------------
a58735ae0a72864ff1acbb801a9407ecbe09e9a8
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 d707683b..3593dac5 100644
--- a/base/doc/ltnews35.tex
+++ b/base/doc/ltnews35.tex
@@ -153,31 +153,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{???}
diff --git a/base/ltclass.dtx b/base/ltclass.dtx
index df4844c7..74ce8c18 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.