summaryrefslogtreecommitdiff
path: root/macros/luatex/generic/penlightplus/penlightplus.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/luatex/generic/penlightplus/penlightplus.tex')
-rw-r--r--macros/luatex/generic/penlightplus/penlightplus.tex91
1 files changed, 71 insertions, 20 deletions
diff --git a/macros/luatex/generic/penlightplus/penlightplus.tex b/macros/luatex/generic/penlightplus/penlightplus.tex
index 50f87fa38b..fec72b8dfd 100644
--- a/macros/luatex/generic/penlightplus/penlightplus.tex
+++ b/macros/luatex/generic/penlightplus/penlightplus.tex
@@ -1,5 +1,5 @@
% Kale Ewasiuk (kalekje@gmail.com)
-% 2023-07-22
+% 2023-08-27
% Copyright (C) 2021-2023 Kale Ewasiuk
%
% Permission is hereby granted, free of charge, to any person obtaining a copy
@@ -85,20 +85,17 @@ require'penlightplus'
+The following global Lua variables are defined:
-
-\subsection*{}
-
-The following global variables are defined:
-
-\llcmd{__SKIP_TEX__} If using the \cmd{penlightplus} package with \cmd{texlua} (good for troubleshooting), set this global before loading \cmd{penlight}\\
+\cmd{__SKIP_TEX__} If using the \cmd{penlightplus} package with \cmd{texlua} (good for troubleshooting), set this global before loading \cmd{penlight}\\
The gloals flags below are taken care of in the package options:\\
-\llcmd{__PL_}\cmd{GLOBALS__} If using package with \cmd{texlua} and you don't want to set some globals (described in next sections), set this global before to \cmd{true} loading \cmd{penlight}\\
+\cmd{__PL_GLOBALS__} If using package with \cmd{texlua} and you don't want to set some globals (described in next sections), set this global before to \cmd{true} loading \cmd{penlight}\\
\cmd{__PL_NO_HYPERREF__} a flag used to change the behaviour of a function, depending on if you don't use the hyperref package\\
+\cmd{__PDFmetadata__} a table used to store PDF meta-data
\subsubsection*{penlight additions}
-Some functionality is added to penlight/lua.
+Some functionality is added to penlight and Lua.
\llcmd{pl.hasval(x)} Python-like boolean testing\\
\llcmd{COMP'xyz'()} Python-like comprehensions:\\\url{https://lunarmodules.github.io/Penlight/libraries/pl.comprehension.html}\\
@@ -116,18 +113,19 @@ Some functionality is added to penlight/lua.
\llcmd{_NumBkts} internal integer for tracking the number of brackets\\
\llcmd{opencmd(cs)} prints \cmd{\cs}\{ and adds to the bracket counters.\\
\\
-\llcmd{_xNoValue,}\cmd{_xTrue,_xFalse}: \cmd{xparse} equivalents for commands\\
+\llcmd{xNoValue,}\cmd{xTrue,xFalse}: \cmd{xparse} equivalents for commands\\
\\
\llcmd{prt(x),prtn(x)} print without or with a newline at end. Tries to help with special characters or numbers printing.\\
\llcmd{prtl(l),prtt(t)} print a literal string, or table\\
\llcmd{wrt(x), wrtn(x)} write to log\\
-\llcmd{help_wrt}\cmd{(s1, s2)} pretty-print something to console. S2 is a flag to help you find.\\
+\llcmd{help_wrt}\cmd{(s1, s2)} pretty-print something to console. S2 is a flag to help you find., alias is \cmd{wrth}\\
\llcmd{prt_array2d(tt)} pretty print a 2d array\\
\\
\llcmd{pkgwarn}\cmd{(pkg, msg1, msg2)} throw a package warning\\
\llcmd{pkgerror}\cmd{(pkg, msg1, msg2, stop)} throw a package error. If stop is true, immediately ceases compile.\\
\\
-\llcmd{defcmd}\cmd{(cs, val)} like \cmd{\gdef}\\
+\llcmd{defcmd}\cmd{(cs, val)} like \cmd{\gdef}, but note that no special chars allowed in \cmd{cs}(eg. \cmd{@})\\
+\llcmd{defmacro}\cmd{(cs, val)} like \cmd{\gdef}, allows special characters, but any tokens in val must be pre-defined (this uses \cmd{token.set_macro} internally)\\
\llcmd{newcmd}\cmd{(cs, val)} like \cmd{\newcommand}\\
\llcmd{renewcmd}\cmd{(cs, val)} like \cmd{\renewcommand}\\
\llcmd{prvcmd}\cmd{(cs, val)} like \cmd{\providecommand}\\
@@ -139,9 +137,11 @@ is true, it will overwrite an existing command (using \cmd{defcmd}), otherwise,
\subsubsection*{global extras}
-If \cmd{extrasglobals} is used and NOT \cmd{extras}, many additional globals are set for shortcuts\\
-All \cmd{pl.tex} modules are made global.\\
-\cmd{pl.hasval}, \cmd{pl.COMP}, \cmd{pl.utils.kpairs}, \cmd{pl.utils.npairs} become globals with the function name.\\
+If the package option \cmd{globals} is used, many additional globals are set for easier scripting.
+All \cmd{pl.tex} functions, and variables, \cmd{pl.hasval}, \cmd{pl.COMP}, \cmd{pl.utils.kpairs}, \cmd{pl.utils.npairs} become globals.
+\cmd{pl.tablex} is aliased as \cmd{TX} (which also includes all native Lua table functions), and
+\cmd{pl.array2d} is aliased as \cmd{A2d}.
+\\
@@ -150,7 +150,14 @@ All \cmd{pl.tex} modules are made global.\\
based on the letters that \cmd{spec} is set to (or \cmd{def} if nothing is provided)
This is useful if you want to write a command with flexibility on argument expansion.
The user can specify \cmd{n}, \cmd{o}, \cmd{t}, and \cmd{f} (case insensitve) if they want
-no, once, twice, or full expansion.
+no, once, twice, or full expansion. For example, we can control the expansion of args 2 and 3 with arg 1:
+
+\begin{verbatim}
+ \NewDocumentCommand{\splitToComma}{ O{nn} m m }{%
+ \MakeluastringCommands[nn]{#1}%
+ \luadirect{penlight.tex.split2comma(\plluastringA{#2},\plluastringB{#3})}%
+}
+\end{verbatim}
% BELOW IS FOR TROUBLESHOOTING ABOVE
%\def\NOTexp{\ONEexp}
@@ -171,14 +178,57 @@ no, once, twice, or full expansion.
%\luastringExpTest{ n o t f }{\NOTexp}
+\subsection*{Lua boolean expressions for LaTeX conditionals}
+
+\cmd{\ifluax{<Lua expr>}{<do if true>}[<do if false>]} and\\ \cmd{\ifluax{<Lua expr>}{<do if true>}[<do if false>]} for truthy (uses \cmd{penlight.hasval})
+
+\begin{LTXexample}
+\ifluax{3^3 == 27}{3*3*3 is 27}[WRONG]\\
+\ifluax{abc123 == nil}{Var is nil}[WRONG]\\
+\ifluax{not true}{tRuE}[fAlSe]\\
+\ifluax{''}{TRUE}[FALSE]\\
+\ifluaxv{''}{true}[false]\\
+\end{LTXexample}
+
+\subsection*{Creating and using Lua tables in LaTeX}
+\cmd{penlightplus} provides a Lua-table interface. Tables are stored in the
+\cmd{penlight.tbls} table.
+
+
+\cmd{\newtbl{t}} declares a new table with name \cmd{t}\\
+\cmd{\chgtbl{t}} changes the 'recent' table\\
+\cmd{\tblfrkv{t}{key-val string}[luakeys opts]} new table from key-vals, used \cmd{luakeys} \\
+\cmd{\settbl{i}{v}} sets a value of the table/index \cmd{i} to \cmd{v}\\
+\cmd{\gettbl{i}} gets the value and \cmd{tex.sprint()}'s it\\
+\cmd{\deftbl{i}{d}} pushes the value to a \cmd{cs} named \cmd{d}\\
+\cmd{\gdeftbl{i}{d}} pushes the value to a global\\
+\cmd{\iftbl{i}{t}[f]} runs code \cmd{t} if the item is true else \cmd{f}\\
+\cmd{\iftblv{i}{t}[f]} runs code \cmd{t} if the item is truthy else \cmd{f}\\
+
+There are 3 ways to use the index (placeholder \cmd{{i}} above).
+\cmd{t.key} where \cmd{t} is the table name and \cmd{key} is a string key,
+\cmd{t/int} where \cmd{int} is a numeric indexer (ie uses \cmd{t[int]}),
+or simply \cmd{ind} without the table name, where the assumed table is the last one that was created or changed to, (pure-numbers are not treated as strings in this case).
+
+\begin{LTXexample}
+\tblfrkv{my}{a,b,c,first=john,last=smith}[defaults={x=0,1=one,n=false,y=yes}, naked_as_value=true]
+
+\settbl{my/4}{d}\gettbl{my/4}\\
+\settbl{5}{e}\gettbl{5}\\
+\gettbl{my.x}\\
+\iftbl{n}{t}[f]\\
+\iftblv{n}{t}[f]\\
+\iftbl{my.y}{t}[f]\\
+\iftblv{y}{t}[f]\\
+\end{LTXexample}
-\subsection*{Split stuff}
+
+\subsection*{Splitting strings}
Splitting text (or a cmd) into oxford comma format via:
\cmd{\splitToComma[expansion level]{text}{text to split on}}:
\begin{LTXexample}
-
-\splitToComma{ j doe }{\and}-\\
-\splitToComma{ j doe \and s else }{\and}-\\
-\splitToComma{ j doe \and s else \and a per }{\and}-\\
@@ -188,13 +238,14 @@ Splitting text (or a cmd) into oxford comma format via:
\splitToComma[o]{\authors}{\and}
\end{LTXexample}
-The expansion level is up to two characters, \cmd{n|o|t|f}, to control teh expasion of each argument.
+The expansion level is up to two characters, \cmd{n|o|t|f}, to control the expansion of each argument.
+You can do a similar string split but to \cmd{\item} instead of commas with \cmd{\splitToItems}
\begin{LTXexample}
-spliToItems:
\begin{itemize}
\splitToItems{kale\and john}{\and}
\splitToItems{kale -john -someone else}{-}
+ \splitToItems{1,2,3,4}{,}
\end{itemize}
\end{LTXexample}