Debian Codegraph @

texmf-dist/doc/luatex/luakeys/luakeys-doc.tex

raw
1 \documentclass{ltxdoc}
2
3 \EnableCrossrefs
4 \CodelineIndex
5 \RecordChanges
6
7 \usepackage{mdframed}
8 \usepackage{minted}
9 \usepackage{luakeys}
10 \usepackage{luakeys-debug}
11 \usepackage{multicol}
12 \usepackage{luacode}
13 \usepackage{syntax}
14 \usepackage{graphicx}
15
16 \definecolor{bg}{rgb}{0.95,0.95,0.95}
17
18 \usemintedstyle{friendly}
19 \setminted{
20 breaklines=true,
21 fontsize=\footnotesize,
22 style=manni,
23 }
24 \def\lua#1{\mintinline{lua}|#1|}
25 \def\latex#1{\mintinline{latex}|#1|}
26
27 \NewDocumentCommand { \InputLatex } { O{} m } {
28 \inputminted[
29 linenos=false,
30 bgcolor=bg,
31 #1
32 ]{latex}{examples/#2}
33 }
34
35 \NewDocumentCommand { \InputLua } { O{} m } {
36 \inputminted[
37 linenos=false,
38 bgcolor=bg,
39 #1
40 ]{lua}{examples/#2}
41 }
42
43 \catcode`_=12
44 \def\DefaultOpt#1{%
45 \texttt{\directlua{
46 tex.print(luakeys.print_default('opts', '#1'))
47 }}%
48 }
49
50 \def\DefaultOptDescription#1{
51 \noindent
52 The default value of the option “\texttt{#1}” is:
53 \DefaultOpt{#1}.
54 }
55
56 \begin{document}
57
58 \providecommand*{\url}{\texttt}
59
60 \title{The \textsf{luakeys} package}
61 \author{%
62 Josef Friedrich\\%
63 \url{[email protected]}\\%
64 \href{https://github.com/Josef-Friedrich/luakeys}
65 {github.com/Josef-Friedrich/luakeys}%
66 }
67 \date{v0.17.0 from 2025/07/19}
68
69 \maketitle
70
71 \vfill
72
73 \InputLua[firstline=4,lastline=7]{first-page.lua}
74
75 \noindent
76 Result:
77
78 \begin{center}
79 \begin{minted}{lua}
80 {
81 ['level1'] = {
82 ['level2'] = {
83 ['naked'] = true,
84 ['dim'] = 1864679,
85 ['bool'] = false,
86 ['num'] = -0.001,
87 ['str'] = 'lua,{}',
88 }
89 }
90 }
91 \end{minted}
92 \end{center}
93
94 \vfill
95
96 \strut
97
98 \newpage
99
100 \tableofcontents
101
102 \newpage
103
104 % \section{Einführung}
105 \section{Introduction}
106
107 \noindent
108 % |luakeys| ist ein Lua-Modul / Lua\TeX package, das wie die Pakete ...
109 % Schlüssel-Wert-Optionen analysieren kann.
110 |luakeys| is a Lua module / Lua\TeX{} package that can parse key-value
111 options like the \TeX{} packages
112 \href{https://www.ctan.org/pkg/keyval}{keyval},
113 \href{https://www.ctan.org/pkg/kvsetkeys}{kvsetkeys},
114 \href{https://www.ctan.org/pkg/kvoptions}{kvoptions},
115 \href{https://www.ctan.org/pkg/xkeyval}{xkeyval},
116 \href{https://www.ctan.org/pkg/pgfkeys}{pgfkeys} etc.
117 %
118 % |luakeys|, erfüllt diese Aufgabe jedoch, indem es die Sprache Lua
119 % verwendet und nicht auf \TeX{} angewiesen ist.
120 |luakeys|, however, accomplishes this task by using the Lua language and
121 doesn’t rely on \TeX{}.
122 %
123 % Deshalb kann dieses Paket nur mit der \TeX{}-Engine Lua\TeX{}
124 % verwendet werden.
125 Therefore this package can only be used with the
126 \TeX{} engine Lua\TeX{}.
127 %
128 % Da |luakeys| \href{http://www.inf.puc-rio.br/~roberto/lpeg/}{LPeg}
129 % verwendet, sollte der Parsing-Mechanismus ziemlich robust sein.
130 Since |luakeys| uses
131 \href{http://www.inf.puc-rio.br/~roberto/lpeg/}{LPeg}, the parsing
132 mechanism should be pretty robust.
133
134 % Der Artikel TUGboat
135 % \href{http://www.tug.org/tugboat/tb30-1/tb94wright-keyval.pdf}
136 % {“Implementing key–value input: An introduction” (Volume 30 (2009), No.
137 % 1)} von \emph{Joseph Wright} und \emph{Christian Feuersänger} gibt einen
138 % einen guten Überblick über die verfügbaren Key-Value-Pakete.
139 The TUGboat article
140 \href{http://www.tug.org/tugboat/tb30-1/tb94wright-keyval.pdf}
141 {“Implementing key–value input: An introduction” (Volume 30 (2009), No.
142 1)} by \emph{Joseph Wright} and \emph{Christian Feuersänger} gives a
143 good overview of the available key-value packages.
144 %
145 % Dieser Artikel geht auf eine auf tex.stackexchange.com von Will
146 % Robertson: gestellte Frage zurück.
147 This article is based on a question asked on tex.stackexchange.com by
148 Will Robertson:
149 \href{https://tex.stackexchange.com/questions/26771}
150 {A big list of every keyval package}.
151 %
152 % CTAN stellt auch eine Übersichtsseite zum Thema bereit.
153 CTAN also provides an overview page on the subject of
154 \href{https://www.ctan.org/topic/keyval}
155 {Key-Val: packages with key-value argument systems}.
156
157 % Dieses Paket wäre ohne den Artikel
158 % \href{https://tug.org/TUGboat/tb40-2/tb125menke-lpeg.pdf}
159 % {"Parsing complex data formats in LuaTEX with LPEG" (Volume 40 (2019),
160 % No. 2)} nicht möglich gewesen.
161 This package would not be possible without the article
162 \href{https://tug.org/TUGboat/tb40-2/tb125menke-lpeg.pdf}
163 {“Parsing complex data formats in LuaTEX with LPEG” (Volume 40 (2019),
164 No. 2)}.
165
166 \subsection{Pros of \texttt{luakeys}}
167
168 \begin{itemize}
169 % \item Schlüssel-Wert-Paare können unabhängig vom Makro-Paket (latex or
170 % context) analysiert werden.
171 \item Key-value pairs can be parsed independently of the macro
172 collection (\LaTeX{} or Con\TeX{}t).
173 % Sogar in Plain LuaTex können Schlüssel analysiert werden
174 Even in plain Lua\TeX{} keys can be parsed.
175
176 % \item |luakeys| kann mit ineinander verschachtelten listen an
177 % Schlüssel-Wert-Paaren umgehen, d. h. es kann mit einer rekursiven
178 % Datenstruktur an Schlüssel umgehen.
179 \item |luakeys| can handle nested lists of key-value pairs, i.e. it can
180 handle a recursive data structure of keys.
181
182 % \item Schlüssel müssen nicht, aber können definiert werden.
183 \item Keys do not have to be defined, but can they can be defined.
184 \end{itemize}
185
186 \subsection{Cons of \texttt{luakeys}}
187
188 \begin{itemize}
189 % \item Das Packet funktioniert nur in der Verbindung mit Lua\TeX.
190 \item The package works only in combination with Lua\TeX.
191
192 % \item Du musst zwei Sprachen beherrschen: \TeX{} und Lua.
193 \item You need to know two languages: \TeX{} and Lua.
194 \end{itemize}
195
196 %-----------------------------------------------------------------------
197 %
198 %-----------------------------------------------------------------------
199
200 % \section{Wie das Paket geladen wird}
201 \section{How the package is loaded}
202
203 %%
204 %
205 %%
206
207 \subsection{Using the Lua module \texttt{luakeys.lua}}
208
209 % Die Kernfunktionalität dieses Pakets ist in Lua realisiert.
210 The core functionality of this package is realized in Lua.
211 %
212 % Sie können also |luakeys| auch ohne die Wrapper-Dateien
213 % \texttt{luakeys.sty} und \texttt{luakeys.tex} verwenden.
214 So you can use |luakeys| even without using the wrapper files
215 |luakeys.sty| and |luakeys.tex|.
216
217 \InputLatex{loading/lua.tex}
218
219 %%
220 %
221 %%
222
223 \subsection{Using the Lua\LaTeX{} wrapper \texttt{luakeys.sty}}
224
225 % Der Paketmanager MikTeX lädt beispielsweise Pakete erst bei Bedarf
226 % herunter.
227 For example, the MiK\TeX{} package manager downloads packages only when
228 needed.
229 %
230 % Es wurde berichtet, dass dieser automatische Download nur mit Hilfe
231 % der Hüll-Dateien funktioniert.
232 It has been reported that this automatic download only works with this
233 wrapper files.
234 %
235 % Wahrscheinlich hält MiK\TeX nach einem Auftreten des LaTeX macros
236 % “\latex{\usepackage{luakeys}} ”Ausschau.
237 Probably MiK\TeX{} is searching for an occurrence of the \LaTeX{} macro
238 “\latex{\usepackage{luakeys}}”.
239 %
240 % Die Datei \texttt{luakeys.sty} lädt das Lua-Modul in die globale
241 % Variable \texttt{luakeys}.
242 The \texttt{luakeys.sty} file loads the Lua module into the global
243 variable \texttt{luakeys}.
244
245 \InputLatex{loading/tex-latex.tex}
246
247 %%
248 %
249 %%
250
251 % \subsection{Verwendung des Plain-Lua\TeX{}-Hüllpakets
252 % \texttt{luakeys.tex}}
253 \subsection{Using the plain Lua\TeX{} wrapper \texttt{luakeys.tex}}
254
255 \noindent
256 % Es macht dasselbe wie das Lua\LaTeX{}-Hüllpacket und lädt das
257 % Lua-Modul \texttt{luakeys.lua} in die globale Variable
258 % \texttt{luakeys}.
259 The file \texttt{luakeys.tex} does the same as the Lua\LaTeX{} wrapper
260 and loads the Lua module \texttt{luakeys.lua} into the global variable
261 \texttt{luakeys}.
262
263 \InputLatex{loading/tex-plain.tex}
264
265 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
266 %
267 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
268
269 \section{Lua interface / API}
270
271 % Luakeys exportiert nur eine Funktion, die aufgerufen werden muss, um auf
272 % die öffentliche API zuzugreifen
273 Luakeys exports only one function that must be called to access the
274 public API.
275 %
276 % Diese Exportfunktion gibt eine Tabelle zurück, die die öffentlichen
277 % Funktionen und weiteren Tabellen enthält:
278 This export function returns a table containing the public functions and
279 additional tables:
280
281 \InputLua[firstline=3,lastline=16]{export.lua}
282
283 \noindent
284 % Das Projekt verwendet einige wenige Abkürzungen für Variablennamen,
285 % die hoffentlich für externe Leser eindeutig und bekannt sind.
286 The project uses a few abbreviations for variable names that are
287 hopefully unambiguous and familiar to external readers.
288
289 \begin{center}
290 \begin{tabular}{lll}
291 Abbreviation & spelled out & Example \\\hline
292 \lua{kv_string} & Key-value string & \lua{'key=value'} \\
293 \lua{opts} & Options (for the parse function) &
294 \lua{ { no_error = false } } \\
295 \lua{defs} & Definitions \\
296 \lua{def} & Definition \\
297 \lua{attr} & Attributes (of a definition) \\
298 \end{tabular}
299 \end{center}
300
301 \noindent
302 % Diese nicht abgekürzten Variablennamen werden häufig verwendet.
303 These unabbreviated variable names are commonly used.
304 \begin{center}
305 \begin{tabular}{ll}
306
307 \lua{result} &
308 % Das Endergebnis aller einzelnen Übersetzungs- und
309 % Normalisierungsschritte
310 The final result of all individual parsing and normalization steps. \\
311
312 \lua{unknown} &
313 % Ein Tabelle mit unbekannten, nicht definierten Schlüssel-Wert-Paaren
314 A table with unknown, undefinied key-value pairs. \\
315
316 \lua{raw} &
317 % Das unbearbeitete, rohe Ergebnis der LPeg-Syntaxanalyse.
318 The raw result of the Lpeg grammar parser. \\
319 \end{tabular}
320 \end{center}
321
322 \noindent
323 % Es wird empfohlen, beim Entwickeln im Texteditor luakeys zusammen mit
324 % dem Lua-Language-Server zu verwenden.
325 It is recommended to use luakeys together with the
326 \href{https://github.com/sumneko/lua-language-server}{github.com/sumneko/lua-language-server}
327 when developing in a text editor.
328 %
329 % Luakeys unterstützt nämlich das vom Server angeboten Annotationsformat
330 luakeys supports the annotation format offered by the server.
331 % Sie sollten dann Warnungen erhalten, wenn Sie die mittlerweile
332 % ziemlich große API von luakeys falsch verwenden.
333 You should then get warnings if you misuse luakeys’ now rather large API.
334
335 %%
336 %
337 %%
338
339 \subsection{Function “\texttt{parse(kv_string, opts): result, unknown,
340 raw}”}
341 \label{parse}
342
343 % Die Function parse ist die wichtigste Funktion des Pakets.
344 The function \lua{parse(kv_string, opts)} is the most important function
345 of the package.
346 %
347 %
348 % Sie konvertiert eine Schlüssel-Wert-Zeichenkette in eine Lua Tabelle.
349 It converts a key-value string into a Lua table.
350
351 \InputLatex{functions/parse/tex-latex.tex}
352
353 \noindent
354 In plain \TeX:
355
356 \InputLatex{functions/parse/tex-plain.tex}
357
358 \subsection{Options to configure the \texttt{parse} function}
359
360 \noindent
361 % Die Funktion \lua{parse} kann mit einer Optionstabelle aufgerufen
362 % werden.
363 The \lua{parse} function can be called with an options table.
364 % Diese Optionen werden unterstützt:
365 This options are supported: \catcode`_=12
366 \texttt{\directlua{luakeys.print_names('opts')}}
367
368 \InputLua[firstline=7,lastline=99]{opts/all-opts.lua}
369
370 \subsection{Table “\texttt{opts}”}
371 \label{table-opts}
372
373 \noindent
374 % Die Optionen können auch global über die exportierte Tabelle
375 % \lua{opts} gesetzt werden:
376 The options can also be set globally using the exported table
377 \lua{opts}:
378
379 \InputLua[firstline=4,lastline=4]{opts/exported-default-opts.lua}
380
381 \InputLua[firstline=10,lastline=11]{opts/exported-default-opts.lua}
382
383 \noindent
384 % Damit es zu keinen Wechselwirkungen mit anderen Paketen kommt, die auch
385 % |luakeys| verwenden und die Optionen global setzen, ist es anzuraten,
386 % die Funktion \lua{new()} zum Laden das Paket verwenden.
387 To avoid interactions with other packages that also use |luakeys| and
388 set the options globally, it is recommended to use the
389 \lua{new()} function
390 (\ref{function:new}) to load the package.
391
392 %%
393 %
394 %%
395
396 \subsubsection{Option “\texttt{accumulated_result}”}
397
398 % Streng genommen handelt es sich hier um keine Option
399 Strictly speaking, this is not an option.
400 %
401 % Mit der Option \lua{accumulated_result} kann eine Ergebnistabelle
402 % angegeben werden, die bei jedem Aufruf der \lua{parse}-Funktion weiter
403 % befüllt wird.
404 The \lua{accumulated_result} “option” can be used to specify a result
405 table that is filled with each call of the \lua{parse} function.
406
407 \InputLua[firstline=5,lastline=14]{opts/accumulated-result.lua}
408
409 %%
410 %
411 %%
412
413 \subsubsection{Option “\texttt{assignment_operator}”}
414 \label{option:assignment-operator}
415 \label{options-delimiter}
416
417 The option \lua{assignment_operator} configures the delimiter that
418 assigns a value to a key. The default value of this option is
419 \texttt{"="}.
420
421 The code example below demonstrates all six delimiter related options.
422
423 \InputLua[firstline=4,lastline=13]{opts/delimiters.lua}
424
425 \begin{tabular}{ll}
426 \textbf{Delimiter options} & \textbf{Section} \\
427 assignment_operator & \ref{option:assignment-operator}\\
428 group_begin & \ref{option:group-begin}\\
429 group_end & \ref{option:group-end}\\
430 list_separator & \ref{option:list-separator}\\
431 quotation_begin & \ref{option:quotation-begin}\\
432 quotation_end & \ref{option:quotation-end}\\
433 \end{tabular}
434
435 %%
436 %
437 %%
438
439 \subsubsection{Option “\texttt{convert_dimensions}”}
440
441 % Wenn Sie die Option \lua{convert_dimensions} auf \lua{true} setzen,
442 % erkennt |luakeys| die \TeX{}-Dimensionen und konvertiert sie mit Hilfe
443 % der die Funktion \lua{tex.sp(dim)} in scaled points.
444 If you set the option \lua{convert_dimensions} to \lua{true}, |luakeys|
445 detects the \TeX{} dimensions and converts them into scaled points using
446 the function \lua{tex.sp(dim)}.
447
448 \InputLua[firstline=4,lastline=7]{opts/convert-dimensions/true.lua}
449
450 \noindent
451 % Standardmäßig werden die Dimensionen nicht in skalierte Punkte
452 % umgewandelt.
453 By default the dimensions are not converted into scaled points.
454
455 \InputLua[firstline=4,lastline=9]{opts/convert-dimensions/false.lua}
456
457 \noindent
458 % Wenn Sie eine skalierte Punktzahl in einen Dimensionszeichenketten
459 % umwandeln möchten, können Sie das Modul
460 If you want to convert a scaled points number into a dimension string
461 you can use the module
462 \href{https://raw.githubusercontent.com/latex3/lualibs/master/lualibs-util-dim.lua}
463 {lualibs-util-dim.lua}.
464
465 \begin{minted}{lua}
466 require('lualibs')
467 tex.print(number.todimen(tex.sp('1cm'), 'cm', '%0.0F%s'))
468 \end{minted}
469
470 \DefaultOptDescription{convert_dimensions}
471
472 %%
473 %
474 %%
475
476 \subsubsection{Option “\texttt{debug}”}
477
478 % Wenn die Option \lua{debug} auf true gesetzt ist, wird die
479 % Ergebnistabelle in der Konsole ausgegeben.
480 If the option \lua{debug} is set to true, the result table is printed to
481 the console.
482
483 \InputLatex{opts/debug-latex.tex}
484
485 \begin{verbatim}
486 This is LuaHBTeX, Version 1.15.0 (TeX Live 2022)
487 ...
488 (./debug.aux) (/usr/local/texlive/texmf-dist/tex/latex/base/ts1cmr.fd)
489 {
490 ['three'] = true,
491 ['two'] = true,
492 ['one'] = true,
493 }
494 [1{/usr/
495 local/texlive/2022/texmf-var/fonts/map/pdftex/updmap/pdftex.map}] (./debug.aux)
496 )
497 ...
498 Transcript written on debug.log.
499 \end{verbatim}
500
501 \DefaultOptDescription{debug}
502
503 %%
504 %
505 %%
506
507 \subsubsection{Option “\texttt{default}”}
508 \label{option-default}
509
510 % Mit der Option \lua{default} kann angegeben werden, welchen Wert
511 % nackte Schlüssel (Schlüssel ohne Wert) erhalten. Diese Option hat
512 % keinen Einfluss auf Schlüssel mit Werten.
513 The option \lua{default} can be used to specify which value naked keys
514 (keys without a value) get. This option has no influence on keys with
515 values.
516
517 \InputLua[firstline=4,lastline=5]{opts/default.lua}
518
519 \noindent
520 % Standardmäßig erhalten nackte Schlüssel den Wert \lua{true}.
521 By default, naked keys get the value \lua{true}.
522
523 \InputLua[firstline=11,lastline=12]{opts/default.lua}
524
525 \DefaultOptDescription{default}
526
527 %%
528 %
529 %%
530
531 \subsubsection{Option “\texttt{defaults}”}
532 \label{options-defaults}
533
534 % Mit der Attribut „defaults“ kann nicht nur ein einiger Standardwert
535 % angegeben werden, sondern eine ganze Tabelle mit Standardwerten.
536 The option “defaults” can be used to specify not only one default value,
537 but a whole table of default values.
538 % Die Ergebnistabelle wird mit der Tabelle bestehend aus Standardwerten
539 % vereinigt.
540 The result table is merged into the defaults table.
541 % Werte aus der Tabelle mit Standardwerten werden von Werten der
542 % Ergebnistabelle überschrieben.
543 Values in the defaults table are
544 overwritten by values in the result table.
545
546 \InputLua[firstline=4,lastline=7]{opts/defaults.lua}
547
548 \DefaultOptDescription{defaults}
549
550 %%
551 %
552 %%
553
554 \subsubsection{Option “\texttt{defs}”}
555
556 % Für mehr Information wie Schlüssel definiert werden, lesen sie das
557 % kapitel 3.2
558 For more informations on how keys are defined, see section \ref{define}.
559 % Wenn sie die Option \lua{defs} verwenden, können sie auf den
560 % Aufruf der Funktion \lua{define} verzichten.
561 If you use the \lua{defs} option, you don't need to call the
562 \lua{define} function.
563 %
564 % Anstatt
565 Instead of ...
566
567 \InputLua[firstline=4,lastline=5]{opts/defs.lua}
568
569 \noindent
570 % können wir schreiben ..
571 we can write ...
572
573 \InputLua[firstline=11,lastline=13]{opts/defs.lua}
574
575 \DefaultOptDescription{defs}
576
577 %%
578 %
579 %%
580
581 \subsubsection{Option “\texttt{false_aliases}”}
582 \label{option:false-aliases}
583
584 % Mit den den Optionen \lua{true_aliases} and \lua{false_aliases} können
585 % die Zeichenketten festgelegt werden, die vom Parser als Wahrheitswerte
586 % erkannt werden.
587 The \lua{true_aliases} and \lua{false_aliases} options can be used to
588 specify the strings that will be recognized as boolean values by the
589 parser.
590 % Standardmäßig sind folgende Zeichenketten konfiguriert
591 The following strings are configured by default.
592
593 \InputLua[firstline=4,lastline=8]{opts/boolean-aliases.lua}
594
595 \InputLua[firstline=14,lastline=18]{opts/boolean-aliases.lua}
596
597 \InputLua[firstline=24,lastline=28]{opts/boolean-aliases.lua}
598
599 % Siehe Abschnitt \label{option:true-aliases} für die entsprechende
600 % Option.
601 See section \ref{option:true-aliases} for the corresponding option.
602
603 %%
604 %
605 %%
606
607 \subsubsection{Option “\texttt{format_keys}”}
608
609 % Mit Hilfe der Option \lua{format_keys} können die Schlüssel formatiert
610 % werden.
611 With the help of the option \lua{format_keys} the keys can be formatted.
612 % Die Werte dieser Option müssen in einer Tabelle angegeben werden.
613 The values of this option must be specified in a table.
614
615 \begin{description}
616 \item[lower]
617
618 % Um alle Schlüssel in \emph{Kleinbuchstaben} umzuwandeln, geben sie in
619 % der Optionentabelle \lua{lower} an.
620 To convert all keys to \emph{lowercase}, specify \lua{lower} in the
621 options table.
622
623 \InputLua[firstline=4,lastline=5]{opts/format-keys.lua}
624
625 \item[snake]
626
627 % Um alle Schlüssel in \emph{snake case} (Die Wörter sind durch
628 % Unterstriche getrennt) umzuwandeln, geben sie in der Optionentabelle
629 % \lua{snake} an.
630 To make all keys \emph{snake case} (The words are separated by
631 underscores), specify \lua{snake} in the options
632 table.
633
634 \InputLua[firstline=11,lastline=12]{opts/format-keys.lua}
635
636 \item[upper]
637
638 % Um alle Schlüssel in \emph{Großbuchstaben} umzuwandeln, geben sie in
639 % der Optionentabelle \lua{upper} an.
640 To convert all keys to \emph{uppercase}, specify \lua{upper} in the
641 options table.
642
643 \InputLua[firstline=18,lastline=19]{opts/format-keys.lua}
644 \end{description}
645
646 % Sie können auch mehrere Formatierungsarten kombinieren.
647 You can also combine several types of formatting.
648
649 \InputLua[firstline=25,lastline=26]{opts/format-keys.lua}
650
651 \DefaultOptDescription{format_keys}
652
653 %%
654 %
655 %%
656
657 \subsubsection{Option “\texttt{group_begin}”}
658 \label{option:group-begin}
659
660 The option \lua{group_begin} configures the delimiter that marks the
661 beginning of a group. The default value of this option is \texttt{"\{"}.
662 A code example can be found in section \ref{options-delimiter}.
663
664 %%
665 %
666 %%
667
668 \subsubsection{Option “\texttt{group_end}”}
669 \label{option:group-end}
670
671 The option \lua{group_end} configures the delimiter that marks the end
672 of a group. The default value of this option is \texttt{"\}"}. A code
673 example can be found in section \ref{options-delimiter}.
674
675 %%
676 %
677 %%
678
679 \subsubsection{Option “\texttt{invert_flag}”}
680
681 % Wird ein nackter Schlüssel mit einem vorangestellten Ausrufezeichen versehen, so wird sein Standardwert invertiert.
682 If a naked key is prefixed with an exclamation mark, its default value
683 is inverted.
684 % Statt \lua{true} nimmt der Schlüssel jetzt den Wert \lua{falsch} an.
685 Instead of \lua{true} the key now takes the value \lua{false}.
686
687 \InputLua[firstline=4,lastline=5]{opts/invert-flat.lua}
688
689 \noindent
690 % Mit der Option \lua{invert_flag} kann dieses Invertierungszeichen
691 % geändert werden.
692 The \lua{invert_flag} option can be used to change this inversion
693 character.
694
695 \InputLua[firstline=11,lastline=12]{opts/invert-flat.lua}
696
697 \noindent
698 % Ist der Standardwert für nackte Schlüssel beispielweise auf \lua{false}
699 % gesetzt, so nehmen die mit dem Umkehrungszeichen versehenen nackten
700 % Schlüssel den Wert \lua{true} an.
701 For example, if the default value for naked keys is set to \lua{false},
702 the naked keys prefixed with the invert flat take the value \lua{true}.
703
704 \InputLua[firstline=18,lastline=19]{opts/invert-flat.lua}
705
706 \noindent
707 % Setzen sie die Option \lua{invert_flag} auf \lua{false}, um diese
708 % automatische Wertumkehrung zu deaktivieren.
709 Set the \lua{invert_flag} option to \lua{false} to disable this
710 automatic boolean value inversion.
711
712 \InputLua[firstline=25,lastline=26]{opts/invert-flat.lua}
713
714 %%
715 %
716 %%
717
718 \subsubsection{Option “\texttt{hooks}”}
719
720 % Die folgenden Hooks bzw. Callback-Funktionen ermöglichen es in den
721 % Verarbeitungsprozess der \lua{parse}-Function einzugreifen.
722 The following hooks or callback functions allow to intervene in the
723 processing of the \lua{parse} function.
724 %
725 % Die Funktionen sind in der Verarbeitungsreihenfolge aufgelistet.
726 The functions are listed in processing order.
727 %
728 % \lua{*_before_opts} bedeutet, dass die Hooks nach der LPeg
729 % Syntaxanalyse und vor dem Anwenden der Optionen ausgeführt
730 \lua{*_before_opts} means that the hooks are executed after the LPeg
731 syntax analysis and before the options are applied.
732 %
733 % Die Hooks \lua{*_before_defs} werden vor dem Anwenden der
734 % Schlüssel-Wert-Definitionen ausgeführt
735 The \lua{*_before_defs} hooks are executed before applying the key value
736 definitions.
737
738 \def\TmpSignature#1{
739 {
740 \scriptsize\texttt{ = #1}
741 }
742 }
743
744 \def\TmpKeySignature{
745 \TmpSignature{function(key, value, depth, current, result): key, value}
746 }
747 \def\TmpResultSignature{
748 \TmpSignature{function(result): void}
749 }
750
751 \begin{enumerate}
752 \item \lua{kv_string} \TmpSignature{function(kv_string): kv_string}
753 \item \lua{keys_before_opts} \TmpKeySignature
754 \item \lua{result_before_opts} \TmpResultSignature
755 \item \lua{keys_before_def} \TmpKeySignature
756 \item \lua{result_before_def} \TmpResultSignature
757 \item (\lua{process}) (has to be definied using defs, see \ref{attr-process})
758 \item \lua{keys} \TmpKeySignature
759 \item \lua{result} \TmpResultSignature
760 \end{enumerate}
761
762 \paragraph{\texttt{kv_string}}
763
764 % Der Hook \lua{kv_string} wird als erste
765 % der Hook-Funktionen noch vor der LPeg-Syntax-Analyse aufgerufen.
766 The \lua{kv_string} hook is called as the first of the hook functions
767 before the LPeg syntax parser is executed.
768
769 \InputLua[firstline=4,lastline=11]{hooks/kv-string.lua}
770
771 \paragraph{\texttt{keys_*}}
772
773 % Die Hooks \lua{keys_*} werden rekursiv auf jeden Schlüssel in der
774 % aktuellen Ergebnistabelle aufgerufen.
775 The hooks \lua{keys_*} are called recursively on each key in the current
776 result table.
777 % Die Hook-Funktion muss zwei Werte zurückgeben: \lua{key, value}
778 The hook function must return two values: \lua{key, value}.
779 %
780 % Das folgende Beispiel gibt \lua{key} und \lua{value} unverändert
781 % zurück, sodass die Ergebnistabelle nicht verändert wird.
782 The following example returns \lua{key} and \lua{value} unchanged, so
783 the result table is not changed.
784
785 \InputLua[firstline=4,lastline=11]{hooks/keys-unchanged.lua}
786
787 \noindent
788 % Das nächste Beispiel demonstriert den dritten Parameter \lua{depth}
789 % der Hook-Funktion.
790 The next example demonstrates the third parameter \lua{depth} of the
791 hook function.
792
793 \InputLua[firstline=4,lastline=16]{hooks/keys-depth.lua}
794
795 \paragraph{\texttt{result_*}}
796
797 % Die Hooks \lua{result_*} werden einmal mit der aktuellen
798 % Ergebnistabelle als Parameter aufgerufen.
799 The hooks \lua{result_*} are called once with the current result table
800 as a parameter.
801
802 %%
803 %
804 %%
805
806 \subsubsection{Option “\texttt{list_separator}”}
807 \label{option:list-separator}
808
809 The option \lua{list_separator} configures the delimiter that separates
810 list items from each other. The default value of this option is
811 \texttt{","}. A code example can be found in section
812 \ref{options-delimiter}.
813
814 %%
815 %
816 %%
817
818 \subsubsection{Option “\texttt{naked_as_value}”}
819
820 % Mit Hilfe der Option \lua{naked_as_value} werden nackte Schlüssel
821 % nicht mit einem Standardwert versehen, sondern als Werte in die
822 % Lua-Tabelle abgelegt.
823 With the help of the option \lua{naked_as_value}, naked keys are not
824 given a default value, but are stored as values in a Lua table.
825
826 \InputLua[firstline=4,lastline=5]{opts/naked-as-value.lua}
827
828 \noindent
829 If we set the option \lua{naked_as_value} to \lua{true}:
830
831 \InputLua[firstline=11,lastline=14]{opts/naked-as-value.lua}
832
833 \DefaultOptDescription{naked_as_value}
834
835 %%
836 %
837 %%
838
839 \subsubsection{Option “\texttt{no_error}”}
840
841 % Standardmaßig wirft parse-Funktion einen Fehler, wenn es unbekannte
842 % Schlüssel gibt.
843 By default the parse function throws an error if there are unknown keys.
844 % Mit Hilfe der Option \lua{no_error} kann dies unterbunden werden.
845 This can be prevented with the help of the \lua{no_error} option.
846
847 \InputLua[firstline=5,lastline=6]{opts/no-error.lua}
848
849 \noindent
850 If we set the option \lua{no_error} to \lua{true}:
851
852 \InputLua[firstline=9,lastline=10]{opts/no-error.lua}
853
854 \DefaultOptDescription{no_error}
855
856 %%
857 %
858 %%
859
860 \subsubsection{Option “\texttt{quotation_begin}”}
861 \label{option:quotation-begin}
862
863 The option \lua{quotation_begin} configures the delimiter that marks the
864 beginning of a string. The default value of this option is
865 \texttt{'"'} (double quotes). A code example can be found in section
866 \ref{options-delimiter}.
867
868 %%
869 %
870 %%
871
872 \subsubsection{Option “\texttt{quotation_end}”}
873 \label{option:quotation-end}
874
875 The option \lua{quotation_end} configures the delimiter that marks the
876 end of a string. The default value of this option is \texttt{'"'}
877 (double quotes). A code example can be found in section
878 \ref{options-delimiter}.
879
880 %%
881 %
882 %%
883
884 \subsubsection{Option “\texttt{true_aliases}”}
885 \label{option:true-aliases}
886
887 See section \ref{option:false-aliases}.
888
889 %%
890 %
891 %%
892
893 \subsubsection{Option “\texttt{unpack}”}
894
895 % Mit Hilfe der Option \lua{unpack} werden alle Tabellen, die nur aus
896 % einem einzigen nackten Schlüssel bzw. einen einzigen alleinstehenden
897 % Wert bestehen, aufgelöst.
898 With the help of the option \lua{unpack}, all tables that consist of
899 only a single naked key or a single standalone value are unpacked.
900
901 \InputLua[firstline=4,lastline=5]{opts/unpack.lua}
902
903 \InputLua[firstline=11,lastline=12]{opts/unpack.lua}
904
905 \DefaultOptDescription{unpack}
906
907 %%
908 %
909 %%
910
911 \subsection{Function “\texttt{define(defs, opts): parse}”}
912 \label{define}
913
914 % Die \lua{define} Funktion definiert eine neue \lua{parse}-Funktion.
915 The \lua{define} function definies a new \lua{parse} function.
916 % Die Funktion \lua{define} gibt eine Funktion \lua{parse} zurück (siehe
917 % \ref{parse}).
918 The \lua{define} function returns a \lua{parse} function (see
919 \ref{parse}).
920 % Diese erstellte „parse“-Funktion ist mit den angegebenen
921 % Schlüssel-Wert-Definitionen konfiguriert.
922 This created \lua{parse} function is configured with the specified
923 key-value defintions.
924
925 The name of a key can be specified in three ways:
926
927 \begin{enumerate}
928 \item as a string.
929 \item as a key in a Lua table. The definition of the corresponding
930 key-value pair is then stored under this key.
931 \item by the “name” attribute.
932 \end{enumerate}
933
934 \InputLua[firstline=4,lastline=16]{functions/define.lua}
935
936 \noindent
937 % Bei verschachtelten Definitionen können nur die letzten beiden
938 % Möglichkeiten zur Angabe der Schlüsselnamen verwendet werden.
939 For nested definitions, only the last two ways of specifying the key
940 names can be used.
941
942 \InputLua[firstline=26,lastline=33]{functions/define.lua}
943
944 %-----------------------------------------------------------------------
945 %
946 %-----------------------------------------------------------------------
947
948 \subsection{Attributes to define a key-value pair}
949
950 % Die Definition eines Schlüssel-Wert-Paares kann mit Hilfe von
951 % verschiedenen Attributen vorgenommen werden.
952 The definition of a key-value pair can be made with the help of various
953 attributes.
954 %
955 % Der Name „Attribut“ für eine Option, einen Schlüssel, eine Eigenschaft
956 % (um nur einige Benennungsmöglichkeiten aufzuzählen) zur
957 % Schlüssel-Definition, wurde bewusst gewählt, um sie von den Optionen
958 % der Funktion \lua{parse} zu unterscheiden.
959 The name \emph{“attribute”} for an option, a key, a property ... (to
960 list just a few naming possibilities) to define keys, was deliberately
961 chosen to distinguish them from the options of the \lua{parse} function.
962 %
963 % Diese Attribute sind erlaubt.
964 These attributes are allowed:
965 \texttt{\directlua{luakeys.print_names('attrs')}}.
966 %
967 % Das folgende Codebeispiel listet alle Attribute auf, die verwendet
968 % werden können, um Schlüssel-Wert-Paare zu definieren.
969 The code example below lists all the attributes that can be used to
970 define key-value pairs.
971
972 \InputLua[firstline=5,lastline=62]{defs/all-attrs.lua}
973
974 %%
975 %
976 %%
977
978 \subsubsection{Attribute “\texttt{alias}”}
979
980 With the help of the \lua{alias} attribute, other key names can be used.
981 The value is always stored under the original key name. A single alias
982 name can be specified by a string ...
983
984 \InputLua[firstline=4,lastline=7]{defs/attrs/alias.lua}
985
986 \noindent
987 multiple aliases by a list of strings.
988
989 \InputLua[firstline=13,lastline=16]{defs/attrs/alias.lua}
990
991 %%
992 %
993 %%
994
995 \subsubsection{Attribute “\texttt{always_present}”}
996
997 % Die Option \lua{default} wird nur bei nackten Schlüsseln verwendet.
998 The \lua{default} attribute is used only for naked keys.
999
1000 \InputLua[firstline=4,lastline=5]{defs/attrs/always-present.lua}
1001
1002 \noindent
1003 % Wird die Option \lua{always_present} auf wahr gesetzt, wird der
1004 % Schlüssel immer ins Ergebnis mit übernommen.
1005 If the attribute \lua{always_present} is set to true, the key is always
1006 included in the result. If no default value is definied, true is taken
1007 as the value.
1008
1009 \InputLua[firstline=11,lastline=12]{defs/attrs/always-present.lua}
1010
1011 %%
1012 %
1013 %%
1014
1015 \subsubsection{Attribute “\texttt{choices}”}
1016
1017 % source: Python argparse documentation.
1018 Some key values should be selected from a restricted set of choices.
1019 These can be handled by passing an array table containing choices.
1020
1021 \InputLua[firstline=4,lastline=5]{defs/attrs/choices.lua}
1022
1023 \noindent
1024 When the key-value pair is parsed, values will be checked, and an error
1025 message will be displayed if the value was not one of the acceptable
1026 choices:
1027
1028 \InputLua[firstline=13,lastline=15]{defs/attrs/choices.lua}
1029
1030 %%
1031 %
1032 %%
1033
1034 \subsubsection{Attribute “\texttt{data_type}”}
1035
1036 % source: Python argparse documentation.
1037 The \lua{data_type} attribute allows type-checking and type conversions
1038 to be performed.
1039 %
1040 % Folgende Datentypen werden unterstützt:
1041 The following data types are supported:
1042 \lua{'boolean'},
1043 \lua{'dimension'},
1044 \lua{'integer'},
1045 \lua{'number'},
1046 \lua{'string'},
1047 \lua{'list'}.
1048 %
1049 % Bei den drei Datentypen integer, number, dimension kann eine
1050 % Typenumwandlung scheitern.
1051 A type conversion can fail with the three data types
1052 \lua{'dimension'},
1053 \lua{'integer'},
1054 \lua{'number'}.
1055 %
1056 % Dann wird eine Fehlermeldung ausgegeben.
1057 Then an error message is displayed.
1058
1059 \InputLua[firstline=4,lastline=8]{defs/attrs/data-type.lua}
1060 \InputLua[firstline=11,lastline=15]{defs/attrs/data-type.lua}
1061
1062 %%
1063 %
1064 %%
1065
1066 \subsubsection{Attribute “\texttt{default}”}
1067
1068 % Verwenden Sie das Attribut „\lua{default}“, um für jeden nackten Schlüssel
1069 % einzeln einen Standardwert bereit zu stellen.
1070 Use the \lua{default} attribute to provide a default value for each naked
1071 key individually.
1072 %
1073 % Mit der globalen \lua{default} Option kann für alle nackten Schlüssel ein
1074 % Standardwert vorgegeben werden.
1075 With the global \lua{default} attribute (\ref{option-default}) a default
1076 value can be specified for all naked keys.
1077
1078 \InputLua[firstline=4,lastline=9]{defs/attrs/default.lua}
1079
1080 %%
1081 %
1082 %%
1083
1084 \subsubsection{Attribute “\texttt{description}”}
1085
1086 % Dieses Attribut wird momentan nicht weiterverarbeitet.
1087 This attribute is currently not processed further.
1088 % Es kann als Kommentar dienen.
1089 It can serve as a comment.
1090
1091 %%
1092 %
1093 %%
1094
1095 \subsubsection{Attribute “\texttt{exclusive_group}”}
1096
1097 % Alle Schlüssel, die der gleichen ausschließenden Gruppe angehören,
1098 % dürfen nicht gemeinsam angegeben werden.
1099 All keys belonging to the same exclusive group must not be specified
1100 together.
1101 %
1102 % Nur ein Schlüssel aus dieser Gruppe ist erlaubt.
1103 Only one key from this group is allowed.
1104 %
1105 % Als Name für diese ausschließende Gruppe kann irgend ein beliebiger
1106 % Wert verwendet werden.
1107 Any value can be used as a name for this exclusive group.
1108
1109 \InputLua[firstline=4,lastline=9]{defs/attrs/exclusive-group.lua}
1110
1111 \noindent
1112 % Werden mehrer Schlüssel der Gruppe angegeben, so wird eine
1113 % Fehlermeldung geworfen.
1114 If more than one key of the group is specified, an error message is
1115 thrown.
1116
1117 \InputLua[firstline=21,lastline=23]{defs/attrs/exclusive-group.lua}
1118
1119 %%
1120 %
1121 %%
1122
1123 \subsubsection{Attribute “\texttt{macro}”}
1124
1125 The attribute \texttt{macro} stores the value in a \TeX{} macro.
1126
1127 \begin{minted}{lua}
1128 local parse = luakeys.define({
1129 key = {
1130 macro = 'MyMacro'
1131 }
1132 })
1133 parse('key=value')
1134 \end{minted}
1135
1136 \begin{minted}{latex}
1137 \MyMacro % expands to “value”
1138 \end{minted}
1139
1140 %%
1141 %
1142 %%
1143
1144 \subsubsection{Attribute “\texttt{match}”}
1145
1146 % Der Wert des Schlüssel wird zuerst der Lua Funktion
1147 % \lua{string.match(value, match)} übergeben, bevor er dem Schlüssel
1148 % zugewiesen wird.
1149 The value of the key is first passed to the Lua function
1150 \lua{string.match(value, match)}
1151 (\url{http://www.lua.org/manual/5.3/manual.html#pdf-string.match})
1152 before being assigned to the key.
1153 %
1154 % Du kannst das Attribut \lua{match} deshalb mit einer Pattern-Matching-
1155 % Zeichenkette konfigurieren, wie sie in Lua zu Einsatz kommt.
1156 You can therefore configure the \lua{match} attribute with a pattern
1157 matching string used in Lua.
1158 %
1159 % Werfe einen Blick in das Lua-Handbuch, wie man Patterns schreibt.
1160 Take a look at the Lua manual on how to write patterns
1161 (\url{http://www.lua.org/manual/5.3/manual.html#6.4.1}).
1162
1163 \InputLua[firstline=4,lastline=7]{defs/attrs/match/birthday.lua}
1164
1165 \noindent
1166 % Kann das Pattern im Wert nicht gefunden werden, wird eine
1167 % Fehlermeldung ausgegeben.
1168 If the pattern cannot be found in the value, an error message is issued.
1169
1170 \InputLua[firstline=15,lastline=18]{defs/attrs/match/birthday.lua}
1171
1172 \noindent
1173 % Der Schlüssel erhält das Ergebnis der Funktion \lua{string.match(value,
1174 % match)}, dass bedeutet, dass der ursprüngliche Wert unter
1175 % Umständen nicht vollständig in den Schlüssel gespeichert wird.
1176 The key receives the result of the function \lua{string.match(value,
1177 match)}, which means that the original value may not be stored
1178 completely in the key.
1179 %
1180 % Im nächsten Beispiel wird der gesamte Eingabewert akzeptiert:
1181 In the next example, the entire input value is accepted:
1182
1183 \InputLua[firstline=4,lastline=5]{defs/attrs/match/year.lua}
1184
1185 \noindent
1186 % Das Präfix “waste ” und das Suffix “ rubbisch” der Zeichenketten wird
1187 % verworfen.
1188 The prefix “waste ” and the suffix “ rubbisch” of the string are
1189 discarded.
1190
1191 \InputLua[firstline=11,lastline=11]{defs/attrs/match/year.lua}
1192
1193 \noindent
1194 % Da Funktion \lua{string.match(value, match)} immer eine Zeichenkette
1195 % zurückgibt, ist der Wert des Schlüssel auch immer eine Zeichenkette.
1196 Since function \lua{string.match(value, match)} always returns a string,
1197 the value of the key is also always a string.
1198
1199 %%
1200 %
1201 %%
1202
1203 \subsubsection{Attribute “\texttt{name}”}
1204
1205 % Die Option \lua{name} ermöglicht eine alternative Notation von
1206 % Schlüsselnamen.
1207 The \lua{name} attribute allows an alternative notation of key names.
1208 %
1209 % Anstatt ...
1210 Instead of ...
1211
1212 \InputLua[firstline=4,lastline=8]{defs/attrs/name/as-key.lua}
1213
1214 \noindent
1215 % ... können wir schreiben:
1216 ... we can write:
1217
1218 \InputLua[firstline=4,lastline=8]{defs/attrs/name/name-attr.lua}
1219
1220 %%
1221 %
1222 %%
1223
1224 \subsubsection{Attribute “\texttt{opposite_keys}”}
1225
1226 % Die Option \lua{opposite_keys} ermöglicht es, gegensätzliche (nackte)
1227 % Schlüssel in Wahrheitswerte umzuwandeln und diesen Wahrheitswert unter
1228 % einem Zielschlüssel zu speichern.
1229 The \lua{opposite_keys} attribute allows to convert opposite (naked)
1230 keys into a boolean value and store this boolean under a target key.
1231 %
1232 % Lua erlaubt es in Tabellen Wahrheitswerte als Schlüssel zu verwenden.
1233 % Es müssen jedoch eckige Klammern verwendet werden.
1234 Lua allows boolean values to be used as keys in tables.
1235 %
1236 % Die Wahrheitswerte müssen jedoch in eckige Klammern geschrieben werden.
1237 However, the boolean values must be written in square brackets, e. g.
1238 \lua{{ opposite_keys = { [true] = 'show', [false] = 'hide' } }}.
1239 %
1240 % Beispiele für gegensätzliche Schlüssel sind:
1241 Examples of opposing keys are: \lua{show} and \lua{hide}, \lua{dark} and
1242 \lua{light}, \lua{question} and \lua{solution}.
1243 %
1244 % Das untenstehende Beispiel verwendet als gegensätzliches Schlüsselpaar
1245 % die Schlüssel \lua{show} und \lua{hide}.
1246 The example below uses the \lua{show} and \lua{hide} keys as the
1247 opposite key pair.
1248 %
1249 % Wird der Schlüssel \lua{show} von der Funktion \lua{parse} gelesen,
1250 % dann erhält der Zielschlüssel \lua{visibility} den Wert \lua{true}.
1251 If the key \lua{show} is parsed by the \lua{parse} function, then the
1252 target key \lua{visibility} receives the value \lua{true}.
1253
1254 \InputLua[firstline=4,lastline=7]{defs/attrs/opposite-keys.lua}
1255
1256 % Wird der Schlüssel \lua{hide} gelesen, dann \lua{falsch}.
1257 \noindent
1258 If the key \lua{hide} is parsed, then \lua{false}.
1259
1260 \InputLua[firstline=13,lastline=13]{defs/attrs/opposite-keys.lua}
1261
1262 \noindent
1263 % Gegensätzliche Schlüsselpaare können in einer Kurzschreibweise
1264 % angegeben werden, nämlich als Liste
1265 Opposing key pairs can be specified in a short form, namely as a list:
1266 % Der gegensätzliche Schlüssel, der den Wahrwert repräsentiert, muss in
1267 % dieser Liste zuerst angegeben werden, dann folgt der Falschwert.
1268 The opposite key, which represents the true value, must be specified
1269 first in this list, followed by the false value.
1270
1271 \InputLua[firstline=19,lastline=21]{defs/attrs/opposite-keys.lua}
1272
1273 %%
1274 %
1275 %%
1276
1277 \subsubsection{Attribute “\texttt{pick}”}
1278
1279 % Das Attribut \lua{pick} sucht nach einem Wert, der keinem Schlüssel
1280 % zugeordnet ist.
1281 The attribute \lua{pick} searches for a value not assigned to a key.
1282 % Der zuerst gefundene Wert, d. h. der weiter links stehende Wert, wird
1283 % einem Schlüssel zugewiesen.
1284 The first value found, i.e. the one further to the left, is assigned to
1285 a key.
1286
1287 \InputLua[firstline=4,lastline=6]{defs/attrs/pick/dimension.lua}
1288
1289 \noindent
1290 % Es wird nur in der aktuellen Ergebnistabelle gesucht und nicht auf
1291 % anderen Ebenen in der rekursiven Datenstruktur.
1292 Only the current result table is searched, not other levels in the
1293 recursive data structure.
1294
1295 \InputLua[firstline=4,lastline=11]{defs/attrs/pick/different-levels.lua}
1296
1297 \noindent
1298 % Die Suche nach Werte wird aktiviert, wenn das Attribut \lua{pick} auf
1299 % \lua{true} gesetzt wird.
1300 The search for values is activated when the attribute \lua{pick} is set
1301 to a data type.
1302 % Mit diesen Datentypen kann nach Werten gesucht werden
1303 These data types can be used to search for values:
1304 string, number, dimension, integer, boolean, any.
1305 % Verwendet den Datentyp any um jeden beliebigen Wert zu akzeptieren.
1306 Use the data type “any” to accept any value.
1307 % Wird einem Schlüssel bereits bei der Eingabe ein Wert zugewiesen, dann
1308 % wird nicht weiter nach Werten gesucht.
1309 If a value is already assigned to a key when it is entered, then no
1310 further search for values is performed.
1311 \InputLua[firstline=4,lastline=8]{defs/attrs/pick/value-set.lua}
1312
1313 \noindent
1314 % Das Attribut \lua{pick} akzeptiert auch mehrere Datentypen, die in
1315 % einer Tabelle angegeben werden.
1316 The \lua{pick} attribute also accepts multiple data types
1317 specified in a table.
1318
1319 \InputLua[firstline=4,lastline=10]{defs/attrs/pick/multiple-data-types.lua}
1320
1321 %%
1322 %
1323 %%
1324
1325 \subsubsection{Attribute “\texttt{process}”}
1326 \label{attr-process}
1327
1328 % Das Attribut \lua{process} kann dazu verwendet werden, um eine Funktion
1329 % zu definieren, deren Rückgabewert an den Schlüssel übergeben wird.
1330 The \lua{process} attribute can be used to define a function whose
1331 return value is passed to the key.
1332 %
1333 % Beim Aufruf der Funktion werden vier Parameter übergeben:
1334 Four parameters are passed when the function is called:
1335
1336 \begin{enumerate}
1337 \item \lua{value}:
1338 % Der zum Schlüssel gehörende aktuelle Wert.
1339 The current value asssociated with the key.
1340
1341 \item \lua{input}:
1342 % Die Ergebnis-Tabelle, die vor dem Zeitpunkt geklont wurde, als mit dem
1343 % Anwenden der Definitionen begonnen wurde.
1344 The result table cloned before the time the definitions started to be
1345 applied.
1346
1347 \item \lua{result}: The table in which the final result will be saved.
1348
1349 \item \lua{unknown}: The table in which the unknown key-value pairs
1350 are stored.
1351 \end{enumerate}
1352
1353 \noindent
1354 % Das folgende Beispiel demonstriert den Parameter \lua{value}:
1355 The following example demonstrates the \lua{value} parameter:
1356 \InputLua[firstline=4,lastline=14]{defs/attrs/process/parameter-value.lua}
1357
1358 \noindent
1359 % Das folgende Beispiel demonstriert den Parameter \lua{input}:
1360 The following example demonstrates the \lua{input} parameter:
1361
1362 \InputLua[firstline=4,lastline=16]{defs/attrs/process/parameter-input.lua}
1363
1364 \noindent
1365 % Das folgende Beispiel demonstriert den Parameter \lua{result}:
1366 The following example demonstrates the \lua{result} parameter:
1367
1368 \InputLua[firstline=4,lastline=12]{defs/attrs/process/parameter-result.lua}
1369
1370 \noindent
1371 % Das folgende Beispiel demonstriert den Parameter \lua{unknown}:
1372 The following example demonstrates the \lua{unknown} parameter:
1373
1374 \InputLua[firstline=4,lastline=11]{defs/attrs/process/parameter-unknown.lua}
1375 \InputLua[firstline=15,lastline=15]{defs/attrs/process/parameter-unknown.lua}
1376
1377 %%
1378 %
1379 %%
1380
1381 \subsubsection{Attribute “\texttt{required}”}
1382
1383 % Durch das Attribut \lua{required} kann erzwungen werden, dass ein
1384 % bestimmter Schlüssel angegeben werden muss.
1385 The \lua{required} attribute can be used to enforce that a specific key
1386 must be specified.
1387 %
1388 % Im untenstehenden Beispiel wird der Schlüssel \lua{important} als
1389 % zwingend notwendig definiert.
1390 In the example below, the key \lua{important} is defined as mandatory.
1391
1392 \InputLua[firstline=4,lastline=5]{defs/attrs/required.lua}
1393
1394 \noindent
1395 % Fehlt der Schlüssel \lua{important} in der Eingabe, so tritt eine
1396 % Fehlermeldung auf.
1397 If the key \lua{important} is missing in the input, an error message
1398 occurs.
1399
1400 \InputLua[firstline=13,lastline=14]{defs/attrs/required.lua}
1401
1402 \noindent
1403 A recursive example:
1404
1405 \InputLua[firstline=18,lastline=23]{defs/attrs/required.lua}
1406
1407 \noindent
1408 % Der Schlüssel \lua{important2} auf der Ebene 2 fehlt.
1409 The \lua{important2} key on level 2 is missing.
1410
1411 \InputLua[firstline=29,lastline=30]{defs/attrs/required.lua}
1412
1413 \noindent
1414 % Der Schlüssel \lua{important1} auf der untersten Schlüssel-Ebene fehlt.
1415 The \lua{important1} key at the lowest key level is missing.
1416
1417 \InputLua[firstline=38,lastline=39]{defs/attrs/required.lua}
1418
1419 %%
1420 %
1421 %%
1422
1423 \subsubsection{Attribute “\texttt{sub_keys}”}
1424
1425 % Mit dem Attribut \lua{sub_keys} können ineinander verschachtelte
1426 % Schlüssel-Wert-Paar-Definitionen aufgebaut werden.
1427 The \lua{sub_keys} attribute can be used to build nested key-value pair
1428 definitions.
1429
1430 \InputLua[firstline=4,lastline=16]{defs/attrs/sub-keys.lua}
1431
1432 %-----------------------------------------------------------------------
1433 %
1434 %-----------------------------------------------------------------------
1435
1436
1437 \subsection{Function “\texttt{new()}”}
1438 \label{function:new}
1439
1440 % Der Aufruf der Funktion \lua{luakeys.new()} der globalen Tabelle
1441 % |luakeys| hat die gleiche Wirkung wie dieser Ausdruck:
1442 % \lua{require('luakeys')()}. Lua module von luakyes exportiert nämlich genau eine
1443 % Funktion, nämlich die new Funktion.
1444 Calling the function \lua{luakeys.new()} of the global table |luakeys| has
1445 the same effect as this expression: \lua{require('luakeys')()}.
1446 % Das Lua-Modul von |luakeys| exportiert genau eine Funktion, nämlich die
1447 % new Funktion.
1448 The Lua module from |luakeys| exports exactly one function, namely the
1449 \lua{new()} function.
1450
1451
1452 \subsection{Function “\texttt{render(value, config): string}”}
1453 \label{function:render}
1454
1455 % Die Funktion \lua{render(value)} rendert oder serialisiert einen
1456 % Lua-Wert jeglicher Art in eine Zeichenkette.
1457 The \lua{render(value)} function renders or serialises a Lua value of
1458 any kind into a string.
1459 % Diese Funktion kann verwendet werden, um die Funktion
1460 % \lua{parse(kv_string)} umzukehren.
1461 This function can be used to reverse the function \lua{parse(kv_string)}.
1462 % Die Schlüssel der resultierenden serialisierten Tabelle sind
1463 % alphabetisch sortiert.
1464 The keys of the resulting serialized table are sorted alpabetically.
1465
1466 \InputLua[firstline=4,lastline=6]{functions/render.lua}
1467
1468 \noindent
1469 % In Lua können nur Tabellen mit 1-basierten, aufeinanderfolgenden
1470 % Integer-Schlüsseln (auch bekannt als Array Tabellen) der Reihe nach
1471 % geparst werden.
1472 In Lua only tables with 1-based consecutive integer keys (a.k.a. array
1473 tables) can be parsed in order.
1474
1475 \InputLua[firstline=12,lastline=13]{functions/render.lua}
1476
1477 \subsubsection{High level configuration options}
1478
1479 \begin{description}
1480 \item[|style|]
1481 % Rendert die Eingabe als \lua{'lua'}-Tabelle oder im \lua{'tex'}-Stil,
1482 % Standard \lua{‚tex‘}.
1483 Render the input as a \lua{'lua'} table or in the \lua{'tex'} style,
1484 default \lua{'tex'}.
1485
1486 \item[|inline|]
1487 % Gibt die Eingabe in einer Zeile ohne Zeilenumbrüche wieder,
1488 % Standardwert \lua{true}.
1489 Render the input on one line without line breaks, default \lua{true}.
1490 \end{description}
1491
1492 \subsubsection{Low level configuration options}
1493
1494
1495 \begin{description}
1496 \item[|line_break|]
1497 % Das Zeichen für einen Zeilenumbruch, z. B. |\n| für die
1498 % Terminalausgabe oder |\par| für die TeX-Darstellung, Standard
1499 % \lua{''}.
1500 The character for a line break, for example, use |\n| for terminal
1501 output or |\par| for TeX rendering, default \lua{''}.
1502
1503 \item[|begin_table|]
1504
1505 % Das Anfangstrennzeichen für eine Tabelle, Standardwert |{|.
1506 The starting delimiter for a table, default |{|.
1507
1508 \item[|end_table|]
1509
1510 % Das abschließende Begrenzungszeichen für eine Tabelle, Standardwert
1511 % |}|.
1512 The final delimiter for a table, default |}|.
1513
1514 \item[|table_delimiters_first_depth|]
1515 % Ob Tabellen-Begrenzungszeichen der 1. Ebene angezeigt werden sollen.
1516 Whether table delimiters of the 1st level should be displayed.
1517 % Anstelle von \lua{'{key1,key2={value2}}'} wird
1518 % \lua{'key1,key2={value2}'} wiedergegeben, Standardwert “False".
1519 Instead of \lua{'{key1,key2={value2}}'} render
1520 \lua{'key1,key2={value2}'}, default `false`.
1521
1522 \item[|indent|]
1523 % Für die Einrückung verwendete Zeichen, standardmäßig \lua{''}.
1524 Characters used for indentation, default \lua{''}.
1525
1526 \item[|begin_key|]
1527 % Das Anfangstrennzeichen für einen Schlüssel, Standardwert \lua{‚[‘}.
1528 The starting delimiter for a key, default \lua{'['}.
1529
1530 \item[|end_key|]
1531 % Das abschließende Begrenzungszeichen für einen Schlüssel, Standardwert
1532 % \lua{‚]‘}.
1533 The final delimiter for a key, default \lua{']'}.
1534
1535 \item[|assignment|]
1536 % Das Symbol für den Zuweisungsoperator, default \lua{'='}.
1537 The symbol for the assignment operator, default \lua{'='}.
1538
1539 \item[|separator|]
1540 % Das Trennzeichen für die einzelnen Tabellenelemente, Standardwert \lua{','}.
1541 The separator for the individual table elements, default \lua{','}.
1542
1543 \item[|separator_last|]
1544 % Ein Trennzeichen nach dem letzten Element hinzufügen, Standardwert
1545 % \lua{false}.
1546 Append a separator after the last element, default \lua{false}.
1547
1548 \item[|quotation|]
1549 % Das Symbol, das eine Zeichenkette abgrenzt, Standardwert \lua{"'"}.
1550 The symbol that delimits a string, default \lua{"'"}.
1551
1552 \item[|format_key|]
1553 % Eine Funktion, die den Schlüssel formatiert.
1554 A function that formats the key.
1555
1556 \item[|format_value|]
1557 % Eine Funktion, die den Wert formatiert.
1558 A function that formats the value.
1559 \end{description}
1560
1561
1562 %%
1563 %
1564 %%
1565
1566 \subsection{Function “\texttt{debug(result, config): void}”}
1567
1568 % Die Funktion \lua{debug(result, config)} gibt auf hübsche Weise einen
1569 % Lua-Wert auf die Standardausgabe (stdout) aus.
1570 The function \lua{debug(result, config)} pretty prints a Lua value to
1571 standard output (stdout).
1572 % Es ist eine Hilfsfunktion, die zum Debuggen verwendet werden kann und um
1573 % die resultierende Lua-Tabelle der Funktion \lua{parse} zu untersuchen.
1574 It is a utility function that can be used to
1575 debug and inspect the resulting Lua table of the function \lua{parse}.
1576 % Sie müssen Ihr \TeX{}-Dokument in einer Konsole kompilieren, um die
1577 % Terminalausgabe zu sehen.
1578 You have to compile your \TeX{} document in a console to see the
1579 terminal output.
1580 % Als zweites Argument kann die Konfiguration für die eingebettete
1581 % Renderfunktion angegeben werden.
1582 The configuration for the embedded render function can be specified as
1583 the second argument (see \ref{function:render}).
1584
1585 \InputLua[firstline=4,lastline=5]{functions/debug.lua}
1586
1587 \noindent
1588 The output should look like this:
1589
1590 \begin{verbatim}
1591 {
1592 level1 = {
1593 level2 = {
1594 key = value
1595 }
1596 }
1597 }
1598 \end{verbatim}
1599
1600 %%
1601 %
1602 %%
1603
1604 \subsection{Function “\texttt{save(identifier, result): void}”}
1605
1606 The function \lua{save(identifier, result)} saves a result (a
1607 table from a previous run of \lua{parse}) under an identifier.
1608 Therefore, it is not necessary to pollute the global namespace to
1609 store results for the later usage.
1610
1611 %%
1612 %
1613 %%
1614
1615 \subsection{Function “\texttt{get(identifier): result}”}
1616
1617 The function \lua{get(identifier)} retrieves a saved result from the
1618 result store.
1619
1620 %%
1621 %
1622 %%
1623
1624 \subsection{Class “\texttt{DefinitionManager()}”}
1625
1626 % Die Klasse DefinitionManager ermöglicht es Schlüssel-Wert-Definitionen
1627 % in einem Objekt abzulegen.
1628 The |DefinitionManager| class allows you to store key-value definitions
1629 in an object.
1630 % Diese Klasse stellt eine \lua{parse}-Methode bereit, die mit diesen
1631 % Definitionen konfiguriert ist.
1632 This class provides a \lua{parse} method that is configured with these
1633 definitions.
1634 % Über die Methoden \lua{include} und \lue{exclude} können auf Basis der
1635 % gespeicherten Definitionen neue Teilmengen an Definitionen gebildet
1636 % werden.
1637 New subsets of definitions can be formed based on the saved definitions
1638 using the \lua{include} and \lua{exclude} methods.
1639
1640 \InputLua[firstline=4]{definition-manager.lua}
1641
1642 \subsection{Field “\texttt{.defs}”}
1643
1644 % Das defs-Feld kann für den Zugriff auf die Sammlung von
1645 % Schlüssel-Wert-Paar-Definitionen einer Instanz verwendet werden.
1646 The \lua{defs} field can be used to access the collection of key-value
1647 pair definitions on an instance.
1648
1649 \InputLua[firstline=7,lastline=17]{definition-manager/defs.lua}
1650
1651 \subsection{Method “\texttt{:set(key, def)}”}
1652
1653 % Die Methode \lua{DefinitionManager:set(key, def)} fügt eine
1654 % Schlüssel-Wert-Paar-Definition unter einem angegeben Schlüsselnamen
1655 % der Definitionsammlung hinzu.
1656 The \lua{DefinitionManager:set(key, def)} method adds a key-value pair
1657 definition under a specified key name to the definition collection.
1658
1659 \InputLua[firstline=13,lastline=14]{definition-manager/set.lua}
1660
1661 \subsection{Method “\texttt{:get(key): Definition}”}
1662
1663 % Die Methode \lua{DefinitionManager:get(key)} ruft anhand ihres
1664 % Schlüsselnamens ein Schlüssel-Wert-Paar-Definition ab.
1665 The \lua{DefinitionManager:get(key)} method retrieves a key-value pair
1666 definition based on its key name.
1667
1668 \InputLua[firstline=13,lastline=13]{definition-manager/get.lua}
1669
1670 \subsection{Method “\texttt{:key_names(): string[]}”}
1671
1672 % Die Methode \lua{DefinitionManager:key_names()} gibt alle
1673 % Schlüsselnamen der entsprechenden Definitionen als Array zurück.
1674 The \lua{DefinitionManager:key_names()} method returns all key names
1675 of the corresponding definitions as an array.
1676
1677 \InputLua[firstline=13,lastline=16]{definition-manager/key_names.lua}
1678
1679 \subsection{Method “\texttt{:include(key_spec, clone): Defs}”}
1680
1681 % Die Methode \lua{DefinitionManager:include(key_spec, clone)} nimmt
1682 % eine Teilmenge der Schlüssel-Wert-Definitionen in den Rückgabesammlung
1683 % an Definition auf oder, wenn \lua{key_spec} nicht angegeben ist, alle
1684 % Definitionen.
1685 The \lua{DefinitionManager:include(key_spec, clone)} method includes a
1686 subset of the key-value definitions in the return collection of
1687 definitions or, if \lua{key_spec} is not specified, all definitions.
1688
1689 \InputLua[firstline=13,lastline=28]{definition-manager/include.lua}
1690
1691 \subsection{Method “\texttt{:exclude(key_spec, clone): Defs}”}
1692
1693 % Diese Methode schließt eine Teilmenge der Schlüssel-Wert-Definitionen
1694 % aus oder gibt, wenn `key_spec` nicht angegeben ist, alle Definitionen
1695 % zurück.
1696 This method excludes a subset of the key-value definitions or, if
1697 \lua{key_spec} is not specified, returns all definitions.
1698
1699 \InputLua[firstline=13,lastline=30]{definition-manager/exclude.lua}
1700
1701 \subsection{Method “\texttt{:clone(opts): DefinitionManager}”}
1702
1703 % Diese Methode erstellt eine neue Instanz der Klasse
1704 % \lua{DefinitionManager} und fügt ihr eine tiefe Kopie der
1705 % Schlüssel-Wert-Paar-Definitionen hinzu.
1706 This method creates a new instance of the \lua{DefinitionManager} class
1707 and adds a deep copy of the key-value pair definitions to it.
1708 % Um Schlüssel-Wert-Paar-Definitionen auszuschließen oder
1709 % einzuschließen, kann eine Optionstabelle verwendet werden.
1710 An options table can be used to exclude or include key-value pair
1711 definitions.
1712 % Werden keinen Option bzw `nil` übergeben , werden alle Definitionen
1713 % geklont.
1714 If no option or \lua{nil} is passed, all definitions are cloned.
1715
1716 \InputLua[firstline=7,lastline=23]{definition-manager/clone.lua}
1717
1718 \subsection{Method “\texttt{:define(key_selection): parse}”}
1719
1720 % Die Methode \lua{DefinitionManager:define(key_selection)} erstellt
1721 % eine neue \lua{parse}-Funktion. Diese erstellte \lua{parse}-Funktion
1722 % wird mit Schlüssel-Wert-Definitionen dieser Instanz oder einer
1723 % Teilmenge konfiguriert, wenn eine Schlüsselauswahl angegeben ist.
1724 The \lua{DefinitionManager:define(key_selection)} method creates a new
1725 \lua{parse} function. This created \lua{parse} function is configured
1726 with key-value defintions of this instance or a subset, if a key
1727 selection is specified.
1728 % Diese Methode ist verwandt mit der Funktion \lua{define} (siehe
1729 % \ref{define}), jedoch mit dem Unterschied, dass die Methode
1730 % \lua{define} bereits mit den Schlüssel-Wert-Paar-Definitionen der
1731 % übergeordneten Klasse DefintionManager konfiguriert ist.
1732 This method is related to the \lua{define} function (see \ref{define}),
1733 but with the difference that the \lua{define} method is already
1734 configured with the key-value pair definitions of the parent
1735 \lua{DefintionManager} class.
1736
1737 \InputLua[firstline=13,lastline=25]{definition-manager/define.lua}
1738
1739 \subsection{Method “\texttt{:parse(kv_string, key_selection): result, unknown, raw}”}
1740
1741 % Die Methode parse übersetzt einer Schlüssel-Wert-Zeichenkette im
1742 % LaTeX/TeX-Stil in eine Lua-Tabelle unter Verwendung aller Definitionen
1743 % dieses Managers oder einer Teilmenge der Definitionen.
1744 The \lua{DefinitionManager:parse(kv_string, key_selection)} method
1745 translates a key-value string in LaTeX/TeX style into a Lua table using
1746 all definitions of this manager or a subset of the definitions.
1747 % Diese Methode ist verwandt mit der Funktion \lua{parse} (siehe
1748 % \ref{parse}), jedoch mit dem Unterschied, dass die Methode \lua{parse}
1749 % bereits mit den Schlüssel-Wert-Paar-Definitionen der übergeordneten
1750 % Klasse DefintionManager konfiguriert ist.
1751 This method is related to the \lua{parse} function (see \ref{parse}),
1752 but with the difference that the \lua{parse} method is already
1753 configured with the key-value pair definitions of the parent
1754 \lua{DefintionManager} class.
1755
1756 \InputLua[firstline=13,lastline=30]{definition-manager/parse.lua}
1757
1758 %%
1759 %
1760 %%
1761
1762 \subsection{Table “\texttt{is}”}
1763
1764 % In der Tabelle \lua{is} werden einige Funktionen zusammengefasst, die
1765 % überprüft ob eine Eingabe einem bestimmen Datentyp entspricht.
1766 In the table \lua{is} some functions are summarized, which check whether
1767 an input corresponds to a certain data type.
1768 %
1769 % Einige Funktionen akzeptieren nicht nur die entsprechenden
1770 % Lua-Datentypen, sondern auch Eingaben als Zeichenketten.
1771 Some functions accept not only the corresponding Lua data types, but also
1772 input as strings.
1773 %
1774 % Beispielsweise wird die Zeichenkette \lua{'true'} von der
1775 % \lua{is.boolean()}-Funktion als Wahrheitswert erkannt.
1776 For example, the string \lua{'true'} is recognized by the
1777 \lua{is.boolean()} function as a boolean value.
1778
1779 \subsubsection{Function “\texttt{is.boolean(value): boolean}”}
1780 \InputLua[firstline=6,lastline=23]{functions/is/boolean.lua}
1781
1782 \subsubsection{Function “\texttt{is.dimension(value): boolean}”}
1783 \InputLua[firstline=6,lastline=16]{functions/is/dimension.lua}
1784
1785 \subsubsection{Function “\texttt{is.integer(value): boolean}”}
1786 \InputLua[firstline=6,lastline=11]{functions/is/integer.lua}
1787
1788 \subsubsection{Function “\texttt{is.number(value): boolean}”}
1789 \InputLua[firstline=6,lastline=13]{functions/is/number.lua}
1790
1791 \subsubsection{Function “\texttt{is.string(value): boolean}”}
1792 \InputLua[firstline=6,lastline=12]{functions/is/string.lua}
1793
1794 \subsubsection{Function “\texttt{is.list(value): boolean}”}
1795
1796 Check if the given value is a list or an array.
1797 % Wie wir alle wissen gibt es in Lua keine Liste oder ein Array. Eine
1798 % Liste ist nichts anderes wie eine Tabelle, die als Schlüssel eine
1799 % aufsteigende Zahlenreihe verwendet.
1800 As we all know, there is no such thing as a list or array in Lua. A list
1801 is nothing more than a table that uses an ascending sequence of integers
1802 as its keys.
1803
1804 \InputLua[firstline=6,lastline=16]{functions/is/list.lua}
1805
1806 \subsubsection{Function “\texttt{is.any(value): boolean}”}
1807
1808 % Die Funktion \lua{is.any(value)} gibt immer wahr zurück und
1809 % akzeptiert deshalb jeden Datentyp.
1810 The function \lua{is.any(value)} always returns \lua{true} and
1811 therefore accepts any data type.
1812
1813 %%
1814 %
1815 %%
1816
1817 \subsection{Table “\texttt{utils}”}
1818
1819 % In der Tabelle \lua{utils} sind einige Hilfsfunktionen gebündelt.
1820 The \lua{utils} table bundles some auxiliary functions.
1821
1822 \InputLua[firstline=3,lastline=35]{utils/all.lua}
1823
1824 %%
1825 %
1826 %%
1827
1828 \subsubsection{Function “\texttt{utils.merge_tables(target, source, overwrite): table}”}
1829
1830 % Die Funktion \lua{merge_tables} führt zwei Tabellen in die erste
1831 % angegebene Tabelle zusammen. Sie kopiert Schlüssel aus der
1832 % `source` Tabelle in die `target`-Tabelle. Sie gibt die geänderte
1833 % Zieltabelle zurück.
1834 The function \lua{merge_tables} merges two tables into the first
1835 specified table. It copies keys from the `source` table into the
1836 `target` table. It returns the target table.
1837
1838 % Wird der Parameter \lua{overwrite} auf wahr gesetzten, so werden Werte
1839 % in der Zieltabelle überschrieben
1840 If the \lua{overwrite} parameter is set to \lua{true}, values in the
1841 target table are overwritten.
1842
1843 \InputLua[firstline=4,lastline=8]{utils/merge-tables.lua}
1844
1845 \noindent
1846 % Geben sie dem Parameter \lua{overwrite} den Wert \lua{false}, um Werte
1847 % in der Zieltabelle zu überschreiben.
1848 Give the parameter \lua{overwrite} the value \lua{false} to overwrite
1849 values in the target table.
1850
1851 \InputLua[firstline=14,lastline=18]{utils/merge-tables.lua}
1852
1853 %%
1854 %
1855 %%
1856
1857 \subsection{Table “\texttt{version}”}
1858
1859 % Das luakeys Projekt verwendet semantic versioning
1860 The luakeys project uses semantic versioning.
1861 % Die drei Versionenzahlen des Semantic Versioning Schemas werden in
1862 % einer Tabelle in der Reihenfolge MAJOR, MINOR, PATCH als Ganzzahlen
1863 % abgelegt.
1864 The three version numbers of the semantic versioning scheme are stored
1865 in a table as integers in the order MAJOR, MINOR, PATCH.
1866 % Mit Hilfe dieser Tabelle kann überprüft werden, ob die richtige
1867 % Version installiert ist.
1868 This table can be used to check whether the correct version is
1869 installed.
1870
1871 \InputLua[firstline=4,lastline=10]{version.lua}
1872
1873 %%
1874 %
1875 %%
1876
1877 \subsection{Table “\texttt{error_messages}”}
1878
1879 \InputLua[firstline=4,lastline=17]{error-messages.lua}
1880
1881 \begin{description}
1882 \directlua{luakeys.print_error_messages()}
1883 \end{description}
1884
1885 %-----------------------------------------------------------------------
1886 %
1887 %-----------------------------------------------------------------------
1888
1889 \section{Syntax of the recognized key-value format}
1890
1891 %%
1892 %
1893 %%
1894
1895 \subsection{An attempt to put the syntax into words}
1896
1897 A key-value pair is definied by an equal sign (\texttt{key=value}).
1898 Several key-value pairs or keys without values (naked keys) are lined up
1899 with commas (\texttt{key=value,naked}) and build a key-value list. Curly
1900 brackets can be used to create a recursive data structure of nested
1901 key-value lists (\texttt{level1=\{level2=\{key=value,naked\}\}}).
1902
1903 %%
1904 %
1905 %%
1906
1907 \subsection{An (incomplete) attempt to put the syntax into the Extended Backus-Naur Form}
1908
1909 \begin{grammar}
1910 <list> ::= \{ <list-item> \}
1911
1912 <list-container> ::= `{' <list> `}'
1913
1914 <list-item> ::= ( <list-container> | <key-value-pair> | <value> ) [ `,' ]
1915
1916 <key-value-pair> ::= <value> `=' ( <list-container> | <value> )
1917
1918 <value> ::= <boolean>
1919 \alt <dimension>
1920 \alt <number>
1921 \alt <string-quoted>
1922 \alt <string-unquoted>
1923
1924 <dimension> ::= <number> <unit>
1925
1926 <number> ::= <sign> ( <integer> [ <fractional> ] | <fractional> )
1927
1928 <fractional> ::= `.' <integer>
1929
1930 <sign> ::= `-' | `+'
1931
1932 <integer> ::= <digit> \{ <digit> \}
1933
1934 <digit> ::= `0' | `1' | `2' | `3' | `4' | `5' | `6' | `7' | `8' | `9'
1935
1936 <unit> ::= `bp' | `BP'
1937 \alt `cc' | `CC'
1938 \alt `cm' | `CM'
1939 \alt `dd' | `DD'
1940 \alt `em' | `EM'
1941 \alt `ex' | `EX'
1942 \alt `in' | `IN'
1943 \alt `mm' | `MM'
1944 \alt `mu' | `MU'
1945 \alt `nc' | `NC'
1946 \alt `nd' | `ND'
1947 \alt `pc' | `PC'
1948 \alt `pt' | `PT'
1949 \alt `px' | `PX'
1950 \alt `sp' | `SP'
1951
1952 <boolean> ::= <boolean-true> | <boolean-false>
1953
1954 <boolean-true> ::= `true' | `TRUE' | `True'
1955
1956 <boolean-false> ::= `false' | `FALSE' | `False'
1957 \end{grammar}
1958
1959 ... to be continued
1960
1961 %%
1962 %
1963 %%
1964
1965 \subsection{Recognized data types}
1966
1967 \subsubsection{boolean}
1968
1969 The strings \texttt{true}, \texttt{TRUE} and \texttt{True} are converted
1970 into Lua’s boolean type \lua{true}, the strings \texttt{false},
1971 \texttt{FALSE} and \texttt{False} into \lua{false}.
1972
1973 \begin{multicols}{2}
1974 \InputLatex[firstline=5,lastline=12]{luakeysdebug/boolean-latex.tex}
1975
1976 \columnbreak
1977
1978 \begin{minted}{lua}
1979 {
1980 ['lower case true'] = true,
1981 ['upper case true'] = true,
1982 ['title case true'] = true,
1983 ['lower case false'] = false,
1984 ['upper case false'] = false
1985 ['title case false'] = false,
1986 }
1987 \end{minted}
1988 \end{multicols}
1989
1990 %%
1991 %
1992 %%
1993
1994 \subsubsection{number}
1995
1996 \begin{multicols}{2}
1997 \InputLatex[firstline=5,lastline=13]{luakeysdebug/number-latex.tex}
1998
1999 \columnbreak
2000
2001 \begin{minted}{lua}
2002 {
2003 ['num0'] = 42,
2004 ['num1'] = 42,
2005 ['num2'] = -42,
2006 ['num3'] = 4.2,
2007 ['num4'] = 0.42,
2008 ['num5'] = 0.42,
2009 ['num6'] = '0 . 42', -- string
2010 }
2011 \end{minted}
2012 \end{multicols}
2013
2014 %%
2015 %
2016 %%
2017
2018 \subsubsection{dimension}
2019
2020 % Luakeys versucht alle Einheiten zu erkennen, die in der TeX-Welt
2021 % verwendet werden.
2022 |luakeys| tries to recognize all units used in the \TeX{} world.
2023 %
2024 % Nach dem Lua\TeX-Quellcode .
2025 According to the Lua\TeX{} source code
2026 (\href{https://github.com/TeX-Live/luatex/blob/51db1985f5500dafd2393aa2e403fefa57d3cb76/source/texk/web2c/luatexdir/lua/ltexlib.c#L434-L625}
2027 {source/texk/web2c/luatexdir/lua/ltexlib.c})
2028 %
2029 % und nach dem Dimensionen-Modul der lulibs-Bibliothek
2030 and the dimension module of the lualibs library
2031 (\href{https://raw.githubusercontent.com/latex3/lualibs/master/lualibs-util-dim.lua}
2032 {lualibs-util-dim.lua}),
2033 %
2034 % müssten alle Einheiten erkannt werden
2035 all units should be recognized.
2036 \begin{multicols}{3}
2037 \tiny
2038 \begin{center}
2039 \begin{tabular}{rl}
2040 % \textbf{Unit name}
2041 & \textbf{Description} \\\hline
2042 bp & big point \\
2043 cc & cicero \\
2044 cm & centimeter \\
2045 dd & didot \\
2046 em & horizontal measure of \emph{M} \\
2047 ex & vertical measure of \emph{x} \\
2048 in & inch \\
2049 mm & milimeter \\
2050 mu & math unit \\
2051 nc & new cicero \\
2052 nd & new didot \\
2053 pc & pica \\
2054 pt & point \\
2055 px & x height current font \\
2056 sp & scaledpoint \\
2057 \end{tabular}
2058 \end{center}
2059
2060 \columnbreak
2061
2062 \InputLatex[firstline=5,lastline=21]{luakeysdebug/dimension/all-latex.tex}
2063
2064 \columnbreak
2065
2066 \begin{minted}{lua}
2067 {
2068 ['bp'] = 65781,
2069 ['cc'] = 841489,
2070 ['cm'] = 1864679,
2071 ['dd'] = 70124,
2072 ['em'] = 655360,
2073 ['ex'] = 282460,
2074 ['in'] = 4736286,
2075 ['mm'] = 186467,
2076 ['mu'] = 65536,
2077 ['nc'] = 839105,
2078 ['nd'] = 69925,
2079 ['pc'] = 786432,
2080 ['pt'] = 65536,
2081 ['px'] = 65781,
2082 ['sp'] = 1,
2083 }
2084 \end{minted}
2085 \end{multicols}
2086
2087 \noindent
2088 % Im nächsten Beispiel werden die unterschiedlichen Notationsformen der
2089 % Dimensionen illustriert.
2090 The next example illustrates the different notations of the dimensions.
2091
2092 \begin{multicols}{2}
2093 \InputLatex[firstline=5,lastline=12]{luakeysdebug/dimension/notations-latex.tex}
2094
2095 \columnbreak
2096
2097 \begin{minted}{lua}
2098 {
2099 ['upper'] = 1864679,
2100 ['lower'] = 1864679,
2101 ['space'] = 1864679,
2102 ['plus'] = 1864679,
2103 ['minus'] = -1864679,
2104 ['nodim'] = '1 c m', -- string
2105 }
2106 \end{minted}
2107 \end{multicols}
2108
2109 %%
2110 %
2111 %%
2112
2113 \subsubsection{string}
2114
2115 % Es gibt zwei Möglichkeiten Zeichenketten anzugeben:
2116 There are two ways to specify strings:
2117 %
2118 % Mit oder ohne doppelte Anführungszeichen.
2119 With or without double quotes.
2120 %
2121 % Wenn der Text Kommas, geschweifte Klammern oder Gleichheitszeichen
2122 % enthalten soll, müssen doppelte Anführungszeichen verwendet werden.
2123 If the text have to contain commas, curly braces or equal signs, then
2124 double quotes must be used.
2125
2126 \InputLua[firstline=4,lastline=17]{data-types/string.lua}
2127
2128 \subsubsection{Naked keys}
2129
2130 % Nackte Schlüssel sind Schlüssel ohne Wert.
2131 Naked keys are keys without a value.
2132 %
2133 % Mit der Option \lua{naked_as_value} können sie als Werte in ein Feld
2134 % übernommen werden.
2135 Using the option \lua{naked_as_value} they can be converted into values
2136 and stored into an array.
2137 %
2138 % In Lua ist ein Feld eine Tabelle mit numerischen Indizes (der erste
2139 % Index ist 1).
2140 In Lua an array is a table with numeric indexes (The first index is 1).
2141
2142 \InputLatex[firstline=5,lastline=12]{luakeysdebug/naked-keys-latex.tex}
2143
2144 \noindent
2145 % Alle erkannten Datentypen können als eigenständige Werte verwendet
2146 % werden.
2147 All recognized data types can be used as standalone values.
2148
2149 \InputLatex[firstline=14,lastline=19]{luakeysdebug/naked-keys-latex.tex}
2150
2151 %-----------------------------------------------------------------------
2152 %
2153 %-----------------------------------------------------------------------
2154
2155 \clearpage
2156
2157 \section{Examples}
2158
2159 %%
2160 %
2161 %%
2162
2163 \subsection{Extend and modify keys of existing macros}
2164
2165 Extend the includegraphics macro with a new key named \latex{caption}
2166 and change the accepted values of the \latex{width} key. A number
2167 between 0 and 1 is allowed and converted into
2168 \latex{width=0.5\linewidth}
2169
2170 \InputLua{extend-includegraphics/extend-keys.lua}
2171 \InputLatex{extend-includegraphics/extend-keys-latex.tex}
2172
2173 %%
2174 %
2175 %%
2176
2177 \subsection{Process document class options}
2178
2179 % Auf die Optionen einer \LaTeX{} Dokumentenklasse kann über das Macro
2180 % \latex{\LuakeysGetClassOptions} zu gegriffen werden.
2181 The options of a \LaTeX{} document class can be accessed via the
2182 \latex{\LuakeysGetClassOptions} macro.
2183 %
2184 % \latex{\LuakeysGetClassOptions} ist ein anderer Name für
2185 \latex{\LuakeysGetClassOptions} is an alias for
2186
2187 \begin{center}
2188 \latex{\luaescapestring{\@raw@classoptionslist}}.
2189 \end{center}
2190
2191 \InputLatex{class-options/test-class.cls}
2192 \InputLatex{class-options/use-test-class-latex.tex}
2193
2194 %%
2195 %
2196 %%
2197
2198 \subsection{Process package options}
2199
2200 \noindent
2201 % Auf die Optionen eines \LaTeX{}-Pakets kann über das Macro
2202 % \latex{\LuakeysGetPackageOptions} zu gegriffen werden.
2203 The options of a \LaTeX{} package can be accessed via the
2204 \latex{\LuakeysGetPackageOptions} macro.
2205 % \latex{\LuakeysGetPackageOptions} ist ein anderer Name für
2206 \latex{\LuakeysGetPackageOptions} is an alias for
2207
2208 \begin{center}
2209 \latex{\luaescapestring{\@ptionlist{\@currname.\@currext}}}.
2210 \end{center}
2211
2212 \InputLatex{package-options/test-package.sty}
2213 \InputLatex{package-options/use-test-package-latex.tex}
2214
2215 %-----------------------------------------------------------------------
2216 %
2217 %-----------------------------------------------------------------------
2218
2219 \clearpage
2220
2221 \section{Debug packages}
2222
2223 Two small debug packages are included in |luakeys|. One debug package
2224 can be used in \LaTeX{} (luakeys-debug.sty) and one can be used in plain
2225 \TeX{} (luakeys-debug.tex). Both packages provide only one command:
2226 |\luakeysdebug{kv-string}|
2227
2228 \begin{minted}{latex}
2229 \luakeysdebug{one,two,three}
2230 \end{minted}
2231
2232 \noindent
2233 Then the following output should appear in the document:
2234 \bigskip
2235
2236 \luakeysdebug{one,two,three}
2237
2238
2239
2240
2241 %%
2242 %
2243 %%
2244
2245 \subsection{For plain \TeX: luakeys-debug.tex}
2246
2247 An example of how to use the command in plain \TeX:
2248
2249 \begin{minted}{latex}
2250 \input luakeys-debug.tex
2251 \luakeysdebug{one,two,three}
2252 \bye
2253 \end{minted}
2254
2255 %%
2256 %
2257 %%
2258
2259 \subsection{For \LaTeX: luakeys-debug.sty}
2260
2261 An example of how to use the command in \LaTeX:
2262
2263 \begin{minted}{latex}
2264 \documentclass{article}
2265 \usepackage{luakeys-debug}
2266 \begin{document}
2267 \luakeysdebug[
2268 unpack=false,
2269 convert dimensions=false
2270 ]{one,two,three}
2271 \end{document}
2272 \end{minted}
2273
2274 \section{Activity diagramm of the parsing process}
2275
2276 \begin{center}
2277 \includegraphics[width=0.8\linewidth]{Activity-Diagramm.eps}
2278 \end{center}
2279
2280 %-----------------------------------------------------------------------
2281 %
2282 %-----------------------------------------------------------------------
2283
2284 \clearpage
2285
2286 \section{Implementation}
2287
2288 The source code is hosted on
2289 \href{https://github.com/Josef-Friedrich/luakeys}{Github}. The
2290 following links will take you to the individual files:
2291
2292 \begin{itemize}
2293 \item \href{https://github.com/Josef-Friedrich/luakeys/blob/main/luakeys.lua}{luakeys.lua}
2294
2295 \item \href{https://github.com/Josef-Friedrich/luakeys/blob/main/luakeys.tex}{luakeys.tex}
2296
2297 \item \href{https://github.com/Josef-Friedrich/luakeys/blob/main/luakeys.sty}{luakeys.sty}
2298
2299 \item \href{https://github.com/Josef-Friedrich/luakeys/blob/main/luakeys-debug.tex}{luakeys-debug.tex}
2300
2301 \item \href{https://github.com/Josef-Friedrich/luakeys/blob/main/luakeys-debug.sty}{luakeys-debug.sty}
2302 \end{itemize}
2303
2304 \pagebreak
2305 \PrintIndex
2306 \end{document}