[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.