diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/l3packages/l3keys2e/l3keys2e.dtx')
| -rw-r--r-- | Master/texmf-dist/source/latex/l3packages/l3keys2e/l3keys2e.dtx | 334 |
1 files changed, 334 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/latex/l3packages/l3keys2e/l3keys2e.dtx b/Master/texmf-dist/source/latex/l3packages/l3keys2e/l3keys2e.dtx new file mode 100644 index 00000000000..4d1930a05e7 --- /dev/null +++ b/Master/texmf-dist/source/latex/l3packages/l3keys2e/l3keys2e.dtx @@ -0,0 +1,334 @@ +% \iffalse meta-comment +% +%% File: l3keys2e.dtx (C) Copyright 2009,2011 The LaTeX3 Project +%% +%% It may be distributed and/or modified under the conditions of the +%% LaTeX Project Public License (LPPL), either version 1.3c of this +%% license or (at your option) any later version. The latest version +%% of this license is in the file +%% +%% http://www.latex-project.org/lppl.txt +%% +%% This file is part of the "l3packages bundle" (The Work in LPPL) +%% and all files in that bundle must be distributed together. +%% +%% The released version of this bundle is available from CTAN. +%% +%% ----------------------------------------------------------------------- +%% +%% The development version of the bundle can be found at +%% +%% http://www.latex-project.org/svnroot/experimental/trunk/ +%% +%% for those people who are interested. +%% +%%%%%%%%%%% +%% NOTE: %% +%%%%%%%%%%% +%% +%% Snapshots taken from the repository represent work in progress and may +%% not work or may contain conflicting material! We therefore ask +%% people _not_ to put them into distributions, archives, etc. without +%% prior consultation with the LaTeX Project Team. +%% +%% ----------------------------------------------------------------------- +%% +% +%<*driver|package> +\RequirePackage{xparse} +\GetIdInfo$Id: l3keys2e.dtx 2492 2011-07-02 13:40:38Z joseph $ + {LaTeX2e option processing using LaTeX3 keys} +%</driver|package> +%<*driver> +\documentclass[full]{l3doc} +\usepackage{amstext} +\begin{document} + \DocInput{\jobname.dtx} +\end{document} +%</driver> +% \fi +% +% \title{^^A +% The \textsf{l3keys2e} package\\ +% \LaTeXe{} option processing using \LaTeX3 keys^^A +% \thanks{This file describes v\ExplFileVersion, +% last revised \ExplFileDate.}^^A +% } +% +% \author{^^A +% The \LaTeX3 Project\thanks +% {^^A +% E-mail: +% \href{mailto:latex-team@latex-project.org} +% {latex-team@latex-project.org}^^A +% }^^A +% } +% +% \date{Released \ExplFileDate} +% +% \maketitle +% +% \begin{documentation} +% +% The key--value method for optional arguments is very popular, as it +% allows the class or package author to define a large number of +% options with a simple interface. The \pkg{expl3} bundle of \LaTeX3 +% base code includes the module \pkg{l3keys} for defining keys, but +% to use these when loading \LaTeXe\ packages and classes requires +% extra support. That support is provided by this small package, which +% is intended to enable \LaTeXe\ packages to benefit from the power of +% the \LaTeX3 key--value system. +% +% \subsection{Creating and using keyval options} +% +% 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, 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 } +% \end{verbatim} +% On its own, this will not make the key an option for the package or +% class containing the definition. The second stage is therefore to +% process the current options, searching for applicable keys. +% +% \begin{function}{\ProcessKeysOptions} +% \begin{syntax} +% \cs{ProcessKeysOptions} \Arg{module} +% \end{syntax} +% The \cs{ProcessKeysOptions} function is used to check the current +% 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} +% \end{function} +% +% \begin{function}{\ProcessKeysPackageOptions} +% \begin{syntax} +% \cs{ProcessKeysPackageOptions} \Arg{module} +% \end{syntax} +% This function works in a similar manner to \cs{ProcessKeysOptions}. +% 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 +% \LaTeXe{} kernel function \cs{ProcessOptions}). +% \end{function} +% +%\end{documentation} +% +%\begin{implementation} +% +%\subsection{\pkg{l3keys2e} Implementation} +% +% \begin{macrocode} +%<*package> +% \end{macrocode} +% +% \begin{macrocode} +\ProvidesExplPackage + {\ExplFileName}{\ExplFileDate}{\ExplFileVersion}{\ExplFileDescription} +% \end{macrocode} +% +% A check to make sure that \pkg{expl3} is not too old +% \begin{macrocode} +\@ifpackagelater { l3token } { 2011/07/02 } + { } + { + \PackageError { l3keys2e } { Support~package~l3kernel~too~old. } + { + Please~install~an~up~to~date~version~of~l3kernel~ + using~your~TeX~package~manager~or~from~CTAN.\\ \\ + Loading~l3keys2e~will~abort! + } + \tex_endinput:D + } +% \end{macrocode} +% +% \begin{macro}{\keys_latexe_options_clist} +% 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} +% \end{macro} +% +% \begin{macro}{\_l_keys_process_class_bool} +% A flag to indicate that class options should be processed for +% packages. +% \begin{macrocode} +\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 +% 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_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 { keyvalue } { option-unknown } + { \l_keys_key_tl } { \@currname } + } + } + } + \keys_set:nV {#1} \keys_latexe_options_clist + \AtEndOfPackage { \cs_set_eq:NN \@unprocessedoptions \scan_stop: } + } +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\keys_latexe_options_global:n} +% Global (class) options are handled differently for \LaTeXe{} packages +% and classes. Hence this function is essentially a check on the current +% 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_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} +% +% \begin{macro}{\keys_latexe_options_class:n} +% For classes, each option (stripped of any content after |=|) +% is checked for existence as a key. If found, the option is added to +% the combined list for processing. On the other hand, unused options +% are stored up in \cs{@unusedoptionlist}. Before any of that, though, +% there is a simple check to see if there is an |unknown| key. If there +% is, then \emph{everything} will match and the mapping can be skipped. +% \begin{macrocode} +\cs_new_protected:Npn \keys_latexe_options_class:n #1 + { + \keys_if_exist:nnTF {#1} { unknown } + { \clist_put_right:No \keys_latexe_options_clist \@classoptionslist } + { + \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} } + } + } + } +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\keys_latexe_options_package:n} +% For global options when processing a package, the tasks are slightly +% different from those for a class. The check is the same, but here +% 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_protected: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} + } + } + } +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\keys_latexe_options_local:} +% If local options are found, the are added to the processing list. +% \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_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} +% +% \begin{macro}{\keys_latexe_remove_equals:n} +% \begin{macro}{\keys_latexe_remove_equals:w} +% As the name suggests, this is a simple function to remove an equals +% sign from the input. This is all wrapped up in an \texttt{n} function +% so that there will always be a sign available. +% \begin{macrocode} +\cs_new:Npn \keys_latexe_remove_equals:n #1 + { \keys_latexe_remove_equals:w #1 = \q_stop } +\cs_new:Npn \keys_latexe_remove_equals:w #1 = #2 \q_stop {#1} +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\ProcessKeysOptions} +% \begin{macro}{\ProcessKeysOptions} +% The user macro are simply wrappers around the internal process. In +% contrast to other similar packages, the module name is always required +% here. +% \begin{macrocode} +\cs_new_protected_nopar:Npn \ProcessKeysOptions #1 + { + \bool_set_true:N \_l_keys_process_class_bool + \keys_latexe_options:n {#1} + } +\cs_new_protected_nopar:Npn \ProcessKeysPackageOptions #1 + { + \bool_set_false:N \_l_keys_process_class_bool + \keys_latexe_options:n {#1} + } +\@onlypreamble \ProcessKeysOptions +\@onlypreamble \ProcessKeysPackageOptions +% \end{macrocode} +%\end{macro} +%\end{macro} +% +% One message to give. +% \begin{macrocode} +\msg_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} +% +% \end{implementation} +% +% \PrintIndex |