summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/datatool/datatool-user.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/datatool/datatool-user.tex')
-rw-r--r--Master/texmf-dist/doc/latex/datatool/datatool-user.tex87
1 files changed, 78 insertions, 9 deletions
diff --git a/Master/texmf-dist/doc/latex/datatool/datatool-user.tex b/Master/texmf-dist/doc/latex/datatool/datatool-user.tex
index aeefbfea21a..08f01e258ff 100644
--- a/Master/texmf-dist/doc/latex/datatool/datatool-user.tex
+++ b/Master/texmf-dist/doc/latex/datatool/datatool-user.tex
@@ -103,11 +103,11 @@
\MakeShortVerb{"}
- \title{User Manual for datatool bundle version~2.30}
+ \title{User Manual for datatool bundle version~2.31}
\author{Nicola L.C. Talbot\\
\url{http://www.dickimaw-books.com/}}
- \date{2018-04-16}
+ \date{2018-12-07}
\maketitle
\pagenumbering{roman}
@@ -122,7 +122,7 @@ The \styfmt{datatool} bundle comes with the following documentation:
\item[\url{datatool-code.pdf}]
Advanced users wishing to know more about the inner workings of
all the packages provided in the \styfmt{datatool} bundle should
- read \qt{Documented Code for datatool v2.30}
+ read \qt{Documented Code for datatool v2.31}
\item[INSTALL] Installation instructions.
@@ -148,7 +148,7 @@ your calculations or data manipulation and save the results in a
file that can be input into your document.} For large amounts of
data that need to be sorted or filtered or joined, consider storing your data
in an~SQL database and use
-\app{datatooltk}\footnote{\url{http://www.dickimaw-books.com/apps/datatooltk/}} to import the data,
+\app{datatooltk}\footnote{\url{http://www.dickimaw-books.com/software/datatooltk/}} to import the data,
using SQL syntax to filter, sort and otherwise
manipulate the values.
\end{important}
@@ -2069,7 +2069,7 @@ by \styfmt{datatool-base}).
In addition to those commands, \styfmt{datatool-base}
provides some commands that deal with comma-separated lists.
Note that this just refers to a control sequence that stores
-a list of elements separated by commands, for example:
+a list of elements separated by commas, for example:
\begin{verbatim}
\newcommand{\mylist}{elephant,ant,zebra,duck}
\end{verbatim}
@@ -2083,16 +2083,40 @@ Formats the comma-separated list. The unstarred version scopes
the internal operation. The starred form doesn't.
The \meta{list} may either be an explicit comma-separated list or
a control sequence whose replacement
-text is a comma-separated list. For example:
+text is a comma-separated list. If the list contains empty
+elements then \cs{DTLformatlist} will either include or
+skip the empty element according to the conditional:
+\begin{definition}[\DescribeMacro{\ifDTLlistskipempty}]
+\cs{ifDTLlistskipempty}
+\end{definition}
+For example:
\begin{verbatim}
-\newcommand{\mylist}{elephant,ant,zebra,duck}%
+\newcommand{\mylist}{elephant,,ant,zebra,duck}%
+\DTLlistskipemptytrue
+\DTLformatlist{\mylist}\par
+\DTLlistskipemptyfalse
\DTLformatlist{\mylist}
\end{verbatim}
which produces:
\begin{display}
-\newcommand{\mylist}{elephant,ant,zebra,duck}%
+\newcommand{\mylist}{elephant,,ant,zebra,duck}%
+\DTLlistskipemptytrue
+\DTLformatlist{\mylist}\par
+\DTLlistskipemptyfalse
\DTLformatlist{\mylist}
\end{display}
+The default setting is
+\begin{verbatim}
+\DTLlistskipemptytrue
+\end{verbatim}
+Note that this may cause a difference when upgrading to v2.31
+as in previous versions \cs{DTLformatlist} didn't skip empty
+elements. To restore the original behaviour use:
+\begin{verbatim}
+\DTLlistskipemptyfalse
+\end{verbatim}
+before \cs{DTLformatlist}.
+
The list formatting command inserts
\begin{definition}[\DescribeMacro\DTLlistformatsep]
\cs{DTLlistformatsep}
@@ -2166,8 +2190,53 @@ expansion on \meta{element}.)
\begin{definition}[\DescribeMacro{\DTLnumitemsinlist}]
\cs{DTLnumitemsinlist}\marg{list}\marg{cmd}
\end{definition}
-Counts the number of non-empty elements in \meta{list} and stores
+Counts the number of elements in \meta{list} and stores the
result in \meta{cmd}, which must be a control sequence.
+As from v2.31, this obeys the conditional \cs{ifDTLlistskipempty}
+to determine if empty elements should be skipped. For example:
+\begin{verbatim}
+\newcommand{\mylist}{foo,,bar,baz,wibble}
+Number of non-empty elements:
+\DTLnumitemsinlist{\mylist}{\listnum}\listnum.\par
+\DTLlistskipemptyfalse
+Number of elements (including empty):
+\DTLnumitemsinlist{\mylist}{\listnum}\listnum.
+\end{verbatim}
+This produces:
+\begin{display}
+\newcommand{\mylist}{foo,,bar,baz,wibble}
+Number of non-empty elements: \DTLnumitemsinlist{\mylist}{\listnum}\listnum.\par
+\DTLlistskipemptyfalse
+Number of elements (including empty): \DTLnumitemsinlist{\mylist}{\listnum}\listnum.
+\end{display}
+
+\begin{definition}[\DescribeMacro{\DTLlistelement}]
+\cs{DTLlistelement}\marg{list}\marg{index}
+\end{definition}
+Does the \meta{index}th element of the list (starting at 1 for
+the first element) or generates a warning if the index is out
+of range. This obeys the conditional \cs{ifDTLlistskipempty}
+to determine if empty elements should be skipped.
+For example:
+\begin{verbatim}
+\newcommand{\mylist}{foo,,bar,baz,wibble}
+3rd item in list (skip empty): \DTLlistelement{\mylist}{3}.\par
+\ifDTLlistskipempty
+3rd item in list (include empty): \DTLlistelement{\mylist}{3}.
+\end{verbatim}
+This produces:
+\begin{display}
+\newcommand{\mylist}{foo,,bar,baz,wibble}
+3rd item in list (skip empty): \DTLlistelement{\mylist}{3}.\par
+\ifDTLlistskipempty
+3rd item in list (include empty): \DTLlistelement{\mylist}{3}.
+\end{display}
+
+\begin{definition}[\DescribeMacro{\DTLfetchlistelement}]
+\cs{DTLfetchlistelement}\marg{list}\marg{index}\marg{cs}
+\end{definition}
+Like \cs{DTLlistelement} but it stores the \meta{index}th
+element in the command given by \meta{cs}.
\begin{definition}[\DescribeMacro\dtlsortlist]
\cs{dtlsortlist}\marg{list cs}\marg{criteria cs}