CTAN sync 202109190301

3 files changed, 105 insertions, 55 deletions

diff --git a/macros/latex/contrib/readarray/readarray.pdf b/macros/latex/contrib/readarray/readarray.pdf
index 5b8f2b4dbd..7bbc00acaa 100644
--- a/macros/latex/contrib/readarray/readarray.pdf
+++ b/macros/latex/contrib/readarray/readarray.pdf
diff --git a/macros/latex/contrib/readarray/readarray.sty b/macros/latex/contrib/readarray/readarray.sty
index fb6c2ba90d..912d43c48b 100644
--- a/macros/latex/contrib/readarray/readarray.sty
+++ b/macros/latex/contrib/readarray/readarray.sty
@@ -1,5 +1,5 @@
-\def\readarrayPackageVersion{3.0}
-\def\readarrayPackageDate{2021/08/08}
+\def\readarrayPackageVersion{3.1}
+\def\readarrayPackageDate{2021/09/17}
 \ProvidesPackage{readarray}
 [\readarrayPackageDate\ \readarrayPackageVersion\ %
 Routines for inputting 2D and 3D array data and recalling it on an 
@@ -17,25 +17,6 @@ element-by-element basis.]
 %
 % The Current Maintainer of this work is Steven B. Segletes.
 %
-% Revisions:
-% v1.01 -Documentation revision
-% v1.1  -Added \csname record\roman{@row}\endcsname to \readdef
-% v1.2  -Corrected the [truncated] LPPL license info
-%       -Added \arrayij and \arrayijk, which can be put into \edef
-%       -Used \romannumeral in preference to \roman{}, when possible,
-%        to avoid unnecessary use of counters.
-% v1.3  -Moved \newread outside of \readdef, so as not to exhaust the
-%        16 allotted file streams (Thanks to Ken Kubota for the tip).
-% v2.0  -Converted parsing to listofitems package.  This allows for
-%        ANY parsing character or combination of characters (via logical OR).
-%       -Replaced all \protected@edef's with appropriately expanded \def's.
-%       -Use listofitems package in preference to \getargsC.
-%       -Deprecated \Arrayijk, \arrayijk, \Arrayij, & \arrayij.  Direct
-%        access now preferred, e.g., \xyz[2,3,1].
-%       -Deprecated most other commands in favor of a more natural syntax.
-% v3.0  (2021-08-05)
-%       -Added features: \setvalue, \initarray, \mergearray, \typesetarray
-%       -Allowed for \readarrayendlinechar to be set other than 9
 \RequirePackage{forloop}
 \RequirePackage{listofitems}[2016-10-22]
 %
@@ -50,6 +31,8 @@ element-by-element basis.]
 \newtoks\@arrayident@toks
 \newread\rdar@file
 \newcount\readarrayendlinechar
+\newif\ifignoreblankreadarrayrecords
+\ignoreblankreadarrayrecordsfalse
 \edef\readarraybackslash{\expandafter\@firstoftwo\string\\}
 %
 \newcommand\readdef[2]{\@readdef{#1}{#2}{ArrayRecord}}
@@ -123,39 +106,51 @@ element-by-element basis.]
 \def\@readdef#1#2#3{%
   \clear@array{#3}%
   \edef\former@recordcount{\csname #3CELLS\endcsname}%
+  \def\nrows{0}%
   \def\first@row{T}%
-  \def\first@plane{T}%
+  \def\first@plane{F}%
   \catcode\endlinechar=\readarrayendlinechar\relax %
   \def#2{}%
   \setcounter{@record}{0}%
   \openin\rdar@file=#1%
+  \ifignoreblankreadarrayrecords
+    \def\rdar@iftest{\rdar@record\empty}\else\def\rdar@iftest{01}\fi
   \loop\unless\ifeof\rdar@file%
-    \read\rdar@file to\rdar@fileline % Reads file line into \rdar@fileline%
-    \addtocounter{@record}{1}%
-    \expandafter\g@addto@macro\expandafter#2\expandafter{\rdar@fileline}%
-    \ifx\rdar@fileline\empty\else\expandafter\g@addto@macro%
-      \expandafter#2\expandafter{\read@array@sepchar}\fi%
-    \if T\first@row\read@array{#2}\setcounter{@col}{\numexpr(\Arg@listlen-1)}%
-      \edef\ncols{\arabic{@col}}\def\first@row{F}\setcounter{@row}{1}%
-    \else%
-      \if T\first@plane%
-        \ifx\rdar@fileline\empty
-          \edef\nrows{\arabic{@row}}\def\first@plane{F}%
+    \read\rdar@file to\rdar@record % Reads record into \rdar@record%
+    \expandafter\ifx\rdar@iftest\else
+      \stepcounter{@record}%
+      \expandafter\g@addto@macro\expandafter#2\expandafter{\rdar@record}%
+      \ifx\rdar@record\empty\else\expandafter
+        \g@addto@macro\expandafter#2\expandafter{\read@array@sepchar}%
+        \if T\first@row
+          \read@array{#2}%
+          \setcounter{@col}{\numexpr(\Arg@listlen-1)}%
+          \edef\ncols{\arabic{@col}}%
+          \def\first@row{F}%
+          \setcounter{@row}{0}%
+          \def\first@plane{T}%
+        \fi
+      \fi
+      \if T\first@plane
+        \ifx\rdar@record\empty
+          \edef\nrows{\arabic{@row}}%
+          \def\first@plane{F}%
         \else
-          \addtocounter{@row}{1}%
+          \stepcounter{@row}%
         \fi
-      \fi%
-    \fi%
-    \def\record@name{\csname #3[\the@record]\endcsname}%
-    \expandafter\expandafter\expandafter\expandafter\expandafter\expandafter%
-      \expandafter\def\expandafter\record@name\expandafter{\rdar@fileline}%
-  \repeat%
+      \fi
+      \def\record@name{\csname #3[\the@record]\endcsname}%
+      \expandafter\expandafter\expandafter\expandafter\expandafter\expandafter
+        \expandafter\def\expandafter\record@name\expandafter{\rdar@record}%
+    \fi
+  \repeat
+  \ifnum\nrows=0 \edef\nrows{\arabic{@row}}\fi
   \edef\nrecords{\arabic{@record}}%
   \expandafter\edef\csname #3PLANES\endcsname{0}%
   \expandafter\edef\csname #3ROWS\endcsname{\nrecords}%
   \expandafter\edef\csname #3COLS\endcsname{0}%
   \expandafter\edef\csname #3CELLS\endcsname{\nrecords}%
-  \closein\rdar@file%
+  \closein\rdar@file
   \catcode\endlinechar=5 %
   \define@rootmacro{#3}%
 }
@@ -252,7 +247,7 @@ element-by-element basis.]
 }
 %
 \def\clear@array#1{%
-  \ifcsname #1\endcsname%
+  \ifcsname #1ROWS\endcsname%
     \forloop{@row}{1}{\value{@row}<\numexpr\csname #1ROWS\endcsname+1}{%
       \ifnum\csname #1COLS\endcsname=0\relax%
         \expandafter\let\csname #1[\the@row]\endcsname\undefined%
@@ -494,16 +489,32 @@ element-by-element basis.]
 
 \endinput
 
-
-
-
-
-
-
-
-
-
-
+% Revisions:
+% v1.0  -Initial release.
+% v1.01 -Documentation revision.
+% v1.1  -Added \csname record\roman{@row}\endcsname to \readdef.
+% v1.2  -Corrected the [truncated] LPPL license info.
+%       -Added \arrayij and \arrayijk, which can be put into \edef.
+%       -Used \romannumeral in preference to \roman{}, when possible,
+%        to avoid unnecessary use of counters.
+% v1.3  -Moved \newread outside of \readdef, so as not to exhaust the
+%        16 allotted file streams (Thanks to Ken Kubota for the tip).
+% v2.0  -Converted parsing to listofitems package.  This allows for
+%        ANY parsing character or combination of characters (via logical OR).
+%       -Replaced all \protected@edef's with appropriately expanded \def's.
+%       -Use listofitems package in preference to \getargsC.
+%       -Deprecated \Arrayijk, \arrayijk, \Arrayij, & \arrayij.  Direct
+%        access now preferred, e.g., \xyz[2,3,1].
+%       -Deprecated most other commands in favor of a more natural syntax.
+% v3.0  (2021-08-05)
+%       -Added features: \setvalue, \initarray, \mergearray, \typesetarray.
+%       -Allowed for \readarrayendlinechar to be set other than 9.
+% v3.1  (2021-09-17)
+%       -Bug fix to not break if first line of file subject to \readdef
+%        is blank/comment line.
+%       -Introduce \ifignoreblankreadarrayrecords
+%       -Bug fix in \clear@array, if selected array name is defined,
+%        but not defined as an array.
 
 
 
diff --git a/macros/latex/contrib/readarray/readarray.tex b/macros/latex/contrib/readarray/readarray.tex
index bd9a4aa114..bdbb3bef70 100644
--- a/macros/latex/contrib/readarray/readarray.tex
+++ b/macros/latex/contrib/readarray/readarray.tex
@@ -9,8 +9,22 @@
 \def\rdar{\textsf{readarray}}
 \def\loi{\textsf{listofitems}}
 \def\cmd#1{\texttt{\string\ \unskip#1}}
-\usepackage{readarray}
+\usepackage{readarray,tokcycle}
 \usepackage{verbatimbox}
+\newcommand\bverb[1][]{\begingroup\ifx\relax#1\relax
+  \def\tmpA{\allowbreak}\def\tmpB{0}\else
+  \def\tmpA{}\def\tmpB{#1}\fi
+  \catcode`\%=12 \bverbaux}
+\newcommand\bverbaux[2][\allowbreak\textvisiblespace\allowbreak]{%
+  \ttfamily\tokencycle
+  {\expandafter\tctestifx\expandafter{\tmpB##1}{\allowbreak}
+    {\string##1\tmpA}}
+  {\{\processtoks{##1}\}}
+  {\tctestifx{\isiteleven##1}{##1}
+    {\expandafter\tctestifx\expandafter{\tmpB##1}{\allowbreak}
+    {\tcpush{\string##1\isiteleven}}}}
+  {#1}#2\endtokencycle\endgroup}
+\def\isiteleven{\tcpeek\zzz\ifcat\noexpand\zzz A\tcpush{\space}\fi}
 \begin{filecontents*}[overwrite]{file1data.txt}
 A111 A112 A113 A114
 A121 A122 A123 A124
@@ -179,7 +193,11 @@ commands are:
 \textup{To select the level of bounds checking on array cell recall:}\\
 \rl\vb|\nocheckbounds|\hfill OR\hfill%
 \vb|\checkbounds|\hfill OR\hfill%
-\vb|\hypercheckbounds|
+\vb|\hypercheckbounds|\\
+\textup{To ignore blank (or fully commented) records during the
+  course of a record-array read (this can be undone with a false
+  setting):}\\
+\rl\vb|\ignoreblankreadarrayrecordstrue|
 \upshape 
 
 In these commands, \cmd{}\textit{data-macro} is a control sequence into
@@ -454,6 +472,27 @@ If an array name is reutilized, its prior definitions are cleared,
   so that ``old'' data is not inadvertantly retrieved following the
   reutilization.
 
+One option (introduced in v3.1) in this regard is the if-condition%
+  \margcmd{ifignoreblank readarrayrecords}
+  \bverb[.]{\ifignore.blankreadarrayrecords}, which can take on
+  values of either \bverb[\-]{\ignoreblank\-readarrayrecordstrue} or
+  \bverb{\ignoreblankreadarrayrecordsfalse}.  
+When set to the true condition, ``blank'' records in the input file
+  (defined either when the record is actually blank or if the first 
+  non-blank token in the record is a catcode-14 \verb|%|) will 
+  be ignored.
+This setting will only affect the record array itself---the result
+  of any \cmd{readdef} will be unaffected by this setting, except
+  as detailed in the next paragraph.
+
+The only warning to heed when setting 
+  \bverb[\-]{\ignoreblankreadarrayrecords\-true} is that the first
+  blank line in a \bverb{\readdef}'ed file is used to set the value
+  of \cmd{nrows}, which can be used to set the row-depth of a 3-D 
+  array plane within subsequent invocations of \cmd{readarray}.
+Of course, the array plane's row-depth may always be set
+  manually, in lieu of using \bverb{\nrows}.
+
 
 \subsection{Creating 2-D and 3-D Arrays from Data}
 
@@ -948,7 +987,7 @@ I am likewise grateful to Ken Kubota, who suggested moving the
   \vb|\newread| outside of \vb|\readdef|, so as not to prematurely 
   exhaust the 16 available file streams.
 
-\clearpage
+%\clearpage
 \section{Code Listing}
 
 \verbfilenobox[\footnotesize]{readarray.sty}