diff options
Diffstat (limited to 'macros/latex/contrib/csvsimple/csvsimple.tex')
-rw-r--r-- | macros/latex/contrib/csvsimple/csvsimple.tex | 2132 |
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} |