1971 lines
70 KiB
TeX
1971 lines
70 KiB
TeX
% \LaTeX-Main\
|
|
% !TeX encoding=UTF-8
|
|
%% The LaTeX package csvsimple - version 2.5.0 (2023/10/16)
|
|
%% csvsimple.tex: Manual
|
|
%%
|
|
%% -------------------------------------------------------------------------------------------
|
|
%% Copyright (c) 2008-2023 by Prof. Dr. Dr. Thomas F. Sturm <thomas dot sturm at unibw dot de>
|
|
%% -------------------------------------------------------------------------------------------
|
|
%%
|
|
%% This work may be distributed and/or modified under the
|
|
%% conditions of the LaTeX Project Public License, either version 1.3
|
|
%% of this license or (at your option) any later version.
|
|
%% The latest version of this license is in
|
|
%% http://www.latex-project.org/lppl.txt
|
|
%% and version 1.3 or later is part of all distributions of LaTeX
|
|
%% version 2005/12/01 or later.
|
|
%%
|
|
%% This work has the LPPL maintenance status `author-maintained'.
|
|
%%
|
|
%% This work consists of all files listed in README.md
|
|
%%
|
|
\documentclass[a4paper,11pt]{ltxdoc}
|
|
\usepackage{csvsimple-doc}
|
|
|
|
\usepackage{\csvpkgprefix csvsimple-legacy}
|
|
|
|
\tcbmakedocSubKey{docCsvKey}{csv}
|
|
|
|
\hypersetup{
|
|
pdftitle={Manual for the csvsimple-legacy package},
|
|
pdfauthor={Thomas F. Sturm},
|
|
pdfsubject={csv file processing with LaTeX2e},
|
|
pdfkeywords={csv file, comma separated values, key value syntax}
|
|
}
|
|
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
\begin{document}
|
|
\begin{center}
|
|
\begin{tcolorbox}[enhanced,hbox,tikznode,left=8mm,right=8mm,boxrule=0.4pt,
|
|
colback=white,colframe=black!50!yellow,
|
|
drop lifted shadow=black!50!yellow,arc is angular,
|
|
before=\par\vspace*{5mm},after=\par\bigskip]
|
|
{\bfseries\LARGE The \texttt{csvsimple-legacy} package}\\[3mm]
|
|
{\large Manual for version \version\ (\datum)}
|
|
\end{tcolorbox}
|
|
{\large Thomas F.~Sturm%
|
|
\footnote{Prof.~Dr.~Dr.~Thomas F.~Sturm, Institut f\"{u}r Mathematik und Informatik,
|
|
University of the Bundeswehr Munich, D-85577 Neubiberg, Germany;
|
|
email: \href{mailto:thomas.sturm@unibw.de}{thomas.sturm@unibw.de}}\par\medskip
|
|
\normalsize\url{https://www.ctan.org/pkg/csvsimple}\par
|
|
\url{https://github.com/T-F-S/csvsimple}
|
|
}
|
|
\end{center}
|
|
\bigskip
|
|
\begin{absquote}
|
|
\begin{center}\bfseries Abstract\end{center}
|
|
|csvsimple(-legacy)| provides a simple \LaTeX\ interface for the processing of files with
|
|
comma separated values (CSV). |csvsimple-legacy| relies heavily on the key value
|
|
syntax from |pgfkeys| which results in an easy way of usage.
|
|
Filtering and table generation is especially supported. Since the package
|
|
is considered as a lightweight tool, there is no support for data sorting
|
|
or data base storage.
|
|
\end{absquote}
|
|
|
|
|
|
\begin{tcolorbox}[enhanced,left=8mm,right=8mm,boxrule=2pt,boxsep=3mm,
|
|
colback=red!85!gray!5!white,colframe=red!85!gray,
|
|
arc is angular,arc=5mm,
|
|
before skip=1cm]
|
|
Actually, |csvsimple-legacy| is identical to the old version 1.22 (2021/06/07)
|
|
of |csvsimple|. It is superseded by |csvsimple-l3|, a \LaTeX3 implementation
|
|
of |csvsimple| which is a \emph{nearly} drop-in for the erstwhile implementation.
|
|
\begin{itemize}
|
|
\item If you are a new user or an experienced user of |csvsimple| creating a
|
|
new document, you are encouraged to turn to |csvsimple-l3|, see\\
|
|
\href{csvsimple-l3.pdf}{\flqq The |csvsimple-l3| package\frqq}
|
|
\item If you used |csvsimple| before version 2.00 in one or many documents,
|
|
there is \emph{no need} to change anything. Loading |csvsimple|
|
|
without options loads |csvsimple-legacy|.
|
|
|csvsimple-legacy| will be maintained to stay functional as it is for the
|
|
sake of compatibility to old documents.
|
|
\item Differences between |csvsimple-legacy| and |csvsimple-l3| are
|
|
discussed in \href{csvsimple.pdf}{\flqq The |csvsimple| package\frqq}.
|
|
\end{itemize}
|
|
\end{tcolorbox}
|
|
|
|
|
|
\clearpage
|
|
\tableofcontents
|
|
|
|
\clearpage
|
|
\section{Introduction}%
|
|
The |csvsimple-legacy| package is applied to the processing of
|
|
CSV\footnote{CSV file: file with comma separated values.} files.
|
|
This processing is controlled by key value assignments according to the
|
|
syntax of |pgfkeys|. Sample applications of the package
|
|
are tabular lists, serial letters, and charts.
|
|
|
|
An alternative to |csvsimple-legacy| is the |datatool| package
|
|
which provides considerably more functions and allows sorting of data by \LaTeX.
|
|
|csvsimple-legacy| has a different approach for the user interface and
|
|
is deliberately restricted to some basic functions with fast
|
|
processing speed.
|
|
|
|
Mind the following restrictions:
|
|
\begin{itemize}
|
|
\item Sorting is not supported directly but can be done
|
|
with external tools, see \Fullref{sec:Sorting}.
|
|
\item Values are expected to be comma separated, but the package
|
|
provides support for other separators, see \Fullref{sec:separators}.
|
|
\item Values are expected to be either not quoted or quoted with
|
|
curly braces |{}| of \TeX\ groups. Other quotes like doublequotes
|
|
are not supported directly, but can be achieved
|
|
with external tools, see \Fullref{sec:importeddata}.
|
|
\item Every data line is expected to contain the same amount of values.
|
|
Unfeasible data lines are silently ignored by default, but this can
|
|
be configured, see \Fullref{sec:consistency}.
|
|
\end{itemize}
|
|
|
|
|
|
\subsection{Loading the Package}
|
|
The package |csvsimple-legacy| loads the packages
|
|
|pgfkeys|,
|
|
|etoolbox|,
|
|
and |ifthen|.
|
|
|csvsimple-legacy| itself is loaded with \emph{one} of the following
|
|
alternatives inside the preamble:
|
|
\begin{dispListing}
|
|
\usepackage{csvsimple}
|
|
% or alternatively (not simultaneously!)
|
|
\usepackage[legacy]{csvsimple}
|
|
% or alternatively (not simultaneously!)
|
|
\usepackage{csvsimple-legacy}
|
|
\end{dispListing}
|
|
|
|
|
|
Not automatically loaded, but used for many examples are the packages
|
|
|longtable|
|
|
and
|
|
|booktabs|.
|
|
|
|
|
|
\clearpage
|
|
\subsection{First Steps}
|
|
Every line of a processable CSV file has to contain an identical amount of
|
|
comma\footnote{See \refKey{/csv/separator} for other separators than comma.} separated values. The curly braces |{}| of \TeX\ groups can be used
|
|
to mask a block which may contain commas not to be processed as separators.
|
|
|
|
The first line of such a CSV file is usually but not necessarily a header line
|
|
which contains the identifiers for each column.
|
|
|
|
%-- file embedded for simplicity --
|
|
\begin{tcbverbatimwrite}{grade.csv}
|
|
name,givenname,matriculation,gender,grade
|
|
Maier,Hans,12345,m,1.0
|
|
Huber,Anna,23456,f,2.3
|
|
Weißbäck,Werner,34567,m,5.0
|
|
Bauer,Maria,19202,f,3.3
|
|
\end{tcbverbatimwrite}
|
|
%-- end embedded file --
|
|
|
|
\csvlisting{grade}
|
|
|
|
\smallskip
|
|
The most simple way to display a CSV file in tabular form is the processing
|
|
with the \refCom{csvautotabular} command.
|
|
|
|
\begin{dispExample}
|
|
\csvautotabular{grade.csv}
|
|
\end{dispExample}
|
|
|
|
|
|
Typically, one would use \refCom{csvreader} instead of |\csvautotabular| to
|
|
gain full control over the interpretation of the included data.
|
|
|
|
In the following example, the entries of the header line are automatically
|
|
assigned to \TeX\ macros which may be used deliberately.
|
|
|
|
|
|
\begin{dispExample}
|
|
\begin{tabular}{|l|c|}\hline%
|
|
\bfseries Person & \bfseries Matr.~No.
|
|
\csvreader[head to column names]{grade.csv}{}%
|
|
{\\\givenname\ \name & \matriculation}%
|
|
\\\hline
|
|
\end{tabular}
|
|
\end{dispExample}
|
|
|
|
|
|
\clearpage
|
|
|\csvreader| is controlled by a plenty of options. For example, for table
|
|
applications line breaks are easily inserted by
|
|
\refKey{/csv/late after line}. This defines a macro execution just before
|
|
the following line.
|
|
Additionally, the assignment of columns to \TeX\ macros is shown in a non automated
|
|
way.
|
|
|
|
\begin{dispExample}
|
|
\begin{tabular}{|r|l|c|}\hline%
|
|
& Person & Matr.~No.\\\hline\hline
|
|
\csvreader[late after line=\\\hline]%
|
|
{grade.csv}{name=\name,givenname=\firstname,matriculation=\matnumber}%
|
|
{\thecsvrow & \firstname~\name & \matnumber}%
|
|
\end{tabular}
|
|
\end{dispExample}
|
|
|
|
\smallskip
|
|
An even more comfortable and preferrable way to create a table is setting
|
|
appropriate option keys. Note, that this gives you the possibility to create a
|
|
|pgfkeys| style which contains the whole table creation.
|
|
|
|
\begin{dispExample}
|
|
\csvreader[tabular=|r|l|c|,
|
|
table head=\hline & Person & Matr.~No.\\\hline\hline,
|
|
late after line=\\\hline]%
|
|
{grade.csv}{name=\name,givenname=\firstname,matriculation=\matnumber}%
|
|
{\thecsvrow & \firstname~\name & \matnumber}%
|
|
\end{dispExample}
|
|
|
|
\smallskip
|
|
The next example shows such a style definition with the convenience macro
|
|
\refCom{csvstyle}. Here, we see again the automated assignment of header
|
|
entries to column names by \refKey{/csv/head to column names}.
|
|
For this, the header entries have to be without spaces and special characters.
|
|
But you can always assign entries to canonical macro names by hand like in the examples
|
|
above. Here, we also add a \refKey{/csv/head to column names prefix} to avoid
|
|
macro name clashes.
|
|
|
|
\begin{dispExample}
|
|
\csvstyle{myTableStyle}{tabular=|r|l|c|,
|
|
table head=\hline & Person & Matr.~No.\\\hline\hline,
|
|
late after line=\\\hline,
|
|
head to column names,
|
|
head to column names prefix=MY,
|
|
}
|
|
|
|
\csvreader[myTableStyle]{grade.csv}{}%
|
|
{\thecsvrow & \MYgivenname~\MYname & \MYmatriculation}%
|
|
\end{dispExample}
|
|
|
|
|
|
\clearpage
|
|
Another way to address columns is to use their roman numbers.
|
|
The direct addressing is done by |\csvcoli|, |\csvcolii|, |\csvcoliii|, \ldots:
|
|
|
|
\begin{dispExample}
|
|
\csvreader[tabular=|r|l|c|,
|
|
table head=\hline & Person & Matr.~No.\\\hline\hline,
|
|
late after line=\\\hline]%
|
|
{grade.csv}{}%
|
|
{\thecsvrow & \csvcolii~\csvcoli & \csvcoliii}%
|
|
\end{dispExample}
|
|
|
|
\smallskip
|
|
And yet another method to assign macros to columns is to use arabic numbers
|
|
for the assignment:
|
|
|
|
\begin{dispExample}
|
|
\csvreader[tabular=|r|l|c|,
|
|
table head=\hline & Person & Matr.~No.\\\hline\hline,
|
|
late after line=\\\hline]%
|
|
{grade.csv}{1=\name,2=\firstname,3=\matnumber}%
|
|
{\thecsvrow & \firstname~\name & \matnumber}%
|
|
\end{dispExample}
|
|
|
|
\smallskip
|
|
For recurring applications, the |pgfkeys| syntax allows to create own styles
|
|
for a consistent and centralized design. The following example is easily
|
|
modified to obtain more or less option settings.
|
|
|
|
\begin{dispExample}
|
|
\csvset{myStudentList/.style={%
|
|
tabular=|r|l|c|,
|
|
table head=\hline & Person & #1\\\hline\hline,
|
|
late after line=\\\hline,
|
|
column names={name=\name,givenname=\firstname}
|
|
}}
|
|
|
|
\csvreader[myStudentList={Matr.~No.}]{grade.csv}{matriculation=\matnumber}%
|
|
{\thecsvrow & \firstname~\name & \matnumber}%
|
|
\hfill%
|
|
\csvreader[myStudentList={Grade}]{grade.csv}{grade=\grade}%
|
|
{\thecsvrow & \firstname~\name & \grade}%
|
|
\end{dispExample}
|
|
|
|
|
|
\clearpage
|
|
Alternatively, column names can be set by \refCom{csvnames}
|
|
and style definitions by \refCom{csvstyle}.
|
|
With this, the last example is rewritten as follows:
|
|
|
|
\begin{dispExample}
|
|
\csvnames{myNames}{1=\name,2=\firstname,3=\matnumber,5=\grade}
|
|
\csvstyle{myStudentList}{tabular=|r|l|c|,
|
|
table head=\hline & Person & #1\\\hline\hline,
|
|
late after line=\\\hline, myNames}
|
|
|
|
\csvreader[myStudentList={Matr.~No.}]{grade.csv}{}%
|
|
{\thecsvrow & \firstname~\name & \matnumber}%
|
|
\hfill%
|
|
\csvreader[myStudentList={Grade}]{grade.csv}{}%
|
|
{\thecsvrow & \firstname~\name & \grade}%
|
|
\end{dispExample}
|
|
|
|
\smallskip
|
|
The data lines of a CSV file can also be filtered. In the following example,
|
|
a certificate is printed only for students with grade unequal to 5.0.
|
|
|
|
\begin{dispExample}
|
|
\csvreader[filter not strcmp={\grade}{5.0}]%
|
|
{grade.csv}{1=\name,2=\firstname,3=\matnumber,4=\gender,5=\grade}%
|
|
{\begin{center}\Large\bfseries Certificate in Mathematics\end{center}
|
|
\large\ifcsvstrcmp{\gender}{f}{Ms.}{Mr.}
|
|
\firstname~\name, matriculation number \matnumber, has passed the test
|
|
in mathematics with grade \grade.\par\ldots\par
|
|
}%
|
|
\end{dispExample}
|
|
|
|
|
|
\clearpage
|
|
\section{Macros for the Processing of CSV Files}\label{sec:makros}%
|
|
|
|
\begin{docCommand}{csvreader}{\oarg{options}\marg{file name}\marg{assignments}\marg{command list}}
|
|
|\csvreader| reads the file denoted by \meta{file name} line by line.
|
|
Every line of the file has to contain an identical amount of
|
|
comma separated values. The curly braces |{}| of \TeX\ groups can be used
|
|
to mask a block which may contain commas not to be processed as separators.\smallskip
|
|
|
|
The first line of such a CSV file is by default but not necessarily
|
|
processed as a header line which contains the identifiers for each column.
|
|
The entries of this line can be used to give \meta{assignments} to \TeX\ macros
|
|
to address the columns. The number of entries of this first line
|
|
determines the accepted number of entries for all following lines.
|
|
Every line which contains a higher or lower number of entries is ignored
|
|
during standard processing.\smallskip
|
|
|
|
The \meta{assignments} are given by key value pairs
|
|
\mbox{\meta{name}|=|\meta{macro}}. Here, \meta{name} is an entry from the
|
|
header line \emph{or} the arabic number of the addressed column.
|
|
\meta{macro} is some \TeX\ macro which gets the content of the addressed column.\smallskip
|
|
|
|
The \meta{command list} is executed for every accepted data line. Inside the
|
|
\meta{command list} is applicable:
|
|
\begin{itemize}
|
|
\item \docAuxCommand{thecsvrow} or the counter |csvrow| which contains the number of the
|
|
current data line (starting with 1).
|
|
\item \docAuxCommand{csvcoli}, \docAuxCommand{csvcolii}, \docAuxCommand{csvcoliii}, \ldots,
|
|
which contain the contents of the column entries of the current data line.
|
|
Alternatively can be used:
|
|
\item \meta{macro} from the \meta{assignments} to have a logical
|
|
addressing of a column entry.
|
|
\end{itemize}
|
|
Note, that the \meta{command list} is allowed to contain |\par| and
|
|
that all macro definitions are made global to be used for table applications.\smallskip
|
|
|
|
The processing of the given CSV file can be controlled by various
|
|
\meta{options} given as key value list. The feasible option keys
|
|
are described in section \ref{sec:schluessel} from page \pageref{sec:schluessel}.
|
|
|
|
\begin{dispExample}
|
|
\csvreader[tabular=|r|l|l|, table head=\hline, table foot=\hline]{grade.csv}%
|
|
{name=\name,givenname=\firstname,grade=\grade}%
|
|
{\grade & \firstname~\name & \csvcoliii}
|
|
\end{dispExample}
|
|
|
|
Mainly, the |\csvreader| command consists of a \refCom{csvloop} macro with
|
|
following parameters:\par
|
|
|\csvloop{|\meta{options}|, file=|\meta{file name}|, column names=|\meta{assignments}|,|\\
|
|
\hspace*{2cm} |command=|\meta{command list}|}|\par
|
|
Therefore, the application of the keys \refKey{/csv/file} and \refKey{/csv/command}
|
|
is useless for |\csvreader|.
|
|
\end{docCommand}
|
|
|
|
\begin{docCommand}{csvloop}{\marg{options}}
|
|
Usually, \refCom{csvreader} may be preferred instead of |\csvloop|.
|
|
\refCom{csvreader} is based on |\csvloop| which takes a mandatory list of
|
|
\meta{options} in key value syntax.
|
|
This list of \meta{options} controls the total processing. Especially,
|
|
it has to contain the CSV file name.
|
|
\begin{dispExample}
|
|
\csvloop{file={grade.csv}, head to column names, command=\name,
|
|
before reading={List of students:\ },
|
|
late after line={{,}\ }, late after last line=.}
|
|
\end{dispExample}
|
|
\end{docCommand}
|
|
|
|
\clearpage
|
|
The following |\csvauto...| commands are intended for quick data overview
|
|
with limited formatting potential.
|
|
See Subsection~\ref{subsec:tabsupport} on page \pageref{subsec:tabsupport}
|
|
for the general table options in combination with \refCom{csvreader} and
|
|
\refCom{csvloop}.
|
|
|
|
\begin{docCommand}{csvautotabular}{\oarg{options}\marg{file name}}
|
|
|\csvautotabular| is an abbreviation for the application of the option key
|
|
\refKey{/csv/autotabular} together with other \meta{options} to \refCom{csvloop}.
|
|
This macro reads the whole CSV file denoted by \meta{file name}
|
|
with an automated formatting.
|
|
\begin{dispExample}
|
|
\csvautotabular{grade.csv}
|
|
\end{dispExample}
|
|
\begin{dispExample}
|
|
\csvautotabular[filter equal={\csvcoliv}{f}]{grade.csv}
|
|
\end{dispExample}
|
|
\end{docCommand}
|
|
|
|
|
|
\begin{docCommand}{csvautolongtable}{\oarg{options}\marg{file name}}
|
|
|csvautolongtable| is an abbreviation for the application of the option key
|
|
\refKey{/csv/autolongtable} together with other \meta{options} to \refCom{csvloop}.
|
|
This macro reads the whole CSV file denoted by \meta{file name}
|
|
with an automated formatting.
|
|
For application, the package |longtable| is required which has to be
|
|
loaded in the preamble.
|
|
\begin{dispListing}
|
|
\csvautolongtable{grade.csv}
|
|
\end{dispListing}
|
|
\csvautolongtable{grade.csv}
|
|
\end{docCommand}
|
|
|
|
\clearpage
|
|
|
|
\begin{docCommand}{csvautobooktabular}{\oarg{options}\marg{file name}}
|
|
|\csvautobooktabular| is an abbreviation for the application of the option key
|
|
\refKey{/csv/autobooktabular} together with other \meta{options} to \refCom{csvloop}.
|
|
This macro reads the whole CSV file denoted by \meta{file name}
|
|
with an automated formatting.
|
|
For application, the package |booktabs| is required which has to be
|
|
loaded in the preamble.
|
|
\begin{dispExample}
|
|
\csvautobooktabular{grade.csv}
|
|
\end{dispExample}
|
|
\end{docCommand}
|
|
|
|
|
|
\begin{docCommand}{csvautobooklongtable}{\oarg{options}\marg{file name}}
|
|
|csvautobooklongtable| is an abbreviation for the application of the option key
|
|
\refKey{/csv/autobooklongtable} together with other \meta{options} to \refCom{csvloop}.
|
|
This macro reads the whole CSV file denoted by \meta{file name}
|
|
with an automated formatting.
|
|
For application, the packages |booktabs| and |longtable| are required which have to be
|
|
loaded in the preamble.
|
|
\begin{dispListing}
|
|
\csvautobooklongtable{grade.csv}
|
|
\end{dispListing}
|
|
\csvautobooklongtable{grade.csv}
|
|
\end{docCommand}
|
|
|
|
|
|
|
|
\clearpage
|
|
|
|
\begin{docCommand}{csvset}{\marg{options}}
|
|
Sets \meta{options} for every following
|
|
\refCom{csvreader} and \refCom{csvloop}. For example, this command may
|
|
be used for style definitions.
|
|
\begin{dispExample}
|
|
\csvset{grade list/.style=
|
|
{column names={name=\name,givenname=\firstname,grade=\grade}},
|
|
passed/.style={filter not strcmp={\grade}{5.0}} }
|
|
|
|
The following students passed the test in mathematics:
|
|
\csvreader[grade list,passed]{grade.csv}{}{\firstname\ \name\ (\grade); }%
|
|
\end{dispExample}
|
|
\end{docCommand}
|
|
|
|
|
|
\begin{docCommand}{csvstyle}{\marg{key}\marg{options}}
|
|
Abbreviation for |\csvset{|\meta{key}|/.style=|\marg{options}|}|
|
|
to define a new style.
|
|
\end{docCommand}
|
|
|
|
\begin{docCommand}{csvnames}{\marg{key}\marg{assignments}}
|
|
Abbreviation for |\csvset{|\meta{key}|/.style={column names=|\marg{assignments}|}}|
|
|
to define additional \meta{assignments} of macros to columns.
|
|
\begin{dispExample}
|
|
\csvnames{grade list}{name=\name,givenname=\firstname,grade=\grade}
|
|
\csvstyle{passed}{filter not strcmp={\grade}{5.0}}
|
|
|
|
The following students passed the test in mathematics:
|
|
\csvreader[grade list,passed]{grade.csv}{}{\firstname\ \name\ (\grade); }%
|
|
\end{dispExample}
|
|
\end{docCommand}
|
|
|
|
|
|
\begin{docCommand}{csvheadset}{\marg{assignments}}
|
|
For some special cases, this command can be used to change the
|
|
\meta{assignments} of macros to columns during execution of
|
|
\refCom{csvreader} and \refCom{csvloop}.
|
|
\begin{dispExample}
|
|
\csvreader{grade.csv}{}%
|
|
{ \csvheadset{name=\n} \fbox{\n}
|
|
\csvheadset{givenname=\n} \ldots\ \fbox{\n} }%
|
|
\end{dispExample}
|
|
\end{docCommand}
|
|
|
|
\clearpage
|
|
|
|
\begin{docCommand}{csviffirstrow}{\marg{then macros}\marg{else macros}}
|
|
Inside the command list of \refCom{csvreader}, the \meta{then macros}
|
|
are executed for the first data line, and the \meta{else macros}
|
|
are executed for all following lines.
|
|
\begin{dispExample}
|
|
\csvreader[tabbing, head to column names, table head=\hspace*{3cm}\=\kill]%
|
|
{grade.csv}{}%
|
|
{\givenname~\name \> (\csviffirstrow{first entry!!}{following entry})}
|
|
\end{dispExample}
|
|
\end{docCommand}
|
|
|
|
|
|
\begin{docCommand}{csvifoddrow}{\marg{then macros}\marg{else macros}}
|
|
Inside the command list of \refCom{csvreader}, the \meta{then macros}
|
|
are executed for odd-numbered data lines, and the \meta{else macros}
|
|
are executed for even-numbered lines.
|
|
\begin{dispExample}
|
|
\csvreader[head to column names,tabular=|l|l|l|l|,
|
|
table head=\hline\bfseries \# & \bfseries Name & \bfseries Grade\\\hline,
|
|
table foot=\hline]{grade.csv}{}{%
|
|
\csvifoddrow{\slshape\thecsvrow & \slshape\name, \givenname & \slshape\grade}%
|
|
{\bfseries\thecsvrow & \bfseries\name, \givenname & \bfseries\grade}}
|
|
\end{dispExample}
|
|
|
|
The |\csvifoddrow| macro may be used for striped tables:
|
|
|
|
\begin{dispExample}
|
|
% This example needs the xcolor package
|
|
\csvreader[head to column names,tabular=rlcc,
|
|
table head=\hline\rowcolor{red!50!black}\color{white}\# & \color{white}Person
|
|
& \color{white}Matr.~No. & \color{white}Grade,
|
|
late after head=\\\hline\rowcolor{yellow!50},
|
|
late after line=\csvifoddrow{\\\rowcolor{yellow!50}}{\\\rowcolor{red!25}}]%
|
|
{grade.csv}{}%
|
|
{\thecsvrow & \givenname~\name & \matriculation & \grade}%
|
|
\end{dispExample}
|
|
|
|
\enlargethispage*{1cm}
|
|
Alternatively, |\rowcolors| from the |xcolor| package can be used for this
|
|
purpose:
|
|
|
|
\begin{dispExample}
|
|
% This example needs the xcolor package
|
|
\csvreader[tabular=rlcc, before table=\rowcolors{2}{red!25}{yellow!50},
|
|
table head=\hline\rowcolor{red!50!black}\color{white}\# & \color{white}Person
|
|
& \color{white}Matr.~No. & \color{white}Grade\\\hline,
|
|
head to column names]{grade.csv}{}%
|
|
{\thecsvrow & \givenname~\name & \matriculation & \grade}%
|
|
\end{dispExample}
|
|
\end{docCommand}
|
|
|
|
\clearpage
|
|
|
|
\begin{docCommand}{csvfilteraccept}{}
|
|
All following consistent data lines will be accepted and processed.
|
|
This command overwrites all previous filter settings and may be used
|
|
inside \refKey{/csv/full filter} to implement
|
|
an own filtering rule together with |\csvfilterreject|.
|
|
\begin{dispExample}
|
|
\csvreader[autotabular,
|
|
full filter=\ifcsvstrcmp{\csvcoliv}{m}{\csvfilteraccept}{\csvfilterreject}
|
|
]{grade.csv}{}{\csvlinetotablerow}%
|
|
\end{dispExample}
|
|
\end{docCommand}
|
|
|
|
|
|
\begin{docCommand}{csvfilterreject}{}
|
|
All following data lines will be ignored.
|
|
This command overwrites all previous filter settings.
|
|
\end{docCommand}
|
|
|
|
|
|
\begin{docCommand}{csvline}{}
|
|
This macro contains the current and unprocessed data line.
|
|
\begin{dispExample}
|
|
\csvreader[no head, tabbing, table head=\textit{line XX:}\=\kill]%
|
|
{grade.csv}{}{\textit{line \thecsvrow:} \> \csvline}%
|
|
\end{dispExample}
|
|
\end{docCommand}
|
|
|
|
|
|
\begin{docCommand}{thecsvrow}{}
|
|
Typesets the current data line number. This is the
|
|
current number of accepted data lines without the header line.
|
|
The \LaTeX\ counter |csvrow| can be addressed directly in the usual way,
|
|
e.\,g. by |\roman{csvrow}|.
|
|
\end{docCommand}
|
|
|
|
|
|
\begin{docCommand}{thecsvinputline}{}
|
|
Typesets the current file line number. This is the
|
|
current number of all data lines including the header line.
|
|
The \LaTeX\ counter |csvinputline| can be addressed directly in the usual way,
|
|
e.\,g. by |\roman{csvinputline}|.
|
|
\begin{dispExample}
|
|
\csvreader[no head, filter test=\ifnumequal{\thecsvinputline}{3}]%
|
|
{grade.csv}{}%
|
|
{The line with number \thecsvinputline\ contains: \csvline}%
|
|
\end{dispExample}
|
|
\end{docCommand}
|
|
|
|
|
|
\begin{docCommand}[doc updated=2016-07-01]{csvlinetotablerow}{}
|
|
Typesets the current processed data line with |&| between the entries.
|
|
%Most users will never apply this command.
|
|
\end{docCommand}
|
|
|
|
|
|
|
|
\clearpage
|
|
\section{Option Keys}\label{sec:schluessel}%
|
|
For the \meta{options} in \refCom{csvreader} respectively \refCom{csvloop}
|
|
the following |pgf| keys can be applied. The key tree path |/csv/| is not
|
|
to be used inside these macros.
|
|
|
|
|
|
\subsection{Command Definition}%--------%[[
|
|
|
|
\begin{docCsvKey}{before reading}{=\meta{code}}{no default, initially empty}
|
|
Sets the \meta{code} to be executed before the CSV file is processed.
|
|
\end{docCsvKey}
|
|
|
|
\begin{docCsvKey}{after head}{=\meta{code}}{no default, initially empty}
|
|
Sets the \meta{code} to be executed after the header line is read.
|
|
\end{docCsvKey}
|
|
|
|
\begin{docCsvKey}{before filter}{=\meta{code}}{no default, initially empty}
|
|
Sets the \meta{code} to be executed after reading and consistency checking
|
|
of a data line. They are executed before any filter condition is checked,
|
|
see \refKey{/csv/filter}.
|
|
Also see \refKey{/csv/full filter}.
|
|
\end{docCsvKey}
|
|
|
|
\begin{docCsvKey}{late after head}{=\meta{code}}{no default, initially empty}
|
|
Sets the \meta{code} to be executed after reading and disassembling
|
|
of the first accepted data line. They are executed before further processing
|
|
of this line.
|
|
\end{docCsvKey}
|
|
|
|
\begin{docCsvKey}{late after line}{=\meta{code}}{no default, initially empty}
|
|
Sets the \meta{code} to be executed after reading and disassembling
|
|
of the next accepted data line (after \refKey{/csv/before filter}).
|
|
They are executed before further processing of this next line.
|
|
|late after line| overwrites |late after first line| and |late after last line|.
|
|
Note that table options like \refKey{/csv/tabular} set this key to |\\|
|
|
automatically.
|
|
\end{docCsvKey}
|
|
|
|
|
|
\begin{docCsvKey}{late after first line}{=\meta{code}}{no default, initially empty}
|
|
Sets the \meta{code} to be executed after reading and disassembling
|
|
of the second accepted data line instead of \refKey{/csv/late after line}.
|
|
This key has to be set after |late after line|.
|
|
\end{docCsvKey}
|
|
|
|
|
|
\begin{docCsvKey}{late after last line}{=\meta{code}}{no default, initially empty}
|
|
Sets the \meta{code} to be executed after processing of the last
|
|
accepted data line instead of \refKey{/csv/late after line}.
|
|
This key has to be set after |late after line|.
|
|
\end{docCsvKey}
|
|
|
|
|
|
\begin{docCsvKey}{before line}{=\meta{code}}{no default, initially empty}
|
|
Sets the \meta{code} to be executed after \refKey{/csv/late after line}
|
|
and before \refKey{/csv/command}.
|
|
|before line| overwrites |before first line|.
|
|
\end{docCsvKey}
|
|
|
|
|
|
\begin{docCsvKey}{before first line}{=\meta{code}}{no default, initially empty}
|
|
Sets the \meta{code} to be executed instead of \refKey{/csv/before line}
|
|
for the first accepted data line.
|
|
This key has to be set after |before line|.
|
|
\end{docCsvKey}
|
|
|
|
|
|
\begin{docCsvKey}{command}{=\meta{code}}{no default, initially \cs{csvline}}
|
|
Sets the \meta{code} to be executed for every accepted data line.
|
|
They are executed between \refKey{/csv/before line} and \refKey{/csv/after line}.
|
|
\end{docCsvKey}
|
|
|
|
|
|
\begin{docCsvKey}{after line}{=\meta{code}}{no default, initially empty}
|
|
Sets the \meta{code} to be executed for every accepted data line
|
|
after \refKey{/csv/command}.
|
|
|after line| overwrites |after first line|.
|
|
\end{docCsvKey}
|
|
|
|
|
|
\begin{docCsvKey}{after first line}{=\meta{code}}{no default, initially empty}
|
|
Sets the \meta{code} to be executed instead of \refKey{/csv/after line}
|
|
for the first accepted data line.
|
|
This key has to be set after |after line|.
|
|
\end{docCsvKey}
|
|
|
|
\begin{docCsvKey}{after reading}{=\meta{code}}{no default, initially empty}
|
|
Sets the \meta{code} to be executed after the CSV file is processed.
|
|
\end{docCsvKey}
|
|
|
|
|
|
\begin{dispExample}
|
|
\csvreader[
|
|
before reading = \meta{before reading}\\,
|
|
after head = \meta{after head},
|
|
before filter = \\\meta{before filter},
|
|
late after head = \meta{late after head},
|
|
late after line = \meta{late after line},
|
|
late after first line = \meta{late after first line},
|
|
late after last line = \\\meta{late after last line},
|
|
before line = \meta{before line},
|
|
before first line = \meta{before first line},
|
|
after line = \meta{after line},
|
|
after first line = \meta{after first line},
|
|
after reading = \\\meta{after reading}
|
|
]{grade.csv}{name=\name}{\textbf{\name}}%
|
|
\end{dispExample}
|
|
|
|
Additional command definition keys are provided for the supported tables,
|
|
see Section~\ref{subsec:tabsupport} from page~\pageref{subsec:tabsupport}.
|
|
|
|
\clearpage
|
|
\subsection{Header Processing and Column Name Assignment}%
|
|
|
|
\begin{docCsvKey}{head}{\colOpt{=true\textbar false}}{default |true|, initially |true|}
|
|
If this key is set, the first line of the CSV file is treated as a header
|
|
line which can be used for column name assignments.
|
|
\end{docCsvKey}
|
|
|
|
|
|
\begin{docCsvKey}{no head}{}{no value}
|
|
Abbreviation for |head=false|, i.\,e. the first line of the CSV file is
|
|
treated as data line.
|
|
Note that this option cannot be used in combination with
|
|
\refCom{csvautotabular}, \refKey{/csv/autotabular}, and similar automated commands/options.
|
|
See Section~\ref{noheader} on page~\pageref{noheader} for assistance.
|
|
\end{docCsvKey}
|
|
|
|
\begin{docCsvKey}{column names}{=\meta{assignments}}{no default, initially empty}
|
|
Adds some new \meta{assignments} of macros to columns in key value syntax.
|
|
Existing assignments are kept.
|
|
\end{docCsvKey}
|
|
|
|
|
|
\begin{docCsvKey}{column names reset}{}{no value}
|
|
Clears all assignments of macros to columns.
|
|
\end{docCsvKey}
|
|
|
|
|
|
\begin{docCsvKey}{head to column names}{\colOpt{=true\textbar false}}{default |true|, initially |false|}
|
|
If this key is set, the entries of the header line are used automatically
|
|
as macro names for the columns. This option can be used only, if
|
|
the header entries do not contain spaces and special characters to be
|
|
used as feasible \LaTeX\ macro names.
|
|
Note that the macro definition is \emph{global} and may therefore override
|
|
existing macros for the rest of the document. Adding
|
|
\refKey{/csv/head to column names prefix} may help to avoid unwanted
|
|
overrides.
|
|
\end{docCsvKey}
|
|
|
|
|
|
\begin{docCsvKey}[][doc new=2019-07-16]{head to column names prefix}{=\meta{text}}{no default, initially empty}
|
|
The given \meta{text} is prefixed to the name of all macros generated by
|
|
\refKey{/csv/head to column names}. For example, if you use the settings
|
|
\begin{dispListing}
|
|
head to column names,
|
|
head to column names prefix=MY,
|
|
\end{dispListing}
|
|
a header entry |section| will generate the corresponding macro
|
|
|\MYsection| instead of destroying the standard \LaTeX\ |\section| macro.
|
|
\end{docCsvKey}
|
|
|
|
|
|
\clearpage
|
|
\subsection{Consistency Check}\label{sec:consistency}%
|
|
|
|
\begin{docCsvKey}{check column count}{\colOpt{=true\textbar false}}{default |true|, initially |true|}
|
|
This key defines, wether the number of entries in a data line is checked against
|
|
an expected value or not.\\
|
|
If |true|, every non consistent line is ignored without announcement.\\
|
|
If |false|, every line is accepted and may produce an error during
|
|
further processing.
|
|
\end{docCsvKey}
|
|
|
|
|
|
\begin{docCsvKey}{no check column count}{}{no value}
|
|
Abbreviation for |check column count=false|.
|
|
\end{docCsvKey}
|
|
|
|
|
|
\begin{docCsvKey}{column count}{=\meta{number}}{no default}
|
|
Sets the \meta{number} of feasible entries per data line.
|
|
This setting is only useful in connection with \refKey{/csv/no head},
|
|
since \meta{number} would be replaced by the number of entries in the
|
|
header line otherwise.
|
|
\end{docCsvKey}
|
|
|
|
|
|
\begin{docCsvKey}{on column count error}{=\meta{code}}{no default, initially empty}
|
|
\meta{code} to be executed for unfeasible data lines.
|
|
\end{docCsvKey}
|
|
|
|
|
|
\begin{docCsvKey}{warn on column count error}{}{style, no value}
|
|
Display of a warning for unfeasible data lines.
|
|
\end{docCsvKey}
|
|
|
|
|
|
\clearpage
|
|
\subsection{Filtering}%
|
|
|
|
\begin{docCsvKey}[][doc new=2016-07-01]{filter test}{=\meta{condition}}{no default}
|
|
Only data lines which fulfill a logical \meta{condition} are accepted.
|
|
For the \meta{condition}, every single test normally employed like
|
|
\begin{dispListing}
|
|
\iftest{some testing}{true}{false}
|
|
\end{dispListing}
|
|
can be used as
|
|
\begin{dispListing}
|
|
filter test=\iftest{some testing},
|
|
\end{dispListing}
|
|
For |\iftest|, tests from the |etoolbox| package like
|
|
|\ifnumcomp|, |\ifdimgreater|, etc. and from \Fullref{sec:stringtests} can be used.
|
|
|
|
\begin{dispExample}
|
|
\csvreader[head to column names,tabular=llll,
|
|
table head=\toprule & \bfseries Name & \bfseries Matr & \bfseries Grade\\\midrule,
|
|
table foot=\bottomrule,
|
|
%>> list only matriculation numbers greater than 20000 <<
|
|
filter test=\ifnumgreater{\matriculation}{20000},
|
|
]{grade.csv}{}{%
|
|
\thecsvrow & \slshape\name, \givenname & \matriculation & \grade}
|
|
\end{dispExample}
|
|
\end{docCsvKey}
|
|
|
|
|
|
\begin{docCsvKey}{filter strcmp}{=\marg{stringA}\marg{stringB}}{style, no default}
|
|
Only lines where \meta{stringA} and \meta{stringB} are equal after expansion
|
|
are accepted.
|
|
The implementation is done with \refCom{ifcsvstrcmp}.
|
|
\end{docCsvKey}
|
|
|
|
|
|
\begin{docCsvKey}{filter not strcmp}{=\marg{stringA}\marg{stringB}}{style, no default}
|
|
Only lines where \meta{stringA} and \meta{stringB} are not equal after expansion
|
|
are accepted.
|
|
The implementation is done with \refCom{ifcsvnotstrcmp}.
|
|
\end{docCsvKey}
|
|
|
|
|
|
\begin{docCsvKey}[][doc new=2016-07-01]{filter expr}{=\meta{condition}}{no default}
|
|
Only data lines which fulfill a logical \meta{condition} are accepted.
|
|
For the \meta{condition}, every boolean expression
|
|
from the |etoolbox| package is feasible.
|
|
To preprocess the data line before testing the \meta{condition},
|
|
the option key \refKey{/csv/before filter} can be used.
|
|
\begin{dispExample}
|
|
\csvreader[head to column names,tabular=llll,
|
|
table head=\toprule & \bfseries Name & \bfseries Matr & \bfseries Grade\\\midrule,
|
|
table foot=\bottomrule,
|
|
%>> list only matriculation numbers greater than 20000
|
|
% and grade less than 4.0 <<
|
|
filter expr={ test{\ifnumgreater{\matriculation}{20000}}
|
|
and test{\ifdimless{\grade pt}{4.0pt}} },
|
|
]{grade.csv}{}{%
|
|
\thecsvrow & \slshape\name, \givenname & \matriculation & \grade}
|
|
\end{dispExample}
|
|
\end{docCsvKey}
|
|
|
|
\clearpage
|
|
\begin{docCsvKey}[][doc new=2016-07-01]{filter ifthen}{=\meta{condition}}{no default}
|
|
Only data lines which fulfill a logical \meta{condition} are accepted.
|
|
For the \meta{condition}, every term from the |ifthen| package
|
|
is feasible.
|
|
To preprocess the data line before testing the \meta{condition},
|
|
the option key \refKey{/csv/before filter} can be used.
|
|
|
|
\begin{dispExample}
|
|
\csvreader[head to column names,tabular=llll,
|
|
table head=\toprule & \bfseries Name & \bfseries Matr & \bfseries Grade\\\midrule,
|
|
table foot=\bottomrule,
|
|
%>> list only female persons <<
|
|
filter ifthen=\equal{\gender}{f},
|
|
]{grade.csv}{}{%
|
|
\thecsvrow & \slshape\name, \givenname & \matriculation & \grade}
|
|
\end{dispExample}
|
|
|
|
\end{docCsvKey}
|
|
|
|
|
|
\begin{docCsvKey}{filter}{=\meta{condition}}{no default}
|
|
Alias for \refKey{/csv/filter ifthen}.
|
|
\end{docCsvKey}
|
|
|
|
\begin{docCsvKey}{filter equal}{=\marg{stringA}\marg{stringB}}{style, no default}
|
|
Only lines where \meta{stringA} and \meta{stringB} are equal after expansion
|
|
are accepted.
|
|
The implementation is done with the |ifthen| package.
|
|
\end{docCsvKey}
|
|
|
|
|
|
\begin{docCsvKey}{filter not equal}{=\marg{stringA}\marg{stringB}}{style, no default}
|
|
Only lines where \meta{stringA} and \meta{stringB} are not equal after expansion
|
|
are accepted.
|
|
The implementation is done with the |ifthen| package.
|
|
\end{docCsvKey}
|
|
|
|
|
|
|
|
\begin{docCsvKey}{no filter}{}{no value, initially set}
|
|
Clears a set filter.
|
|
\end{docCsvKey}
|
|
|
|
|
|
\begin{docCsvKey}{filter accept all}{}{no value, initially set}
|
|
Alias for |no filter|. All consistent data lines are accepted.
|
|
\end{docCsvKey}
|
|
|
|
|
|
\begin{docCsvKey}{filter reject all}{}{no value}
|
|
All data line are ignored.
|
|
\end{docCsvKey}
|
|
|
|
|
|
|
|
\enlargethispage*{2cm}
|
|
\begin{docCsvKey}[][doc new=2016-07-01]{full filter}{=\meta{code}}{no default}
|
|
Technically, this key is an alias for \refKey{/csv/before filter}.
|
|
Philosophically, \refKey{/csv/before filter} computes something before
|
|
a filter condition is set, but \refKey{/csv/full filter} should implement
|
|
the full filtering. Especially, \refCom{csvfilteraccept} or
|
|
\refCom{csvfilterreject} \emph{should} be set inside the \meta{code}.
|
|
\begin{dispExample}
|
|
\csvreader[head to column names,tabular=llll,
|
|
table head=\toprule & \bfseries Name & \bfseries Matr & \bfseries Grade\\\midrule,
|
|
table foot=\bottomrule,
|
|
%>> list only matriculation numbers greater than 20000
|
|
% and grade less than 4.0 <<
|
|
full filter=\ifnumgreater{\matriculation}{20000}
|
|
{\ifdimless{\grade pt}{4.0pt}{\csvfilteraccept}{\csvfilterreject}}
|
|
{\csvfilterreject},
|
|
]{grade.csv}{}{%
|
|
\thecsvrow & \slshape\name, \givenname & \matriculation & \grade}
|
|
\end{dispExample}
|
|
\end{docCsvKey}
|
|
|
|
|
|
|
|
%]]
|
|
|
|
|
|
\clearpage
|
|
\subsection{Table Support}\label{subsec:tabsupport}%--------%[[
|
|
|
|
\begin{docCsvKey}{tabular}{=\meta{table format}}{style, no default}
|
|
Surrounds the CSV processing with |\begin{tabular}|\marg{table format}
|
|
at begin and with |\end{tabular}| at end.
|
|
Additionally, the commands defined by the key values of
|
|
\refKey{/csv/before table}, \refKey{/csv/table head}, \refKey{/csv/table foot},
|
|
and \refKey{/csv/after table} are executed at the appropriate places.
|
|
\end{docCsvKey}
|
|
|
|
|
|
\begin{docCsvKey}{centered tabular}{=\meta{table format}}{style, no default}
|
|
Like \refKey{/csv/tabular} but inside an additional |center| environment.
|
|
\end{docCsvKey}
|
|
|
|
|
|
\begin{docCsvKey}{longtable}{=\meta{table format}}{style, no default}
|
|
Like \refKey{/csv/tabular} but for the |longtable| environment.
|
|
This requires the package |longtable| (not loaded automatically).
|
|
\end{docCsvKey}
|
|
|
|
|
|
\begin{docCsvKey}{tabbing}{}{style, no value}
|
|
Like \refKey{/csv/tabular} but for the |tabbing| environment.
|
|
\end{docCsvKey}
|
|
|
|
|
|
\begin{docCsvKey}{centered tabbing}{}{style, no value}
|
|
Like \refKey{/csv/tabbing} but inside an additional |center| environment.
|
|
\end{docCsvKey}
|
|
|
|
|
|
\begin{docCsvKey}{no table}{}{style, no value}
|
|
Deactivates |tabular|, |longtable|, and |tabbing|.
|
|
\end{docCsvKey}
|
|
|
|
|
|
\begin{docCsvKey}{before table}{=\meta{code}}{no default, initially empty}
|
|
Sets the \meta{code} to be executed before |\begin{tabular}| or before |\begin{longtable}|
|
|
or before |\begin{tabbing}|, respectively.
|
|
\end{docCsvKey}
|
|
|
|
|
|
\begin{docCsvKey}{table head}{=\meta{code}}{no default, initially empty}
|
|
Sets the \meta{code} to be executed after |\begin{tabular}| or after |\begin{longtable}|
|
|
or after |\begin{tabbing}|, respectively.
|
|
\end{docCsvKey}
|
|
|
|
|
|
\begin{docCsvKey}{table foot}{=\meta{code}}{no default, initially empty}
|
|
Sets the \meta{code} to be executed before |\end{tabular}| or before |\end{longtable}|
|
|
or before |\end{tabbing}|, respectively.
|
|
\end{docCsvKey}
|
|
|
|
|
|
\begin{docCsvKey}{after table}{=\meta{code}}{no default, initially empty}
|
|
Sets the \meta{code} to be executed after |\end{tabular}| or after |\end{longtable}|
|
|
or after |\end{tabbing}|, respectively.
|
|
\end{docCsvKey}
|
|
|
|
\bigskip
|
|
|
|
The following |auto| options are the counterparts for the respective quick
|
|
overview commands like \refCom{csvautotabular}. They are listed for
|
|
completeness, but are unlikely to be used directly.
|
|
|
|
\begin{docCsvKey}{autotabular}{=\meta{file name}}{no default}
|
|
Reads the whole CSV file denoted \meta{file name} with an automated formatting.
|
|
\end{docCsvKey}
|
|
|
|
|
|
\begin{docCsvKey}{autolongtable}{=\meta{file name}}{no default}
|
|
Reads the whole CSV file denoted \meta{file name} with an automated formatting
|
|
using the required |longtable| package.
|
|
\end{docCsvKey}
|
|
|
|
|
|
\begin{docCsvKey}{autobooktabular}{=\meta{file name}}{no default}
|
|
Reads the whole CSV file denoted \meta{file name} with an automated formatting
|
|
using the required |booktabs| package.
|
|
\end{docCsvKey}
|
|
|
|
|
|
\begin{docCsvKey}{autobooklongtable}{=\meta{file name}}{no default}
|
|
Reads the whole CSV file denoted \meta{file name} with an automated formatting
|
|
using the required |booktabs| and |longtable| packages.
|
|
\end{docCsvKey}
|
|
|
|
|
|
\clearpage
|
|
\subsection{Special Characters}\label{subsec:specchar}
|
|
Be default, the CSV content is treated like normal \LaTeX\ text, see
|
|
Subsection~\ref{macrocodexample} on page~\pageref{macrocodexample}.
|
|
But, \TeX\ special characters of the CSV content may also be interpreted
|
|
as normal characters, if one or more of the following options are used.
|
|
|
|
\begin{docCsvKey}{respect tab}{\colOpt{=true\textbar false}}{default |true|, initially |false|}
|
|
If this key is set, every
|
|
tabulator sign
|
|
inside the CSV content is a normal character.
|
|
\end{docCsvKey}
|
|
|
|
\begin{docCsvKey}{respect percent}{\colOpt{=true\textbar false}}{default |true|, initially |false|}
|
|
If this key is set, every
|
|
percent sign \verbbox{\%}
|
|
inside the CSV content is a normal character.
|
|
\end{docCsvKey}
|
|
|
|
\begin{docCsvKey}{respect sharp}{\colOpt{=true\textbar false}}{default |true|, initially |false|}
|
|
If this key is set, every
|
|
sharp sign \verbbox{\#}
|
|
inside the CSV content is a normal character.
|
|
\end{docCsvKey}
|
|
|
|
\begin{docCsvKey}{respect dollar}{\colOpt{=true\textbar false}}{default |true|, initially |false|}
|
|
If this key is set, every
|
|
dollar sign \verbbox{\$}
|
|
inside the CSV content is a normal character.
|
|
\end{docCsvKey}
|
|
|
|
\begin{docCsvKey}{respect and}{\colOpt{=true\textbar false}}{default |true|, initially |false|}
|
|
If this key is set, every
|
|
and sign \verbbox{\&}
|
|
inside the CSV content is a normal character.
|
|
\end{docCsvKey}
|
|
|
|
\begin{docCsvKey}{respect backslash}{\colOpt{=true\textbar false}}{default |true|, initially |false|}
|
|
If this key is set, every
|
|
backslash sign \verbbox{\textbackslash}
|
|
inside the CSV content is a normal character.
|
|
\end{docCsvKey}
|
|
|
|
\begin{docCsvKey}{respect underscore}{\colOpt{=true\textbar false}}{default |true|, initially |false|}
|
|
If this key is set, every
|
|
underscore sign \verbbox{\_}
|
|
inside the CSV content is a normal character.
|
|
\end{docCsvKey}
|
|
|
|
\begin{docCsvKey}{respect tilde}{\colOpt{=true\textbar false}}{default |true|, initially |false|}
|
|
If this key is set, every
|
|
tilde sign \verbbox{\textasciitilde}
|
|
inside the CSV content is a normal character.
|
|
\end{docCsvKey}
|
|
|
|
\begin{docCsvKey}{respect circumflex}{\colOpt{=true\textbar false}}{default |true|, initially |false|}
|
|
If this key is set, every
|
|
circumflex sign \verbbox{\textasciicircum}
|
|
inside the CSV content is a normal character.
|
|
\end{docCsvKey}
|
|
|
|
\begin{docCsvKey}{respect leftbrace}{\colOpt{=true\textbar false}}{default |true|, initially |false|}
|
|
If this key is set, every
|
|
left brace sign \verbbox{\textbraceleft}
|
|
inside the CSV content is a normal character.
|
|
\end{docCsvKey}
|
|
|
|
\begin{docCsvKey}{respect rightbrace}{\colOpt{=true\textbar false}}{default |true|, initially |false|}
|
|
If this key is set, every
|
|
right brace sign \verbbox{\textbraceright}
|
|
inside the CSV content is a normal character.
|
|
\end{docCsvKey}
|
|
|
|
\begin{docCsvKey}{respect all}{}{style, no value, initially unset}
|
|
Set all special characters from above to normal characters. This means
|
|
a quite verbatim interpretation of the CSV content.
|
|
\end{docCsvKey}
|
|
|
|
\begin{docCsvKey}{respect none}{}{style, no value, initially set}
|
|
Do not change any special character from above to normal character.
|
|
\end{docCsvKey}
|
|
|
|
\clearpage
|
|
\subsection{Separators}\label{sec:separators}%
|
|
\begin{docCsvKey}{separator}{=\meta{sign}}{no default, initially |comma|}
|
|
\catcode `|=12
|
|
Sets the \meta{sign} which is treates as separator between the data values
|
|
of a data line. Feasible values are:
|
|
\begin{itemize}
|
|
\item\docValue{comma}: This is the initial value with '\texttt{,}' as separator.
|
|
\medskip
|
|
|
|
\item\docValue{semicolon}: Sets the separator to '\texttt{;}'.
|
|
\begin{dispExample}
|
|
% \usepackage{tcolorbox} for tcbverbatimwrite
|
|
\begin{tcbverbatimwrite}{testsemi.csv}
|
|
name;givenname;matriculation;gender;grade
|
|
Maier;Hans;12345;m;1.0
|
|
Huber;Anna;23456;f;2.3
|
|
Weißbäck;Werner;34567;m;5.0
|
|
\end{tcbverbatimwrite}
|
|
|
|
\csvautobooktabular[separator=semicolon]{testsemi.csv}
|
|
\end{dispExample}
|
|
\medskip
|
|
|
|
\item\docValue{pipe}: Sets the separator to '\texttt{|}'.
|
|
\begin{dispExample}
|
|
% \usepackage{tcolorbox} for tcbverbatimwrite
|
|
\begin{tcbverbatimwrite}{pipe.csv}
|
|
name|givenname|matriculation|gender|grade
|
|
Maier|Hans|12345|m|1.0
|
|
Huber|Anna|23456|f|2.3
|
|
Weißbäck|Werner|34567|m|5.0
|
|
\end{tcbverbatimwrite}
|
|
|
|
\csvautobooktabular[separator=pipe]{pipe.csv}
|
|
\end{dispExample}
|
|
\medskip
|
|
|
|
\item\docValue{tab}: Sets the separator to the tabulator sign.
|
|
Automatically, \refKey{/csv/respect tab} is set also.
|
|
\end{itemize}
|
|
\end{docCsvKey}
|
|
|
|
\clearpage
|
|
\subsection{Miscellaneous}%
|
|
|
|
\begin{docCsvKey}{every csv}{}{style, initially empty}
|
|
A style definition which is used for every following CSV file.
|
|
This definition can be overwritten with user code.
|
|
\begin{dispListing}
|
|
% Sets a warning message for unfeasible data lines.
|
|
\csvset{every csv/.style={warn on column count error}}
|
|
% Alternatively:
|
|
\csvstyle{every csv}{warn on column count error}
|
|
\end{dispListing}
|
|
\end{docCsvKey}
|
|
|
|
\begin{docCsvKey}{default}{}{style}
|
|
A style definition which is used for every following CSV file which
|
|
resets all settings to default values\footnote{\texttt{default} is used
|
|
because of the global nature of most settings.}.
|
|
This key should not be used or changed by the user if there is not a
|
|
really good reason (and you know what you do).
|
|
\end{docCsvKey}
|
|
|
|
|
|
\begin{docCsvKey}{file}{=\meta{file name}}{no default, initially |unknown.csv|}
|
|
Sets the \meta{file name} of the CSV file to be processed.
|
|
\end{docCsvKey}
|
|
|
|
|
|
\begin{docCsvKey}{preprocessed file}{=\meta{file name}}{no default, initially \texttt{\textbackslash\detokenize{jobname_sorted.csv}}}
|
|
Sets the \meta{file name} of the CSV file which is the output of a
|
|
preprocessor.
|
|
\end{docCsvKey}
|
|
|
|
|
|
\begin{docCsvKey}{preprocessor}{=\meta{macro}}{no default}
|
|
Defines a preprocessor for the given CSV file.
|
|
The \meta{macro} has to have two mandatory arguments. The first argument
|
|
is the original CSV file which is set by \refKey{/csv/file}.
|
|
The second argument is the preprocessed CSV file
|
|
which is set by \refKey{/csv/preprocessed file}.\par\smallskip
|
|
Typically, the \meta{macro} may call an external program which preprocesses
|
|
the original CSV file (e.\,g. sorting the file) and creates the
|
|
preprocessed CSV file. The later file is used by \refCom{csvreader}
|
|
or \refCom{csvloop}.
|
|
\begin{dispListing}
|
|
\newcommand{\mySortTool}[2]{%
|
|
% call to an external program to sort file #1 with resulting file #2
|
|
}
|
|
|
|
\csvreader[%
|
|
preprocessed file=\jobname_sorted.csv,
|
|
preprocessor=\mySortTool,
|
|
]{some.csv}{}{%
|
|
% do something
|
|
}
|
|
\end{dispListing}
|
|
See Subsection~\ref{sec:Sorting} on page~\pageref{sec:Sorting} for a
|
|
concrete sorting preprocessing implemented with an external tool.
|
|
\end{docCsvKey}
|
|
|
|
|
|
\begin{docCsvKey}{no preprocessing}{}{style, no value, initially set}
|
|
Clears any preprocessing, i.\,e. preprocessing is switched of.
|
|
\end{docCsvKey}
|
|
|
|
|
|
|
|
\clearpage
|
|
\subsection{Sorting}\label{sec:Sorting}%
|
|
\TeX/\LaTeX\ was not born under a sorting planet. |csvsimple-legacy| provides no
|
|
sorting of data lines by \LaTeX-methods since sorting can be done much faster
|
|
and much better by external tools.
|
|
|
|
First, one should consider the appropriate \emph{place} for sorting:
|
|
\begin{itemize}
|
|
\item CSV files may be sorted by a tool \emph{before} the \LaTeX\ document is processed
|
|
at all. If the CSV data is not likely to change, this is the most efficient method.
|
|
\item CSV files may be sorted by a tool every time before the \LaTeX\ document is compiled.
|
|
This could be automated by a shell script or some processing tool like |arara|.
|
|
\item CSV files may be sorted on-the-fly by a tool during compilation of
|
|
a \LaTeX\ document. This is the most elegant but not the most efficient way.
|
|
\end{itemize}
|
|
|
|
The first two methods are decoupled from anything concerning |csvsimple-legacy|.
|
|
For the third method, the \refKey{/csv/preprocessor} option is made for.
|
|
This allows to access an external tool for sorting.
|
|
\emph{Which tool} is your choice.
|
|
|
|
\csvsorter\ was written as a companion tool for |csvsimple|.
|
|
It is an open source Java command-line tool for sorting CSV files, available at\\
|
|
\url{http://T-F-S.github.io/csvsorter/}\quad or\quad
|
|
\url{https://github.com/T-F-S/csvsorter}
|
|
|
|
It can be
|
|
used for all three sorting approaches described above.
|
|
There is special support for on-the-fly sorting with \csvsorter\ using the
|
|
following options.
|
|
|
|
\begin{enumerate}\bfseries
|
|
\item To use the sorting options, you have to install \csvsorter\ before!\\
|
|
|csvsimple| v1.12 or newer needs \csvsorter\ v0.94 of newer!
|
|
\item You have to give permission to call external tools during
|
|
compilation, i.\,e.\ the command-line options for |latex| have to include
|
|
|-shell-escape|.
|
|
\end{enumerate}
|
|
|
|
\bigskip
|
|
|
|
\begin{docCsvKey}{csvsorter command}{=\meta{system command}}{no default, initially |csvsorter|}
|
|
The \meta{system command} specifies the system call for \csvsorter\ (without the options).
|
|
If \csvsorter\ was completely installed following its documentation, there is
|
|
nothing to change here. If the |csvsorter.jar| file is inside the same
|
|
directory as the \LaTeX\ source file, you may configure:% preferrably inside the preamble:
|
|
\begin{dispListing}
|
|
\csvset{csvsorter command=java -jar csvsorter.jar}
|
|
\end{dispListing}
|
|
\end{docCsvKey}
|
|
|
|
\begin{docCsvKey}{csvsorter configpath}{=\meta{path}}{no default, initially |.|}
|
|
Sorting with \csvsorter\ is done using XML configuration files. If these files
|
|
are not stored inside the same directory as the \LaTeX\ source file, a
|
|
\meta{path} to access them can be configured:
|
|
\begin{dispListing}
|
|
\csvset{csvsorter configpath=xmlfiles}
|
|
\end{dispListing}
|
|
Here, the configuration files would be stored in a subdirectory named |xmlfiles|.
|
|
\end{docCsvKey}
|
|
|
|
\begin{docCsvKey}{csvsorter log}{=\meta{file name}}{no default, initially |csvsorter.log|}
|
|
Sets the log file of \csvsorter\ to the given \meta{file name}.
|
|
\begin{dispListing}
|
|
\csvset{csvsorter log=outdir/csvsorter.log}
|
|
\end{dispListing}
|
|
Here, the log file is written to a subdirectory named |outdir|.
|
|
\end{docCsvKey}
|
|
|
|
\clearpage
|
|
\begin{docCsvKey}{csvsorter token}{=\meta{file name}}{no default, initially |\textbackslash jobname.csvtoken|}
|
|
Sets \meta{file name} as token file. This is an auxiliary file which
|
|
communicates the success of \csvsorter\ to |csvsimple|.
|
|
\begin{dispListing}
|
|
\csvset{csvsorter log=outdir/\jobname.csvtoken}
|
|
\end{dispListing}
|
|
Here, the token file is written to a subdirectory named |outdir|.
|
|
\end{docCsvKey}
|
|
|
|
|
|
\begin{docCsvKey}{sort by}{=\meta{file name}}{style, initially unset}
|
|
The \meta{file name} denotes an XML configuration file for \csvsorter.
|
|
Setting this option inside \refCom{csvreader} or
|
|
\refCom{csvloop} will issue a system call to \csvsorter.
|
|
\begin{itemize}
|
|
\item \csvsorter\ uses the given CSV file as input file.
|
|
\item \csvsorter\ uses \meta{file name} as configuration file.
|
|
\item The output CSV file is denoted by \refKey{/csv/preprocessed file}
|
|
which is by default \texttt{\textbackslash\detokenize{jobname_sorted.csv}}.
|
|
This output file is this actual file processed by \refCom{csvreader} or \refCom{csvloop}.
|
|
\item \csvsorter\ also generates a log file denoted by \refKey{/csv/csvsorter log} which is by default |csvsorter.log|.
|
|
\end{itemize}
|
|
|
|
\par\medskip\textbf{First example:}
|
|
To sort our example |grade.csv| file according to |name| and |givenname|, we
|
|
use the following XML configuration file. Since \csvsorter\ uses double quotes
|
|
as default brackets for column values, we remove bracket recognition to avoid
|
|
a clash with the escaped umlauts of the example CSV file.\par\smallskip
|
|
|
|
\xmllisting{namesort}
|
|
\begin{dispExample}
|
|
% \usepackage{booktabs}
|
|
\csvreader[sort by=namesort.xml,
|
|
head to column names,
|
|
tabular=>{\color{red}}lllll,
|
|
table head=\toprule Name & Given Name & Matriculation & Gender & Grade\\\midrule,
|
|
table foot=\bottomrule]
|
|
{grade.csv}{}{\csvlinetotablerow}
|
|
\end{dispExample}
|
|
|
|
\clearpage\textbf{Second example:}
|
|
To sort our example |grade.csv| file according to |grade|, we
|
|
use the following XML configuration file. Further, persons with the same |grade|
|
|
are sorted by |name| and |givenname|. Since \csvsorter\ uses double quotes
|
|
as default brackets for column values, we remove bracket recognition to avoid
|
|
a clash with the escaped umlauts of the example CSV file.\par\smallskip
|
|
|
|
\xmllisting{gradesort}
|
|
\begin{dispExample}
|
|
% \usepackage{booktabs}
|
|
\csvreader[sort by=gradesort.xml,
|
|
head to column names,
|
|
tabular=llll>{\color{red}}l,
|
|
table head=\toprule Name & Given Name & Matriculation & Gender & Grade\\\midrule,
|
|
table foot=\bottomrule]
|
|
{grade.csv}{}{\csvlinetotablerow}
|
|
\end{dispExample}
|
|
|
|
\clearpage\textbf{Third example:}
|
|
To generate a matriculation/grade list, we sort our example |grade.csv| file
|
|
using the following XML configuration file.
|
|
Again, since \csvsorter\ uses double quotes
|
|
as default brackets for column values, we remove bracket recognition to avoid
|
|
a clash with the escaped umlauts of the example CSV file.\par\smallskip
|
|
|
|
\xmllisting{matriculationsort}
|
|
\begin{dispExample}
|
|
% \usepackage{booktabs}
|
|
\csvreader[sort by=matriculationsort.xml,
|
|
head to column names,
|
|
tabular=>{\color{red}}ll,
|
|
table head=\toprule Matriculation & Grade\\\midrule,
|
|
table foot=\bottomrule]
|
|
{grade.csv}{}{\matriculation & \grade}
|
|
\end{dispExample}
|
|
\end{docCsvKey}
|
|
|
|
|
|
\clearpage
|
|
\begin{docCsvKey}{new sorting rule}{=\marg{name}\marg{file name}}{style, initially unset}
|
|
This is a convenience option to generate a new shortcut for often used
|
|
\refKey{/csv/sort by} applications. It also adds a more semantic touch.
|
|
The new shortcut option is
|
|
\tcbox[on line,size=small,colback=white,colframe=red]{|sort by| \meta{name}} which expands to
|
|
\tcbox[on line,size=small,colback=white,colframe=red]{|sort by=|\marg{file name}}.\par\medskip
|
|
|
|
Consider the following example:
|
|
\begin{dispExample}
|
|
\csvautotabular[sort by=namesort.xml]{grade.csv}
|
|
\end{dispExample}
|
|
A good place for setting up a new sorting rule would be inside the preamble:
|
|
|
|
\csvset{new sorting rule={name}{namesort.xml}}
|
|
\begin{dispListing}
|
|
\csvset{new sorting rule={name}{namesort.xml}}
|
|
\end{dispListing}
|
|
|
|
Now, we can use the new rule:
|
|
\begin{dispExample}
|
|
\csvautotabular[sort by name]{grade.csv}
|
|
\end{dispExample}
|
|
|
|
\end{docCsvKey}
|
|
|
|
|
|
\clearpage
|
|
\section{String Tests}\label{sec:stringtests}%
|
|
|
|
The following string tests are complementing the string tests
|
|
from the |etoolbox| package. They all do the same, i.e.,
|
|
comparing expanded strings for equality.
|
|
\begin{itemize}
|
|
\item\refCom{ifcsvstrcmp} is the most efficient method, because it uses
|
|
native compiler string comparison (if available).
|
|
\item\refCom{ifcsvstrequal} does not rely on a compiler. It also is the
|
|
fallback implementation for \refCom{ifcsvstrcmp}, if there is no
|
|
native comparison method.
|
|
\item\refCom{ifcsvprostrequal} is possibly more failsafe than the other two
|
|
string tests. It may be used, if strings contain dirty things like |\textbf{A}|.
|
|
\end{itemize}
|
|
\medskip
|
|
|
|
\begin{docCommand}[doc new=2016-07-01]{ifcsvstrcmp}{\marg{stringA}\marg{stringB}\marg{true}\marg{false}}
|
|
Compares two strings and executes \meta{true} if they are equal, and \meta{false} otherwise.
|
|
The comparison is done using |\pdfstrcmp|, if compilation is done with pdf\LaTeX.
|
|
The comparison is done using |\pdf@strcmp|, if the package |pdftexcmds| is
|
|
loaded and compilation is done with lua\LaTeX\ or Xe\LaTeX.
|
|
Otherwise, \refCom{ifcsvstrcmp} is identical to \refCom{ifcsvstrequal}.
|
|
This command cannot be used inside the preamble.
|
|
\end{docCommand}
|
|
|
|
|
|
\begin{docCommand}[doc new=2016-07-01]{ifcsvnotstrcmp}{\marg{stringA}\marg{stringB}\marg{true}\marg{false}}
|
|
Compares two strings and executes \meta{true} if they are \emph{not} equal, and \meta{false} otherwise.
|
|
The implementation uses \refCom{ifcsvstrcmp}.
|
|
\end{docCommand}
|
|
|
|
|
|
\begin{docCommand}[doc new=2016-07-01]{ifcsvstrequal}{\marg{stringA}\marg{stringB}\marg{true}\marg{false}}
|
|
Compares two strings and executes \meta{true} if they are equal, and \meta{false} otherwise.
|
|
The strings are expanded with |\edef| in the test.
|
|
\end{docCommand}
|
|
|
|
\begin{docCommand}[doc new=2016-07-01]{ifcsvprostrequal}{\marg{stringA}\marg{stringB}\marg{true}\marg{false}}
|
|
Compares two strings and executes \meta{true} if they are equal, and \meta{false} otherwise.
|
|
The strings are expanded with |\protected@edef| in the test, i.e. parts of the
|
|
strings which are protected stay unexpanded.
|
|
\end{docCommand}
|
|
|
|
|
|
|
|
\clearpage
|
|
\section{Examples}%
|
|
|
|
\subsection{A Serial Letter}%
|
|
In this example, a serial letter is to be written to all persons with
|
|
addresses from the following CSV file. Deliberately, the file content is
|
|
not given in very pretty format.
|
|
|
|
%-- file embedded for simplicity --
|
|
\begin{tcbverbatimwrite}{address.csv}
|
|
name,givenname,gender,degree,street,zip,location,bonus
|
|
Maier,Hans,m,,Am Bachweg 17,10010,Hopfingen,20
|
|
% next line with a comma in curly braces
|
|
Huber,Erna,f,Dr.,{Moosstraße 32, Hinterschlag},10020,Örtingstetten,30
|
|
Weißbäck,Werner,m,Prof. Dr.,Brauallee 10,10030,Klingenbach,40
|
|
% this line is ignored %
|
|
Siebener , Franz,m, , Blaumeisenweg 12 , 10040 , Pardauz , 50
|
|
% preceding and trailing spaces in entries are removed %
|
|
Schmitt,Anton,m,,{\AE{}lfred-Esplanade, T\ae{}g 37}, 10050,\OE{}resung,60
|
|
\end{tcbverbatimwrite}
|
|
%-- end embedded file --
|
|
|
|
\csvlisting{address}
|
|
|
|
Firstly, we survey the file content quickly using
|
|
|\csvautotabular|.
|
|
As can be seen, unfeasible lines are ignored automatically.
|
|
|
|
\begin{dispExample}
|
|
\tiny\csvautotabular{address.csv}
|
|
\end{dispExample}
|
|
|
|
Now, we create the serial letter where every feasible data line produces
|
|
an own page. Here, we simulate the page by a |tcolorbox| (from the package
|
|
|tcolorbox|).
|
|
For the gender specific salutations, an auxiliary macro |\ifmale| is
|
|
introduced.
|
|
|
|
\begin{dispExample}
|
|
% this example requires the tcolorbox package
|
|
\newcommand{\ifmale}[2]{\ifcsvstrcmp{\gender}{m}{#1}{#2}}
|
|
|
|
\csvreader[head to column names]{address.csv}{}{%
|
|
\begin{tcolorbox}[colframe=DarkGray,colback=White,arc=0mm,width=(\linewidth-2pt)/2,
|
|
equal height group=letter,before=,after=\hfill,fonttitle=\bfseries,
|
|
adjusted title={Letter to \name}]
|
|
\ifcsvstrcmp{\degree}{}{\ifmale{Mr.}{Ms.}}{\degree}~\givenname~\name\\
|
|
\street\\\zip~\location
|
|
\tcblower
|
|
{\itshape Dear \ifmale{Sir}{Madam},}\\
|
|
we are pleased to announce you a bonus value of \bonus\%{}
|
|
which will be delivered to \location\ soon.\\\ldots
|
|
\end{tcolorbox}}
|
|
\end{dispExample}
|
|
|
|
|
|
|
|
\clearpage
|
|
\subsection{A Graphical Presentation}%
|
|
For this example, we use some artificial statistical data given by a CSV file.
|
|
|
|
%-- file embedded for simplicity --
|
|
\begin{tcbverbatimwrite}{data.csv}
|
|
land,group,amount
|
|
Bayern,A,1700
|
|
Baden-Württemberg,A,2300
|
|
Sachsen,B,1520
|
|
Thüringen,A,1900
|
|
Hessen,B,2100
|
|
\end{tcbverbatimwrite}
|
|
%-- end embedded file --
|
|
|
|
\csvlisting{data}
|
|
|
|
Firstly, we survey the file content using
|
|
|\csvautobooktabular|.
|
|
|
|
\begin{dispExample}
|
|
% needs the booktabs package
|
|
\csvautobooktabular{data.csv}
|
|
\end{dispExample}
|
|
|
|
The amount values are presented in the following diagram by bars where
|
|
the group classification is given using different colors.
|
|
|
|
\begin{dispExample}
|
|
% This example requires the package tikz
|
|
\begin{tikzpicture}[Group/A/.style={left color=red!10,right color=red!20},
|
|
Group/B/.style={left color=blue!10,right color=blue!20}]
|
|
\csvreader[head to column names]{data.csv}{}{%
|
|
\begin{scope}[yshift=-\thecsvrow cm]
|
|
\path [draw,Group/\group] (0,-0.45)
|
|
rectangle node[font=\bfseries] {\amount} (\amount/1000,0.45);
|
|
\node[left] at (0,0) {\land};
|
|
\end{scope} }
|
|
\end{tikzpicture}
|
|
\end{dispExample}
|
|
|
|
|
|
\clearpage
|
|
It would be nice to sort the bars by length, i.\,e.\ to sort the CSV file
|
|
by the |amount| column. If the \csvsorter\ program is properly installed,
|
|
see Subsection~\ref{sec:Sorting} on page~\pageref{sec:Sorting},
|
|
this can be done with the following configuration file for \csvsorter:
|
|
|
|
\xmllisting{amountsort}
|
|
|
|
Now, we just have to add an option |sort by=amountsort.xml|:
|
|
\begin{dispExample}
|
|
% This example requires the package tikz
|
|
% Also, the CSV-Sorter tool has to be installed
|
|
\begin{tikzpicture}[Group/A/.style={left color=red!10,right color=red!20},
|
|
Group/B/.style={left color=blue!10,right color=blue!20}]
|
|
\csvreader[head to column names,sort by=amountsort.xml]{data.csv}{}{%
|
|
\begin{scope}[yshift=-\thecsvrow cm]
|
|
\path [draw,Group/\group] (0,-0.45)
|
|
rectangle node[font=\bfseries] {\amount} (\amount/1000,0.45);
|
|
\node[left] at (0,0) {\land};
|
|
\end{scope} }
|
|
\end{tikzpicture}
|
|
\end{dispExample}
|
|
|
|
|
|
|
|
|
|
\clearpage
|
|
Next, we create a pie chart by calling |\csvreader| twice.
|
|
In the first step, the total sum of amounts is computed, and in the second
|
|
step the slices are drawn.
|
|
|
|
\begin{dispExample}
|
|
% Modified example from www.texample.net for pie charts
|
|
% This example needs the packages tikz, xcolor, calc
|
|
\definecolorseries{myseries}{rgb}{step}[rgb]{.95,.85,.55}{.17,.47,.37}
|
|
\resetcolorseries{myseries}%
|
|
|
|
% a pie slice
|
|
\newcommand{\slice}[4]{
|
|
\pgfmathsetmacro{\midangle}{0.5*#1+0.5*#2}
|
|
\begin{scope}
|
|
\clip (0,0) -- (#1:1) arc (#1:#2:1) -- cycle;
|
|
\colorlet{SliceColor}{myseries!!+}%
|
|
\fill[inner color=SliceColor!30,outer color=SliceColor!60] (0,0) circle (1cm);
|
|
\end{scope}
|
|
\draw[thick] (0,0) -- (#1:1) arc (#1:#2:1) -- cycle;
|
|
\node[label=\midangle:#4] at (\midangle:1) {};
|
|
\pgfmathsetmacro{\temp}{min((#2-#1-10)/110*(-0.3),0)}
|
|
\pgfmathsetmacro{\innerpos}{max(\temp,-0.5) + 0.8}
|
|
\node at (\midangle:\innerpos) {#3};
|
|
}
|
|
|
|
% sum of amounts
|
|
\csvreader[before reading=\def\mysum{0}]{data.csv}{amount=\amount}{%
|
|
\pgfmathsetmacro{\mysum}{\mysum+\amount}%
|
|
}
|
|
|
|
% drawing of the pie chart
|
|
\begin{tikzpicture}[scale=3]%
|
|
\def\mya{0}\def\myb{0}
|
|
\csvreader[head to column names]{data.csv}{}{%
|
|
\let\mya\myb
|
|
\pgfmathsetmacro{\myb}{\myb+\amount}
|
|
\slice{\mya/\mysum*360}{\myb/\mysum*360}{\amount}{\land}
|
|
}
|
|
\end{tikzpicture}%
|
|
\end{dispExample}
|
|
|
|
|
|
\clearpage
|
|
Finally, the filter option is demonstrated by separating the groups A and B.
|
|
Every item is piled upon the appropriate stack.
|
|
|
|
\begin{dispExample}
|
|
\newcommand{\drawGroup}[2]{%
|
|
\def\mya{0}\def\myb{0}
|
|
\node[below=3mm] at (2.5,0) {\bfseries Group #1};
|
|
\csvreader[head to column names,filter equal={\group}{#1}]{data.csv}{}{%
|
|
\let\mya\myb
|
|
\pgfmathsetmacro{\myb}{\myb+\amount}
|
|
\path[draw,top color=#2!25,bottom color=#2!50]
|
|
(0,\mya/1000) rectangle node{\land\ (\amount)} (5,\myb/1000);
|
|
}}
|
|
|
|
\begin{tikzpicture}
|
|
\fill[gray!75] (-1,0) rectangle (13,-0.1);
|
|
\drawGroup{A}{red}
|
|
\begin{scope}[xshift=7cm]
|
|
\drawGroup{B}{blue}
|
|
\end{scope}
|
|
\end{tikzpicture}
|
|
|
|
\end{dispExample}
|
|
|
|
|
|
\clearpage
|
|
\subsection{Macro code inside the data}\label{macrocodexample}%
|
|
|
|
If needed, the data file may contain macro code. Note that the first character
|
|
of a data line is not allowed to be the backslash '|\|'.
|
|
|
|
%-- file embedded for simplicity --
|
|
\begin{tcbverbatimwrite}{macrodata.csv}
|
|
type,description,content
|
|
M,A nice \textbf{formula}, $\displaystyle \int\frac{1}{x} = \ln|x|+c$
|
|
G,A \textcolor{red}{colored} ball, {\tikz \shadedraw [shading=ball] (0,0) circle (.5cm);}
|
|
M,\textbf{Another} formula, $\displaystyle \lim\limits_{n\to\infty} \frac{1}{n}=0$
|
|
\end{tcbverbatimwrite}
|
|
%-- end embedded file --
|
|
|
|
\csvlisting{macrodata}
|
|
|
|
Firstly, we survey the file content using
|
|
|\csvautobooktabular|.
|
|
|
|
\begin{dispExample}
|
|
\csvautobooktabular{macrodata.csv}
|
|
\end{dispExample}
|
|
|
|
|
|
\begin{dispExample}
|
|
\csvstyle{my enumerate}{head to column names,
|
|
before reading=\begin{enumerate},after reading=\end{enumerate}}
|
|
|
|
\csvreader[my enumerate]{macrodata.csv}{}{%
|
|
\item \description:\par\content}
|
|
|
|
\bigskip
|
|
Now, formulas only:
|
|
\csvreader[my enumerate,filter equal={\type}{M}]{macrodata.csv}{}{%
|
|
\item \description:\qquad\content}
|
|
\end{dispExample}
|
|
|
|
\clearpage
|
|
\subsection{Tables with Number Formatting}\label{numberformatting}%
|
|
|
|
We consider a file with numerical data which should be pretty-printed.
|
|
|
|
%-- file embedded for simplicity --
|
|
\begin{tcbverbatimwrite}{data_numbers.csv}
|
|
month, dogs, cats
|
|
January, 12.50,12.3e5
|
|
February, 3.32, 8.7e3
|
|
March, 43, 3.1e6
|
|
April, 0.33, 21.2e4
|
|
May, 5.12, 3.45e6
|
|
June, 6.44, 6.66e6
|
|
July, 123.2,7.3e7
|
|
August, 12.3, 5.3e4
|
|
September,2.3, 4.4e4
|
|
October, 6.5, 6.5e6
|
|
November, 0.55, 5.5e5
|
|
December, 2.2, 3.3e3
|
|
\end{tcbverbatimwrite}
|
|
|
|
\csvlisting{data_numbers}
|
|
|
|
The |siunitx| package provides a new column type |S|
|
|
which can align material using a number of different strategies.
|
|
The following example demonstrates the application with CSV reading.
|
|
The package documentation of |siunitx| contains a huge amount
|
|
of formatting options.
|
|
|
|
\begin{dispExample}
|
|
% \usepackage{siunitx,array,booktabs}
|
|
\csvloop{
|
|
file=data_numbers.csv,
|
|
head to column names,
|
|
before reading=\centering\sisetup{table-number-alignment=center},
|
|
tabular={lSS[table-format=2.2e1]@{}c},
|
|
table head=\toprule\textbf{Month} & \textbf{Dogs} & \textbf{Cats} &\\\midrule,
|
|
command=\month & \dogs & \cats &,
|
|
table foot=\bottomrule}
|
|
\end{dispExample}
|
|
|
|
\clearpage
|
|
Special care is needed, if the \emph{first} or the \emph{last} column is to be formatted with
|
|
the column type |S|. The number detection of |siunitx| is disturbed by
|
|
the line reading code of |csvsimple-legacy| which actually is present at the
|
|
first and last column. To avoid this problem, the content of the first and last column
|
|
could be formatted not by the table format definition, but by using a
|
|
suitable |\tablenum| formatting directly, see |siunitx|.
|
|
|
|
Another and very nifty workaround suggested by Enrico Gregorio is to
|
|
add an invisible dummy column with |c@{}| as first column
|
|
and |@{}c| as last column:
|
|
|
|
|
|
\begin{dispExample}
|
|
% \usepackage{siunitx,array,booktabs}
|
|
\csvloop{
|
|
file=data_numbers.csv,
|
|
head to column names,
|
|
before reading=\centering\sisetup{table-number-alignment=center},
|
|
tabular={c@{}S[table-format=2.2e1]S@{}c},
|
|
table head= & \textbf{Cats} & \textbf{Dogs} & \\\midrule,
|
|
command= & \cats & \dogs &,
|
|
table foot=\bottomrule}
|
|
\end{dispExample}
|
|
|
|
|
|
\clearpage
|
|
Now, the preceding table shall be sorted by the \emph{cats} values.
|
|
If the \csvsorter\ program is properly installed,
|
|
see Subsection~\ref{sec:Sorting} on page~\pageref{sec:Sorting},
|
|
this can be done with the following configuration file for \csvsorter:
|
|
|
|
\xmllisting{catsort}
|
|
|
|
Now, we just have to add an option |sort by=catsort.xml|:
|
|
\begin{dispExample}
|
|
% \usepackage{siunitx,array,booktabs}
|
|
% Also, the CSV-Sorter tool has to be installed
|
|
\csvloop{
|
|
file=data_numbers.csv,
|
|
sort by=catsort.xml,
|
|
head to column names,
|
|
before reading=\centering\sisetup{table-number-alignment=center},
|
|
tabular={lSS[table-format=2.2e1]@{}c},
|
|
table head=\toprule\textbf{Month} & \textbf{Dogs} & \textbf{Cats} & \\\midrule,
|
|
command=\month & \dogs & \cats &,
|
|
table foot=\bottomrule}
|
|
\end{dispExample}
|
|
|
|
|
|
\clearpage
|
|
\subsection{CSV data without header line}\label{noheader}%
|
|
CSV files with a header line are more semantic than files without header,
|
|
but it's no problem to work with headless files.
|
|
|
|
For this example, we use again some artificial statistical data given by a CSV file
|
|
but this time without header.
|
|
|
|
%-- file embedded for simplicity --
|
|
\begin{tcbverbatimwrite}{data_headless.csv}
|
|
Bayern,A,1700
|
|
Baden-Württemberg,A,2300
|
|
Sachsen,B,1520
|
|
Thüringen,A,1900
|
|
Hessen,B,2100
|
|
\end{tcbverbatimwrite}
|
|
%-- end embedded file --
|
|
|
|
\csvlisting{data_headless}
|
|
|
|
Note that you cannot use the \refKey{/csv/no head} option for the auto tabular
|
|
commands. If no options are given, the first line is interpreted as header line
|
|
which gives an unpleasant result:
|
|
|
|
\begin{dispExample}
|
|
\csvautobooktabular{data_headless.csv}
|
|
\end{dispExample}
|
|
|
|
To get the expected result, one can redefine \refKey{/csv/table head}
|
|
using \refCom{csvlinetotablerow} which holds the first line data for the
|
|
|\csvauto...| commands:
|
|
|
|
\begin{dispExample}
|
|
\csvautobooktabular[table head=\toprule\csvlinetotablerow\\]{data_headless.csv}
|
|
\end{dispExample}
|
|
|
|
This example can be extended to insert a table head for this headless data:
|
|
|
|
\begin{dispExample}
|
|
\csvautobooktabular[table head=\toprule\bfseries Land & \bfseries Group
|
|
& \bfseries Amount\\\midrule\csvlinetotablerow\\]{data_headless.csv}
|
|
\end{dispExample}
|
|
|
|
\clearpage
|
|
|
|
For the normal \refCom{csvreader} command, the \refKey{/csv/no head} option
|
|
should be applied. Of course, we cannot use \refKey{/csv/head to column names}
|
|
because there is no head, but the columns can be addressed by their numbers:
|
|
|
|
\begin{dispExample}
|
|
\csvreader[no head,
|
|
tabular=lr,
|
|
table head=\toprule\bfseries Land & \bfseries Amount\\\midrule,
|
|
table foot=\bottomrule]
|
|
{data_headless.csv}
|
|
{1=\land,3=\amount}
|
|
{\land & \amount}
|
|
\end{dispExample}
|
|
|
|
|
|
\clearpage
|
|
\subsection{Imported CSV data}\label{sec:importeddata}%
|
|
If data is imported from other applications, there is not always a choice
|
|
to format in comma separated values with curly brackets.
|
|
|
|
Consider the following example data file:
|
|
|
|
%-- file embedded for simplicity --
|
|
\begin{tcbverbatimwrite}{imported.csv}
|
|
"name";"address";"email"
|
|
"Frank Smith";"Yellow Road 123, Brimblsby";"frank.smith@organization.org"
|
|
"Mary May";"Blue Alley 2a, London";"mmay@maybe.uk"
|
|
"Hans Meier";"Hauptstraße 32, Berlin";"hans.meier@corporation.de"
|
|
\end{tcbverbatimwrite}
|
|
%-- end embedded file --
|
|
|
|
\csvlisting{imported}
|
|
|
|
If the \csvsorter\ program is properly installed,
|
|
see Subsection~\ref{sec:Sorting} on page~\pageref{sec:Sorting},
|
|
this can be transformed on-the-fly
|
|
with the following configuration file for \csvsorter:
|
|
|
|
\xmllisting{transform}
|
|
|
|
Now, we just have to add an option |sort by=transform.xml| to transform
|
|
the input data. Here, we actually do not sort.
|
|
|
|
\begin{dispExample}
|
|
% \usepackage{booktabs,array}
|
|
% Also, the CSV-Sorter tool has to be installed
|
|
\newcommand{\Header}[1]{\normalfont\bfseries #1}
|
|
|
|
\csvreader[
|
|
sort by=transform.xml,
|
|
tabular=>{\itshape}ll>{\ttfamily}l,
|
|
table head=\toprule\Header{Name} & \Header{Address} & \Header{email}\\\midrule,
|
|
table foot=\bottomrule]
|
|
{imported.csv}{}{\csvlinetotablerow}
|
|
\end{dispExample}
|
|
|
|
The file which is generated on-the-fly and which is actually read by
|
|
|csvsimple-legacy| is the following:
|
|
|
|
\tcbinputlisting{docexample,listing style=tcbdocumentation,fonttitle=\bfseries,
|
|
listing only,listing file=\jobname_sorted._csv}
|
|
|
|
|
|
\clearpage
|
|
\subsection{Encoding}\label{encoding}%
|
|
If the CSV file has a different encoding than the \LaTeX\ source file,
|
|
then special care is needed.
|
|
|
|
\begin{itemize}
|
|
\item The most obvious treatment is to change the encoding of the CSV file
|
|
or the \LaTeX\ source file to match the other one (every good editor
|
|
supports such a conversion). This is the easiest choice, if there a no
|
|
good reasons against such a step. E.g., unfortunately, several tools
|
|
under Windows need the CSV file to be |cp1252| encoded while
|
|
the \LaTeX\ source file may need to be |utf8| encoded.
|
|
|
|
\item The |inputenc| package allows to switch the encoding inside the
|
|
document, say from |utf8| to |cp1252|. Just be aware that you should only
|
|
use pure ASCII for additional texts inside the switched region.
|
|
\begin{dispListing}
|
|
% !TeX encoding=UTF-8
|
|
% ....
|
|
\usepackage[utf8]{inputenc}
|
|
% ....
|
|
\begin{document}
|
|
% ....
|
|
\inputencoding{latin1}% only use ASCII from here, e.g. "Uberschrift
|
|
\csvreader[%...
|
|
]{data_cp1252.csv}{%...
|
|
}{% ....
|
|
}
|
|
\inputencoding{utf8}
|
|
% ....
|
|
\end{document}
|
|
\end{dispListing}
|
|
|
|
\item As a variant to the last method, the encoding switch can be done
|
|
using options from |csvsimple-legacy|:
|
|
\begin{dispListing}
|
|
% !TeX encoding=UTF-8
|
|
% ....
|
|
\usepackage[utf8]{inputenc}
|
|
% ....
|
|
\begin{document}
|
|
% ....
|
|
% only use ASCII from here, e.g. "Uberschrift
|
|
\csvreader[%...
|
|
before reading=\inputencoding{latin1},
|
|
after reading=\inputencoding{utf8},
|
|
]{data_cp1252.csv}{%...
|
|
}{% ....
|
|
}
|
|
% ....
|
|
\end{document}
|
|
\end{dispListing}
|
|
|
|
\pagebreak\item
|
|
If the \csvsorter\ program is properly installed,
|
|
see Subsection~\ref{sec:Sorting} on page~\pageref{sec:Sorting},
|
|
the CSV file can be re-encoded on-the-fly
|
|
with the following configuration file for \csvsorter:
|
|
|
|
\xmllisting{encoding}
|
|
|
|
\begin{dispListing}
|
|
% !TeX encoding=UTF-8
|
|
% ....
|
|
\usepackage[utf8]{inputenc}
|
|
% ....
|
|
\begin{document}
|
|
% ....
|
|
\csvreader[%...
|
|
sort by=encoding.xml,
|
|
]{data_cp1252.csv}{%...
|
|
}{% ....
|
|
}
|
|
% ....
|
|
\end{document}
|
|
\end{dispListing}
|
|
|
|
|
|
\end{itemize}
|
|
|
|
|
|
\clearpage
|
|
|
|
\printindex
|
|
|
|
\end{document}
|