summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/csvsimple/csvsimple.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/csvsimple/csvsimple.tex')
-rw-r--r--macros/latex/contrib/csvsimple/csvsimple.tex2132
1 files changed, 97 insertions, 2035 deletions
diff --git a/macros/latex/contrib/csvsimple/csvsimple.tex b/macros/latex/contrib/csvsimple/csvsimple.tex
index 924a819584..305f949631 100644
--- a/macros/latex/contrib/csvsimple/csvsimple.tex
+++ b/macros/latex/contrib/csvsimple/csvsimple.tex
@@ -1,6 +1,6 @@
% \LaTeX-Main\
% !TeX encoding=UTF-8
-%% The LaTeX package csvsimple - version 1.22 (2021/06/07)
+%% The LaTeX package csvsimple - version 2.0.0 (2021/06/29)
%% csvsimple.tex: Manual
%%
%% -------------------------------------------------------------------------------------------
@@ -17,105 +17,12 @@
%%
%% This work has the LPPL maintenance status `author-maintained'.
%%
-%% This work consists of all files listed in README
+%% This work consists of all files listed in README.md
%%
\documentclass[a4paper,11pt]{ltxdoc}
+\usepackage{csvsimple-doc}
-\usepackage[T1]{fontenc}
-\usepackage[utf8]{inputenc}
-\usepackage[english]{babel}
-\usepackage{lmodern,parskip,array,ifthen,calc,makeidx}
-\usepackage{amsmath,amssymb}
-\usepackage[svgnames,table,hyperref]{xcolor}
-\usepackage{tikz,siunitx}
-\usepackage{varioref}
-\usepackage[pdftex,bookmarks,raiselinks,pageanchor,hyperindex,colorlinks]{hyperref}
-\urlstyle{sf}
-\usepackage{cleveref}
-
-\usepackage[a4paper,left=2.5cm,right=2.5cm,top=1.5cm,bottom=1.5cm,
- marginparsep=3mm,marginparwidth=18mm,
- headheight=0mm,headsep=0cm,
- footskip=1.5cm,includeheadfoot]{geometry}
-\usepackage{fancyhdr}
-\fancyhf{}
-\fancyfoot[C]{\thepage}%
-\renewcommand{\headrulewidth}{0pt}
-\renewcommand{\footrulewidth}{0pt}
-\pagestyle{fancy}
-\tolerance=2000%
-\setlength{\emergencystretch}{20pt}%
-
-\RequirePackage{csquotes}
-\RequirePackage[style=numeric-comp,sorting=nyt,
- maxnames=8,minnames=8,abbreviate=false,backend=biber]{biblatex}
-\DeclareFieldFormat{url}{\newline\url{#1}}%
-\DeclareListFormat{language}{}%
-\setlength{\bibitemsep}{\smallskipamount}
-\addbibresource{\jobname.bib}
-
-\usepackage{longtable,booktabs}
-\usepackage{csvsimple}
-
-\usepackage{tcolorbox}
-\tcbuselibrary{skins,xparse,minted,breakable,documentation,raster}
-
-\definecolor{Green_Dark}{rgb}{0.078431,0.407843,0.176471}
-\definecolor{Blue_Dark}{rgb}{0.090196,0.211765,0.364706}
-\definecolor{Blue_Bright}{rgb}{0.858824,0.898039,0.945098}
-
-\tcbset{skin=enhanced,
- minted options={fontsize=\footnotesize},
- doc head={colback=yellow!10!white,interior style=fill},
- doc head key={colback=magenta!5!white,interior style=fill},
- color key=DarkViolet,
- color value=Teal,
- color color=Teal,
- color counter=Orange!85!black,
- color length=Orange!85!black,
- index colorize,
- index annotate,
- beforeafter example/.style={
- before skip=4pt plus 2pt minus 1pt,
- after skip=8pt plus 4pt minus 2pt
- },
- docexample/.style={bicolor,
- beforeafter example,
- arc is angular,fonttitle=\bfseries,
- %fontupper=\tiny\itshape,
- fontlower=\footnotesize,
- %colframe=Blue_Dark,
- %colback=Blue_Bright!75,
- colframe=green!25!yellow!50!black,
- colback=green!25!yellow!7,
- colbacklower=white,
-% drop fuzzy shadow,
- drop fuzzy shadow=green!25!yellow!50!black,
- listing engine=minted,
- documentation minted style=colorful,
- documentation minted options={fontsize=\footnotesize},
- },
-}
-
-\renewcommand*{\tcbdocnew}[1]{\textcolor{green!50!black}{\sffamily\bfseries N} #1}
-\renewcommand*{\tcbdocupdated}[1]{\textcolor{blue!75!black}{\sffamily\bfseries U} #1}
-
-\tcbmakedocSubKey{docCsvKey}{csv}
-
-\NewDocumentCommand{\csvsorter}{}{\textsf{\bfseries\color{red!20!black}CSV-Sorter}}
-
-%\newtcbinputlisting{\csvlisting}[1]{docexample,listing style=tcbdocumentation,fonttitle=\bfseries,
-% listing only,title={CSV file \flqq\texttt{\detokenize{#1.csv}}\frqq},listing file=#1.csv}
-\newtcbinputlisting{\csvlisting}[1]{docexample,minted options={fontsize=\footnotesize},minted language=latex,
- fonttitle=\bfseries,listing only,title={CSV file \flqq\texttt{\detokenize{#1.csv}}\frqq},listing file=#1.csv}
-
-%\newtcbinputlisting{\xmllisting}[1]{docexample,listing options={style=tcbdocumentation,language=XML},
-% fonttitle=\bfseries,listing only,title={Configuration file \flqq\texttt{\detokenize{#1.xml}}\frqq},listing file=#1.xml}
-\newtcbinputlisting{\xmllisting}[1]{docexample,minted options={fontsize=\footnotesize},minted language=xml,
- fonttitle=\bfseries,listing only,title={Configuration file \flqq\texttt{\detokenize{#1.xml}}\frqq},listing file=#1.xml}
-
-\NewTotalTCBox{\verbbox}{m}{enhanced,on line,size=fbox,frame empty,colback=red!5!white,
- colupper=red!85!black,fontupper=\bfseries\ttfamily}{\detokenize{"}#1\detokenize{"}}
+\usepackage{\csvpkgprefix csvsimple-legacy}
\hypersetup{
pdftitle={Manual for the csvsimple package},
@@ -124,11 +31,6 @@
pdfkeywords={csv file, comma separated values, key value syntax}
}
-\def\version{1.22}%
-\def\datum{2021/06/07}%
-\makeindex
-
-
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{document}
\begin{center}
@@ -151,1963 +53,123 @@
\begin{absquote}
\begin{center}\bfseries Abstract\end{center}
|csvsimple| provides a simple \LaTeX\ interface for the processing of files with
- comma separated values (CSV). |csvsimple| relies heavily on the key value
- syntax from |pgfkeys| which results (hopefully) in an easy way of usage.
+ comma separated values (CSV). |csvsimple| relies heavily on a key value
+ syntax 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}
-\clearpage
-\tableofcontents
-
-\clearpage
-\section{Introduction}%
-The |csvsimple| 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| \cite{tantau:tikz}. Sample applications of the package
-are tabular lists, serial letters, and charts.
-
-An alternative to |csvsimple| is the |datatool| package \cite{talbot:datatool}
-which provides considerably more functions and allows sorting of data by \LaTeX.
-|csvsimple| has a different approach for the user interface and
-is deliberately restricted to some basic functions with fast
-processing speed.
+\section{Package Options}%
-Mind the following restrictions:
+|csvsimple| is a stub which merely selects to load exclusively one of the
+following packages:
\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| loads the packages
-|pgfkeys| \cite{tantau:tikz},
-|etoolbox| \cite{lehmannwright:etoolbox},
-and |ifthen| \cite{carlisle:2014c}.
-|csvsimple| itself is loaded in the usual manner in the preamble:
+\item \href{csvsimple-l3.pdf}{\flqq The |csvsimple-l3| package\frqq}:\\
+ This is the pure \LaTeX3 version of |csvsimple|. It is considered
+ to be the \emph{current} version.
+ New documents are encouraged to use this package.\par
+ |csvsimple-l3| is loaded with \emph{one} of the following
+ alternatives inside the preamble:
\begin{dispListing}
-\usepackage{csvsimple}
+\usepackage[l3]{csvsimple}
+ % or alternatively (not simultaneously!)
+\usepackage{csvsimple-l3}
\end{dispListing}
-
-Not automatically loaded, but used for many examples are the packages
-|longtable| \cite{carlisle:2014d}
-and
-|booktabs| \cite{fear:2016a}.
-
-
-\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}}
- |\csvautotabular| 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{Stilname}\marg{options}}
- Abbreviation for |\csvset{|\meta{style name}|/.style=|\marg{options}|}|
- to define a new style.
-\end{docCommand}
-
-\begin{docCommand}{csvnames}{\marg{Stilname}\marg{Zuweisungsliste}}
- Abbreviation for |\csvset{|\meta{style name}|/.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 \cite{lehmannwright:etoolbox} 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 \cite{lehmannwright:etoolbox} 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| \cite{carlisle:2014c} 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| \cite{carlisle:2014c} 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| \cite{carlisle:2014c} 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}.
+\item \href{csvsimple-l3.pdf}{\flqq The |csvsimple-legacy| package\frqq}:\\
+ This is the \LaTeXe{} version of |csvsimple|. It is considered
+ to be the \emph{superseded} version identical to version 1.22 of |csvsimple|.
+ Documents based on that former version do \emph{not have to be changed}
+ and stay compilable in future.\par
+ |csvsimple-legacy| is loaded with \emph{one} of the following
+ alternatives inside the preamble:
\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
-}
+\usepackage{csvsimple}
+ % or alternatively (not simultaneously!)
+\usepackage[legacy]{csvsimple}
+ % or alternatively (not simultaneously!)
+\usepackage{csvsimple-legacy}
\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| 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|.
-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\ \cite{sturm: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\ \cite{sturm: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}
+\section{Differences between \texttt{csvsimple-l3} and \texttt{csvsimple-legacy}}
+This section is intended for users who know |csvsimple| before version~2.00.
-\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}
+|csvsimple-l3| is a \emph{nearly} drop-in replacement for
+|csvsimple-legacy|. Although old documents have no \emph{need} to be changed,
+adopting the new \LaTeX3 version for existing documents should impose not
+too much effort. Actually, it depends on how intense |pgfkeys| specific
+styles were used.
-Now, we can use the new rule:
-\begin{dispExample}
-\csvautotabular[sort by name]{grade.csv}
-\end{dispExample}
+That brings us to the differences between the two packages and a more precise
+understanding what \emph{nearly} drop-in replacement means. The following enumeration
+does not list new features of \texttt{csvsimple-l3} (if any), but takes an
+upgrade point of view.
-\end{docCsvKey}
-
-
-\clearpage
-\section{String Tests}\label{sec:stringtests}%
-
-The following string tests are complementing the string tests
-from the |etoolbox| \cite{lehmannwright: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}|.
+\item Any patches or additions using undocumented internals of |csvsimple-legacy|
+ will stop to function, because |csvsimple-l3| has a completely implementation.
+\item |csvsimple-l3| is programmed in |expl3| code using the \LaTeX3 interfaces.
+ No additional packages are loaded or needed with exception of several options
+ which allow to access methods from |ifthen|, |etoolbox|, |longtable|, etc.
+ On the other hand, |csvsimple-legacy| is programmed in \LaTeXe{} with
+ dirty tricks from here and there.
+\item The most significant change of the user interface is that the key value
+ engine of |csvsimple-legacy| is |pgfkeys| (root \docAuxKey*[csv]{}) while |csvsimple-l3| uses
+ |l3keys| (root \docAuxKey*[csvsim]{}).
+ Names und usage of the keys are \emph{unchanged}.
+ But, if
+ you made own |pgfkeys| \emph{styles} using the |pgfkeys| style handler,
+ these \emph{styles} have to be adapted to |.meta| keys of |l3keys|.
+ The good news is that styles
+ made with \docAuxCommand*{csvstyle} become |.meta| keys automatically.
+\item The macro \docAuxCommand*{csvheadset} is removed. It is not supportable
+ by the new implementation. I never used it and I forgot why I ever wrote it
+ -- I hope the same is true for you. If not, |csvsimple-legacy| can be
+ used for documents which needs it.
+\item Option \docAuxKey*[csv]{filter} is removed. Instead, \docAuxKey*[csvsim]{filter ifthen}
+ can be used (also true with \docAuxKey*[csv]{filter ifthen} for the old version).
+\item The deprecated options
+ \docAuxKey*[csv]{nofilter} and \docAuxKey*[csv]{nohead} are removed.
+ They were not documented any more since years. Obviously, use
+ \docAuxKey*[csvsim]{no filter} and \docAuxKey*[csvsim]{no head} instead.
+\item Compilation problems are to be expected, if an |S| column of the |siunitx| package
+ is used as first or last column. Documents neglecting this rule successfully
+ for |csvsimple-legacy|, may fail to compile with |csvsimple-l3.|
+\item The \LaTeX{} counters \docCounter*{csvinputline}
+ and \docCounter*{csvrow}
+ are replaced by \LaTeX3 integers
+ \docCounter*{g_csvsim_inputline_int}
+ and \docCounter*{g_csvsim_row_int}, but accessors
+ \docAuxCommand*{thecsvinputline} and
+ \docAuxCommand*{thecsvrow} are still valid.
+\item The packages |pgfrcs|, |pgfkeys|, |ifthen|, |etoolbox|, and |shellesc|
+ are not included anymore (include manually, if needed).
+\item
+ \docAuxCommand*{csviffirstrow} and
+ \docAuxCommand*{csvifoddrow} are deprecated and replaced by
+ \docAuxCommand*{ifcsvfirstrow}
+ \docAuxCommand*{ifcsvoddrow}
+ which are more consistent in nomenclature.
+\item For |csvsimple-l3|, data lines are allowed to begin with an backslash.
+\item Assigned macros like |\myname| for e.g. the third column contain
+ not |\csvcoliii| anymore, but are equal to the content of |\csvcoliii| now.
+\item Character code changes with \docAuxKey*[csvsim]{respect percent} etc.
+ and the tabulator as separator should work for |csvsimple-l3| as expected in every
+ situation (not always worked for |csvsimple-legacy|).
+\item A drawback of |csvsimple-l3| against |csvsimple-legacy| is
+ a higher compilation time. This may vary by used compiler.
+ An example document of 5061 pages using a CSV file with 166 992 lines
+ took about 28 seconds with |csvsimple-legacy| and
+ about 51 seconds with |csvsimple-l3| on my machine
+ (just a singular observation, no scientific analysis at all).
\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| \cite{wright:siuntix} 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 \cite{wright:siuntix} 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]},
- 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} column is to be formatted with
-the column type |S|. The number detection of |siunitx| is disturbed by
-the line reading code of |csvsimple| which actually is present at the
-first column. To avoid this problem, the content of the first column
-could be formatted not by the table format definition, but by using a
-suitable |\tablenum| formatting directly, see |siunitx| \cite{wright:siuntix}.
-
-Another and very nifty workaround suggested by Enrico Gregorio is to
-add an invisible dummy column with |c@{}| as first 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},
- 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]},
- 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| 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|:
-\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
-
-% Actually, it is not a good idea to include the references like this!
-% Do not follow this bad example ...
-\begin{tcbverbatimwrite}{\jobname.bib}
-@manual{tantau:tikz,
- author = {Till Tantau},
- title = {The TikZ and PGF Packages},
- subtitle = {Manual for version 3.1.2},
- url = {http://mirrors.ctan.org/graphics/pgf/base/doc/pgfmanual.pdf},
- date = {2019-04-04},
-}
-
-@manual{carlisle:2014c,
- author = {David Carlisle},
- title = {The ifthen package},
- url = {http://mirror.ctan.org/macros/latex/base/ifthen.pdf},
- date = {2014-09-29},
- language = {english}
-}
-
-
-@manual{talbot:datatool,
- author = {Nicola L. C. Talbot},
- title = {User Manual for the datatool bundle version 2.31},
- url = {http://mirrors.ctan.org/macros/latex/contrib/datatool/datatool-user.pdf},
- date = {2018-12-07},
- language = {english}
-}
-
-@manual{sturm:csvsorter,
- author = {Thomas F. Sturm},
- title = {The CSV-Sorter program},
- subtitle = {Manual for version 0.95 beta},
- url = {http://T-F-S.github.io/csvsorter/csvsorter.pdf},
- date = {2018-01-11},
- language = {english}
-}
-
-@manual{carlisle:2014d,
- author = {David Carlisle},
- title = {The longtable package},
- url = {http://mirror.ctan.org/macros/latex/required/tools/longtable.pdf},
- date = {2014-10-28},
- language = {english}
-}
-
-
-@manual{fear:2016a,
- author = {Simon Fear},
- title = {Publication quality tables in \LaTeX},
- url = {http://mirror.ctan.org/macros/latex/contrib/booktabs/booktabs.pdf},
- date = {2016-04-29},
- language = {english}
-}
-
-@manual{wright:siuntix,
- author = {Joseph Wright},
- title = {siunitx --- A comprehensive (SI) units package},
- url = {http://mirror.ctan.org/macros/latex/contrib/siunitx/siunitx.pdf},
- date = {2018-05-17},
- language = {english}
-}
-
-@manual{lehmannwright:etoolbox,
- author = {Philipp Lehman and Joseph Wright},
- title = {The etoolbox Package},
- url = {http://mirror.ctan.org/macros/latex/contrib/etoolbox/etoolbox.pdf},
- date = {2018-08-19},
-}
-
-\end{tcbverbatimwrite}
-\printbibliography[heading=bibintoc]
-\printindex
\end{document}