summaryrefslogtreecommitdiff
path: root/macros/luatex/generic/luakeys/luakeys.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/luatex/generic/luakeys/luakeys.tex')
-rw-r--r--macros/luatex/generic/luakeys/luakeys.tex121
1 files changed, 114 insertions, 7 deletions
diff --git a/macros/luatex/generic/luakeys/luakeys.tex b/macros/luatex/generic/luakeys/luakeys.tex
index 75ffbc8c70..fc465f46ae 100644
--- a/macros/luatex/generic/luakeys/luakeys.tex
+++ b/macros/luatex/generic/luakeys/luakeys.tex
@@ -28,9 +28,9 @@
\author{%
Josef Friedrich\\%
\url{josef@friedrich.rocks}\\%
- \href{https://github.com/Josef-Friedrich/nodetree}{github.com/Josef-Friedrich/luakeys}%
+ \href{https://github.com/Josef-Friedrich/luakeys}{github.com/Josef-Friedrich/luakeys}%
}
-\date{v0.1 from 2021/01/18}
+\date{v0.2 from 2021/09/19}
\maketitle
@@ -105,6 +105,27 @@ This package would not be possible without the article
\clearpage
+\section{Usage}
+
+\begin{minted}{latex}
+\documentclass{article}
+\directlua{
+ luakeys = require('luakeys')
+}
+
+\newcommand{\helloworld}[2][]{
+ \directlua{
+ local keys = luakeys.parse('\luaescapestring{\unexpanded{#1}}')
+ luakeys.print(keys)
+ local marg = '#2'
+ tex.print(keys.greeting .. ', ' .. marg .. keys.punctuation)
+ }
+}
+\begin{document}
+\helloworld[greeting=hello,punctuation=!]{world}
+\end{document}
+\end{minted}
+
\section{Syntax of the recognized key-value format}
%%
@@ -123,7 +144,7 @@ lists (\texttt{level1=\{level2=\{key=value,value\}\}}).
%
%%
-\subsection{An (incomplete) attempt to put the syntax into the (Extended) Backus-Naur form}
+\subsection{An (incomplete) attempt to put the syntax into the Extended Backus-Naur Form}
\begin{grammar}
<list> ::= <list-item> | <list-item> <list>
@@ -137,6 +158,25 @@ lists (\texttt{level1=\{level2=\{key=value,value\}\}}).
\alt <number>
\alt <string-quoted>
\alt <string-unquoted>
+
+<sign> ::= `-' | `+'
+
+<integer> ::= `0' | `1' | `2' | `3' | `4' | `5' | `6' | `7' | `8' | `9'
+
+<unit> ::= `bp' | `BP'
+ \alt `cc' | `CC'
+ \alt `cm' | `CM'
+ \alt `dd' | `DD'
+ \alt `em' | `EM'
+ \alt `ex' | `EX'
+ \alt `in' | `IN'
+ \alt `mm' | `MM'
+ \alt `nc' | `NC'
+ \alt `nd' | `ND'
+ \alt `pc' | `PC'
+ \alt `pt' | `PT'
+ \alt `sp' | `SP'
+
\end{grammar}
... to be continued
@@ -226,7 +266,8 @@ local result = parse('dim=1cm', {
})
\end{minted}
-If you want to convert a scale point into a unit string you can used the module
+\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}.
\begin{minted}{latex}
@@ -317,6 +358,46 @@ marks must be used.
\end{minted}
\end{multicols}
+\subsubsection{Standalone values}
+
+Standalone values are values without a key. They are converted into an
+array. In Lua an array is a table with numeric indexes (The first index
+is 1).
+
+\begin{multicols}{2}
+\begin{minted}{latex}
+\luakeysdebug{one,two,three}
+\end{minted}
+\columnbreak
+\begin{minted}{lua}
+{ 'one', 'two', 'three' }
+\end{minted}
+
+\noindent
+is equivalent to
+
+\begin{minted}{lua}
+{
+ [1] = 'one',
+ [2] = 'two',
+ [3] = 'three',
+}
+\end{minted}
+\end{multicols}
+
+\noindent
+All recognized data types can be used as standalone values.
+
+\begin{multicols}{2}
+\begin{minted}{latex}
+\luakeysdebug{one,2,3cm}
+\end{minted}
+\columnbreak
+\begin{minted}{lua}
+{ 'one', 2, 5594039 }
+\end{minted}
+\end{multicols}
+
%-----------------------------------------------------------------------
%
%-----------------------------------------------------------------------
@@ -325,7 +406,7 @@ marks must be used.
\section{Exported functions of the Lua module \texttt{luakeys.lua}}
-To learn more about the individual functions (local functions), pleasecommand
+To learn more about the individual functions (local 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
@@ -336,6 +417,8 @@ local luakeys = require('luakeys')
local parse = luakeys.parse
local render = luakeys.render
--local print = luakeys.print -- That would overwrite the built-in Lua function
+local save = luakeys.save
+local get = luakeys.get
\end{minted}
%%
@@ -443,6 +526,26 @@ The output should look like this:
}
\end{minted}
+%%
+%
+%%
+
+\subsection{\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.
+Therefore, it is not necessary to pollute the global namespace to
+store results for the later usage.
+
+%%
+%
+%%
+
+\subsection{\texttt{get(identifier): table}}
+
+The function \lua{get(identifier)} retrieves a saved result from the
+result store.
+
%-----------------------------------------------------------------------
%
%-----------------------------------------------------------------------
@@ -535,8 +638,12 @@ An example of how to use the command in \LaTeX:
\inputminted[linenos=true]{latex}{luakeys-debug.sty}
-\changes{v0.1}{2020/01/17}{Inital release}
-
+\changes{v0.1}{2021/01/18}{Inital release}
+\changes{v0.2}{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)
+}
\pagebreak
\PrintChanges
\pagebreak