How can I define a key-value command like \hypersetup?

Question

I am quite familiar with switch (\if...\else...\fi) now and read many questions on key-value topic, but I cannot find an example to create the options listing command like \hypersetup, to make

\documentclass[key1=...,key2=...,key3=...]{myclass}

equivalent to

\documentclass{myclass}
\myclssetup{%
    key1 = ...,
    key2 = ...,
    key3 = ...,
    .............
}

None of these keys are boolean, and all these values helps me to do switch into different layout schemes. For instance, key1 is to set one type of cover page and key2 is to set one type of section formats. I do not need to draw something or to set some geometry properties (I don't need values of numerical parameters). I also want some default options pre-set, if the user didn't specify their options.

If I use the kvoptions package, all I know is that I probably need \newif and \DeclareVoidOption (kvoptions package) to create options (values), \define@key (keyval package) and \kvsetkeys command (keyval package) to link values and keys. However, I have been struggling to find similar and simple examples to achieve the function I need.

I think it's important to stress that I am writing a class (not package), and it will be based on another class (like book).

Answer 1

Here's a xkeyval version, with automatic definition of keys and it's keyval macro and a corresponding \if... whether the option is used.

The precise implementation depends on the internal options to be specified what they should do if specified. I assumed, that the class options are to be stored to a macro, say \classoption@myclass@#2 where #2 has the relevant meaning, say paper or width etc.

\documentclass{article}


\usepackage{xkeyval}

\makeatletter

\newcommand{\definemykey}[2]{%
  \expandafter\newif\csname ifmyclassname@#1\endcsname
  \define@key{myclass}{#1}{%
    \expandafter\gdef\csname classoption@myclass@#2\endcsname{##1}
    \global\expandafter\csname myclassname@#1true\endcsname
  }
}

\definemykey{keyA}{KeyA}
\definemykey{keyB}{KeyB}
\definemykey{keyC}{KeyC}


\newcommand{\myclasssetup}[1]{%
  \setkeys{myclass}{#1}%
}

\makeatother


\myclasssetup{keyB={upvote good answers!}, keyC={provide a MWE}}

\begin{document}

\makeatletter
\ifmyclassname@keyA
Yes, it was specified
\else
No, it is missing
\fi


\ifmyclassname@keyB
Yes, it was specified and has the value \textbf{\classoption@myclass@KeyB}
\else
No, it is missing
\fi

\makeatother


\end{document}

Answer 2

Examples for kvoptions among my packages: accsupp, attachfile2, bookmark, enparen, epstopdf-base, grffile, pagegrid, pmboxdraw, rerunfilecheck, resizegather, selinput, zref-xr, ...

A grep -r kvoptions TDS:tex/latex will reveal much more packages.

Example rerunfilecheck:

% Package start
[...]
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{rerunfilecheck}%
  [2011/04/15 v1.7 Rerun checks for auxiliary files (HO)]

% Option setup
\RequirePackage{kvoptions}[2010/02/22]
\SetupKeyvalOptions{%
  family=rerunfilecheck,%
  prefix=ReFiCh@%
}

% The setup command (a convenience wrapper for `\setkeys`:
\newcommand*{\RerunFileCheckSetup}{%
  \setkeys{rerunfilecheck}%
}

% The options
\DeclareBoolOption{mainaux}
\DeclareBoolOption{partaux}
\DeclareBoolOption{starttoc}
\DeclareBoolOption{index}
\DeclareBoolOption{glossary}
\define@key{rerunfilecheck}{aux}[true]{%
  \RerunFileCheckSetup{%
    mainaux={#1},%
    partaux={#1},%
    starttoc={#1},%
    index={#1},%
    glossary={#1}%
  }%
}

% Option processing: first configuration file, then package options
\InputIfFileExists{rerunfilecheck.cfg}{}{}
\ProcessLocalKeyvalOptions*

% Helper macro to disable options
\def\ReFiCh@DisableOption{%
  \DisableKeyvalOption[%
    action=warning,%
    package=rerunfilecheck%
  ]{rerunfilecheck}%
}

[...]

% The options are disabled after they have been used the last time:
\ReFiCh@DisableOption{mainaux}
\ReFiCh@DisableOption{partaux}
\ReFiCh@DisableOption{starttoc}
\ReFiCh@DisableOption{index}
\ReFiCh@DisableOption{glossary}
\ReFiCh@DisableOption{aux}

[...]

Answer 3

Using expkv-opt you can process package/class options with keys defined for expkv (possibly via the helper package expkv-def).

An example could be the following class-file stored as myclass.cls:

\ProvidesClass{myclass}

\RequirePackage{expkv-opt,expkv-def}

% define the keys (see expkv-def's documentation for an overview on key types)
\ekvdefinekeys{myclass}
  {
     store key1 = \myclassA
    ,store key2 = \myclassB
    ,store key3 = \myclassC
  }
% define the setup macro (will be defined protected here)
\protected\ekvsetdef\myclssetup{myclass}

% process the options given to \documentclass
\ekvoProcessGlobalOptions{myclass}

% lets base on article
\LoadClass{article}

\endinput

If used together with this document:

\documentclass[key2=def]{myclass}
\myclssetup{key1=abc,key3=ghi}

\begin{document}
\myclassA\par
\myclassB\par
\myclassC\par
\end{document}

You'll get

Please note that in any case (and with any package) the usage of \documentclass[<options>]{<class>} and \documentclass{<class>}\clssetup{<options>} is not the same. Options given to \documentclass are (normally) picked up by every package you use (and classes loaded with \LoadClass) whereas options given to \clssetup don't propagate that way. Also the options given to \documentclass will be expanded using \edef once (expkv-opt doesn't use the expanded option list, but the raw one provided by recent versions of LaTeX, still the keys will be expanded inside \edef for backwards compatibility), whereas \clssetup receives its options as-is.