diff options
author | Karl Berry <karl@freefriends.org> | 2021-11-06 20:34:49 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2021-11-06 20:34:49 +0000 |
commit | ac65c6f4efd32bedb3d08ad3fb1be79b48d337cb (patch) | |
tree | 2e3cd7ed54fb0dea5be9c6242c934052656d10bd /Master/texmf-dist/doc/luatex/luakeys | |
parent | bf7388665ea358da056548125d48636fc73f045d (diff) |
luakeys (6nov21)
git-svn-id: svn://tug.org/texlive/trunk@60972 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/luatex/luakeys')
-rw-r--r-- | Master/texmf-dist/doc/luatex/luakeys/README.md | 22 | ||||
-rw-r--r-- | Master/texmf-dist/doc/luatex/luakeys/luakeys-debug.tex | 4 | ||||
-rw-r--r-- | Master/texmf-dist/doc/luatex/luakeys/luakeys-doc.pdf (renamed from Master/texmf-dist/doc/luatex/luakeys/luakeys.pdf) | bin | 153582 -> 157648 bytes | |||
-rw-r--r-- | Master/texmf-dist/doc/luatex/luakeys/luakeys-doc.tex | 726 | ||||
-rw-r--r-- | Master/texmf-dist/doc/luatex/luakeys/luakeys.tex | 660 |
5 files changed, 764 insertions, 648 deletions
diff --git a/Master/texmf-dist/doc/luatex/luakeys/README.md b/Master/texmf-dist/doc/luatex/luakeys/README.md index cb4c429d4cd..8c2e5cf8dba 100644 --- a/Master/texmf-dist/doc/luatex/luakeys/README.md +++ b/Master/texmf-dist/doc/luatex/luakeys/README.md @@ -50,3 +50,25 @@ or ``` make test ``` + +### Release a new version + +Update copyright in: + +* LICENSE +* luakeys-debug.sty +* luakeys-debug.tex +* luakeys.lua +* luakeys.sty +* luakeys.tex +* README.md + +Update version in: + +* luakeys-doc.tex +* luakeys-debug.sty +* luakeys.sty + +Summarize the changes in the luakeys-doc.tex as changes. + +Create a new git tag `git tag -sa v0.3`. Prefix the version with “v”. diff --git a/Master/texmf-dist/doc/luatex/luakeys/luakeys-debug.tex b/Master/texmf-dist/doc/luatex/luakeys/luakeys-debug.tex index b63e67e0502..a6cd7c85c21 100644 --- a/Master/texmf-dist/doc/luatex/luakeys/luakeys-debug.tex +++ b/Master/texmf-dist/doc/luatex/luakeys/luakeys-debug.tex @@ -13,8 +13,8 @@ % % The Current Maintainer of this work is Josef Friedrich. % -% This work consists of the files luakeys.lua, luakeys-debug.sty -% and luakeys-debug.tex. +% This work consists of the files luakeys.lua, luakeys.sty, luakeys.tex +% luakeys-debug.sty and luakeys-debug.tex. \directlua{ luakeys = require('luakeys') diff --git a/Master/texmf-dist/doc/luatex/luakeys/luakeys.pdf b/Master/texmf-dist/doc/luatex/luakeys/luakeys-doc.pdf Binary files differindex c65765d5b9f..3c28176a7d2 100644 --- a/Master/texmf-dist/doc/luatex/luakeys/luakeys.pdf +++ b/Master/texmf-dist/doc/luatex/luakeys/luakeys-doc.pdf diff --git a/Master/texmf-dist/doc/luatex/luakeys/luakeys-doc.tex b/Master/texmf-dist/doc/luatex/luakeys/luakeys-doc.tex new file mode 100644 index 00000000000..b7e525fc4ba --- /dev/null +++ b/Master/texmf-dist/doc/luatex/luakeys/luakeys-doc.tex @@ -0,0 +1,726 @@ +\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/luakeys}{github.com/Josef-Friedrich/luakeys}% +} +\date{v0.3 from 2021/11/05} + +\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{Usage} + +%% +% +%% + +\subsection{Using the Lua module \texttt{luakeys.lua}} + +The core functionality of this package is realized in Lua. So you can +use \texttt{luakeys} without using the wrapper \TeX{} files +\texttt{luakeys.sty} and \texttt{luakeys.tex}. + +\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} + +%% +% +%% + +\subsection{Using the Lua\LaTeX{} wrapper \texttt{luakeys.sty}} + +The supplied Lua\LaTeX{} file is quite small: + +\begin{minted}{latex} +\NeedsTeXFormat{LaTeX2e} +\ProvidesPackage{luakeys} +\directlua{luakeys = require('luakeys')} +\end{minted} + +\noindent +It loads the Lua module into the global variable \texttt{luakeys}. + +\begin{minted}{latex} +\documentclass{article} +\usepackage{luakeys} + +\begin{document} + \directlua{ + local keys = luakeys.parse('one,two,three') + tex.print(keys[1]) + tex.print(keys[2]) + tex.print(keys[3]) + } +\end{document} +\end{minted} + +%% +% +%% + +\subsection{Using the plain Lua\TeX{} wrapper \texttt{luakeys.tex}} + +Even smaller is the file \texttt{luakeys.tex}. It consists of only one +line: + +\begin{minted}{latex} +\directlua{luakeys = require('luakeys')} +\end{minted} + +\noindent +It does the same as the Lua\LaTeX{} wrapper and loads the Lua module +\texttt{luakeys.lua} into the global variable \texttt{luakeys}. + +\begin{minted}{latex} +\input luakeys.tex + +\directlua{ + local keys = luakeys.parse('one,two,three') + tex.print(keys[1]) + tex.print(keys[2]) + tex.print(keys[3]) +} +\bye +\end{minted} + +\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> + +<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 + +%% +% +%% + +\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} + +\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} +\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} + +\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} + +%----------------------------------------------------------------------- +% +%----------------------------------------------------------------------- + +\clearpage + +\section{Exported functions of the Lua module \texttt{luakeys.lua}} + +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 +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 +local save = luakeys.save +local get = luakeys.get +\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} + +%% +% +%% + +\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. + +%----------------------------------------------------------------------- +% +%----------------------------------------------------------------------- + +\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}{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) +} +\changes{v0.3}{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” +} +\pagebreak +\PrintChanges +\pagebreak +\PrintIndex +\end{document} diff --git a/Master/texmf-dist/doc/luatex/luakeys/luakeys.tex b/Master/texmf-dist/doc/luatex/luakeys/luakeys.tex index fc465f46aec..68fc92d8ee2 100644 --- a/Master/texmf-dist/doc/luatex/luakeys/luakeys.tex +++ b/Master/texmf-dist/doc/luatex/luakeys/luakeys.tex @@ -1,651 +1,19 @@ -\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/luakeys}{github.com/Josef-Friedrich/luakeys}% -} -\date{v0.2 from 2021/09/19} - -\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{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} - -%% -% -%% - -\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> - -<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 - -%% -% -%% - -\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} - -\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} -\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} - -\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} - -%----------------------------------------------------------------------- +%% luakeys.tex +%% Copyright 2021 Josef Friedrich % -%----------------------------------------------------------------------- - -\clearpage - -\section{Exported functions of the Lua module \texttt{luakeys.lua}} - -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 -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 -local save = luakeys.save -local get = luakeys.get -\end{minted} - -%% +% 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. % -%% - -\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} - -%% +% This work has the LPPL maintenance status `maintained'. % -%% - -\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} - -%% +% The Current Maintainer of this work is Josef Friedrich. % -%% - -\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. - -%----------------------------------------------------------------------- -% -%----------------------------------------------------------------------- - -\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} +% This work consists of the files luakeys.lua, luakeys.sty, luakeys.tex +% luakeys-debug.sty and luakeys-debug.tex. -\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 -\PrintIndex -\end{document} +\directlua{luakeys = require('luakeys')} |