diff options
Diffstat (limited to 'macros/latex/contrib/csvsimple/csvsimple-l3.tex')
-rw-r--r-- | macros/latex/contrib/csvsimple/csvsimple-l3.tex | 286 |
1 files changed, 265 insertions, 21 deletions
diff --git a/macros/latex/contrib/csvsimple/csvsimple-l3.tex b/macros/latex/contrib/csvsimple/csvsimple-l3.tex index a3e61e241f..fc8d82b903 100644 --- a/macros/latex/contrib/csvsimple/csvsimple-l3.tex +++ b/macros/latex/contrib/csvsimple/csvsimple-l3.tex @@ -1,6 +1,6 @@ % \LaTeX-Main\ % !TeX encoding=UTF-8 -%% The LaTeX package csvsimple - version 2.0.0 (2021/06/29) +%% The LaTeX package csvsimple - version 2.1.0 (2021/07/06) %% csvsimple.tex: Manual %% %% ------------------------------------------------------------------------------------------- @@ -19,6 +19,7 @@ %% %% This work consists of all files listed in README.md %% +% \RequirePackage[check-declarations,enable-debug]{expl3} \documentclass[a4paper,11pt]{ltxdoc} \usepackage{csvsimple-doc} @@ -102,7 +103,7 @@ This processing is controlled by key value assignments according to the syntax of |l3keys|. Sample applications of the package are tabular lists, serial letters, and charts. -An alternative to |csvsimple-l3| is the |datatool| package +An alternative to |csvsimple-l3| is the \ctanpkg{datatool} package which provides considerably more functions and allows sorting of data by \LaTeX. |csvsimple-l3| has a different approach for the user interface and is deliberately restricted to some basic functions with fast @@ -134,7 +135,7 @@ alternatives inside the preamble: \end{dispListing} Not automatically loaded, but used for many examples are the packages -|longtable|, |booktabs|, |ifthen|, and |booktabs|. +\ctanpkg{longtable}, \ctanpkg{booktabs}, \ctanpkg{ifthen}, and \ctanpkg{etoolbox}. \clearpage @@ -788,12 +789,21 @@ to be used inside these macros. \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 e.g. \refKey{/csvsim/filter ifthen}. - Also see \refKey{/csvsim/full filter}. + of a data line. It is executed before any filter condition is checked, + see e.g. \refKey{/csvsim/filter ifthen} and + also see \refKey{/csvsim/full filter}. + No additions to the input stream should be given here. All line entries are available. \end{docCsvKey} +\begin{docCsvKey}[][doc new=2021-07-06]{after filter}{=\meta{code}}{no default, initially empty} + Sets the \meta{code} to be executed for an accepted line after + \refKey{/csvsim/late after line} and before \refKey{/csvsim/before line}. + All line entries are available. + No additions to the input stream should be given here. \meta{code} may + contain processing of data content to generate new values. +\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. @@ -833,7 +843,7 @@ to be used inside these macros. \begin{docCsvKey}{before line}{=\meta{code}}{no default, initially empty} - Sets the \meta{code} to be executed after \refKey{/csvsim/late after line} + Sets the \meta{code} to be executed after \refKey{/csvsim/after filter} and before \refKey{/csvsim/command}. All line entries are available. \refKey{/csvsim/before line} overwrites @@ -848,6 +858,7 @@ to be used inside these macros. This key has to be set after \refKey{/csvsim/before line}. \end{docCsvKey} +\pagebreak \begin{docCsvKey}{command}{=\meta{code}}{no default, initially \cs{csvline}} Sets the \meta{code} to be executed for every accepted data line. @@ -857,8 +868,6 @@ to be used inside these macros. parameter. \end{docCsvKey} -\pagebreak - \begin{docCsvKey}{after line}{=\meta{code}}{no default, initially empty} Sets the \meta{code} to be executed for every accepted data line after \refKey{/csvsim/command}. @@ -889,6 +898,7 @@ parameter of \refCom{csvreader}. before reading = \meta{before reading}\\, after head = \meta{after head}, before filter = \\\meta{before filter}, + after filter = \meta{after filter}, late after head = \meta{late after head}, late after line = \meta{late after line}, late after first line = \meta{late after first line}, @@ -1041,20 +1051,20 @@ The following string compare filters \refKey{/csvsim/filter strcmp} and \begin{docCsvKey}{filter equal}{=\marg{stringA}\marg{stringB}}{style, no default} Only lines where \meta{stringA} and \meta{stringB} are equal after expansion are accepted. - The implementation is done with the |ifthen| package (loading required!). + The implementation is done with the \ctanpkg{ifthen} package (loading required!). \end{docCsvKey} \begin{docCsvKey}{filter not equal}{=\marg{stringA}\marg{stringB}}{style, no default} Only lines where \meta{stringA} and \meta{stringB} are not equal after expansion are accepted. - The implementation is done with the |ifthen| package (loading required!). + The implementation is done with the \ctanpkg{ifthen} package (loading required!). \end{docCsvKey} \begin{docCsvKey}[][doc new=2021-06-25]{filter fp}{=\meta{floating point expression}}{no default} Only data lines which fulfill a \LaTeX3 \meta{floating point expression} - (|l3fp|, |xfp|) are accepted. + (|l3fp|, \ctanpkg{xfp}) are accepted. \begin{dispExample} % \usepackage{booktabs} \csvreader[ @@ -1146,7 +1156,7 @@ The following string compare filters \refKey{/csvsim/filter strcmp} and \begin{dispListing} filter test=\iftest{some testing}, \end{dispListing} - For |\iftest|, tests from the |etoolbox| package like + For |\iftest|, tests from the \ctanpkg{etoolbox} package like |\ifnumcomp|, |\ifdimgreater|, etc. and from \Fullref{sec:stringtests} can be used. Also, arbitrary own macros fulfilling this signature can be applied. \begin{dispExample} @@ -1169,7 +1179,7 @@ filter test=\iftest{some testing}, \begin{docCsvKey}[][doc new=2016-07-01]{filter expr}{=\meta{boolean expression}}{no default} Only data lines which fulfill a \meta{boolean expression} are accepted. Every \meta{boolean expression} - from the |etoolbox| package is feasible (package loading required!). + from the \ctanpkg{etoolbox} package is feasible (package loading required!). To preprocess the data line before testing the \meta{condition}, the option key \refKey{/csvsim/before filter} can be used. \begin{dispExample} @@ -1193,7 +1203,7 @@ filter test=\iftest{some testing}, \clearpage \begin{docCsvKey}[][doc new=2016-07-01]{filter ifthen}{=\meta{boolean expression}}{no default} Only data lines which fulfill a \meta{boolean expression} are accepted. - For the \meta{boolean expression}, every term from the |ifthen| package + For the \meta{boolean expression}, every term from the \ctanpkg{ifthen} package is feasible (package loading required!). To preprocess the data line before testing the \meta{condition}, the option key \refKey{/csvsim/before filter} can be used. @@ -1372,7 +1382,7 @@ The following example displays the last three line numbers: \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 + Additionally, the commands defined by the key values of \refKey{/csvsim/before table}, \refKey{/csvsim/table head}, \refKey{/csvsim/table foot}, and \refKey{/csvsim/after table} are executed at the appropriate places. \end{docCsvKey} @@ -1385,7 +1395,7 @@ Additionally, the commands defined by the key values of \begin{docCsvKey}{longtable}{=\meta{table format}}{style, no default} Like \refKey{/csvsim/tabular} but for the |longtable| environment. - This requires the package |longtable| (not loaded automatically). + This requires the package \ctanpkg{longtable} (not loaded automatically). \end{docCsvKey} @@ -1399,6 +1409,21 @@ Additionally, the commands defined by the key values of \end{docCsvKey} +\begin{docCsvKey}[][doc new=2021-07-06]{tabularray}{=\meta{table format}}{style, no default} + Like \refKey{/csvsim/tabular} but for the |tblr| environment. + This requires the package \ctanpkg{tabularray} (not loaded automatically). + This also sets \refKey{/csvsim/collect data} since this kind of table + needs collected content, see \Fullref{sec:datacollection}. + Note that \refKey{/csvsim/after reading} is set to use the collected + data immediately. See \Fullref{sec:tabularray} for examples. +\end{docCsvKey} + + +\begin{docCsvKey}[][doc new=2021-07-06]{centered tabularray}{=\meta{table format}}{style, no default} + Like \refKey{/csvsim/tabularray} but inside an additional |center| environment. +\end{docCsvKey} + + \begin{docCsvKey}{no table}{}{style, no value} Deactivates |tabular|, |longtable|, and |tabbing|. \end{docCsvKey} @@ -1879,6 +1904,118 @@ Now, we can use the new rule: \clearpage +\subsection{Data Collection}\label{sec:datacollection} + +|csvsimple-l3| reads and processes a CSV file line by line. Accordingly, the \TeX{} +input stream is filled line by line. +Although this is an efficient procedure, for some applications like tables with +the \ctanpkg{tabularray} package, collecting the data from the CSV file into a macro is needed. +This macro can be given to the target application for further processing. + + +\begin{docCsvKey}[][doc new=2021-07-06]{collect data}{\colOpt{=true\textbar false}}{default |true|, initially |false|} +|csvsimple-l3| provides limited and experimental support to collect the input data +from the CSV file plus user additions into a macro named \refCom{csvdatacollection}. +Setting \refKey{/csvsim/collect data} adds the contents of the following keys +to \refCom{csvdatacollection}: +\begin{itemize} +\item\refKey{/csvsim/after head} +\item\refKey{/csvsim/after line} +\item\refKey{/csvsim/before first line} +\item\refKey{/csvsim/before line} +\item\refKey{/csvsim/late after first line} +\item\refKey{/csvsim/late after head} +\item\refKey{/csvsim/late after last line} +\item\refKey{/csvsim/late after line} +\end{itemize} +Also, the \emph{expanded} content of +\begin{itemize} +\item\refKey{/csvsim/command} +\end{itemize} +is added to \docAuxCommand{csvdatacollection}. +Note that for \refKey{/csvsim/command} special care has to be taken +\emph{what} should be protected from expansion and \emph{what not}. +Observe the following hints for \refKey{/csvsim/command}: +\begin{itemize} +\item For data macros like |\csvcoli| use |\csvexpval\csvcoli| to add + the \emph{value} of this macro to \refCom{csvdatacollection}. + This is optional, if |\csvcoli| contains numbers or text without active + characters, but essential, if it contains macros. +\item For macros like |\textbf| use |\csvexpnot\textbf| to \emph{prevent} + expansion. +\item Using computations or not expandable conditionals may likely cause + compilation errors. +\end{itemize} + +\begin{dispExample} +\csvreader[ + collect data, + head to column names, + late after line=\\, + late after last line=, + ]{grade.csv}{}{% + \thecsvrow. \csvexpval\givenname\ \csvexpnot\textbf{\csvexpval\name} + } +Collected data:\par +\csvdatacollection +\end{dispExample} + +Note that data collection is \emph{limited} to some special cases and does not +allow to save all possible content. Table options like \refKey{/csvsim/longtable} +are generally not supported with the important exception of \refKey{/csvsim/tabularray} +which uses \refKey{/csvsim/collect data} automatically.\par +See \Fullref{sec:tabularray} for examples. +\end{docCsvKey} + +\clearpage + +\begin{docCsvKey}[][doc new=2021-07-06]{data collection}{=\meta{macro}}{no default, initially \refCom{csvdatacollection}} +Sets the collection macro to an alternative for \refCom{csvdatacollection}. +\begin{dispListing} + data collection = \myData, % instead of \csvdatacollection +\end{dispListing} +\end{docCsvKey} + + +\begin{docCommand}[doc new=2021-07-26]{csvdatacollection}{} + Macro which contains the collected data of a CSV file processed with + \refKey{/csvsim/collect data}. This macro name can be changed by + settiing \refKey{/csvsim/data collection}. +\end{docCommand} + + +\begin{docCommand}[doc new=2021-07-26]{csvexpval}{\meta{macro}} + Recovers the content of the given \meta{macro} and prevents further + expansion. This is a wrapper for \docAuxCommand*{exp_not:V}. + Alternatively, |\expandonce| from \ctanpkg{etoolbox} could be used. +\end{docCommand} + + +\begin{docCommand}[doc new=2021-07-26]{csvexpnot}{\meta{macro}} + Prevents the expansion of the given \meta{macro}. This is a wrapper + for \docAuxCommand*{exp_not:N}. + Alternatively, |\noexpand| could be used. +\end{docCommand} + + +\begin{docCommand}[doc new=2021-07-26]{csvcollectn}{\marg{code}} + Appends the given \meta{code} to \refCom{csvdatacollection}.\\ + This corresponds to \docAuxCommand*{tl_gput_right:Nn}. +\end{docCommand} + + +\begin{docCommand}[doc new=2021-07-26]{csvcollectx}{\marg{code}} + Appends the expansion of the given \meta{code} to \refCom{csvdatacollection}.\\ + This corresponds to \docAuxCommand*{tl_gput_right:Nx}. +\end{docCommand} + +\begin{docCommand}[doc new=2021-07-26]{csvcollectV}{\meta{macro}} + Appends the content of the given \meta{macro} to \refCom{csvdatacollection}.\\ + This corresponds to \docAuxCommand*{tl_gput_right:NV}. +\end{docCommand} + + +\clearpage \section{String and Number Tests}\label{sec:stringtests}% The following string tests are complementing the string tests @@ -2003,7 +2140,7 @@ introduced. \clearpage -\subsection{A Graphical Presentation}% +\subsection{A Graphical Presentation}\label{sec:examgrapghpres}% For this example, we use some artificial statistical data given by a CSV file. %-- file embedded for simplicity -- @@ -2202,10 +2339,10 @@ December, 2.2, 3.3e3 \medskip -The |siunitx| package provides a huge amount of formatting options for -numbers. A good and robust way to apply formatting by |siunitx| inside +The \ctanpkg{siunitx} package provides a huge amount of formatting options for +numbers. A good and robust way to apply formatting by \ctanpkg{siunitx} inside tables generated by |csvsimple-l3| is the |\tablenum| macro from -|siunitx|. +\ctanpkg{siunitx}. \begin{dispExample} % \usepackage{siunitx,array,booktabs} @@ -2366,6 +2503,113 @@ because there is no head, but the columns can be addressed by their numbers: \end{dispExample} + +\clearpage +\subsection{Tables with \texttt{tabularray}}\label{sec:tabularray}% + +The \ctanpkg{tabularray} package gives extended control for generating +tables. \refKey{/csvsim/tabularray} and \refKey{/csvsim/centered tabularray} +support such tables. A distinctiveness is that for \ctanpkg{tabularray} +data from a CSV file has to be \emph{collected} first (into a macro) +and applied afterwards. The process is hidden from the user view, but +has to be taken into account when \refKey{/csvsim/command} is set up, +see \Fullref{sec:datacollection}. + +The following examples uses |data.csv| from \Fullref{sec:examgrapghpres}. + +\begin{dispExample} +% \usepackage{tabularray,siunitx,xfp} +\csvreader[ + head to column names, + centered tabularray = + { + rowsep = 1mm, + colsep = 5mm, + rows = {blue7}, + hlines = {2pt, white}, + vlines = {2pt, white}, + row{1} = {bg=azure3, fg=white, font=\bfseries\large, 8mm}, + }, + table head = {\SetCell[c=4]{c} Important Data Table \\}, + ]{data.csv}{}{ + \ifcsvstrcmp{\group}{A}{\csvexpnot\SetRow{brown7}}{} + \csvexpnot\SetCell{bg=purple7} + \csvexpval\land + & \csvexpval\group + & \csvexpval\amount + & \csvexpnot\tablenum[exponent-mode=scientific, round-precision=3, + round-mode=places, table-format=1.3e1]{\fpeval{pi*\amount}} + } +\end{dispExample} + +Note in the example above that +\begin{itemize} +\item \refKey{/csvsim/table head} is \emph{collected} unexpanded, i.e. + |\SetCell| has not to be protected. On the other hand, CSV data could not + be used here. +\item \refKey{/csvsim/command} is \emph{collected} expanded. This is identical + to the mandatory last argument of \refCom{csvreader}. + \begin{itemize} + \item Therefore, expansion of |\SetRow|, |\SetCell|, etc. is prevented by \refCom{csvexpnot}. + \item The \emph{values} (content) of |\land|, |\group|, etc. are recovered by + \refCom{csvexpval}. + \item |\ifcsvstrcmp| and |\fpeval| are \emph{expandable} and therefore the + results of these commands are \emph{collected}. + \end{itemize} +\end{itemize} + +\clearpage + +Filters and line ranges can be used for \ctanpkg{tabularray} and all +data collections without restriction: + +\begin{dispExample} +% \usepackage{tabularray} +Display group `A` only:\par +\csvreader[ + head to column names, + filter strcmp = {\group}{A}, + centered tabularray = + { + rowsep = 1mm, + colsep = 5mm, + column{1} = {r, fg=yellow5, colsep=2pt}, + column{2} = {r, yellow8!10, font=\bfseries}, + column{3} = {l, yellow8}, + hlines = {2pt, white}, + }, + ]{data.csv}{}{ + \thecsvrow + & \csvexpval\land + & \csvexpval\amount + } +\end{dispExample} + + +\begin{dispExample} +% \usepackage{tabularray} +Display data from line 3 on:\par +\csvreader[ + head to column names, + range = 3-, + centered tabularray = + { + rowsep = 1mm, + colsep = 5mm, + column{1} = {r, fg=violet5, colsep=2pt}, + column{2} = {r, violet8!10, font=\bfseries}, + column{3} = {l, violet8}, + hlines = {2pt, white}, + }, + ]{data.csv}{}{ + \thecsvrow + & \csvexpval\land + & \csvexpval\amount + } +\end{dispExample} + + + \clearpage \subsection{Imported CSV data}\label{sec:importeddata}% If data is imported from other applications, there is not always a choice |