Debian Codegraph @

texmf-dist/doc/lualatex/luatbls/luatbls.tex

raw
1 % Kale Ewasiuk ([email protected])
2 % 2025-02-14
3 % Copyright (C) 2025 Kale Ewasiuk
4 %
5 % Permission is hereby granted, free of charge, to any person obtaining a copy
6 % of this software and associated documentation files (the "Software"), to deal
7 % in the Software without restriction, including without limitation the rights
8 % to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9 % copies of the Software, and to permit persons to whom the Software is
10 % furnished to do so, subject to the following conditions:
11 %
12 % The above copyright notice and this permission notice shall be included in
13 % all copies or substantial portions of the Software.
14 %
15 % THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF
16 % ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
17 % TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
18 % PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT
19 % SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR
20 % ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
21 % ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
22 % OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE
23 % OR OTHER DEALINGS IN THE SOFTWARE.
24
25
26
27 \documentclass[11pt,parskip=half]{scrartcl}
28 \usepackage[default]{lato}
29 \usepackage[left=0.75in,right=0.75in,top=1in,bottom=1in]{geometry}
30 \setlength{\parindent}{0ex}
31 \newcommand{\llcmd}[1]{\leavevmode\llap{\texttt{\detokenize{#1}}}}
32 \newcommand{\cmd}[1]{\texttt{\detokenize{#1}}}
33 \newcommand{\qcmd}[1]{``\cmd{#1}''}
34 \usepackage{url}
35 \usepackage[svgnames]{xcolor}
36 \usepackage{showexpl}
37 \lstset{explpreset={justification=\raggedright,pos=r,hsep=1cm,preset={\color{Navy}\small}}}
38 \setlength\ResultBoxRule{0mm}
39 \lstset{
40 language=[LaTeX]TeX,
41 basicstyle=\ttfamily\footnotesize\color{blue},
42 commentstyle=\ttfamily\footnotesize\color{gray},
43 frame=none,
44 numbers=left,
45 numberstyle=\ttfamily\footnotesize\color{gray},
46 prebreak=\raisebox{0ex}[0ex][0ex]{\color{gray}\ensuremath{\hookleftarrow}},
47 extendedchars=true,
48 breaklines=true,
49 tabsize=4,
50 }
51 \addtokomafont{title}{\raggedright}
52 \addtokomafont{author}{\raggedright}
53 \addtokomafont{date}{\raggedright}
54 \author{Kale Ewasiuk (\url{[email protected]})}
55 \usepackage[yyyymmdd]{datetime}\renewcommand{\dateseparator}{--}
56 \date{\today}
57
58 \usepackage{enumitem}
59
60 \RequirePackage{luatbls}
61
62 \title{luatbls}
63 \subtitle{Create, modify, and use Lua tables from within LaTeX}
64
65
66 \begin{document}
67 %
68
69 %TODO: need options in updating tables or csv
70
71 \maketitle
72
73
74 \subsection*{Introduction}
75
76 This package provides a Lua-table interface based on the \cmd{luakeys} package:\\
77 \url{https://mirror.quantum5.ca/CTAN/macros/luatex/generic/luakeys/luakeys.pdf}\\
78
79 A global table called \cmd{luatbls} is created by loading this package. This table contains all user-defined tables
80 as well as internal package functions and settings.
81 User tables are stored directly under the module's table, so you can access a table within Lua by using:
82 \cmd{luatbls['mytable']} or \cmd{luatbls.mytable}. Further, \cmd{luatbls} can be called directly to obtain a table item by \cmd{luatbls'i'},
83 where \cmd{i} is a ``flexible'' indexing system discussed in the next paragraphs.
84
85 If you want to change the \cmd{luakeys} global parser options, you can adjust them by:\\
86 \cmd{\directlua{luatbls._luakeys.opts.OPTION = VALUE}}\\
87 For debugging, set \cmd{\directlua{luatbls._debug = true}}
88
89
90 In this documentation, arguments are represented as follows:\\
91 \llcmd{t }: table name. If none provided, the most recent is used.\\
92 \llcmd{k }: a string key.\\
93 \llcmd{n }: an integer index.\\
94 \llcmd{v }: a value.\\
95 \llcmd{i }: the flexible indexer to get a single item.\\
96 \llcmd{I }: the flexible indexer to get a single or multiple items.\\
97 \llcmd{keyval }: a key-value string for the table. Standalone values are set to boolean.\\
98 \llcmd{csv }: a key-value string where standalone values are parsed as array-like.\\
99 \llcmd{opts }: options for \cmd{luakeys.parse()}.\\
100 \llcmd{cstemp }: a template for command-sequences, lengths, or toggles. By default is \cmd{ltbl<t><k>}.\\
101
102 There are a few ways to use the index (placeholder \cmd{i}).\\
103 \cmd{t.k} where \cmd{t} is the table name and \cmd{k} is a string key (i.e. uses \cmd{luatbls.t.k}),\\
104 \cmd{t/n} where \cmd{n} is an integer index (i.e. uses \cmd{t.k[n]}); note that negative indexes are allowed where -1 is the last element.
105 Alternatively, \cmd{t} and the symbol can be omitted, and simply pass the element without the table name as a prefix,
106 where the assumed table is the last one that was created or changed to (i.e. the most 'recent' table).
107 In this case, passing a number will assume an integer index.
108
109 To use a \cmd{I},
110 you can select tables and groups of keys by \cmd{t|seq}, or \cmd{t.k}, or \cmd{t/n}.
111 If no \cmd{|./} is provided, the recent table is used and the argument is assumed to be a sequence of keys.
112 \cmd{penlightplus}'s command \cmd{penlight.seq.tbltrain()} syntax is used for \cmd{seq}uences.
113 To summarize what \cmd{seq} can be, a comma-separated list of numbers or keys are used to specify which elements are iterated over.
114 NumPy-like slicing is possibly with \cmd{:} to choose integer ranges.
115 If \cmd{*} is provided,
116 all string keys are iterated.
117 If \cmd{I} is entirely blank, all elements of the recent table are used, which is equivalent to \cmd{t|*,:}.
118
119
120 The \cmd{cstemp} default can be changed with: \cmd{\luadirect{luatbls._cstemp = 'ltbl<t><k>'}},
121 where \cmd{<t>} and \cmd{<k>} are the table and key names. Numerical keys are converted to capital letters: 1->A, 2->B.
122 It is recommended that tables and keys contain letters only for predictable behaviour when using this feature.
123 If the value of a tbl's key is a table, every element in that table is defined, and the keys of that nested table is
124 appended to the cs: \cmd{ltbl<t><k1><k2>} (noting that numbers are converted to letters).
125
126 Note: nested tables are currently not fully supported. Some variations of commands have an \cmd{E} suffix which indicates
127 that nested elements can be explicitly indexed.
128 The table name must be specified, and the validity of table names and keys are not checked.
129
130 The \cmd{tbl} commands fully expand the
131 \cmd{t}, \cmd{k}, \cmd{n}, \cmd{i}, and \cmd{I} arguments. However a variation with an \cmd{N}-appended is usually provided
132 which will not expand the \cmd{v}, \cmd{keyval}, or \cmd{csv} args.
133
134
135 %%%
136 \subsection*{Creating Tables}
137
138 %\tblfrkv{kale}{kale=ewasiuk}
139 %\luadirect{penlight.wrth(luatbls'kale.kale')}
140
141 \cmd{\tblnew{t}} declares a new table with name \cmd{t}\\
142 \cmd{\tblchg{t}} changes the 'recent' table\\
143 \\
144 \cmd{\tblfrkv{t}{keyval}[opts]} new table from key-vals using \cmd{luakeys} \\
145 \cmd{\tblfrkvN{t}{keyval}[opts]} does not expand key-val string \cmd{luakeys}. Note:
146 \cmd{opts} are parsed using luakeys with the \cmd{naked_as_value=true}, so booleans must be explicitly set.\\
147 \\
148 \cmd{\tblfrcsv{t}{csv}[opts]} a shorthand \cmd{\tblfrkv{t}{csv}[naked_as_value=true,opts]}, a good way to convert a comma-separated list to an array\\
149 \cmd{\tblfrcsvN{t}{csv}[opts]} same as above, but the csv is not expanded.\\
150 \\
151 \cmd{\tblkvundefcheck} will throw an error if you use define a table from key-values
152 and use a key that was not specified in the luakeys parse options via \cmd{opts.defaults} or \cmd{opts.defs}.\\
153 \\
154 \cmd{\tblenforcechoices{i}{csv}} will throw an error if the value of item \cmd{i} is not in the provided \cmd{csv}
155
156
157 \subsection*{Setting, getting, and modifying}
158
159
160 \cmd{\tblset{i}{v}} sets a value of the table/index \cmd{i} to \cmd{v}\\
161 \cmd{\tblsetN{i}{v}} same as above, but the value is not expanded.\\
162 \\
163 \cmd{\tblget{i}} gets the value and \cmd{tex.sprint()}s it\\
164 \cmd{\tblgetE{t.k}} An 'explicit' version of tbl get. Use this for nested tables. The tbl name must be specified.
165 The validity of table names and keys are not checked.\\
166
167 \cmd{\tblsetE{i}{v}} the explicit version of \cmd{\tblset}. Quotes must be used for strings in the \cmd{v}, and arbitrary lua code can be entered.\\
168
169
170 \begin{LTXexample}
171 \tblfrkv{ex}{a,b,c,first=john,last=smith}%
172 [defaults={x=0,1=one,n=false,y=yes}]
173 \tblget{ex.a}\\
174 \tblset{a}{tRuE!!}
175 \tblget{a}\\
176 \tblget{ex.x}\\
177 \tblget{.x}\\
178 \tbladd{ex.newkey}{val}\tblget{newkey}\\
179 \tbladd{nk}{VAL}\tblget{nk}\\
180 \tblsetE{ex.d}{math.mod2(3)}
181 \tblget{d}
182 \end{LTXexample}
183
184 \begin{LTXexample}
185 \tblfrcsv{EX}{x={1,2,{1,2,3}},name=me}
186 \tblgetE{EX.x[1]}\\
187 \tblsetE{EX.x[3][3]}{99}\\
188 \tblgetE{EX.x[3][3]}\\
189 \tblgetE{EX.name}\\
190 \end{LTXexample}
191
192
193
194 \cmd{\tbladd{i}{v}} add a new value to a table using index method\\
195 \cmd{\tbladdN{i}{v}} above, but don't expand the value argument\\
196 \\
197 \cmd{\tblapp{t}{v}} append a \cmd{v}alue (integer-wise) to a \cmd{t}able\\
198 \cmd{\tblappN{t}{v}}\\
199 \\
200 \cmd{\tblupd{t}{keyval}} update a \cmd{t}able with more \cmd{keyval}s\\
201 \cmd{\tblupdN{t}{keyval}}\\
202 \\
203 \cmd{\tblcon{t}{csv}} concatenate array-style \cmd{csv} at the end of \cmd{t}\\
204 \cmd{\tblconN{t}{csv}}\\
205
206
207
208 \subsection*{Conditionals}
209
210 \cmd{\tblif{i}{tr}[fa]} runs code \cmd{tr} if the item is true else \cmd{fa}\\
211 \cmd{\tblifv{i}{tr}[fa]} runs code \cmd{tr} if the item is truth-y (using \cmd{pl.hasval}) else \cmd{fa}\\
212 \cmd{\tblifeq{i}{v}{tr}[fa]} checks the equivalency of to a user-specified value.
213 The value is fully expanded. Quotes must be used to indicate strings.\\
214 \cmd{\tblifeqstr{i}{v}{tr}[fa]} checks the equivalency of to a user-specified value to a string (uses luastring).
215
216 \begin{LTXexample}
217 \def\JJ{1}
218 \tblfrcsv{x}{n=false,y=true,
219 k0="",kv=val,k2=6,
220 k1=1,k11="1",
221 }
222 \tblif{n}{tr}[FA]\\
223 \tblif{k0}{TR}[fa]\\
224 \tblifv{k0}{tr}[FA]\\
225 \tblifeq{kv}{'val'}{TR}[fa]\\
226 \tblifeq{k2}{6}{TR}[fa]\\
227 \tblifeq{k1}{\JJ}{Tr}
228 \tblifeqstr{k11}{\JJ}{Tr}
229 \end{LTXexample}
230
231
232 \subsection*{Iterating}
233 %TODO use PIPE SYMBOLZ \dsadsa
234
235 \cmd{\tblfor{I}{template}} and \cmd{\tblforN} By default, iterates over all elements (\cmd{seq = *,:}),
236 but arbitrary indices/keys can be iterated over as per \cmd{penlight.seq.tbltrain} syntax.
237 \cmd{<k>} and \cmd{<v>} are placeholders in the template that are replaced by the keys and vals and can be changed by:\\
238 \cmd{\luadirect{luatbls._tblv = '<v>'}}
239
240 If you want to iterate over a second-level table, you must use:\\
241 \cmd{\tblforE} and \cmd{\tblforEN}, and explicitly provide the table and element.
242
243 \begin{LTXexample}
244 \tblfrcsv{x}{n1,k1=v1,n2,n3,n4,
245 k2=v2,k3=v3,n5,n6}
246 1> \tblfor{:}{<k> = <v>; }\\
247 2> \tblfor{*}{<k> = <v>; }\\
248 3> \tblfor{1,*,2::2}{<k> = <v>; }\\
249 4> \tblfor{ x | 1,*,2::2}{<k> = <v>; }\\
250 \tblfrcsv{x}{a,{a,b,c}}
251 5> \tblforE{x[2]}{<k> = <v>; }
252 \end{LTXexample}
253
254
255
256
257 \subsection*{Definitions}
258 \cmd{\tbldef{i}[cstemp]} pushes the value to macro \cmd{cstemp}.\\
259 \cmd{\tblgdef{i}[cstemp]} like above but global definition is used.\\
260
261 \cmd{\tbldefs{I}[cstemp]} and \cmd{\tblgdefs{I}[cstemp]} defines items in table \cmd{t} (use recent if blank).
262
263 %\newlength{\tesst}
264 %\setlength{\tesst}{ 1 cm }
265
266 \begin{LTXexample}
267 \tblfrcsv{EX}{n1,kA=v1,n2,n3,n4,
268 kB=v2,kC=v3,n5,n6}
269 1>\tbldef{kA}[mycs]\mycs\tbldef{kA}\ltblEXkA\\
270 2> \tbldef{EX/1}\ltblEXA
271 \end{LTXexample}
272
273 \begin{LTXexample}
274 \tblfrcsv{EX}{x={1,2,3}}
275 1>\tbldef{x}[mycs]\mycsA, \mycsB \\
276 2>\tbldefs{}\ltblEXxA, \ltblEXxB
277 \end{LTXexample}
278
279
280
281 \cmd{\tbldefxy{i}[cstemp]} splits the value of item by space, and creates two definitions \cmd{<cstemp>x} and \cmd{<cstemp>y}.
282 This might be useful for passing and using tikz coordinates, for example \cmd{xy=0 5}. An error is thrown if the values
283 are non-numeric.\\
284
285 \begin{LTXexample}[width=0.5\linewidth]
286 \tblfrkv{EX}{coords=12 34,other}
287 \tbldefxy{coords}[d]\dx, \dy \\
288 \tbldefxy{coords}\ltblEXcoordsx, \ltblEXcoordsy \\
289 \end{LTXexample}
290
291 \cmd{\tblmaketoggle{i}[cstemp]} will create and set a toggle (see etoolbox) for a truth-y value (see \cmd{pl.hasval})\\
292 \cmd{\tblmaketoggles{I}[cstemp]} will iterate over I and create and set global toggles (see etoolbox) for boolean values\\
293
294 \begin{LTXexample}
295 \tblfrkv{ex}{atog=true,!btog}
296 \tblmakegtoggles{}
297 \iftoggle{ltblexatog}{True}{}\\
298 \iftoggle{ltblexbtog}{}{False}\\
299 \end{LTXexample}
300
301
302 \cmd{\tblmakelength{i}[cstemp]} will 'forcefully' create a length for an element. Glue expressions are permitted. See
303 etoolbox's \cmd{\deflength{}}\\
304 \cmd{\tblmakelengths{I}[cstemp]} will iterate over I and create global lengths for elements that are tex dimensions. If
305 plain numbers are found, \cmd{sp} units are used (in case the \cmd{convert_dimensions=true} luakeys option is used, which converts to sp)\\
306
307
308 \begin{LTXexample}
309 \tblfrkv{ex}{alen=1cm,blen=2cm,clen=10mm*2+2cm}[convert_dimensions=true]
310 \tblmakelengths{}[<k>]
311 I\hspace{\alen}I\\
312 I\hspace{\blen}I\\
313 \tblmakelength{clen}[LEN]
314 I\hspace{\LEN}I
315 \end{LTXexample}
316
317
318
319 \subsection*{Utilities}
320
321 \cmd{\tblapply{I}{func1(<v>,x,y)|:func2}[newtable]} apply a Lua function(s).\\If \cmd{newtable} is provided, a new table is created (and made the recent table)
322 and the original table is preserved.\\ The \cmd{.}, \cmd{/} or \cmd{|} indexer may be used to apply a function
323 to a single value or group of keys.
324 Multiple functions can be applied sequentially, separated by \cmd{|}.
325
326 An arbitrary global function (including additional arguments) can be used,
327 but if a function is prefixed with a \cmd{:}, the class method will be called.
328 The \cmd{stringx} and \cmd{tablex} methods
329 from \cmd{penlight} are used depending on the value's type. See:\\
330 \url{https://lunarmodules.github.io/Penlight/}
331
332 Arguments can be specified with round brackets, where
333 \cmd{<v>} and \cmd{<k>} are used as a placeholder for the values and keys.
334 If no arguments are passed, it is assumed that the value is the only argument.
335 Note that luakeys parses the args, so quotes are not needed around strings for the args.
336
337
338 \begin{LTXexample}[width=0.5\linewidth]
339 \tblfrcsv{ex}{{a, b, c}}
340 \tblapply{}{:concat(<v>,-) | :upper}[new]
341 1> \tblgetE{ex[1][1]}\\
342 2> \tblget{new/1}\\
343 \tblfrcsv{ex}{HelloWorld}
344 \tblapply{}{string.sub(<v>,2,-5)}[new]
345 3> \tblget{new/1}
346 \end{LTXexample}
347
348
349
350
351
352 \cmd{\tblprt{t}} pretty-print the table in console. Using \cmd{\tblprt*{}} will terminate the LaTeX program immediately after and issue an error, which could be useful for debugging.
353
354
355
356 \clearpage
357
358 \luadirect{luatbls._debug = true}
359
360 \subsubsection*{An Example}
361 %
362 \begin{LTXexample}\scriptsize
363 \NewDocumentCommand{\Exampletbl}{m}{
364 \tblfrcsv{ex}{#1}[defaults={sal=Hello}]
365 %\tblkvundefcheck
366 \tblapply{ex.auth}{:list2comma}
367 \tblget{sal}, \tblget{auth}! Thank you for writing such a great novel.
368 My favorite parts were:
369 \begin{description}
370 \tblforEN{ex.chaps}{\item[<k>] <v> }
371 \end{description}
372 It was also very cool to learn that
373 \tblgetE{ex.num[1]}*\tblgetE{ex.num[2]}=
374 \luadirect{tex.sprint(tostring(luatbls.ex.num[1]*luatbls.ex.num[2]))}
375 }
376 \Exampletbl{auth={You,Me,Dupree},
377 chaps={intro=very enticing, climax=thrilling, finale=what a twist!}
378 num={12,13}
379 }
380 \end{LTXexample}
381
382 \tblprt{ex}
383
384
385
386
387
388
389 \end{document}
390
391
392
393
394
395
396 %\begin{luacode*}
397 % function prt_pyth()
398 % t = pl.tbls.pyth
399 % if not t.a then
400 % pl.tex.pkgerror('must pass a= to \\pyth')
401 % elseif not t.b then
402 % t.b = (tonumber(t.c)^2 -
403 % tonumber(t.a)^2)^0.5
404 % elseif not t.c then
405 % t.c = (tonumber(t.a)^2 +
406 % tonumber(t.b)^2)^0.5
407 % end
408 % local t = pl.tbx.fmt(t,'.'..t.d..'f') -- format table according to d decimals
409 % s = 'Right-angle sides a=$a and b=$b form a hypotenuse of c=$c'
410 % pl.tex.prt(s:fmt(t))
411 % end
412 %\end{luacode*}
413 %\NewDocumentCommand{\pyth}{m}{%
414 % \tblfrkv{pyth}{#1}[defaults={a=false,b=false,c=false,d=0,e=extras}]
415 % \luadirect{prt_pyth()}%
416 %}
417 %
418 %\pyth{a=3,c=5}\\
419 %\pyth{a=3.2,b=4.2,d=2}\\
420 %C: \tblget{c}
421 %
422 %\end{LTXexample}
423
424 %
425
426 %
427 %\begin{luacode*}
428 %function prttol()
429 % local dec = penlight.tbls.tol[4] or 1
430 % penlight.wrth(dec,'??')
431 % penlight.tbls.tol[3] = penlight.tbls.tol[3] or 3
432 % penlight.tbls.tol[4] = penlight.tbls.tol[1]*(1.0-penlight.tbls.tol[3]/100.0) + 0.0
433 % penlight.tbls.tol[5] = penlight.tbls.tol[1]*(1.0+penlight.tbls.tol[3]/100.0) + 0.0
434 % --penlight.tbls.tol['k'] = 'fuckboi'
435 % --ttt = pl.tbx.fmt(penlight.tbls.tol, '.3f')
436 % penlight.wrth(('$1\\$2 (\\pmpct{$3} tolerance, $4\\ndash$5\\$2)'):fmt(penlight.tbls.tol, '4=.'..dec..'f, 5=.'..dec..'f'), 'XYZ')
437 %end
438 %\end{luacode*}
439 %\NewDocumentCommand{\prttol}{ m }{\tblfrcsv{tol}{#1}\luadirect{prttol()}}% {50.0,kV,3,P} % 50\us (\pmpct{20} tolerance, 40=--60\us), P is optional and precision of the range (number of decimals)
440 %
441 %\prttol{50,kV,3}
442 %
443 %\begin{luacode*}
444 % pl.wrth(pl.filterfiles('.',true,'.*%.tex'), 'FF')
445 %\end{luacode*}
446
447
448
449
450 %\begin{luacode*}
451 % for t, k, v in luatbls._iter_tbls_vals('my|*,:') do
452 % --for t, k, v in luatbls._iter_tbls_vals('my/1') do
453 % penlight.wrth({t,k,v})
454 % end
455 %\end{luacode*}
456
457