luakeys (18jan21)

git-svn-id: svn://tug.org/texlive/trunk@57463 c570f23f-e606-0410-a88d-b1316a301751

4 files changed, 629 insertions, 0 deletions

diff --git a/Master/texmf-dist/doc/luatex/luakeys/README.md b/Master/texmf-dist/doc/luatex/luakeys/README.md
new file mode 100644
index 00000000000..cb4c429d4cd
--- /dev/null
+++ b/Master/texmf-dist/doc/luatex/luakeys/README.md
@@ -0,0 +1,52 @@
+# luakeys
+
+`luakeys` is a Lua module that can parse key-value options like the
+TeX packages [keyval](https://www.ctan.org/pkg/keyval),
+[kvsetkeys](https://www.ctan.org/pkg/kvsetkeys),
+[kvoptions](https://www.ctan.org/pkg/kvoptions),
+[xkeyval](https://www.ctan.org/pkg/xkeyval),
+[pgfkeys](https://www.ctan.org/pkg/pgfkeys) etc. do. `luakeys`,
+however, accompilshes this task entirely, by using the Lua language and
+doesn’t rely on TeX. Therefore this package can only be used with the
+TeX engine LuaTeX. Since `luakeys` uses
+[LPeg](http://www.inf.puc-rio.br/~roberto/lpeg/), the parsing
+mechanism should be pretty robust.
+
+## License
+
+Copyright 2021 Josef Friedrich
+
+This work may be distributed and/or modified under the
+conditions of the LaTeX Project Public License, either version 1.3c
+of this license or (at your option) any later version.
+The latest version of this license is in
+
+http://www.latex-project.org/lppl.txt
+
+and version 1.3c or later is part of all distributions of LaTeX
+version 2008/05/04 or later.
+
+This work has the LPPL maintenance status `maintained`.
+
+The Current Maintainer of this work is Josef Friedrich.
+
+## Tasks
+
+### Installing
+
+```
+make install
+```
+
+### Testing
+
+```
+luarocks install luaunit
+lua test/tests.lua
+```
+
+or
+
+```
+make test
+```
diff --git a/Master/texmf-dist/doc/luatex/luakeys/luakeys-debug.tex b/Master/texmf-dist/doc/luatex/luakeys/luakeys-debug.tex
new file mode 100644
index 00000000000..499b1305f67
--- /dev/null
+++ b/Master/texmf-dist/doc/luatex/luakeys/luakeys-debug.tex
@@ -0,0 +1,33 @@
+%% luakeys-debug.tex
+%% Copyright 2021 Josef Friedrich
+%
+% This work may be distributed and/or modified under the
+% conditions of the LaTeX Project Public License, either version 1.3c
+% of this license or (at your option) any later version.
+% The latest version of this license is in
+%   http://www.latex-project.org/lppl.txt
+% and version 1.3c or later is part of all distributions of LaTeX
+% version 2008/05/04 or later.
+%
+% This work has the LPPL maintenance status `maintained'.
+%
+% The Current Maintainer of this work is Josef Friedrich.
+%
+% This work consists of the files luakeys.lua, luakeys-debug.sty
+% and luakeys-debug.tex.
+
+\directlua{
+  luakeys = require('luakeys')
+}
+
+\def\luakeysdebug#1{
+  {
+    \tt
+    \parindent=0pt
+    \directlua{
+      local result = luakeys.parse('#1')
+      tex.print(luakeys.stringify(result, true))
+      luakeys.print(result)
+    }
+  }
+}
diff --git a/Master/texmf-dist/doc/luatex/luakeys/luakeys.pdf b/Master/texmf-dist/doc/luatex/luakeys/luakeys.pdf
new file mode 100644
index 00000000000..ceaebbee048
--- /dev/null
+++ b/Master/texmf-dist/doc/luatex/luakeys/luakeys.pdf
diff --git a/Master/texmf-dist/doc/luatex/luakeys/luakeys.tex b/Master/texmf-dist/doc/luatex/luakeys/luakeys.tex
new file mode 100644
index 00000000000..75ffbc8c70d
--- /dev/null
+++ b/Master/texmf-dist/doc/luatex/luakeys/luakeys.tex
@@ -0,0 +1,544 @@
+\documentclass{ltxdoc}
+
+\usepackage{hyperref}
+\EnableCrossrefs
+\CodelineIndex
+\RecordChanges
+
+\usepackage{mdframed}
+\usepackage{minted}
+\usepackage{luakeys-debug}
+\usepackage{multicol}
+\usepackage{luacode}
+\usepackage{syntax}
+\usemintedstyle{friendly}
+\BeforeBeginEnvironment{minted}{\begin{mdframed}}
+\AfterEndEnvironment{minted}{\end{mdframed}}
+\setminted{
+  breaklines=true,
+  fontsize=\footnotesize,
+}
+\def\lua#1{\mintinline{lua}|#1|}
+
+\begin{document}
+
+\providecommand*{\url}{\texttt}
+
+\title{The \textsf{luakeys} package}
+\author{%
+  Josef Friedrich\\%
+  \url{josef@friedrich.rocks}\\%
+  \href{https://github.com/Josef-Friedrich/nodetree}{github.com/Josef-Friedrich/luakeys}%
+}
+\date{v0.1 from 2021/01/18}
+
+\maketitle
+
+\vfill
+
+%\luakeysdebug{level1={level2={level3={dim=1cm,bool=true,num=-1e-03,str=lua}}}}
+
+\begin{minted}{lua}
+local luakeys = require('luakeys')
+local kv = luakeys.parse('level1={level2={level3={dim=1cm,bool=true,num=-1e-03,str=lua}}}')
+luakeys.print(kv)
+\end{minted}
+
+\noindent
+Result:
+
+\begin{center}
+\begin{minted}{lua}
+{
+  ['level1'] = {
+    ['level2'] = {
+      ['level3'] = {
+        ['dim'] = 1864679,
+        ['bool'] = true,
+        ['num'] = -0.001
+        ['str'] = 'lua',
+      }
+    }
+  }
+}
+\end{minted}
+\end{center}
+
+\vfill
+
+\strut
+
+\newpage
+
+\tableofcontents
+
+\newpage
+
+\section{Introduction}
+
+\noindent
+|luakeys| is a Lua module that can parse key-value options like the
+\TeX{} packages \href{https://www.ctan.org/pkg/keyval}{keyval},
+\href{https://www.ctan.org/pkg/kvsetkeys}{kvsetkeys},
+\href{https://www.ctan.org/pkg/kvoptions}{kvoptions},
+\href{https://www.ctan.org/pkg/xkeyval}{xkeyval},
+\href{https://www.ctan.org/pkg/pgfkeys}{pgfkeys} etc. do. |luakeys|,
+however, accompilshes this task entirely, by using the Lua language and
+doesn’t rely on \TeX{}. Therefore this package can only be used with the
+\TeX{} engine Lua\TeX{}. Since |luakeys| uses
+\href{http://www.inf.puc-rio.br/~roberto/lpeg/}{LPeg}, the parsing
+mechanism should be pretty robust.
+
+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 Joseph Wright and Christian Feuersänger gives a good overview of the
+available key-value packages.
+
+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)}.
+
+%-----------------------------------------------------------------------
+%
+%-----------------------------------------------------------------------
+
+\clearpage
+
+\section{Syntax of the recognized key-value format}
+
+%%
+%
+%%
+
+\subsection{A attempt to put the syntax into words}
+
+A key-value pair is definied by an equal sign (\texttt{key=value}).
+Several key-value pairs or values without keys are lined up with commas
+(\texttt{key=value,value}) and build a key-value list. Curly brackets
+can be used to create a recursive data structure of nested key-value
+lists (\texttt{level1=\{level2=\{key=value,value\}\}}).
+
+%%
+%
+%%
+
+\subsection{An (incomplete) attempt to put the syntax into the (Extended) Backus-Naur form}
+
+\begin{grammar}
+<list> ::= <list-item> | <list-item> <list>
+
+<list-item> ::= ( <key-value-pair> | <value-without-key> ) [ `,' ]
+
+<list-container> ::== `{' <list> `}'
+
+<value> ::= <boolean>
+  \alt <dimension>
+  \alt <number>
+  \alt <string-quoted>
+  \alt <string-unquoted>
+\end{grammar}
+
+... to be continued
+
+%%
+%
+%%
+
+\subsection{Recognized data types}
+
+\subsubsection{boolean}
+
+The strings \texttt{true}, \texttt{TRUE} and \texttt{True} are converted
+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}
+\begin{minted}{lua}
+{
+  ['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}
+\end{multicols}
+
+%%
+%
+%%
+
+\clearpage
+
+\subsubsection{number}
+
+\begin{multicols}{2}
+\begin{minted}{latex}
+\luakeysdebug{
+  num1 = 4,
+  num2 = -4,
+  num3 = 0.4,
+  num4 = 4.57e-3,
+  num5 = 0.3e12,
+  num6 = 5e+20
+}
+\end{minted}
+\begin{minted}{lua}
+{
+  ['num1'] = 4,
+  ['num2'] = -4,
+  ['num3'] = 0.4,
+  ['num4'] = 0.00457,
+  ['num5'] = 300000000000.0,
+  ['num6'] = 5e+20
+}
+\end{minted}
+\end{multicols}
+
+%%
+%
+%%
+
+\clearpage
+
+\subsubsection{dimension}
+
+|luakeys| detects \TeX{} dimensions and automatically converts the
+dimensions into scaled points using the function \lua{tex.sp(dim)}. Use
+the option \lua{convert_dimensions} of the function
+\lua{parse(kv_string, options)} to disalbe the automatic conversion.
+
+\begin{minted}{lua}
+local result = parse('dim=1cm', {
+  convert_dimensions = false,
+})
+\end{minted}
+
+If you want to convert a scale point into a unit string you can used the module
+\href{https://raw.githubusercontent.com/latex3/lualibs/master/lualibs-util-dim.lua}{lualibs-util-dim.lua}.
+
+\begin{minted}{latex}
+\begin{luacode}
+require('lualibs')
+tex.print(number.todimen(tex.sp('1cm'), 'cm', '%0.0F%s'))
+\end{luacode}
+\end{minted}
+
+\begin{center}
+\begin{tabular}{rl}
+\textbf{Unit name} & \textbf{Description} \\\hline
+bp & big point \\
+cc & cicero \\
+cm & centimeter \\
+dd & didot \\
+em & horizontal measure of \emph{M} \\
+ex & vertical measure of \emph{x} \\
+in & inch \\
+mm & milimeter \\
+nc & new cicero \\
+nd & new didot \\
+pc & pica \\
+pt & point \\
+sp & scaledpoint \\
+\end{tabular}
+\end{center}
+
+\begin{multicols}{2}
+\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}
+\begin{minted}{lua}
+{
+  ['bp'] = 65781,
+  ['cc'] = 841489,
+  ['cm'] = 1864679,
+  ['dd'] = 70124,
+  ['em'] = 655360,
+  ['ex'] = 282460,
+  ['in'] = 4736286,
+  ['mm'] = 186467,
+  ['nc'] = 839105,
+  ['nd'] = 69925,
+  ['pc'] = 786432,
+  ['pt'] = 65536,
+  ['sp'] = 1,
+}
+\end{minted}
+\end{multicols}
+
+%%
+%
+%%
+
+\subsubsection{string}
+
+There are two ways to specify strings: With or without quotes. If the
+text have to contain commas or equal signs, then double quotation
+marks must be used.
+
+\begin{multicols}{2}
+\begin{minted}{latex}
+\luakeysdebug{
+  without quotes = no commas and equal signs are allowed,
+  with double quotes = ", and = are allowed",
+}
+\end{minted}
+\begin{minted}{lua}
+{
+  ['without quotes'] = 'no commas and equal signs are allowed',
+  ['with double quotes'] = ', and = are allowed',
+}
+\end{minted}
+\end{multicols}
+
+%-----------------------------------------------------------------------
+%
+%-----------------------------------------------------------------------
+
+\clearpage
+
+\section{Exported functions of the Lua module \texttt{luakeys.lua}}
+
+To learn more about the individual functions (local functions), pleasecommand
+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:
+
+\begin{minted}{lua}
+local luakeys = require('luakeys')
+local parse = luakeys.parse
+local render = luakeys.render
+--local print = luakeys.print -- That would overwrite the built-in Lua function
+\end{minted}
+
+%%
+%
+%%
+
+\subsection{\texttt{parse(kv\_string, options)}: table}
+
+The function \lua{parse(input_string, options)} is the main method of
+this module. It parses a key-value string into a Lua table.
+
+\begin{minted}{latex}
+\newcommand{\mykeyvalcmd}[1][]{
+  \directlua{
+    result = luakeys.parse('#1')
+    luakeys.print(result)
+  }
+  #2
+}
+\mykeyvalcmd[one=1]{test}
+\end{minted}
+
+\noindent
+In plain \TeX:
+
+\begin{minted}{latex}
+\def\mykeyvalcommand#1{
+  \directlua{
+    result = luakeys.parse('#1')
+    luakeys.print(result)
+  }
+}
+\mykeyvalcmd{one=1}
+\end{minted}
+
+\noindent
+The function can be called with a options table. This two options are
+supported.
+
+\begin{minted}{lua}
+local result = parse('one,two,three', {
+  convert_dimensions = false,
+  unpack_single_array_value = false
+})
+\end{minted}
+
+%%
+%
+%%
+
+\subsection{\texttt{render(tbl)}: string}
+
+The function \lua{render(tbl)} 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.
+
+\begin{minted}{lua}
+result = luakeys.parse('one=1,two=2,tree=3,')
+print(luakeys.render(result))
+--- one=1,two=2,tree=3,
+--- or:
+--- two=2,one=1,tree=3,
+--- or:
+--- ...
+\end{minted}
+
+\noindent
+In Lua only tables with 1-based consecutive integer keys (a.k.a. array
+tables) can be parsed in order.
+
+\begin{minted}{lua}
+result = luakeys.parse('one,two,three')
+print(luakeys.render(result))
+--- one,two,three, (always)
+\end{minted}
+
+%%
+%
+%%
+
+\subsection{\texttt{print(tbl): void}}
+
+The function \lua{print(tbl)} 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.
+
+%\luakeysdebug{level1={level2={key=value}}}
+
+\begin{minted}{lua}
+result = luakeys.parse('level1={level2={key=value}}')
+luakeys.print(result)
+\end{minted}
+
+\noindent
+The output should look like this:
+
+\begin{minted}{md}
+{
+  ['level1'] = {
+    ['level2'] = {
+      ['key'] = 'value',
+  },
+}
+\end{minted}
+
+%-----------------------------------------------------------------------
+%
+%-----------------------------------------------------------------------
+
+\clearpage
+
+\section{Debug packages}
+
+Two small debug packages are included in |luakeys|. One debug package
+can be used in \LaTeX{} (luakeys-debug.sty) and one can be used in plain
+\TeX{} (luakeys-debug.tex). Both packages provide only one command:
+|\luakeysdebug{kv-string}|
+
+\begin{minted}{latex}
+\luakeysdebug{one,two,three}
+\end{minted}
+
+\noindent
+Then the following output should appear in the document:
+\bigskip
+
+\luakeysdebug{one,two,three}
+
+%%
+%
+%%
+
+\subsection{For plain \TeX: luakeys-debug.tex}
+
+An example of how to use the command in plain \TeX:
+
+\begin{minted}{latex}
+\input luakeys-debug.tex
+\luakeysdebug{one,two,three}
+\bye
+\end{minted}
+
+%%
+%
+%%
+
+\subsection{For \LaTeX: luakeys-debug.sty}
+
+An example of how to use the command in \LaTeX:
+
+\begin{minted}{latex}
+\documentclass{article}
+\usepackage{luakeys-debug}
+\begin{document}
+\luakeysdebug[
+  unpack single array values=false,
+  convert dimensions=false
+]{one,two,three}
+\end{document}
+\end{minted}
+
+%-----------------------------------------------------------------------
+%
+%-----------------------------------------------------------------------
+
+\clearpage
+
+\section{Implementation}
+
+%%
+%
+%%
+
+\subsection{luakeys.lua}
+
+\inputminted[linenos=true]{lua}{luakeys.lua}
+
+%%
+%
+%%
+
+\clearpage
+
+\subsection{luakeys-debug.tex}
+
+\inputminted[linenos=true]{latex}{luakeys-debug.tex}
+
+%%
+%
+%%
+
+\clearpage
+
+\subsection{luakeys-debug.sty}
+
+\inputminted[linenos=true]{latex}{luakeys-debug.sty}
+
+\changes{v0.1}{2020/01/17}{Inital release}
+
+\pagebreak
+\PrintChanges
+\pagebreak
+\PrintIndex
+\end{document}