% Options for packages loaded elsewhere
\PassOptionsToPackage{unicode}{hyperref}
\PassOptionsToPackage{hyphens}{url}
%
\documentclass[
]{luaoptionsmanual}
\usepackage{amsmath,amssymb}
\usepackage[]{libertine}
\usepackage{iftex}
\ifPDFTeX
  \usepackage[T1]{fontenc}
  \usepackage[utf8]{inputenc}
  \usepackage{textcomp} % provide euro and other symbols
\else % if luatex or xetex
  \usepackage{unicode-math}
  \defaultfontfeatures{Scale=MatchLowercase}
  \defaultfontfeatures[\rmfamily]{Ligatures=TeX,Scale=1}
\fi
% Use upquote if available, for straight quotes in verbatim environments
\IfFileExists{upquote.sty}{\usepackage{upquote}}{}
\IfFileExists{microtype.sty}{% use microtype if available
  \usepackage[]{microtype}
  \UseMicrotypeSet[protrusion]{basicmath} % disable protrusion for tt fonts
}{}
\makeatletter
\@ifundefined{KOMAClassName}{% if non-KOMA class
  \IfFileExists{parskip.sty}{%
    \usepackage{parskip}
  }{% else
    \setlength{\parindent}{0pt}
    \setlength{\parskip}{6pt plus 2pt minus 1pt}}
}{% if KOMA class
  \KOMAoptions{parskip=half}}
\makeatother
\usepackage{xcolor}
\IfFileExists{xurl.sty}{\usepackage{xurl}}{} % add URL line breaks if available
\IfFileExists{bookmark.sty}{\usepackage{bookmark}}{\usepackage{hyperref}}
\hypersetup{
  pdfauthor={Fr.~Jacques Peron; Urs Liska},
  hidelinks,
  pdfcreator={LaTeX via pandoc}}
\urlstyle{same} % disable monospaced font for URLs
\usepackage{color}
\usepackage{fancyvrb}
\newcommand{\VerbBar}{|}
\newcommand{\VERB}{\Verb[commandchars=\\\{\}]}
\DefineVerbatimEnvironment{Highlighting}{Verbatim}{commandchars=\\\{\}}
% Add ',fontsize=\small' for more characters per line
\newenvironment{Shaded}{}{}
\newcommand{\AlertTok}[1]{\textcolor[rgb]{1.00,0.00,0.00}{\textbf{#1}}}
\newcommand{\AnnotationTok}[1]{\textcolor[rgb]{0.38,0.63,0.69}{\textbf{\textit{#1}}}}
\newcommand{\AttributeTok}[1]{\textcolor[rgb]{0.49,0.56,0.16}{#1}}
\newcommand{\BaseNTok}[1]{\textcolor[rgb]{0.25,0.63,0.44}{#1}}
\newcommand{\BuiltInTok}[1]{\textcolor[rgb]{0.00,0.50,0.00}{#1}}
\newcommand{\CharTok}[1]{\textcolor[rgb]{0.25,0.44,0.63}{#1}}
\newcommand{\CommentTok}[1]{\textcolor[rgb]{0.38,0.63,0.69}{\textit{#1}}}
\newcommand{\CommentVarTok}[1]{\textcolor[rgb]{0.38,0.63,0.69}{\textbf{\textit{#1}}}}
\newcommand{\ConstantTok}[1]{\textcolor[rgb]{0.53,0.00,0.00}{#1}}
\newcommand{\ControlFlowTok}[1]{\textcolor[rgb]{0.00,0.44,0.13}{\textbf{#1}}}
\newcommand{\DataTypeTok}[1]{\textcolor[rgb]{0.56,0.13,0.00}{#1}}
\newcommand{\DecValTok}[1]{\textcolor[rgb]{0.25,0.63,0.44}{#1}}
\newcommand{\DocumentationTok}[1]{\textcolor[rgb]{0.73,0.13,0.13}{\textit{#1}}}
\newcommand{\ErrorTok}[1]{\textcolor[rgb]{1.00,0.00,0.00}{\textbf{#1}}}
\newcommand{\ExtensionTok}[1]{#1}
\newcommand{\FloatTok}[1]{\textcolor[rgb]{0.25,0.63,0.44}{#1}}
\newcommand{\FunctionTok}[1]{\textcolor[rgb]{0.02,0.16,0.49}{#1}}
\newcommand{\ImportTok}[1]{\textcolor[rgb]{0.00,0.50,0.00}{\textbf{#1}}}
\newcommand{\InformationTok}[1]{\textcolor[rgb]{0.38,0.63,0.69}{\textbf{\textit{#1}}}}
\newcommand{\KeywordTok}[1]{\textcolor[rgb]{0.00,0.44,0.13}{\textbf{#1}}}
\newcommand{\NormalTok}[1]{#1}
\newcommand{\OperatorTok}[1]{\textcolor[rgb]{0.40,0.40,0.40}{#1}}
\newcommand{\OtherTok}[1]{\textcolor[rgb]{0.00,0.44,0.13}{#1}}
\newcommand{\PreprocessorTok}[1]{\textcolor[rgb]{0.74,0.48,0.00}{#1}}
\newcommand{\RegionMarkerTok}[1]{#1}
\newcommand{\SpecialCharTok}[1]{\textcolor[rgb]{0.25,0.44,0.63}{#1}}
\newcommand{\SpecialStringTok}[1]{\textcolor[rgb]{0.73,0.40,0.53}{#1}}
\newcommand{\StringTok}[1]{\textcolor[rgb]{0.25,0.44,0.63}{#1}}
\newcommand{\VariableTok}[1]{\textcolor[rgb]{0.10,0.09,0.49}{#1}}
\newcommand{\VerbatimStringTok}[1]{\textcolor[rgb]{0.25,0.44,0.63}{#1}}
\newcommand{\WarningTok}[1]{\textcolor[rgb]{0.38,0.63,0.69}{\textbf{\textit{#1}}}}
\setlength{\emergencystretch}{3em} % prevent overfull lines
\providecommand{\tightlist}{%
  \setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}}
\setcounter{secnumdepth}{-\maxdimen} % remove section numbering
\ifLuaTeX
  \usepackage{selnolig}  % disable illegal ligatures
\fi

\title{\texttt{luaoptions}}
\usepackage{etoolbox}
\makeatletter
\providecommand{\subtitle}[1]{% add subtitle to \maketitle
  \apptocmd{\@title}{\par {\large #1 \par}}{}{}
}
\makeatother
\subtitle{0.8}
\author{Fr.~Jacques Peron \and Urs Liska}
\date{\luaoptionsmanualdate}

\begin{document}
\maketitle

\thispagestyle{empty}
\enlargethispage*{3\baselineskip}

\hypertarget{introduction}{%
\section{Introduction}\label{introduction}}

\texttt{luaoptions} is a LuaLaTeX package providing extensive support
for handling \emph{options}, on package level and locally. It is hosted
at \url{https://github.com/lualatex-tools/luaoptions} and maintained by
Jacques Peron
(\href{mailto:cataclop@hotmail.com}{\nolinkurl{cataclop@hotmail.com}})
and Urs Liska
(\href{mailto:git@ursliska.de}{\nolinkurl{git@ursliska.de}}). The
package was originally developed as part of the \texttt{lyluatex}
package\footnote{\url{https://github.com/jperon/lyluatex}} but has now
been extracted as a standalone package because we realized it can be a
useful tool for arbitrary LuaLaTeX packages having to deal with
\emph{options} -- both \emph{package options} and \emph{optional macro
arguments}. A \texttt{lyluatex} installation should not be a dependency
for packages that want to make use of option handling but are not
interested in music engraving \dots

\texttt{luaoptions} allows the declaration of sets of options, along
with defaults, expected/allowed values and limited type checking. These
options can be enforced as package options, changed at any point during
a document, or overwritten locally by optional macro arguments. It is
also possible to instantiate an \texttt{Options} object as an
independent Lua object, without linking it to a package.
\texttt{luaoptions} can be used to enforce and prepopulate options, or
it can be used to simply handle the parsing of optional
\texttt{key=value} arguments into proper Lua tables.

The main use of \texttt{luaoptions} is to define package options as
follows:

\begin{Shaded}
\begin{Highlighting}[]
\FunctionTok{\textbackslash{}RequirePackage}\NormalTok{\{luaoptions\}}
\FunctionTok{\textbackslash{}directlua}\NormalTok{\{}
\NormalTok{  local \_opt = lua\_options}
\NormalTok{  lua\_options.register(\textquotesingle{}myoptions\textquotesingle{}, \{}
\NormalTok{    [\textquotesingle{}option\textquotesingle{}] = \{\textquotesingle{}default value\textquotesingle{}, \textquotesingle{}other value\textquotesingle{}, \textquotesingle{}\textquotesingle{}\},}
\NormalTok{    [\textquotesingle{}otheroption\textquotesingle{}] = \{\textquotesingle{}default\textquotesingle{}, validator\},}
\NormalTok{    [\textquotesingle{}yetanotheroptions\textquotesingle{}] = \{\},}
\NormalTok{  \})}
\NormalTok{\}}
\end{Highlighting}
\end{Shaded}

\texttt{validator} is a function that returns \texttt{true} when the
defined option is valid, \texttt{false} otherwise. \texttt{luaoptions}
itself contains predefined such functions.

After that, defined options are available in a lua table, which can be
used by the mean of the \texttt{client} command:

\begin{Shaded}
\begin{Highlighting}[]
\KeywordTok{local}\NormalTok{ myopts }\OperatorTok{=}\NormalTok{ lua\_options}\OperatorTok{.}\NormalTok{client}\OperatorTok{(}\StringTok{\textquotesingle{}myoptions\textquotesingle{}}\OperatorTok{)}
\NormalTok{tex}\OperatorTok{.}\NormalTok{sprint}\OperatorTok{(}\NormalTok{myopts}\OperatorTok{.}\NormalTok{option}\OperatorTok{)}
\end{Highlighting}
\end{Shaded}

This initial release does \emph{not} include documentation beyond this
short introduction; please refer to the docstrings in
\texttt{luaoptions.lua} and \texttt{luaoptions-lib.lua} for more
information.

For the time being it is possible to look into how some of our own
packages make use of \texttt{luaoptions}:

\begin{itemize}
\tightlist
\item
  \url{https://github.com/jperon/lyluatex/blob/master/lyluatextools.sty}
\item
  \url{https://github.com/jperon/lyluatex/blob/master/lyluatex.lua}
\item
  \url{https://github.com/lualatex-tools/luaformatters/blob/master/luaformatters.sty}
\item
  \url{https://github.com/lualatex-tools/luaformatters/blob/master/luaformatters.lua}
\item
  \url{https://github.com/lualatex-tools/luaformatters/blob/master/submodules/luaformatters-formatter.lua}
\end{itemize}

\end{document}