From f0742aeaa5ca28ca9680735f2b540c7f8da10df5 Mon Sep 17 00:00:00 2001 From: Wayne Davison Date: Fri, 21 May 2004 20:04:59 +0000 Subject: Document the new -a option to `fc -p' and improved the documentation for the history push/pop in other ways. --- Doc/Zsh/builtins.yo | 36 +++++++++++++++++++++++++----------- 1 file changed, 25 insertions(+), 11 deletions(-) (limited to 'Doc/Zsh') diff --git a/Doc/Zsh/builtins.yo b/Doc/Zsh/builtins.yo index f9d1a5de1..0b3ca9b6c 100644 --- a/Doc/Zsh/builtins.yo +++ b/Doc/Zsh/builtins.yo @@ -397,7 +397,7 @@ findex(fc) cindex(history, editing) cindex(editing history) xitem(tt(fc) [ tt(-e) var(ename) ] [ tt(-nlrdDfEim) ] [ var(old)tt(=)var(new) ... ] [ var(first) [ var(last) ] ]) -xitem(tt(fc) tt(-p) [ var(filename) [ var(histsize) [ var(savehistsize) ] ] ]) +xitem(tt(fc) tt(-p) [ tt(-a) ] [ var(filename) [ var(histsize) [ var(savehistsize) ] ] ]) xitem(tt(fc) tt(-P)) item(tt(fc) tt(-ARWI) [ var(filename) ])( Select a range of commands from var(first) to var(last) from the @@ -439,18 +439,32 @@ cindex(history, stack) cindex(stack, history) `tt(fc -p)' pushes the current history list onto a stack and switches to a -new history list. If no arguments are specified, the history list is -empty, tt($HISTFILE) is unset, and tt($HISTSIZE) & tt($SAVEHIST) are set to -their default values. If one argument is given, tt($HISTFILE) is set to -the filename, tt($HISTSIZE) & tt($SAVEHIST) are left unchanged, and the -history file is read in (if it exists) to initialize the new history list. -If a second argument is specified, tt($HISTSIZE) & tt($SAVEHIST) are -instead set to the specified numeric value. Finally, if a third argument -is specified, tt($SAVEHIST) is set to a separate value from tt($HISTSIZE). +new history list. If the tt(-a) option is also specified, this history list +will be automatically popped when the current function scope is exited, which +is a much better solution than creating a trap function to call `tt(fc -P)' +manually. If no arguments are specified, the history list is left empty, +tt($HISTFILE) is unset, and tt($HISTSIZE) & tt($SAVEHIST) are set to their +default values. If one argument is given, tt($HISTFILE) is set to that +filename, tt($HISTSIZE) & tt($SAVEHIST) are left unchanged, and the history +file is read in (if it exists) to initialize the new list. If a second +argument is specified, tt($HISTSIZE) & tt($SAVEHIST) are instead set to the +single specified numeric value. Finally, if a third argument is specified, +tt($SAVEHIST) is set to a separate value from tt($HISTSIZE). You are free to +change these environment values for the new history list however you desire +in order to manipulate the new history list. `tt(fc -P)' pops the history list back to an older list saved by `tt(fc -p)'. -The current list is saved to its tt($HISTFILE) before it is destroyed (as long -as tt($HISTFILE) and tt($SAVEHIST) are set appropriately, of course). +The current list is saved to its tt($HISTFILE) before it is destroyed +(assuming that tt($HISTFILE) and tt($SAVEHIST) are set appropriately, of +course). The values of tt($HISTFILE), tt($HISTSIZE), and tt($SAVEHIST) are +restored to the values they had when `tt(fc -p)' was called. Note that this +restoration can conflict with making these variables "local", so your best +bet is to avoid local declarations for these variables in functions that use +`tt(fc -p)'. The one other guaranteed-safe combination is declaring these +variables to be local at the top of your function and using the automatic +option (tt(-a)) with `tt(fc -p)'. Finally, note that it is legal to manually +pop a push marked for automatic popping if you need to do so before the +function exits. cindex(history, file) cindex(file, history) -- cgit 1.4.1