[latex3-commits] [git/LaTeX3-latex3-latex3] master: Split hooks into document and generic versions (66777a1)
Joseph Wright
joseph.wright at morningstar2.co.uk
Thu Jun 6 21:03:52 CEST 2019
Repository : https://github.com/latex3/latex3
On branch : master
Link : https://github.com/latex3/latex3/commit/66777a10ceef6a30b1b618792e811401ff84eb41
>---------------------------------------------------------------
commit 66777a10ceef6a30b1b618792e811401ff84eb41
Author: Joseph Wright <joseph.wright at morningstar2.co.uk>
Date: Thu Jun 6 20:03:52 2019 +0100
Split hooks into document and generic versions
>---------------------------------------------------------------
66777a10ceef6a30b1b618792e811401ff84eb41
l3trial/l3hooks/l3hooks.dtx | 193 ++++++++++++++++++++++++++++++++++---------
1 file changed, 152 insertions(+), 41 deletions(-)
diff --git a/l3trial/l3hooks/l3hooks.dtx b/l3trial/l3hooks/l3hooks.dtx
index 5291d4c..b0effaf 100644
--- a/l3trial/l3hooks/l3hooks.dtx
+++ b/l3trial/l3hooks/l3hooks.dtx
@@ -54,15 +54,19 @@
%
% \section{\pkg{l3hooks} documentation}
%
-% \begin{function}[added = 2019-06-03]
-% {\hook_single_new:nn, \hook_repeated_new:nn}
+% \subsection{Standard hooks}
+%
+% Standard hooks may be used repeatedly throughout a document. They are
+% sub-divided by the module \emph{providing} the hook. These hooks may have
+% content added just to the next use of the hook or to all future uses.
+%
+% \begin{function}[added = 2019-06-06]
+% {\hook_new:nn}
% \begin{syntax}
-% \cs{hook_single_new:nn} \Arg{module} \Arg{hook}
+% \cs{hook_new:nn} \Arg{module} \Arg{hook}
% \end{syntax}
-% Creates a new \meta{hook} for the \meta{module} specified. The
-% |single| version creates a hook for a single use, and thus for
-% document-wide concepts. The |repeated| version creates a hook which
-% is persistent, and can be used multiple times.
+% Creates a new \meta{hook} for the \meta{module} specified. The hook may
+% be used repeatedly.
% \end{function}
%
% \begin{function}[added = 2019-06-03]
@@ -80,6 +84,43 @@
% \begin{syntax}
% \cs{hook_use:nn} \Arg{module} \Arg{hook}
% \end{syntax}
+% Inserts the entries in the \meta{hook} for the \meta{module} at this
+% point in the source. The |next| hook entries are inserted \emph{after}
+% those for |all|. The |next| hook is cleared before it is used, thus it
+% is possible for a |next| entry to add to the following |next| hook.
+% \end{function}
+%
+% \subsection{Document-wide hooks}
+%
+% Document-wide hooks may be used only once in a document. These are therefore
+% not divided by module but rather have their own interfaces and a single
+% namespace for all hooks. Adding to a document-wide hook after it has been used
+% will raise an error.
+%
+% \begin{function}[added = 2019-06-06]{\hook_document_new:n}
+% \begin{syntax}
+% \cs{hook_document_new:n} \Arg{hook}
+% \end{syntax}
+% Creates a new \meta{hook} for use in a document-wide context. The
+% \meta{hook} may only be used once, after which point it is disable.
+% \end{function}
+%
+% \begin{function}[added = 2019-06-06]
+% {\hook_document_gpush:nnn, \hook_document_gpush:nnnn}
+% \begin{syntax}
+% \cs{hook_document_gpush:nnn} \Arg{hook} \Arg{module} \Arg{code}
+% \cs{hook_document_gpush:nnnn} \Arg{hook} \Arg{module} \Arg{desc} \Arg{code}
+% \end{syntax}
+% Pushes an entry to the document-wide \meta{hook}.
+% \end{function}
+%
+% \begin{function}[added = 2019-06-06]{\hook_document_use:n}
+% \begin{syntax}
+% \cs{hook_document_use:n} \Arg{hook}
+% \end{syntax}
+% Inserts the document-wide \meta{hook} at the current position. After this
+% point, the \meta{hook} may not be used again, nor may any material be
+% added to it.
% \end{function}
%
% \end{documentation}
@@ -103,13 +144,12 @@
%</package>
% \end{macrocode}
%
-% \begin{macro}{\hook_repeated_new:nn, \hook_single_new:nn}
-% Hooks can be set up for a single use (for example at the start of a
-% document) or to be used repeatedly (\emph{e.g.}~at the start of every
-% use of an environment). We use the \enquote{one-off} hook structure as
-% a marker: this will always be created.
+% \subsection{Standard hooks}
+%
+% \begin{macro}{\hook_new:nn}
+% Simply create the structures at this point: nothing fancy.
% \begin{macrocode}
-\cs_new_protected:Npn \hook_repeated_new:nn #1#2
+\cs_new_protected:Npn \hook_new:nn #1#2
{
\cs_if_free:cTF { g_@@_next_ #1 _ #2 _seq }
{
@@ -123,18 +163,6 @@
{ hook-already-defined } {#1} {#2}
}
}
-\cs_new_protected:Npn \hook_single_new:nn #1#2
- {
- \cs_if_free:cTF { g_@@_next_ #1 _ #2 _seq }
- {
- \prop_new:c { g_@@_next_ #1 _ #2 _seq }
- \seq_new:c { g_@@_next_ #1 _ #2 _seq }
- }
- {
- \__kernel_msg_error:nnn { hooks }
- { hook-already-defined } {#1} {#2}
- }
- }
% \end{macrocode}
% \end{macro}
%
@@ -157,15 +185,8 @@
{
\seq_if_exist:cTF { g_@@_next_ #2 _ #3 _seq }
{
- \seq_if_exist:cTF { g_@@_ #1 _ #2 _ #3 _seq }
- {
- \seq_gpush:cn { g_@@_ #1 _ #2 _ #3 _seq } {#4}
- \prop_gput:cnn { g_@@_ #1 _ #2 _ #3 _prop } {#4} {#5}
- }
- {
- \__kernel_msg_error:nnn { hooks }
- { single-use-hook } {#2} {#3}
- }
+ \seq_gpush:cn { g_@@_ #1 _ #2 _ #3 _seq } {#4}
+ \prop_gput:cnn { g_@@_ #1 _ #2 _ #3 _prop } {#4} {#5}
}
{
\__kernel_msg_error:nnn { hooks }
@@ -194,8 +215,7 @@
{
\cs_set:Npn \@@_use:n ##1
{ \prop_item:cn { g_@@_all_ #1 _ #2 _prop } {##1} }
- \cs_if_free:cF { g_@@_all_ #1 _ #2 _seq }
- { \seq_map_function:cN { g_@@_all_ #1 _ #2 _seq } \@@_use:n }
+ \seq_map_function:cN { g_@@_all_ #1 _ #2 _seq } \@@_use:n
\cs_set:Npn \@@_use:n ##1
{
\exp_not:f
@@ -217,19 +237,110 @@
% \end{macro}
% \end{macro}
%
-% Messages.
+% \subsection{Document-wide hooks}
+%
+% \begin{macro}{\hook_document_new:n}
+% A simpler version of the standard set up.
% \begin{macrocode}
+\cs_new_protected:Npn \hook_document_new:n #1
+ {
+ \cs_if_free:cTF { g_@@_document_ #1 _seq }
+ {
+ \prop_new:c { g_@@_document_ #1 _seq }
+ \seq_new:c { g_@@_document_ #1 _seq }
+ \bool_new:c { g_@@_document_ #1 _bool }
+ }
+ {
+ \__kernel_msg_error:nnn { hooks }
+ { document-hook-already-defined } {#1}
+ }
+ }
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\hook_document_gpush:nnn}
+% \begin{macro}{\hook_document_gpush:nnnn}
+% \begin{macro}{\@@_document_gpush:nnn}
+% Much the same as the generic case, but with a check for the hook being
+% disabled.
+% \begin{macrocode}
+\cs_new_protected:Npn \hook_document__gpush:nnn #1#2#3
+ { \@@_document_gpush:nnn {#1} {#2} {#3} }
+\cs_new_protected:Npn \hook_document_gpush:nnnn #1#2#3#4
+ { \@@_document_gpush:nnn {#1} { #2 - #3 } {#4} }
+\cs_new_protected:Npn \@@_document_gpush:nnn #1#2#3
+ {
+ \seq_if_exist:cTF { g_@@_document_ #1 _seq }
+ {
+ \bool_if:cTF { g_@@_document_ #1 _bool }
+ {
+ \seq_gpush:cn { g_@@_document_ #1 _seq } {#2}
+ \prop_gput:cnn { g_@@_document_ #1 _prop } {#2} {#3}
+ }
+ }
+ {
+ \__kernel_msg_error:nnn { hooks }
+ { unknown-document-hook } {#1}
+ }
+ }
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\hook_document_use:n}
+% As this can only fire once, we have to check for it being disabled.
+% \begin{macrocode}
+\cs_new_protected:Npn \hook_docment_use:n #1
+ {
+ \cs_if_free:cTF { g_@@_document_ #1 _seq }
+ {
+ \__kernel_msg_error:nnn { hooks }
+ { unknown-document-hook } {#1}
+ }
+ {
+ \bool_if:cTF { g_@@_document_ #1 _bool }
+ {
+ \bool_gset_true:c { g_@@_document_ #1 _bool }
+ \cs_set:Npn \@@_use:n ##1
+ { \prop_item:cn { g_@@_document_ #1 _prop } {##1} }
+ \seq_map_function:cN { g_@@_document_ #1 _seq } \@@_use:n
+ }
+ {
+ \__kernel_msg_error:nnn { hooks }
+ { document-hook-used } {#1} { use }
+ }
+ }
+ }
+% \end{macrocode}
+% \end{macro}
+%
+% \subsection{Messages}
+%
+% \begin{macrocode}
+\__kernel_msg_new:nnnn { hooks } { document-hook-already-defined }
+ { Hook~'#1'~already~defined. }
+ {
+ LaTeX~has~been~asked~to~create~a~new~document-wide~hook~'#1'~
+ but~this~name~has~already~been~used~elsewhere.
+ }
\__kernel_msg_new:nnnn { hooks } { hook-already-defined }
{ Hook~'#1/#2'~already~defined. }
{
LaTeX~has~been~asked~to~create~a~new~hook~'#2'~for~module~'#1'~
but~this~name~has~already~been~used~elsewhere.
}
-\__kernel_msg_new:nnnn { hooks } { single-use-hook }
- { Hook~'#1/#2'~is~single~use~only. }
+\__kernel_msg_new:nnnn { hooks } { document-hook-used }
+ { Document~hook~'#1'~has~already~been~used. }
{
- LaTeX~has~been~asked~add~content~to~all~uses~of~hook~'#2'~for module~'#1'~
- but~this~hook~is~only~every~used~once.
+ LaTeX~has~been~asked~to~ #2 ~document-wide~hook~'#1'~
+ but~this~hook~has~already~been~used.
+ }
+\__kernel_msg_new:nnnn { hooks } { unknown-document-hook }
+ { Unknown~document-wide~hook~'#1'. }
+ {
+ LaTeX~has~been~asked~insert~a~document-wide~hook~'#1'~
+ but~this~name~has~not~been~defined.
}
\__kernel_msg_new:nnnn { hooks } { unknown-hook }
{ Unknown~hook~'#1/#2'. }
More information about the latex3-commits
mailing list