Debian Codegraph @

texmf-dist/doc/luatex/tsvtemplate/tsvtemplate.doc

raw
1
2 \input minim-doc.sty
3
4 \nopagenumbers
5 \setbox\notehead=\vtop to 0pt
6 {\halign{&\strut#\quad\cr a1&b1&c1\cr a2&b2&c2\cr a3&b3&c3\cr}
7 \vskip-\baselineskip}
8
9 \startmetadata
10 author {Esger Renkema}
11 title {tsvtemplate}
12 date {2022-01-01}
13 version {2022/1.0}
14 keywords {tsv; tab-separated values}
15 stopmetadata
16 \maketitle
17 \stopformulatagging
18
19 This is a small package with a single purpose: reading tab-separated value
20 (tsv) files and applying a template to the content of their rows.
21
22
23 \section Loading this package
24
25 Plain tex users can say ⟦\input tsvtemplate⟧; latex users can say
26 ⟦\usepackage {tsvtemplate}⟧. You must use the lua(la)tex compiler.
27
28
29 \section Using this package
30
31 The main command of this package is ⟦*\tsvtemplate⟧, used like this
32
33 {\leftskip2em
34 ⟦*\tsvtemplate⟧⟦ [names,of,the,columns]
35 {... template ...} {filename.tsv}⟧\par}
36
37 This will read the file named ⟦filename.tsv⟧ row-by-row and assign the
38 contents of the fields of every row to the control sequences
39 ⟦\names \of \the \columns⟧. These control sequences can then be used in the
40 ⟦template⟧, which will be repeated for every row.
41
42 If you do not specify column names, they will be read from the first line of
43 the file. In that case spaces will be ignored, so that a column headed by e.g.
44 ⟦Postal Code⟧ is available as ⟦\PostalCode⟧.
45
46 In the latex case, an environment is also available as
47
48 {\leftskip2em
49 ⟦\begin{⟧⟦*tsv template⟧⟦}[names,of,the,columns]{filename.tsv}
50 ... template ...
51 \end{⟧⟦*tsv template⟧⟦}⟧\par}
52
53
54 \section Field separators
55
56 You can use other field separators than tabs by using the lower-level command
57 ⟦*\applytemplate⟧; in fact, ⟦\tsvtemplate[fields]⟧ is equivalent to
58
59 {\leftskip2em
60 ⟦*\applytemplate⟧⟦ \^^I {fields}⟧\par}
61
62 (Note that ⟦\^^I⟧ is just the tab character, preceded by a backslash. For
63 colon-separated values you could say ⟦\:⟧ etc.)
64 The ⟦fields⟧ may be separated either by commas or by the separator character.
65 Note that they are no longer optional: leave the argument empty in order to
66 have tsv read the first line of the file as a header line.
67
68
69 \section Limitations
70
71 Every row in the tsv file must have the exact same number of columns; an error
72 is emitted otherwise.
73
74 When reading files with commas or semicolons as field separators, be aware of
75 programs generating fields surrounded by double quotes (⟦"⟧ characters)
76 containing commas (or semicolons) themselves. Such files will confuse this
77 package. The best thing you can do is convert them to proper tsv, which has no
78 need for quoting.
79
80
81 \section Implementation
82
83 \font\eighttt {Latin Modern Mono:script=latn;+smcp;} at 8pt
84 \font\eightit {Latin Modern Roman/I:script=latn;} at 8pt
85 \def\r#1{\baselineskip10pt\input{#1}}
86 \def\showfile#1{\begingroup
87 \noindent \vrule height 2pt depth 8pt
88 \raise1.6pt\vbox{\hrule width 2em} file: #1\par\nointerlineskip
89 \let\tentt\eighttt\let\tenit\eightit
90 \baselineskip10pt \leftskip1em
91 \hbox{\vrule\vtop{⟦\relax\input{#1}⟧}}\nointerlineskip
92 \vskip-\baselineskip\endgroup
93 \noindent \raise1.6pt\hbox{\vrule height 1em}%
94 \raise1.6pt\vbox{\hrule width 8em}\par}
95
96 The latex style file simply loads the plain tex implementation:
97
98 \showfile{tsvtemplate.sty}
99
100 \dots which has been kept quite short, so that you may the more easier copy and
101 modify it to suit your own needs:
102
103 \showfile{tsvtemplate.tex}
104
105 \licencesection
106
107 \bye
108