| 1 |
%% lua-placeholders-manual.tex |
| 2 |
%% Copyright 2024 E. Nijenhuis |
| 3 |
% |
| 4 |
% This work may be distributed and/or modified under the |
| 5 |
% conditions of the LaTeX Project Public License, either version 1.3c |
| 6 |
% of this license or (at your option) any later version. |
| 7 |
% The latest version of this license is in |
| 8 |
% http://www.latex-project.org/lppl.txt |
| 9 |
% and version 1.3c or later is part of all distributions of LaTeX |
| 10 |
% version 2005/12/01 or later. |
| 11 |
% |
| 12 |
% This work has the LPPL maintenance status ‘maintained’. |
| 13 |
% |
| 14 |
% The Current Maintainer of this work is E. Nijenhuis. |
| 15 |
% |
| 16 |
% This work consists of the files lua-placeholders.sty |
| 17 |
% lua-placeholders-manual.pdf lua-placeholders.lua |
| 18 |
% lua-placeholders-common.lua lua-placeholders-namespace.lua |
| 19 |
% lua-placeholders-parser.lua and lua-placeholders-types.lua |
| 20 |
|
| 21 |
\documentclass{ltxdoc} |
| 22 |
\usepackage[english]{babel} |
| 23 |
\usepackage[titlepage,authors,rootdir]{gitinfo-lua} |
| 24 |
\usepackage{listings} |
| 25 |
\usepackage{lua-placeholders} |
| 26 |
\usepackage{multicol} |
| 27 |
\usepackage{calc} |
| 28 |
\usepackage{fmtcount} |
| 29 |
\usepackage[nodayofweek]{datetime} |
| 30 |
\usepackage{hyperref,embedfile} |
| 31 |
\usepackage{textcomp} |
| 32 |
\usepackage{attachfile2} |
| 33 |
\usepackage{enumitem} |
| 34 |
\usepackage{biblatex} |
| 35 |
\usepackage[english]{isodate} |
| 36 |
|
| 37 |
\DefineBibliographyStrings{english}{% |
| 38 |
bibliography = {References}, |
| 39 |
} |
| 40 |
|
| 41 |
%! suppress = MissingBibliographystyle |
| 42 |
\bibliography{lua-placeholders-deps} |
| 43 |
|
| 44 |
\embedfile[desc={Parameter Specification Example},filespec=example.pdf]{lua-placeholders-example/example.pdf} |
| 45 |
\embedfile[desc={Parameter Specification Example (YAML)},filespec=example-specification.yaml]{lua-placeholders-example/example-specification.yaml} |
| 46 |
\embedfile[desc={Values Specification Example},filespec=example.yaml]{lua-placeholders-example/example.yaml} |
| 47 |
|
| 48 |
\def\projecturl{https://github.com/Xerdi/lua-placeholders} |
| 49 |
|
| 50 |
\newcommand\showexample[5][15pt]{% |
| 51 |
\begin{minipage}[t]{.5\linewidth - .5 \columnsep}% |
| 52 |
\lstinputlisting[firstnumber={#2},linerange={#3},style=YAML,frame=single,numbers=left,xleftmargin=0pt,numbersep=10pt,columns=fullflexible]{lua-placeholders-example/example-specification.yaml} |
| 53 |
\end{minipage}\hspace*{\columnsep}% |
| 54 |
\begin{minipage}[t]{.5\linewidth - .5 \columnsep}% |
| 55 |
\lstinputlisting[firstnumber={#4},linerange={#5},style=YAML,frame=single,numbers=left,xleftmargin={#1},numbersep=10pt,columns=fullflexible]{lua-placeholders-example/example.yaml} |
| 56 |
\end{minipage}\\% |
| 57 |
} |
| 58 |
|
| 59 |
\usepackage[headsepline]{scrlayer-scrpage} |
| 60 |
\automark[section]{section} |
| 61 |
\lohead{\normalfont Lua placeholders {\footnotesize v\gitversion}} |
| 62 |
\rohead{\normalfont Section \rightmark} |
| 63 |
\cofoot{\thepage} |
| 64 |
|
| 65 |
\begin{document} |
| 66 |
\title{Lua \paramplaceholder{placeholders}\thanks{This document corresponds to \texttt{lua-placeholders} version \gitversion, written on \gitdate}} |
| 67 |
\maketitle |
| 68 |
\begin{abstract} |
| 69 |
A package for producing `example' documents --- parameters rendered as placeholders --- and `actual copy' documents --- parameters replaced with real values --- driven by YAML and a small Lua core. |
| 70 |
Supports Lua\LaTeX\ via \texttt{lua-placeholders.sty} and plain Lua\TeX\ via \texttt{lua-placeholders.tex}. |
| 71 |
\end{abstract} |
| 72 |
|
| 73 |
\tableofcontents |
| 74 |
|
| 75 |
\clearpage |
| 76 |
|
| 77 |
\section{Introduction} |
| 78 |
This package is meant for setting parameters in a document programmatically via YAML\@. |
| 79 |
Parameters can be specified by adding a `recipe' file. |
| 80 |
These recipe files describe the parameter's type, placeholders and/or default values. |
| 81 |
From thereon, the placeholders can be displayed in the document and an `\textit{example}' document can be created. |
| 82 |
An `\textit{actual copy}' document can be created by loading additional payload files, which all must correspond to a recipe file. |
| 83 |
|
| 84 |
\paragraph{A note on engines and naming.} |
| 85 |
\texttt{lua-placeholders} is a Lua module wrapped by two thin engine bridges: a \LaTeX\ package, \texttt{lua-placeholders.sty} for use under Lua\LaTeX, and a plain-format input, \texttt{lua-placeholders.tex} for use under Lua\TeX. |
| 86 |
Throughout this manual, where we write \LaTeX\ we specifically mean Lua\LaTeX, and where we write \TeX\ we mean plain Lua\TeX --- there is no support for any other engine, since the runtime requires Lua\TeX\ primitives. |
| 87 |
Each macro section also states the plain-\TeX\ form when it differs from the \LaTeX\ one (typically by lacking the optional \meta{namespace} argument). |
| 88 |
|
| 89 |
\begin{multicols}{2} |
| 90 |
\subsection{Pros} |
| 91 |
\begin{enumerate}[align=left] |
| 92 |
\item Create an `\textit{example}' or `\textit{actual copy}' document from the same source and YAML recipe. |
| 93 |
\item Integration is as easy as compiling a normal document, especially thanks to the fallback support to JSON. |
| 94 |
\item Supports multiple data types and formatting macros which work in most environments, like \texttt{enumerate} or \texttt{tabular}. |
| 95 |
\item Same Lua core powers both the \LaTeX\ and the \TeX\ bridge; new macros land in both at once. |
| 96 |
\end{enumerate} |
| 97 |
\columnbreak |
| 98 |
\subsection{Cons} |
| 99 |
\begin{enumerate}[align=left] |
| 100 |
\item Requires a Lua-based engine: Lua\LaTeX\ or plain Lua\TeX. Other engines are not supported. |
| 101 |
\item In order for the files to be loaded, commandline option `\texttt{--shell-restricted}' is required. |
| 102 |
\end{enumerate} |
| 103 |
\textbf{Important:} In the 1.x.x series this documentation suggested `\texttt{--shell-escape}' instead, which allows the execution of programs and isn't a requirement for this package since the introduction of \texttt{lua-tinyyaml}. |
| 104 |
\end{multicols} |
| 105 |
|
| 106 |
\begin{multicols}{2} |
| 107 |
\subsection{Security Considerations} |
| 108 |
When using \texttt{--shell-escape} instead of \texttt{--shell-restricted}, one should be aware of the security vulnerabilities it might introduce. |
| 109 |
While it may not seem to be a risk for most users and use cases, for best practices, one should avoid using \texttt{--shell-escape}, since this package is meant for seamless workflow integration, which could introduce vulnerabilities in an unknown variety of ways. |
| 110 |
|
| 111 |
Therefore, I urge everyone that still requires the execution of programs to whitelist those programs in \texttt{shell\_escape\_commands} instead. |
| 112 |
This can be configured system-wide in \texttt{texmf.cnf} or within a Lua initialization script using the \texttt{texconfig} table, thoroughly explained in section 4.1.3, 4.2.4 and 10.4 of the Lua\TeX\ manual\cite{luatex}. |
| 113 |
|
| 114 |
\subsection{Dependencies}\label{sec:deps} |
| 115 |
The Lua core has \emph{no hard dependency} on any \LaTeX\ package. |
| 116 |
The \LaTeX\ bridge (\texttt{.sty}) loads \texttt{textcomp} for the placeholder symbols and \texttt{xspace} for trailing-space handling inside the \texttt{paramobject} environment; the \TeX\ bridge (\texttt{.tex}) needs neither. |
| 117 |
The following packages are \emph{optional} --- the \LaTeX\ bridge falls back gracefully if they are absent: |
| 118 |
\begin{itemize}[align=left,leftmargin=*] |
| 119 |
\item \texttt{numprint}\cite{numprint} for number formatting via \cmd{\paramnumberformat}; without it, numeric values render as-is. |
| 120 |
\item \texttt{isodate}\cite{isodate} for date formatting via \cmd{\paramdateformat} when \texttt{lua-tinyyaml} produces a Lua date table from a \texttt{YYYY-MM-DD} payload scalar. |
| 121 |
\end{itemize} |
| 122 |
Booleans are handled by a self-contained \cmd{\newif}-style flag bridge built on \cmd{\let} and \cmd{\csname}; \texttt{ifthen} is no longer required. |
| 123 |
|
| 124 |
\subsubsection{YAML Support} |
| 125 |
During the 1.x.x series the preferred YAML implementation changed from \texttt{lyaml}\cite{lyaml} to \texttt{lua-tinyyaml}\cite{lua-tinyyaml}. |
| 126 |
The reason for this change is that \texttt{lua-tinyyaml} doesn't require any platform-specific dependencies, such as \texttt{libYAML}\cite{libYAML}. |
| 127 |
|
| 128 |
The older YAML implementation will still function for older installations that do not have \texttt{lua-tinyyaml}. |
| 129 |
As before, when no YAML implementation is found, \texttt{lua-placeholders} will fall back to JSON support. |
| 130 |
|
| 131 |
\subsubsection{\TeX\ vs \LaTeX\ differences}\label{sec:engine-diff} |
| 132 |
The Lua core is identical for both engines; only the bridge file changes. |
| 133 |
Concretely: |
| 134 |
\begin{itemize}[align=left,leftmargin=*] |
| 135 |
\item \textbf{Optional arguments.}\hspace*{0.5em} |
| 136 |
\LaTeX\ macros take an optional \oarg{namespace}; the \TeX\ forms have no optional argument and use \cmd{\curnamespace} (settable via \cmd{\setnamespace}). |
| 137 |
\item \textbf{Environments.}\hspace*{0.5em} |
| 138 |
The \texttt{paramobject} environment is a \cmd{\begin}/\cmd{\end} pair under \LaTeX\ and a \cmd{\paramobject}/\cmd{\endparamobject} macro pair under \TeX. |
| 139 |
\item \textbf{Hooks.}\hspace*{0.5em} |
| 140 |
Under \LaTeX\ each \cmd{\loadrecipe} fires \texttt{namespace/}\meta{name} via \texttt{lthooks}, and each \cmd{\loadpayload} fires \texttt{namespace/}\meta{name}\texttt{/loaded}; under \TeX\ no hook system is available so the emissions are skipped at the Lua level. |
| 141 |
The parameter state is fully populated either way --- only attached callbacks are unavailable in \TeX. |
| 142 |
\item \textbf{Booleans.}\hspace*{0.5em} |
| 143 |
Same call shape on both sides (\cmd{\paramnewbool} / \cmd{\paramsetbool}); the bridge backs them with \cmd{\let}-based flags rather than \cmd{\newif} so they work identically without \texttt{ifthen}. |
| 144 |
\item \textbf{Engine wrappers} (\cmd{\paramnumberformat}, \cmd{\paramdateformat}, \cmd{\paramfieldterm}).\hspace*{0.5em} |
| 145 |
\LaTeX\ wires them to \texttt{numprint}, \texttt{isodate} and \cmd{\xspace}; \TeX\ leaves them as plain pass-throughs. |
| 146 |
See \S\ref{sec:bridges}. |
| 147 |
\end{itemize} |
| 148 |
\end{multicols} |
| 149 |
|
| 150 |
\section{Usage} |
| 151 |
This section describes the basic commands of \texttt{lua-placeholders}. |
| 152 |
For more detail about type specific commands or the behavior of types with commands described here, see section~\ref{sec:spec}.\\ |
| 153 |
|
| 154 |
\subsection{Configuration} |
| 155 |
\DescribeMacro{\strictparams} In order to give an error when values are missing, the \cmd{\strictparams}\footnote{The \cmd{\strictparams} command is still under development.} command can be used. |
| 156 |
Make sure to do it before loading any \meta{recipe} and \meta{payload} files. |
| 157 |
Identical form in \TeX. |
| 158 |
|
| 159 |
\DescribeMacro{\loadrecipe} |
| 160 |
In order to load a recipe the macro \cmd{\loadrecipe}\oarg{namespace}\marg{filename} can be used. |
| 161 |
Where the \meta{filename} is a YAML file with its corresponding extension. |
| 162 |
The optional \meta{namespace} is only a placeholder in order to prevent any conflicts between duplicate \meta{key}s. |
| 163 |
If left out, the \meta{namespace} defaults to the base name of the filename. |
| 164 |
\DescribeMacro{\loadpayload} The same behaviour counts for \cmd{\loadpayload}\oarg{namespace}\marg{filename}. |
| 165 |
The order of loading \meta{recipe} and \meta{payload} files doesn't matter. |
| 166 |
If the \meta{payload} file got loaded first, it will be yielded until the corresponding \meta{recipe} file is loaded. |
| 167 |
The hook emissions on each load are described in section~\ref{sec:engine-diff} (\LaTeX\ only). |
| 168 |
|
| 169 |
Plain \TeX\ form: \cmd{\loadrecipe}\marg{filename} and \cmd{\loadpayload}\marg{filename} take only the filename. |
| 170 |
The active namespace is whatever \cmd{\curnamespace} expands to at call time --- defaulting to \cmd{\jobname} and adjustable with \cmd{\setnamespace}. |
| 171 |
|
| 172 |
All other macros of this package also take the optional \meta{namespace}, which by default is equal to \cmd{\jobname}. |
| 173 |
\DescribeMacro{\setnamespace} This default \meta{namespace} can be changed with \cmd{\setnamespace}\marg{new default namespace}. |
| 174 |
Identical form in \TeX.\\ |
| 175 |
|
| 176 |
\subsection{Displaying Parameters} |
| 177 |
For displaying variables, the commands \cmd{\param} and \cmd{\PARAM} share the same interface. |
| 178 |
\DescribeMacro{\param} The most trivial, displaying the variable as-is, is \cmd{\param}\oarg{namespace}\marg{key}. |
| 179 |
\DescribeMacro{\PARAM} The \cmd{\PARAM} however, shows the value as upper case. |
| 180 |
Plain \TeX\ forms: \cmd{\param}\marg{key} and \cmd{\PARAM}\marg{key} (no optional argument; namespace comes from \cmd{\curnamespace}). |
| 181 |
|
| 182 |
In some cases, it's required to output the text without any \TeX\ related functionality. |
| 183 |
Another case is that some environments don't take macros with optional arguments well. |
| 184 |
\DescribeMacro{\rawparam} For these cases there is \cmd{\rawparam}\marg{namespace}\marg{key}, which takes the namespace as mandatory argument, instead of optional, and doesn't output fancy \TeX\ placeholders. |
| 185 |
Plain \TeX\ form: \cmd{\rawparam}\marg{key} (single argument; namespace from \cmd{\curnamespace}).\\ |
| 186 |
|
| 187 |
\DescribeMacro{\hasparam} To check whether a parameter is set, the \cmd{\hasparam}\oarg{namespace}\marg{key}\marg{true case}\marg{false case} command is used. |
| 188 |
Plain \TeX\ form: drop the optional namespace --- \cmd{\hasparam}\marg{key}\marg{true case}\marg{false case}. |
| 189 |
|
| 190 |
\subsection{Engine bridges}\label{sec:bridges} |
| 191 |
The Lua core never references package-specific commands directly; it emits the following wrappers, which the bridge file (\texttt{.sty} for \LaTeX, \texttt{.tex} for \TeX) backs with engine-appropriate behaviour. |
| 192 |
Override any of them in your own preamble before the bridge is loaded if you need different formatting. |
| 193 |
\begin{description}[font=\ttfamily] |
| 194 |
\item[\textbackslash paramnumberformat\marg{N}] |
| 195 |
Numeric values pass through here. |
| 196 |
\LaTeX\ default: \cmd{\numprint}\marg{N} when \texttt{numprint} is loaded, otherwise \meta{N} as-is. |
| 197 |
\TeX\ default: \meta{N} as-is. |
| 198 |
\item[\textbackslash paramdateformat\marg{Y}\marg{M}\marg{D}] |
| 199 |
\texttt{YYYY-MM-DD} payload scalars (parsed as a Lua date table by \texttt{lua-tinyyaml}) pass through here. |
| 200 |
\LaTeX\ default: \cmd{\printdateTeX}\marg{Y/M/D} when \texttt{isodate} is loaded, otherwise \meta{Y}/\meta{M}/\meta{D} as text. |
| 201 |
\TeX\ default: \meta{Y}/\meta{M}/\meta{D} as text. |
| 202 |
\item[\textbackslash paramfieldterm] |
| 203 |
Appended after each field binding inside the \texttt{paramobject} environment. |
| 204 |
\LaTeX\ default: \cmd{\xspace}. |
| 205 |
\TeX\ default: empty (the author writes \cmd{\name}\cmd{\space} or \cmd{\name}\texttt{\{\}} explicitly). |
| 206 |
\end{description} |
| 207 |
|
| 208 |
\clearpage |
| 209 |
|
| 210 |
\section{Parameter Specification}\label{sec:spec} |
| 211 |
Every parameter specified has a \meta{type} set. |
| 212 |
Optionally there is a choice between setting a \meta{default} or a \meta{placeholder} for the parameter. |
| 213 |
\begin{description} |
| 214 |
\item[bool] Next to the textual representation of \textit{true} and \textit{false}, the bridge tracks each boolean as a \cmd{\newif}-style flag. |
| 215 |
Therefore, only the \meta{default} setting makes sense.\\[5pt] |
| 216 |
\hspace*{5pt}\parbox{\linewidth-5pt}{% |
| 217 |
\hfill\texttt{Recipe}\hfill\hspace*{\columnsep}% |
| 218 |
\hfill\texttt{Payload}\hfill\hspace*{\columnsep}}\\% |
| 219 |
\showexample{1}{1-3}{1}{1-1} |
| 220 |
\DescribeMacro{\param} |
| 221 |
With a boolean type the \cmd{\param}\oarg{namespace}\marg{name} returns either \textit{true} or \textit{false}. |
| 222 |
\DescribeMacro{\ifparam} |
| 223 |
Additionally, it provides the \cmd{\ifparam}\oarg{namespace}\marg{name}\marg{true code}\marg{false code} command for top level boolean types. |
| 224 |
The flag is set via \cmd{\paramsetbool} and tested with \cmd{\csname if}\meta{name}\cmd{\endcsname}, which supports spaces in names without any package dependency (no \texttt{ifthen} is needed). |
| 225 |
Plain \TeX\ form: \cmd{\ifparam}\marg{name}\marg{true code}\marg{false code} (no optional namespace). |
| 226 |
\item[string] representing a piece of text. |
| 227 |
Values are passed through to \TeX\ verbatim --- only embedded newlines are normalised to spaces. |
| 228 |
\TeX-special characters (\texttt{\textbackslash}, \texttt{\%}, \texttt{\#}, \texttt{\&}, \texttt{\_}, \texttt{\$}, \texttt{\^{}}, \texttt{\~{}}) are \emph{not} escaped: pass an unescaped \texttt{\%} and \TeX\ will treat the rest of the value as a comment, pass a bare \texttt{\&} and you'll get a misplaced-alignment-tab error, etc. |
| 229 |
Escape them in the YAML payload using their usual \LaTeX\ forms (e.g.\ \texttt{\textbackslash\%} for a literal percent, \texttt{\textbackslash\&} for an ampersand, \texttt{\textbackslash textbackslash} for a backslash).\\ |
| 230 |
\showexample{4}{4-6}{2}{2-2} |
| 231 |
\DescribeMacro{\param} A string type can easily be placed in \LaTeX\ using the \cmd{\param} command. |
| 232 |
|
| 233 |
\paragraph{YAML date caveat.} |
| 234 |
When the YAML payload is parsed by \texttt{lua-tinyyaml}, scalars matching the ISO~8601 date pattern \texttt{YYYY-MM-DD} are returned as a Lua table \texttt{\{year=,~month=,~day=\}} rather than a string. |
| 235 |
\texttt{lua-placeholders} hands the three components to \cmd{\paramdateformat}\marg{Y}\marg{M}\marg{D} (see~\ref{sec:bridges}); the \LaTeX\ bridge wraps that in \cmd{\printdateTeX} from \texttt{isodate}\cite{isodate} when available, and the \TeX\ bridge prints \meta{Y}/\meta{M}/\meta{D} as text. |
| 236 |
The \texttt{date~example} field below illustrates this:\\ |
| 237 |
\showexample{7}{7-9}{3}{3-3} |
| 238 |
Note that \cmd{\rawparam} bypasses this conversion and will not produce useful output for a date-typed value. |
| 239 |
The \texttt{lyaml} fallback and JSON do not perform this conversion --- the same \texttt{YYYY-MM-DD} payload is delivered as a plain string instead. |
| 240 |
\item[number] representing a number, like the number type of Lua. |
| 241 |
In most cases it's necessary to use \meta{default} instead of \meta{placeholder}, especially when the number is used in calculations, since a placeholder will cause errors in \LaTeX\ calculations.\\ |
| 242 |
\showexample{10}{10-12}{4}{4-4} |
| 243 |
\DescribeMacro{\param} |
| 244 |
A number type can be used with \cmd{\param}, just like the string type. |
| 245 |
In the 1.x.x series there was a special command \cmd{\numparam}, which is now deprecated as it is the default implementation for number types using \cmd{\param}. |
| 246 |
Numeric values pass through \cmd{\paramnumberformat} (see~\ref{sec:bridges}); the \LaTeX\ bridge wraps in \cmd{\numprint} from \texttt{numprint}\cite{numprint} when loaded, the \TeX\ bridge prints the value as-is. |
| 247 |
The same behaviour applies to number values inside a \texttt{list}, \texttt{object} or \texttt{table}. |
| 248 |
If you need a nonformatted version of the number, use \cmd{\rawparam} instead. |
| 249 |
\item[list] representing a list of values. |
| 250 |
The simplest form sets the item shape with \meta{item type} (one of \texttt{string}, \texttt{number}, \texttt{bool}). |
| 251 |
For nested complex item types, use the long form \meta{item}: a full nested parameter spec, e.g.\ \texttt{item: \{type: object, fields: \dots\}} or \texttt{item: \{type: table, columns: \dots\}}. |
| 252 |
A \meta{default} setting can be set. |
| 253 |
Due to its structure, a \meta{placeholder} would be somewhat incompatible with the corresponding macros; instead, set placeholder content as children of the \meta{default} list.\\ |
| 254 |
\showexample{13}{13-18}{5}{5-7} |
| 255 |
\DescribeMacro{\param} |
| 256 |
Command \cmd{\param} concatenates every item with command \cmd{\paramlistconjunction}. |
| 257 |
\DescribeMacro{\paramlistconjunction} |
| 258 |
By default, the conjunction is set to `\texttt{,\textasciitilde}'. |
| 259 |
|
| 260 |
\DescribeMacro{\forlistitem} |
| 261 |
There's also the \cmd{\forlistitem}\oarg{namespace}\marg{name}\marg{csname} command, which takes an additional \meta{csname} and will execute it for every item in the list. |
| 262 |
For primitive item types the \meta{csname} is invoked with the value as its single argument. |
| 263 |
For complex item types (\texttt{object}, \texttt{list}, \texttt{table}) each item is pushed onto the lookup context: object items expose every field as a direct \cmd{\<fieldname>} macro, while list/table items are bound under the synthetic key \texttt{self} so the row macro can drill in with \cmd{\fortablerow}\marg{self}\marg{...} or \cmd{\forlistitem}\marg{self}\marg{...}. |
| 264 |
Plain \TeX\ form: \cmd{\forlistitem}\marg{name}\marg{csname} (no optional namespace). |
| 265 |
\item[object] representing a list of key value pairs. |
| 266 |
This parameter type requires a \meta{fields} specification to be set. |
| 267 |
Each field is itself a parameter spec, so \texttt{bool}, \texttt{number}, \texttt{string} as well as nested \texttt{list}, \texttt{object} and \texttt{table} types are all permitted.\\ |
| 268 |
\showexample{19}{19-30}{8}{8-11} |
| 269 |
There is no support for the \cmd{\param} command. |
| 270 |
\DescribeMacro{\paramfield} |
| 271 |
In order to show to contents there is the \cmd{\paramfield}\oarg{namespace}\marg{name}\marg{field} command. |
| 272 |
However, unlike the common command \cmd{\param}, the command \cmd{\hasparam} does work with object types. |
| 273 |
Plain \TeX\ form: \cmd{\paramfield}\marg{name}\marg{field}. |
| 274 |
|
| 275 |
\DescribeEnv{paramobject} There's also the \texttt{paramobject} environment, which takes an optional \meta{namespace} and the \meta{name} of the object as arguments and then defines for every primitive field name a corresponding command. |
| 276 |
Each binding is appended with \cmd{\paramfieldterm} (\cmd{\xspace} under \LaTeX, empty under \TeX) so the author doesn't have to end the command with accolades `\{\}' to get the expected output. |
| 277 |
Complex (list, object, table) sub-fields are not flattened to a macro; they remain reachable inside the environment via \cmd{\forlistitem}\marg{field}\marg{...}, \cmd{\paramfield}\marg{field}\marg{...} (for nested objects), \cmd{\fortablerow}\marg{field}\marg{...}, etc.\\ |
| 278 |
Plain \TeX\ form: \cmd{\paramobject}\marg{name}~\dots~\cmd{\endparamobject} (a macro pair instead of a \cmd{\begin}/\cmd{\end} environment). |
| 279 |
|
| 280 |
\item[table] representing a table. |
| 281 |
This parameter type requires a \meta{columns} specification to be set. |
| 282 |
The \meta{columns} describes each column by name with its own type specification. |
| 283 |
Each column may be of any type --- \texttt{bool}, \texttt{number}, \texttt{string}, or a nested \texttt{list}, \texttt{object} or \texttt{table} --- and is reached from the row macro via the corresponding type-specific command (\cmd{\paramfield}, \cmd{\forlistitem}, nested \cmd{\fortablerow}).\\ |
| 284 |
\showexample[20pt]{31}{31-39}{12}{12-16} |
| 285 |
\DescribeMacro{\fortablerow} |
| 286 |
Like the object, the table has no support for \cmd{\param}, but comes with a table-specific command \cmd{\fortablerow}\oarg{namespace}\marg{name}\marg{csname}. |
| 287 |
The control sequence name \meta{csname} is a user-defined command with no arguments, containing any of the column names in a command form. |
| 288 |
For example, the name \texttt{example} would be accessible as \cmd{\example} in the user-defined command body. |
| 289 |
Cells do not require braces; the column macros expand naturally inside \TeX, so \texttt{\textbackslash example} works the same way as \texttt{\textbackslash example\{\}}. |
| 290 |
Plain \TeX\ form: \cmd{\fortablerow}\marg{name}\marg{csname} (no optional namespace). |
| 291 |
|
| 292 |
Internally, \cmd{\fortablerow} pushes a frame onto a context stack shared with \texttt{paramobject} and \cmd{\forlistitem}, then rebinds every primitive column to a global control sequence via \texttt{token.set\_macro} just before each invocation of \meta{csname}. |
| 293 |
Because the column macros are real \TeX\ control sequences --- not string substitutions --- prefix collisions between column names (e.g.\ a column \texttt{item} alongside \texttt{item\_name}) are no longer a concern, and unreferenced columns in \meta{csname} are silently dropped instead of leaking partial substitutions. |
| 294 |
|
| 295 |
\paragraph{Underscore in a column name.} |
| 296 |
\cmd{\token.set\_macro} is catcode-agnostic, so it can define a control sequence \cmd{\item\_name} regardless of the catcode of \texttt{\_} at the time \cmd{\fortablerow} runs. |
| 297 |
\emph{Using} that control sequence in \meta{csname}, however, requires \texttt{\_} to have letter catcode (\texttt{11}) when the row macro is parsed --- otherwise \TeX\ reads \cmd{\item\_name} as \cmd{\item} followed by the subscript token \texttt{\_} and the letters \texttt{name}. |
| 298 |
The standard idiom is to wrap the row macro definition in \cmd{\ExplSyntaxOn}~\dots\cmd{\ExplSyntaxOff}, which temporarily flips \texttt{\_} (and \texttt{:}) to letter catcode for the parser: |
| 299 |
\begin{verbatim} |
| 300 |
\ExplSyntaxOn |
| 301 |
\cs_new:Npn \rowU {\item & \item_name & \unit_price \\} |
| 302 |
\ExplSyntaxOff |
| 303 |
\fortablerow{my-table}{rowU}\end{verbatim} |
| 304 |
Once \cmd{\rowU} has been tokenised, the catcode of \texttt{\_} no longer matters at expansion time. |
| 305 |
|
| 306 |
\end{description} |
| 307 |
|
| 308 |
\clearpage |
| 309 |
% Enlarge the \textwidth for the coming pages |
| 310 |
\addtolength\textwidth{2cm}% |
| 311 |
\setlength\linewidth{\textwidth}% |
| 312 |
\addtolength\oddsidemargin{-2cm}% |
| 313 |
\addtolength\evensidemargin{-1cm}% |
| 314 |
|
| 315 |
\printbibliography[heading=bibnumbered] |
| 316 |
|
| 317 |
\clearpage |
| 318 |
\begin{multicols}{2} |
| 319 |
\section{Change Log} |
| 320 |
\newcommand\setcurdate[1]{\def\curdate{#1}}% |
| 321 |
\newcommand\commitline[4]{% |
| 322 |
\ifthenelse{\equal{#2}{\curdate}}{}{\item[] \hrulefill~{\scriptsize\printdate{#2}}\def\curdate{#2}}% |
| 323 |
\item[\href{https://github.com/Xerdi/lua-placeholders/commit/#4}{#4}]% |
| 324 |
{\small\fontfamily{\sfdefault}\selectfont#1}% |
| 325 |
\ifx&\else\\% |
| 326 |
{\footnotesize#3}% |
| 327 |
\fi% |
| 328 |
} |
| 329 |
\newcommand\formatversion[3]{% |
| 330 |
{\bfseries\large Release \href{https://github.com/Xerdi/lua-placeholders/releases/tag/#1}{#1}}~\hrulefill~% |
| 331 |
\gittag[(taggerdate)(taggerdate:short)(authordate:short)]{setcurdate}{#1}% |
| 332 |
{\scriptsize\gittag[(taggerdate)(taggerdate:short)(authordate:short)]{printdate}{#1}} |
| 333 |
\begin{description}[font=\small\ttfamily,itemsep=1pt] |
| 334 |
\forgitcommit[s,as,b,h]{commitline}{#3,flags={no-merges}} |
| 335 |
\end{description} |
| 336 |
\bigskip |
| 337 |
}% |
| 338 |
\forgittagseq{formatversion} |
| 339 |
\end{multicols} |
| 340 |
\clearpage |
| 341 |
|
| 342 |
\section{Example} |
| 343 |
|
| 344 |
The source file \texttt{example.tex} is a perfect demonstration of all macros in action. |
| 345 |
It shows perfectly what happens when there's a \meta{payload} file loaded and when not. |
| 346 |
The result of this example \attachfile[icon=Paperclip,description={Lua Parameters Example v\gitversion}]{lua-placeholders-example/example.pdf} is attached in the digital version of this document. |
| 347 |
|
| 348 |
\lstinputlisting[language={[LaTeX]TeX},frame=single,caption={\ttfamily example.tex},captionpos=t,numbers=left,keywordsprefix={\\},firstnumber=20,firstline=20,columns=fullflexible]{lua-placeholders-example/example.tex} |
| 349 |
\end{document} |