kvoptions

Provides a standardized framework for implementing key-value style options in LaTeX package development.

Overview

Enables package developers to create more flexible and intuitive configuration options for their LaTeX packages using a key-value format instead of traditional boolean flags. This approach offers several advantages:

Allows for more descriptive and self-documenting package options
Supports complex option values beyond simple true/false settings
Makes package configuration more maintainable and easier to understand
Facilitates consistent option handling across different packages

Particularly valuable for package authors developing sophisticated LaTeX extensions that require multiple configuration parameters or complex customization options.

Getting Started

To use kvoptions, include it in your document preamble:

\documentclass{article}
\usepackage{kvoptions}

This package is primarily intended for package authors. The main functionality is:

% In your package file (mypackage.sty)
\RequirePackage{kvoptions}
\SetupKeyvalOptions{family=mypackage,prefix=mypackage@}
\DeclareStringOption[default]{option1}
\ProcessKeyvalOptions*

Examples

Using kvoptions to define and process key-value options for a custom package.

\documentclass{article}
\usepackage{filecontents}

% First create a sample package that uses kvoptions
\begin{filecontents*}{mypackage.sty}
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{mypackage}[2023/01/01 v1.0 Sample package with key-value options]

% Load the kvoptions package
\RequirePackage{kvoptions}

% Setup the package prefix for options
\SetupKeyvalOptions{
  family=mypackage,
  prefix=mypackage@
}

% Define default values
\DeclareStringOption[blue]{color}  % Default color is blue
\DeclareBoolOption[false]{boxed}  % Default is not boxed
\DeclareComplementaryOption{unboxed}{boxed} % Opposite of boxed
\DeclareVoidOption{demo}{\setkeys{mypackage}{color=red,boxed=true}} % Shortcut option
\ProcessKeyvalOptions*

% Define commands that use the options
\newcommand{\mybox}[1]{%
  \ifmypackage@boxed
    \fbox{\textcolor{\mypackage@color}{#1}}
  \else
    \textcolor{\mypackage@color}{#1}
  \fi
}

\RequirePackage{xcolor} % For color support
\end{filecontents*}

% Now use the package with various options
\usepackage[color=green, boxed]{mypackage}

\begin{document}

\section{Demonstration of kvoptions in a custom package}

This text uses our custom package with key-value options:\par\medskip

\mybox{This text is formatted according to the package options.}

\end{document}

A simpler example showing how to use kvoptions in a document class.

\documentclass{article}
\usepackage{filecontents}

% Create a simple document class that uses kvoptions
\begin{filecontents*}{mysimpleclass.cls}
\NeedsTeXFormat{LaTeX2e}
\ProvidesClass{mysimpleclass}[2023/01/01 v1.0 Simple class with key-value options]

% Load the kvoptions package
\RequirePackage{kvoptions}

% Setup the class prefix for options
\SetupKeyvalOptions{
  family=mysimpleclass,
  prefix=mysimpleclass@
}

% Define options
\DeclareStringOption[11pt]{fontsize} % Default font size
\DeclareStringOption[1.5]{linespacing} % Default line spacing
\DeclareVoidOption{draft}{\PassOptionsToClass{draft}{article}} % Pass through option

% Process options
\ProcessKeyvalOptions*

% Load the base class with appropriate options
\LoadClass[\mysimpleclass@fontsize]{article}

% Apply settings based on options
\RequirePackage{setspace}
\setstretch{\mysimpleclass@linespacing}
\end{filecontents*}

% Now create a document using our custom class
\begin{filecontents*}{sample.tex}
\documentclass[fontsize=12pt,linespacing=2]{mysimpleclass}
\begin{document}
This document uses a custom class with key-value options.

The font size is set to 12pt and the line spacing is double-spaced.
\end{document}
\end{filecontents*}

% Main document just to explain
\begin{document}
\section{Using kvoptions in a document class}

The file \texttt{mysimpleclass.cls} demonstrates how to use the \texttt{kvoptions} package to create a document class with key-value options. The file \texttt{sample.tex} shows how to use this class.

To compile the sample document, you would run:

\texttt{pdflatex sample.tex}
\end{document}