diff options
Diffstat (limited to 'macros/luatex/generic/luakeys/luakeys-doc.tex')
-rw-r--r-- | macros/luatex/generic/luakeys/luakeys-doc.tex | 726 |
1 files changed, 524 insertions, 202 deletions
diff --git a/macros/luatex/generic/luakeys/luakeys-doc.tex b/macros/luatex/generic/luakeys/luakeys-doc.tex index bc9a55f632..dd6fcc0973 100644 --- a/macros/luatex/generic/luakeys/luakeys-doc.tex +++ b/macros/luatex/generic/luakeys/luakeys-doc.tex @@ -1,12 +1,12 @@ \documentclass{ltxdoc} -\usepackage[hidelinks]{hyperref} \EnableCrossrefs \CodelineIndex \RecordChanges \usepackage{mdframed} \usepackage{minted} +\usepackage{luakeys} \usepackage{luakeys-debug} \usepackage{multicol} \usepackage{luacode} @@ -22,19 +22,30 @@ \def\lua#1{\mintinline{lua}|#1|} \def\latex#1{\mintinline{latex}|#1|} -\NewDocumentCommand { \InputLatexExample } { O{} m } { +\NewDocumentCommand { \InputLatex } { O{} m } { \begin{mdframed} \inputminted[linenos=false,#1]{latex}{examples/#2} \end{mdframed} } -\NewDocumentCommand { \InputLuaExample } { O{} m } { +\NewDocumentCommand { \InputLua } { O{} m } { \begin{mdframed} \inputminted[linenos=false,#1]{lua}{examples/#2} \end{mdframed} } \catcode`_=12 +\def\DefaultOpt#1{% + \texttt{\directlua{ + tex.print(luakeys.print_default('opts', '#1')) + }}% +} + +\def\DefaultOptDescription#1{ +\noindent +The default value of the option “\texttt{#1}” is: +\DefaultOpt{#1}. +} \begin{document} @@ -44,15 +55,16 @@ \author{% Josef Friedrich\\% \url{josef@friedrich.rocks}\\% - \href{https://github.com/Josef-Friedrich/luakeys}{github.com/Josef-Friedrich/luakeys}% + \href{https://github.com/Josef-Friedrich/luakeys} + {github.com/Josef-Friedrich/luakeys}% } -\date{v0.6 from 2022/06/09} +\date{0.7.0 from 2022/07/06} \maketitle \vfill -\InputLuaExample[firstline=4,lastline=7]{first-page.lua} +\InputLua[firstline=4,lastline=7]{first-page.lua} \noindent Result: @@ -83,6 +95,7 @@ Result: \newpage +% \section{Einführung} \section{Introduction} \noindent @@ -112,20 +125,62 @@ Since |luakeys| uses \href{http://www.inf.puc-rio.br/~roberto/lpeg/}{LPeg}, the parsing mechanism should be pretty robust. +% Der Artikel TUGboat +% \href{http://www.tug.org/tugboat/tb30-1/tb94wright-keyval.pdf} +% {“Implementing key–value input: An introduction” (Volume 30 (2009), No. +% 1)} von \emph{Joseph Wright} und \emph{Christian Feuersänger} gibt einen +% einen guten Überblick über die verfügbaren Key-Value-Pakete. The TUGboat article \href{http://www.tug.org/tugboat/tb30-1/tb94wright-keyval.pdf} -{“Implementing key–value input: An introduction” (Volume 30 (2009), No. 1)} -by \emph{Joseph Wright} and \emph{Christian Feuersänger} gives a good -overview of the available key-value packages. - +{“Implementing key–value input: An introduction” (Volume 30 (2009), No. +1)} by \emph{Joseph Wright} and \emph{Christian Feuersänger} gives a +good overview of the available key-value packages. + +% Dieses Paket wäre ohne den Artikel +% \href{https://tug.org/TUGboat/tb40-2/tb125menke-lpeg.pdf} +% {"Parsing complex data formats in LuaTEX with LPEG" (Volume 40 (2019), +% No. 2)} nicht möglich gewesen. This package would not be possible without the article \href{https://tug.org/TUGboat/tb40-2/tb125menke-lpeg.pdf} -{“Parsing complex data formats in LuaTEX with LPEG” (Volume 40 (2019), No. 2)}. +{“Parsing complex data formats in LuaTEX with LPEG” (Volume 40 (2019), +No. 2)}. + +\subsection{Pros of \texttt{luakeys}} + +\begin{itemize} +% \item Schlüssel-Wert-Paare können unabhängig vom Makro-Paket (latex or +% context) analysiert werden. +\item Key-value pairs can be parsed independently of the macro +collection (\LaTeX{} or Con\TeX{}t). + +% \item Sogar in Plain LuaTex können Schlüssel analysiert werden +\item Even in plain Lua\TeX{} keys can be parsed. + +% \item |luakeys| kann mit ineinander verschachtelten listen an +% Schlüssel-Wert-Paaren umgehen, d. h. es kann mit einer rekursiven +% Datenstruktur an Schlüssel umgehen. +\item |luakeys| can handle nested lists of key-value pairs, i.e. it can +handle a recursive data structure of keys. + +% \item Schlüssel müssen nicht, aber können definiert werden. +\item Keys do not have to be defined, but can they can be defined. +\end{itemize} + +\subsection{Cons of \texttt{luakeys}} + +\begin{itemize} +% \item Das Packet funktioniert nur in der Verbindung mit Lua\TeX. +\item The package works only in combination with Lua\TeX. + +% \item Du musst zwei Sprachen beherrschen: \TeX{} und Lua. +\item You need to know two languages: \TeX{} and Lua. +\end{itemize} %----------------------------------------------------------------------- % %----------------------------------------------------------------------- +% \section{Wie das Paket geladen wird} \section{How the package is loaded} %% @@ -142,7 +197,7 @@ The core functionality of this package is realized in Lua. So you can use |luakeys| even without using the wrapper files |luakeys.sty| and |luakeys.tex|. -\InputLatexExample{loading/lua.tex} +\InputLatex{loading/lua.tex} %% % @@ -155,8 +210,8 @@ So you can use |luakeys| even without using the wrapper files For example, the MiK\TeX{} package manager downloads packages only when needed. % -% Es wurde berichtet, dass dieser automatische Download nur mit Hilfe der -% Hüll-Dateien funktioniert. +% Es wurde berichtet, dass dieser automatische Download nur mit Hilfe +% der Hüll-Dateien funktioniert. It has been reported that this automatic download only works with this wrapper files. % @@ -164,7 +219,7 @@ wrapper files. % “\latex{\usepackage{luakeys}} ”Ausschau. Probably MiK\TeX{} is searching for an occurrence of the \LaTeX{} macro “\latex{\usepackage{luakeys}}”. - +% % Die mitgelieferte Lua\LaTeX{}-Datei ist recht klein: The supplied Lua\LaTeX{} file is quite small: @@ -175,38 +230,62 @@ The supplied Lua\LaTeX{} file is quite small: \end{minted} \noindent +% Es lädt das Lua-Modul in die globale Variable \texttt{luakeys}. It loads the Lua module into the global variable \texttt{luakeys}. -\InputLatexExample{loading/latex.tex} +\InputLatex{loading/tex-latex.tex} %% % %% +% \subsection{Verwendung des Plain-Lua\TeX{}-Hüllpakets +% \texttt{luakeys.tex}} \subsection{Using the plain Lua\TeX{} wrapper \texttt{luakeys.tex}} -Even smaller is the file \texttt{luakeys.tex}. It consists of only one -line: +% Noch kleiner ist die Datei \texttt{luakeys.tex}. +Even smaller is the file \texttt{luakeys.tex}. +% +% Sie besteht aus nur einer Zeile: +It consists of only one line: \begin{minted}{latex} \directlua{luakeys = require('luakeys')} \end{minted} \noindent +% Es macht dasselbe wie das Lua\LaTeX{}-Hüllpacket und lädt das +% Lua-Modul \texttt{luakeys.lua} in die globale Variable +% \texttt{luakeys}. It does the same as the Lua\LaTeX{} wrapper and loads the Lua module \texttt{luakeys.lua} into the global variable \texttt{luakeys}. -\InputLatexExample{loading/tex.tex} +\InputLatex{loading/tex-plain.tex} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Lua interface / API} -To learn more about the individual functions (local functions), please +% Das Lua-Modul exportiert diese Funktionen und Tabellen: +The Lua module exports this functions and tables: + +\InputLua[firstline=3,lastline=13]{export.lua} + +% Diese Dokumentation stellt nur die öffentlichen Funktionen und +% Tabellen vor. +This documentation presents only the public functions and tables. +% +% Um mehr über die privaten, nicht exportierten Funktionen zu erfahren, +% lesen Sie bitte die +% \href{https://josef-friedrich.github.io/luakeys/}{Quellcode +% Dokumentation}, die mit +% \href{http://stevedonovan.github.io/ldoc/}{LDoc} erstellt wurde. +To learn more about the private, not exported functions, please read the \href{https://josef-friedrich.github.io/luakeys/}{source code documentation}, which was created with -\href{http://stevedonovan.github.io/ldoc/}{LDoc}. The Lua module exports -this functions and tables: - -\InputLuaExample[firstline=3,lastline=12]{export.lua} +\href{http://stevedonovan.github.io/ldoc/}{LDoc}. \subsection{Lua indentifier names} @@ -219,7 +298,8 @@ hopefully unambiguous and familiar to external readers. \begin{tabular}{lll} Abbreviation & spelled out & Example \\\hline \lua{kv_string} & Key-value string & \lua{'key=value'} \\ -\lua{opts} & Options (for the parse function) & \lua{ { no_error = false } } \\ +\lua{opts} & Options (for the parse function) & +\lua{ { no_error = false } } \\ \lua{defs} & Definitions \\ \lua{def} & Definition \\ \lua{attr} & Attributes (of a definition) \\ @@ -233,7 +313,8 @@ These unabbreviated variable names are commonly used. \begin{tabular}{ll} \lua{result} & -% Das Endergebnis aller einzelnen Übersetzungs- und Normalisierungsschritte +% Das Endergebnis aller einzelnen Übersetzungs- und +% Normalisierungsschritte The final result of all individual parsing and normalization steps. \\ \lua{unknown} & @@ -250,54 +331,41 @@ The raw result of the Lpeg grammar parser. \\ % %% -\subsection{Function \texttt{parse(kv_string, opts): result, unknown, raw}} +\subsection{Function “\texttt{parse(kv_string, opts): result, unknown, +raw}”} \label{parse} % Die Function parse ist die wichtigste Funktion des Pakets. The function \lua{parse(kv_string, opts)} is the most important function of the package. +% +% % Sie konvertiert eine Schlüssel-Wert-Zeichenkette in eine Lua Tabelle. It converts a key-value string into a Lua table. -\begin{minted}{latex} -\newcommand{\mykeyvalcmd}[2][]{ - \directlua{ - result = luakeys.parse('#1') - luakeys.debug(result) - } - #2 -} -\mykeyvalcmd[one=1]{test} -\end{minted} +\InputLatex{functions/parse/tex-latex.tex} \noindent In plain \TeX: -\begin{minted}{latex} -\def\mykeyvalcommand#1{ - \directlua{ - result = luakeys.parse('#1') - luakeys.debug(result) - } -} -\mykeyvalcmd{one=1} -\end{minted} +\InputLatex{functions/parse/tex-plain.tex} \subsection{Options to configure the \texttt{parse} function} \noindent The \lua{parse} function can be called with an options table. This -options are supported: +options are supported: \catcode`_=12 +\directlua{luakeys.print_names('opts')} -\InputLuaExample[firstline=5,lastline=69]{opts/all-opts.lua} +\InputLua[firstline=5,lastline=69]{opts/all-opts.lua} \noindent The options can also be set globally using the exported table |opts|: -\InputLuaExample[firstline=4,lastline=4]{opts/exported-default-opts.lua} +\InputLua[firstline=4,lastline=4]{opts/exported-default-opts.lua} -\InputLuaExample[firstline=10,lastline=11]{opts/exported-default-opts.lua} +\InputLua[firstline=10,lastline=11]{opts/exported-default-opts.lua} %% % @@ -305,45 +373,49 @@ The options can also be set globally using the exported table \subsubsection{Option “\texttt{convert_dimensions}”} +% Wenn Sie die Option \lua{convert_dimensions} auf \lua{true} setzen, +% erkennt |luakeys| die \TeX{}-Dimensionen und konvertiert sie mit Hilfe +% der die Funktion \lua{tex.sp(dim)} in scaled points. If you set the option \lua{convert_dimensions} to \lua{true}, |luakeys| detects the \TeX{} dimensions and converts them into scaled points using the function \lua{tex.sp(dim)}. -\InputLuaExample[firstline=4,lastline=7]{opts/convert-dimensions.lua} +\InputLua[firstline=4,lastline=7]{opts/convert-dimensions/true.lua} \noindent +% Standardmäßig werden die Dimensionen nicht in skalierte Punkte +% umgewandelt. By default the dimensions are not converted into scaled points. -\InputLuaExample[firstline=13,lastline=18]{opts/convert-dimensions.lua} +\InputLua[firstline=4,lastline=9]{opts/convert-dimensions/false.lua} \noindent -If you want to convert a scale point into a unit string you can use the module -\href{https://raw.githubusercontent.com/latex3/lualibs/master/lualibs-util-dim.lua}{lualibs-util-dim.lua}. +% Wenn Sie eine skalierte Punktzahl in einen Dimensionszeichenketten +% umwandeln möchten, können Sie das Modul +If you want to convert a scaled points number into a dimension string +you can use the module +\href{https://raw.githubusercontent.com/latex3/lualibs/master/lualibs-util-dim.lua} +{lualibs-util-dim.lua}. \begin{minted}{lua} require('lualibs') tex.print(number.todimen(tex.sp('1cm'), 'cm', '%0.0F%s')) \end{minted} +\DefaultOptDescription{convert_dimensions} + %% % %% \subsubsection{Option “\texttt{debug}”} -If the option “debug” is set to ture, the result table is printed to the -console. +% Wenn die Option \lua{debug} auf true gesetzt ist, wird die +% Ergebnistabelle in der Konsole ausgegeben. +If the option \lua{debug} is set to ture, the result table is printed to +the console. -\begin{minted}{latex} -\documentclass{article} -\usepackage{luakeys} -\begin{document} -\directlua{ - luakeys.parse('one,two,three', { debug = true }) -} -debug -\end{document} -\end{minted} +\InputLatex{opts/debug-latex.tex} \begin{verbatim} This is LuaHBTeX, Version 1.15.0 (TeX Live 2022) @@ -361,6 +433,8 @@ local/texlive/2022/texmf-var/fonts/map/pdftex/updmap/pdftex.map}] (./debug.aux) Transcript written on debug.log. \end{verbatim} +\DefaultOptDescription{debug} + %% % %% @@ -375,13 +449,15 @@ The option \lua{default} can be used to specify which value naked keys (keys without a value) get. This option has no influence on keys with values. -\InputLuaExample[firstline=4,lastline=5]{opts/default.lua} +\InputLua[firstline=4,lastline=5]{opts/default.lua} \noindent % Standardmäßig erhalten nackte Schlüssel den Wert \lua{true}. By default, naked keys get the value \lua{true}. -\InputLuaExample[firstline=11,lastline=12]{opts/default.lua} +\InputLua[firstline=11,lastline=12]{opts/default.lua} + +\DefaultOptDescription{default} %% % @@ -402,7 +478,9 @@ The result table is merged into the defaults table. Values in the defaults table are overwritten by values in the result table. -\InputLuaExample[firstline=4,lastline=7]{opts/defaults.lua} +\InputLua[firstline=4,lastline=7]{opts/defaults.lua} + +\DefaultOptDescription{defaults} %% % @@ -421,13 +499,15 @@ If you use the \lua{defs} option, you don't need to call the % Anstatt Instead of ... -\InputLuaExample[firstline=4,lastline=5]{opts/defs.lua} +\InputLua[firstline=4,lastline=5]{opts/defs.lua} \noindent % können wir schreiben .. we can write ... -\InputLuaExample[firstline=11,lastline=13]{opts/defs.lua} +\InputLua[firstline=11,lastline=13]{opts/defs.lua} + +\DefaultOptDescription{defs} %% % @@ -438,17 +518,19 @@ we can write ... \begin{description} \item[lower] \strut -\InputLuaExample[firstline=4,lastline=5]{opts/format-keys.lua} +\InputLua[firstline=4,lastline=5]{opts/format-keys.lua} \item[snake] \strut -\InputLuaExample[firstline=11,lastline=12]{opts/format-keys.lua} +\InputLua[firstline=11,lastline=12]{opts/format-keys.lua} \item[upper] \strut -\InputLuaExample[firstline=18,lastline=19]{opts/format-keys.lua} +\InputLua[firstline=18,lastline=19]{opts/format-keys.lua} \end{description} +\DefaultOptDescription{format_keys} + %% % %% @@ -463,8 +545,8 @@ processing of the \lua{parse} function. % Die Funktionen sind in der Verarbeitungsreihenfolge aufgelistet. The functions are listed in processing order. % -% \lua{*_before_opts} bedeutet, dass die Hooks nach der LPeg Syntaxanalyse -% und vor dem Anwenden der Optionen ausgeführt +% \lua{*_before_opts} bedeutet, dass die Hooks nach der LPeg +% Syntaxanalyse und vor dem Anwenden der Optionen ausgeführt \lua{*_before_opts} means that the hooks are executed after the LPeg syntax analysis and before the options are applied. % @@ -504,7 +586,7 @@ definitions. The \lua{kv_string} hook is called as the first of the hook functions before the LPeg syntax parser is executed. -\InputLuaExample[firstline=4,lastline=11]{hooks/kv-string.lua} +\InputLua[firstline=4,lastline=11]{hooks/kv-string.lua} \paragraph{\texttt{keys_*}} @@ -515,12 +597,12 @@ result table. % Die Hook-Funktion muss zwei Werte zurückgeben: \lua{key, value} The hook function must return two values: \lua{key, value}. % -% Das folgende Beispiel gibt \lua{key} und \lua{value} unverändert zurück, -% sodass die Ergebnistabelle nicht verändert wird. +% Das folgende Beispiel gibt \lua{key} und \lua{value} unverändert +% zurück, sodass die Ergebnistabelle nicht verändert wird. The following example returns \lua{key} and \lua{value} unchanged, so the result table is not changed. -\InputLuaExample[firstline=4,lastline=11]{hooks/keys-unchanged.lua} +\InputLua[firstline=4,lastline=11]{hooks/keys-unchanged.lua} \noindent % Das nächste Beispiel demonstriert den dritten Parameter \lua{depth} @@ -528,7 +610,7 @@ the result table is not changed. The next example demonstrates the third parameter \lua{depth} of the hook function. -\InputLuaExample[firstline=4,lastline=16]{hooks/keys-depth.lua} +\InputLua[firstline=4,lastline=16]{hooks/keys-depth.lua} \paragraph{\texttt{result_*}} @@ -549,12 +631,14 @@ as a parameter. With the help of the option \lua{naked_as_value}, naked keys are not given a default value, but are stored as values in a Lua table. -\InputLuaExample[firstline=4,lastline=5]{opts/naked-as-value.lua} +\InputLua[firstline=4,lastline=5]{opts/naked-as-value.lua} \noindent If we set the option \lua{naked_as_value} to \lua{true}: -\InputLuaExample[firstline=11,lastline=14]{opts/naked-as-value.lua} +\InputLua[firstline=11,lastline=14]{opts/naked-as-value.lua} + +\DefaultOptDescription{naked_as_value} %% % @@ -568,12 +652,14 @@ By default the parse function throws an error if there are unknown keys. % Mit Hilfe der Option \lua{no_error} kann dies unterbunden werden. This can be prevented with the help of the \lua{no_error} option. -\InputLuaExample[firstline=5,lastline=6]{opts/no-error.lua} +\InputLua[firstline=5,lastline=6]{opts/no-error.lua} \noindent If we set the option \lua{no_error} to \lua{true}: -\InputLuaExample[firstline=9,lastline=10]{opts/no-error.lua} +\InputLua[firstline=9,lastline=10]{opts/no-error.lua} + +\DefaultOptDescription{no_error} %% % @@ -587,15 +673,17 @@ If we set the option \lua{no_error} to \lua{true}: With the help of the option \lua{unpack}, all tables that consist of only one a single naked key or a single standalone value are unpacked. -\InputLuaExample[firstline=4,lastline=5]{opts/unpack.lua} +\InputLua[firstline=4,lastline=5]{opts/unpack.lua} + +\InputLua[firstline=11,lastline=12]{opts/unpack.lua} -\InputLuaExample[firstline=11,lastline=12]{opts/unpack.lua} +\DefaultOptDescription{unpack} %% % %% -\subsection{Function \texttt{define(defs, opts): parse}} +\subsection{Function “\texttt{define(defs, opts): parse}”} \label{define} The \lua{define} function returns a \lua{parse} function (see @@ -609,13 +697,13 @@ key-value pair is then stored under this key. \item by the “name” attribute. \end{enumerate} -\InputLuaExample[firstline=4,lastline=16]{functions/define.lua} +\InputLua[firstline=4,lastline=16]{functions/define.lua} \noindent For nested definitions, only the last two ways of specifying the key names can be used. -\InputLuaExample[firstline=26,lastline=33]{functions/define.lua} +\InputLua[firstline=26,lastline=33]{functions/define.lua} %----------------------------------------------------------------------- % @@ -636,12 +724,16 @@ The name \emph{“attribute”} for an option, a key, a property ... (to list just a few naming possibilities) to define keys, was deliberately chosen to distinguish them from the options of the \lua{parse} function. % +% Diese Attribute sind erlaubt. +These attributes are allowed: +\directlua{luakeys.print_names('attrs')}. +% % Das folgende Codebeispiel listet alle Attribute auf, die verwendet % werden können, um Schlüssel-Wert-Paare zu definieren. The code example below lists all the attributes that can be used to define key-value pairs. -\InputLuaExample[firstline=5,lastline=41]{defs/all-attrs.lua} +\InputLua[firstline=5,lastline=46]{defs/all-attrs.lua} %% % @@ -653,12 +745,12 @@ With the help of the \lua{alias} attribute, other key names can be used. The value is always stored under the original key name. A single alias name can be specified by a string ... -\InputLuaExample[firstline=4,lastline=7]{defs/attrs/alias.lua} +\InputLua[firstline=4,lastline=7]{defs/attrs/alias.lua} \noindent multiple aliases by a list of strings. -\InputLuaExample[firstline=13,lastline=16]{defs/attrs/alias.lua} +\InputLua[firstline=13,lastline=16]{defs/attrs/alias.lua} %% % @@ -669,7 +761,7 @@ multiple aliases by a list of strings. % Die Option \lua{default} wird nur bei nackten Schlüsseln verwendet. The \lua{default} attribute is used only for naked keys. -\InputLuaExample[firstline=4,lastline=5]{defs/attrs/always-present.lua} +\InputLua[firstline=4,lastline=5]{defs/attrs/always-present.lua} \noindent % Wird die Option \lua{always_present} auf wahr gesetzt, wird der @@ -678,7 +770,7 @@ If the attribute \lua{always_present} is set to true, the key is always included in the result. If no default value is definied, true is taken as the value. -\InputLuaExample[firstline=11,lastline=12]{defs/attrs/always-present.lua} +\InputLua[firstline=11,lastline=12]{defs/attrs/always-present.lua} %% % @@ -690,14 +782,14 @@ as the value. Some key values should be selected from a restricted set of choices. These can be handled by passing an array table containing choices. -\InputLuaExample[firstline=4,lastline=5]{defs/attrs/choices.lua} +\InputLua[firstline=4,lastline=5]{defs/attrs/choices.lua} \noindent When the key-value pair is parsed, values will be checked, and an error message will be displayed if the value was not one of the acceptable choices: -\InputLuaExample[firstline=13,lastline=15]{defs/attrs/choices.lua} +\InputLua[firstline=13,lastline=15]{defs/attrs/choices.lua} %% % @@ -727,8 +819,8 @@ A type conversion can fail with the three data types % Dann wird eine Fehlermeldung ausgegeben. Then an error message is displayed. -\InputLuaExample[firstline=4,lastline=8]{defs/attrs/data-type.lua} -\InputLuaExample[firstline=11,lastline=15]{defs/attrs/data-type.lua} +\InputLua[firstline=4,lastline=8]{defs/attrs/data-type.lua} +\InputLua[firstline=11,lastline=15]{defs/attrs/data-type.lua} %% % @@ -746,7 +838,7 @@ key individually. With the global \lua{default} attribute (\ref{option-default}) a default value can be specified for all naked keys. -\InputLuaExample[firstline=4,lastline=9]{defs/attrs/default.lua} +\InputLua[firstline=4,lastline=9]{defs/attrs/default.lua} %% % @@ -766,14 +858,15 @@ Only one key from this group is allowed. % Wert verwendet werden. Any value can be used as a name for this exclusive group. -\InputLuaExample[firstline=4,lastline=9]{defs/attrs/exclusive-group.lua} +\InputLua[firstline=4,lastline=9]{defs/attrs/exclusive-group.lua} +\noindent % Werden mehrer Schlüssel der Gruppe angegeben, so wird eine % Fehlermeldung geworfen. If more than one key of the group is specified, an error message is thrown. -\InputLuaExample[firstline=21,lastline=23]{defs/attrs/exclusive-group.lua} +\InputLua[firstline=21,lastline=23]{defs/attrs/exclusive-group.lua} %% % @@ -809,13 +902,13 @@ opposite key pair. If the key \lua{show} is parsed by the \lua{parse} function, then the target key \lua{visibility} receives the value \lua{true}. -\InputLuaExample[firstline=4,lastline=7]{defs/attrs/opposite-keys.lua} +\InputLua[firstline=4,lastline=7]{defs/attrs/opposite-keys.lua} % Wird der Schlüssel \lua{hide} gelesen, dann \lua{falsch}. \noindent If the key \lua{hide} is parsed, then \lua{false}. -\InputLuaExample[firstline=13,lastline=13]{defs/attrs/opposite-keys.lua} +\InputLua[firstline=13,lastline=13]{defs/attrs/opposite-keys.lua} %% % @@ -844,21 +937,31 @@ parse('key=value') \subsubsection{Attribute “\texttt{match}”} -% Der Wert des Schlüssel wird der Lua Funktion übergeben -The value of the key is passed to the Lua function -\lua{string.match(value, match)} ((\url{http://www.lua.org/manual/5.3/manual.html#pdf-string.match})). +% Der Wert des Schlüssel wird zuerst der Lua Funktion +% \lua{string.match(value, match)} übergeben, bevor er dem Schlüssel +% zugewiesen wird. +The value of the key is first passed to the Lua function +\lua{string.match(value, match)} +(\url{http://www.lua.org/manual/5.3/manual.html#pdf-string.match}) +before being assigned to the key. +% +% Du kannst das Attribut \lua{match} deshalb mit einer Pattern-Matching- +% Zeichenkette konfigurieren, wie sie in Lua zu Einsatz kommt. +You can therefore configure the \lua{match} attribute with a pattern +matching string used in Lua. +% % Werfe einen Blick in das Lua-Handbuch, wie man Patterns schreibt. Take a look at the Lua manual on how to write patterns -(\url{http://www.lua.org/manual/5.3/manual.html#6.4.1}) +(\url{http://www.lua.org/manual/5.3/manual.html#6.4.1}). -\InputLuaExample[firstline=4,lastline=6]{defs/attrs/match.lua} +\InputLua[firstline=4,lastline=7]{defs/attrs/match/birthday.lua} \noindent % Kann das Pattern im Wert nicht gefunden werden, wird eine % Fehlermeldung ausgegeben. If the pattern cannot be found in the value, an error message is issued. -\InputLuaExample[firstline=14,lastline=17]{defs/attrs/match.lua} +\InputLua[firstline=15,lastline=18]{defs/attrs/match/birthday.lua} \noindent % Der Schlüssel erhält das Ergebnis der Funktion \lua{string.match(value, @@ -867,8 +970,11 @@ If the pattern cannot be found in the value, an error message is issued. The key receives the result of the function \lua{string.match(value, match)}, which means that the original value may not be stored completely in the key. +% +% Im nächsten Beispiel wird der gesamte Eingabewert akzeptiert: +In the next example, the entire input value is accepted: -\InputLuaExample[firstline=22,lastline=23]{defs/attrs/match.lua} +\InputLua[firstline=4,lastline=5]{defs/attrs/match/year.lua} \noindent % Das Präfix “waste ” und das Suffix “ rubbisch” der Zeichenketten wird @@ -876,7 +982,7 @@ completely in the key. The prefix “waste ” and the suffix “ rubbisch” of the string are discarded. -\InputLuaExample[firstline=29,lastline=29]{defs/attrs/match.lua} +\InputLua[firstline=11,lastline=11]{defs/attrs/match/year.lua} \noindent % Da Funktion \lua{string.match(value, match)} immer eine Zeichenkette @@ -897,13 +1003,61 @@ The \lua{name} attribute allows an alternative notation of key names. % Anstatt ... Instead of ... -\InputLuaExample[firstline=4,lastline=5]{defs/attrs/name.lua} +\InputLua[firstline=4,lastline=8]{defs/attrs/name/as-key.lua} \noindent % ... können wir schreiben: ... we can write: -\InputLuaExample[firstline=11,lastline=15]{defs/attrs/name.lua} +\InputLua[firstline=4,lastline=8]{defs/attrs/name/name-attr.lua} + +%% +% +%% + +\subsubsection{Attribute “\texttt{pick}”} + +% Das Attribut \lua{pick} sucht nach einem Wert, der keinem Schlüssel +% zugeordnet ist. +The attribute \lua{pick} searches for a value not assigned to a key. +% Der zuerst gefundene Wert, d. h. der weiter links stehende Wert, wird +% einem Schlüssel zugewiesen. +The first value found, i.e. the one further to the left, is assigned to +a key. + +\InputLua[firstline=4,lastline=6]{defs/attrs/pick/dimension.lua} + +\noindent +% Es wird nur in der aktuellen Ergebnistabelle gesucht und nicht auf +% anderen Ebenen in der rekursiven Datenstruktur. +Only the current result table is searched, not other levels in the +recursive data structure. + +\InputLua[firstline=4,lastline=11]{defs/attrs/pick/different-levels.lua} + +\noindent +% Die Suche nach Werte wird aktiviert, wenn das Attribut \lua{pick} auf +% \lua{true} gesetzt wird. +The search for values is activated when the attribute \lua{pick} is set +to \lua{true}. +% Die Suche kann eingeschränkt werden, indem ein Datentype angegeben +% wird. +The search can be limited by specifying a data type. +% Nach diesen Datentypen kann gesucht werden: +These data types can be searched for: +\directlua{ + local types = {} + for t, fn in pairs(luakeys.is) do + table.insert(types, t) + end + tex.print(table.concat(types, ', ')) +}. + +% Wird einem Schlüssel bereits bei der Eingabe ein Wert zugewiesen, dann +% wird nicht weiter nach Werten gesucht. +If a value is already assigned to a key when it is entered, then no +further search for values is performed. +\InputLua[firstline=4,lastline=8]{defs/attrs/pick/value-set.lua} %% % @@ -912,19 +1066,24 @@ Instead of ... \subsubsection{Attribute “\texttt{process}”} \label{attr-process} -The \lua{process} attribute can be used to define a function whose return -value is passed to the key. Four parameters are passed when the -function is called: +% Das Attribut \lua{process} kann dazu verwendet werden, um eine Funktion +% zu definieren, deren Rückgabewert an den Schlüssel übergeben wird. +The \lua{process} attribute can be used to define a function whose +return value is passed to the key. +% +% Beim Aufruf der Funktion werden vier Parameter übergeben: +Four parameters are passed when the function is called: \begin{enumerate} \item \lua{value}: -% Der zum schlüssel gehörende aktuelle Wert. +% Der zum Schlüssel gehörende aktuelle Wert. The current value asssociated with the key. \item \lua{input}: % Die Ergebnis-Tabelle, die vor dem Zeitpunkt geklont wurde, als mit dem % Anwenden der Definitionen begonnen wurde. -The result table cloned before the time the definitions started to be applied. +The result table cloned before the time the definitions started to be +applied. \item \lua{result}: The table in which the final result will be saved. @@ -932,26 +1091,29 @@ The result table cloned before the time the definitions started to be applied. are stored. \end{enumerate} -% Das folgende Beispiel demonstriert den Parameter \lua{value}. \noindent +% Das folgende Beispiel demonstriert den Parameter \lua{value}: The following example demonstrates the \lua{value} parameter: -\InputLuaExample[firstline=4,lastline=14]{defs/attrs/process.lua} +\InputLua[firstline=4,lastline=14]{defs/attrs/process/parameter-value.lua} \noindent +% Das folgende Beispiel demonstriert den Parameter \lua{input}: The following example demonstrates the \lua{input} parameter: -\InputLuaExample[firstline=22,lastline=34]{defs/attrs/process.lua} +\InputLua[firstline=4,lastline=16]{defs/attrs/process/parameter-input.lua} \noindent +% Das folgende Beispiel demonstriert den Parameter \lua{result}: The following example demonstrates the \lua{result} parameter: -\InputLuaExample[firstline=42,lastline=50]{defs/attrs/process.lua} +\InputLua[firstline=4,lastline=12]{defs/attrs/process/parameter-result.lua} \noindent +% Das folgende Beispiel demonstriert den Parameter \lua{unknown}: The following example demonstrates the \lua{unknown} parameter: -\InputLuaExample[firstline=58,lastline=65]{defs/attrs/process.lua} -\InputLuaExample[firstline=69,lastline=69]{defs/attrs/process.lua} +\InputLua[firstline=4,lastline=11]{defs/attrs/process/parameter-unknown.lua} +\InputLua[firstline=15,lastline=15]{defs/attrs/process/parameter-unknown.lua} %% % @@ -959,16 +1121,41 @@ The following example demonstrates the \lua{unknown} parameter: \subsubsection{Attribute “\texttt{required}”} -\InputLuaExample[firstline=4,lastline=5]{defs/attrs/required.lua} +% Durch das Attribut \lua{required} kann erzwungen werden, dass ein +% bestimmter Schlüssel angegeben werden muss. +The \lua{required} attribute can be used to enforce that a specific key +must be specified. +% +% Im untenstehenden Beispiel wird der Schlüssel \lua{important} als +% zwingend notwendig definiert. +In the example below, the key \lua{important} is defined as mandatory. -\InputLuaExample[firstline=13,lastline=14]{defs/attrs/required.lua} +\InputLua[firstline=4,lastline=5]{defs/attrs/required.lua} + +\noindent +% Fehlt der Schlüssel \lua{important} in der Eingabe, so tritt eine +% Fehlermeldung auf. +If the key \lua{important} is missing in the input, an error message +occurs. + +\InputLua[firstline=13,lastline=14]{defs/attrs/required.lua} \noindent A recursive example: -\InputLuaExample[firstline=18,lastline=23]{defs/attrs/required.lua} -\InputLuaExample[firstline=29,lastline=30]{defs/attrs/required.lua} -\InputLuaExample[firstline=38,lastline=39]{defs/attrs/required.lua} +\InputLua[firstline=18,lastline=23]{defs/attrs/required.lua} + +\noindent +% Der Schlüssel \lua{important2} auf der Ebene 2 fehlt. +The \lua{important2} key on level 2 is missing. + +\InputLua[firstline=29,lastline=30]{defs/attrs/required.lua} + +\noindent +% Der Schlüssel \lua{important1} auf der untersten Schlüssel-Ebene fehlt. +The \lua{important1} key at the lowest key level is missing. + +\InputLua[firstline=38,lastline=39]{defs/attrs/required.lua} %% % @@ -981,39 +1168,39 @@ A recursive example: The \lua{sub_keys} attribute can be used to build nested key-value pair definitions. -\InputLuaExample[firstline=4,lastline=16]{defs/attrs/sub-keys.lua} +\InputLua[firstline=4,lastline=16]{defs/attrs/sub-keys.lua} %----------------------------------------------------------------------- % %----------------------------------------------------------------------- -\subsection{Function \texttt{render(result): string}} +\subsection{Function “\texttt{render(result): string}”} The function \lua{render(result)} reverses the function \lua{parse(kv_string)}. It takes a Lua table and converts this table into a key-value string. The resulting string usually has a different order as the input table. -\InputLuaExample[firstline=4,lastline=10]{functions/render.lua} +\InputLua[firstline=4,lastline=10]{functions/render.lua} \noindent In Lua only tables with 1-based consecutive integer keys (a.k.a. array tables) can be parsed in order. -\InputLuaExample[firstline=16,lastline=17]{functions/render.lua} +\InputLua[firstline=16,lastline=17]{functions/render.lua} %% % %% -\subsection{Function \texttt{debug(result): void}} +\subsection{Function “\texttt{debug(result): void}”} The function \lua{debug(result)} pretty prints a Lua table to standard output (stdout). It is a utility function that can be used to debug and inspect the resulting Lua table of the function \lua{parse}. You have to compile your \TeX{} document in a console to see the terminal output. -\InputLuaExample[firstline=4,lastline=5]{functions/debug.lua} +\InputLua[firstline=4,lastline=5]{functions/debug.lua} \noindent The output should look like this: @@ -1032,7 +1219,7 @@ The output should look like this: % %% -\subsection{Function \texttt{save(identifier, result): void}} +\subsection{Function “\texttt{save(identifier, result): void}”} The function \lua{save(identifier, result)} saves a result (a table from a previous run of \lua{parse}) under an identifier. @@ -1043,7 +1230,7 @@ store results for the later usage. % %% -\subsection{Function \texttt{get(identifier): result}} +\subsection{Function “\texttt{get(identifier): result}”} The function \lua{get(identifier)} retrieves a saved result from the result store. @@ -1052,22 +1239,105 @@ result store. % %% -\subsection{Table \texttt{is}} +\subsection{Table “\texttt{is}”} + +% In der Tabelle \lua{is} werden einige Funktionen zusammengefasst, die +% überprüft ob eine Eingabe einem bestimmen Datentyp entspricht. +In the table \lua{is} some functions are summarized, which check whether +an input corresponds to a certain data type. +% +% Alle Funktionen akzeptieren nicht nur die entsprechenden Lua-Datentypen, +% sondern auch Eingaben als Zeichenketten. +All functions accept not only the corresponding Lua data types, but also +input as strings. +% +% Beispielsweise wird die Zeichenkette \lua{'true'} von der +% \lua{is.boolean()}-Funktion als Wahrheitswert erkannt. +For example, the string \lua{'true'} is recognized by the +\lua{is.boolean()} function as a boolean value. + +\subsubsection{Function “\texttt{is.boolean(value): boolean}”} +\InputLua[firstline=6,lastline=23]{functions/is/boolean.lua} + +\subsubsection{Function “\texttt{is.dimension(value): boolean}”} +\InputLua[firstline=6,lastline=16]{functions/is/dimension.lua} + +\subsubsection{Function “\texttt{is.integer(value): boolean}”} +\InputLua[firstline=6,lastline=11]{functions/is/integer.lua} + +\subsubsection{Function “\texttt{is.number(value): boolean}”} +\InputLua[firstline=6,lastline=13]{functions/is/number.lua} + +\subsubsection{Function “\texttt{is.string(value): boolean}”} +\InputLua[firstline=6,lastline=12]{functions/is/string.lua} + +%% +% +%% + +\subsection{Table “\texttt{utils}”} + +\subsubsection{Function “\texttt{utils.scan_oarg(initial_delimiter?, end_delimiter?): string}”} -\subsubsection{Function \texttt{is.boolean(value): boolean}} -\InputLuaExample[firstline=7,lastline=23]{is-table.lua} +% Plain \TeX{} kennt keine optionalen Argumente (oarg). +Plain \TeX{} does not know optional arguments (oarg). +% +% Die Funktion ermöglicht es nicht nur in \LaTeX{}, sondern auch in +% Plain \TeX{} nach optionalen Argumenten zu suchen. +The function \\ \lua{utils.scan_oarg(initial_delimiter?, +end_delimiter?): string} allows to search for optional arguments not only +in \LaTeX{} but also in Plain \TeX. +% +% Die Funktion basiert auf der Token-Bibliothek. +The function uses the token library built into Lua\TeX{}. +% +% Die beiden Parameter \lua{initial_delimiter} und \lua{end_delimiter} +% können weggelassen werden. +The two parameters \lua{initial_delimiter} and \lua{end_delimiter} can +be omitted. +% +% Dann werden eckige Klammern als Begrenzungszeichen angenommen. +Then square brackets are assumed to be delimiters. +% +% Dieser Lua-Code \lua{utils.scan_oarg('(', ')')} sucht beispielsweise +% nach an einem optionalen Argument in runden Klammern. +For example, this Lua code \lua{utils.scan_oarg('(', ')')} searches for +an optional argument in round brackets +% +% Die Funktion gibt die Zeichenkette zwischen den Begrenzungszeichen +% zurück, oder nil wenn Begrenzungszeichen gefunden werden konnten. +The function returns the string between the delimiters or \lua{nil} if +no delimiters could be found. +% +% Die Begrenzungszeichen sind im Ergebnis nicht enthalten. +The delimiters themselves are not included in the result. +% +% Nach dem \latex{\directlua{}} darf das Makro, indem +% \lua{utils.scan_oarg} eingesetzt wird, zu keinen Zeichen expandieren. +After the \latex{\directlua{}}, the macro using \lua{utils.scan_oarg} +must not expand to any characters. -\subsubsection{Function \texttt{is.dimension(value): boolean}} -\InputLuaExample[firstline=27,lastline=37]{is-table.lua} +\InputLatex{utils/scan-oarg-plain.tex} -\subsubsection{Function \texttt{is.integer(value): boolean}} -\InputLuaExample[firstline=41,lastline=46]{is-table.lua} +%% +% +%% + +\subsection{Table “version”} -\subsubsection{Function \texttt{is.number(value): boolean}} -\InputLuaExample[firstline=50,lastline=57]{is-table.lua} +% Das luakeys Projekt verwendet semantic versioning +The luakeys project uses semantic versioning. +% Die drei Versionenzahlen des Semantic Versioning Schemas werden in +% einer Tabelle in der Reihenfolge MAJOR, MINOR, PATCH als Ganzzahlen +% abgelegt. +The three version numbers of the semantic versioning scheme are stored +in a table as integers in the order MAJOR, MINOR, PATCH. +% Mit Hilfe dieser Tabelle kann überprüft werden, ob die richtige +% Version installiert ist. +This table can be used to check whether the correct version is +installed. -\subsubsection{Function \texttt{is.string(value): boolean}} -\InputLuaExample[firstline=61,lastline=67]{is-table.lua} +\InputLua[firstline=4,lastline=10]{version.lua} %----------------------------------------------------------------------- % @@ -1128,10 +1398,12 @@ key-value lists (\texttt{level1=\{level2=\{key=value,naked\}\}}). \alt `ex' | `EX' \alt `in' | `IN' \alt `mm' | `MM' + \alt `mu' | `MU' \alt `nc' | `NC' \alt `nd' | `ND' \alt `pc' | `PC' \alt `pt' | `PT' + \alt `px' | `PX' \alt `sp' | `SP' <boolean> ::= <boolean-true> | <boolean-false> @@ -1156,16 +1428,10 @@ into Lua’s boolean type \lua{true}, the strings \texttt{false}, \texttt{FALSE} and \texttt{False} into \lua{false}. \begin{multicols}{2} -\begin{minted}{latex} -\luakeysdebug{ - lower case true = true, - upper case true = TRUE, - title case true = True - lower case false = false, - upper case false = FALSE, - title case false = False, -} -\end{minted} +\InputLatex[firstline=5,lastline=12]{luakeysdebug/boolean-latex.tex} + +\columnbreak + \begin{minted}{lua} { ['lower case true'] = true, @@ -1185,18 +1451,19 @@ into Lua’s boolean type \lua{true}, the strings \texttt{false}, \subsubsection{number} \begin{multicols}{2} -\begin{minted}{latex} -\luakeysdebug{ - num1 = 4, - num2 = -4, - num3 = 0.4 -} -\end{minted} +\InputLatex[firstline=5,lastline=13]{luakeysdebug/number-latex.tex} + +\columnbreak + \begin{minted}{lua} { - ['num1'] = 4, - ['num2'] = -4, - ['num3'] = 0.4 + ['num0'] = 42, + ['num1'] = 42, + ['num2'] = -42, + ['num3'] = 4.2, + ['num4'] = 0.42, + ['num5'] = 0.42, + ['num6'] = '0 . 42', -- string } \end{minted} \end{multicols} @@ -1207,6 +1474,22 @@ into Lua’s boolean type \lua{true}, the strings \texttt{false}, \subsubsection{dimension} +% Luakeys versucht alle Einheiten zu erkennen, die in der TeX-Welt +% verwendet werden. +|luakeys| tries to recognize all units used in the \TeX{} world. +% +% Nach dem Lua\TeX-Quellcode . +According to the Lua\TeX{} source code +(\href{https://github.com/TeX-Live/luatex/blob/51db1985f5500dafd2393aa2e403fefa57d3cb76/source/texk/web2c/luatexdir/lua/ltexlib.c#L434-L625} +{source/texk/web2c/luatexdir/lua/ltexlib.c}) +% +% und nach dem Dimensionen-Modul der lulibs-Bibliothek +and the dimension module of the lualibs library +(\href{https://raw.githubusercontent.com/latex3/lualibs/master/lualibs-util-dim.lua} +{lualibs-util-dim.lua}), +% +% müssten alle Einheiten erkannt werden +all units should be recognized. \begin{multicols}{3} \tiny \begin{center} @@ -1221,33 +1504,19 @@ em & horizontal measure of \emph{M} \\ ex & vertical measure of \emph{x} \\ in & inch \\ mm & milimeter \\ +mu & math unit \\ nc & new cicero \\ nd & new didot \\ pc & pica \\ pt & point \\ +px & x height current font \\ sp & scaledpoint \\ \end{tabular} \end{center} \columnbreak -\begin{minted}{latex} -\luakeysdebug{ - bp = 1bp, - cc = 1cc, - cm = 1cm, - dd = 1dd, - em = 1em, - ex = 1ex, - in = 1in, - mm = 1mm, - nc = 1nc, - nd = 1nd, - pc = 1pc, - pt = 1pt, - sp = 1sp, -} -\end{minted} +\InputLatex[firstline=5,lastline=21]{luakeysdebug/dimension/all-latex.tex} \columnbreak @@ -1261,15 +1530,39 @@ sp & scaledpoint \\ ['ex'] = 282460, ['in'] = 4736286, ['mm'] = 186467, + ['mu'] = 65536, ['nc'] = 839105, ['nd'] = 69925, ['pc'] = 786432, ['pt'] = 65536, + ['px'] = 65781, ['sp'] = 1, } \end{minted} \end{multicols} +\noindent +% Im nächsten Beispiel werden die unterschiedlichen Notationsformen der +% Dimensionen illustriert. +The next example illustrates the different notations of the dimensions. + +\begin{multicols}{2} +\InputLatex[firstline=5,lastline=12]{luakeysdebug/dimension/notations-latex.tex} + +\columnbreak + +\begin{minted}{lua} +{ + ['upper'] = 1864679, + ['lower'] = 1864679, + ['space'] = 1864679, + ['plus'] = 1864679, + ['minus'] = -1864679, + ['nodim'] = '1 c m', -- string +} +\end{minted} +\end{multicols} + %% % %% @@ -1287,7 +1580,7 @@ With or without double quotes. If the text have to contain commas, curly braces or equal signs, then double quotes must be used. -\InputLuaExample[firstline=4,lastline=17]{data-types/string.lua} +\InputLua[firstline=4,lastline=17]{data-types/string.lua} \subsubsection{Naked keys} @@ -1303,14 +1596,14 @@ and stored into an array. % Index ist 1). In Lua an array is a table with numeric indexes (The first index is 1). -\InputLatexExample[firstline=5,lastline=12]{luakeysdebug/naked-keys.tex} +\InputLatex[firstline=5,lastline=12]{luakeysdebug/naked-keys-latex.tex} \noindent % VAlle erkannten Datentypen können als eigenständige Werte verwendet % werden. All recognized data types can be used as standalone values. -\InputLatexExample[firstline=14,lastline=19]{luakeysdebug/naked-keys.tex} +\InputLatex[firstline=14,lastline=19]{luakeysdebug/naked-keys-latex.tex} %----------------------------------------------------------------------- % @@ -1320,6 +1613,10 @@ All recognized data types can be used as standalone values. \section{Examples} +%% +% +%% + \subsection{Extend and modify keys of existing macros} Extend the includegraphics macro with a new key named \latex{caption} @@ -1327,17 +1624,34 @@ and change the accepted values of the \latex{width} key. A number between 0 and 1 is allowed and converted into \latex{width=0.5\linewidth} -\InputLuaExample{extend-includegraphics/extend-keys.lua} -\InputLatexExample{extend-includegraphics/extend-keys.tex} +\InputLua{extend-includegraphics/extend-keys.lua} +\InputLatex{extend-includegraphics/extend-keys-latex.tex} + +%% +% +%% \subsection{Process document class options} -\begin{minted}{latex} -\directlua{luakeys.parse('\@classoptionslist')} -\end{minted} +% Auf die Optionen einer \LaTeX{} Dokumentenklasse kann über das Macro +% \latex{\@classoptionslist} zu gegriffen werden. +The options of a \LaTeX{} document class can be accessed via the +\latex{\@classoptionslist} macro. +% +% Die Zeichenkette des Makros \latex{\@classoptionslist} ist bereits +% expandiert und normalisiert. +The string of the macro \latex{\@classoptionslist} is already expanded +and normalized. +% +% Neben Leerzeichen werden auch die geschweiften Klammern entfernt. +In addition to spaces, the curly brackets are also removed. +% Es ist deshalb nicht möglich, in einander geschachtelte hierarische +% Schlüssel-Wert-Paare über die Option zu verarbeiten. +It is therefore not possible to process nested hierarchical key-value +pairs via the option. -\InputLatexExample{class-options/test-class.cls} -\InputLatexExample{class-options/use-test-class.tex} +\InputLatex{class-options/test-class.cls} +\InputLatex{class-options/use-test-class-latex.tex} \begin{minted}{lua} { @@ -1458,30 +1772,30 @@ An example of how to use the command in \LaTeX: \inputminted[linenos=true]{latex}{luakeys-debug.sty} -\changes{v0.1}{2021/01/18}{Inital release} -\changes{v0.2}{2021/09/19}{ +\changes{0.1.0}{2021/01/18}{Inital release} +\changes{0.2.0}{2021/09/19}{ * Allow all recognized data types as keys * Allow TeX macros in the values * New public Lua functions: save(identifier, result), get(identifier) } -\changes{v0.3}{2021/11/05}{ +\changes{0.3.0}{2021/11/05}{ * Add a LuaLaTeX wrapper “luakeys.sty” * Add a plain LuaTeX wrapper “luakeys.tex” * Rename the previous documentation file “luakeys.tex” to luakeys-doc.tex” } -\changes{v0.4}{2021/12/31}{ +\changes{0.4.0}{2021/12/31}{ * Parser: Add support for nested tables (for example {{'a', 'b'}}) * Parser: Allow only strings and numbers as keys * Parser: Remove support from Lua numbers with exponents (for example '5e+20') * Switch the Lua testing framework to busted } -\changes{v0.5}{2022/04/04}{ +\changes{0.5.0}{2022/04/04}{ * Add possibility to change options globally * New option: standalone_as_true * Add a recursive converter callback / hook to process the parse tree * New option: case_insensitive_keys } -\changes{v0.6}{2022/06/09}{ +\changes{0.6.0}{2022/06/09}{ * New feature: keys now can be defined using the function “define(defs, opts)” or “define(kv_string, { defs = { key = { ... } } })” * Rename the global options table from “default_options” to “opts” @@ -1494,6 +1808,14 @@ An example of how to use the command in \LaTeX: produce the previous effect. * The function “print()” is now called “debug()” } +\changes{0.7.0}{2022/07/06}{ +* The project now uses semantic versioning. +* New definition attribute “pick” to pick standalone values and assign + them to a key +* New function “utils.scan_oarg()” to search for an optional argument, + that means scan for tokens that are enclosed in square brackets +* extend and improve documentation +} \pagebreak \PrintChanges \pagebreak |