diff options
Diffstat (limited to 'Doc/Zsh/options.yo')
| -rw-r--r-- | Doc/Zsh/options.yo | 118 |
1 files changed, 75 insertions, 43 deletions
diff --git a/Doc/Zsh/options.yo b/Doc/Zsh/options.yo index cf4600769..c3af8dd33 100644 --- a/Doc/Zsh/options.yo +++ b/Doc/Zsh/options.yo @@ -41,6 +41,9 @@ will be treated just as `tt(-f)', but the string `tt(-f i)' is an error. This is because many systems which implement the `tt(#!)' mechanism for calling scripts do not strip trailing whitespace. +It is possible for options to be set within a function scope. See the +description of the option tt(LOCAL_OPTIONS) below. + texinode(Description of Options)(Option Aliases)(Specifying Options)(Options) sect(Description of Options) cindex(options, description) @@ -1211,6 +1214,9 @@ Note that, when the tt(HASH_LIST_ALL) option is not set or when some directories in the path are not readable, this may falsely report spelling errors the first time some commands are used. +Refer to the shell variable tt(SPROMPT) for an explanation of the +`tt([nyae])' (no/yes/abort/edit) prompt that is offered. + The shell variable tt(CORRECT_IGNORE) may be set to a pattern to match words that will never be offered as corrections. ) @@ -1219,7 +1225,10 @@ pindex(NO_CORRECT_ALL) pindex(CORRECTALL) pindex(NOCORRECTALL) item(tt(CORRECT_ALL) (tt(-O)))( -Try to correct the spelling of all arguments in a line. +Try to correct the spelling of all arguments in a line, in order from +left to right, treating each as a file name. Answering `tt(a)' or +`tt(e)' at any prompt stops all corrections, otherwise every correction +is prompted for. The shell variable tt(CORRECT_IGNORE_FILE) may be set to a pattern to match file names that will never be offered as corrections. @@ -1720,27 +1729,38 @@ pindex(NOERREXIT) cindex(exit status, trapping) item(tt(ERR_EXIT) (tt(-e), ksh: tt(-e)))( If a command has a non-zero exit status, execute the tt(ZERR) -trap, if set, and exit. This is disabled while running initialization -scripts. - -The behaviour is also disabled inside tt(DEBUG) traps. In this -case the option is handled specially: it is unset on entry to -the trap. If the option tt(DEBUG_BEFORE_CMD) is set, -as it is by default, and the option tt(ERR_EXIT) is found to have been set -on exit, then the command for which the tt(DEBUG) trap is being executed is -skipped. The option is restored after the trap exits. - -Non-zero status in a command list containing tt(&&) or tt(||) is ignored -for commands not at the end of the list. Hence - -example(false && true) - -does not trigger exit. +trap, if set, and exit. + +The option is ignored when executing the commands following tt(while), +tt(until), tt(if), or tt(elif), a pipeline beginning with tt(!), or +any command other than the last in command list containing tt(&&) or +tt(||). Hence neither `tt(if foo; then true; fi)', nor `tt(foo && +true)' trigger exit when tt(foo) returns with a non-zero exit status. +Note that if tt(foo) is a function, the option is also ignored during +its whole execution. + +The option is also ignored when executing a complex command (tt(if), +tt(for), tt(while), tt(until), tt(repeat), tt(case), tt(select), +tt(always), or a list in braces) if its exit status comes from a +command executed while the option is ignored. Hence, the tt(if) +command in `tt(if true; then false && true; fi)' does not trigger +exit. + +Finally, the option is also ignored while running initialization +scripts and inside tt(DEBUG) traps. In the latter case, the option is +handled specially: it is unset on entry to the trap. If the option +tt(DEBUG_BEFORE_CMD) is set, as it is by default, and the option +tt(ERR_EXIT) is found to have been set on exit, then the command for +which the tt(DEBUG) trap is being executed is skipped. The option is +restored after the trap exits. Exiting due to tt(ERR_EXIT) has certain interactions with asynchronous jobs noted in ifzman(the section JOBS in zmanref(zshmisc))\ ifnzman(noderef(Jobs & Signals)). + +Note this behaviour is not disabled in interactive shells --- +a non-zero status on the command line causes the shell to exit. ) pindex(ERR_RETURN) pindex(NO_ERR_RETURN) @@ -1749,26 +1769,29 @@ pindex(NOERRRETURN) cindex(function return, on error) cindex(return from function, on error) item(tt(ERR_RETURN))( -If a command has a non-zero exit status, return immediately from the -enclosing function. The logic is similar to that for tt(ERR_EXIT), -except that an implicit tt(return) statement is executed instead of an -tt(exit). This will trigger an exit at the outermost level of a -non-interactive script. - -Normally this option inherits the behaviour of tt(ERR_EXIT) that -code followed by `tt(&&)' `tt(||)' does not trigger a return. Hence -in the following: - -example(summit || true) -no return is forced as the combined effect always has a zero return -status. - -Note. however, that if tt(summit) in the above example is itself a -function, code inside it is considered separately: it may force a return -from tt(summit) (assuming the option remains set within tt(summit)), but -not from the enclosing context. This behaviour is different from -tt(ERR_EXIT) which is unaffected by function scope. +If a command has a non-zero exit status, return immediately from the +enclosing function. Except as explained below, an implicit tt(return) +statement is executed following the same logic described for +tt(ERR_EXIT). This will trigger an exit at the outermost level of a +non-interactive script. At the top level of an interactive shell, it +will trigger a return to the command prompt; in other words, the +sequence of commands typed by the user may be thought of as a function +for this purpose. + +Unlike for tt(ERR_EXIT), when a function is called while the option is +being ignored, the option is NOT ignored during the execution of the +function. Hence, if tt(foo) in `tt(foo && true)' is a function, code +inside it is considered separately: it may force a return from tt(foo) +(assuming the option remains set within tt(foo)). + +Like for tt(ERR_EXIT), the option is ignored inside tt(DEBUG) traps +but it's not unset on entry to the trap and setting or unsetting it +inside the trap has no special effect. + +If tt(ERR_RETURN) and tt(ERR_EXIT) are both set, it may happen that +both exit and return should be triggered. In that case only exit is +triggered. ) pindex(EVAL_LINENO) pindex(NO_EVAL_LINENO) @@ -1881,6 +1904,11 @@ fn2)var(...)tt(LPAR()RPAR())'; if the option is not set, this causes a parse error. Definition of multiple functions with the tt(function) keyword is always allowed. Multiple function definitions are not often used and can cause obscure errors. + +Note that no error is raised if multiple functions are defined as a +result of a set of names that were originally read as a single word on +the command line, for example `tt(TRAP{INT,QUIT})'. Although there are +no plans to change this behaviour at present, it is not guaranteed. ) pindex(MULTIOS) pindex(NO_MULTIOS) @@ -1949,7 +1977,7 @@ pindex(NOTYPESETTOUNSET) item(tt(TYPESET_TO_UNSET) <K> <S>)( When declaring a new parameter with any of the `tt(typeset)' family of related commands, the parameter remains unset unless and until a -value is explicity assigned to it, either in the `tt(typeset)' command +value is explicitly assigned to it, either in the `tt(typeset)' command itself or as a later assignment statement. ) pindex(VERBOSE) @@ -2542,10 +2570,12 @@ pindex(NO_EMACS) pindex(NOEMACS) item(tt(EMACS))( If ZLE is loaded, turning on this option has the equivalent effect -of `tt(bindkey -e)'. In addition, the VI option is unset. +of `tt(bindkey -e)'. In addition, the tt(VI) option is unset. Turning it off has no effect. The option setting is -not guaranteed to reflect the current keymap. This option is -provided for compatibility; tt(bindkey) is the recommended interface. +not guaranteed to reflect the current keymap, and the tt(LOCALOPTIONS) +option does not work correctly. This option is provided only for +compatibility, and its use is highly discouraged. tt(bindkey) is the +recommended interface. ) pindex(OVERSTRIKE) pindex(NO_OVERSTRIKE) @@ -2574,10 +2604,12 @@ pindex(NO_VI) pindex(NOVI) item(tt(VI))( If ZLE is loaded, turning on this option has the equivalent effect -of `tt(bindkey -v)'. In addition, the EMACS option is unset. +of `tt(bindkey -v)'. In addition, the tt(EMACS) option is unset. Turning it off has no effect. The option setting is -not guaranteed to reflect the current keymap. This option is -provided for compatibility; tt(bindkey) is the recommended interface. +not guaranteed to reflect the current keymap, and the tt(LOCALOPTIONS) +option does not work correctly. This option is provided only for +compatibility, and its use is highly discouraged. tt(bindkey) is the +recommended interface. ) pindex(ZLE) pindex(NO_ZLE) |