summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/luatex/tsvtemplate/tsvtemplate.doc
blob: bae8ac64787bce9c3ba1a61bce3d3ecec1762d66 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108

\input minim-doc.sty

\nopagenumbers
\setbox\notehead=\vtop to 0pt
    {\halign{&\strut#\quad\cr a1&b1&c1\cr a2&b2&c2\cr a3&b3&c3\cr}
    \vskip-\baselineskip}

\startmetadata
    author   {Esger Renkema}
    title    {tsvtemplate}
    date     {2022-01-01}
    version  {2022/1.0}
    keywords {tsv; tab-separated values}
    stopmetadata
\maketitle
\stopformulatagging

This is a small package with a single purpose: reading tab-separated value 
(tsv) files and applying a template to the content of their rows.


\section Loading this package

Plain tex users can say ⟦\input tsvtemplate⟧; latex users can say
⟦\usepackage {tsvtemplate}⟧. You must use the lua(la)tex compiler.


\section Using this package

The main command of this package is ⟦*\tsvtemplate⟧, used like this

{\leftskip2em
⟦*\tsvtemplate⟧⟦ [names,of,the,columns]
        {... template ...} {filename.tsv}⟧\par}

This will read the file named ⟦filename.tsv⟧ row-by-row and assign the 
contents of the fields of every row to the control sequences
⟦\names \of \the \columns⟧. These control sequences can then be used in the 
⟦template⟧, which will be repeated for every row.

If you do not specify column names, they will be read from the first line of 
the file. In that case spaces will be ignored, so that a column headed by e.g.
⟦Postal Code⟧ is available as ⟦\PostalCode⟧.

In the latex case, an environment is also available as

{\leftskip2em
⟦\begin{⟧⟦*tsv template⟧⟦}[names,of,the,columns]{filename.tsv}
    ... template ...
\end{⟧⟦*tsv template⟧⟦}⟧\par}


\section Field separators

You can use other field separators than tabs by using the lower-level command 
⟦*\applytemplate⟧; in fact, ⟦\tsvtemplate[fields]⟧ is equivalent to

{\leftskip2em
⟦*\applytemplate⟧⟦ \^^I {fields}⟧\par}

(Note that ⟦\^^I⟧ is just the tab character, preceded by a backslash. For 
colon-separated values you could say ⟦\:⟧ etc.)
The ⟦fields⟧ may be separated either by commas or by the separator character. 
Note that they are no longer optional: leave the argument empty in order to 
have tsv read the first line of the file as a header line.


\section Limitations

Every row in the tsv file must have the exact same number of columns; an error 
is emitted otherwise.

When reading files with commas or semicolons as field separators, be aware of 
programs generating fields surrounded by double quotes (⟦"⟧ characters) 
containing commas (or semicolons) themselves. Such files will confuse this 
package. The best thing you can do is convert them to proper tsv, which has no 
need for quoting.


\section Implementation

\font\eighttt {Latin Modern Mono:script=latn;+smcp;} at 8pt
\font\eightit {Latin Modern Roman/I:script=latn;} at 8pt
\def\r#1{\baselineskip10pt\input{#1}}
\def\showfile#1{\begingroup
    \noindent \vrule height 2pt depth 8pt
    \raise1.6pt\vbox{\hrule width 2em} file: #1\par\nointerlineskip
    \let\tentt\eighttt\let\tenit\eightit
    \baselineskip10pt \leftskip1em
    \hbox{\vrule\vtop{⟦\relax\input{#1}⟧}}\nointerlineskip
    \vskip-\baselineskip\endgroup
    \noindent \raise1.6pt\hbox{\vrule height 1em}%
    \raise1.6pt\vbox{\hrule width 8em}\par}

The latex style file simply loads the plain tex implementation:

\showfile{tsvtemplate.sty}

\dots which has been kept quite short, so that you may the more easier copy and 
modify it to suit your own needs:

\showfile{tsvtemplate.tex}

\licencesection

\bye