using hooks with insufficient arguments

[jlaurens]

Brief outline of the enhancement

lthooks-doc.pdf reads at page 20

To use a

hook with arguments, just write \UseHookWithArguments{⟨hook⟩}{⟨number⟩} [...] Behaviour is unpredictable6 if too few arguments are provided. If the hook isn’t declared, ⟨number⟩ arguments are removed from the input stream.

The 6 footnote reads

The hook will take the declared number of arguments, and what will happen depends on what was grabbed, and what the hook code does with its arguments.

This can cause problems when the number of arguments of a hook changes through versions (as suggested twice on pages 21 of the doc), even if it is well documented.

Next suggestion makes things more predictable when too few arguments are provided. Considering

\NewHookWithArguments{foo}{⟨n+k⟩}
\UseHookWithArguments{foo}{⟨n⟩}{⟨arg_{1}⟩}…{⟨arg_{⟨n⟩}⟩}

\UseHookWithArguments can replace the missing ⟨arg_{⟨n+1⟩}⟩ to ⟨arg_{⟨n+k⟩}⟩ with a predefined value. Then hook code can test for this special argument:

\AddToHookWithArguments{foo}{
  \IfHookValueTF{#⟨i⟩}
    {⟨do something with argument number ⟨i⟩⟩}
    {⟨do something else with a default value⟩}
}

\IfHookValue(TF) would be similar to \IfValue(TF).

Consequence

Actually, the number of arguments of a hook must be declared before use. In fact the real number of necessary arguments only depends on the various code chunks of the hook. So, taking always 9 arguments makes life easier, because anyways

Thus it is important that package writers explicitly document how many arguments (if any) each hook can take, so users of those packages know how many arguments can be referenced, and equally important, what each argument means.

as emphasized by the documentation (bottom of page 21).

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity.

[josephwright]

This is simply how TeX works: argument numbers have to be known/correct to get the right outputs in an efficient way.