diff options
Diffstat (limited to 'macros/latex/contrib/nicematrix/nicematrix.dtx')
| -rw-r--r-- | macros/latex/contrib/nicematrix/nicematrix.dtx | 267 |
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 |