summaryrefslogtreecommitdiff
path: root/macros/luatex/generic/penlight/penlight.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/luatex/generic/penlight/penlight.tex')
-rw-r--r--macros/luatex/generic/penlight/penlight.tex100
1 files changed, 62 insertions, 38 deletions
diff --git a/macros/luatex/generic/penlight/penlight.tex b/macros/luatex/generic/penlight/penlight.tex
index 869fda37ed..f3ee02f2ec 100644
--- a/macros/luatex/generic/penlight/penlight.tex
+++ b/macros/luatex/generic/penlight/penlight.tex
@@ -1,5 +1,5 @@
% Kale Ewasiuk (kalekje@gmail.com)
-% 2022-10-15
+% 2022-10-22
% Copyright (C) 2021-2022 Kale Ewasiuk
%
% Permission is hereby granted, free of charge, to any person obtaining a copy
@@ -29,6 +29,7 @@
\newcommand{\cmd}[1]{\texttt{\detokenize{#1}}}
\newcommand{\qcmd}[1]{``\cmd{#1}''}
\usepackage{url}
+\usepackage{xcolor}
\usepackage{showexpl}
\lstset{explpreset={justification=\raggedright,pos=r,wide=true}}
\setlength\ResultBoxRule{0mm}
@@ -57,11 +58,14 @@
\subtitle{Lua libraries for use in LuaLaTeX}
\begin{document}
+
+%{\Huge todo add split to text example with ltxexample\\reference the exact version of penlight used in this library. consider no globals by default\\ COVERT existing examples to extras globals, document hyperref}
+
\maketitle
- The official documentation for the Lua library can be found here:\\
+ Documentation for the Lua library this includes can be found here:\\
\mbox{\url{https://lunarmodules.github.io/Penlight}}
- \\
+ \\ This package uses version \cmd{1.13.1}
\subsection*{Required Package Option}
The first option sent to this package MUST be one of: \\
@@ -80,7 +84,7 @@ penlight = require'penlight'
-- below is optional
__SKIP_TEX__ = true --only required if you want to use
--penlightextras without a LaTeX run
--- __PL_NO_GLOBALS__ = true -- optional, skip global definitions
+__PL_GLOBALS__ = true -- optional, include global definitions
__SKIP_LUAKEYS__ = true -- luakeys is laoded in penlightextras be default, you may skip it with this
require'penlightextras'
\end{verbatim}
@@ -101,8 +105,8 @@ require'penlightextras'
\texttt{func} & allows placehold expressions eg. \texttt{\_1+1} to be used \\
& this will be ran in pre-amble: \texttt{penlight.utils.import('pl.func')}\\
& \url{https://lunarmodules.github.io/Penlight/libraries/pl.func}\\
- \texttt{\llap{extras}noglobals} & does the above three (\cmd{func,stringx,format}); adds some additional functions to \cmd{penlight} module; and adds the \cmd{pl.tex} sub-module.\\
- \texttt{extras} & does the above \texttt{extrasnoglobals} but makes many of the functions global variables.
+ \texttt{extras} & does the above three (\cmd{func,stringx,format}); adds some additional functions to \cmd{penlight} module; and adds the \cmd{pl.tex} sub-module.\\
+ \texttt{extrasglobals} & does the above \texttt{extras} but makes many of the functions global variables as well.
\end{tabular}
@@ -114,7 +118,12 @@ If \cmd{extras} is used, the following Lua globals will be defined:\\
\subsubsection*{Misc stuff}
\llcmd{__SKIP_TEX__} If using package with \cmd{texlua}, set this global before loading \cmd{penlight}\\
-\llcmd{__PL_NO_}\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}\\
+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{__SKIP_LUAKEYS__}\\
+\cmd{__PL_NO_HYPERREF__}\\
+\cmd{__PL_EXTRAS__} false, 1 or 2\\
+
\llcmd{hasval(x)} Python-like boolean testing\\
\llcmd{COMP'xyz'()} Python-like comprehensions:\\\url{https://lunarmodules.github.io/Penlight/libraries/pl.comprehension.html}\\
\llcmd{math.mod(n,d)}, \cmd{math.mod2(n)} math modulous\\
@@ -124,11 +133,11 @@ If \cmd{extras} is used, the following Lua globals will be defined:\\
\llcmd{pl.}\cmd{Char(n)} return letter corresponding to 1=A, 2=B, etc.\\
\llcmd{kpairs(t), }\cmd{npairs(t)} iterate over keys only, or include nil value from table ipairs\\
-{\Large todo document all string helper functions}
+
+%{\Large todo document all string helper functions}
\llcmd{pl.utils.}\cmd{filterfiles}\cmd{(dir,filt,rec)} Get files from dir and apply glob-like filters. Set rec to \cmd{true} to include sub directories\\
-\pagebreak
\subsubsection*{\cmd{pl.tex.} module is added}
\llcmd{add_bkt}\cmd{_cnt(n), }\cmd{close_bkt_cnt(n), reset_bkt_cnt} functions to keep track of adding curly brackets as strings. \cmd{add} will return \cmd{n} (default 1) \{'s and increment a counter. \cmd{close} will return \cmd{n} \}'s (default will close all brackets) and decrement.\\
@@ -153,9 +162,45 @@ If \cmd{extras} is used, the following Lua globals will be defined:\\
\llcmd{deccmd}\cmd{(cs, dft, overwrite)} declare a command. If \cmd{dft} (default) is \cmd{nil}, \cmd{cs} is set
to a package warning saying \cmd{'cs' was declared and used in document, but never set}. If \cmd{overwrite}
is true, it will overwrite an existing command (using \cmd{defcmd}), otherwise, it will throw error like \cmd{newcmd}.\\
+\llcmd{get_ref_info(l)}accesses the \cmd{\r@label} and returns a table\\
+
+
+
+
+\subsection*{Macro helpers}
+\cmd{\MakeluastringCommands[def]{spec}} will let \cmd{\plluastring(A|B|C..)} be \cmd{\luastring(N|O|T|F)}
+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.
+
+% BELOW IS FOR TROUBLESHOOTING ABOVE
+%\def\NOTexp{\ONEexp}
+%\def\ONEexp{\TWOexp}
+%\def\TWOexp{\TREexp}
+%\def\TREexp{Fully expanded}
+%
+%\NewDocumentCommand{\luastringExpTest}{m m}{
+% \MakeluastringCommands{#1}
+% \luadirect{texio.write_nl('VVVVVVVVVVVVVVVVVVVVVVVVVVVVV')}
+% \luadirect{texio.write_nl(\plluastringA{#2}..' | Not')}
+% \luadirect{texio.write_nl(\plluastringB{#2}..' | Once')}
+% \luadirect{texio.write_nl(\plluastringC{#2}..' | Twice')}
+% \luadirect{texio.write_nl(\plluastringD{#2}..' | Full')}
+% \luadirect{texio.write_nl('VVVVVVVVVVVVVVVVVVVVVVVVVVVVV')}
+%}
+%
+%\luastringExpTest{ n o t f }{\NOTexp}
+
+
+
+
+\subsection*{Split stuff}
+Splitting text (or a cmd) into oxford comma format via:
+\cmd{\splitToComma[expansion level]{text}{text to split on}}:
+
+\begin{LTXexample}
-\subsection{Split stuff}
-splitToComma:
-\splitToComma{ j doe }{\and}-\\
-\splitToComma{ j doe \and s else }{\and}-\\
-\splitToComma{ j doe \and s else \and a per }{\and}-\\
@@ -163,44 +208,23 @@ splitToComma:
\def\authors{j doe \and s else \and a per \and f guy}
\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.
+\begin{LTXexample}
spliToItems:
\begin{itemize}
\splitToItems{kale\and john}{\and}
\splitToItems{kale -john -someone else}{-}
\end{itemize}
+\end{LTXexample}
-\subsection{Macro helpers}
-\cmd{\MakeluastringCommands[def]{spec}} will let \cmd{\plluastring(A|B|C..)} be \cmd{\luastring(N|O|T|F)}
-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.
-
-
-\def\NOTexp{\ONEexp}
-\def\ONEexp{\TWOexp}
-\def\TWOexp{\TREexp}
-\def\TREexp{Fully expanded}
-
-\NewDocumentCommand{\luastringExpTest}{m m}{
- \MakeluastringCommands{#1}
- \luadirect{texio.write_nl('VVVVVVVVVVVVVVVVVVVVVVVVVVVVV')}
- \luadirect{texio.write_nl(\plluastringA{#2}..' | Not')}
- \luadirect{texio.write_nl(\plluastringB{#2}..' | Once')}
- \luadirect{texio.write_nl(\plluastringC{#2}..' | Twice')}
- \luadirect{texio.write_nl(\plluastringD{#2}..' | Full')}
- \luadirect{texio.write_nl('VVVVVVVVVVVVVVVVVVVVVVVVVVVVV')}
-}
-
-\luastringExpTest{ n o t f }{\NOTexp}
\subsubsection*{global extras}
-If \cmd{extras} is used and NOT \cmd{extrasnoglobals}, then some globals are set.\\
-All \cmd{pl.tex} modules are added.\\
+If \cmd{extrasglobals} is used and NOT \cmd{extras}, many globals are set.\\
+All \cmd{pl.tex} modules are made global.\\
\cmd{hasval}, \cmd{COMP}, \cmd{kpairs}, \cmd{npairs} are globals.\\
-\cmd{pl.tablex} functions are added to the \cmd{table} table.\\
\section*{}
Disclaimer: I am not the author of the Lua Penlight library.