[latex3-commits] [git/LaTeX3-latex3-latex2e] hook-args: Replace \hook_use:nw by \hook_use:nnw (6cd90f83)
PhelypeOleinik
phelype.oleinik at latex-project.org
Fri Apr 14 19:59:08 CEST 2023
Repository : https://github.com/latex3/latex2e
On branch : hook-args
Link : https://github.com/latex3/latex2e/commit/6cd90f837dc09c99f003fe6f7f823a9acc70c4c9
>---------------------------------------------------------------
commit 6cd90f837dc09c99f003fe6f7f823a9acc70c4c9
Author: PhelypeOleinik <phelype.oleinik at latex-project.org>
Date: Fri Apr 14 14:59:08 2023 -0300
Replace \hook_use:nw by \hook_use:nnw
And pass the number of arguments to be used
>---------------------------------------------------------------
6cd90f837dc09c99f003fe6f7f823a9acc70c4c9
base/lthooks.dtx | 163 ++++++++++++++++++++++++---------
base/testfiles-lthooks/lthooks-033.lvt | 6 +-
2 files changed, 122 insertions(+), 47 deletions(-)
diff --git a/base/lthooks.dtx b/base/lthooks.dtx
index c5272914..f76d2c9a 100644
--- a/base/lthooks.dtx
+++ b/base/lthooks.dtx
@@ -266,11 +266,14 @@
%
% \begin{function}{\UseHookWithArguments}
% \begin{syntax}
-% \cs{UseHookWithArguments} \Arg{hook} \Arg{arg_1} \ldots \Arg{arg_n}
+% \cs{UseHookWithArguments} \Arg{hook} \Arg{number} \Arg{arg_1} \ldots \Arg{arg_n}
% \end{syntax}
% Execute the code stored in the \meta{hook} and pass the arguments
% \Arg{arg_1} through \Arg{arg_n} to the \meta{hook}. Otherwise, it
% works exactly like \cs{UseHook}.
+% The \meta{number} should be the number of arguments declared for
+% the hook. If the hook is not declared, this command does nothing
+% and it will remove \meta{number} items from the input.
% Section~\ref{sec:hook-args} explains hooks with arguments.
%
% The \meta{hook} \emph{cannot} be specified using the dot-syntax.
@@ -312,10 +315,13 @@
%
% \begin{function}{\UseOneTimeHookWithArguments}
% \begin{syntax}
-% \cs{UseOneTimeHookWithArguments} \Arg{hook} \Arg{arg_1} \ldots \Arg{arg_n}
+% \cs{UseOneTimeHookWithArguments} \Arg{hook} \Arg{number} \Arg{arg_1} \ldots \Arg{arg_n}
% \end{syntax}
% Works exactly like \cs{UseOneTimeHook}, but passes arguments
% \Arg{arg_1} through \Arg{arg_n} to the \meta{hook}.
+% The \meta{number} should be the number of arguments declared for
+% the hook. If the hook is not declared, this command does nothing
+% and it will remove \meta{number} items from the input.
%
% It should be noted that after a one-time hook is used, it is no
% longer possible to use \cs{AddToHookWithArguments} or similar with
@@ -1085,32 +1091,38 @@
%
%
%
-% \begin{function}{\hook_use:n,\hook_use:nw}
+% \begin{function}{\hook_use:n,\hook_use:nnw}
% \begin{syntax}
% \cs{hook_use:n} \Arg{hook}
-% \cs{hook_use:nw} \Arg{hook} \Arg{arg_1} \ldots \Arg{arg_n}
+% \cs{hook_use:nnw} \Arg{hook} \Arg{number} \Arg{arg_1} \ldots \Arg{arg_n}
% \end{syntax}
% Executes the \Arg{hook} code followed (if set up) by the code for next
% invocation only, then empties that next invocation code.
-% \cs{hook_use:nw} should be used for hooks declared with arguments,
+% \cs{hook_use:nnw} should be used for hooks declared with arguments,
% and should be followed by as many brace groups as the declared
% number of arguments.
+% The \meta{number} should be the number of arguments declared for
+% the hook. If the hook is not declared, this command does nothing
+% and it will remove \meta{number} items from the input.
%
% The \meta{hook} \emph{cannot} be specified using the dot-syntax.
% A leading |.| is treated literally.
% \end{function}
%
-% \begin{function}{\hook_use_once:n,\hook_use_once:nw}
+% \begin{function}{\hook_use_once:n,\hook_use_once:nnw}
% \begin{syntax}
% \cs{hook_use_once:n} \Arg{hook}
-% \cs{hook_use_once:nw} \Arg{hook} \Arg{arg_1} \ldots \Arg{arg_n}
+% \cs{hook_use_once:nnw} \Arg{hook} \Arg{number} \Arg{arg_1} \ldots \Arg{arg_n}
% \end{syntax}
% Changes the \Arg{hook} status so that from now on any addition to
% the hook code is executed immediately. Then execute any
% \Arg{hook} code already set up.
-% \cs{hook_use_once:nw} should be used for hooks declared with arguments,
+% \cs{hook_use_once:nnw} should be used for hooks declared with arguments,
% and should be followed by as many brace groups as the declared
% number of arguments.
+% The \meta{number} should be the number of arguments declared for
+% the hook. If the hook is not declared, this command does nothing
+% and it will remove \meta{number} items from the input.
%
% The \meta{hook} \emph{cannot} be specified using the dot-syntax.
% A leading |.| is treated literally.
@@ -1129,8 +1141,8 @@
% appended to the already existing code.
%
% If \cs{hook_gput_code_with_args:nnn} is used, the \meta{code}
-% can access the arguments passed to \cs{hook_use:nw}
-% (or~\cs{hook_use_once:nw}) with \verb|#1|, \verb|#2|, \ldots,
+% can access the arguments passed to \cs{hook_use:nnw}
+% (or~\cs{hook_use_once:nnw}) with \verb|#1|, \verb|#2|, \ldots,
% \verb|#n| (up to the number of arguments declared for the hook).
% In that case, if an actual parameter token should be added to the
% code, it should be doubled.
@@ -1156,8 +1168,8 @@
% \meta{hook}. Once used it is gone.
%
% If \cs{hook_gput_next_code_with_args:nn} is used, the \meta{code}
-% can access the arguments passed to \cs{hook_use:nw}
-% (or~\cs{hook_use_once:nw}) with \verb|#1|, \verb|#2|, \ldots,
+% can access the arguments passed to \cs{hook_use:nnw}
+% (or~\cs{hook_use_once:nnw}) with \verb|#1|, \verb|#2|, \ldots,
% \verb|#n| (up to the number of arguments declared for the hook).
% In that case, if an actual parameter token should be added to the
% code, it should be doubled.
@@ -5132,8 +5144,7 @@
% call the hook code and not initialize it (as it was done in the
% preamble.
% \begin{macrocode}
- \cs_gset_eq:NN \hook_use:n \@@_use_initialized:n
- \cs_gset_eq:NN \@@_preamble_hook:n \use_none:n
+ \@@_post_initialization_defs:
}
% \end{macrocode}
%
@@ -6333,9 +6344,8 @@
%
% \subsection{Using the hook}
%
-% \begin{macro}{\hook_use:n,\hook_use:nw}
+% \begin{macro}{\hook_use:n}
% \begin{macro}[EXP]{\@@_use_initialized:n}
-% \begin{macro}{\@@_use_undefined:w,\@@_use_end:}
% \begin{macro}{\@@_preamble_hook:n}
% \cs{hook_use:n} as defined here is used in the preamble, where
% hooks aren't initialized by default. \cs{@@_use_initialized:n} is
@@ -6360,27 +6370,29 @@
% \verb=\csname ...\endcsname= construct \cs{tl_if_exist:c} is
% careful to avoid this.
% \changes{v1.1a}{2023/04/06}
-% {Add \cs{hook_use:nw} (hook-args).}
+% {Add \cs{hook_use:nnw} (hook-args).}
% \begin{macrocode}
%<latexrelease>\IncludeInRelease{2023/06/01}{\hook_use:n}
%<latexrelease> {Hooks~with~args}
\cs_new_protected:Npn \hook_use:n #1
{
- \cs_if_exist:cT { @@~#1 }
- {
- \@@_preamble_hook:n {#1}
- \cs:w @@~#1 \cs_end:
- }
+ \@@_preamble_hook:n {#1}
+ \@@_use_initialized:n {#1}
}
\cs_new:Npn \@@_use_initialized:n #1
{
\if_cs_exist:w @@~#1 \cs_end:
- \cs:w @@~#1 \exp_after:wN \cs_end:
+ \cs:w @@~#1 \use_i:nn
\fi:
+ \use_none:n
+ \cs_end:
}
\cs_new_protected:Npn \@@_preamble_hook:n #1
- { \@@_initialize_hook_code:n {#1} }
-\cs_new:Npn \hook_use:nw { \hook_use:n }
+ {
+ \if_cs_exist:w @@~#1 \cs_end:
+ \@@_initialize_hook_code:n {#1}
+ \fi:
+ }
%<latexrelease>\EndIncludeInRelease
% \end{macrocode}
%
@@ -6403,7 +6415,7 @@
%<latexrelease> }
%<latexrelease>\cs_new_protected:Npn \@@_preamble_hook:n #1
%<latexrelease> { \@@_initialize_hook_code:n {#1} }
-%<latexrelease>\cs_new:Npn \hook_use:nw #1 { }
+%<latexrelease>\cs_new:Npn \hook_use:nnw #1 { }
%<latexrelease>\EndIncludeInRelease
% \end{macrocode}
%
@@ -6435,13 +6447,60 @@
%<latexrelease>\cs_new_protected:Npn \@@_preamble_hook:n #1
%<latexrelease> { \@@_initialize_hook_code:n {#1} }
%<latexrelease>\cs_new_eq:NN \@@_use_end: \cs_end:
-%<latexrelease>\cs_new:Npn \hook_use:nw #1 { }
+%<latexrelease>\cs_new:Npn \hook_use:nnw #1 { }
%<latexrelease>\EndIncludeInRelease
% \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
+%
+%
+% \begin{macro}{\hook_use:nnw}
+% \begin{macro}[EXP]{\@@_use_initialized:nnw}
+%<latexrelease>\IncludeInRelease{2023/06/01}{\hook_use:nnw}
+%<latexrelease> {Hooks~with~args}
+\cs_new_protected:Npn \hook_use:nnw #1
+ {
+ \@@_preamble_hook:n {#1}
+ \@@_use_initialized:nnw {#1}
+ }
+\cs_new:Npn \@@_use_initialized:nnw #1 #2
+ {
+ \cs:w
+ \if_cs_exist:w @@~#1 \cs_end:
+ @@~#1
+ \else:
+ use_none: \prg_replicate:nn {#2} { n }
+ \fi:
+ \cs_end:
+ }
+%<latexrelease>\EndIncludeInRelease
+%<latexrelease>\IncludeInRelease{2020/10/01}{\hook_use:nnw}
+%<latexrelease> {Hooks~with~args}
+%<latexrelease>\cs_gset:Npn \hook_use:nnw #1 #2
+%<latexrelease> { \use:c { use_none: \prg_replicate:nn {#2} { n } } }
+%<latexrelease>\EndIncludeInRelease
% \end{macro}
+% \end{macro}
+%
+%
+% \begin{macro}{\@@_post_initialization_defs:}
+%<latexrelease>\IncludeInRelease{2023/06/01}{\@@_post_initialization_defs:}
+%<latexrelease> {Hooks~with~args}
+\cs_new_protected:Npn \@@_post_initialization_defs:
+ {
+ \cs_gset_eq:NN \hook_use:n \@@_use_initialized:n
+ \cs_gset_eq:NN \hook_use:nnw \@@_use_initialized:nnw
+ \cs_gset_eq:NN \@@_preamble_hook:n \use_none:n
+ \cs_gset_eq:NN \@@_post_initialization_defs: \prg_do_nothing:
+ }
+%<latexrelease>\EndIncludeInRelease
+%<latexrelease>\IncludeInRelease{2020/10/01}{\@@_post_initialization_defs:}
+%<latexrelease> {Hooks~with~args}
+%<latexrelease>\cs_undefine:N \@@_post_initialization_defs:
+%<latexrelease>\EndIncludeInRelease
+% \end{macro}
+%
%
% \begin{macro}[EXP]{\@@_use:wn}
% \begin{macro}{\@@_try_file_hook:n,\@@_if_usable_use:n}
@@ -6498,7 +6557,7 @@
% \end{macro}
% \end{macro}
%
-% \begin{macro}{\hook_use_once:n,\hook_use_once:nw}
+% \begin{macro}{\hook_use_once:n,\hook_use_once:nnw}
% For hooks that can and should be used only once we have a special
% use command that further inhibits the hook from getting more code
% added to it. This has the effect that any
@@ -6511,34 +6570,44 @@
%
% \changes{v1.0r}{2021/09/06}{Clean up after \cs{UseOneTimeHook} (gh/606)}
% \changes{v1.1a}{2023/04/06}
-% {Add \cs{hook_use_once:nw} (hook-args).}
+% {Add \cs{hook_use_once:nnw} (hook-args).}
% \begin{macrocode}
-%<latexrelease>\IncludeInRelease{2023/06/01}{\hook_use_once:nw}
+%<latexrelease>\IncludeInRelease{2023/06/01}{\hook_use_once:nnw}
%<latexrelease> {Hooks~with~args}
\cs_new_protected:Npn \hook_use_once:n #1
{
\@@_if_execute_immediately:nF {#1}
- { \@@_normalize_hook_args:Nn \@@_use_once:n { \use:n {#1} } }
+ { \@@_normalize_hook_args:Nn \@@_use_once:nn { \use:n {#1} } { 0 } }
+ }
+\cs_new_protected:Npn \hook_use_once:nnw #1 #2
+ {
+ \@@_if_execute_immediately:nF {#1}
+ { \@@_normalize_hook_args:Nn \@@_use_once:nn { \use:n {#1} } {#2} }
}
-\cs_new:Npn \hook_use_once:nw { \hook_use_once:n }
%<latexrelease>\EndIncludeInRelease
% \end{macrocode}
% \end{macro}
%
% \begin{macrocode}
-%<latexrelease>\IncludeInRelease{2020/10/01}{\hook_use_once:nw}
+%<latexrelease>\IncludeInRelease{2020/10/01}{\hook_use_once:nnw}
%<latexrelease> {Hooks~with~args}
-%<latexrelease>\cs_new:Npn \hook_use_once:nw #1 { }
+%<latexrelease>\cs_gset_protected:Npn \hook_use_once:n #1
+%<latexrelease> {
+%<latexrelease> \@@_if_execute_immediately:nF {#1}
+%<latexrelease> { \@@_normalize_hook_args:Nn \@@_use_once:n { \use:n {#1} } }
+%<latexrelease> }
+%<latexrelease>\cs_gset:Npn \hook_use_once:nnw #1 #2
+%<latexrelease> { \use:c { use_none: \prg_replicate:nn {#2} { n } } }
%<latexrelease>\EndIncludeInRelease
% \end{macrocode}
%
-% \begin{macro}{\@@_use_once:n}
+% \begin{macro}{\@@_use_once:nn}
% \changes{v1.1a}{2023/04/06}
% {Changes to add hook arguments (hook-args).}
% \begin{macrocode}
-%<latexrelease>\IncludeInRelease{2023/06/01}{\@@_use_once:n}
+%<latexrelease>\IncludeInRelease{2023/06/01}{\@@_use_once:nn}
%<latexrelease> {Hooks~with~args}
-\cs_new_protected:Npn \@@_use_once:n #1
+\cs_new_protected:Npn \@@_use_once:nn #1 #2
{
\@@_preamble_hook:n {#1}
\@@_use_once_set:n {#1}
@@ -6552,19 +6621,25 @@
\@@_replacing_args_false:
\@@_cs_gput_right:nnn { _next } {#1} { \@@_use_once_clear:n {#1} }
\@@_replacing_args_unset:
- \@@_use_initialized:n {#1}
+ \@@_if_usable:nTF {#1}
+ { \@@_use_initialized:n {#1} }
+ {
+ \int_compare:nNnT {#2} > { 0 }
+ { \use:c { use_none: \prg_replicate:nn {#2} { n } } }
+ }
}
%<latexrelease>\EndIncludeInRelease
%
-%<latexrelease>\IncludeInRelease{2020/10/01}{\@@_use_once:n}
+%<latexrelease>\IncludeInRelease{2020/10/01}{\@@_use_once:nn}
%<latexrelease> {Hooks~with~args}
-%<latexrelease>\cs_new_protected:Npn \@@_use_once:n #1
+%<latexrelease>\cs_gset_protected:Npn \@@_use_once:n #1
%<latexrelease> {
%<latexrelease> \@@_preamble_hook:n {#1}
%<latexrelease> \@@_use_once_set:n {#1}
%<latexrelease> \@@_use_initialized:n {#1}
%<latexrelease> \@@_use_once_clear:n {#1}
%<latexrelease> }
+%<latexrelease>\cs_undefine:N \@@_use_once:nn
%<latexrelease>\EndIncludeInRelease
% \end{macrocode}
% \end{macro}
@@ -7274,13 +7349,13 @@
%<latexrelease> {Hooks~with~args}
\cs_new:Npn \UseHook { \hook_use:n }
\cs_new:Npn \UseOneTimeHook { \hook_use_once:n }
-\cs_new:Npn \UseHookWithArguments { \hook_use:nw }
-\cs_new:Npn \UseOneTimeHookWithArguments { \hook_use_once:nw }
+\cs_new:Npn \UseHookWithArguments { \hook_use:nnw }
+\cs_new:Npn \UseOneTimeHookWithArguments { \hook_use_once:nnw }
%<latexrelease>\EndIncludeInRelease
%<latexrelease>\IncludeInRelease{2020/10/01}{\UseHookWithArguments}
%<latexrelease> {Hooks~with~args}
-%<latexrelease>\cs_new:Npn \UseHookWithArguments #1 { }
-%<latexrelease>\cs_new:Npn \UseOneTimeHookWithArguments #1 { }
+%<latexrelease>\cs_new:Npn \UseHookWithArguments #1 #2 { }
+%<latexrelease>\cs_new:Npn \UseOneTimeHookWithArguments #1 #2 { }
%<latexrelease>\EndIncludeInRelease
% \end{macrocode}
% \end{macro}
diff --git a/base/testfiles-lthooks/lthooks-033.lvt b/base/testfiles-lthooks/lthooks-033.lvt
index 79f3ee3b..22f84c5c 100644
--- a/base/testfiles-lthooks/lthooks-033.lvt
+++ b/base/testfiles-lthooks/lthooks-033.lvt
@@ -142,7 +142,7 @@
%
\ShowHook{use-once}
%
- \UseOneTimeHookWithArguments{use-once}{foo}{bar}
+ \UseOneTimeHookWithArguments{use-once}{2}{foo}{bar}
\AddToHookWithArguments{use-once}{\typeout{twice(#1,#2)}}
%
\ShowHook{use-once}
@@ -172,7 +172,7 @@
%
\ShowHook{not-declared}
%
- \UseHookWithArguments{not-declared}{foo}{bar}
+ \UseHookWithArguments{not-declared}{2}{foo}{bar}
}
%
@@ -199,7 +199,7 @@
%
\ShowHook{not-nine}
%
- \UseHookWithArguments{not-nine}{foo}2345678{bar}
+ \UseHookWithArguments{not-nine}{9}{foo}2345678{bar}
}
%
More information about the latex3-commits
mailing list.