diff options
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/META-FAQ.yo | 1 | ||||
| -rw-r--r-- | Doc/Makefile.in | 2 | ||||
| -rw-r--r-- | Doc/Zsh/arith.yo | 12 | ||||
| -rw-r--r-- | Doc/Zsh/builtins.yo | 230 | ||||
| -rw-r--r-- | Doc/Zsh/calsys.yo | 35 | ||||
| -rw-r--r-- | Doc/Zsh/compsys.yo | 100 | ||||
| -rw-r--r-- | Doc/Zsh/contrib.yo | 143 | ||||
| -rw-r--r-- | Doc/Zsh/expn.yo | 22 | ||||
| -rw-r--r-- | Doc/Zsh/ftp_sites.yo | 14 | ||||
| -rw-r--r-- | Doc/Zsh/func.yo | 8 | ||||
| -rw-r--r-- | Doc/Zsh/grammar.yo | 49 | ||||
| -rw-r--r-- | Doc/Zsh/manual.yo | 9 | ||||
| -rw-r--r-- | Doc/Zsh/metafaq.yo | 18 | ||||
| -rw-r--r-- | Doc/Zsh/mod_datetime.yo | 55 | ||||
| -rw-r--r-- | Doc/Zsh/mod_db_gdbm.yo | 51 | ||||
| -rw-r--r-- | Doc/Zsh/mod_files.yo | 5 | ||||
| -rw-r--r-- | Doc/Zsh/mod_system.yo | 3 | ||||
| -rw-r--r-- | Doc/Zsh/options.yo | 51 | ||||
| -rw-r--r-- | Doc/Zsh/params.yo | 210 | ||||
| -rw-r--r-- | Doc/Zsh/prompt.yo | 11 | ||||
| -rw-r--r-- | Doc/Zsh/roadmap.yo | 6 | ||||
| -rw-r--r-- | Doc/Zsh/zle.yo | 221 | ||||
| -rw-r--r-- | Doc/zman.yo | 1 | ||||
| -rw-r--r-- | Doc/ztexi.yo | 1 |
24 files changed, 943 insertions, 315 deletions
diff --git a/Doc/META-FAQ.yo b/Doc/META-FAQ.yo index bfdb76b77..992844ec1 100644 --- a/Doc/META-FAQ.yo +++ b/Doc/META-FAQ.yo @@ -19,6 +19,7 @@ ARG1 def(em)(1)(ARG1) def(bf)(1)(ARG1) def(tt)(1)(ARG1) +def(uref)(1)(ARG1) def(var)(1)(ARG1) def(nofill)(1)(ARG1) diff --git a/Doc/Makefile.in b/Doc/Makefile.in index 41af4a33e..a420781ee 100644 --- a/Doc/Makefile.in +++ b/Doc/Makefile.in @@ -60,7 +60,7 @@ MODDOCSRC = \ Zsh/mod_attr.yo Zsh/mod_cap.yo Zsh/mod_clone.yo \ Zsh/mod_compctl.yo Zsh/mod_complete.yo Zsh/mod_complist.yo \ Zsh/mod_computil.yo Zsh/mod_curses.yo \ -Zsh/mod_datetime.yo Zsh/mod_deltochar.yo \ +Zsh/mod_datetime.yo Zsh/mod_db_gdbm.yo Zsh/mod_deltochar.yo \ Zsh/mod_example.yo Zsh/mod_files.yo Zsh/mod_langinfo.yo \ Zsh/mod_mapfile.yo Zsh/mod_mathfunc.yo Zsh/mod_newuser.yo \ Zsh/mod_parameter.yo Zsh/mod_pcre.yo Zsh/mod_regex.yo \ diff --git a/Doc/Zsh/arith.yo b/Doc/Zsh/arith.yo index 96dc2dc68..5c334ce9c 100644 --- a/Doc/Zsh/arith.yo +++ b/Doc/Zsh/arith.yo @@ -39,7 +39,8 @@ zero status. cindex(arithmetic base) cindex(bases, in arithmetic) Integers can be in bases other than 10. -A leading `tt(0x)' or `tt(0X)' denotes hexadecimal. +A leading `tt(0x)' or `tt(0X)' denotes hexadecimal and a leading +`tt(0b)' or `tt(0B) binary. Integers may also be of the form `var(base)tt(#)var(n)', where var(base) is a decimal number between two and thirty-six representing the arithmetic base and var(n) @@ -232,6 +233,15 @@ necessary. In addition, if any operator which requires an integer equivalents with assignment) is given a floating point argument, it will be silently rounded down to the next integer. +Users should beware that, in common with many other programming +languages but not software designed for calculation, the evaluation of +an expression in zsh is taken a term at a time and promotion of integers +to floating point does not occur in terms only containing integers. A +typical result of this is that a division such as tt(6/8) is truncated, +in this being rounded down to 0. The tt(FORCE_FLOAT) shell option can +be used in scripts or functions where floating point evaluation is +required throughout. + Scalar variables can hold integer or floating point values at different times; there is no memory of the numeric type in this case. diff --git a/Doc/Zsh/builtins.yo b/Doc/Zsh/builtins.yo index 46f40cc3a..c4acf7672 100644 --- a/Doc/Zsh/builtins.yo +++ b/Doc/Zsh/builtins.yo @@ -54,13 +54,13 @@ in a group before any non-option arguments; once the first non-option argument has been found, option processing is terminated. All builtin commands other than precommand modifiers, even those that -have no options, can be given the argument `tt(--)' to terminate option +have no options, can be given the argument `tt(-)tt(-)' to terminate option processing. This indicates that the following words are non-option arguments, but is otherwise ignored. This is useful in cases where arguments to the command may begin with `tt(-)'. For historical reasons, most builtin commands also recognize a single `tt(-)' in a separate word for this purpose; note that this is less standard and -use of `tt(--) is recommended. +use of `tt(-)tt(-)' is recommended. startitem() prefix(-) @@ -142,7 +142,7 @@ ifnzman(noderef(Aliasing)). findex(autoload) cindex(functions, autoloading) cindex(autoloading functions) -item(tt(autoload) [ {tt(PLUS())|tt(-)}tt(UXkmtz) ] [ tt(-w) ] [ var(name) ... ])( +item(tt(autoload) [ {tt(PLUS())|tt(-)}tt(TUXkmtz) ] [ tt(-w) ] [ var(name) ... ])( Equivalent to tt(functions -u), with the exception of tt(-X)/tt(+X) and tt(-w). @@ -198,7 +198,7 @@ cindex(exiting loops) cindex(loops, exiting) item(tt(break) [ var(n) ])( Exit from an enclosing tt(for), tt(while), -tt(until), tt(select) or tt(repeat) loop. If var(n) +tt(until), tt(select) or tt(repeat) loop. If an arithmetic expression var(n) is specified, then break var(n) levels instead of just one. ) findex(builtin) @@ -291,7 +291,7 @@ cindex(continuing loops) item(tt(continue) [ var(n) ])( Resume the next iteration of the enclosing tt(for), tt(while), tt(until), tt(select) or -tt(repeat) loop. If var(n) is specified, break out of +tt(repeat) loop. If an arithmetic expression var(n) is specified, break out of var(n)-1 loops and resume at the var(n)th enclosing loop. ) alias(declare)(typeset) @@ -615,16 +615,21 @@ the same as if the commands had been executed directly by the shell; if there are no var(args) or they contain no commands (i.e. are an empty string or whitespace) the return status is zero. ) -item(tt(exec) [ tt(-cl) ] [ tt(-a) var(argv0) ] var(simple command))( -Replace the current shell with an external command rather than forking. +item(tt(exec) [ tt(-cl) ] [ tt(-a) var(argv0) ] [ var(command) [ var(arg) ... ]])( +Replace the current shell with an external var(command) rather than forking. With tt(-c) clear the environment; with tt(-l) prepend tt(-) to the tt(argv[0]) string of the command executed (to simulate a login shell); with tt(-a) var(argv0) set the tt(argv[0]) string of the command executed. See noderef(Precommand Modifiers). + +cindex(redirection, current shell's I/O) +If var(command) is omitted but any redirections are specified, +then the redirections will take effect in the current shell. ) findex(exit) item(tt(exit) [ var(n) ])( -Exit the shell with the exit status specified by var(n); if none +Exit the shell with the exit status specified by an arithmetic +expression var(n); if none is specified, use the exit status from the last command executed. pindex(IGNORE_EOF, use of) An EOF condition will also cause the shell to exit, unless @@ -657,6 +662,12 @@ xitem(tt( )[ var(old)tt(=)var(new) ... ] [ var(first) [ var(last) ] ]) 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) ])( +The tt(fc) command controls the interactive history mechanism. Note +that reading and writing of history options is only performed if the +shell is interactive. Usually this is detected automatically, but +it can be forced by setting the tt(interactive) option when starting the +shell. + Select a range of commands from var(first) to var(last) from the history list. The arguments var(first) and var(last) may be specified as a @@ -1088,10 +1099,13 @@ item( [ tt(-R) [ tt(-en) ]] [ var(arg) ... ])( With the `tt(-f)' option the arguments are printed as described by tt(printf). With no flags or with the flag `tt(-)', the arguments are printed on the standard output as described by tt(echo), with the following differences: -the escape sequence `tt(\M-)var(x)' metafies the character +the escape sequence `tt(\M-)var(x)' (or `tt(\M)var(x)') metafies the character var(x) (sets the highest bit), -`tt(\C-)var(x)' produces a control character (`tt(\C-@)' and `tt(\C-?)' give the -characters NUL and delete), and `tt(\E)' is a synonym for `tt(\e)'. +`tt(\C-)var(x)' (or `tt(\C)var(x)') produces a control character +(`tt(\C-@)' and `tt(\C-?)' give the characters NULL and delete), +a character code in octal is represented by `tt(\)var(NNN)' +(instead of `tt(\0)var(NNN)'), +and `tt(\E)' is a synonym for `tt(\e)'. Finally, if not in an escape sequence, `tt(\)' escapes the following character and is not printed. @@ -1294,10 +1308,10 @@ item(tt(-q))( Read only one character from the terminal and set var(name) to `tt(y)' if this character was `tt(y)' or `tt(Y)' and to `tt(n)' otherwise. With this flag set the return status is zero only if the character was -`tt(y)' or `tt(Y)'. This option may be used with a timeout; if -the read times out, or encounters end of file, status 2 is returned. -Input is read from the terminal unless one of tt(-u) -or tt(-p) is present. This option may also be used within zle widgets. +`tt(y)' or `tt(Y)'. This option may be used with a timeout (see tt(-t)); if +the read times out, or encounters end of file, status 2 is returned. Input is +read from the terminal unless one of tt(-u) or tt(-p) is present. This option +may also be used within zle widgets. ) item(tt(-k) [ var(num) ])( Read only one (or var(num)) characters. All are assigned to the first @@ -1400,7 +1414,8 @@ findex(return) cindex(functions, returning from) item(tt(return) [ var(n) ])( Causes a shell function or `tt(.)' script to return to -the invoking script with the return status specified by var(n). If var(n) +the invoking script with the return status specified by +an arithmetic expression var(n). If var(n) is omitted, the return status is that of the last command executed. @@ -1661,7 +1676,7 @@ See also the shell variable tt(STTY) for a means of initialising the tty before running external commands. ) findex(type) -item(tt(type) [ tt(-wfpams) ] var(name) ...)( +item(tt(type) [ tt(-wfpamsS) ] var(name) ...)( Equivalent to tt(whence -v). ) findex(typeset) @@ -1702,66 +1717,98 @@ newly-created parameters, or when any attribute flags listed below are given along with the var(name). Using `tt(PLUS())' instead of minus to introduce an attribute turns it off. -If the tt(-p) option is given, parameters and values are printed in the -form of a typeset command and an assignment (which will be printed -separately for arrays and associative arrays), regardless of other flags -and options. Note that the tt(-h) flag on parameters is respected; no -value will be shown for these parameters. - -If the tt(-T) option is given, two or three arguments must be present (an -exception is that zero arguments are allowed to show the list of parameters -created in this fashion). The first two are the name of a scalar and an -array parameter (in that order) that will be tied together in the manner of -tt($PATH) and tt($path). The optional third argument is a single-character -separator which will be used to join the elements of the array to form the -scalar; if absent, a colon is used, as with tt($PATH). Only the first -character of the separator is significant; any remaining characters are -ignored. Only the scalar parameter may be assigned an initial value. Both -the scalar and the array may otherwise be manipulated as normal. If one is -unset, the other will automatically be unset too. There is no way of -untying the variables without unsetting them, or converting the type of one -of them with another tt(typeset) command; tt(+T) does not work, assigning -an array to var(SCALAR) is an error, and assigning a scalar to var(array) -sets it to be a single-element array. Note that both `tt(typeset -xT ...)' -and `tt(export -T ...)' work, but only the scalar will be marked for -export. Setting the value using the scalar version causes a split on all -separators (which cannot be quoted). It is possible to use the -same two tied variables with a different separator character in which -case the variables remain joined as before but the separator is changed. -This flag has a different meaning when used with tt(-f); see below. - -The tt(-g) (global) flag is treated specially: it means that any -resulting parameter will not be restricted to local scope. Note that this -does not necessarily mean that the parameter will be global, as the flag -will apply to any existing parameter (even if unset) from an enclosing -function. This flag does not affect the parameter after creation, hence it -has no effect when listing existing parameters, nor does the flag tt(+g) -have any effect except in combination with tt(-m) (see below). - If no var(name) is present, the names and values of all parameters are printed. In this case the attribute flags restrict the display to only those parameters that have the specified attributes, and using `tt(PLUS())' rather than `tt(-)' to introduce the flag suppresses printing of the values -of parameters when there is no parameter name. Also, if the last option -is the word `tt(PLUS())', then names are printed but values are not. +of parameters when there is no parameter name. + +If no attribute flags are given, and either no var(name) arguments are +present or the flag tt(+m) is used, then each parameter name printed is +preceded by a list of the attributes of that parameter (tt(array), +tt(association), tt(exported), tt(float), tt(integer), tt(readonly), +or tt(undefined) for autoloaded parameters not yet loaded). If tt(+m) is +used with attribute flags, and all those flags are introduced with +tt(PLUS()), the matching parameter names are printed but their values +are not. + +The following control flags change the behavior of tt(typeset): +startitem() +item(tt(PLUS()))( +If `tt(PLUS())' appears by itself in a separate word as the last option, +then the names of all parameters (functions with tt(-f)) are printed, but +the values (function bodies) are not. No var(name) arguments may appear, +and it is an error for any other options to follow `tt(PLUS())'. The +effect of `tt(PLUS())' is as if all attribute flags which precede it were +given with a `tt(PLUS())' prefix. For example, `tt(typeset -U PLUS())' is +equivalent to `tt(typeset +U)' and displays the names of all arrays having +the uniqueness attribute, whereas `tt(typeset -f -U PLUS())' displays the +names of all autoloadable functions. If tt(PLUS()) is the only option, +then type information (array, readonly, etc.) is also printed for each +parameter, in the same manner as `tt(typeset +m "*")'. +) +item(tt(-g))( +The tt(-g) (global) means that any resulting parameter will not be +restricted to local scope. Note that this does not necessarily mean that +the parameter will be global, as the flag will apply to any existing +parameter (even if unset) from an enclosing function. This flag does not +affect the parameter after creation, hence it has no effect when listing +existing parameters, nor does the flag tt(+g) have any effect except in +combination with tt(-m) (see below). +) +item(tt(-m))( If the tt(-m) flag is given the var(name) arguments are taken as patterns -(which should be quoted). With no attribute flags, all parameters (or -functions with the tt(-f) flag) with matching names are printed (the shell -option tt(TYPESET_SILENT) is not used in this case). Note that tt(-m) is -ignored if no patterns are given. If the tt(+g) flag is combined with -tt(-m), a new local parameter is created for every matching parameter that -is not already local. Otherwise tt(-m) applies all other flags or -assignments to the existing parameters. Except when assignments are made -with var(name)tt(=)var(value), using tt(+m) forces the matching parameters -to be printed, even inside a function. - -If no attribute flags are given and either no tt(-m) flag is present or -the tt(+m) form was used, each parameter name printed is preceded by a -list of the attributes of that parameter (tt(array), tt(association), -tt(exported), tt(integer), tt(readonly)). If tt(+m) is used with attribute -flags, and all those flags are introduced with tt(PLUS()), the matching -parameter names are printed but their values are not. +(use quoting to prevent these from being interpreted as file patterns). +With no attribute flags, all parameters (or functions with the tt(-f) +flag) with matching names are printed (the shell option tt(TYPESET_SILENT) +is not used in this case). + +If the tt(+g) flag is combined with tt(-m), a new local parameter is +created for every matching parameter that is not already local. Otherwise +tt(-m) applies all other flags or assignments to the existing parameters. + +Except when assignments are made with var(name)tt(=)var(value), using +tt(+m) forces the matching parameters and their attributes to be printed, +even inside a function. Note that tt(-m) is ignored if no patterns are +given, so `tt(typeset -m)' displays attributes but `tt(typeset -a +m)' +does not. +) +item(tt(-p))( +If the tt(-p) option is given, parameters and values are printed in the +form of a typeset command and an assignment (which will be printed +separately for arrays and associative arrays), regardless of other flags +and options. Note that the tt(-H) flag on parameters is respected; no +value will be shown for these parameters. +) +item(tt(-T) [ var(scalar)[tt(=)var(value)] var(array) [ var(sep) ] ])( +This flag has a different meaning when used with tt(-f); see below. +Otherwise the tt(-T) option requires zero, two, or three arguments to be +present. With no arguments, the list of parameters created in this +fashion is shown. With two or three arguments, the first two are the name +of a scalar and of an array parameter (in that order) that will be tied +together in the manner of tt($PATH) and tt($path). The optional third +argument is a single-character separator which will be used to join the +elements of the array to form the scalar; if absent, a colon is used, as +with tt($PATH). Only the first character of the separator is significant; +any remaining characters are ignored. + +Only the scalar parameter may be assigned an initial value. Both the +scalar and the array may otherwise be manipulated as normal. If one is +unset, the other will automatically be unset too. There is no way of +untying the variables without unsetting them, nor of converting the type +of one of them with another tt(typeset) command; tt(+T) does not work, +assigning an array to var(scalar) is an error, and assigning a scalar to +var(array) sets it to be a single-element array. + +Note that both `tt(typeset -xT ...)' and `tt(export -T ...)' work, but +only the scalar will be marked for export. Setting the value using the +scalar version causes a split on all separators (which cannot be quoted). +It is possible to apply tt(-T) to two previously tied variables but with a +different separator character, in which case the variables remain joined +as before but the separator is changed. +) +enditem() Attribute flags that transform the final value (tt(-L), tt(-R), tt(-Z), tt(-l), tt(u)) are only applied to the expanded value at the point @@ -1892,6 +1939,13 @@ item(tt(-r))( The given var(name)s are marked readonly. Note that if var(name) is a special parameter, the readonly attribute can be turned on, but cannot then be turned off. + +If the tt(POSIX_BUILTINS) option is set, the readonly attribute is +more restrictive: unset variables can be marked readonly and cannot then +be set; furthermore, the readonly attribute cannot be removed from any +variable. Note that in zsh (unlike other shells) it is still possible +to create a local variable of the same name as this is considered a +different variable (though this variable, too, can be marked readonly). ) item(tt(-t))( Tags the named parameters. Tags have no special meaning to the shell. @@ -2059,12 +2113,33 @@ then all currently active child processes are waited for. Each var(job) can be either a job specification or the process ID of a job in the job table. The exit status from this command is that of the job waited for. + +It is possible to wait for recent processes (specified by process ID, +not by job) that were running in the background even if the process has +exited. Typically the process ID will be recorded by capturing the +value of the variable tt($!) immediately after the process has been +started. There is a limit on the number of process IDs remembered by +the shell; this is given by the value of the system configuration +parameter tt(CHILD_MAX). When this limit is reached, older process IDs +are discarded, least recently started processes first. + +Note there is no protection against the process ID wrapping, i.e. if the +wait is not executed soon enough there is a chance the process waited +for is the wrong one. A conflict implies both process IDs have been +generated by the shell, as other processes are not recorded, and that +the user is potentially interested in both, so this problem is intrinsic +to process IDs. ) findex(whence) -item(tt(whence) [ tt(-vcwfpams) ] var(name) ...)( +item(tt(whence) [ tt(-vcwfpamsS) ] var(name) ...)( For each name, indicate how it would be interpreted if used as a command name. +tt(whence) is most useful when var(name) is only the last path component +of a command, i.e. does not include a `tt(/)'; in particular, pattern +matching only succeeds if just the non-directory component of the command is +passed. + startitem() item(tt(-v))( Produce a more verbose report. @@ -2097,21 +2172,26 @@ throughout the command path. Normally only the first occurrence is printed. ) item(tt(-m))( -The arguments are taken as patterns (should be +The arguments are taken as patterns (pattern characters should be quoted), and the information is displayed for each command matching one of these patterns. ) item(tt(-s))( If a pathname contains symlinks, print the symlink-free pathname as well. ) +item(tt(-S))( +As tt(-s), but if the pathname had to be resolved by following +multiple symlinks, the intermediate steps are printed, too. The +symlink resolved at each step might be anywhere in the path. +) enditem() ) findex(where) -item(tt(where) [ tt(-wpms) ] var(name) ...)( +item(tt(where) [ tt(-wpmsS) ] var(name) ...)( Equivalent to tt(whence -ca). ) findex(which) -item(tt(which) [ tt(-wpams) ] var(name) ...)( +item(tt(which) [ tt(-wpamsS) ] var(name) ...)( Equivalent to tt(whence -c). ) findex(zcompile) diff --git a/Doc/Zsh/calsys.yo b/Doc/Zsh/calsys.yo index 0d7abbf86..6b5fe27fb 100644 --- a/Doc/Zsh/calsys.yo +++ b/Doc/Zsh/calsys.yo @@ -10,9 +10,9 @@ or future events, details of which are stored in a text file (typically tt(calendar) in the user's home directory). The version provided here includes a mechanism for alerting the user when an event is due. -In addition a function tt(age) is provided that can be used in a glob -qualifier; it allows files to be selected based on their modification -times. +In addition functions tt(age), tt(before) and tt(after) are provided +that can be used in a glob qualifier; they allow files to be selected +based on their modification times. The format of the tt(calendar) file and the dates used there in and in the tt(age) function are described first, then the functions that can @@ -122,10 +122,10 @@ enditemize() Here, square brackets indicate optional elements, possibly with alternatives. Fractions of a second are recognised but ignored. For absolute times (the normal format require by the tt(calendar) file and the -tt(age) function) a date is mandatory but a time of day is not; the time -returned is at the start of the date. One variation is allowed: if -tt(a.m.) or tt(p.m.) or one of their variants is present, an hour without a -minute is allowed, e.g. tt(3 p.m.). +tt(age), tt(before) and tt(after) functions) a date is mandatory but a +time of day is not; the time returned is at the start of the date. One +variation is allowed: if tt(a.m.) or tt(p.m.) or one of their variants +is present, an hour without a minute is allowed, e.g. tt(3 p.m.). Time zones are not handled, though if one is matched following a time specification it will be removed to allow a surrounding date to be @@ -605,8 +605,10 @@ left in a file with the suffix tt(.old). enditem() subsect(Glob qualifiers) -findex(age) +startitem() +item(tt(age))( +findex(age) The function tt(age) can be autoloaded and use separately from the calendar system, although it uses the function tt(calendar_scandate) for date formatting. It requires the tt(zsh/stat) builtin, but uses @@ -675,6 +677,23 @@ example(print *+LPAR()e-age :file1 :file2-+RPAR()) matches all files modified no earlier than tt(file1) and no later than tt(file2); precision here is to the nearest second. +) +xitem(tt(after)) +item(tt(before))( +findex(after) +findex(before) +The functions tt(after) and tt(before) are simpler versions of tt(age) +that take just one argument. The argument is parsed similarly to an +argument of tt(age); if it is not given the variable tt(AGEREF) is +consulted. As the names of the functions suggest, a file matches if its +modification time is after or before the time and date specified. If +a time only is given the date is today. + +The two following examples are therefore equivalent: +example(print *+LPAR()e-after 12:00-RPAR() +print *+LPAR()e-after today:12:00-RPAR()) +) +enditem() texinode(Calendar Styles)(Calendar Utility Functions)(Calendar System User Functions)(Calendar Function System) sect(Styles) diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo index 920b5903d..b699502ca 100644 --- a/Doc/Zsh/compsys.yo +++ b/Doc/Zsh/compsys.yo @@ -354,7 +354,7 @@ tt(all): no further completion is attempted; a string containing the substring tt(patterns): no pattern completion functions will be called; a string containing tt(default): the function for the `tt(-default-)' context will not be called, but -functions defined for commands will +functions defined for commands will be. ) kindex(-math-, completion context) item(tt(-math-))( @@ -533,21 +533,41 @@ generated. subsect(Overview) When completion is attempted somewhere on the command line the -completion system first works out the context. This takes account of a +completion system begins building the context. The context represents +everything that the shell knows about the meaning of the command line +and the significance of the cursor position. This takes account of a number of things including the command word (such as `tt(grep)' or `tt(zsh)') and options to which the current word may be an argument (such as the `tt(-o)' option to tt(zsh) which takes a shell option as an argument). -This context information is condensed into a string consisting of -multiple fields separated by colons, referred to simply as `the context' -in the remainder of the documentation. This is used to look up -em(styles), context-sensitive options that can be used to configure the -completion system. The context used for lookup may vary during the same -call to the completion system. +The context starts out very generic ("we are beginning a completion") +and becomes more specific as more is learned ("the current word is in a +position that is usually a command name" or "the current word might be a +variable name" and so on). Therefore the context will vary during the +same call to the completion system. + +This context information is condensed into a string consisting of multiple +fields separated by colons, referred to simply as `the context' in the +remainder of the documentation. Note that a user of the completion system +rarely needs to compose a context string, unless for example a new +function is being written to perform completion for a new command. What a +user may need to do is compose a em(style) pattern, which is matched +against a context when needed to look up context-sensitive options that +configure the completion system. + +The next few paragraphs explain how a context is composed within the +completion function suite. Following that is discussion of how em(styles) +are defined. Styles determine such things as how the matches are +generated, similarly to shell options but with much more control. They +are defined with the tt(zstyle) builtin command (\ +ifzman(see zmanref(zshmodules))\ +ifnzman(noderef(The zsh/zutil Module))). The context string always consists of a fixed set of fields, separated -by colons and with a leading colon before the first, in the form +by colons and with a leading colon before the first. Fields which are +not yet known are left empty, but the surrounding colons appear anyway. +The fields are always in the order tt(:completion:)var(function)tt(:)var(completer)tt(:)var(command)tt(:)var(argument)tt(:)tt(tag). These have the following meaning: startitemize() @@ -628,17 +648,13 @@ described in ifzman(the section `Bindable Commands' below)\ ifnzman(noderef(Bindable Commands)). -Styles determine such things as how the matches are generated, similarly -to shell options but with much more control. They can have any number -of strings as their value. They are defined with the tt(zstyle) builtin -command (\ -ifzman(see zmanref(zshmodules))\ -ifnzman(noderef(The zsh/zutil Module))). - When looking up styles the completion system uses full context names, -including the tag. Looking up the value of a style therefore consists -of two things: the context, which may be matched as a pattern, and the -name of the style itself, which must be given exactly. +including the tag. Looking up the value of a style therefore consists of +two things: the context, which is matched to the most specific (best +fitting) style pattern, and the name of the style itself, which must be +matched exactly. The following examples demonstrate that style patterns +may be loosely defined for styles that apply broadly, or as tightly +defined as desired for styles that apply in narrower circumstances. For example, many completion functions can generate matches in a simple and a verbose form and use the tt(verbose) style to decide @@ -661,7 +677,7 @@ completion for the tt(kill) builtin. If the style is set, the builtin lists full job texts and process command lines; otherwise it shows the bare job numbers and PIDs. To turn the style off for this use only: -example(zstyle ':completion:*:*:kill:*' verbose no) +example(zstyle ':completion:*:*:kill:*:*' verbose no) For even more control, the style can use one of the tags `tt(jobs)' or `tt(processes)'. To turn off verbose display only for jobs: @@ -688,10 +704,15 @@ as tt(menu) and tt(list-rows-first). Note that the order in which styles are em(defined) does not matter; the style mechanism uses the most specific possible match for a particular style to determine the set of values. More precisely, strings are -preferred over patterns (for example, `tt(:completion::complete:foo)' is -more specific than `tt(:completion::complete:*')), and longer patterns are +preferred over patterns (for example, `tt(:completion::complete:::foo)' is +more specific than `tt(:completion::complete:::*')), and longer patterns are preferred over shorter patterns. +A good rule of thumb is that any completion style pattern that needs to +include more than one wildcard (tt(*)) and that does not end in a tag +name, should include all six colons (tt(:)), possibly surrounding +additional wildcards. + Style names like those of tags are arbitrary and depend on the completion function. However, the following two sections list some of the most common tags and styles. @@ -1491,7 +1512,7 @@ For example, to make the tt(rm) command first complete only names of object files and then the names of all files if there is no matching object file: -example(zstyle ':completion:*:*:rm:*' file-patterns \ +example(zstyle ':completion:*:*:rm:*:*' file-patterns \ '*.o:object-files' '%p:all-files') To alter the default behaviour of file completion DASH()- offer files @@ -1643,7 +1664,7 @@ For example, to have names of builtin commands, shell functions and external commands appear in that order when completing in command position: -example(zstyle ':completion:*:*:-command-:*' group-order \ +example(zstyle ':completion:*:*:-command-:*:*' group-order \ builtins functions commands) ) kindex(groups, completion style) @@ -1839,7 +1860,7 @@ tested for all tags valid for the current completion, then the tt(default) tag. The cursor will be moved back to the previous line if this style is `true' for all types of match. Note that unlike the tt(ALWAYS_LAST_PROMPT) option this is independent of the -numeric prefix argument. +numeric argument. ) kindex(known-hosts-files) item(tt(known-hosts-files))( @@ -2029,7 +2050,7 @@ use the completers tt(_complete) and tt(_prefix) but allow case-insensitive completion only with tt(_complete): example(zstyle ':completion:*' completer _complete _prefix -zstyle ':completion:*:complete:*' matcher-list \ +zstyle ':completion:*:complete:*:*:*' matcher-list \ '' 'm:{a-zA-Z}={A-Za-z}') User-defined names, as explained for the tt(completer) style, are @@ -2040,9 +2061,9 @@ with case-insensitive matching, then correction, and finally partial-word completion: example(zstyle ':completion:*' completer _complete _correct _complete:foo -zstyle ':completion:*:complete:*' matcher-list \ +zstyle ':completion:*:complete:*:*:*' matcher-list \ '' 'm:{a-zA-Z}={A-Za-z}' -zstyle ':completion:*:foo:*' matcher-list \ +zstyle ':completion:*:foo:*:*:*' matcher-list \ 'm:{a-zA-Z}={A-Za-z} r:|[-_./]=* r:|=*') If the style is unset in any context no match specification is applied. @@ -2565,7 +2586,7 @@ an exception to this behavior.) For example: -example(zstyle ':completion:*:complete:-command-:*' tag-order \ +example(zstyle ':completion:*:complete:-command-:*:*' tag-order \ 'commands functions') specifies that completion in command position first offers @@ -2624,7 +2645,7 @@ repeat them all. For example, to make completion of function names in command position ignore all the completion functions starting with an underscore the first time completion is tried: -example(zstyle ':completion:*:*:-command-:*' tag-order \ +example(zstyle ':completion:*:*:-command-:*:*' tag-order \ 'functions:-non-comp *' functions zstyle ':completion:*:functions-non-comp' ignored-patterns '_*') @@ -2660,7 +2681,7 @@ try normal completion without any match specification and, if that generates no matches, try again with case-insensitive matching, restricting the effect to arguments of the command tt(foo): -example(zstyle ':completion:*:*:foo:*' tag-order '*' '*:-case' +example(zstyle ':completion:*:*:foo:*:*' tag-order '*' '*:-case' zstyle ':completion:*-case' matcher 'm:{a-z}={A-Z}') First, all the tags offered when completing after tt(foo) are tried using @@ -4119,7 +4140,7 @@ tt(compadd) when generating matches from the style value, or to the functions for the fields if they are called. ) findex(_describe) -item(tt(_describe) [ tt(-oO) | tt(-t) var(tag) ] var(descr) var(name1) [ var(name2) ] var(opts) ... tt(-)tt(-) ...)( +item(tt(_describe) [tt(-12JVx)] [ tt(-oO) | tt(-t) var(tag) ] var(descr) var(name1) [ var(name2) ] var(opts) ... tt(-)tt(-) ...)( This function associates completions with descriptions. Multiple groups separated by tt(-)tt(-) can be supplied, potentially with different completion options var(opts). @@ -4150,6 +4171,9 @@ tt(prefix-needed) style. With the tt(-t) option a var(tag) can be specified. The default is `tt(values)' or, if the tt(-o) option is given, `tt(options)'. +The options tt(-1), tt(-2), tt(-J), tt(-V), tt(-x) are passed to +tt(_next_label). + If selected by the tt(list-grouped) style, strings with the same description will appear together in the list. @@ -4257,12 +4281,12 @@ option `tt(-)tt(-help)'. ) findex(_guard) item(tt(_guard) [ var(options) ] var(pattern descr))( -This function is intended to be used in the var(action) for -the specifications passed to tt(_arguments) and similar functions. It -returns immediately with a non-zero return status if -the string to be completed does not match the var(pattern). If the -pattern matches, the var(descr) is displayed; the function then returns -status zero if the word to complete is not empty, non-zero otherwise. +This function displays var(descr) if var(pattern) matches the string to +be completed. It is intended to be used in the var(action) for the +specifications passed to tt(_arguments) and similar functions. + +The return status is zero if the message was displayed and the word to +complete is not empty, and non-zero otherwise. The var(pattern) may be preceded by any of the options understood by tt(compadd) that are passed down from tt(_description), namely tt(-M), diff --git a/Doc/Zsh/contrib.yo b/Doc/Zsh/contrib.yo index 8c5e66b17..24be63eb9 100644 --- a/Doc/Zsh/contrib.yo +++ b/Doc/Zsh/contrib.yo @@ -595,22 +595,22 @@ In order to do that, you may use the tt(vcs_info) function. The following VCSs are supported, showing the abbreviated name by which they are referred to within the system: startsitem() -sitem(Bazaar (tt(bzr)))(http://bazaar-vcs.org/) -sitem(Codeville (tt(cdv)))(http://codeville.org/) -sitem(Concurrent Versioning System (tt(cvs)))(http://www.nongnu.org/cvs/) -sitem(Darcs (tt(darcs)))(http://darcs.net/) -sitem(Fossil (tt(fossil)))(http://fossil-scm.org/) -sitem(Git (tt(git)))(http://git-scm.com/) -sitem(GNU arch (tt(tla)))(http://www.gnu.org/software/gnu-arch/) -sitem(Mercurial (tt(hg)))(http://mercurial.selenic.com/) -sitem(Monotone (tt(mtn)))(http://monotone.ca/) -sitem(Perforce (tt(p4)))(http://www.perforce.com/) -sitem(Subversion (tt(svn)))(http://subversion.tigris.org/) -sitem(SVK (tt(svk)))(http://svk.bestpractical.com/) +sitem(Bazaar (tt(bzr)))(uref(http://bazaar.canonical.com/)) +sitem(Codeville (tt(cdv)))(uref(http://freecode.com/projects/codeville/)) +sitem(Concurrent Versioning System (tt(cvs)))(uref(http://www.nongnu.org/cvs/)) +sitem(Darcs (tt(darcs)))(uref(http://darcs.net/)) +sitem(Fossil (tt(fossil)))(uref(http://fossil-scm.org/)) +sitem(Git (tt(git)))(uref(http://git-scm.com/)) +sitem(GNU arch (tt(tla)))(uref(http://www.gnu.org/software/gnu-arch/)) +sitem(Mercurial (tt(hg)))(uref(http://mercurial.selenic.com/)) +sitem(Monotone (tt(mtn)))(uref(http://monotone.ca/)) +sitem(Perforce (tt(p4)))(uref(http://www.perforce.com/)) +sitem(Subversion (tt(svn)))(uref(http://subversion.apache.org/)) +sitem(SVK (tt(svk)))(uref(http://svk.bestpractical.com/)) endsitem() There is also support for the patch management system tt(quilt) -(http://savannah.nongnu.org/projects/quilt). See tt(Quilt Support) +(uref(http://savannah.nongnu.org/projects/quilt)). See tt(Quilt Support) below for details. To load tt(vcs_info): @@ -927,6 +927,10 @@ kindex(get-bookmarks) item(tt(get-bookmarks))( If set to true, the tt(hg) backend will try to get a list of current bookmarks. They will be available via the `tt(%m)' replacement. + +The default is to generate a comma-separated list of all bookmark names +that refer to the currently checked out revision. If a bookmark is active, +its name is suffixed an asterisk and placed first in the list. ) kindex(use-prompt-escapes) item(tt(use-prompt-escapes))( @@ -944,6 +948,21 @@ item(tt(hooks))( A list style that defines hook-function names. See bf(Hooks in vcs_info) below for details. ) +kindex(patch-format) +kindex(nopatch-format) +xitem(tt(patch-format)) +item(tt(nopatch-format))( +This pair of styles format the patch information used by the tt(%m) expando in +formats and actionformats for the tt(git) and tt(hg) backends. The value is +subject to certain tt(%)-expansions described below. +) +kindex(get-unapplied) +item(tt(get-unapplied))( +This boolean style controls whether a backend should attempt to gather a list +of unapplied patches (for example with Mercurial Queue patches). + +Used by the tt(quilt) and tt(hg) backends. +) enditem() The default values for these styles in all contexts are: @@ -975,6 +994,9 @@ sitem(tt(use-quilt))(false) sitem(tt(quilt-standalone))(false) sitem(tt(quilt-patch-dir))(empty - use tt($QUILT_PATCHES)) sitem(tt(quiltcommand))(quilt) +sitem(tt(patch-format))(var(backend dependent)) +sitem(tt(nopatch-format))(var(backend dependent)) +sitem(tt(get-unapplied))(false) endsitem() In normal tt(formats) and tt(actionformats) the following replacements are @@ -996,11 +1018,26 @@ sitem(tt(%r))(The repository name. If tt(%R) is tt(/foo/bar/repoXY), tt(%r) is tt(repoXY).) sitem(tt(%S))(A subdirectory within a repository. If tt($PWD) is tt(/foo/bar/repoXY/beer/tasty), tt(%S) is tt(beer/tasty).) -sitem(tt(%m))(A "misc" replacement. It is at the discretion of the backend to -decide what this replacement expands to. It is currently used by the tt(hg) -and tt(git) backends to display patch information from the tt(mq) and -tt(stgit) extensions.) endsitem() +startitem() +item(tt(%m))( +A "misc" replacement. It is at the discretion of the backend to +decide what this replacement expands to. + +The tt(hg) and tt(git) backends use this expando to display patch information. +tt(hg) sources patch information from the tt(mq) extensions; tt(git) from the +tt(rebase) command and from the and tt(stgit) extension. The tt(patch-format) +and tt(nopatch-format) styles control the generated string. The former is used +when at least one patch from the patch queue has been applied, and the latter +otherwise. + +The tt(hg) backend displays bookmark information in this expando (in addition +to tt(mq) information). See the tt(get-mq) and tt(get-bookmarks) styles. Both +of these styles may be enabled at the same time. If both are enabled, both +resulting strings will be shown separated by a semicolon (that cannot currently +be customized). +) +enditem() In tt(branchformat) these replacements are done: @@ -1290,6 +1327,9 @@ tt(get-revision) and tt(get-bookmarks) styles must be true. This hook gets the names of the Mercurial bookmarks that tt(vcs_info) collected from `hg'. +If a bookmark is active, the key tt(${hook_com[hg-active-bookmark]}) is +set to its name. The key is otherwise unset. + When setting tt(ret) to non-zero, the string in tt(${hook_com[hg-bookmark-string]}) will be used in the tt(%m) escape in tt(formats) and tt(actionformats) and will be available in the global @@ -1377,6 +1417,30 @@ If tt(ret) is set to non-zero, the string in tt(${hook_com[rev-replace]}) will be used unchanged as the `tt(%i)' replacement in the variables set by tt(vcs_info). ) +item(tt(pre-addon-quilt))( +This hook is used when tt(vcs_info)'s quilt functionality is active in "addon" +mode (quilt used on top of a real version control system). It is activated +right before any quilt specific action is taken. + +Setting the `tt(ret)' variable in this hook to a non-zero value avoids any +quilt specific actions from being run at all. +) +item(tt(set-patch-format))( +This hook is used to control some of the possible expansions in +tt(patch-format) and tt(nopatch-format) styles with patch queue systems such as +quilt, mqueue and the like. + +This hook is used in the tt(git), tt(hg) and tt(quilt) backends. + +The hook allows the control of the tt(%p) (tt(${hook_com[applied]})) and tt(%u) +(tt(${hook_com[unapplied]})) expansion in all backends that use the hook. With +the mercurial backend, the tt(%g) (tt(${hook_com[guards]})) expansion is +controllable in addition to that. + +If tt(ret) is set to non-zero, the string in tt(${hook_com[patch-replace]}) +will be used unchanged instead of an expanded format from tt(patch-format) or +tt(nopatch-format). +) item(tt(set-message))( Called each time before a `tt(vcs_info_msg_N_)' message is set. It takes two arguments; the first being the `N' in the message @@ -1864,7 +1928,7 @@ described immediately above, i.e. using styles to decide the word boundaries. However, it is not a replacement for any existing function. The basic behaviour is to delete the word around the cursor. There is no -numeric prefix handling; only the single word around the cursor is +numeric argument handling; only the single word around the cursor is considered. If the widget contains the string tt(kill), the removed text will be placed in the cutbuffer for future yanking. This can be obtained by defining tt(kill-whole-word-match) as follows: @@ -1930,14 +1994,14 @@ full history line. Note that leading zeroes must be typed (they are only shown when necessary for removing ambiguity). The entire history is searched; there is no distinction between forwards and backwards. -With a prefix argument, the search is not anchored to the start of +With a numeric argument, the search is not anchored to the start of the line; the string typed by the use may appear anywhere in the line in the history. If the widget name contains `tt(-end)' the cursor is moved to the end of the line inserted. If the widget name contains `tt(-space)' any space in the text typed is treated as a wildcard and can match anything (hence -a leading space is equivalent to giving a prefix argument). Both +a leading space is equivalent to giving a numeric argument). Both forms can be combined, for example: example(zle -N history-beginning-search-menu-space-end \ @@ -1967,8 +2031,8 @@ vindex(incarg, use of) item(tt(incarg))( Typing the keystrokes for this widget with the cursor placed on or to the left of an integer causes that integer to be incremented by one. With a -numeric prefix argument, the number is incremented by the amount of the -argument (decremented if the prefix argument is negative). The shell +numeric argument, the number is incremented by the amount of the +argument (decremented if the numeric argument is negative). The shell parameter tt(incarg) may be set to change the default increment to something other than one. @@ -1997,7 +2061,7 @@ accented characters, the two keys are a base character followed by a code for the accent, while for other special characters the two characters together form a mnemonic for the character to be inserted. The two-character codes are a subset of those given by RFC 1345 (see for -example tt(http://www.faqs.org/rfcs/rfc1345.html)). +example uref(http://www.faqs.org/rfcs/rfc1345.html)). The function may optionally be followed by up to two characters which replace one or both of the characters read from the keyboard; if both @@ -2442,7 +2506,7 @@ This function may replace the tt(insert-last-word) widget, like so: example(zle -N insert-last-word smart-insert-last-word) -With a numeric prefix, or when passed command line arguments in a call +With a numeric argument, or when passed command line arguments in a call from another widget, it behaves like tt(insert-last-word), except that words in comments are ignored when tt(INTERACTIVE_COMMENTS) is set. @@ -2471,12 +2535,12 @@ The effect is similar to the function of the same name in Emacs. Transpose the current line with the previous line and move the cursor to the start of the next line. Repeating this (which can be done by -providing a positive numeric prefix argument) has the effect of moving +providing a positive numeric argument) has the effect of moving the line above the cursor down by a number of lines. -With a negative numeric prefix argument, requires two lines above the +With a negative numeric argument, requires two lines above the cursor. These two lines are transposed and the cursor moved to the -start of the previous line. Using a numeric prefix less than -1 +start of the previous line. Using a numeric argument less than -1 has the effect of moving the line above the cursor up by minus that number of lines. ) @@ -3227,8 +3291,18 @@ A reasonably powerful calculator based on zsh's arithmetic evaluation facility. The syntax is similar to that of formulae in most programming languages; see ifzman(the section `Arithmetic Evaluation' in zmanref(zshmisc))\ -ifnzman(noderef(Arithmetic Evaluation)) for details. The mathematical -library tt(zsh/mathfunc) will be loaded if it is available; see +ifnzman(noderef(Arithmetic Evaluation)) for details. + +Non-programmers should note that, as in many other programming +languages, expressions involving only integers (whether constants +without a `tt(.)', variables containing such constants as strings, or +variables declared to be integers) are by default evaluated using +integer arithmetic, which is not how an ordinary desk calculator +operates. To force floating point operation, pass the option tt(-f); +see further notes below. + +The mathematical library tt(zsh/mathfunc) will be loaded if it is +available; see ifzman(the section `The zsh/mathfunc Module' in zmanref(zshmodules))\ ifnzman(noderef(The zsh/mathfunc Module)). The mathematical functions correspond to the raw system libraries, so trigonometric functions are @@ -3609,6 +3683,17 @@ If you quit in the middle of a game, the next invocation of the tt(tetris) widget will continue where you left off. If you lost, it will start a new game. ) +item(tt(tetriscurses))( +This is a port of the above to zcurses. The input handling is improved +a bit so that moving a block sideways doesn't automatically advance a +timestep, and the graphics use unicode block graphics. + +This version does not save the game state between invocations, and is not +invoked as a widget, but rather as: + +example(autoload -U tetriscurses +tetriscurses) +) findex(zargs) item(tt(zargs) [ var(option) ... tt(-)tt(-) ] [ var(input) ... ] [ tt(-)tt(-) var(command) [ var(arg) ... ] ])( This function has a similar purpose to GNU xargs. Instead of diff --git a/Doc/Zsh/expn.yo b/Doc/Zsh/expn.yo index 5aab25954..8728803e0 100644 --- a/Doc/Zsh/expn.yo +++ b/Doc/Zsh/expn.yo @@ -1061,6 +1061,9 @@ for arrays which keep only the first occurrence of duplicated values item(tt(hide))( for parameters with the `hide' flag ) +item(tt(hideval))( +for parameters with the `hideval' flag +) item(tt(special))( for special parameters defined by the shell ) @@ -1124,6 +1127,19 @@ item(tt(p))( Recognize the same escape sequences as the tt(print) builtin in string arguments to any of the flags described below that follow this argument. + +Alternatively, with this option string arguments may be in the form +tt($)var(var) in which case the value of the variable is substituted. +Note this form is strict; the string argument does not undergo general +parameter expansion. + +For example, + +example(sep=: +val=a:b:c +print ${+LPAR()ps.$sep.+RPAR()val}) + +splits the variable on a tt(:). ) item(tt(~))( Strings inserted into the expansion by any of the flags below are to @@ -2372,7 +2388,7 @@ item(tt(p))( named pipes (FIFOs) ) item(tt(*))( -executable plain files (0100) +executable plain files (0100 or 0010 or 0001) ) item(tt(%))( device files (character or block special) @@ -2695,6 +2711,10 @@ example(ls *(-/)) lists all directories and symbolic links that point to directories, and +example(ls *(-@)) + +lists all broken symbolic links, and + example(ls *(%W)) lists all world-writable device files in the current directory, and diff --git a/Doc/Zsh/ftp_sites.yo b/Doc/Zsh/ftp_sites.yo index 62c1bff06..804d975f3 100644 --- a/Doc/Zsh/ftp_sites.yo +++ b/Doc/Zsh/ftp_sites.yo @@ -1,15 +1,15 @@ startitem() item(Primary site)( -nofill(tt(ftp://ftp.zsh.org/pub/) -tt(http://www.zsh.org/pub/)) +nofill(uref(ftp://ftp.zsh.org/pub/) +uref(http://www.zsh.org/pub/)) ) item(Australia)( -nofill(tt(ftp://ftp.zsh.org/pub/) -tt(http://www.zsh.org/pub/) -tt(http://mirror.dejanseo.com.au/pub/zsh/)) +nofill(uref(ftp://ftp.zsh.org/pub/) +uref(http://www.zsh.org/pub/) +uref(http://mirror.dejanseo.com.au/pub/zsh/)) ) item(Hungary)( -nofill(tt(ftp://ftp.cs.elte.hu/pub/zsh/) -tt(http://www.cs.elte.hu/pub/zsh/)) +nofill(uref(ftp://ftp.cs.elte.hu/pub/zsh/) +uref(http://www.cs.elte.hu/pub/zsh/)) ) enditem() diff --git a/Doc/Zsh/func.yo b/Doc/Zsh/func.yo index 6e9cfeee9..ace0a4051 100644 --- a/Doc/Zsh/func.yo +++ b/Doc/Zsh/func.yo @@ -247,10 +247,10 @@ findex(preexec) vindex(preexec_functions) item(tt(preexec))( Executed just after a command has been read and is about to be -executed. If the history mechanism is active (and the line was not -discarded from the history buffer), the string that the user typed is -passed as the first argument, otherwise it is an empty string. The -actual command that will be executed (including expanded aliases) is +executed. If the history mechanism is active (regardless of whether the +line was discarded from the history buffer), the string that the user +typed is passed as the first argument, otherwise it is an empty string. +The actual command that will be executed (including expanded aliases) is passed in two different forms: the second argument is a single-line, size-limited version of the command (with things like function bodies elided); the third argument contains the full text that is being diff --git a/Doc/Zsh/grammar.yo b/Doc/Zsh/grammar.yo index 4d04c2470..522ad0472 100644 --- a/Doc/Zsh/grammar.yo +++ b/Doc/Zsh/grammar.yo @@ -239,7 +239,11 @@ item(tt(case) var(word) tt(in) [ [tt(LPAR())] var(pattern) [ tt(|) var(pattern) Execute the var(list) associated with the first var(pattern) that matches var(word), if any. The form of the patterns is the same as that used for filename generation. See -noderef(Filename Generation). +noderef(Filename Generation). Note further that the whole +pattern with alternatives is treated by the shell as equivalent +to a group of patterns within parentheses, even though in +the tt(case) syntax whitespace may appear about the parentheses and the +vertical bar. If the var(list) that is executed is terminated with tt(;&) rather than tt(;;), the following list is also executed. The rule for @@ -528,29 +532,54 @@ characters up to a newline to be ignored. texinode(Aliasing)(Quoting)(Comments)(Shell Grammar) sect(Aliasing) cindex(aliasing) -Every token in the shell input is checked to see if there +Every eligible em(word) in the shell input is checked to see if there is an alias defined for it. If so, it is replaced by the text of the alias if it is in command position (if it could be the first word of a simple command), or if the alias is global. -If the text ends with a space, the next word in the shell input -is treated as though it were in command position for purposes of alias -expansion. +If the replacement text ends with a space, the next word in the shell input +is always eligible for purposes of alias expansion. findex(alias, use of) cindex(aliases, global) An alias is defined using the tt(alias) builtin; global aliases may be defined using the tt(-g) option to that builtin. +A em(word) is defined as: + +startitemize() +itemiz(Any plain string or glob pattern) +itemiz(Any quoted string, using any quoting method (note that the quotes +must be part of the alias definition for this to be eligible)) +itemiz(Any parameter reference or command substitution) +itemiz(Any series of the foregoing, concatenated without whitespace or +other tokens between them) +itemiz(Any reserved word (tt(case), tt(do), tt(else), etc.)) +itemiz(With global aliasing, any command separator, any redirection +operator, and `tt(LPAR())' or `tt(RPAR())' when not part of a glob pattern) +enditemize() + +It is not presently possible to alias the `tt(LPAR()LPAR())' token that +introduces arithmetic expressions, because until a full statement has been +parsed, it cannot be distinguished from two consecutive `tt(LPAR())' +tokens introducing nested subshells. + +When tt(POSIX_ALIASES) is set, only plain unquoted strings are eligible +for aliasing. The tt(alias) builtin does not reject ineligible aliases, +but they are not expanded. + Alias expansion is done on the shell input before any other expansion except history expansion. Therefore, if an alias is defined for the word tt(foo), alias expansion may be avoided by quoting part of the word, e.g. tt(\foo). Any form of quoting works, although there is nothing to prevent an alias being defined for the quoted form such as -tt(\foo) as well. For use with completion, which would remove an -initial backslash followed by a character that isn't special, it may be -more convenient to quote the word by starting with a single quote, -i.e. tt('foo); completion will automatically add the trailing single -quote. +tt(\foo) as well. Also, if a separator such as tt(&&) is aliased, +tt(\&&) turns into the two tokens tt(\&) and tt(&), each of which may +have been aliased separately. Similarly for tt(\<<), tt(\>|), etc. + +For use with completion, which would remove an initial backslash followed +by a character that isn't special, it may be more convenient to quote the +word by starting with a single quote, i.e. tt('foo); completion will +automatically add the trailing single quote. There is a commonly encountered problem with aliases illustrated by the following code: diff --git a/Doc/Zsh/manual.yo b/Doc/Zsh/manual.yo index 5184928c2..e0b0f14cb 100644 --- a/Doc/Zsh/manual.yo +++ b/Doc/Zsh/manual.yo @@ -5,7 +5,8 @@ texitop(The Z Shell Manual) texiifinfo(\ This Info file documents Zsh, a freely available UNIX command interpreter (shell), which of the standard shells most closely resembles the Korn shell -(ksh), although it is not completely compatible. +(ksh), although it is not completely compatible. Zsh is able to emulate +POSIX shells, but its default mode is not POSIX compatible, either. cindex(version) Version version(), last updated date(). @@ -184,16 +185,16 @@ produce a nicely formatted printed manual. item(The HTML manual)( An HTML version of this manual is available at the Zsh web site via: -tt(http://zsh.sourceforge.net/Doc/). +uref(http://zsh.sourceforge.net/Doc/). (The HTML version is produced with bf(texi2html), which may be obtained -from tt(http://www.nongnu.org/texi2html/). The command is +from uref(http://www.nongnu.org/texi2html/). The command is `tt(texi2html --output . --ifinfo --split=chapter --node-files zsh.texi)'. If necessary, upgrade to version 1.78 of texi2html.) ) enditem() For those who do not have the necessary tools to process texinfo, -precompiled documentation (PostScript, dvi, info and HTML formats) +precompiled documentation (PostScript, dvi, PDF, info and HTML formats) is available from the zsh archive site or its mirrors, in the file tt(zsh-doc.tar.gz). (See noderef(Availability) for a list of sites.) diff --git a/Doc/Zsh/metafaq.yo b/Doc/Zsh/metafaq.yo index 34cd70e32..6cb299ad1 100644 --- a/Doc/Zsh/metafaq.yo +++ b/Doc/Zsh/metafaq.yo @@ -27,10 +27,10 @@ cindex(acquiring zsh by FTP) cindex(availability of zsh) INCLUDEFILE(Zsh/ftp_sites.yo)\ -The up-to-date source code is available via anonymous CVS and Git from -Sourceforge. See tt(http://sourceforge.net/projects/zsh/) for details. -A summary of instructions for the CVS and Git archives can be found at -tt(http://zsh.sourceforget.net/). +The up-to-date source code is available via Git from Sourceforge. See +uref(http://sourceforge.net/projects/zsh/) for details. A summary of +instructions for the archive can be found at +uref(http://zsh.sourceforge.net/). texinode(Mailing Lists)(The Zsh FAQ)(Availability)(Introduction) sect(Mailing Lists) @@ -75,18 +75,18 @@ maintained by Karsten Thygesen tt(<karthy@kom.auc.dk>). The mailing lists are archived; the archives can be accessed via the administrative addresses listed above. There is also a hypertext archive, maintained by Geoff Wing tt(<gcw@zsh.org>), available at -tt(http://www.zsh.org/mla/). +uref(http://www.zsh.org/mla/). texinode(The Zsh FAQ)(The Zsh Web Page)(Mailing Lists)(Introduction) sect(The Zsh FAQ) Zsh has a list of Frequently Asked Questions (FAQ), maintained by Peter Stephenson tt(<pws@zsh.org>). It is regularly posted to the newsgroup bf(comp.unix.shell) and the bf(zsh-announce) mailing list. The latest version can be found at any of the Zsh FTP sites, or at -tt(http://www.zsh.org/FAQ/). The contact address for FAQ-related matters +uref(http://www.zsh.org/FAQ/). The contact address for FAQ-related matters is tt(<faqmaster@zsh.org>). texinode(The Zsh Web Page)(The Zsh Userguide)(The Zsh FAQ)(Introduction) sect(The Zsh Web Page) -Zsh has a web page which is located at tt(http://www.zsh.org/). This is +Zsh has a web page which is located at uref(http://www.zsh.org/). This is maintained by Karsten Thygesen tt(<karthy@zsh.org>), of SunSITE Denmark. The contact address for web-related matters is tt(<webmaster@zsh.org>). texinode(The Zsh Userguide)(See Also)(The Zsh Web Page)(Introduction) @@ -95,10 +95,10 @@ A userguide is currently in preparation. It is intended to complement the manual, with explanations and hints on issues where the manual can be cabbalistic, hierographic, or downright mystifying (for example, the word `hierographic' does not exist). It can be viewed in its current state at -tt(http://zsh.sourceforge.net/Guide/). At the time of writing, chapters +uref(http://zsh.sourceforge.net/Guide/). At the time of writing, chapters dealing with startup files and their contents and the new completion system were essentially complete. sect(The Zsh Wiki) -A `wiki' website for zsh has been created at tt(http://www.zshwiki.org/). +A `wiki' website for zsh has been created at uref(http://www.zshwiki.org/). This is a site which can be added to and modified directly by users without any special permission. You can add your own zsh tips and configurations. diff --git a/Doc/Zsh/mod_datetime.yo b/Doc/Zsh/mod_datetime.yo index 619067698..27bc78157 100644 --- a/Doc/Zsh/mod_datetime.yo +++ b/Doc/Zsh/mod_datetime.yo @@ -8,25 +8,46 @@ findex(strftime) cindex(date string, printing) xitem(tt(strftime) [ tt(-s) var(scalar) ] var(format) var(epochtime) ) item(tt(strftime) tt(-r) [ tt(-q) ] [ tt(-s) var(scalar) ] var(format) var(timestring) )( -Output the date denoted by var(epochtime) in the var(format) -specified. +Output the date denoted by var(epochtime) in the var(format) specified. +See manref(strftime)(3) for details. The zsh extensions described in +ifzman(the section EXPANSION OF PROMPT SEQUENCES in zmanref(zshmisc))\ +ifnzman(noderef(Prompt Expansion)) are also available. -With the option tt(-r) (reverse), use the format var(format) to parse the -input string var(timestring) and output the number of seconds since the -epoch at which the time occurred. If no timezone is parsed, the current -timezone is used; other parameters are set to zero if not present. If -var(timestring) does not match var(format) the command returns status 1; it -will additionally print an error message unless the option tt(-q) (quiet) -is given. If var(timestring) matches var(format) but not all characters in -var(timestring) were used, the conversion succeeds; however, a warning is -issued unless the option tt(-q) is given. The matching is implemented by -the system function tt(strptime); see manref(strptime)(3). This means that -zsh format extensions are not available, however for reverse lookup they -are not required. If the function is not implemented, the command returns -status 2 and (unless tt(-q) is given) prints a message. +startitem() +item(tt(-q))( +Run quietly; suppress printing of all error messages described below. +Errors for invalid var(epochtime) values are always printed. +) +item(tt(-r))( +With the option tt(-r) (reverse), use var(format) to parse the input +string var(timestring) and output the number of seconds since the epoch at +which the time occurred. The parsing is implemented by the system +function tt(strptime); see manref(strptime)(3). This means that zsh +format extensions are not available, but for reverse lookup they are not +required. + +In most implementations of tt(strftime) any timezone in the +var(timestring) is ignored and the local timezone declared by the tt(TZ) +environment variable is used; other parameters are set to zero if not +present. + +If var(timestring) does not match var(format) the command returns status 1 +and prints an error message. If var(timestring) matches var(format) but +not all characters in var(timestring) were used, the conversion succeeds +but also prints an error message. + +If either of the system functions tt(strptime) or tt(mktime) is not +available, status 2 is returned and an error message is printed. +) +item(tt(-s) var(scalar))( +Assign the date string (or epoch time in seconds if tt(-r) is given) to +var(scalar) instead of printing it. +) +enditem() -If tt(-s) var(scalar) is given, assign the date string (or epoch time -in seconds if tt(-r) is given) to var(scalar) instead of printing it. +Note that depending on the system's declared integral time type, +tt(strftime) may produce incorrect results for epoch times greater than +2147483647 which corresponds to 2038-01-19 03:14:07 +0000. ) enditem() diff --git a/Doc/Zsh/mod_db_gdbm.yo b/Doc/Zsh/mod_db_gdbm.yo new file mode 100644 index 000000000..90974297c --- /dev/null +++ b/Doc/Zsh/mod_db_gdbm.yo @@ -0,0 +1,51 @@ +COMMENT(!MOD!zsh/db/gdbm +Builtins for managing associative array parameters tied to GDBM databases. +!MOD!) +The tt(zsh/db/gdbm) module is used to create "tied" associative arrays +that interface to database files. If the GDBM interface is not available, +the builtins defined by this module will report an error. This module is +also intended as a prototype for creating additional database interfaces, +so the tt(ztie) builtin may move to a more generic module in the future. + +The builtins in this module are: + +startitem() +findex(ztie) +cindex(database tied array, creating) +item(tt(ztie -d db/gdbm -f) var(filename) [ tt(-r) ] var(arrayname))( +Open the GDBM database identified by var(filename) and, if successful, +create the associative array var(arrayname) linked to the file. To create +a local tied array, the parameter must first be declared, so commands +similar to the following would be executed inside a function scope: + +example(local -A sampledb +ztie -d db/gdbm -f sample.gdbm sampledb) + +The tt(-r) option opens the database file for reading only, creating a +parameter with the readonly attribute. Without this option, using +`tt(ztie)' on a file for which the user does not have write permission is +an error. If writable, the database is opened synchronously so fields +changed in var(arrayname) are immediately written to var(filename). + +Changes to the file modes var(filename) after it has been opened do not +alter the state of var(arrayname), but `tt(typeset -r) var(arrayname)' +works as expected. +) +findex(zuntie) +cindex(database tied array, destroying) +item(tt(zuntie) [ tt(-u) ] var(arrayname) ...)( +Close the GDBM database associated with each var(arrayname) and then +unset the parameter. The tt(-u) option forces an unset of parameters +made readonly with `tt(ztie -r)'. + +This happens automatically if the parameter is explicitly unset or its +local scope (function) ends. Note that a readonly parameter may not be +explicitly unset, so the only way to unset a global parameter created with +`tt(ztie -r)' is to use `tt(zuntie -u)'. +) +enditem() + +The fields of an associative array tied to GDBM are neither cached nor +otherwise stored in memory, they are read from or written to the database +on each reference. Thus, for example, the values in a readonly array may +be changed by a second writer of the same database file. diff --git a/Doc/Zsh/mod_files.yo b/Doc/Zsh/mod_files.yo index 5dbdae7d2..90e988474 100644 --- a/Doc/Zsh/mod_files.yo +++ b/Doc/Zsh/mod_files.yo @@ -10,7 +10,10 @@ all features now required by relevant standards committees. For all commands, a variant beginning tt(zf_) is also available and loaded automatically. Using the features capability of zmodload will let you load -only those names you want. +only those names you want. Note that it's possible to load only the +builtins with zsh-specific names using the following command: + +example(zmodload -m -F zsh/files b:zf_\*) The commands loaded by default are: diff --git a/Doc/Zsh/mod_system.yo b/Doc/Zsh/mod_system.yo index dce07175f..7101e37dc 100644 --- a/Doc/Zsh/mod_system.yo +++ b/Doc/Zsh/mod_system.yo @@ -178,12 +178,15 @@ used. vindex(sysparams) item(tt(sysparams))( A readonly associative array. The keys are: + startitem() item(tt(pid))( +vindex(pid, sysparams) Returns the process ID of the current process, even in subshells. Compare tt($$), which returns the process ID of the main shell process. ) item(tt(ppid))( +vindex(ppid, sysparams) Returns the process ID of the parent of the current process, even in subshells. Compare tt($PPID), which returns the process ID of the parent of the main shell process. diff --git a/Doc/Zsh/options.yo b/Doc/Zsh/options.yo index 068a253ac..20d9fc2a8 100644 --- a/Doc/Zsh/options.yo +++ b/Doc/Zsh/options.yo @@ -63,6 +63,10 @@ item(tt(AUTO_CD) (tt(-J)))( If a command is issued that can't be executed as a normal command, and the command is the name of a directory, perform the tt(cd) command to that directory. +This option is only applicable if the option tt(SHIN_STDIN) is set, +i.e. if commands are being read from standard input. The option +is designed for interactive use; it is recommended that tt(cd) +be used explicitly in scripts to avoid ambiguity. ) pindex(AUTO_PUSHD) pindex(NO_AUTO_PUSHD) @@ -492,9 +496,10 @@ pindex(NOFORCEFLOAT) cindex(floating point, forcing use of) cindex(forcing use of floating point) item(tt(FORCE_FLOAT))( -Constants in arithmetic evaluation will be treated as floating point -even without the use of a decimal point. Integers in any base -will be converted. +Constants in arithmetic evaluation will be treated as +floating point even without the use of a decimal point; the +values of integer variables will be converted to floating point when +used in arithmetic expressions. Integers in any base will be converted. ) pindex(GLOB) pindex(NO_GLOB) @@ -535,7 +540,7 @@ pindex(GLOBSUBST) pindex(NOGLOBSUBST) item(tt(GLOB_SUBST) <C> <K> <S>)( Treat any characters resulting from parameter expansion as being -eligible for file expansion and filename generation, and any +eligible for filename expansion and filename generation, and any characters resulting from command substitution as being eligible for filename generation. Braces (and commas in between) do not become eligible for expansion. @@ -804,7 +809,7 @@ pindex(NOHISTBEEP) cindex(history beeping) cindex(beep, history) item(tt(HIST_BEEP) <D>)( -Beep when an attempt is made to access a history entry which +Beep in ZLE when a widget attempts to access a history entry which isn't there. ) pindex(HIST_EXPIRE_DUPS_FIRST) @@ -1434,10 +1439,10 @@ shell is saved for output within a subshell (for example, within a pipeline). When the option is set, the output of tt(jobs) is empty until a job is started within the subshell. -When the option is set, it becomes possible to use the tt(wait) builtin to -wait for the last job started in the background (as given by tt($!)) even -if that job has already exited. This works even if the option is turned -on temporarily around the use of the tt(wait) builtin. +In previous versions of the shell, it was necessary to enable +tt(POSIX_JOBS) in order for the builtin command tt(wait) to return the +status of background jobs that had already exited. This is no longer +the case. ) enditem() @@ -1841,8 +1846,8 @@ cindex(history style, csh) item(tt(CSH_JUNKIE_HISTORY) <C>)( A history reference without an event specifier will always refer to the previous command. Without this option, such a history reference refers -to the same event as the previous history reference, defaulting to the -previous command. +to the same event as the previous history reference on the current +command line, defaulting to the previous command. ) pindex(CSH_JUNKIE_LOOPS) pindex(NO_CSH_JUNKIE_LOOPS) @@ -2092,7 +2097,7 @@ pindex(NOPOSIXTRAPS) cindex(traps, on function exit) cindex(traps, POSIX compatibility) item(tt(POSIX_TRAPS) <K> <S>)( -When the is option is set, the usual zsh behaviour of executing +When this option is set, the usual zsh behaviour of executing traps for tt(EXIT) on exit from shell functions is suppressed. In that case, manipulating tt(EXIT) traps always alters the global trap for exiting the shell; the tt(LOCAL_TRAPS) option is @@ -2195,10 +2200,22 @@ pindex(NOPRIVILEGED) cindex(privileged mode) cindex(mode, privileged) item(tt(PRIVILEGED) (tt(-p), ksh: tt(-p)))( -Turn on privileged mode. This is enabled automatically on startup if the -effective user (group) ID is not equal to the real user (group) ID. Turning -this option off causes the effective user and group IDs to be set to the -real user and group IDs. This option disables sourcing user startup files. +Turn on privileged mode. Typically this is used when script is to be run +with elevated privileges. This should be done as follows directly with +the tt(-p) option to zsh so that it takes effect during startup. + +example(#!/bin/zsh -p) + +The option is enabled automatically on startup if the effective user +(group) ID is not equal to the real user (group) ID. In this case, +turning the option off causes the effective user and group IDs to be set +to the real user and group IDs. Be aware that if that fails the shell may +be running with different IDs than was intended so a script should check +for failure and act accordingly, for example: + +example(unsetopt privileged || exit) + +The tt(PRIVILEGED) option disables sourcing user startup files. If zsh is invoked as `tt(sh)' or `tt(ksh)' with this option set, tt(/etc/suid_profile) is sourced (after tt(/etc/profile) on interactive shells). Sourcing tt(~/.profile) is disabled and the contents of the @@ -2231,7 +2248,7 @@ taken as a file to run will instead be treated as a normal positional parameter. Note that setting or unsetting this option on the command line does not necessarily affect the state the option will have while the shell is -running - that is purely an indicator of whether on not commands are +running - that is purely an indicator of whether or not commands are em(actually) being read from standard input. The value of this option can only be changed via flags supplied at invocation of the shell. diff --git a/Doc/Zsh/params.yo b/Doc/Zsh/params.yo index 3698829f3..9d06b6af6 100644 --- a/Doc/Zsh/params.yo +++ b/Doc/Zsh/params.yo @@ -1,48 +1,81 @@ texinode(Parameters)(Options)(Expansion)(Top) chapter(Parameters) cindex(parameters) +cindex(variables) sect(Description) A parameter has a name, a value, and a number of attributes. A name may be any sequence of alphanumeric characters and underscores, or the single characters `tt(*)', `tt(@)', `tt(#)', `tt(?)', `tt(-)', `tt($)', or `tt(!)'. -The value may be a em(scalar) (a string), -an integer, an array (indexed numerically), or an em(associative) -array (an unordered set of name-value pairs, indexed by name). To declare -the type of a parameter, or to assign a scalar or integer value to a -parameter, use the tt(typeset) builtin. +A parameter whose name begins with an alphanumeric or underscore is also +referred to as a em(variable). + +cindex(scalar) +cindex(parameters, scalar) +cindex(parameters, array) +cindex(parameters, associative array) +cindex(hash) +The attributes of a parameter determine the em(type) of its value, often +referred to as the parameter type or variable type, and also control +other processing that may be applied to the value when it is referenced. +The value type may be a em(scalar) (a string, an integer, or a floating +point number), an array (indexed numerically), or an em(associative) +array (an unordered set of name-value pairs, indexed by name, also +referred to as a em(hash)). + +cindex(export) +cindex(environment) +cindex(environment variables) +cindex(variables, environment) +Named scalar parameters may have the em(exported), tt(-x), attribute, to +copy them into the process environment, which is then passed from the +shell to any new processes that it starts. Exported parameters are called +em(environment variables). The shell also em(imports) environment variables +at startup time and automatically marks the corresponding parameters as +exported. Some environment variables are not imported for reasons of +security or because they would interfere with the correct operation of +other shell features. + +cindex(special parameters) +cindex(parameters, special) +Parameters may also be em(special), that is, they have a predetermined +meaning to the shell. Special parameters cannot have their type changed +or their readonly attribute turned off, and if a special parameter is +unset, then later recreated, the special properties will be retained. + +To declare the type of a parameter, or to assign a string or numeric value +to a scalar parameter, use the tt(typeset) builtin. findex(typeset, use of) -The value of a scalar or integer parameter may also be assigned by -writing: +The value of a scalar parameter may also be assigned by writing: cindex(assignment) - +ifzman() indent(var(name)tt(=)var(value)) -If the integer attribute, tt(-i), is set for var(name), the var(value) -is subject to arithmetic evaluation. Furthermore, by replacing `tt(=)' -with `tt(+=)', a parameter can be added or appended to. - In scalar assignment, var(value) is expanded as a single string, in which the elements of arrays are joined together; filename expansion is -not performed unless the option tt(GLOB_ASSIGN) is set. See -noderef(Array Parameters) for additional forms of assignment. - -To refer to the value of a parameter, write `tt($)var(name)' or +not performed unless the option tt(GLOB_ASSIGN) is set. + +When the integer attribute, tt(-i), or a floating point attribute, tt(-E) +or tt(-F), is set for var(name), the var(value) is subject to arithmetic +evaluation. Furthermore, by replacing `tt(=)' with `tt(+=)', a parameter +can be incremented or appended to. See noderef(Array Parameters) and +ifzman(em(Arithmetic Evaluation) LPAR()in zmanref(zshexpn)RPAR())\ +ifnzman(noderef(Arithmetic Evaluation)) +for additional forms of assignment. + +Note that assignment may implicitly change the attributes of a parameter. +For example, assigning a number to a variable in arithmetic evaluation may +change its type to integer or float, and with tt(GLOB_ASSIGN) assigning a +pattern to a variable may change its type to an array. + +To reference the value of a parameter, write `tt($)var(name)' or `tt(${)var(name)tt(})'. See ifzman(em(Parameter Expansion) in zmanref(zshexpn))\ ifnzman(noderef(Parameter Expansion)) -for complete details. This section also explains the effect +for complete details. That section also explains the effect of the difference between scalar and array assignment on parameter expansion. - -In the parameter lists that follow, the mark `<S>' indicates that the -parameter is special. -Special parameters cannot have their type changed or their -readonly attribute turned off, and if a special parameter is unset, then -later recreated, the special properties will be retained. `<Z>' indicates -that the parameter does not exist when the shell initializes in tt(sh) or -tt(ksh) emulation mode. startmenu() menu(Array Parameters) menu(Positional Parameters) @@ -55,39 +88,48 @@ sect(Array Parameters) To assign an array value, write one of: findex(set, use of) cindex(array assignment) - +ifzman() indent(tt(set -A) var(name) var(value) ...) indent(var(name)tt(=LPAR())var(value) ...tt(RPAR())) If no parameter var(name) exists, an ordinary array parameter is created. If the parameter var(name) exists and is a scalar, it is replaced by a new -array. Ordinary array parameters may also be explicitly declared with: -findex(typeset, use of) +array. To append to an array without changing the existing values, use +the syntax: +ifzman() +indent(var(name)tt(+=LPAR())var(value) ...tt(RPAR())) +Ordinary array parameters may also be explicitly declared with: +findex(typeset, use of) +ifzman() indent(tt(typeset -a) var(name)) Associative arrays em(must) be declared before assignment, by using: - +ifzman() indent(tt(typeset -A) var(name)) When var(name) refers to an associative array, the list in an assignment is interpreted as alternating keys and values: - +ifzman() indent(set -A var(name) var(key) var(value) ...) indent(var(name)tt(=LPAR())var(key) var(value) ...tt(RPAR())) Every var(key) must have a var(value) in this case. Note that this -assigns to the entire array, deleting any elements that do not appear -in the list. +assigns to the entire array, deleting any elements that do not appear in +the list. The append syntax may also be used with an associative array: +ifzman() +indent(var(name)tt(+=LPAR())var(key) var(value) ...tt(RPAR())) -To create an empty array (including associative arrays), use one of: +This adds a new key/value pair if the key is not already present, and +replaces the value for the existing key if it is. +To create an empty array (including associative arrays), use one of: +ifzman() indent(tt(set -A) var(name)) indent(var(name)tt(=LPAR()RPAR())) subsect(Array Subscripts) cindex(subscripts) - Individual elements of an array may be selected using a subscript. A subscript of the form `tt([)var(exp)tt(])' selects the single element var(exp), where var(exp) is an arithmetic expression which will be subject @@ -145,12 +187,32 @@ from the end of the array tt(foo), and Subscripting may also be performed on non-array values, in which case the subscripts specify a substring to be extracted. For example, if tt(FOO) is set to `tt(foobar)', then -`tt(echo $FOO[2,5])' prints `tt(ooba)'. +`tt(echo $FOO[2,5])' prints `tt(ooba)'. Note that +some forms of subscripting described below perform pattern matching, +and in that case the substring extends from the start of the match +of the first subscript to the end of the match of the second +subscript. For example, + +example(string="abcdefghijklm" +print ${string[+LPAR()r+RPAR()d?,+LPAR()r+RPAR()h?]}) + +prints `tt(defghi)'. This is an obvious generalisation of the +rule for single-character matches. For a single subscript, +only a single character is referenced (not the range of characters +covered by the match). + +Note that in substring operations the second subscript is handled +differently by the tt(r) and tt(R) subscript flags: the former takes the +shortest match as the length and the latter the longest match. Hence +in the former case a tt(*) at the end is redundant while in +the latter case it matches the whole remainder of the string. This +does not affect the result of the single subscript case as here the +length of the match is irrelevant. subsect(Array Element Assignment) A subscript may be used on the left side of an assignment like so: - +ifzman() indent(var(name)tt([)var(exp)tt(]=)var(value)) In this form of assignment the element or range specified by var(exp) @@ -162,7 +224,7 @@ other elements to accommodate the new values. (This is not supported for associative arrays.) This syntax also works as an argument to the tt(typeset) command: - +ifzman() indent(tt(typeset) tt(")var(name)tt([)var(exp)tt(]"=)var(value)) The var(value) may em(not) be a parenthesized list in this case; only @@ -174,12 +236,11 @@ could be used instead. To delete an element of an ordinary array, assign `tt(LPAR()RPAR())' to that element. To delete an element of an associative array, use the tt(unset) command: - +ifzman() indent(tt(unset) tt(")var(name)tt([)var(exp)tt(]")) subsect(Subscript Flags) cindex(subscript flags) - If the opening bracket, or the comma in a range, in any subscript expression is directly followed by an opening parenthesis, the string up to the matching closing one is considered to be a list of flags, as in @@ -319,16 +380,13 @@ patterns used for reverse subscripting (the `tt(r)', `tt(R)', `tt(i)', etc. flags), but it may also affect parameter substitutions that appear as part of an arithmetic expression in an ordinary subscript. -It is possible to avoid the use of subscripts in assignments to associative -array elements by using the syntax: +To avoid subscript parsing limitations in assignments to associative array +elements, use the append syntax: example( aa+=('key with "*strange*" characters' 'value string') ) -This adds a new key/value pair if the key is not already present, and -replaces the value for the existing key if it is. - The basic rule to remember when writing a subscript expression is that all text between the opening `tt([)' and the closing `tt(])' is interpreted em(as if) it were in double quotes (\ @@ -493,6 +551,10 @@ were never exported has been removed. texinode(Parameters Set By The Shell)(Parameters Used By The Shell)(Local Parameters)(Parameters) sect(Parameters Set By The Shell) +In the parameter lists that follow, the mark `<S>' indicates that the +parameter is special. `<Z>' indicates that the parameter does not exist +when the shell initializes in tt(sh) or tt(ksh) emulation mode. + The following parameters are automatically set by the shell: startitem() @@ -712,6 +774,17 @@ It may be reset, clearing the error condition. See ifzman(em(Complex Commands) in zmanref(zshmisc))\ ifnzman(noderef(Complex Commands)) ) +vindex(TRY_BLOCK_INTERRUPT) +item(tt(TRY_BLOCK_INTERRUPT) <S>)( +This variable works in a similar way to tt(TRY_BLOCK_ERROR), but +represents the status of an interrupt from the signal SIGINT, which +typically comes from the keyboard when the user types tt(^C). If set to +0, any such interrupt will be reset; otherwise, the interrupt is +propagated after the tt(always) block. + +Note that it is possible that an interrupt arrives during the execution +of the tt(always) block; this interrupt is also propagated. +) vindex(TTY) item(tt(TTY))( The name of the tty associated with the shell, if any. @@ -870,7 +943,9 @@ The version number of the release of zsh. enditem() texinode(Parameters Used By The Shell)()(Parameters Set By The Shell)(Parameters) sect(Parameters Used By The Shell) -The following parameters are used by the shell. +The following parameters are used by the shell. Again, `<S>' indicates +that the parameter is special and `<Z>' indicates that the parameter does +not exist when the shell initializes in tt(sh) or tt(ksh) emulation mode. In cases where there are two parameters with an upper- and lowercase form of the same name, such as tt(path) and tt(PATH), the lowercase form @@ -997,10 +1072,25 @@ item(tt(HISTORY_IGNORE))( If set, is treated as a pattern at the time history files are written. Any potential history entry that matches the pattern is skipped. For example, if the value is `tt(fc *)' then commands that invoke the -interactive history editor are never written to the history file (compare -the tt(HIST_NO_STORE) option or the tt(zshaddhistory) hook, either of -which would prevent such commands from being added to the interactive -history at all). +interactive history editor are never written to the history file. + +Note that tt(HISTORY_IGNORE) defines a single pattern: to +specify alternatives use the `tt(+LPAR()first|second|...+RPAR())' +syntax. + +Compare the tt(HIST_NO_STORE) option or the tt(zshaddhistory) hook, +either of which would prevent such commands from being added to the +interactive history at all. If you wish to use tt(HISTORY_IGNORE) to +stop history being added in the first place, you can define the +following hook: + +example(zshaddhistory+LPAR()RPAR() { + emulate -L zsh + ## uncomment if HISTORY_IGNORE + ## should use EXTENDED_GLOB syntax + # setopt extendedglob + [[ $1 != ${~HISTORY_IGNORE} ]] +}) ) vindex(HISTSIZE) item(tt(HISTSIZE) <S>)( @@ -1355,7 +1445,7 @@ sitem(tt(%U))(CPU seconds spent in user mode.) sitem(tt(%S))(CPU seconds spent in kernel mode.) sitem(tt(%E))(Elapsed time in seconds.) sitem(tt(%P))(The CPU percentage, computed as -(100*tt(%U)PLUS()tt(%S))/tt(%E).) +100*(tt(%U)PLUS()tt(%S))/tt(%E).) sitem(tt(%W))(Number of times the process was swapped.) sitem(tt(%X))(The average amount in (shared) text space used in kilobytes.) sitem(tt(%D))(The average amount in (unshared) data/stack space used in @@ -1402,15 +1492,27 @@ vindex(watch) vindex(WATCH) item(tt(watch) <S> <Z> (tt(WATCH) <S>))( An array (colon-separated list) of login/logout events to report. + If it contains the single word `tt(all)', then all login/logout events are reported. If it contains the single word `tt(notme)', then all events are reported as with `tt(all)' except tt($USERNAME). + An entry in this list may consist of a username, an `tt(@)' followed by a remote hostname, -and a `tt(%)' followed by a line (tty). +and a `tt(%)' followed by a line (tty). Any of these may +be a pattern (be sure to quote this during the assignment to +tt(watch) so that it does not immediately perform file generation); +the setting of the tt(EXTENDED_GLOB) option is respected. Any or all of these components may be present in an entry; if a login/logout event matches all of them, it is reported. + +For example, with the tt(EXTENDED_GLOB) option set, the following: + +example(watch=('^(pws|barts)')) + +causes reports for activity assoicated with any user other than tt(pws) +or tt(barts). ) vindex(WATCHFMT) item(tt(WATCHFMT))( @@ -1466,6 +1568,12 @@ The date in `var(mm)tt(/)var(dd)tt(/)var(yy)' format. item(tt(%D))( The date in `var(yy)tt(-)var(mm)tt(-)var(dd)' format. ) +item(tt(%D{)var(string)tt(}))( +The date formatted as var(string) using the tt(strftime) function, with +zsh extensions as described by +ifzman(EXPANSION OF PROMPT SEQUENCES in zmanref(zshmisc))\ +ifnzman(noderef(Prompt Expansion)). +) item(tt(%LPAR())var(x)tt(:)var(true-text)tt(:)var(false-text)tt(RPAR()))( Specifies a ternary expression. The character following the var(x) is diff --git a/Doc/Zsh/prompt.yo b/Doc/Zsh/prompt.yo index 17af5b0fb..307587678 100644 --- a/Doc/Zsh/prompt.yo +++ b/Doc/Zsh/prompt.yo @@ -93,7 +93,7 @@ continuation lines and tt(PS4) for debugging with the tt(XTRACE) option; in the latter case it will also work non-interactively. ) xitem(tt(%d)) -item(tt(/))( +item(tt(%/))( Current working directory. If an integer follows the `tt(%)', it specifies a number of trailing components of the current working directory to show; zero means the whole path. A negative integer @@ -274,7 +274,7 @@ The value of the first element of the tt(psvar) array parameter. Following the `tt(%)' with an integer gives that element of the array. Negative integers count from the end of the array. ) -item(tt(%LPAR())var(x.true-text.false-text)tt(RPAR()))( +item(tt(%LPAR())var(x)tt(.)var(true-text)tt(.)var(false-text)tt(RPAR()))( Specifies a ternary expression. The character following the var(x) is arbitrary; the same character is used to separate the text for the `true' result from that for the `false' result. @@ -364,17 +364,18 @@ level (i.e. truncations inside a `tt(%LPAR())' are separate), which ever comes first. In particular, a truncation with argument zero (e.g., `tt(%<<)') marks the end of the range of the string to be truncated while turning off truncation from there on. For example, the -prompt '%10<...<%~%<<%# ' will print a truncated representation of the +prompt `tt(%10<...<%~%<<%# )' will print a truncated representation of the current directory, followed by a `tt(%)' or `tt(#)', followed by a space. Without the `tt(%<<)', those two characters would be included -in the string to be truncated. Note that `tt(%-0<<)' is a distinct +in the string to be truncated. Note that `tt(%-0<<)' is not equivalent +to `tt(%<<)' but specifies that the prompt is truncated at the right margin. Truncation applies only within each individual line of the prompt, as delimited by embedded newlines (if any). If the total length of any line of the prompt after truncation is greater than the terminal width, or if the part to be truncated contains embedded newlines, truncation behavior is undefined and may change in a future version of the shell. Use -`tt(%-var(n)LPAR()l.var(true-text).var(false-text)RPAR())' to remove parts +`tt(%-)var(n)tt(LPAR()l.)var(true-text)tt(.)var(false-text)tt(RPAR())' to remove parts of the prompt when the available space is less than var(n). ) enditem() diff --git a/Doc/Zsh/roadmap.yo b/Doc/Zsh/roadmap.yo index ba598e5ea..bd064e2b2 100644 --- a/Doc/Zsh/roadmap.yo +++ b/Doc/Zsh/roadmap.yo @@ -41,13 +41,15 @@ set appropriate variables, and the number of history lines retained by default is quite small (30 lines). See the description of the shell variables (referred to in the documentation as parameters) tt(HISTFILE), tt(HISTSIZE) and tt(SAVEHIST) in ifzman(zmanref(zshparam))\ -ifnzman(noderef(Parameters Used By The Shell)). +ifnzman(noderef(Parameters Used By The Shell)). Note that it's +currently only possible to read and write files saving history +when the shell is interactive, i.e. it does not work from scripts. The shell now supports the UTF-8 character set (and also others if supported by the operating system). This is (mostly) handled transparently by the shell, but the degree of support in terminal emulators is variable. There is some discussion of this in the shell FAQ, -http://zsh.dotsrc.org/FAQ/ . Note in particular that for combining +uref(http://www.zsh.org/FAQ/). Note in particular that for combining characters to be handled the option tt(COMBINING_CHARS) needs to be set. Because the shell is now more sensitive to the definition of the character set, note that if you are upgrading from an older version of diff --git a/Doc/Zsh/zle.yo b/Doc/Zsh/zle.yo index 98f38025a..653678eba 100644 --- a/Doc/Zsh/zle.yo +++ b/Doc/Zsh/zle.yo @@ -40,6 +40,17 @@ the following setting: example(zle_highlight=(none)) +In many places, references are made to the tt(numeric argument). This can +by default be entered in emacs mode by holding the alt key and typing +a number, or pressing escape before each number, and in vi command mode +by typing the number before entering a command. Generally the numeric +argument causes the next command entered to be repeated the specified +number of times, unless otherwise noted below. See also +ifzman(the em(Arguments) subsection of the em(Widgets) section )\ +ifnzman(noderef(Arguments) )\ +for some other ways the numeric argument can be modified. The default +bindings mentioned here use the tt(digit-argument) widget. + startmenu() menu(Keymaps) menu(Zle Builtins) @@ -60,12 +71,14 @@ or more names. If all of a keymap's names are deleted, it disappears. findex(bindkey, use of) tt(bindkey) can be used to manipulate keymap names. -Initially, there are six keymaps: +Initially, there are eight keymaps: startsitem() sitem(tt(emacs))(EMACS emulation) sitem(tt(viins))(vi emulation - insert mode) sitem(tt(vicmd))(vi emulation - command mode) +sitem(tt(viopp))(vi emulation - operator pending) +sitem(tt(visual))(vi emulation - selection active) sitem(tt(isearch))(incremental search mode) sitem(tt(command))(read a command name) sitem(tt(.safe))(fallback keymap) @@ -122,6 +135,21 @@ in user-defined widgets with the tt(read-command) widget, described ifzman(below)\ ifnzman(in noderef(Miscellaneous) below)\ . +subsect(Local Keymaps) +cindex(local keymaps) +While for normal editing a single keymap is used exclusively, in many +modes a local keymap allows for some keys to be customised. For example, +in an incremental search mode, a binding in the tt(isearch) keymap will +override a binding in the tt(main) keymap but all keys that are not +overriden can still be used. + +If a key sequence is defined in a local keymap, it will hide a key +sequence in the global keymap that is a prefix of that sequence. An +example of this occurs with the binding of tt(iw) in tt(viopp) as this +hides the binding of tt(i) in tt(vicmd). However, a longer sequence in +the global keymap that shares the same prefix can still apply so for +example the binding of tt(^Xa) in the global keymap will be unaffected +by the binding of tt(^Xb) in the local keymap. texinode(Zle Builtins)(Zle Widgets)(Keymaps)(Zsh Line Editor) sect(Zle Builtins) @@ -295,6 +323,8 @@ sitem(tt(\t))(horizontal tab) sitem(tt(\v))(vertical tab) sitem(tt(\)var(NNN))(character code in octal) sitem(tt(\x)var(NN))(character code in hexadecimal) +sitem(tt(\u)var(NNNN))(unicode character code in hexadecimal) +sitem(tt(\U)var(NNNNNNNN))(unicode character code in hexadecimal) sitem(tt(\M)[tt(-)]var(X))(character with meta bit set) sitem(tt(\C)[tt(-)]var(X))(control character) sitem(tt(^)var(X))(control character) @@ -630,9 +660,9 @@ item(var(widget) tt([ -n) var(num) tt(]) tt([ -Nw ] [ -K) var(keymap) tt(]) var( Invoke the specified widget. This can only be done when ZLE is active; normally this will be within a user-defined widget. -With the options tt(-n) and tt(-N), the current numerical argument will be +With the options tt(-n) and tt(-N), the current numeric argument will be saved and then restored after the call to tt(widget); `tt(-n) var(num)' -sets the numerical argument temporarily to var(num), while `tt(-N)' sets it +sets the numeric argument temporarily to var(num), while `tt(-N)' sets it to the default, i.e. as if there were none. With the option tt(-K), var(keymap) will be used as the current keymap @@ -713,6 +743,21 @@ local scope, like parameters created in a function using tt(local). Inside completion widgets and traps called while ZLE is active, these parameters are available read-only. +Note that the parameters appear as local to any ZLE widget in +which they appear. Hence if it is desired to override them this needs +to be done within a nested function: + +example(widget-function+LPAR()+RPAR() { + # $WIDGET here refers to the special variable + # that is local inside widget-function + +LPAR()+RPAR() { + # This anonymous nested function allows WIDGET + # to be used as a local variable. The -h + # removes the special status of the variable. + local -h WIDGET + } +}) + startitem() vindex(BUFFER) item(tt(BUFFER) (scalar))( @@ -817,7 +862,10 @@ cursor remains between the new tt($LBUFFER) and the old tt($RBUFFER). ) vindex(MARK) item(tt(MARK) (integer))( -Like tt(CURSOR), but for the mark. +Like tt(CURSOR), but for the mark. With vi-mode operators that wait for +a movement command to select a region of text, setting tt(MARK) allows +the selection to extend in both directions from the the initial cursor +position. ) vindex(NUMERIC) item(tt(NUMERIC) (integer))( @@ -863,7 +911,9 @@ cursor remains between the old tt($LBUFFER) and the new tt($RBUFFER). vindex(REGION_ACTIVE) item(tt(REGION_ACTIVE) (integer))( Indicates if the region is currently active. It can be assigned 0 or 1 -to deactivate and activate the region respectively; +to deactivate and activate the region respectively. A value of 2 +activates the region in line-wise mode with the highlighted text +extending for whole lines only; ifzman(see em(Character Highlighting) below)\ ifnzman(noderef(Character Highlighting)). ) @@ -1040,6 +1090,7 @@ menu(Modifying Text) menu(Arguments) menu(Completion) menu(Miscellaneous) +menu(Text Objects) endmenu() texinode(Movement)(History Control)()(Zle Widgets) subsect(Movement) @@ -1049,6 +1100,11 @@ item(tt(vi-backward-blank-word) (unbound) (B) (unbound))( Move backward one word, where a word is defined as a series of non-blank characters. ) +tindex(vi-backward-blank-word-end) +item(tt(vi-backward-blank-word-end) (unbound) (gE) (unbound))( +Move to the end of the previous word, where a word is defined as a +series of non-blank characters. +) tindex(backward-char) item(tt(backward-char) (^B ESC-[D) (unbound) (unbound))( Move backward one character. @@ -1069,6 +1125,10 @@ tindex(vi-backward-word) item(tt(vi-backward-word) (unbound) (b) (unbound))( Move to the beginning of the previous word, vi-style. ) +tindex(vi-backward-word-end) +item(tt(vi-backward-word-end) (unbound) (ge) (unbound))( +Move to the end of the previous word, vi-style. +) tindex(beginning-of-line) item(tt(beginning-of-line) (^A) (unbound) (unbound))( Move to the beginning of the line. If already at the beginning @@ -1078,6 +1138,10 @@ tindex(vi-beginning-of-line) item(tt(vi-beginning-of-line))( Move to the beginning of the line, without changing lines. ) +tindex(down-line) +item(tt(down-line) (unbound) (unbound) (unbound))( +Move down a line in the buffer. +) tindex(end-of-line) item(tt(end-of-line) (^E) (unbound) (unbound))( Move to the end of the line. If already at the end @@ -1170,12 +1234,16 @@ tindex(vi-rev-repeat-find) item(tt(vi-rev-repeat-find) (unbound) (,) (unbound))( Repeat the last tt(vi-find) command in the opposite direction. ) +tindex(up-line) +item(tt(up-line) (unbound) (unbound) (unbound))( +Move up a line in the buffer. +) enditem() texinode(History Control)(Modifying Text)(Movement)(Zle Widgets) subsect(History Control) startitem() tindex(beginning-of-buffer-or-history) -item(tt(beginning-of-buffer-or-history) (ESC-<) (unbound) (unbound))( +item(tt(beginning-of-buffer-or-history) (ESC-<) (gg) (unbound))( Move to the beginning of the buffer, or if already there, move to the first event in the history list. ) @@ -1450,7 +1518,7 @@ reexamined. Note that negative numbers should be preceded by a If two arguments are given, the second specifies the word on the command line in normal array index notation (as a more natural alternative to the -prefix argument). Hence 1 is the first word, and -1 (the default) is the +numeric argument). Hence 1 is the first word, and -1 (the default) is the last word. If a third argument is given, its value is ignored, but it is used to @@ -1565,6 +1633,13 @@ Read a movement command from the keyboard, and kill from the cursor position to the endpoint of the movement. Then enter insert mode. If the command is tt(vi-change), change the current line. + +For compatibility with vi, if the command is tt(vi-forward-word) +or tt(vi-forward-blank-word), the whitespace after the word is not +included. If you prefer the more consistent behaviour with the +whitespace included use the following key binding: + +example(bindkey -a -s cw dwi) ) tindex(vi-change-eol) item(tt(vi-change-eol) (unbound) (C) (unbound))( @@ -1681,7 +1756,7 @@ item(tt(vi-open-line-below) (unbound) (o) (unbound))( Open a line below the cursor and enter insert mode. ) tindex(vi-oper-swap-case) -item(tt(vi-oper-swap-case))( +item(tt(vi-oper-swap-case) (unbound) (g~) (unbound))( Read a movement command from the keyboard, and swap the case of all characters from the cursor position to the endpoint of the movement. @@ -1704,6 +1779,13 @@ Insert the contents of the kill buffer after the cursor. If the kill buffer contains a sequence of lines (as opposed to characters), paste it below the current line. ) +tindex(put-replace-selection) +item(tt(put-replace-selection) (unbound) (unbound) (unbound))( +Replace the contents of the current region or selection with the +contents of the kill buffer. If the kill buffer contains a sequence of +lines (as opposed to characters), the current line will be split by the +pasted lines. +) tindex(quoted-insert) item(tt(quoted-insert) (^V) (unbound) (unbound))( Insert the next character typed into the buffer literally. @@ -1786,7 +1868,7 @@ tindex(yank-pop) item(tt(yank-pop) (ESC-y) (unbound) (unbound))( Remove the text just yanked, rotate the kill-ring (the history of previously killed text) and yank the new top. Only works following -tt(yank) or tt(yank-pop). +tt(yank), tt(vi-put-before), tt(vi-put-after) or tt(yank-pop). ) tindex(vi-yank) item(tt(vi-yank) (unbound) (y) (unbound))( @@ -1833,14 +1915,14 @@ spaces; if instead it is followed by tt(-2), then tt(forward-char), move backward two spaces. Inside a widget function, if passed an argument, i.e. `tt(zle -universal-argument) var(num)', the numerical argument will be set to +universal-argument) var(num)', the numeric argument will be set to var(num); this is equivalent to `tt(NUMERIC=)var(num)'. ) tindex(argument-base) item(tt(argument-base))( Use the existing numeric argument as a numeric base, which must be in the range 2 to 36 inclusive. Subsequent use of tt(digit-argument) and -tt(universal-argument) will input a new prefix in the given base. +tt(universal-argument) will input a new numeric argument in the given base. The usual hexadecimal convention is used: the letter tt(a) or tt(A) corresponds to 10, and so on. Arguments in bases requiring digits from 10 upwards are more conveniently input with tt(universal-argument), since @@ -1929,7 +2011,7 @@ When a previous completion displayed a list below the prompt, this widget can be used to move the prompt below the list. ) enditem() -texinode(Miscellaneous)()(Completion)(Zle Widgets) +texinode(Miscellaneous)(Text Objects)(Completion)(Zle Widgets) subsect(Miscellaneous) startitem() tindex(accept-and-hold) @@ -1997,9 +2079,9 @@ Reads a key sequence, then prints the function bound to that sequence. tindex(exchange-point-and-mark) item(tt(exchange-point-and-mark) (^X^X) (unbound) (unbound))( Exchange the cursor position (point) with the position of the mark. -Unless a negative prefix argument is given, the region between +Unless a negative numeric argument is given, the region between point and mark is activated so that it can be highlighted. -If a zero prefix argument is given, the region is activated but +If a zero numeric argument is given, the region is activated but point and mark are not swapped. ) tindex(execute-named-cmd) @@ -2169,7 +2251,8 @@ item(tt(send-break) (^G ESC-^G) (unbound) (unbound))( Abort the current editor function, e.g. tt(execute-named-command), or the editor itself, e.g. if you are in tt(vared). Otherwise abort the parsing of the current line; in this case the aborted line is available in the shell -variable tt(ZLE_LINE_ABORTED). +variable tt(ZLE_LINE_ABORTED). If the editor is aborted from within +tt(vared), the variable tt(ZLE_VARED_ABORTED) is set. ) tindex(run-help) item(tt(run-help) (ESC-H ESC-h) (unbound) (unbound))( @@ -2180,19 +2263,29 @@ command. tt(run-help) is normally aliased to tt(man). tindex(vi-set-buffer) item(tt(vi-set-buffer) (unbound) (") (unbound))( Specify a buffer to be used in the following command. -There are 35 buffers that can be specified: -the 26 `named' buffers tt("a) to tt("z) -and the nine `queued' buffers tt("1) to tt("9). The named buffers can also -be specified as tt("A) to tt("Z). - -When a buffer is specified for a cut command, the text being cut replaces -the previous contents of the specified buffer. If a named buffer -is specified using a capital, the newly cut text is appended to the buffer -instead of overwriting it. - -If no buffer is specified for a cut command, tt("1) is used, and the -contents of tt("1) to tt("8) are each shifted along one buffer; the contents of -tt("9) is lost. +There are 37 buffers that can be specified: +the 26 `named' buffers tt("a) to tt("z), the `yank' buffer tt("0), +the nine `queued' buffers tt("1) to tt("9) and the `black hole' buffer +tt("_). The named buffers can also be specified as tt("A) to tt("Z). + +When a buffer is specified for a cut, change or yank command, the text +concerned replaces the previous contents of the specified buffer. If +a named buffer is specified using a capital, the newly cut text is +appended to the buffer instead of overwriting it. When using the tt("_) +buffer, nothing happens. This can be useful for deleting text without +affecting the normal registers. + +If no buffer is specified for a cut or change command, tt("1) is used, and +the contents of tt("1) to tt("8) are each shifted along one buffer; +the contents of tt("9) is lost. If no buffer is specified for a yank +command, tt("0") is used. Finally, a paste command without a specified +buffer will paste the text from the most recent command regardless of any +buffer that might have been used with that command. + +When called from a widget function by the tt(zle) command, the buffer +can optionally be specified with an argument. For example, + +example(zle vi-set-buffer A) ) tindex(vi-set-mark) item(tt(vi-set-mark) (unbound) (m) (unbound))( @@ -2201,7 +2294,7 @@ Set the specified mark at the cursor position. tindex(set-mark-command) item(tt(set-mark-command) (^@) (unbound) (unbound))( Set the mark at the cursor position. If called with a negative -prefix argument, do not set the mark but deactivate the region so that +numeric argument, do not set the mark but deactivate the region so that it is no longer highlighted (it is still usable for other purposes). Otherwise the region is marked as active. ) @@ -2222,7 +2315,7 @@ This command is executed when a key sequence that is not bound to any command is typed. By default it beeps. ) tindex(undo) -item(tt(undo) (^_ ^Xu ^X^U) (unbound) (unbound))( +item(tt(undo) (^_ ^Xu ^X^U) (u) (unbound))( Incrementally undo the last text modification. When called from a user-defined widget, takes an optional argument indicating a previous state of the undo history as returned by the tt(UNDO_CHANGE_NO) variable; @@ -2233,16 +2326,30 @@ insert mode is reverted, the changes having been merged when command mode was selected. ) tindex(redo) -item(tt(redo))( +item(tt(redo) (unbound) (^R) (unbound))( Incrementally redo undone text modifications. ) tindex(vi-undo-change) -item(tt(vi-undo-change) (unbound) (u) (unbound))( +item(tt(vi-undo-change) (unbound) (unbound) (unbound))( Undo the last text modification. If repeated, redo the modification. ) +tindex(visual-mode) +item(tt(visual-mode) (unbound) (v) (unbound))( +Toggle vim-style visual selection mode. If line-wise visual mode is +currently enabled then it is changed to being character-wise. If used +following an operator, it forces the subsequent movement command to be +treated as a character-wise movement. +) +tindex(visual-line-mode) +item(tt(visual-line-mode) (unbound) (V) (unbound))( +Toggle vim-style line-wise visual selection mode. If character-wise +visual mode is currently enabled then it is changed to being line-wise. If used +following an operator, it forces the subsequent movement command to be +treated as a line-wise movement. +) tindex(what-cursor-position) -item(tt(what-cursor-position) (^X=) (unbound) (unbound))( +item(tt(what-cursor-position) (^X=) (ga) (unbound))( Print the character under the cursor, its code as an octal, decimal and hexadecimal number, the current cursor position within the buffer and the column of the cursor in the current line. @@ -2267,6 +2374,50 @@ If the last command executed was a digit as part of an argument, continue the argument. Otherwise, execute vi-beginning-of-line. ) enditem() +texinode(Text Objects)()(Miscellaneous)(Zle Widgets) +subsect(Text Objects) +cindex(text objects) +Text objects are commands that can be used to select a block of text +according to some criteria. They are a feature of the vim text editor +and so are primarily intended for use with vi operators or from visual +selection mode. However, they can also be used from vi-insert or emacs +mode. Key bindings listed below apply to the tt(viopp) and tt(visual) +keymaps. + +startitem() +tindex(select-a-blank-word) +item(tt(select-a-blank-word) (aW))( +Select a word including adjacent blanks, where a word is defined as a +series of non-blank characters. With a numeric argument, multiple words +will be selected. +) +tindex(select-a-shell-word) +item(tt(select-a-shell-word) (aa))( +Select the current command argument applying the normal rules for +quoting. +) +tindex(select-a-word) +item(tt(select-a-word) (aw))( +Select a word including adjacent blanks, using the normal vi-style word +definition. With a numeric argument, multiple words will be selected. +) +tindex(select-in-blank-word) +item(tt(select-in-blank-word) (iW))( +Select a word, where a word is defined as a series of non-blank +characters. With a numeric argument, multiple words will be selected. +) +tindex(select-in-shell-word) +item(tt(select-in-shell-word) (ia))( +Select the current command argument applying the normal rules for +quoting. If the argument begins and ends with matching quote characters, +these are not included in the selection. +) +tindex(select-in-word) +item(tt(select-in-word) (iw))( +Select a word, using the normal vi-style word definition. With a numeric +argument, multiple words will be selected. +) +enditem() texinode(Character Highlighting)()(Zle Widgets)(Zsh Line Editor) sect(Character Highlighting) @@ -2301,8 +2452,8 @@ tt(set-mark-command). The region is only highlighted if it is active, which is the case if tt(set-mark-command) or tt(exchange-point-and-mark) has been called and the line has not been subsequently modified. The region can be deactivated by calling tt(set-mark-command) with a -negative prefix argument, or reactivated by calling -tt(exchange-point-and-mark) with a zero prefix argument. Note +negative numeric argument, or reactivated by calling +tt(exchange-point-and-mark) with a zero numeric argument. Note that whether or not the region is active has no effect on its use within widgets, it simply determines whether it is highlighted. ) diff --git a/Doc/zman.yo b/Doc/zman.yo index 3329cb975..73cc186e0 100644 --- a/Doc/zman.yo +++ b/Doc/zman.yo @@ -32,6 +32,7 @@ COMMENT(--- emphasised text ---) def(em)(1)(NOTRANS(\fI)ARG1+NOTRANS(\fP)) def(bf)(1)(NOTRANS(\fB)ARG1+NOTRANS(\fP)) def(tt)(1)(NOTRANS(\fB)ARG1+NOTRANS(\fP)) +def(uref)(1)(NOTRANS(\fB)ARG1+NOTRANS(\fP)) def(var)(1)(NOTRANS(\fI)ARG1+NOTRANS(\fP)) COMMENT(--- man page headers ---) diff --git a/Doc/ztexi.yo b/Doc/ztexi.yo index 636896117..699567724 100644 --- a/Doc/ztexi.yo +++ b/Doc/ztexi.yo @@ -38,6 +38,7 @@ COMMENT(--- emphasised text ---) def(em)(1)(+NOTRANS(@emph{)ARG1+NOTRANS(})) def(bf)(1)(+NOTRANS(@cite{)ARG1+NOTRANS(})) def(tt)(1)(+NOTRANS(@t{)ARG1+NOTRANS(})) +def(uref)(1)(+NOTRANS(@t{@uref{)ARG1+NOTRANS(}})) def(var)(1)(+NOTRANS(@var{)ARG1+NOTRANS(})) COMMENT(--- man page headers ---) |