summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/nicematrix/nicematrix.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/nicematrix/nicematrix.dtx')
-rw-r--r--macros/latex/contrib/nicematrix/nicematrix.dtx267
1 files changed, 211 insertions, 56 deletions
diff --git a/macros/latex/contrib/nicematrix/nicematrix.dtx b/macros/latex/contrib/nicematrix/nicematrix.dtx
index 4f3effcd14..5aa6211092 100644
--- a/macros/latex/contrib/nicematrix/nicematrix.dtx
+++ b/macros/latex/contrib/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