nicematrix (12nov19)

git-svn-id: svn://tug.org/texlive/trunk@52757 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 211 insertions, 56 deletions

diff --git a/Master/texmf-dist/source/latex/nicematrix/nicematrix.dtx b/Master/texmf-dist/source/latex/nicematrix/nicematrix.dtx
index 4f3effcd146..5aa62110929 100644
--- a/Master/texmf-dist/source/latex/nicematrix/nicematrix.dtx
+++ b/Master/texmf-dist/source/latex/nicematrix/nicematrix.dtx
@@ -15,8 +15,8 @@
 %
 % \fi
 % \iffalse
-\def\myfileversion{3.6}
-\def\myfiledate{2019/10/29}
+\def\myfileversion{3.7}
+\def\myfiledate{2019/11/11}
 %
 %
 %<*batchfile>
@@ -1362,11 +1362,11 @@ c & c & b & a & e
 % \section{The counters iRow and jCol}
 %
 % In the cells of the array, it's possible to use the LaTeX counters |iRow| and
-% |jCol| which represents the number of the current row and the number of the
+% |jCol| which represent the number of the current row and the number of the
 % current col\footnote{We recall that the first row (if it exists) has the
-% number~$0$ and that the first col (if it exists) has also the number~$0$).}. Of
-% course, the user must not change the value of the these counters which are
-% used internally by \pkg{nicematrix}.
+% number~$0$ and that the first col (if it exists) has also the number~$0$).}.
+% Of course, the user must not change the value of these counters which are used
+% internally by \pkg{nicematrix}.
 %
 % \medskip
 % \begin{BVerbatim}[baseline=c,boxwidth=10.6cm]
@@ -1391,10 +1391,30 @@ c & c & b & a & e
 % & 9 & 10 & 11 & 12
 % \end{pNiceMatrix}$
 % 
-% \smallskip
+% \medskip
 % If LaTeX counters called |iRow| and |jCol| are defined in the document by
 % extensions other than \pkg{nicematrix} (or by the user), they are shadowed in
-% the environements of \pkg{nicematrix}.
+% the environments of \pkg{nicematrix}.
+%
+% \bigskip
+% The extension \pkg{nicematrix} also provides commands in order to compose
+% automatically matrices from a general pattern. These commands are
+% |\pAutoNiceMatrix|, |\bAutoNiceMatrix|, |\vAutoNiceMatrix|,
+% |\VAutoNiceMatrix| and |\BAutoNiceMatrix|.
+%
+% These commands take two mandatory arguments. The first is the format of the
+% matrix, with the syntax $n$-$p$ where $n$ is the number of rows and $p$ the
+% number of columns. The second argument is the pattern (it's a list of tokens
+% which are inserted in each cell of the constructed matrix, excepted in the
+% cells of the eventual exterior rows and columns).
+%
+% \medskip
+% \begin{Verbatim}
+% $C = ~emphase#\pAutoNiceMatrix@{3-3}{C_{\arabic{iRow},\arabic{jCol}}}$
+% \end{Verbatim}
+%
+%
+% $C = \pAutoNiceMatrix{3-3}{C_{\arabic{iRow},\arabic{jCol}}}$
 %
 % \section{The option hlines}
 % 
@@ -2615,7 +2635,8 @@ c & c & b & a & e
 %    \end{macrocode}
 %
 % \bigskip
-% The name of the current environment (will be used only in the error messages).
+% The name of the current environment or the current command (will be used only
+% in the error messages). 
 %    \begin{macrocode}
 \str_new:N \g_@@_type_env_str
 %    \end{macrocode}
@@ -3004,11 +3025,11 @@ c & c & b & a & e
     columns-width .value_required:n = true ,
     name .code:n = 
       \unless \ifmeasuring@
-          \str_set:Nn \l_tmpa_str { #1 }
-          \seq_if_in:NVTF \g_@@_names_seq \l_tmpa_str
-             { \@@_error:nn { Duplicate~name } { #1 } }
-             { \seq_gput_left:NV \g_@@_names_seq \l_tmpa_str }
-          \str_set_eq:NN \l_@@_name_str \l_tmpa_str 
+         \str_set:Nn \l_tmpa_str { #1 }
+         \seq_if_in:NVTF \g_@@_names_seq \l_tmpa_str
+           { \@@_error:nn { Duplicate~name } { #1 } }
+           { \seq_gput_left:NV \g_@@_names_seq \l_tmpa_str }
+         \str_set_eq:NN \l_@@_name_str \l_tmpa_str 
       \fi ,
     name .value_required:n = true ,
     code-after .tl_gset:N = \g_@@_code_after_tl ,
@@ -3815,7 +3836,10 @@ c & c & b & a & e
 \NewDocumentEnvironment { NiceArrayWithDelims } { m m O { } m ! O { } }
   { 
     \str_if_empty:NT \g_@@_type_env_str 
-      { \str_gset:Nn \g_@@_type_env_str { NiceArrayWithDelims } }
+      { 
+        \str_gset:Nn \g_@@_type_env_str 
+          { environment ~ { NiceArrayWithDelims } }
+      } 
     \@@_adapt_S_column:
     \@@_test_if_math_mode:
     \bool_if:NT \l_@@_in_env_bool { \@@_fatal:n { Yet~in~env } } 
@@ -4231,7 +4255,21 @@ c & c & b & a & e
         \hbox_set:Nw \l_tmpa_box 
         \c_math_toggle_token
         \bool_if:NT \l_@@_small_bool \scriptstyle
-        \int_compare:nNnT \c@iRow > \c_zero_int \l_@@_code_for_first_col_tl
+%    \end{macrocode}
+% We insert |\l_@@_code_for_first_col_tl|... but we don't insert it in the
+% potential ``first row'' and in the potential ``last row''.
+%    \begin{macrocode}
+        \bool_if:nT
+          {
+            \int_compare_p:nNn \c@iRow > \c_zero_int 
+            && 
+            (
+              \int_compare_p:nNn \l_@@_last_row_int < 0
+              ||
+              \int_compare_p:nNn \c@iRow < \l_@@_last_row_int
+            )
+          }
+          { \l_@@_code_for_first_col_tl }
       }
     l
     < 
@@ -4314,7 +4352,21 @@ c & c & b & a & e
         \hbox_set:Nw \l_tmpa_box 
           \c_math_toggle_token
           \bool_if:NT \l_@@_small_bool \scriptstyle 
-          \l_@@_code_for_last_col_tl
+%    \end{macrocode}
+% We insert |\l_@@_code_for_last_col_tl|... but we don't insert it in the
+% potential ``first row'' and in the potential ``last row''.
+%    \begin{macrocode}
+        \bool_if:nT
+          {
+            \int_compare_p:nNn \c@iRow > \c_zero_int 
+            && 
+            (
+              \int_compare_p:nNn \l_@@_last_row_int < 0
+              ||
+              \int_compare_p:nNn \c@iRow < \l_@@_last_row_int
+            )
+          }
+          { \l_@@_code_for_last_col_tl }
       }
     l
     < 
@@ -4385,7 +4437,7 @@ c & c & b & a & e
   { 
     \bool_set_true:N \l_@@_NiceArray_bool
     \str_if_empty:NT \g_@@_type_env_str 
-      { \str_gset:Nn \g_@@_type_env_str { NiceArray } }
+      { \str_gset:Nn \g_@@_type_env_str { environment ~ { NiceArray } } } 
 %    \end{macrocode}
 % We put . and . for the delimiters but, in fact, that doesn't matter because
 % these arguments won't be used in |{NiceArrayWithDelims}| (because the flag
@@ -4405,7 +4457,7 @@ c & c & b & a & e
 \NewDocumentEnvironment { pNiceArray } { }
   {
     \str_if_empty:NT \g_@@_type_env_str 
-      { \str_gset:Nn \g_@@_type_env_str { pNiceArray } }
+      { \str_gset:Nn \g_@@_type_env_str { environment ~ { pNiceArray } } }
     \@@_test_if_math_mode:
     \NiceArrayWithDelims ( )
   }
@@ -4416,7 +4468,7 @@ c & c & b & a & e
 \NewDocumentEnvironment { bNiceArray } { }
   {
     \str_if_empty:NT \g_@@_type_env_str 
-      { \str_gset:Nn \g_@@_type_env_str { NiceArray } }
+      { \str_gset:Nn \g_@@_type_env_str { environment ~ { bNiceArray } } }
     \@@_test_if_math_mode:
     \NiceArrayWithDelims [ ]
   }
@@ -4427,18 +4479,18 @@ c & c & b & a & e
 \NewDocumentEnvironment { BNiceArray } { }
   {
     \str_if_empty:NT \g_@@_type_env_str 
-      { \str_gset:Nn \g_@@_type_env_str { BNiceArray } }
+      { \str_gset:Nn \g_@@_type_env_str { environment ~ { BNiceArray } } }
     \@@_test_if_math_mode:
     \NiceArrayWithDelims \{ \}
   }
   { \endNiceArrayWithDelims }
-%    \end{macrocode}
+%    \end{macrocode} 
 %               
 %   \begin{macrocode}
 \NewDocumentEnvironment { vNiceArray } { }
   {
     \str_if_empty:NT \g_@@_type_env_str 
-      { \str_gset:Nn \g_@@_type_env_str { vNiceArray } }
+      { \str_gset:Nn \g_@@_type_env_str { environment ~ { vNiceArray } } }
     \@@_test_if_math_mode:
     \NiceArrayWithDelims | |
   }
@@ -4449,7 +4501,7 @@ c & c & b & a & e
 \NewDocumentEnvironment { VNiceArray } { }
   {
     \str_if_empty:NT \g_@@_type_env_str 
-      { \str_gset:Nn \g_@@_type_env_str { VNiceArray } }
+      { \str_gset:Nn \g_@@_type_env_str { environment ~ { VNiceArray } } }
     \@@_test_if_math_mode:
     \NiceArrayWithDelims \| \|
   }
@@ -4464,7 +4516,7 @@ c & c & b & a & e
   {
     \NewDocumentEnvironment { #1 NiceMatrix } { ! O { } }
       {
-        \str_gset:Nn \g_@@_type_env_str { #1 NiceMatrix } 
+        \str_gset:Nn \g_@@_type_env_str { environment ~ { #1 NiceMatrix } }  
         \keys_set:nn { NiceMatrix / NiceMatrix } { ##1 }
         \begin { #1 NiceArray } 
           { 
@@ -5742,8 +5794,37 @@ c & c & b & a & e
 % In the |code-after|, the command |\@@_line:nn| will be linked to |\line|. This
 % command takes two arguments which are the specification of two cells in the
 % array (in the format $i$-$j$) and draws a dotted line between these cells. 
+% 
+% \medskip
+% First, we write a command with an argument of the format $i$-$j$ and applies
+% the command |\int_eval:n| to $i$ and~$j$ ; this must \emph{not} be protected
+% (and is, of course fully expandable).\footnote{Indeed, we want that the user
+% may use the command |\line| in |code-after| with LaTeX counters in the
+% arguments --- with the command |\value|.}
+%    \begin{macrocode}
+\cs_new:Npn \@@_double_int_eval:n #1-#2 \q_stop
+  { \int_eval:n { #1 } - \int_eval:n { #2 } }
+%    \end{macrocode}
+%
+% \medskip
+% With the following construction, the command |\@@_double_int_eval:n| is
+% applied to both arguments before the application of |\@@_line_i:nn| (the
+% construction uses the fact the |\@@_line_i:nn| is protected and that
+% |\@@_double_int_eval:n| is fully expandable).
 %    \begin{macrocode}
-\cs_new_protected:Nn \@@_line:nn
+\cs_new_protected:Npn \@@_line:nn #1 #2
+  {
+    \use:x
+      {
+        \@@_line_i:nn 
+          { \@@_double_int_eval:n #1 \q_stop }
+          { \@@_double_int_eval:n #2 \q_stop }
+      }
+  }
+%    \end{macrocode}
+% 
+%    \begin{macrocode}
+\cs_new_protected:Nn \@@_line_i:nn
   {
     \bool_if:NF \c_@@_draft_bool
       {
@@ -5761,13 +5842,13 @@ c & c & b & a & e
           }
           {
             \begin { tikzpicture }
-               \path~(#1)~--~(#2)~node[at~start]~(i)~{}~node[at~end]~(f)~{} ;
-               \tikz@parse@node \pgfutil@firstofone ( i )
-               \dim_gset:Nn \g_@@_x_initial_dim \pgf@x
-               \dim_gset:Nn \g_@@_y_initial_dim \pgf@y
-               \tikz@parse@node \pgfutil@firstofone ( f )
-               \dim_gset:Nn \g_@@_x_final_dim \pgf@x
-               \dim_gset:Nn \g_@@_y_final_dim \pgf@y
+              \path~(#1)~--~(#2)~node[at~start]~(i)~{}~node[at~end]~(f)~{} ;
+              \tikz@parse@node \pgfutil@firstofone ( i )
+              \dim_gset:Nn \g_@@_x_initial_dim \pgf@x
+              \dim_gset:Nn \g_@@_y_initial_dim \pgf@y
+              \tikz@parse@node \pgfutil@firstofone ( f )
+              \dim_gset:Nn \g_@@_x_final_dim \pgf@x
+              \dim_gset:Nn \g_@@_y_final_dim \pgf@y
             \end { tikzpicture }  
             \@@_draw_tikz_line:
           }
@@ -6403,9 +6484,7 @@ c & c & b & a & e
 % command |\multicolumn|. 
 %    \begin{macrocode}
 \NewExpandableDocumentCommand \@@_Block: { m D < > { } m }
-  {
-    \@@_Block_i #1 \q_stop { #2 } { #3 }
-  }
+  { \@@_Block_i #1 \q_stop { #2 } { #3 } }
 %    \end{macrocode}
 % 
 % \medskip
@@ -6413,10 +6492,7 @@ c & c & b & a & e
 % It must be of the form $i$|-|$j$ where $i$ and $j$ are the size (in rows and 
 % columns) of the block.
 %    \begin{macrocode}
-\cs_new:Npn \@@_Block_i #1-#2 \q_stop
-  {
-    \@@_Block_ii:nnnn { #1 } { #2 } 
-  }
+\cs_new:Npn \@@_Block_i #1-#2 \q_stop { \@@_Block_ii:nnnn { #1 } { #2 } }
 %    \end{macrocode}
 %
 % \medskip
@@ -6520,7 +6596,7 @@ c & c & b & a & e
   }
 %    \end{macrocode}
 %                          
-% % \subsection{How to draw the dotted lines transparently}
+% \subsection{How to draw the dotted lines transparently}
 %    \begin{macrocode}
 \cs_set_protected:Npn \@@_renew_matrix:
   { 
@@ -6543,7 +6619,75 @@ c & c & b & a & e
 %    \end{macrocode}
 %
 %
+% \medskip
+% \subsection{Automatic arrays}
+%
+% 
+%    \begin{macrocode}
+\cs_new_protected:Npn \@@_set_size:n #1-#2 \q_stop
+  {
+    \int_set:Nn \l_@@_nb_rows_int { #1 }
+    \int_set:Nn \l_@@_nb_cols_int { #2 }
+  }
+%    \end{macrocode}
+%
 %
+%    \begin{macrocode}
+\NewDocumentCommand \AutoNiceMatrixWithDelims { m m O { } m O { } m ! O { } } 
+  {
+    \int_zero_new:N \l_@@_nb_rows_int
+    \int_zero_new:N \l_@@_nb_cols_int
+    \@@_set_size:n #4 \q_stop
+    \begin { NiceArrayWithDelims } { #1 } { #2 } 
+      { * { \l_@@_nb_cols_int } { C } } [ #3 , #5 , #7 ] 
+    \int_compare:nNnT \l_@@_first_row_int = \c_zero_int
+      { 
+        \int_compare:nNnT \l_@@_first_col_int = \c_zero_int { & } 
+        \prg_replicate:nn { \l_@@_nb_cols_int - 1 } { & } 
+        \int_compare:nNnT \l_@@_last_col_int > { -1 } { & } \\ 
+      }
+    \prg_replicate:nn \l_@@_nb_rows_int
+      { 
+        \int_compare:nNnT \l_@@_first_col_int = \c_zero_int { & }
+%    \end{macrocode}
+% You put |{ }| before |#6| to avoid a hasty expansion of an eventual
+% |\arabic{iRow}| at the beginning of the row which would result in an incorrect
+% value of that |iRow| (since |iRow| is incremented in the first cell of the row
+% of the |\halign|).
+%    \begin{macrocode}
+        \prg_replicate:nn { \l_@@_nb_cols_int - 1 } { { } #6 & } #6
+        \int_compare:nNnT \l_@@_last_col_int > { -1 } { & } \\  
+      }
+    \int_compare:nNnT \l_@@_last_row_int > { -2 }
+      { 
+        \int_compare:nNnT \l_@@_first_col_int = \c_zero_int { & }
+        \prg_replicate:nn { \l_@@_nb_cols_int - 1 } { & } 
+        \int_compare:nNnT \l_@@_last_col_int > { -1 } { & } \\  
+      }
+    \end { NiceArrayWithDelims }
+  }
+%    \end{macrocode}
+% 
+%    \begin{macrocode}
+\cs_set_protected:Npn \@@_define_com:nnn #1 #2 #3
+  { 
+    \cs_set_protected:cpn { #1 AutoNiceMatrix }
+      {
+        \str_gset:Nx \g_@@_type_env_str 
+          { command ~ \c_backslash_str #1 AutoNiceMatrix } 
+        \AutoNiceMatrixWithDelims { #2 } { #3 }
+      }  
+  }
+%    \end{document}
+%    \begin{macrocode}
+\@@_define_com:nnn p ( ) 
+\@@_define_com:nnn b [ ]
+\@@_define_com:nnn v | |
+\@@_define_com:nnn V \| \|
+\@@_define_com:nnn B \{ \}
+%    \end{macrocode}
+% 
+% \medskip
 % \subsection{We process the options}
 %
 % We process the options when the package is loaded (with |\usepackage|) but we
@@ -6584,9 +6728,8 @@ c & c & b & a & e
 %    \begin{macrocode}
 \@@_msg_new:nn { last-col~non~empty~for~NiceArray }
   {
-    In~the~environment~\{\g_@@_type_env_str\},~you~must~use~the~option~
-    'last-col'~without~value~(the~number~of~columns~is~known~by~the~
-    preamble~of~the~environment).\\
+    In~the~\g_@@_type_env_str,~you~must~use~the~option~
+    'last-col'~without~value.\\
     However,~you~can~go~on~for~this~time~
     (the~value~'\l_keys_value_tl'~will~be~ignored). 
   }
@@ -6595,7 +6738,7 @@ c & c & b & a & e
 %    \begin{macrocode}
 \@@_msg_new:nn { last-col~empty~for~NiceMatrix }
   {
-    In~the~environment~\{\g_@@_type_env_str\}~you~can't~use~the~option~
+    In~the~\g_@@_type_env_str, you~can't~use~the~option~
     'last-col'~without~value.~You~must~give~the~number~of~that~last~column.\\
     If~you~go~on~this~option~will~be~ignored.
   }
@@ -6606,7 +6749,7 @@ c & c & b & a & e
   {
     You~try~to~draw~a~block~in~the~cell~#1-#2~of~your~matrix~but~the~matrix~is~
     too~small~for~that~block.\\
-    If~you~go~on,~this~command~line~will~be~ignored.
+    If~you~go~on,~this~command~will~be~ignored.
   }
 %    \end{macrocode}
 %
@@ -6623,10 +6766,10 @@ c & c & b & a & e
 %    \begin{macrocode}
 \@@_msg_new:nn { Wrong~last~row }
   { 
-    You~have~used~'last-row=\int_use:N \l_@@_last_row_int'~but~your~environment~
-    \{\g_@@_type_env_str\}~seems~to~have~\int_use:N \c@iRow 
-    rows.~If~you~go~on,~the~value~of~\int_use:N \c@iRow 
-    will~be~used~for~last~row.~You~can~avoid~this~problem~by~using~'last-row'~
+    You~have~used~'last-row=\int_use:N \l_@@_last_row_int'~but~your~
+    \g_@@_type_env_str\ seems~to~have~\int_use:N \c@iRow \ rows.~
+    If~you~go~on,~the~value~of~\int_use:N \c@iRow \ will~be~used~for~
+    last~row.~You~can~avoid~this~problem~by~using~'last-row'~  
     without~value~(more~compilations~might~be~necessary).
   }
 %    \end{macrocode}     
@@ -6643,7 +6786,7 @@ c & c & b & a & e
 %    \begin{macrocode}
 \@@_msg_new:nn { Outside~math~mode }
   {
-    The~environment~\{\g_@@_type_env_str\}~can~be~used~only~in~math~mode~
+    The~\g_@@_type_env_str\ can~be~used~only~in~math~mode~
     (and~not~in~\token_to_str:N \vcenter).\\
     This~error~is~fatal.
   }
@@ -6655,6 +6798,9 @@ c & c & b & a & e
     The~option~'Transparent'~has~been~renamed~'transparent'.\\
     However,~you~can~go~on~for~this~time.
   }
+%    \end{macrocode}
+%
+%    \begin{macrocode}
 \@@_msg_new:nn { Option~RenewMatrix~suppressed }
   { 
     The~option~'RenewMatrix'~has~been~renamed~'renew-matrix'.\\
@@ -6744,8 +6890,8 @@ c & c & b & a & e
 %    \begin{macrocode}
 \@@_msg_new:nnn { Unknown~option~for~NiceMatrix }
   { 
-    The~option~'\tl_use:N\l_keys_key_tl'~is~unknown~for~the~environment~
-    \{\g_@@_type_env_str\}. \\
+    The~option~'\tl_use:N\l_keys_key_tl'~is~unknown~for~the~
+    \g_@@_type_env_str. \\
     If~you~go~on,~it~will~be~ignored. \\
     For~a~list~of~the~available~options,~type~H~<return>.
   }
@@ -6805,7 +6951,7 @@ c & c & b & a & e
 %    \begin{macrocode}
 \@@_msg_new:nn { Zero~row }
   { 
-    There~is~a~problem.~Maybe~your~environment~\{\g_@@_type_env_str\}~is~empty.~ 
+    There~is~a~problem.~Maybe~your~\g_@@_type_env_str\ is~empty.~ 
     Maybe~you~have~used~l,~c~and~r~instead~of~L,~C~and~R~in~the~preamble~
     of~your~environment. \\
     If~you~go~on,~the~result~may~be~incorrect.
@@ -6816,7 +6962,7 @@ c & c & b & a & e
 \@@_msg_new:nn { Use~of~:~in~first~position }
   { 
     You~can't~use~the~column~specifier~'\l_@@_letter_for_dotted_lines_str'~in~the~
-    first~position~of~the~preamble~of~the~environment~\{\g_@@_type_env_str\}. \\
+    first~position~of~the~preamble~of~the~\g_@@_type_env_str. \\
     If~you~go~on,~this~dotted~line~will~be~ignored.
   }
 %    \end{macrocode}
@@ -6827,7 +6973,7 @@ c & c & b & a & e
 %    \begin{macrocode}
 \@@_msg_new:nn { Obsolete~environment }
   {
-    The~environment~\{\@currenvir\}~is~obsolete.~
+    The~environment~\{\@currenvir\}~is~obsolete~and~will~be~deleted~in~future~version.~ 
     We~should~use~#1~instead.
   }
 %    \end{macrocode}
@@ -7171,6 +7317,15 @@ c & c & b & a & e
 %
 % There is no longer artificial errors |Duplicate~name| in the environments of
 % \pkg{amsmath}. 
+%
+% \subsection*{Changes between version 3.6 and 3.7} 
+% 
+% The four ``corners'' of the matrix are correctly protected against the four
+% codes: |code-for-first-col|, |code-for-last-col|, |code-for-first-row| and
+% |code-for-last-row|. 
+%
+% New command |\pAutoNiceMatrix| and its variants (suggestion of Christophe Bal).
+% 
 % \PrintIndex
 % 
 % \tableofcontents