Debian Codegraph @

texmf-dist/doc/luatex/lua-placeholders/lua-placeholders-manual.tex

raw
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&#3&\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}