From 2e35f211a96168b7a51de89304489ec5513f9716 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Sun, 19 Sep 2021 20:46:16 +0000 Subject: luakeys (19sep21) git-svn-id: svn://tug.org/texlive/trunk@60552 c570f23f-e606-0410-a88d-b1316a301751 --- .../doc/luatex/luakeys/luakeys-debug.tex | 35 +++++- Master/texmf-dist/doc/luatex/luakeys/luakeys.pdf | Bin 140586 -> 153582 bytes Master/texmf-dist/doc/luatex/luakeys/luakeys.tex | 121 +++++++++++++++++++-- 3 files changed, 146 insertions(+), 10 deletions(-) (limited to 'Master/texmf-dist/doc/luatex') diff --git a/Master/texmf-dist/doc/luatex/luakeys/luakeys-debug.tex b/Master/texmf-dist/doc/luatex/luakeys/luakeys-debug.tex index 499b1305f67..b63e67e0502 100644 --- a/Master/texmf-dist/doc/luatex/luakeys/luakeys-debug.tex +++ b/Master/texmf-dist/doc/luatex/luakeys/luakeys-debug.tex @@ -20,14 +20,43 @@ luakeys = require('luakeys') } -\def\luakeysdebug#1{ +% https://tex.stackexchange.com/a/418401/42311 +\catcode`\@=11 +\long\def\LuaKeysIfNextChar#1#2#3{% + \let\@tmpa=#1% + \def\@tmpb{#2}% + \def\@tmpc{#3}% + \futurelet\@future\LuaKeysIfNextChar@i% +}% +\def\LuaKeysIfNextChar@i{% + \ifx\@tmpa\@future% + \expandafter\@tmpb + \else + \expandafter\@tmpc + \fi +}% +\def\luakeysdebug@parse@options#1{ + \directlua{ + luakeys.save('debug_options', luakeys.parse('#1')) + } +}% +\def\luakeysdebug@output#1{ { \tt \parindent=0pt \directlua{ - local result = luakeys.parse('#1') + local result = luakeys.parse('\luaescapestring{\unexpanded{#1}}', luakeys.get('debug_options')) tex.print(luakeys.stringify(result, true)) luakeys.print(result) } } -} +}% +\def\luakeysdebug@oarg[#1]#2{% + \luakeysdebug@parse@options{#1}% + \luakeysdebug@output{#2}% +}% +\def\luakeysdebug@marg#1{% + \luakeysdebug@output{#1}% +}% +\def\luakeysdebug{\LuaKeysIfNextChar[{\luakeysdebug@oarg}{\luakeysdebug@marg}}% +\catcode`\@=12 diff --git a/Master/texmf-dist/doc/luatex/luakeys/luakeys.pdf b/Master/texmf-dist/doc/luatex/luakeys/luakeys.pdf index ceaebbee048..c65765d5b9f 100644 Binary files a/Master/texmf-dist/doc/luatex/luakeys/luakeys.pdf and b/Master/texmf-dist/doc/luatex/luakeys/luakeys.pdf differ diff --git a/Master/texmf-dist/doc/luatex/luakeys/luakeys.tex b/Master/texmf-dist/doc/luatex/luakeys/luakeys.tex index 75ffbc8c70d..fc465f46aec 100644 --- a/Master/texmf-dist/doc/luatex/luakeys/luakeys.tex +++ b/Master/texmf-dist/doc/luatex/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} ::= | @@ -137,6 +158,25 @@ lists (\texttt{level1=\{level2=\{key=value,value\}\}}). \alt \alt \alt + + ::= `-' | `+' + + ::= `0' | `1' | `2' | `3' | `4' | `5' | `6' | `7' | `8' | `9' + + ::= `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 -- cgit v1.2.3