Clarify zshaddhistory doc?

Clarify zshaddhistory doc?

[Bart Schaefer]

Under the entry for zshaddhistory:

     If any of the hook functions return a non-zero value the history
     line will not be saved, although it lingers in the history until
     the next line is executed allow you to reuse or edit it
     immediately.

What exactly does this mean?  There's no $zshaddhistory_functions array
so "any of the hook functions" is either a typo, or must refer to the
$preexec_functions hooks, which ought to be clearer.

Re: Clarify zshaddhistory doc?

[Peter Stephenson]

Bart Schaefer wrote:
> Under the entry for zshaddhistory:
> 
>      If any of the hook functions return a non-zero value the history
>      line will not be saved, although it lingers in the history until
>      the next line is executed allow you to reuse or edit it
>      immediately.
> 
> What exactly does this mean?  There's no $zshaddhistory_functions array
> so "any of the hook functions" is either a typo, or must refer to the
> $preexec_functions hooks, which ought to be clearer.

There isn't a zshaddhistory_functions array until you add one, then
there is.

Index: Doc/Zsh/func.yo
===================================================================
RCS file: /cvsroot/zsh/zsh/Doc/Zsh/func.yo,v
retrieving revision 1.23
diff -u -r1.23 func.yo
--- Doc/Zsh/func.yo	5 Sep 2008 09:05:23 -0000	1.23
+++ Doc/Zsh/func.yo	18 Feb 2009 17:07:35 -0000
@@ -189,19 +189,23 @@
 sect(Special Functions)
 Certain functions, if defined, have special meaning to the shell.
 
-In the case of tt(chpwd), tt(periodic), tt(precmd) and tt(preexec) it is
-possible to define an array that has the same name with `tt(_functions)'
-appended.  Any element in such an array is taken as the name of a function
-to execute; it is executed in the same context and with the same arguments
-as the basic function.  For example, if tt($chpwd_functions) is an array
-containing the values `tt(mychpwd)', `tt(chpwd_save_dirstack)', then the
-shell attempts to execute the functions `tt(chpwd)', `tt(mychpwd)' and
+subsect(Hook Functions)
+findex(functions, hook)
+findex(hook functions)
+
+For the functions below, it is possible to define an array that has the
+same name as the function with `tt(_functions)' appended.  Any element in
+such an array is taken as the name of a function to execute; it is executed
+in the same context and with the same arguments as the basic function.  For
+example, if tt($chpwd_functions) is an array containing the values
+`tt(mychpwd)', `tt(chpwd_save_dirstack)', then the shell attempts to
+execute the functions `tt(chpwd)', `tt(mychpwd)' and
 `tt(chpwd_save_dirstack)', in that order.  Any function that does not exist
 is silently ignored.  A function found by this mechanism is referred to
-elsewhere as a `hook function'.  An error in any function causes
-subsequent functions not to be run.  Note further that an error
-in a tt(precmd) hook causes an immediately following tt(periodic)
-function not to run (thought it may run at the next opportunity).
+elsewhere as a `hook function'.  An error in any function causes subsequent
+functions not to be run.  Note further that an error in a tt(precmd) hook
+causes an immediately following tt(periodic) function not to run (thought
+it may run at the next opportunity).
 
 startitem()
 findex(chpwd)
@@ -277,6 +281,14 @@
 precommand modifier is used before an external command.  Also, unlike
 tt(TRAPEXIT), it is not called when functions exit.
 )
+enditem()
+
+subsect(Trap Functions)
+
+The functions below are treated specially but do not have corresponding
+hook arrays.
+
+startitem()
 item(tt(TRAP)var(NAL))(
 cindex(signals, trapping)
 cindex(trapping signals)



-- 
Peter Stephenson <pws@csr.com>                  Software Engineer
CSR PLC, Churchill House, Cambridge Business Park, Cowley Road
Cambridge, CB4 0WZ, UK                          Tel: +44 (0)1223 692070

Re: Clarify zshaddhistory doc?

[Mikael Magnusson]

2009/2/18 Peter Stephenson <pws@csr.com>:
> Index: Doc/Zsh/func.yo
> ===================================================================
> RCS file: /cvsroot/zsh/zsh/Doc/Zsh/func.yo,v
> retrieving revision 1.23
> diff -u -r1.23 func.yo
> --- Doc/Zsh/func.yo     5 Sep 2008 09:05:23 -0000       1.23
> +++ Doc/Zsh/func.yo     18 Feb 2009 17:07:35 -0000
> @@ -189,19 +189,23 @@
>  sect(Special Functions)
>  Certain functions, if defined, have special meaning to the shell.
>
> -In the case of tt(chpwd), tt(periodic), tt(precmd) and tt(preexec) it is
> -possible to define an array that has the same name with `tt(_functions)'
> -appended.  Any element in such an array is taken as the name of a function
> -to execute; it is executed in the same context and with the same arguments
> -as the basic function.  For example, if tt($chpwd_functions) is an array
> -containing the values `tt(mychpwd)', `tt(chpwd_save_dirstack)', then the
> -shell attempts to execute the functions `tt(chpwd)', `tt(mychpwd)' and
> +subsect(Hook Functions)
> +findex(functions, hook)
> +findex(hook functions)
> +
> +For the functions below, it is possible to define an array that has the
> +same name as the function with `tt(_functions)' appended.  Any element in
> +such an array is taken as the name of a function to execute; it is executed
> +in the same context and with the same arguments as the basic function.  For
> +example, if tt($chpwd_functions) is an array containing the values
> +`tt(mychpwd)', `tt(chpwd_save_dirstack)', then the shell attempts to
> +execute the functions `tt(chpwd)', `tt(mychpwd)' and
>  `tt(chpwd_save_dirstack)', in that order.  Any function that does not exist
>  is silently ignored.  A function found by this mechanism is referred to
> -elsewhere as a `hook function'.  An error in any function causes
> -subsequent functions not to be run.  Note further that an error
> -in a tt(precmd) hook causes an immediately following tt(periodic)
> -function not to run (thought it may run at the next opportunity).
> +elsewhere as a `hook function'.  An error in any function causes subsequent
> +functions not to be run.  Note further that an error in a tt(precmd) hook
> +causes an immediately following tt(periodic) function not to run (thought
> +it may run at the next opportunity).

Driveby typo fix, thought -> though.


-- 
Mikael Magnusson

Re: Clarify zshaddhistory doc?

[Bart Schaefer]

On Feb 18,  5:09pm, Peter Stephenson wrote:
}
} > What exactly does this mean?  There's no $zshaddhistory_functions array
} > so "any of the hook functions" is either a typo, or must refer to the
} > $preexec_functions hooks, which ought to be clearer.
} 
} There isn't a zshaddhistory_functions array until you add one, then
} there is.

Hrm.  Well, then, perhaps the explicit reference to "preexec_functions"
in Src/init.c is wrong, and it should be using the HOOK_SUFFIX constant?

Re: Clarify zshaddhistory doc?

[Peter Stephenson]

On Wed, 18 Feb 2009 10:39:39 -0800
Bart Schaefer <schaefer@brasslantern.com> wrote:
> On Feb 18,  5:09pm, Peter Stephenson wrote:
> }
> } > What exactly does this mean?  There's no $zshaddhistory_functions array
> } > so "any of the hook functions" is either a typo, or must refer to the
> } > $preexec_functions hooks, which ought to be clearer.
> } 
> } There isn't a zshaddhistory_functions array until you add one, then
> } there is.
> 
> Hrm.  Well, then, perhaps the explicit reference to "preexec_functions"
> in Src/init.c is wrong, and it should be using the HOOK_SUFFIX constant?

Index: Src/init.c
===================================================================
RCS file: /cvsroot/zsh/zsh/Src/init.c,v
retrieving revision 1.98
diff -u -r1.98 init.c
--- Src/init.c	11 Feb 2009 20:42:16 -0000	1.98
+++ Src/init.c	19 Feb 2009 09:57:52 -0000
@@ -150,7 +150,7 @@
 
 	    if (toplevel &&
 		(getshfunc("preexec") ||
-		 paramtab->getnode(paramtab, "preexec_functions"))) {
+		 paramtab->getnode(paramtab, "preexec" HOOK_SUFFIX))) {
 		LinkList args;
 		char *cmdstr;
 
Index: Src/utils.c
===================================================================
RCS file: /cvsroot/zsh/zsh/Src/utils.c,v
retrieving revision 1.208
diff -u -r1.208 utils.c
--- Src/utils.c	5 Jan 2009 21:56:53 -0000	1.208
+++ Src/utils.c	19 Feb 2009 09:57:52 -0000
@@ -1174,8 +1174,6 @@
     if (arrayp) {
 	char **arrptr;
 	int namlen = strlen(name);
-#define HOOK_SUFFIX	"_functions"
-#define HOOK_SUFFIX_LEN	11	/* including NUL byte */
 	VARARR(char, arrnam, namlen + HOOK_SUFFIX_LEN);
 	memcpy(arrnam, name, namlen);
 	memcpy(arrnam + namlen, HOOK_SUFFIX, HOOK_SUFFIX_LEN);
Index: Src/zsh.h
===================================================================
RCS file: /cvsroot/zsh/zsh/Src/zsh.h,v
retrieving revision 1.152
diff -u -r1.152 zsh.h
--- Src/zsh.h	11 Feb 2009 20:42:16 -0000	1.152
+++ Src/zsh.h	19 Feb 2009 09:57:52 -0000
@@ -1117,6 +1117,15 @@
 #define WRAPDEF(func) \
     { NULL, 0, func, NULL }
 
+/*
+ * User-defined hook arrays
+ */
+
+/* Name appended to function name to get hook array */
+#define HOOK_SUFFIX	"_functions"
+/* Length of that including NUL byte */
+#define HOOK_SUFFIX_LEN	11
+
 /* node in builtin command hash table (builtintab) */
 
 /*



-- 
Peter Stephenson <pws@csr.com>                  Software Engineer
CSR PLC, Churchill House, Cambridge Business Park, Cowley Road
Cambridge, CB4 0WZ, UK                          Tel: +44 (0)1223 692070