From 63952430a7ccd88a6eab4721dad57e66eb407fff Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Fri, 24 Sep 2021 21:44:17 +0000 Subject: yamlvars (24sep21) git-svn-id: svn://tug.org/texlive/trunk@60602 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/lualatex/yamlvars/README.md | 32 +++ .../texmf-dist/doc/lualatex/yamlvars/YAMLvars.pdf | Bin 0 -> 39208 bytes .../texmf-dist/doc/lualatex/yamlvars/YAMLvars.tex | 264 +++++++++++++++++++++ 3 files changed, 296 insertions(+) create mode 100644 Master/texmf-dist/doc/lualatex/yamlvars/README.md create mode 100644 Master/texmf-dist/doc/lualatex/yamlvars/YAMLvars.pdf create mode 100644 Master/texmf-dist/doc/lualatex/yamlvars/YAMLvars.tex (limited to 'Master/texmf-dist/doc/lualatex') diff --git a/Master/texmf-dist/doc/lualatex/yamlvars/README.md b/Master/texmf-dist/doc/lualatex/yamlvars/README.md new file mode 100644 index 00000000000..f901e1ef358 --- /dev/null +++ b/Master/texmf-dist/doc/lualatex/yamlvars/README.md @@ -0,0 +1,32 @@ +# YAMLvars -- parse a YAML document and create LaTeX definitons + +This LuaLaTeX package provides a YAML parser and some functions to declare and define LaTeX definitions using YAML files. + + + +# License + +Copyright (C) 2021 Kale Ewasiuk + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF +ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED +TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A +PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT +SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR +ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN +ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE +OR OTHER DEALINGS IN THE SOFTWARE. + + + diff --git a/Master/texmf-dist/doc/lualatex/yamlvars/YAMLvars.pdf b/Master/texmf-dist/doc/lualatex/yamlvars/YAMLvars.pdf new file mode 100644 index 00000000000..1d3b1ed2b7d Binary files /dev/null and b/Master/texmf-dist/doc/lualatex/yamlvars/YAMLvars.pdf differ diff --git a/Master/texmf-dist/doc/lualatex/yamlvars/YAMLvars.tex b/Master/texmf-dist/doc/lualatex/yamlvars/YAMLvars.tex new file mode 100644 index 00000000000..e97b325df3b --- /dev/null +++ b/Master/texmf-dist/doc/lualatex/yamlvars/YAMLvars.tex @@ -0,0 +1,264 @@ +% Kale Ewasiuk (kalekje@gmail.com) +% 2021-09-24 +% +% Copyright (C) 2021 Kale Ewasiuk +% +% Permission is hereby granted, free of charge, to any person obtaining a copy +% of this software and associated documentation files (the "Software"), to deal +% in the Software without restriction, including without limitation the rights +% to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +% copies of the Software, and to permit persons to whom the Software is +% furnished to do so, subject to the following conditions: +% +% The above copyright notice and this permission notice shall be included in +% all copies or substantial portions of the Software. +% +% THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF +% ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED +% TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A +% PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT +% SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR +% ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN +% ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +% OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE +% OR OTHER DEALINGS IN THE SOFTWARE. + + +\documentclass{article} +\usepackage{url} +\usepackage{YAMLvars} +\setlength{\parindent}{0ex} +\setlength{\parskip}{0.75em} + +\begin{document} + +{\noindent\huge\bfseries YAMLvars \LARGE -- a YAML variable parser for LuaLaTeX}\\ + 2021-09-24, Kale Ewasiuk, \url{kalekje@gmail.com} + +YAMLvars is a LuaLaTeX-based package to help make definitions or produce LaTeX code using a YAML file. +This package might be useful for you if you want to batch create docummnts +by pushing various sets YAML data to a fixed LaTeX template, +or just find it easier to read document metadata from a YAML file compared to the +standard title, author, etc. commands. + +\section{Package Options} +\leavevmode\llap{\texttt{useyv}\ \ \ }By default, when you specify a YAML variable, it will be defined using \texttt{gdef} +(only if it wasn't defined previously). +If you use this setting, unless otherwise specified, YAML variables will be accessible under +the \texttt{\textbackslash yv\{\}} command. +This also allows numbers and symbols in the variable names. +Note that internally, the variables are stored in the command sequence +\texttt{yv--}. + +\leavevmode\llap{\texttt{parseCLI}\ \ \ }If this option is enabled, any arguments passed to your lualatex compile +command that end in ``.yaml'' will be used, separated by a space. +If two yaml files are passed, the first one will be the declaration file, +and the second will be the parsing file. +They will be used at the beginning of the document. +If one yaml file is passed, it will be treated as a parsing file, so you should +declare the variables somewhere in the preamble. +This option is offered to help with automation scripts. +An example is showin in Section \ref{example}. + +\leavevmode\llap{\texttt{allowundeclared}\ \ \ }% +It might be helpful to define something in your YAML parsing doc without declaring it. +If you want this flexibility, use this setting. Note that eisting definitions will not be overwritten and an error +will br thrown if the name exists. + +\section{Dependencies} +This package contains the \texttt{tinyyaml} Lua package. +If you want to use it for other purposes, you can bring it into Lua by either: +\begin{verbatim} +\directlua{yaml = YAMLvars.yaml} or +\directlua{yaml = require('tinyyaml')} +\end{verbatim} +The distribution: \url{https://github.com/peposso/lua-tinyyaml}\\ +The YAML specification: \url{https://yaml.org/spec/}\\ + +Many of the ``transform'' and ``processing'' functions built-in to this package rely on other packages. +\texttt{penlight}, +\texttt{xspace}, +\texttt{hyperref} for example. + +\section{Declaring variables} +A declaration file can either be parsed with the command \texttt{declareYAMLvarsFile} command, +or, if you want to do it \LaTeX, you can put the YAML code in the \texttt{declareYAMLvars} environment. +It is a declaring YAML docuemnt is (like all YAML) key-value ditionary: +The top level key is the name of the variable to be defined/used. +If the value of the top level is a string: it's interpreted as a single transform function to be applied. +Otherwise, it must +be a table that contains at least one of the following keys:\\ +\texttt{xfm} (transform, may be a string or list of strings),\\ +\texttt{prc} (processing, must be a single string), or \\ +\texttt{dft} (default value, if being defined. Must be a string). + +The default value for variables is the Lua \texttt{nil}. +YAMLvars will first check if the definition exists, if so, an error will be thrown +so that we avoid overwriting. +If the token is available, it is set to a package error, so that if the variable no defined later on, an error will +tell the user they forgot to set it. +This will be overwritten when you parse the variables and assign a value to it. + +You can change the default \texttt{xfm}, \texttt{prc}, or \texttt{dft} by changing +the value (in Lua): \texttt{YAMLvars.xfmDefault = ''} etc. + +Here is an example of a declaration document. +\begin{verbatim} +\begin{declareYAMLvars} +Location: addxspace # sets xfm=addxspace +People: [arrsortlastnameAZ, list2nl] # BAD! don't do. +People: + xfm: [arrsortlastnameAZ, list2nl] # Correct way +Company: + dft: Amazon # Change default only +Revisions: + dft: '1 & \today & initial version \\' + xfm: [sortZA, list2tab] +Rhead: + prc: setRightHead +\end{declareYAMLvars} +\end{verbatim} + + + +\section{Parsing variables} +A YAML file to be parsed will contain the variables as the top level keys, similar to declaring. +The value can be anything you want; as long as you have applied appropriate transform and declaring +functions to it so that it can be useful. For example, a value specified as a YAML list will first be +interpreted as a Lua table (with numeric indexes/keys). You could declare a series of transforms functions +to sort this table, map functions, and convert it to a series of \LaTeX \texttt{\textbackslash item}s. + +Here is an example of a parsing document. + + +\begin{verbatim} +\begin{declareYAMLvars} +Location: Planet Earth +People: # a YAML list + - Some One # turns into Lua table + - No Body +# company assumed Amazon if not set here +Rhead: \today +\end{declareYAMLvars} +\end{verbatim} + + + \section{xfm -- Transform Functions} +These functions accept two arguments: \texttt{(var, val)} where \texttt{var} is the variable (or key) and val is the value. +The transforms are specified as a list and are iteratively applied to the val. +Usually, the final \texttt{xfm} function should produce a string so it can be defined. + +Hint: if for some reason, your \texttt{xfm} and \texttt{prc} depends on other variables, +you can access them within the function +with \texttt{YAMLvars.varsvals} + +\subsection{Defining your own transform functions} +After the package is loaded, you may add your function (somewhere in Lua) +by adding it to the \texttt{YAMLvars.xfm} table. +For example, if you wanted to wrap a variable's value with ``xxx'', here's how you could do that. +\begin{verbatim} +function myfunction(var, val) + return 'xxx'..val..'xxx' +end +YAMLvars.xfm['addmyfunction'] = myfunction +\end{verbatim} + + \section{prc -- Processing Functions} +Like the transform functions, the processing function must accept \texttt{(var, val)}. +Only one processing function is applied to the final (var, val) after the transforms are done. + +This package includes \texttt{gdef} to set a definition, \texttt{yvdef} to define a variable under the \texttt{yv} command. +\texttt{title, author, date} to set \texttt{\textbackslash @title, \textbackslash @author, \textbackslash @date}, +respectively + + \section{Example}\label{example} + + Suppose you had a number of bills of sales in yaml format and wanted to produce some nice pdfs. + The following code shows how this could be done. + + \pagebreak + \vspace*{-5em} + \subsection{The main tex template} + \begin{verbatim} + %% main.tex +\documentclass{article} +\usepackage[paperheight=4in,paperwidth=3in,margin=0.25in]{geometry} +\usepackage[pl,func,extras]{penlight} +\usepackage[useyv,parseCLI]{YAMLvars} % using command line option to make files +\usepackage{hyperref} +\usepackage{xspace} +\usepackage{luacode} + +\setlength{\parindent}{0ex} +\setlength{\parskip}{0.75em} + +\begin{luacode*} -- adding a custom function, put hfill between k-v pairs + function YAMLvars.xfm.kv2hfill(var, val) + local t = {} + for k, v in pairs(val) do + t[#t+1] = k..'\\hfill '..tostring(v) + end + return t + end +\end{luacode*} + + +%! language = yaml +\begin{declareYAMLvars} +Customer: addxspace +Date: addxspace +Items: + xfm: [kv2hfill, arr2itemize] +\end{declareYAMLvars} + +\begin{document} + Bill of sale for: \hfill \yv{Customer}\\ + Purchased: \hfill \yv{Date}\\ + \begin{itemize} + \item[] ITEM \hfill PRICE + \yv{Items} % the yaml variable + \begin{luacode*} + totalcost = pl.tablex.reduce('+', + pl.tablex.values(YAMLvars.varsvals['Items']), 0) + tex.print('\\item[] TOTAL:\\hfill'..tostring(totalcost)) + \end{luacode*} + \end{itemize} +\end{document} + \end{verbatim} + + \subsection{The lua automation script} + \begin{verbatim} +--automate.lua +for f in io.popen('dir .'):lines() do -- get all files and info in cwd + local i, j = f:find('%S*%.yaml') -- find fnames + if i ~= nil then + f = f:sub(i,j) -- extract .yaml file name (no space in fname allowed) + os.execute('lualatex -output-format=pdf main.tex '.. f) + -- compile w/ yaml file as arg + local fnew = f:gsub('yaml', 'pdf') -- file name for output pdf + os.remove(fnew) -- delete if it exists already + os.rename('main.pdf', fnew) -- change main.pdf to same as yaml file name + end +end + \end{verbatim} + +\subsection{The yaml data files} + \begin{verbatim} +# sale1.yaml +Customer: Someone Cold +Date: January 2, 2021 +Items: + Toque: 12 + Mitts: 5.6 + Boots: 80 + +# sale2.yaml +Customer: Someone Warm +Date: July 1, 2021 +Items: + Beer (24 pk): 24 + Sunscreen: 5 + Hat: 12 + \end{verbatim} +\end{document} + -- cgit v1.2.3