1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
|
% 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}
|
