| 1 |
% Options for packages loaded elsewhere |
| 2 |
\PassOptionsToPackage{unicode}{hyperref} |
| 3 |
\PassOptionsToPackage{hyphens}{url} |
| 4 |
% |
| 5 |
\documentclass[ |
| 6 |
]{luaoptionsmanual} |
| 7 |
\usepackage{amsmath,amssymb} |
| 8 |
\usepackage{iftex} |
| 9 |
\ifPDFTeX |
| 10 |
\usepackage[T1]{fontenc} |
| 11 |
\usepackage[utf8]{inputenc} |
| 12 |
\usepackage{textcomp} % provide euro and other symbols |
| 13 |
\else % if luatex or xetex |
| 14 |
\usepackage{unicode-math} % this also loads fontspec |
| 15 |
\defaultfontfeatures{Scale=MatchLowercase} |
| 16 |
\defaultfontfeatures[\rmfamily]{Ligatures=TeX,Scale=1} |
| 17 |
\fi |
| 18 |
\usepackage[]{libertine} |
| 19 |
\ifPDFTeX\else |
| 20 |
% xetex/luatex font selection |
| 21 |
\fi |
| 22 |
% Use upquote if available, for straight quotes in verbatim environments |
| 23 |
\IfFileExists{upquote.sty}{\usepackage{upquote}}{} |
| 24 |
\IfFileExists{microtype.sty}{% use microtype if available |
| 25 |
\usepackage[]{microtype} |
| 26 |
\UseMicrotypeSet[protrusion]{basicmath} % disable protrusion for tt fonts |
| 27 |
}{} |
| 28 |
\makeatletter |
| 29 |
\@ifundefined{KOMAClassName}{% if non-KOMA class |
| 30 |
\IfFileExists{parskip.sty}{% |
| 31 |
\usepackage{parskip} |
| 32 |
}{% else |
| 33 |
\setlength{\parindent}{0pt} |
| 34 |
\setlength{\parskip}{6pt plus 2pt minus 1pt}} |
| 35 |
}{% if KOMA class |
| 36 |
\KOMAoptions{parskip=half}} |
| 37 |
\makeatother |
| 38 |
\usepackage{xcolor} |
| 39 |
\usepackage{color} |
| 40 |
\usepackage{fancyvrb} |
| 41 |
\newcommand{\VerbBar}{|} |
| 42 |
\newcommand{\VERB}{\Verb[commandchars=\\\{\}]} |
| 43 |
\DefineVerbatimEnvironment{Highlighting}{Verbatim}{commandchars=\\\{\}} |
| 44 |
% Add ',fontsize=\small' for more characters per line |
| 45 |
\newenvironment{Shaded}{}{} |
| 46 |
\newcommand{\AlertTok}[1]{\textcolor[rgb]{1.00,0.00,0.00}{\textbf{#1}}} |
| 47 |
\newcommand{\AnnotationTok}[1]{\textcolor[rgb]{0.38,0.63,0.69}{\textbf{\textit{#1}}}} |
| 48 |
\newcommand{\AttributeTok}[1]{\textcolor[rgb]{0.49,0.56,0.16}{#1}} |
| 49 |
\newcommand{\BaseNTok}[1]{\textcolor[rgb]{0.25,0.63,0.44}{#1}} |
| 50 |
\newcommand{\BuiltInTok}[1]{\textcolor[rgb]{0.00,0.50,0.00}{#1}} |
| 51 |
\newcommand{\CharTok}[1]{\textcolor[rgb]{0.25,0.44,0.63}{#1}} |
| 52 |
\newcommand{\CommentTok}[1]{\textcolor[rgb]{0.38,0.63,0.69}{\textit{#1}}} |
| 53 |
\newcommand{\CommentVarTok}[1]{\textcolor[rgb]{0.38,0.63,0.69}{\textbf{\textit{#1}}}} |
| 54 |
\newcommand{\ConstantTok}[1]{\textcolor[rgb]{0.53,0.00,0.00}{#1}} |
| 55 |
\newcommand{\ControlFlowTok}[1]{\textcolor[rgb]{0.00,0.44,0.13}{\textbf{#1}}} |
| 56 |
\newcommand{\DataTypeTok}[1]{\textcolor[rgb]{0.56,0.13,0.00}{#1}} |
| 57 |
\newcommand{\DecValTok}[1]{\textcolor[rgb]{0.25,0.63,0.44}{#1}} |
| 58 |
\newcommand{\DocumentationTok}[1]{\textcolor[rgb]{0.73,0.13,0.13}{\textit{#1}}} |
| 59 |
\newcommand{\ErrorTok}[1]{\textcolor[rgb]{1.00,0.00,0.00}{\textbf{#1}}} |
| 60 |
\newcommand{\ExtensionTok}[1]{#1} |
| 61 |
\newcommand{\FloatTok}[1]{\textcolor[rgb]{0.25,0.63,0.44}{#1}} |
| 62 |
\newcommand{\FunctionTok}[1]{\textcolor[rgb]{0.02,0.16,0.49}{#1}} |
| 63 |
\newcommand{\ImportTok}[1]{\textcolor[rgb]{0.00,0.50,0.00}{\textbf{#1}}} |
| 64 |
\newcommand{\InformationTok}[1]{\textcolor[rgb]{0.38,0.63,0.69}{\textbf{\textit{#1}}}} |
| 65 |
\newcommand{\KeywordTok}[1]{\textcolor[rgb]{0.00,0.44,0.13}{\textbf{#1}}} |
| 66 |
\newcommand{\NormalTok}[1]{#1} |
| 67 |
\newcommand{\OperatorTok}[1]{\textcolor[rgb]{0.40,0.40,0.40}{#1}} |
| 68 |
\newcommand{\OtherTok}[1]{\textcolor[rgb]{0.00,0.44,0.13}{#1}} |
| 69 |
\newcommand{\PreprocessorTok}[1]{\textcolor[rgb]{0.74,0.48,0.00}{#1}} |
| 70 |
\newcommand{\RegionMarkerTok}[1]{#1} |
| 71 |
\newcommand{\SpecialCharTok}[1]{\textcolor[rgb]{0.25,0.44,0.63}{#1}} |
| 72 |
\newcommand{\SpecialStringTok}[1]{\textcolor[rgb]{0.73,0.40,0.53}{#1}} |
| 73 |
\newcommand{\StringTok}[1]{\textcolor[rgb]{0.25,0.44,0.63}{#1}} |
| 74 |
\newcommand{\VariableTok}[1]{\textcolor[rgb]{0.10,0.09,0.49}{#1}} |
| 75 |
\newcommand{\VerbatimStringTok}[1]{\textcolor[rgb]{0.25,0.44,0.63}{#1}} |
| 76 |
\newcommand{\WarningTok}[1]{\textcolor[rgb]{0.38,0.63,0.69}{\textbf{\textit{#1}}}} |
| 77 |
\setlength{\emergencystretch}{3em} % prevent overfull lines |
| 78 |
\providecommand{\tightlist}{% |
| 79 |
\setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}} |
| 80 |
\setcounter{secnumdepth}{-\maxdimen} % remove section numbering |
| 81 |
\ifLuaTeX |
| 82 |
\usepackage{selnolig} % disable illegal ligatures |
| 83 |
\fi |
| 84 |
\IfFileExists{bookmark.sty}{\usepackage{bookmark}}{\usepackage{hyperref}} |
| 85 |
\IfFileExists{xurl.sty}{\usepackage{xurl}}{} % add URL line breaks if available |
| 86 |
\urlstyle{same} |
| 87 |
\hypersetup{ |
| 88 |
pdfauthor={Fr.~Jacques Peron; Urs Liska}, |
| 89 |
hidelinks, |
| 90 |
pdfcreator={LaTeX via pandoc}} |
| 91 |
|
| 92 |
\title{\texttt{luaoptions}} |
| 93 |
\usepackage{etoolbox} |
| 94 |
\makeatletter |
| 95 |
\providecommand{\subtitle}[1]{% add subtitle to \maketitle |
| 96 |
\apptocmd{\@title}{\par {\large #1 \par}}{}{} |
| 97 |
} |
| 98 |
\makeatother |
| 99 |
\subtitle{\luaoptionsmanualversion} |
| 100 |
\author{Fr.~Jacques Peron \and Urs Liska} |
| 101 |
\date{\luaoptionsmanualdate} |
| 102 |
|
| 103 |
\begin{document} |
| 104 |
\maketitle |
| 105 |
|
| 106 |
\thispagestyle{empty} |
| 107 |
\enlargethispage*{3\baselineskip} |
| 108 |
|
| 109 |
\hypertarget{introduction}{% |
| 110 |
\section{Introduction}\label{introduction}} |
| 111 |
|
| 112 |
\texttt{luaoptions} is a LuaLaTeX package providing extensive support |
| 113 |
for handling \emph{options}, on package level and locally. It is hosted |
| 114 |
at \url{https://github.com/lualatex-tools/luaoptions} and maintained by |
| 115 |
Jacques Peron |
| 116 |
(\href{mailto:[email protected]}{\nolinkurl{[email protected]}}) |
| 117 |
and Urs Liska |
| 118 |
(\href{mailto:[email protected]}{\nolinkurl{[email protected]}}). The |
| 119 |
package was originally developed as part of the \texttt{lyluatex} |
| 120 |
package\footnote{\url{https://github.com/jperon/lyluatex}} but has now |
| 121 |
been extracted as a standalone package because we realized it can be a |
| 122 |
useful tool for arbitrary LuaLaTeX packages having to deal with |
| 123 |
\emph{options} -- both \emph{package options} and \emph{optional macro |
| 124 |
arguments}. A \texttt{lyluatex} installation should not be a dependency |
| 125 |
for packages that want to make use of option handling but are not |
| 126 |
interested in music engraving \dots |
| 127 |
|
| 128 |
\texttt{luaoptions} allows the declaration of sets of options, along |
| 129 |
with defaults, expected/allowed values and limited type checking. These |
| 130 |
options can be enforced as package options, changed at any point during |
| 131 |
a document, or overwritten locally by optional macro arguments. It is |
| 132 |
also possible to instantiate an \texttt{Options} object as an |
| 133 |
independent Lua object, without linking it to a package. |
| 134 |
\texttt{luaoptions} can be used to enforce and prepopulate options, or |
| 135 |
it can be used to simply handle the parsing of optional |
| 136 |
\texttt{key=value} arguments into proper Lua tables. |
| 137 |
|
| 138 |
The main use of \texttt{luaoptions} is to define package options as |
| 139 |
follows: |
| 140 |
|
| 141 |
\begin{Shaded} |
| 142 |
\begin{Highlighting}[] |
| 143 |
\FunctionTok{\textbackslash{}RequirePackage}\NormalTok{\{luaoptions\}} |
| 144 |
\FunctionTok{\textbackslash{}directlua}\NormalTok{\{} |
| 145 |
\NormalTok{ local \_opt = lua\_options} |
| 146 |
\NormalTok{ lua\_options.register(\textquotesingle{}myoptions\textquotesingle{}, \{} |
| 147 |
\NormalTok{ [\textquotesingle{}option\textquotesingle{}] = \{\textquotesingle{}default value\textquotesingle{}, \textquotesingle{}other value\textquotesingle{}, \textquotesingle{}\textquotesingle{}\},} |
| 148 |
\NormalTok{ [\textquotesingle{}otheroption\textquotesingle{}] = \{\textquotesingle{}default\textquotesingle{}, validator\},} |
| 149 |
\NormalTok{ [\textquotesingle{}yetanotheroptions\textquotesingle{}] = \{\},} |
| 150 |
\NormalTok{ \})} |
| 151 |
\NormalTok{\}} |
| 152 |
\end{Highlighting} |
| 153 |
\end{Shaded} |
| 154 |
|
| 155 |
\texttt{validator} is a function that returns \texttt{true} when the |
| 156 |
defined option is valid, \texttt{false} otherwise. \texttt{luaoptions} |
| 157 |
itself contains predefined such functions. |
| 158 |
|
| 159 |
After that, defined options are available in a lua table, which can be |
| 160 |
used by the mean of the \texttt{client} command: |
| 161 |
|
| 162 |
\begin{Shaded} |
| 163 |
\begin{Highlighting}[] |
| 164 |
\KeywordTok{local} \VariableTok{myopts} \OperatorTok{=} \VariableTok{lua\_options}\OperatorTok{.}\NormalTok{client}\OperatorTok{(}\StringTok{\textquotesingle{}myoptions\textquotesingle{}}\OperatorTok{)} |
| 165 |
\VariableTok{tex}\OperatorTok{.}\NormalTok{sprint}\OperatorTok{(}\VariableTok{myopts}\OperatorTok{.}\VariableTok{option}\OperatorTok{)} |
| 166 |
\end{Highlighting} |
| 167 |
\end{Shaded} |
| 168 |
|
| 169 |
This initial release does \emph{not} include documentation beyond this |
| 170 |
short introduction; please refer to the docstrings in |
| 171 |
\texttt{luaoptions.lua} and \texttt{luaoptions-lib.lua} for more |
| 172 |
information. |
| 173 |
|
| 174 |
For the time being it is possible to look into how some of our own |
| 175 |
packages make use of \texttt{luaoptions}: |
| 176 |
|
| 177 |
\begin{itemize} |
| 178 |
\tightlist |
| 179 |
\item |
| 180 |
\url{https://github.com/jperon/lyluatex/blob/master/lyluatextools.sty} |
| 181 |
\item |
| 182 |
\url{https://github.com/jperon/lyluatex/blob/master/lyluatex.lua} |
| 183 |
\item |
| 184 |
\url{https://github.com/lualatex-tools/luaformatters/blob/master/luaformatters.sty} |
| 185 |
\item |
| 186 |
\url{https://github.com/lualatex-tools/luaformatters/blob/master/luaformatters.lua} |
| 187 |
\item |
| 188 |
\url{https://github.com/lualatex-tools/luaformatters/blob/master/submodules/luaformatters-formatter.lua} |
| 189 |
\end{itemize} |
| 190 |
|
| 191 |
\end{document} |