Debian Codegraph @

texmf-dist/doc/lualatex/luaoptions/luaoptions.tex

raw
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}