summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/xpackages/xtras/l3keys2e.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/xpackages/xtras/l3keys2e.dtx')
-rw-r--r--Master/texmf-dist/source/latex/xpackages/xtras/l3keys2e.dtx205
1 files changed, 82 insertions, 123 deletions
diff --git a/Master/texmf-dist/source/latex/xpackages/xtras/l3keys2e.dtx b/Master/texmf-dist/source/latex/xpackages/xtras/l3keys2e.dtx
index 43eec9ceff8..576a0161c94 100644
--- a/Master/texmf-dist/source/latex/xpackages/xtras/l3keys2e.dtx
+++ b/Master/texmf-dist/source/latex/xpackages/xtras/l3keys2e.dtx
@@ -77,9 +77,8 @@
%
% As with any key--value input, using key--value pairs as package or
% class options has two parts. The first stage is to define one or
-% more keys. This should be done using the \LaTeX3 module \pkg{l3keys}.
-% For example, an option which simply stores a value would be created
-% using:
+% more keys, using the \cs{keys_define:nn} function. For example, an
+% option which simply stores a value would be created using:
%\begin{verbatim}
% \keys_define:nn { module } {
% option .set:N = \l_module_variable_tl
@@ -89,92 +88,31 @@
% class containing the definition. The second stage is therefore to
% process the current options, searching for applicable keys.
%
-%\begin{function}{\ProcessKeysOptions}
+%\begin{function}{ \ProcessKeysOptions }
% \begin{syntax}
-% "\ProcessKeysOptions" \Arg{module}
+% \cs{ProcessKeysOptions} \Arg{module}
% \end{syntax}
% The \cs{ProcessKeysOptions} function is used to check the current
-% option list against the keys defined for <module>. Global (class)
+% option list against the keys defined for \Arg{module}. Global (class)
% options and local (package) options are checked when this function
% is called in a package. Each option which does match a key name is
% then used to attempt to set the appropriate key using
% \cs{keys_set:nn}. For example, the option defined earlier would be
-% processed by the line
-% \begin{verbatim}
-% \ProcessKeysOptions { module }
-% \end{verbatim}
+% processed by the line
+% \begin{verbatim}
+% \ProcessKeysOptions { module }
+% \end{verbatim}
%\end{function}
%
-%\begin{function}{\ProcessKeysPackageOptions}
+%\begin{function}{ \ProcessKeysPackageOptions }
% \begin{syntax}
-% "\ProcessKeysPackageOptions" \Arg{module}
+% \cs{ProcessKeysPackageOptions} \Arg{module}
% \end{syntax}
% This function works in a similar manner to \cs{ProcessKeysOptions}.
-% When used in a LaTeX2e package, \cs{ProcessKeysPackageOptions}
+% When used in a \LaTeXe\ package, \cs{ProcessKeysPackageOptions}
% will not examine any class options available. In contrast,
% \cs{ProcessKeysOptions} does parse class options (in common with the
-% LaTeX2e kernel function \cs{ProcessOptions}).
-%\end{function}
-%
-%\subsection{Internal functions and variables}
-%
-%\begin{variable}{\keys_latexe_options_clist}
-% Local options and applicable global (class) options are collected up
-% here prior to processing using \cs{keys_set:nn}.
-%\end{variable}
-%
-%\begin{function}{\keys_latexe_options:n}
-% \begin{syntax}
-% "\keys_latexe_options:n" \Arg{module}
-% \end{syntax}
-% Examines current global and local options, comparing them to the
-% keys defined for <module>. Option names which match defined keys are
-% then executed by passing the appropriate data to \cs{keys_set:nn}.
-%\end{function}
-%
-%\begin{function}{\keys_latexe_options_global:n}
-% \begin{syntax}
-% "\keys_latexe_options_global:n" \Arg{module}
-% \end{syntax}
-% Makes appropriate checks on global (class) options, then searches for
-% key matches for <module>.
-%\end{function}
-%
-%\begin{function}{\keys_latexe_options_class:n}
-% \begin{syntax}
-% "\keys_latexe_options_class:n" \Arg{module}
-% \end{syntax}
-% Processes global options when the current file is itself a class,
-% checking the options against keys defined for <module>.
-%\end{function}
-%
-%\begin{function}{\keys_latexe_options_package:n}
-% \begin{syntax}
-% "\keys_latexe_options_package:n" \Arg{module}
-% \end{syntax}
-% Processes global options when the current file is a \LaTeXe\ package,
-% checking the options against keys defined for <module>.
-%\end{function}
-%
-%\begin{function}{\keys_latexe_options_local:}
-% \begin{syntax}
-% "\keys_latexe_options_local:"
-% \end{syntax}
-% Finds local (package) options and adds them to the list to be
-% parsed by \cs{keys_set:nn}.
-%\end{function}
-%
-%\begin{function}{
-% \keys_latexe_remove_equals:n / (EXP) |
-% \keys_latexe_remove_equals:w / (EXP)
-%}
-% \begin{syntax}
-% "\keys_latexe_remove_equals:n" \Arg{option}
-% "\keys_latexe_remove_equals:w" <key> = <value> "\q_stop"
-% \end{syntax}
-% Returns only the key part of a key--value option by removing
-% everything after the first equals sign. It is assumed that, as this
-% will apply in the preamble, equals signs have category code 12.
+% \LaTeXe\ kernel function \cs{ProcessOptions}).
%\end{function}
%
%\end{documentation}
@@ -183,17 +121,17 @@
%
%\subsection{Implementation}
%
-% The usual lead-off, using \pkg{xparse} at the interface level.
+% The usual lead-off.
% \begin{macrocode}
%<*package>
\ProvidesExplPackage
{\filename}{\filedate}{\fileversion}{\filedescription}
-\RequirePackage{xparse}
+\RequirePackage { xparse }
% \end{macrocode}
%
%\begin{macro}{\keys_latexe_options_clist}
-% The module collects all applicable global and local options into a
-% single list before processing them.
+% A single list is used for all options, into which they are collected
+% before processing.
% \begin{macrocode}
\clist_new:N \keys_latexe_options_clist
% \end{macrocode}
@@ -206,34 +144,33 @@
\bool_new:N \_l_keys_process_class_bool
% \end{macrocode}
%\end{macro}
-%
+%
%\begin{macro}{\keys_latexe_options:n}
% The main function calls functions to collect up the global and local
-% options into \cs{keys_latexe_options_clist} before calling the main
-% \pkg{l3keys} module to actually do the processing. So that a suitable
+% options into \cs{keys_latexe_options_clist} before calling the
+% underlying functions to actually do the processing. So that a suitable
% message is produced if the option is unknown, the special
% \texttt{unknown} key is set if it does not already exist for the
% current module.
% \begin{macrocode}
-\cs_new:Npn \keys_latexe_options:n #1 {
+\cs_new_protected:Npn \keys_latexe_options:n #1 {
\clist_clear:N \keys_latexe_options_clist
\keys_latexe_options_global:n {#1}
\keys_latexe_options_local:
- \keys_if_exist:nnF {#1} { unknown } {
- \keys_define:nn {#1} {
- unknown .code:n = {
- \msg_error:nnxx { Option~Processing } { unknown-option }
- { \l_keys_key_tl } { \@currname }
- }
+ \cs_if_exist:cTF { \c_keys_root_tl {#1} / unknown .cmd:n }
+ {
+ \keys_define:nn {#1}
+ {
+ unknown .code:n =
+ {
+ \msg_kernel_error:nnxx { keyvalue } { option-unknown }
+ { \l_keys_key_tl } { \@currname }
+ }
+ }
}
- }
\keys_set:nV {#1} \keys_latexe_options_clist
\AtEndOfPackage { \cs_set_eq:NN \@unprocessedoptions \scan_stop: }
}
-\msg_new:nnn { Option~Processing } { unknown-option } {%
- Unknown~option~`#1'\\%
- for~module~#2.%
-}
% \end{macrocode}
%\end{macro}
%
@@ -243,15 +180,16 @@
% file type. The initial test is needed as \LaTeXe\ allows variables to
% be equal to \cs{scan_stop:}, which is forbidden in \LaTeX3 code.
% \begin{macrocode}
-\cs_new:Npn \keys_latexe_options_global:n #1 {
- \cs_if_eq:NNF \@classoptionslist \scan_stop: {
- \cs_if_eq:NNTF \@currext \@clsextension {
- \keys_latexe_options_class:n {#1}
- }{
- \bool_if:NT \_l_keys_process_class_bool
- { \keys_latexe_options_package:n {#1} }
+\cs_new_protected:Npn \keys_latexe_options_global:n #1 {
+ \cs_if_eq:NNF \@classoptionslist \scan_stop:
+ {
+ \cs_if_eq:NNTF \@currext \@clsextension
+ { \keys_latexe_options_class:n {#1} }
+ {
+ \bool_if:NT \_l_keys_process_class_bool
+ { \keys_latexe_options_package:n {#1} }
+ }
}
- }
}
% \end{macrocode}
%\end{macro}
@@ -262,14 +200,17 @@
% the combined list for processing. On the other hand, unused options
% are stored up in \cs{@unusedoptionlist}.
% \begin{macrocode}
-\cs_new:Npn \keys_latexe_options_class:n #1 {
- \clist_map_inline:Nn \@classoptionslist {
- \keys_if_exist:nnTF {#1} { \keys_latexe_remove_equals:n {##1} } {
- \clist_put_right:Nn \keys_latexe_options_clist {##1}
- }{
- \clist_put_right:Nn \@unusedoptionlist {##1}
+\cs_new_protected:Npn \keys_latexe_options_class:n #1 {
+ \clist_map_inline:Nn \@classoptionslist
+ {
+ \cs_if_exist:cTF
+ {
+ \c_keys_root_tl #1 /
+ \keys_latexe_remove_equals:n {##1} .cmd:n
+ }
+ { \clist_put_right:Nn \keys_latexe_options_clist {##1} }
+ { \clist_put_right:Nn \@unusedoptionlist {##1} }
}
- }
}
% \end{macrocode}
%\end{macro}
@@ -280,13 +221,19 @@
% there is nothing to do if the option is not applicable. Each valid
% option also needs to be removed from \cs{@unusedoptionlist}.
% \begin{macrocode}
-\cs_new:Npn \keys_latexe_options_package:n #1 {
- \clist_map_inline:Nn \@classoptionslist {
- \keys_if_exist:nnT {#1} { \keys_latexe_remove_equals:n {##1} } {
- \clist_put_right:Nn \keys_latexe_options_clist {##1}
- \clist_remove_element:Nn \@unusedoptionlist {##1}
+\cs_new_protected:Npn \keys_latexe_options_package:n #1 {
+ \clist_map_inline:Nn \@classoptionslist
+ {
+ \cs_if_exist:cTF
+ {
+ \c_keys_root_tl #1 /
+ \keys_latexe_remove_equals:n {##1} .cmd:n
+ }
+ {
+ \clist_put_right:Nn \keys_latexe_options_clist {##1}
+ \clist_remove_element:Nn \@unusedoptionlist {##1}
+ }
}
- }
}
% \end{macrocode}
%\end{macro}
@@ -296,13 +243,15 @@
% \LaTeXe\ stores options for each file in a macro which may or may not
% exist, hence the need to use \cs{cs_if_exist:c}.
% \begin{macrocode}
-\cs_new_nopar:Npn \keys_latexe_options_local: {
- \cs_if_eq:NNF \@currext \@clsextension {
- \cs_if_exist:cT { opt@ \@currname . \@currext } {
- \exp_args:NNc \clist_put_right:NV \keys_latexe_options_clist
- { opt@ \@currname . \@currext }
+\cs_new_protected_nopar:Npn \keys_latexe_options_local: {
+ \cs_if_eq:NNF \@currext \@clsextension
+ {
+ \cs_if_exist:cT { opt@ \@currname . \@currext }
+ {
+ \exp_args:NNc \clist_put_right:NV \keys_latexe_options_clist
+ { opt@ \@currname . \@currext }
+ }
}
- }
}
% \end{macrocode}
%\end{macro}
@@ -327,11 +276,11 @@
% contrast to other similar packages, the module name is always required
% here.
% \begin{macrocode}
-\NewDocumentCommand \ProcessKeysOptions { m } {
+\cs_new_protected:Npn \ProcessKeysOptions #1 {
\bool_set_true:N \_l_keys_process_class_bool
\keys_latexe_options:n {#1}
}
-\NewDocumentCommand \ProcessKeysPackageOptions { m } {
+\cs_new_protected:Npn \ProcessKeysPackageOptions #1 {
\bool_set_false:N \_l_keys_process_class_bool
\keys_latexe_options:n {#1}
}
@@ -341,6 +290,16 @@
%\end{macro}
%\end{macro}
%
+% One message to give.
+% \begin{macrocode}
+\msg_kernel_new:nnnn { keyvalue } { option-unknown }
+ { Unknown~option~'#1'~for~package~#2. }
+ {
+ LaTeX~has~been~asked~to~set~an~option~called~'#1'\\
+ but~the~#2~package~has~not~created~an~option~with~this~name.
+ }
+% \end{macrocode}
+%
% \begin{macrocode}
%</package>
% \end{macrocode}