diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/xpackages/xtras/l3keys2e.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex/xpackages/xtras/l3keys2e.dtx | 205 |
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} |