Letters can be generated using data given in
each line from filename.
If the CSV file contains a header row, the
unstarred version of \applyCSVfile should
be used, otherwise the starred version \applyCSVfile*
should be used. The optional argument n
specifies on which line the actual data (not header line)
starts. The unstarred version defaults to line 2
(the header row is always assumed to be on line 1)
and the starred version defaults to 1.

With the unstarred version, the entries in the header row
are used to generate commands of the form
\insertidentifier1 to access corresponding elements
in the row currently being processed. For example,
suppose the first line of the CSV file looks like:

Name,Address,Time,Date

then the commands \insertName, \insertAddress,
\insertTime and \insertDate are
created, allowing you to use the entries in the first,
second, third and fourth columns of the current row.
If the header text contains non-alphabetical characters,
e.g. Full Name, then you will need to use
\insertbyname{text},
e.g. \insertbyname{Full Name}.

Alternatively, you can use the
\field{col} command, where
col is the column number of the entry, so \field{1}
indicates the first entry in the current row and \field{2}
indicates the second entry in the current row.

then the following code can be used to generate a letter for each
person in the CSV file2:

\applyCSVfile{details.csv}{%
\begin{letter}{\insertName\\\insertAddress}
\opening{Dear \insertName}
You are invited to an interview at \insertTime\ on the \insertDate.
\closing{Yours Sincerely}
\end{letter}}

Note that you could also use \insertbyname{Name} etc instead
of \insertName etc. Also note that you need to specify the
file extension when specifying the filename.

filename is the name of the CSV file which must have a header row on line 1,
col-align is the column alignment argument that gets passed
to the tabular environment, first
is the code for the first line, middle is the code
for the middle lines and last is the code for the last line.
This is best demonstrated with an example.

Notice that instead of placing \multicolumn{1}{l|}{}
at the start of the final argument, it is instead
placed in the first argument to \ifnextrowlast5.
See the PDF version (csvtools.pdf) of this
manual for an illustration of the results.

Within the \CSVtotabular, \CSVtolongtable and
\applyCSVfile commands, there are two
counters, csvlinenum and csvrownumber.
The former, csvlinenum, is the current line number in the CSV
file, whereas the latter, csvrownumber, is the current
data row. Of the two counters, csvrownumber is likely to be
the most useful.

Labels can be generated using the standard
\label command, but you will need some way
to make each label unique. Example 10
does this by using \thecsvrownumber,
whereas Example 11 uses \insertidentifier.

In this example, each experiment has the corresponding label
exp:Incubation Temperature:Incubation Time
so the first experiment has label exp:40:120, the
second experiment has the label exp:40:90 and the
third experiment has the label exp:35:180.

The following example is more refined in that it
takes advantage of the fact that the time to growth data consists
of integers only, so the experiment with the maximum growth can be
determined by LaTeX.

It is not possible to nest \CSVtotabular,
\CSVtolongtable and \applyCSVfile,
so if you need to go through index.csv and use each file
named in there, you can first go through index.csv
storing the information using \csvSaveEntry as follows:

The counter maxexperiments simply counts the number of
entries in index.csv.
The entries can now be used to generate a table for each
file listed in index.csv (the \whiledo command
is defined in the ifthen package):

If you want to create a pie chart from data stored in a CSV file,
you can use the csvpie package, distributed with the
csvtools package. A basic pie chart can be created
using the command:

\csvpiechart[options]{variable}{filename}

where filename is the name of the CSV file containing the
data, and variable is the command indicating the entry that
contains the value for the given segment.
The starred version of \csvpiechart should be used if
the CSV file has no header row.

The pie charts have ``inner'' labels on the segment, and
``outer'' labels outside the chart. The labels are given by the
commands \csvpieinnerlabel
and \csvpieouterlabel.
The default definitions are:

This assumes that the second column contains the data, and the
first column contains a description, but can be redefined
as necessary.

The pie chart display can be modified using the optional
argument to \csvpiechart.
This argument should be a key=value list.
The available keys are as follows:

start

This should be an integer specifying the starting angle
of the first segment. This is 0 by default.

total

This should be an integer specifying the sum of all
the segment values. This is 100 by default.

radius

This should be a length specifying the radius of the
pie chart. (Default: 2cm)

inner

This should be a fraction specifying the relative distance
along the radius to start the inner label. (Default: 0.25)

outer

This should be a fraction specifying the relative distance
along the radius to start the outer label. (Default: 1.25)

cutaway

This should be a comma-separated list of numbers
corresponding to the segments that should be cut away from the
rest of the pie chart. Since the value may contain commas, the value
should always be enclosed in braces. Ranges may also be used.
If a range is used, all the segments in the given range are
kept together, so, for example, cutaway={1,2} will separate
the first two segments from the pie chart, and the two segments
will also be separated from each other, whereas cutaway={1-2}
will separate the first two segments from the pie chart, but will
keep the two segments together.

offset

This should be a fraction specifying the
relative distance along the radius to shift the cut away
segments. (Default: 0.1)

firstrow

This should be the number of the first row
containing the actual data. This is equivalent to the optional
argument of \applyCSVfile or \applyCSVfile*.

Note that TEX performs integer arithmetic. Although the CSV
file may contain decimal numbers, rounding will occur when
constructing the pie charts.

The colours for the pie chart segments can be set using the
command:

\csvpiesegmentcol{n}{colour}

where n is the segment number, and colour is a
defined colour name. For example, if you want the first segment
in the pie chart to be yellow, do:

\csvpiesegmentcol{1}{yellow}

There are 8 predefined segment colours, if your pie chart has
more than 8 segments, you will need to specify the remainder.

You can obtain the colour name for a given segment
using:

\csvpiesegcolname{n}

where n is the segment number. The \csvpiechart
command uses \applyCSVfile, so the csvrownumber
counter can be used. This means that you can change the text
colour of the outer label to match the segment. For example:

Then the value for each segment is given by the second column, so
variable should be \field{2} or \insertValue.
The following code creates a figure containing two
pie charts from the above data (for an image, see the
PDF version of the manual, csvtools.pdf):

The inner and outer labels have been
redefined to use a sans-serif font, and the outer label is in
the same colour as its corresponding segment.
Both pie charts have a starting angle of 45 degrees, and they
have the first two segments cutaway, but in (a)
the first two segments are separated from each other, whereas in
(b), the first two segments are joined, although separated
from the rest of the pie chart.

If the CSV file has no header row, the starred version should be
used, e.g.:

The csvsort package (which forms part of the
csvtools bundle) provides analogous commands to
those provided by csvtools, but the data is first
sorted. The csvsort package needs to be loaded
separately in order to access the necessary commands. The package
options should be a list of key=value pairs, where the available
keys are:

verbose

Verbose mode. This is a boolean key. If set, the
comparisons performed by the insertion sort code are printed to
the screen. (Default: verbose=true.)

sort

This key specifies how to sort the data. It may take
one of the following values:

alphabetical ascending (or just alphabetical)

alphabetical descending

numerical ascending (or just numerical)

numerical descending

(Default: sort=alphabetical ascending)

variable

The sort variable. (Default: sort=\field{1})

sfirstdataline

The line on which the data starts in a data
file without a header row. (Default: sfirstdataline=1.)

firstdataline

The line on which the data starts in a data
file with a header row. (Default: firstdataline=2.)

Note that the csvsort package requires Éamonn McManus'
compare.tex file. The csvsort package uses
an insertion sort method to sort the data, so large amounts of data
may slow processing time. The following commands are provided
by csvsort:

\sortapplyCSVfileoptionsfilenametext

\sortapplyCSVfile*optionsfilenametext

These commands are analogous to \applyCSVfile and
\applyCSVfile*, except that the data is first sorted.
The optional argument is a key=value list. The keys are the same
as those used in the package options, described above. These options
only apply to the given instance of the command, whereas the
package options apply to all csvsort commands, unless
overridden in options. Example, suppose you have a file
called unsorted.csv which looks like:

\sortCSVtotabularoptionsfilenamecol-specfirst rowall but last rowlast row
\sortCSVtolongtableoptionsfilenamecol-specfirst rowall but last rowlast row
Are analogous to \CSVtotabular and \CSVtolongtable,
where, again, options is a list of key=value pairs, the same
as \sortapplyCSVfile. Using the same example data as above,
the following command will sort the data according to age (in
numerical order) and place in a tabular environment:

Suppose you have several large CSV files, and you have included
the information into your document using \applyCSVfile,
\CSVtolongtable, \CSVtotabular or
\csvpiechart, which has
made life so much easier for you, but you are now required by a
journal to submit your source code in a single .tex file.
They don't want all your CSV files, so what do you do? If you
have Perl installed on your system you can use the
csvtools.pl Perl script. This has the following syntax:

csvtools.plin-fileout-file

where in-file is the name of your file that contains the
\applyCSVfile, \CSVtotabular etc
commands, and out-file is a new file which will be created by csvtools.pl. This new
file will be the same as in-file except that all
occurances of \applyCSVfile, \CSVtolongtable,
\CSVtotabular and \csvpiechart will be replaced
by the relevant data extracted from the named CSV files.

It can pick up on \addtocounter, \stepcounter,
\refstepcounter and \setcounter but only if
they are used explicitly in the named .tex file. (It
ignores any files that have been included using
\input, \include etc.)

This Perl script has only been tested under Linux, but it
ought to work under other systems.

Bugs/Drawbacks/``Features''

The package doesn't check to see whether
\insertidentifier exists, otherwise you would not
be able to use multiple CSV files with the same headers, as in
Example 14. Therefore it is recommended that
you check to make sure that the command does not already exist.
For example, the TEX commands \insert and
\insertpenalties already exist, so a blank header or a
header named penalties would cause problems. (These two
will now cause an error as from version 1.1, but it's something
bear in mind.)

Note also that \insertbyname doesn't check
if you've given a valid label, so if no text appears,
check you've spelt it correctly, checking punctuation, spaces and case.

will cause an error, as \insertbyname{File} doesn't get
fully expanded by the time it gets passed to
\includegraphics, and will prevent
\includegraphics from
finding the file. It is possible to get around this using
TEX's \edef command:

You can't have commands like
\hline, \cline and \multicolumn in the
first column of the middle or last code of
\CSVtotabular or \CSVtolongtable. If you do,
it will generate a misplaced \noalign error, instead you
need to put it at the end of the first or middle
code. (See Example 6.)

You can't have nested \applyCSVfile,
\CSVtolongtable and \CSVtotabular
commands. Nor can you have \csvpiechart within
one of these commands (See Example 14)

If the CSV file has a header row, it must be on the first
line.

It is possible for TEX to run out of memory if you use
\csvSaveEntry on a large file.

In version 1.0, there was an
inconsistency with csvrownumber within
\applyCSVfile and \CSVtotabular. In the
former it excluded the header row, whereas the latter
included it. This has been changed in version 1.1 so that within
\applyCSVfile, \CSVtotabular and
\CSVtolongtable, csvrownumber refers to the
data row (excluding header row.) I hope this doesn't cause
problems, but it makes more sense that they should be
consistent. So if you have no blank lines in your CSV file,
csvrownumber should always be 1 more than
csvlinenumber.