diff options
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/Makefile.in | 29 | ||||
| -rw-r--r-- | Doc/Zsh/arith.yo | 5 | ||||
| -rw-r--r-- | Doc/Zsh/builtins.yo | 138 | ||||
| -rw-r--r-- | Doc/Zsh/compsys.yo | 89 | ||||
| -rw-r--r-- | Doc/Zsh/compwid.yo | 9 | ||||
| -rw-r--r-- | Doc/Zsh/cond.yo | 6 | ||||
| -rw-r--r-- | Doc/Zsh/contrib.yo | 104 | ||||
| -rw-r--r-- | Doc/Zsh/expn.yo | 284 | ||||
| -rw-r--r-- | Doc/Zsh/files.yo | 2 | ||||
| -rw-r--r-- | Doc/Zsh/func.yo | 37 | ||||
| -rw-r--r-- | Doc/Zsh/grammar.yo | 20 | ||||
| -rw-r--r-- | Doc/Zsh/index.yo | 2 | ||||
| -rw-r--r-- | Doc/Zsh/manual.yo | 3 | ||||
| -rw-r--r-- | Doc/Zsh/mod_hlgroup.yo | 25 | ||||
| -rw-r--r-- | Doc/Zsh/mod_ksh93.yo | 243 | ||||
| -rw-r--r-- | Doc/Zsh/mod_parameter.yo | 11 | ||||
| -rw-r--r-- | Doc/Zsh/mod_pcre.yo | 19 | ||||
| -rw-r--r-- | Doc/Zsh/mod_private.yo | 15 | ||||
| -rw-r--r-- | Doc/Zsh/mod_random.yo | 56 | ||||
| -rw-r--r-- | Doc/Zsh/mod_system.yo | 16 | ||||
| -rw-r--r-- | Doc/Zsh/mod_zselect.yo | 2 | ||||
| -rw-r--r-- | Doc/Zsh/mod_zutil.yo | 68 | ||||
| -rw-r--r-- | Doc/Zsh/options.yo | 115 | ||||
| -rw-r--r-- | Doc/Zsh/params.yo | 147 | ||||
| -rw-r--r-- | Doc/Zsh/prompt.yo | 11 | ||||
| -rw-r--r-- | Doc/Zsh/restricted.yo | 4 | ||||
| -rw-r--r-- | Doc/Zsh/zle.yo | 37 | ||||
| -rw-r--r-- | Doc/intro.ms | 40 |
28 files changed, 1290 insertions, 247 deletions
diff --git a/Doc/Makefile.in b/Doc/Makefile.in index 23e5fc7e2..f68f40a9e 100644 --- a/Doc/Makefile.in +++ b/Doc/Makefile.in @@ -43,6 +43,7 @@ TEXI2DVI = @TEXI2DVI@ DVIPS = dvips TEXI2PDF = @TEXI2PDF@ TEXI2HTML = @TEXI2HTML@ +SET_TEXI2ANY_VAR = @SET_TEXI2ANY_VAR@ PAPERSIZE = @PAPERSIZE@ .SUFFIXES: .yo .1 @@ -62,11 +63,12 @@ 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_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_example.yo Zsh/mod_files.yo \ +Zsh/mod_hlgroup.yo Zsh/mod_langinfo.yo \ +Zsh/mod_ksh93.yo Zsh/mod_mapfile.yo Zsh/mod_mathfunc.yo \ Zsh/mod_nearcolor.yo Zsh/mod_newuser.yo \ Zsh/mod_parameter.yo Zsh/mod_pcre.yo Zsh/mod_private.yo \ -Zsh/mod_regex.yo Zsh/mod_sched.yo Zsh/mod_socket.yo \ +Zsh/mod_regex.yo Zsh/mod_random.yo Zsh/mod_sched.yo Zsh/mod_socket.yo \ Zsh/mod_stat.yo Zsh/mod_system.yo Zsh/mod_tcp.yo \ Zsh/mod_termcap.yo Zsh/mod_terminfo.yo \ Zsh/mod_watch.yo \ @@ -116,15 +118,20 @@ zsh.pdf zsh_a4.pdf zsh_us.pdf: $(sdir)/zsh.texi $(TEXI2PDF) -o $@ -t @afourpaper $(sdir)/zsh.texi; \ fi -# Use roff2ps / ps2pdf because pdfroff produces doubled output. intro.pdf intro.a4.pdf intro.us.pdf: $(sdir)/intro.ms if test $@ = intro.us.pdf || \ { test $@ = intro.pdf && test "$(PAPERSIZE)" = us; }; then \ - roff2ps -ms -P-pletter < $(sdir)/intro.ms > intro.ps; \ + pdfroff -mspdf --no-kill-null-pages -P-pletter --pdf-output=$@ $(sdir)/intro.ms; \ else \ - roff2ps -ms -P-pa4 < $(sdir)/intro.ms > intro.ps; \ - fi; \ - ps2pdf -sOutputFile=$@ intro.ps + pdfroff -mspdf --no-kill-null-pages -P-pa4 --pdf-output=$@ $(sdir)/intro.ms; \ + fi + +intro.html: $(sdir)/intro.ms + if groff -ms -Thtml -P-jintro $(sdir)/intro.ms > tmp.html; then \ + mv tmp.html $@; \ + else \ + rm -f tmp.html; false; \ + fi texi: $(sdir)/zsh.texi .PHONY: texi @@ -170,7 +177,7 @@ a4_ps: zsh_a4.ps zsh_a4.ps: zsh_a4.dvi $(DVIPS) -t a4 -o $@ zsh_a4.dvi -html: zsh_toc.html +html: zsh_toc.html intro.html .PHONY: html zsh_toc.html: $(sdir)/zsh.texi texi2html.conf @@ -266,7 +273,7 @@ texi2html.conf: $(sdir_top)/Config/version.mk d=`echo $(VERSION_DATE)`; \ v="<font size=\"-1\">Zsh version $(VERSION), released on $$d.</font>"; \ case '$(TEXI2HTML)' in \ - *texi2any*) echo "set_from_init_file('PRE_BODY_CLOSE','$$v');" ;; \ + *texi2any*) echo "$(SET_TEXI2ANY_VAR)('PRE_BODY_CLOSE','$$v');" ;; \ *) echo "\$$PRE_BODY_CLOSE = '$$v';" ;; \ esac > $@ @@ -407,7 +414,7 @@ uninstall.html: clean-here: rm -f *.html *.info* *.dvi *.ps *.pdf - rm -f *.aux *.cp *.cps *.fn *.fns *.ky *.log + rm -f *.aux *.cp *.cps *.fn *.fns *.ky *.kys *.log *.idx rm -f *.pg *.pgs *.toc *.tp *.tps *.vr *.vrs rm -rf infodir rm -f texi2html.conf diff --git a/Doc/Zsh/arith.yo b/Doc/Zsh/arith.yo index bc3e35ad5..9f5298821 100644 --- a/Doc/Zsh/arith.yo +++ b/Doc/Zsh/arith.yo @@ -206,6 +206,11 @@ example, example(((val2 = val1 * 2))) assigns twice the value of tt($val1) to the parameter named tt(val2). +If the expansion of tt($val1) is text rather than a number, then when +tt(val1) is referenced that text is itself evaluated as a math expression +as if surrounded by parentheses `tt(LPAR()$val1)tt(RPAR())'. Expansion +continues until there are no more parameter references, a number has +resulted, or an expression error occurs. An internal integer representation of a named parameter can be specified with the tt(integer) builtin. diff --git a/Doc/Zsh/builtins.yo b/Doc/Zsh/builtins.yo index 280f1d72a..103b6d842 100644 --- a/Doc/Zsh/builtins.yo +++ b/Doc/Zsh/builtins.yo @@ -683,6 +683,7 @@ 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. ) +findex(exec) item(tt(exec) [ tt(-cl) ] [ tt(-a) var(argv0) ] [ var(command) [ var(arg) ... ] ])( Replace the current shell with var(command) rather than forking. If var(command) is a shell builtin command or a shell function, @@ -1052,9 +1053,11 @@ The choice of hash table to work on is determined by the tt(-d) option; without the option the command hash table is used, and with the option the named directory hash table is used. -A command var(name) starting with a tt(/) is never hashed, whether by -explicit use of the tt(hash) command or otherwise. Such a command -is always found by direct look up in the file system. +A command var(name) starting with a tt(/) or with a relative path +starting with tt(./) or tt(../) is never executed by lookup in +the command hash table, and these can only be added to the table by +explicit use of the tt(hash) command. Such a command is always +found by direct look up in the file system. Given no arguments, and neither the tt(-r) or tt(-f) options, the selected hash table will be listed in full. @@ -1063,9 +1066,11 @@ The tt(-r) option causes the selected hash table to be emptied. It will be subsequently rebuilt in the normal fashion. The tt(-f) option causes the selected hash table to be fully rebuilt immediately. For the command hash table this hashes -all the absolute directories in the tt(PATH), -and for the named directory hash table this adds all users' home directories. +all (and em(only)) the absolute directories in the tt(PATH), +and for the named directory hash table this adds all users' home +directories. These two options cannot be used with any arguments. +Both options remove any explicitly-added elements. The tt(-m) option causes the arguments to be taken as patterns (which should be quoted) and the elements of the hash table @@ -1138,8 +1143,9 @@ findex(kill) cindex(killing jobs) cindex(jobs, killing) xitem(tt(kill) [ tt(-s) var(signal_name) | tt(-n) var(signal_number) | \ -tt(-)var(sig) ] var(job) ...) -item(tt(kill) tt(-l) [ var(sig) ... ])( +tt(-)var(sig) ] [ tt(-q) var(value) ] var(job) ...) +xitem(tt(kill) tt(-l) [ var(sig) ... ]) +item(tt(kill) tt(-L))( Sends either tt(SIGTERM) or the specified signal to the given jobs or processes. Signals are given by number or by names, with or without the `tt(SIG)' @@ -1153,7 +1159,8 @@ specified the signal names are listed. Otherwise, for each var(sig) that is a name, the corresponding signal number is listed. For each var(sig) that is a signal number or a number representing the exit status of a process which was terminated or -stopped by a signal the name of the signal is printed. +stopped by a signal the name of the signal is printed. The final +form with tt(-L) lists each signal name with its corresponding number. On some systems, alternative signal names are allowed for a few signals. Typical examples are tt(SIGCHLD) and tt(SIGCLD) or tt(SIGPOLL) and @@ -1165,6 +1172,9 @@ tt(kill -IO) and tt(kill -POLL) have the same effect. Many systems will allow process IDs to be negative to kill a process group or zero to kill the current process group. + +The tt(-q) option allows an integer value to be sent with the signal +on systems that support tt(sigqueue+LPAR()RPAR()). ) findex(let) item(tt(let) var(arg) ...)( @@ -1208,19 +1218,26 @@ sitem(tt(datasize))(Maximum data size (including stack) for each process.) sitem(tt(descriptors))(Maximum value for a file descriptor.) sitem(tt(filesize))(Largest single file allowed.) sitem(tt(kqueues))(Maximum number of kqueues allocated.) +sitem(tt(maxfilelocks))(Maximum number of file locks.) sitem(tt(maxproc))(Maximum number of processes.) sitem(tt(maxpthreads))(Maximum number of threads per process.) sitem(tt(memorylocked))(Maximum amount of memory locked in RAM.) sitem(tt(memoryuse))(Maximum resident set size.) sitem(tt(msgqueue))(Maximum number of bytes in POSIX message queues.) +sitem(tt(nice))(Maximum nice value.) +sitem(tt(pipebuf))(Maximum size of buffers for pipes/fifos.) sitem(tt(posixlocks))(Maximum number of POSIX locks per user.) sitem(tt(pseudoterminals))(Maximum number of pseudo-terminals.) sitem(tt(resident))(Maximum resident set size.) +sitem(tt(rt_priority))(Maximum real-time priority.) +sitem(tt(rt_time))(Maximum CPU time without a blocking system call.) sitem(tt(sigpending))(Maximum number of pending signals.) sitem(tt(sockbufsize))(Maximum size of all socket buffers.) sitem(tt(stacksize))(Maximum stack size for each process.) sitem(tt(swapsize))(Maximum amount of swap used.) +sitem(tt(umtxp))(Maximum number of POSIX thread library objects.) sitem(tt(vmemorysize))(Maximum amount of virtual memory.) +sitem(tt(vnodemonitors))(Maximum number of open vnode monitors.) endsitem() Which of these resource limits are available depends on the system. @@ -1585,7 +1602,8 @@ Input is read from the coprocess. ) item(tt(-d) var(delim))( Input is terminated by the first character of var(delim) instead of -by newline. +by newline. For compatibility with other shells, if var(delim) is an +empty string, input is terminated at the first NUL. ) item(tt(-t) [ var(num) ])( Test if input is available before attempting to read. If var(num) @@ -1628,6 +1646,7 @@ cancels both tt(-p) and tt(-u). The tt(-c) or tt(-l) flags cancel any and all of tt(-kpquz). ) +findex(readonly) cindex(parameters, marking readonly) item(tt(readonly))( Same as tt(typeset -r). With the tt(POSIX_BUILTINS) option set, same @@ -1639,7 +1658,9 @@ 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 -an arithmetic expression var(n). +an arithmetic expression var(n). Also causes a non-interctive +shell to exit, allowing files containing shell code to be used +both as scripts and as autoloadable shell functions. For example, the following prints `tt(42)': example(() { integer foo=40; return "foo + 2" } @@ -1919,6 +1940,8 @@ redef(SPACES)(0)(tt(ifztexi(NOTRANS(@ @ @ @ @ @ @ @ ))ifnztexi( ))) xitem(tt(typeset )[ {tt(PLUS())|tt(-)}tt(AHUaghlmrtux) ] \ [ {tt(PLUS())|tt(-)}tt(EFLRZip) [ var(n) ] ]) xitem(SPACES()[ tt(+) ] [ var(name)[tt(=)var(value)] ... ]) +xitem(tt(typeset ){tt(PLUS())|tt(-)}tt(n) [ tt(-g) ] \ +[ {tt(PLUS())|tt(-)}tt(r) ] [ var(name)[tt(=)var(value)] ... ]) xitem(tt(typeset )tt(-T) [ {tt(PLUS())|tt(-)}tt(Uglrux) ] [ {tt(PLUS())|tt(-)}tt(LRZp) [ var(n) ] ]) xitem(SPACES()[ tt(+) | var(SCALAR)[tt(=)var(value)] var(array)[tt(=LPAR())var(value) ...tt(RPAR())] [ var(sep) ] ]) item(tt(typeset) tt(-f) [ {tt(PLUS())|tt(-)}tt(TUkmtuz) ] [ tt(+) ] [ var(name) ... ])( @@ -1936,7 +1959,7 @@ retain their special attributes when made local. For each var(name)tt(=)var(value) assignment, the parameter var(name) is set to var(value). If the assignment is omitted and var(name) -does em(not) refer to an existing parameter, a new parameter is intialized +does em(not) refer to an existing parameter, a new parameter is initialized to empty string, zero, or empty array (as appropriate), em(unless) the shell option tt(TYPESET_TO_UNSET) is set. When that option is set, the parameter attributes are recorded but the parameter remains unset. @@ -2032,6 +2055,38 @@ To initialize a parameter var(param) to a command output and mark it readonly, use tt(typeset -r )var(param) or tt(readonly )var(param) after the parameter assignment statement. +cindex(named reference) +cindex(reference, named) +The flag tt(-n) creates a em(named reference) to another parameter. +The second parameter need not exist at the time the reference is +created. Only the tt(-H), tt(-g), and tt(-r) flags may be used in +conjunction with tt(-n), having their usual meanings. The tt(-u) +flag is special and may be applied to alter the scope of the reference. +The var(name) so created may not be an array element nor use +a subscript, but the var(value) assigned may be any valid parameter +name syntax, even a subscripted array element (including an associative +array element) or an array slice, which is evaluated when the named +reference is expanded. It is an error for a named reference to refer +to itself, even indirectly through a chain of references. When tt(-u) +is applied to a named reference, the parameter identified by var(value) +is always found in the calling function scope rather than the current +local scope. In this case, if there is no such parameter in the calling +scope, assignments to the named reference may fail, setting tt($?) to 1. +See ifzman(zmanref(zshexpn))ifnzman(noderef(Parameter Expansion)) and +ifzman(zmanref(zshparam))ifnzman(noderef(Parameters)) for details of the +behavior of named references. + +Local function scoping rules for `tt(typeset)' do apply with `tt(-n)', +so a declaration within a function persists only until the end of the +function unless `tt(-g -n)' is specified, and any local parameter (of +any type) with the same var(name) supplants a named reference from a +surrounding scope. + +A scalar parameter, including an existing named reference, may be +converted to a new named reference by `tt(typeset -n )var(name)', so +the `tt(-p)' option must be included to display the value of a +specific named reference var(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), @@ -2047,8 +2102,9 @@ 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 +the values (function bodies) are not. If var(name) arguments appear, +both those names and their values are printed in the form of assignments. +It is an error for any other options to follow `tt(PLUS())', but 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 @@ -2075,13 +2131,15 @@ 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. +tt(-m) applies all other flags or assignments to the existing parameters, +except that the tt(-n) option cannot create named references in this way. 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. +does not. Ordinary scalar string parameters have no attributes, so for +those tt(+m) prints only the names. ) item(tt(-p) [ var(n) ])( If the tt(-p) option is given, parameters and values are printed in the @@ -2093,6 +2151,14 @@ tt(-p) may be followed by an optional integer argument. Currently only the value tt(1) is supported. In this case arrays and associative arrays are printed with newlines between indented elements for readability. + +The names and values of readonly special parameters +(most of the parameters marked `<S>' in +ifzman(zmanref(zshparam))ifnzman(noderef(Parameters Set By The Shell)), +except those documented as settable) +are not printed with `tt(-)tt(p)' because to execute those typeset commands +would cause errors. However, these parameters are printed when they +have been made local to the scope where `tt(typeset -p)' is run. ) item(tt(-T) [ var(scalar)[tt(=)var(value)] var(array)[tt(=LPAR())var(value) ...tt(RPAR())] [ var(sep) ] ])( This flag has a different meaning when used with tt(-f); see below. @@ -2229,15 +2295,15 @@ special tt(PATH) parameter is not altered in any way. It is also possible to create a local parameter using `tt(typeset +h )var(special)', where the local copy of var(special) will retain its special properties regardless of having the tt(-h) attribute. Global special parameters loaded from shell -modules (currently those in tt(zsh/mapfile) and tt(zsh/parameter)) are +modules (for example, those in tt(zsh/mapfile) and tt(zsh/parameter)) are automatically given the tt(-h) attribute to avoid name clashes. ) item(tt(-H))( Hide value: specifies that tt(typeset) will not display the value of the parameter when listing parameters; the display for such parameters is -always as if the `tt(PLUS())' flag had been given. Use of the parameter is -in other respects normal, and the option does not apply if the parameter is -specified by name, or by pattern with the tt(-m) option. This is on by +always as if the `tt(PLUS())' flag were given, but use of the parameter is +in other respects normal. This effect does not apply when the parameter is +specified by name or by pattern with the tt(-m) option. This is on by default for the parameters in the tt(zsh/parameter) and tt(zsh/mapfile) modules. Note, however, that unlike the tt(-h) flag this is also useful for non-special parameters. @@ -2284,13 +2350,15 @@ readonly). Special variables that have been made readonly retain their value and readonly attribute when made local. ) item(tt(-t))( -Tags the named parameters. Tags have no special meaning to the shell. -This flag has a different meaning when used with tt(-f); see above. +Tags the named parameters. Tags only exist to flag the parameter for +the user's own purposes --- the list of tagged parameters can be queried +using `tt(typeset -t)'. Tags have no other use. Note that the tt(-t) +flag has a different meaning when used with tt(-f); see above. ) item(tt(-u))( Convert the result to upper case whenever the parameter is expanded. The value is em(not) converted when assigned. -This flag has a different meaning when used with tt(-f); see above. +This flag has different meanings when used with tt(-f) or tt(-n); see above. ) item(tt(-x))( Mark for automatic export to the environment of subsequently @@ -2329,16 +2397,18 @@ Not all the following resources are supported on all systems. Running tt(ulimit -a) will show which are supported. startsitem() -sitem(tt(-a))(Lists all of the current resource limits.) +sitem(tt(-a))(List all of the current resource limits.) sitem(tt(-b))(Socket buffer size in bytes LPAR()N.B. not kilobytes+RPAR()) sitem(tt(-c))(512-byte blocks on the size of core dumps.) sitem(tt(-d))(Kilobytes on the size of the data segment.) +sitem(tt(-e))(Maximum nice value.) sitem(tt(-f))(512-byte blocks on the size of files written.) sitem(tt(-i))(The number of pending signals.) sitem(tt(-k))(The number of kqueues allocated.) sitem(tt(-l))(Kilobytes on the size of locked-in memory.) sitem(tt(-m))(Kilobytes on the size of physical memory.) -sitem(tt(-n))(open file descriptors.) +sitem(tt(-n))(Open file descriptors.) +sitem(tt(-o))(Maximum number of POSIX thread library objects.) sitem(tt(-p))(The number of pseudo-terminals.) sitem(tt(-q))(Bytes in POSIX message queues.) sitem(tt(-r))(Maximum real time priority. On some systems where this @@ -2352,6 +2422,7 @@ sitem(tt(-v))(Kilobytes on the size of virtual memory. On some systems this refers to the limit called `address space'.) sitem(tt(-w))(Kilobytes on the size of swapped out memory.) sitem(tt(-x))(The number of locks on files.) +sitem(tt(-y))(Maximum size of buffers for pipes/fifos.) endsitem() A resource may also be specified by integer in the form `tt(-N) @@ -2375,6 +2446,7 @@ the mask is printed as an octal number. Note that in the symbolic form the permissions you specify are those which are to be allowed (not denied) to the users specified. ) +findex(unalias) cindex(aliases, removing) item(tt(unalias) [ tt(-ams) ] var(name) ...)( Removes aliases. This command works the same as tt(unhash -a), except that @@ -2416,7 +2488,7 @@ with the command `tt(zmodload -F zsh/rlimits b:unlimit)'. ) findex(unset) cindex(parameters, unsetting) -item(tt(unset) [ tt(-fmv) ] var(name) ...)( +item(tt(unset) [ tt(-fmv) ] [ tt(-n) ] var(name) ...)( Each named parameter is unset. Local parameters remain local even if unset; they appear unset within scope, but the previous value will still reappear when the scope ends. @@ -2430,10 +2502,13 @@ be quoted) and all parameters with matching names are unset. Note that this cannot be used when unsetting associative array elements, as the subscript will be treated as part of the pattern. -The tt(-v) flag specifies that var(name) refers to parameters. This is the -default behaviour. +The tt(-v) flag specifies that var(name) refers to parameters. This is +the default behaviour. If the tt(-n) option is supplied, and +var(name) is a a named reference, var(name) will be unset rather than +the variable it references. -tt(unset -f) is equivalent to tt(unfunction). +tt(unset -f) is equivalent to tt(unfunction). The tt(-n) option has +no effect with tt(-f). ) findex(unsetopt) cindex(options, unsetting) @@ -2521,11 +2596,14 @@ item(tt(-a))( Do a search for all occurrences of var(name) throughout the command path. Normally only the first occurrence is printed. +When combined with tt(-m), only names appearing in the command hash +table are searched, but all occurrences of those names are printed. ) item(tt(-m))( The arguments are taken as patterns (pattern characters should be -quoted), and the information is displayed for each command matching one -of these patterns. +quoted), and the information is displayed for each entry in the command +hash table matching one of these patterns. The hash table is first +refilled, in case of changes to tt(PATH). ) item(tt(-s))( If a pathname contains symlinks, print the symlink-free pathname as well. diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo index 584ede441..06b08cc72 100644 --- a/Doc/Zsh/compsys.yo +++ b/Doc/Zsh/compsys.yo @@ -89,9 +89,9 @@ menu(Initialization) menu(Completion System Configuration) menu(Control Functions) menu(Bindable Commands) -menu(Completion Functions) -menu(Completion Directories) +menu(Utility Functions) menu(Completion System Variables) +menu(Completion Directories) endmenu() texinode(Initialization)(Completion System Configuration)()(Completion System) @@ -2023,8 +2023,8 @@ position shown as a percentage of the total length otherwise. In each case the form with the uppercase letter will be replaced by a string of fixed width, padded to the right with spaces, while the lowercase form will be replaced by a variable width string. As in other prompt strings, the -escape sequences `tt(%S)', `tt(%s)', `tt(%B)', `tt(%b)', `tt(%U)', -`tt(%u)' for entering and leaving the display modes +escape sequence `tt(%H)` along with `tt(%S)', `tt(%s)', `tt(%B)', `tt(%b)', +`tt(%U)', `tt(%u)' for entering and leaving the display modes standout, bold and underline, and `tt(%F)', `tt(%f)', `tt(%K)', `tt(%k)' for changing the foreground background colour, are also available, as is the form `tt(%{)...tt(%})' for enclosing escape sequences which display with zero @@ -3363,7 +3363,7 @@ endsitem() ) enditem() -texinode(Bindable Commands)(Completion Functions)(Control Functions)(Completion System) +texinode(Bindable Commands)(Utility Functions)(Control Functions)(Completion System) sect(Bindable Commands) cindex(completion system, bindable commands) @@ -3562,7 +3562,7 @@ emacs and vi respectively. ) enditem() -texinode(Completion Functions)(Completion System Variables)(Bindable Commands)(Completion System) +texinode(Utility Functions)(Completion System Variables)(Bindable Commands)(Completion System) sect(Utility Functions) cindex(completion system, utility functions) @@ -4290,6 +4290,14 @@ arguments. The first describes the first argument as a be completed. The last description gives all other arguments the description `var(page number)' but does not offer completions. ) +findex(_as_if) +item(tt(_as_if) var(command) [var(arg) ... ])( +This function is useful when one command should be completed as if it were +another command with particular arguments. For example to complete tt(foo) as +if it were tt(bar --baz), use + +example(compdef '_as_if bar --baz' foo) +) findex(_cache_invalid) item(tt(_cache_invalid) var(cache_identifier))( This function returns status zero if the completions cache corresponding to @@ -4389,8 +4397,10 @@ the functions for the fields if they are called. findex(_command_names) item(tt(_command_names) [ tt(-e) | tt(-) ])( This function completes words that are valid at command position: names of -aliases, builtins, hashed commands, functions, and so on. With the tt(-e) -flag, only hashed commands are completed. The tt(-) flag is ignored. +aliases, builtins, hashed commands, functions, and so on. If the tt(-e) +flag is given, or if the list of precommands contains a non-builtin command +(e.g. because tt(_normal -p) has been used previously), only hashed commands +are completed. The tt(-) flag is ignored. ) findex(_comp_locale) item(tt(_comp_locale))( @@ -4776,7 +4786,11 @@ functions) regardless of prior precommands (e.g. `tt(zsh -c)'). ) item(tt(-p) var(precommand))( Append var(precommand) to the list of precommands. This option should be -used in nearly all cases in which tt(-P) is not applicable. +used in nearly all cases in which tt(-P) is not applicable. An advantage +of using this option is that it can automatically signal to +tt(_command_names) that subsequent completion should be limited to hashed +commands, which is usually the desired behaviour following commands like +tt(chroot) and tt(nohup). ) enditem() @@ -5227,6 +5241,57 @@ the group name. This function is called automatically from tt(_description) and hence is not normally called explicitly. ) +findex(_shadow) +findex(_unshadow) +xitem(tt(_shadow) [ tt(-s) var(suffix) ] [ -- ] var(command_name) ...) +item(tt(_unshadow))( +The tt(_shadow) function creates a copy of each of the shell functions +in the var(command_name) arguments. The original functions can then +be replaced by new implementations. A later call to tt(_unshadow) +removes the new implementations, if any, and restores the originals. + +Recommended usage is to pair tt(_shadow) and tt(_unshadow) calls by +use of an `tt(always)' block: +example({ + _shadow fname + function fname { + # Do your new thing + } + # Invoke callers of fname +} always { + _unshadow +}) + +The var(suffix), if supplied, is prepended by an `tt(@)' character and +then appended to each var(command_name) to create the copy. Thus +example(_shadow -s XX foo) +creates a function named `tt(foo@XX)'. This provides a well-known +name for the original implementation if the new implementation needs +to call it as a wrapper. If a nested call to tt(_shadow) uses the +same var(suffix), em(no new copy is made). The presumption thus is +that suffixes and new implementations correspond one to one. + +If var(command_name) is a builtin or external command, and there has been +no preceding tt(_shadow) replacement made, the function so created calls +the shadowed name prefixed by the tt(builtin) or tt(command) keywords as +appropriate. +example({ + _shadow -s wrap compadd + compadd LPAR()RPAR() { + # compadd@wrap runs builtin compadd + compadd@wrap -O tmparr "$@" } +} always { + _unshadow +}) + +When no var(suffix) argument is present, tt(_shadow) creates a unique +suffix to avoid name collisions. + +Arguments of tt(_unshadow) are ignored. Every listed var(command_name) +for the most recent call to tt(_shadow) is removed. This differs from +an early implementation that required tt(_unshadow) to receive the +same var(suffix) and var(command_name) list as tt(_shadow). +) findex(_store_cache) item(tt(_store_cache) var(cache_identifier) var(param) ...)( This function, together with tt(_retrieve_cache) and @@ -5397,10 +5462,6 @@ example(local expl _wanted tag expl 'description' \ compadd -- var(match1) var(match2)...) -See also the use of tt(_wanted) in the example function in -ifzman(the subsection `Dynamic named directories' in zmanref(zshexpn))\ -ifnzman(noderef(Dynamic named directories)). - Note that, as for tt(_requested), the var(command) must be able to accept options to be passed down to tt(compadd). @@ -5420,7 +5481,7 @@ ifnzman(noderef(The zsh/zleparameter Module)). ) enditem() -texinode(Completion System Variables)(Completion Directories)(Completion Functions)(Completion System) +texinode(Completion System Variables)(Completion Directories)(Utility Functions)(Completion System) sect(Completion System Variables) cindex(completion system, variables) diff --git a/Doc/Zsh/compwid.yo b/Doc/Zsh/compwid.yo index d32a0702f..b0c9b0a5f 100644 --- a/Doc/Zsh/compwid.yo +++ b/Doc/Zsh/compwid.yo @@ -112,7 +112,7 @@ vindex(QIPREFIX) item(tt(QIPREFIX))( This parameter is read-only and contains the quoted string up to the word being completed. E.g. when completing `tt("foo)', this parameter -contains the double quote. If the tt(-q) option of tt(compset) is used +contains the double quote. If the tt(-q) option of tt(compset) is used (see below), and the original string was `tt("foo bar)' with the cursor on the `tt(bar)', this parameter contains `tt("foo )'. ) @@ -597,7 +597,8 @@ ifnzman((see noderef(Prompt Expansion)))\ ifzman(as described in the section EXPANSION OF PROMPT SEQUENCES in zmanref(zshmisc)): `tt(%B)', `tt(%S)', `tt(%U)', `tt(%F)', `tt(%K)' and their lower case -counterparts, as well as `tt(%{)...tt(%})'. `tt(%F)', `tt(%K)' and +counterparts, as well as `tt(%H)' and `tt(%{)...tt(%})'. `tt(%F)', +`tt(%K)', `tt(%H)' and `tt(%{)...tt(%})' take arguments in the same form as prompt expansion. (Note that the sequence `tt(%G)' is not available; an argument to `tt(%{)' should be used instead.) The sequence `tt(%%)' @@ -1082,8 +1083,8 @@ enditem() ) xitem(tt(l:)tt(|)var(word-pat)tt(=)var(match-pat)) xitem(tt(L:)tt(|)var(word-pat)tt(=)var(match-pat)) -xitem(tt(R:)var(word-pat)tt(|)tt(=)var(match-pat)) -item(tt(r:)var(word-pat)tt(|)tt(=)var(match-pat))( +xitem(tt(r:)var(word-pat)tt(|)tt(=)var(match-pat)) +item(tt(R:)var(word-pat)tt(|)tt(=)var(match-pat))( If there is a substring at the tt(l:)eft or tt(r:)ight edge of the current word that matches var(word-pat), then broaden the corresponding part of the match diff --git a/Doc/Zsh/cond.yo b/Doc/Zsh/cond.yo index 000e576d0..db92cc766 100644 --- a/Doc/Zsh/cond.yo +++ b/Doc/Zsh/cond.yo @@ -241,7 +241,11 @@ ifnzman(\ noderef(Filename Generation)\ )\ , but there is no special behaviour -of `tt(/)' nor initial dots, and no glob qualifiers are allowed. +of `tt(/)' nor initial dot, and the patterns `tt(**/)' and `tt(***/)' behave +the same as `tt(*/)', in which the `tt(*)' has its standard behaviour +but may also match further `tt(/)' characters. Also, no bare glob +qualifiers are allowed, though the form `((#q)var(...))' is allowed as +shown above. In each of the above expressions, if var(file) is of the form `tt(/dev/fd/)var(n)', diff --git a/Doc/Zsh/contrib.yo b/Doc/Zsh/contrib.yo index 0ef59dbc9..c1bea6022 100644 --- a/Doc/Zsh/contrib.yo +++ b/Doc/Zsh/contrib.yo @@ -2448,6 +2448,33 @@ history is restricted, so cursor motions, etc., may not pass outside of the pasted content. Text assigned to tt(BUFFER) by the active widgets is copied back into tt(PASTED) before tt(paste-finish). ) +tindex(bracketed-paste-url-magic) +item(tt(bracketed-paste-url-magic))( +This widget is a simpler version of using tt(bracketed-paste-magic) +to enable tt(quote-url-magic). Rather than re-interpreting everything as +keystrokes, it simply handles quoting of pasted urls itself, and all other +text is handled like the default bracketed-paste widget. + +It limits the quoting to pastes that consist of a single url, but you +can also enable or disable quoting explicitly for a paste by setting +NUMERIC to 1 or 2 respectively (ie, by pressing alt-1 or alt-2 before +pasting). + +It is also possible to customize the list of schemas used to +decide if something is a url by setting the tt(schema) style in the +tt(:bracketed-paste-url-magic) context, for example: +ifzman() +example(zstyle :bracketed-paste-url-magic schema http:// myspecialschema:) + +The default list of schemas is tt(http:// https:// ftp:// ftps:// file:// \ + ssh:// sftp:// magnet:). + +The widget itself is installed in a similar way as +tt(bracketed-paste-magic) above, by +ifzman() +example(autoload -Uz bracketed-paste-url-magic +zle -N bracketed-paste bracketed-paste-url-magic) +) tindex(copy-earlier-word) item(tt(copy-earlier-word))( This widget works like a combination of tt(insert-last-word) and @@ -2593,12 +2620,33 @@ zle -N history-pattern-search-forward history-pattern-search) tindex(incarg) 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 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. +This widget allows you to increment integers on the current line. In addition +to decimals, it can handle hexadecimals prefixed with tt(0x), binaries with +tt(0b), and octals with tt(0o). + +By default, the target integer will be incremented by one. With a numeric +argument, the integer is incremented by the amount of the argument. The shell +parameter tt(incarg) may be set to change the default increment to something +other than one. + +The behavior of this widget changes depending on the widget name. + +When the widget is named tt(incarg), the widget will increment an integer +placed under the cursor placed or just to the left of it. tt(decarg), on the +other hand, decrements the integer. When the name is prefixed with tt(vi), +the cursor will jump to the nearest integer after the cursor before incrementing +it. The tt(vi) prefix can also be combined with a tt(backward-) prefix to make +the widget search backwards for numbers. + +There's also a tt(sync-) prefix that can be added to the widget name. This +variant is used for creating a sequence of numbers on split terminals with +synchronized key input. The first pane won't increment the integer at all, but +each pane after that will have the integer incremented once more than the +previous pane. It currently supports tmux and iTerm2. + +The prefixes tt(vi), tt(backward-), and tt(sync-) can be combined, for example, +into tt(vim-sync-) or tt(vim-backward-sync-). The tt(vi) prefix needs to be +at the very beginning. example(bindkey '^X+' incarg) ) @@ -3972,8 +4020,11 @@ calculation is stored. For example, the result of the calculation on the line preceded by `tt(4> )' is available as tt($4). The last value calculated is available as tt(ans). Full command line editing, including the history of previous calculations, is available; the history is saved in -the file tt(~/.zcalc_history). To exit, enter a blank line or type `tt(:q)' -on its own (`tt(q)' is allowed for historical compatibility). +the file tt($ZCALC_HISTFILE). If tt($ZCALC_HISTFILE) is unset, +tt($ZDOTDIR/.zcalc_history) is used instead, which in turn falls backs to +tt($HOME/.zcalc_history) if tt($ZDOTDIR) is unset. To exit, enter a blank +line or type `tt(:q)' on its own (`tt(q)' is allowed for historical +compatibility). A line ending with a single backslash is treated in the same fashion as it is in command line editing: the backslash is removed, the @@ -4262,13 +4313,17 @@ tt(colors) more than once. The eight base colors are: tt(black), tt(red), tt(green), tt(yellow), tt(blue), tt(magenta), tt(cyan), and tt(white). Each of these has codes for foreground and background. In addition there are seven intensity attributes: -tt(bold), tt(faint), tt(standout), tt(underline), tt(blink), tt(reverse), +tt(bold), tt(faint), tt(italic), tt(underline), tt(blink), tt(reverse), and tt(conceal). Finally, there are seven codes used to negate attributes: tt(none) (reset all attributes to the defaults), tt(normal) -(neither bold nor faint), tt(no-standout), tt(no-underline), tt(no-blink), +(neither bold nor faint), tt(no-italic), tt(no-underline), tt(no-blink), tt(no-reverse), and tt(no-conceal). Some terminals do not support all combinations of colors and intensities. +Prior to zsh tt(5.8.1) the intensity tt(standout) was provided. It has +been replaced by the more specific tt(italic) and tt(reverse) to match +the specification, but some terminals may swap these or make one of them +produce blinking text even if the tt(blink) code is not usable. The associative arrays are: @@ -4333,6 +4388,27 @@ example(is-at-least 3.1.6-15 && setopt NO_GLOBAL_RCS is-at-least 3.1.0 && setopt HIST_REDUCE_BLANKS is-at-least 2.6-17 || print "You can't use is-at-least here.") ) +findex(mkshadow) +findex(rmshadow) +xitem(tt(mkshadow) [ tt(-s) var(suffix) ] [ -- ] var(command_name) ...) +item(tt(rmshadow))( +These functions are an interface to the tt(_shadow) and tt(_unshadow) +completion utilities to make them more easily accessible in other +contexts. Usage is exactly as for the completion utility: +example({ + mkshadow fname + function fname { + # Do your new thing + } + # Invoke callers of fname +} always { + rmshadow +}) + +Upon return, the value of tt($REPLY) is the suffix used to create a +copy of the original var(command_name), so var(command_name)tt(@$REPLY) +invokes that original. +) findex(nslookup) item(tt(nslookup) [ var(arg) ... ])( This wrapper function for the tt(nslookup) command requires the @@ -4617,10 +4693,10 @@ renames `tt(foo.lis)' to `tt(foo.txt)', `tt(my.old.stuff.lis)' to The pattern is always treated as an tt(EXTENDED_GLOB) pattern. Any file whose name is not changed by the substitution is simply ignored. Any -error (a substitution resulted in an empty string, two substitutions gave -the same result, the destination was an existing regular file and tt(-f) -was not given) causes the entire function to abort without doing -anything. +error (no files matched the var(srcpat), substitution resulted in an empty +string, two substitutions gave the same result, the destination was an +existing regular file and tt(-f) was not given) causes the entire function +to abort without doing anything. In addition to pattern replacement, the variable tt($f) can be referred to in the second (replacement) argument. This makes it possible to diff --git a/Doc/Zsh/expn.yo b/Doc/Zsh/expn.yo index eb8cdbae5..7eade4a11 100644 --- a/Doc/Zsh/expn.yo +++ b/Doc/Zsh/expn.yo @@ -312,7 +312,8 @@ zero) that are neither `tt(.)' nor `tt(/)' and that continue to the end of the string. For example, the extension of `tt(foo.orig.c)' is `tt(.c)', and `tt(dir.c/foo)' has no extension. ) -item(tt(s/)var(l)tt(/)var(r)[tt(/)])( +xitem(tt(s/)var(l)tt(/)var(r)[tt(/)]) +item(tt(S/)var(l)tt(/)var(r)[tt(/)])( Substitute var(r) for var(l) as described below. The substitution is done only for the first string that matches var(l). For arrays and for filename @@ -324,13 +325,17 @@ perform global substitution, i.e. substitute every occurrence of var(r) for var(l). Note that the tt(g) or tt(:G) must appear in exactly the position shown. +The use of tt(S) instead of tt(s) is identical except that +the source is treated as a pattern, just as if the option +tt(HIST_SUBST_PATTERN) were set. + See further notes on this form of substitution below. ) item(tt(&))( -Repeat the previous tt(s) substitution. Like tt(s), may be preceded -immediately by a tt(g). In parameter expansion the tt(&) must appear -inside braces, and in filename generation it must be quoted with a -backslash. +Repeat the previous tt(s) or tt(S) substitution, whichever was most +recent. Like tt(s) and tt(S), may be preceded immediately by a tt(g). +In parameter expansion the tt(&) must appear inside braces, and in +filename generation it must be quoted with a backslash. ) item(tt(t) [ var(digits) ])( Remove all leading pathname components, leaving the final component (tail). @@ -377,7 +382,8 @@ substitutions or expansions are performed once at the time the qualifier is parsed, even before the `tt(:s)' expression itself is divided into var(l) and var(r) sides. -If the option tt(HIST_SUBST_PATTERN) is set, var(l) is treated as +If the option tt(HIST_SUBST_PATTERN) is set or the original substitution +was started with a capital tt(S), var(l) is treated as a pattern of the usual form described in ifzman(the section FILENAME GENERATION below)\ ifnzman(noderef(Filename Generation)). This can be used in @@ -604,6 +610,16 @@ and other operators, such as `tt(${PREFIX:-"/usr/local"})'. Parameter expansions can also be nested. These topics will be introduced below. The full rules are complicated and are noted at the end. +cindex(namespace) +Parameter expansions may optionally include a em(namespace) prefix in +the format `tt(.)var(identifier)tt(.)' This currently has no special +meaning to the shell, but provides a convenient means of grouping +related parameters. Expansions using a namespace em(must) include +braces (tt({) and tt(})) as shown in the descriptions below, and +only one namespace prefix is allowed. Note that, for support of +possible future features, the first `tt(.)' is optional, but omitting +it is discouraged. + In the expansions discussed below that require a pattern, the form of the pattern is the same as that used for filename generation; see noderef(Filename Generation). Note that these patterns, along with @@ -616,6 +632,8 @@ substitution on the expansion of parameter tt($i). In the following descriptions, `var(word)' refers to a single word substituted on the command line, not necessarily a space delimited word. +The reference to `var(name)' in each description presumes any optional +namespace prefix. startitem() item(tt(${)var(name)tt(}))( @@ -665,7 +683,9 @@ item(tt(${)var(name)tt(:?)var(word)tt(}))( In the first form, if var(name) is set, or in the second form if var(name) is both set and non-null, then substitute its value; otherwise, print var(word) and exit from the shell. Interactive shells instead return to -the prompt. If var(word) is omitted, then a standard message is printed. +the prompt. If var(word) is omitted, then a standard message is +printed. Note that var(word) is expanded even though its value +is not substituted onto the command line. ) enditem() @@ -967,6 +987,11 @@ means the same thing as the more readable `(tt(%%qqq))'. The following flags are supported: startitem() +item(tt(!))( +When the parameter being expanded is a named reference, the reference +itself is examined and thus is em(not) resolved to its referent. In +ksh emulation, the parens around this flag are optional. +) item(tt(#))( Evaluate the resulting words as numeric expressions and interpret these as character codes. Output the corresponding characters. Note @@ -1093,7 +1118,7 @@ tt(KSH_ARRAYS) option a subscript `tt([*])' or `tt([@])' is needed to operate on the whole array, as usual. ) item(tt(L))( -Convert all letters in the result to lower case. +Convert all letters in the result to lower case, like `tt(typeset -l)'. ) item(tt(n))( Sort decimal integers numerically; if the first differing @@ -1177,34 +1202,35 @@ of the parameter would usually appear. This string consists of keywords separated by hyphens (`tt(-)'). The first keyword in the string describes the main type, it can be one of `tt(scalar)', `tt(array)', `tt(integer)', `tt(float)' or `tt(association)'. The other keywords describe the type in -more detail: +more detail, in most cases corresponding to options of the `tt(typeset)' +command: startitem() item(tt(local))( for local parameters ) item(tt(left))( -for left justified parameters +for left justified parameters (tt(-L)) ) item(tt(right_blanks))( -for right justified parameters with leading blanks +for right justified parameters with leading blanks (tt(-R)) ) item(tt(right_zeros))( -for right justified parameters with leading zeros +for right justified parameters with leading zeros (tt(-Z)) ) item(tt(lower))( for parameters whose value is converted to all lower case when it is -expanded +expanded (tt(-l)) ) item(tt(upper))( for parameters whose value is converted to all upper case when it is -expanded +expanded (tt(-u)) ) item(tt(readonly))( -for readonly parameters +for readonly parameters (tt(-r)) ) item(tt(tag))( -for tagged parameters +for tagged parameters (tt(-t)) ) item(tt(tied))( for parameters tied to another parameter in the manner of tt(PATH) @@ -1212,16 +1238,20 @@ for parameters tied to another parameter in the manner of tt(PATH) special parameters or user-defined with `tt(typeset -T)' ) item(tt(export))( -for exported parameters +for exported parameters (tt(-x) or `tt(export)') ) item(tt(unique))( -for arrays which keep only the first occurrence of duplicated values +for arrays which keep only the first occurrence of duplicated values (tt(-U)) ) item(tt(hide))( -for parameters with the `hide' flag +for parameters with the `hide' flag (tt(-h)) ) item(tt(hideval))( -for parameters with the `hideval' flag +for parameters with the `hideval' flag (tt(-H)) +) +item(tt(nameref))( +for named references (tt(typeset -n)) either having an empty value or +when combined with `tt(!)' as in `tt(${LPAR()!t)tt(RPAR()var(rname)})' ) item(tt(special))( for special parameters defined by the shell @@ -1229,10 +1259,10 @@ for special parameters defined by the shell enditem() ) item(tt(u))( -Expand only the first occurrence of each unique word. +Expand only the first occurrence of each unique word, like `tt(typeset -U)'. ) item(tt(U))( -Convert all letters in the result to upper case. +Convert all letters in the result to upper case, like `tt(typeset -u)'. ) item(tt(v))( Used with tt(k), substitute (as two consecutive words) both the key @@ -1520,6 +1550,103 @@ Include the unmatched portion in the result (the em(R)est). ) enditem() +subsect(Named References) +cindex(named references) +cindex(namerefs) +cindex(reference variables) +cindex(parameters, nameref) +The command +ifzman() +indent(tt(typeset -n )var(pname)tt(=)var(rname)) + +initializes a parameter var(pname) as a reference to a second +parameter var(rname). With the few exceptions described here, when +var(pname) is used in any of the expansion forms described above, the +parameter var(rname) is expanded instead. This is similar to the +action of the `tt((P))' expansion flag, but when var(rname) has itself +been declared a named reference, that third parameter referenced by +var(pname) is also expanded, and so on. With `tt((P))' this must be +done explicitly, so for example +tt(${LPAR()P)tt(RPAR()${LPAR()P)tt(RPAR())var(name)tt(}}). + +Unlike `tt((P))', named references in substitutions that perform +assignment, such as tt(${)var(pname)tt(::=)var(word)tt(}), do not +create new arrays when var(rname) is in the form of an array element +or slice and no such array (or associative array) is presently set. +This includes arrays declared, but not initialized, when the option +tt(TYPESET_TO_UNSET) is in effect. The var(word) is substituted but +no assignment occurs. + +Also unlike `tt((P))' named references always expand parameters at +the scope in which var(rname) existed when `tt(typeset -n)' was +called. This can be used to expand or assign parameters from an +earlier scope even if a local of the same name has been declared at +a later scope. Example: +ifzman() +example(tt(caller=OUTER) +tt(func LPAR()RPAR() {) +tt( print before local: $caller) +tt( typeset -n outer=$1) +tt( local caller=INNER) +tt( print by reference: $outer) +tt( outer=RESULT) +tt(}) +tt(func caller) +tt(print after func: $caller)) + +displays the output +ifzman() +example(tt(before local: OUTER) +tt(by reference: OUTER) +tt(after func: RESULT)) + +To force a named reference to refer to the outer scope, even if a local +has already been declared, add the tt(-u) option when declaring the +named reference. In this case var(rname) should already exist in the +outer scope, otherwise the behavior of assignment through var(pname) +is not defined and may change the scope of the reference or fail with +a status of 1. Example of correct usage: +ifzman() +example(tt(caller=OUTER) +tt(func LPAR()RPAR() {) +tt( print before local: $caller) +tt( local caller=INNER) +tt( print after local: $caller) +tt( typeset -n -u outer=$1) +tt( print by reference: $outer) +tt( outer=RESULT) +tt(}) +tt(func caller) +tt(print after func: $caller)) + +Note, however, that named references to em(special) parameters acquire +the behavior of the special parameter, regardless of the scope where +the reference is declared. + +When var(rname) includes an array subscript, the subscript expression +is interpreted at the time tt(${)var(pname)tt(}) is expanded. Any +form of subscript is allowed, including those that select individual +elements, substrings of scalar strings, or multiple elements as with +array slices or the `tt((i))', `tt((I))', `tt((r))', `tt((R))' and +`tt((w))' subscript flags. However, the subscript is evaluated with +the tt(NO_EXEC) option in effect, so command substitution and other +similar constructs produce no output, although are not syntactically +excluded. + +When var(rname) is an array (but not an array element or slice), the +named reference may also be used in substitutions requiring an +var(arrayname), so these are equivalent: +ifzman() +example(tt(${)var(name)tt(:|)var(rname)tt(}) +tt(${)var(name)tt(:|)var(pname)tt(})) + +Expansions of the form `tt(${LPAR()t)tt(RPAR())var(pname)tt(})' expand +the type information of var(rname), unless var(rname) is empty, in which +case the expansion is `tt(nameref)', or when no variable var(rname) +exists, in which case the expansion is empty. + +See also ifzman(zmanref(zshparam))ifnzman(noderef(Parameters)). + subsect(Rules) cindex(parameter expansion rules) cindex(rules, parameter expansion) @@ -1542,12 +1669,16 @@ substitutions; the nested substitution will return either a scalar or an array as determined by the flags, possibly adjusted for quoting. All the following steps take place where applicable at all levels of substitution. -Note that, unless the `tt((P))' flag is present, the flags and any +Note that, unless the `tt((P))' flag or a named reference is present, +the flags and any subscripts apply directly to the value of the nested substitution; for example, the expansion tt(${${foo}}) behaves exactly the same as -tt(${foo}). When the `tt((P))' flag is present in a nested substitution, +tt(${foo}). When a named reference or the `tt((P))' flag is used in a +nested substitution, the other substitution rules are applied to the value em(before) it is interpreted as a name, so tt(${${(P)foo}}) may differ from tt(${(P)foo}). +When both a named reference and the `tt((P))' flag appear, the named +reference is resolved before `tt((P))' is applied. At each nested level of substitution, the substituted words undergo all forms of single-word substitution (i.e. not filename generation), including @@ -1773,23 +1904,65 @@ sect(Command Substitution) cindex(command substitution) cindex(substitution, command) A command enclosed in parentheses preceded by a dollar sign, like -`tt($LPAR())...tt(RPAR())', or quoted with grave -accents, like `tt(`)...tt(`)', is replaced with its standard output, with -any trailing newlines deleted. -If the substitution is not enclosed in double quotes, the -output is broken into words using the tt(IFS) parameter. +`tt($LPAR())...tt(RPAR())', or quoted with grave accents, like +`tt(`)...tt(`)', is executed in a subshell and replaced by its +standard output, with any trailing newlines deleted. If the +substitution is not enclosed in double quotes, the output is broken +into words using the tt(IFS) parameter. vindex(IFS, use of) The substitution `tt($LPAR()cat) var(foo)tt(RPAR())' may be replaced by the faster `tt($LPAR()<)var(foo)tt(RPAR())'. In this case var(foo) undergoes single word shell expansions (em(parameter expansion), em(command substitution) and em(arithmetic expansion)), but not -filename generation. +filename generation. No subshell is created. If the option tt(GLOB_SUBST) is set, the result of any unquoted command substitution, including the special form just mentioned, is eligible for filename generation. +A command with a leading pipe character, enclosed in braces prefixed by +a dollar sign, as in `tt(${|)...tt(})', is executed in the current shell +context, rather than in a subshell, and is replaced by the value of the +parameter tt(REPLY) at the end of the command. There em(must not) be +any whitespace between the opening brace and the pipe character. Any +prior value of tt($REPLY) is saved and restored around this substitution, +in the manner of a function local parameter. Other parameters declared +within the substitution also behave as locals, as if in a function, +unless `tt(typeset -g)' is used. Trailing newlines are em(not) deleted +from the final replacement in this case, and it is subject to filename +generation in the same way as `tt($LPAR())...tt(RPAR())' but is em(not) +split on tt(IFS) unless the tt(SH_WORD_SPLIT) option is set. + +cindex(substitution, command, current shell) +cindex(substitution, command, non forking) +cindex(substitution, nofork) +Substitutions of the form `tt(${{)var(param)tt(}) ...tt(})' are similar, +except that the substitution is replaced by the value of the parameter +named by var(param). No implicit save or restore applies to var(param) +and var(param) should em(not) be declared within the command. No space +is allowed within `tt(${{)' and space or newline is required after +`tt({)var(param)tt(})'. The var(param) may include a subscript, and if, +after evaluating the expression, var(param) names an array, then array +expansion rules apply to the final substitution. + +A command enclosed in braces preceded by a dollar sign, and set off from +the braces by whitespace, like `tt(${ )...tt( })', is replaced by its +standard output. Like `tt(${|)...tt(})' and unlike +`tt($LPAR())...tt(RPAR())', the command executes in the current shell +context with function local behaviors and does not create a subshell. +Word splitting does not apply unless tt(SH_WORD_SPLIT) is set, but a +single trailing newline is stripped unless the substitution is enclosed +in double quotes. + +Note that because `tt(${|)...tt(})' and the two related substitutions +must be parsed at once as both string tokens and commands, all other +braces (`tt({)' or `tt(})') within the command either must be quoted, +or must appear in syntactically valid pairs, such as around complex +commands, function bodies, or parameter references. Furthermore, +comments are always recognized, even when tt(NO_INTERACTIVE_COMMENTS) +is in effect. + texinode(Arithmetic Expansion)(Brace Expansion)(Command Substitution)(Expansion) sect(Arithmetic Expansion) cindex(arithmetic expansion) @@ -1970,34 +2143,24 @@ tt(/home/pws/perforce). In this simple case a static name for the directory would be just as effective. example(zsh_directory_name+LPAR()RPAR() { - emulate -L zsh - setopt extendedglob + emulate -L zsh -o extendedglob local -a match mbegin mend - if [[ $1 = d ]]; then - # turn the directory into a name - if [[ $2 = (#b)(/home/pws/perforce/)([^/]##)* ]]; then - typeset -ga reply - reply=(p:$match[2] $(( ${#match[1]} + ${#match[2]} )) ) - else - return 1 - fi - elif [[ $1 = n ]]; then - # turn the name into a directory - [[ $2 != (#b)p:(?*) ]] && return 1 - typeset -ga reply - reply=(/home/pws/perforce/$match[1]) - elif [[ $1 = c ]]; then - # complete names - local expl - local -a dirs - dirs=(/home/pws/perforce/*(/:t)) - dirs=(p:${^dirs}) - _wanted dynamic-dirs expl 'dynamic directory' compadd -S\] -a dirs - return - else - return 1 - fi - return 0 + local base=/home/pws/perforce + case $1 in + ( d ) # Turn the directory into a name. + [[ $2 == (#b)($base/)([^/]##)* ]] && + reply=( p:$match[2] $(( $#match[1] + $#match[2] )) ) + ;; + ( n ) # Turn the name into a directory. + [[ $2 == (#b)p:(?*) ]] && + reply=( $base/$match[1] ) + ;; + ( c ) # Complete names. + local -a dirs=( $base/*(/:t) ) + # Completion system populates $expl with flags for compadd. + compadd "$expl[@]" p:$^dirs + ;; + esac }) texinode(Static named directories)(`=' expansion)(Dynamic named directories)(Filename Expansion) @@ -2987,9 +3150,10 @@ so both can be used on the same glob expression; for example by writing ) enditem() -More than one of these lists can be combined, separated by commas. The -whole list matches if at least one of the sublists matches (they are -`or'ed, the qualifiers in the sublists are `and'ed). Some qualifiers, +Multiple consecutive qualifiers are joined into a list by implicit logical AND. +More than one of these lists can be combined using comma `tt(,)' as logical OR. +The whole list matches if at least one of the sublists matches. +Some qualifiers, however, affect all matches generated, independent of the sublist in which they are given. These are the qualifiers `tt(M)', `tt(T)', `tt(N)', `tt(D)', `tt(n)', `tt(o)', `tt(O)' and the subscripts given diff --git a/Doc/Zsh/files.yo b/Doc/Zsh/files.yo index 65debe044..c6c7da307 100644 --- a/Doc/Zsh/files.yo +++ b/Doc/Zsh/files.yo @@ -14,7 +14,7 @@ cindex(zshenv) Commands are first read from tt(zshenv()); this cannot be overridden. Subsequent behaviour is modified by the tt(RCS) and tt(GLOBAL_RCS) options; the former affects all startup files, while the -second only affects global startup files (those shown here with an +second only affects global startup files (those shown here with a path starting with a tt(/)). If one of the options is unset at any point, any subsequent startup file+LPAR()s+RPAR() of the corresponding diff --git a/Doc/Zsh/func.yo b/Doc/Zsh/func.yo index 12db3f56a..7b71e34e9 100644 --- a/Doc/Zsh/func.yo +++ b/Doc/Zsh/func.yo @@ -13,6 +13,43 @@ Functions are executed like commands with the arguments passed as positional parameters. (See noderef(Command Execution).) +Parameters declared by any of the `tt(typeset)' family of commands +during the execution of a function become em(local) to the function +unless the `tt(-g)' option is used. This is the em(scope) of the +parameter, which extends dynamically to any other functions called by +the declaring function. In most cases, local parameters take the +place of any other parameter having the same name that was assigned or +declared in an earlier function scope. +(See noderef(Local Parameters).) + +A named parameter declared with the `tt(-n)' option to any of the +`tt(typeset)' commands becomes a reference to a parameter in scope at +the time of assignment to the named reference, which may be at a +different call level than the declaring function. For this reason, +it is good practice to declare a named reference as soon as the +referent parameter is in scope, and as early as possible in the +function if the reference is to a parameter in a calling scope. + +A typical use of named references is to pass the name +of the referent as a positional parameter. In this case it is +good practice to use the tt(-u) option to reference the calling +scope. For example, +ifzman() +example(pop+LPAR()RPAR() { + local -nu ref=$1 + local last=$ref[$#ref] + ref[$#ref]=LPAR()RPAR() + print -r -- $last +} +array=LPAR() a list of five values RPAR() +pop array) + +prints the word `tt(values)' and shortens `tt($array)' to +`tt(LPAR() a list of five RPAR())'. With tt(-nu), `tt(ref)' becomes a +reference to `tt(array)' in the caller. There are no local parameters in +tt(pop) at the time `tt(ref=$1)' is assigned, so in this example tt(-u) +could have been omitted, but it makes the intention clear. + Functions execute in the same process as the caller and share all files and present working directory with the diff --git a/Doc/Zsh/grammar.yo b/Doc/Zsh/grammar.yo index f8f4ada86..b80f9750c 100644 --- a/Doc/Zsh/grammar.yo +++ b/Doc/Zsh/grammar.yo @@ -100,14 +100,15 @@ More generally, a list can be seen as a set of any shell commands whatsoever, including the complex commands below; this is implied wherever the word `list' appears in later descriptions. For example, the commands in a shell function form a special sort of list. + texinode(Precommand Modifiers)(Complex Commands)(Simple Commands & Pipelines)(Shell Grammar) sect(Precommand Modifiers) cindex(precommand modifiers) cindex(modifiers, precommand) -A simple command may be preceded by a em(precommand modifier), -which will alter how the command is interpreted. These modifiers are -shell builtin commands with the exception of tt(nocorrect) which is -a reserved word. +With the exception of tt(nocorrect), which is a reserved word that +affects further parsing when it is found in command position, each +of the following builtin commands is a em(precommand modifier) which +may precede a simple command to alter how that command is interpreted. startitem() findex(-) @@ -158,8 +159,7 @@ before any parsing is done. It has no effect in non-interactive shells. ) findex(noglob) item(tt(noglob))( -Filename generation (globbing) is not performed on any of -the words. +Filename generation (globbing) is not performed on any of the words. ) enditem() texinode(Complex Commands)(Alternate Forms For Complex Commands)(Precommand Modifiers)(Shell Grammar) @@ -187,6 +187,12 @@ Expand the list of var(word)s, and set the parameter var(name) to each of them in turn, executing var(list) each time. If the `tt(in) var(word)' is omitted, use the positional parameters instead of the var(word)s. +If any var(name) has been declared as a named reference, +the corresponding var(word) is treated as the name of a +parameter and var(name) is made a reference to that. +Note that for the positional parameters, this treats the +value of each positional as parameter name rather than +creating a reference to the position. The var(term) consists of one or more newline or tt(;) which terminate the var(word)s, and are optional when the @@ -536,7 +542,7 @@ itemiz(Errors creating command or process substitutions) itemiz(Syntax errors in glob qualifiers) itemiz(File generation errors where not caught by the option tt(BAD_PATTERN)) itemiz(All bad patterns used for matching within case statements) -itemiz(File generation failures where not caused by tt(NO_MATCH) or +itemiz(File generation failures where not caused by tt(NOMATCH) or similar options) itemiz(All file generation errors where the pattern was used to create a multio) diff --git a/Doc/Zsh/index.yo b/Doc/Zsh/index.yo index 191e0f2f9..131d7a4f2 100644 --- a/Doc/Zsh/index.yo +++ b/Doc/Zsh/index.yo @@ -5,7 +5,7 @@ def(printindex)(2)(\ NL()\ NOTRANS(@printindex) ARG2\ )\ -texinode(Concept Index)(Variables Index)(Top)(Top) +texinode(Concept Index)(Variables Index)()(Top) printindex(Concept Index)(cp) texinode(Variables Index)(Options Index)(Concept Index)(Top) diff --git a/Doc/Zsh/manual.yo b/Doc/Zsh/manual.yo index dc4d6ed07..e54dd077c 100644 --- a/Doc/Zsh/manual.yo +++ b/Doc/Zsh/manual.yo @@ -126,7 +126,8 @@ menu(Initialization) menu(Completion System Configuration) menu(Control Functions) menu(Bindable Commands) -menu(Completion Functions) +menu(Utility Functions) +menu(Completion System Variables) menu(Completion Directories) Completion Using compctl diff --git a/Doc/Zsh/mod_hlgroup.yo b/Doc/Zsh/mod_hlgroup.yo new file mode 100644 index 000000000..efe8934a1 --- /dev/null +++ b/Doc/Zsh/mod_hlgroup.yo @@ -0,0 +1,25 @@ +COMMENT(!MOD!zsh/hlgroup +Alternative views of highlighting groups +!MOD!) +The tt(zsh/hlgroup) module defines special parameters that represent +highlighting groups in different forms to ease the use of the groups when +configuring other tools. + +In each case, these are readonly associative arrays where accessing elements +uses values from the underlying tt(.zle.hlgroups) variable. + +startitem() +vindex(.zle.esc) +item(tt(.zle.esc))( +This associative array contains the literal escape sequences used to apply the +highlighting for each group. An example use would be when setting the +tt(LESS_TERMCAP_xx) environment variables for the tt(less) pager. +) +vindex(.zle.sgr) +item(tt(.zle.sgr))( +Where highlighting makes use of CSI escape sequences, this parameter contains +the "Select Graphic Rendition" number sequence. This is useful with, for +example the tt(GREP_COLORS) and tt(LSCOLORS) environment variables and the +tt(list-colors) style. +) +enditem() diff --git a/Doc/Zsh/mod_ksh93.yo b/Doc/Zsh/mod_ksh93.yo new file mode 100644 index 000000000..7d22064ee --- /dev/null +++ b/Doc/Zsh/mod_ksh93.yo @@ -0,0 +1,243 @@ +COMMENT(!MOD!zsh/ksh93 +Extended ksh93 compatibility for "emulate ksh" +!MOD!) +cindex(ksh93) +The tt(zsh/ksh93) module provides one builtin and several parameters to +improve compatibility with ksh93. As of this writing, several ksh93 +features are still missing. + +subsect(Ksh Builtins) +The single builtin provided by this module is: + +startitem() +findex(nameref) +cindex(named references, creating) +item(tt(nameref) [ tt(-gpur) ] var(pname)[tt(=)var(rname)])( +Equivalent to tt(typeset -n )var(pname)tt(=)var(rname) + +However, tt(nameref) is a builtin command rather than a reserved word, +so when var(rname) uses subscript syntax it must be quoted against +globbing. Subscripts in referenced parameters are not supported in +ksh93, so this is not a significant compatibility issue. +) +enditem() + +subsect(Ksh Parameters) +cindex(parameters, ksh) +Parameters supplied by this module that are marked with `<K>' below +are available only when ksh emulation is active before entry to the +shell function, that is, `tt(emulate ksh)' locally to a function does +not populate these parameters for that function. + +startitem() +vindex(.sh.command) +item(tt(.sh.command))( +A named reference to `tt(ZSH_DEBUG_CMD)' +) +vindex(.sh.edchar) +item(tt(.sh.edchar) <K>)( +In a ZLE widget, equivalent to the `tt(KEYS)' special parameter. In a +future release, assignments to this parameter will affect the input +stream seen by ZLE. +) +vindex(.sh.edcol) +item(tt(.sh.edcol))( +A named reference to the ZLE special parameter `tt(CURSOR)'. +) +vindex(.sh.edmode) +item(tt(.sh.edmode) <K>)( +In a ZLE widget, this parameter has the value tt(ESC) (tt($'\e')) if the +tt(VI) option is set and the `tt(main)' keymap is selected. This is +intended for use with vi-mode key bindings (`tt(bindkey -v)'). In a +future revision, assigning `tt(.sh.edchar=${.sh.edmode})' is expected +to initiate `tt(vicmd)' mode when `tt(viins)' is active, and do +nothing when `tt(vicmd)' is already active. +) +vindex(.sh.edtext) +item(tt(.sh.edtext))( +A named reference to the `tt(BUFFER)' special ZLE parameter. +) +vindex(.sh.file) +item(tt(.sh.file))( +A named reference to the `tt(ZSH_SCRIPT)' parameter. +) +vindex(.sh.fun) +item(tt(.sh.fun) <K>)( +In a shell function, the function's name. Usually the same as `tt($0)', +but not affected by tt(POSIX_ARGZERO) or tt(FUNCTION_ARGZERO) options. +) +vindex(.sh.level) +item(tt(.sh.level) <K>)( +In a shell function, initially set to the depth of the call stack. This +may be assigned to change the apparent depth. However, such assignment +does not affect the scope of local parameters. +) +vindex(.sh.lineno) +item(tt(.sh.lineno))( +A named reference to the `tt(LINENO)' special parameter. +) +vindex(.sh.match) +item(tt(.sh.match))( +An array equivalent to the `tt(match)' parameter as assigned by the +`tt(LPAR()#b)tt(RPAR())' extended globbing flag. When the +tt(KSH_ARRAYS) option is set, `tt(${.sh.match[0]})' gives the value of +the `tt(MATCH)' parameter as set by the `tt(LPAR()#m)tt(RPAR())' extended +globbing flag. Currently, the tt(EXTENDED_GLOB) option must be enabled +and those flags must be explicitly used in a pattern in order for these +values of `tt(.sh.match)' to be set. +) +vindex(.sh.name) +item(tt(.sh.name) <K>)( +When the `tt(vared)' command is used, this parameter may be used in +user-defined ZLE widgets to get the name of the variable being edited. +A future release is expected to use this parameter in the implementation +of "discipline functions". +) +vindex(.sh.subscript) +item(tt(.sh.subscript) <K>)( +When `tt(vared)' has been used on an array element, this parameter holds +the array index (either a number, or an associative array key). +) +vindex(.sh.subshell) +item(tt(.sh.subshell))( +A named reference to the `tt(ZSH_SUBSHELL)' parameter. +) +vindex(.sh.value) +item(tt(.sh.value) <K>)( +In `tt(vared)' this is a named reference to the ZLE special `tt(BUFFER)'. +A future release is expected to use this parameter in the implementation +of "discipline functions". +) +vindex(.sh.version) +item(tt(.sh.version))( +A named reference to `tt(ZSH_PATCHLEVEL)'. +) +enditem() + +subsect(Future Compatibility) + +The following features of ksh93 are not currently supported but may be +available in a future release. + +startitem() +item(tt(namespace )var(ident)tt( { )var(list)tt( }))( +This reserved word executes the current shell compound command +tt({ )var(list)tt( }), with the special behavior that all functions +and parameters `var(name)' declared within var(list) are implicitly +prefixed to become `tt(.)var(ident)tt(.)var(name)', and similarly any +reference to a function or parameter `var(name)' is searched for as +`tt(.)var(ident)tt(.)var(name)' before falling back to `var(name)'. + +em(THIS FEATURE IS NOT YET IMPLEMENTED.) +) +item(tt(.sh.math) <K>)( +This parameter is more accurately considered a namespace. A function +defintion of the form +ifzman() +indent(tt(function .sh.math.)var(name)tt( )var(ident)tt( ... { )var(list)tt( })) + +is equivalent to the native zsh definition +ifzman() +example(tt(function )var(name)tt( {) +tt( local )var(ident)tt(=$1 ...) +tt( )var(list) +tt(}) +tt(functions -M )var(name)tt( 1 3)) +ifzman() +Up to 3 var(ident) arguments, interpreted as floating point numbers, +may be provided for a function defined with tt(.sh.math) in this way. +The names (but not definitions) of all such functions are available +via tt(${.sh.math[@]}). + +em(THIS FEATURE IS NOT YET IMPLEMENTED.) +) +item(tt(var(name)tt(.get)))( +A shell function having this name, if defined, is invoked whenever the +parameter tt(${)var(name)tt(}) is referenced, including by commands +such as `tt(typeset -p)'. If the special variable `tt(.sh.value)' is +assigned by the function, that value is substituted instead of the +true value of var(name). This does not change the value of var(name), +but there is no way to access the actual value without first removing +the function. + +Additionally, an explicit reference to tt(${)var(name)tt(.get}) +calls the function var(name)tt(.get) even if there is no parameter +`var(name)' and substitutes the standard output of the function. + +em(THIS FEATURE IS NOT YET IMPLEMENTED.) +) +xitem(tt(var(name)tt(.set))) +item(tt(var(name)tt(.append)))( +Shell functions having these names are invoked when the parameter +var(name) is assigned or (for array types) has a new field appended. +The function may change the result of the operation by assigning to +the `tt(.sh.value)' special parameter, or block the change by +unsetting `tt(.sh.value)'. + +Explicit reference to tt(${)var(name)tt(.set}) or tt(${)var(name)tt(.append}) +substitutes the standard output of the function. + +em(THIS FEATURE IS NOT YET IMPLEMENTED.) +) +item(tt(var(name)tt(.unset)))( +When a function of this name is defined, it is called whenever the +parameter var(name) would be unset. The function must explicitly +`tt(unset )var(name)', otherwise the variable remains set. + +em(THIS FEATURE IS NOT YET IMPLEMENTED.) +) +item(tt(typeset -C )var(name)[tt(=)var(values)tt( ...)])( +Creates a em(compound variable). + +em(THIS FEATURE IS NOT YET IMPLEMENTED, and the syntax of var(values) +is unlikely to be fully ksh compatible.) +) +enditem() + +subsect(Other Differences) + +The following features of ksh93 are not currently supported and there are +no plans to implement them. + +startitem() +item(var(pathdir)tt(/.paths))( +Each directory var(pathdir) in the tt(PATH) parameter may contain a +text file `tt(.paths)' which may define additional directories to +be searched for function definitions (tt(FPATH)), external executables +(tt(PATH)), and plugin files (similar to tt(MODULE_PATH)). + +em(THIS FEATURE IS UNLIKELY EVER TO BE IMPLEMENTED.) +) +item(tt(builtin -f )var(file))( +Installs a new shell builtin command dynamically linked from var(file), +where var(file) is found by a path search and the base name of the file +is the name of the builtin to be added. + +Similar to `tt(zmodload -F zsh/)var(file)tt( +b:)var(file)'. + +em(THIS FEATURE IS UNLIKELY EVER TO BE IMPLEMENTED.) +) +item(tt(typeset -H )var(name)[tt(=)var(value)])( +Used for em(host-name file mapping) on some operating systems. + +em(THIS FEATURE IS UNLIKELY EVER TO BE IMPLEMENTED.) +) +item(tt(typeset ){tt(PLUS()|-)}tt(M )var(mapname)tt( )var(name)[tt(=)var(value)])( +Declares a character translation var(mapname) for values assigned to var(name). +) +xitem(tt(typeset -S)) +xitem(tt(typeset -T ) [tt(-f)] [ var(tname)tt(=LPAR())var(values)tt(RPAR()) ]) +item(tt(typeset -h )var(str))( +Used to define em(typed variables) and properties of their em(sub-variables). +The tt(-T) and tt(-h) options conflict with existing zsh usage. +) +item(tt(typeset -X )var(name)[tt(=)var(value)])( +Declares a floating-point variable displayed in hexadecimal format. +) +item(tt(typeset -b )var(name)[tt(=)var(value)])( +Declares a parameter stored in em(base64) format. +) +item(tt(typeset -m )var(newname)tt(=)var(oldname))( +em(Moves) var(oldname) to var(newname). Conflicts with native zsh usage. +) +enditem() diff --git a/Doc/Zsh/mod_parameter.yo b/Doc/Zsh/mod_parameter.yo index f3bcd7957..3defef2b7 100644 --- a/Doc/Zsh/mod_parameter.yo +++ b/Doc/Zsh/mod_parameter.yo @@ -125,7 +125,16 @@ zmanref(zshexpn) ifnzman(\ noderef(Parameter Expansion) )\ -. +. The value may also be `tt(undefined)' indicating a parameter that +may be autoloaded from a module but has not yet been referenced. +When the key is the name of a named reference, the value is +`tt(nameref-)' prepended to the type of the referenced parameter, +for example +ifzman() +example(tt(% typeset -n parms=parameters) +tt(% print -r ${parameters[parms]}) +tt(nameref-association-readonly-hide-hideval-special)) + Setting or unsetting keys in this array is not possible. ) vindex(modules) diff --git a/Doc/Zsh/mod_pcre.yo b/Doc/Zsh/mod_pcre.yo index c2817f519..41fab4475 100644 --- a/Doc/Zsh/mod_pcre.yo +++ b/Doc/Zsh/mod_pcre.yo @@ -20,12 +20,12 @@ including those that indicate newline. ) findex(pcre_study) item(tt(pcre_study))( -Studies the previously-compiled PCRE which may result in faster -matching. +Requests JIT compilation for the previously-compiled PCRE which +may result in faster matching. ) findex(pcre_match) item(tt(pcre_match) [ tt(-v) var(var) ] [ tt(-a) var(arr) ] \ -[ tt(-n) var(offset) ] [ tt(-b) ] var(string))( +[ tt(-A) var(assoc) ] [ tt(-n) var(offset) ] [ tt(-bd) ] var(string))( Returns successfully if tt(string) matches the previously-compiled PCRE. @@ -36,7 +36,9 @@ substrings, unless the tt(-a) option is given, in which case it will set the array var(arr). Similarly, the variable tt(MATCH) will be set to the entire matched portion of the string, unless the tt(-v) option is given, in which case the variable -var(var) will be set. +var(var) will be set. Furthermore, any named captures will +be stored in the associative array tt(.pcre.match) unless an +alternative is given with tt(-A). No variables are altered if there is no successful match. A tt(-n) option starts searching for a match from the byte var(offset) position in var(string). If the tt(-b) option is given, @@ -67,6 +69,15 @@ print -l $accum) ) enditem() +If the regular expression contains callouts, these are executed as shell code. +During the execution of the callout, the string the regular expression is +matching against is available in the parameter tt(.pcre.subject). If there is a +non-zero return status from the shell code, the callout does not match. + +The option tt(-d) uses the alternative breadth-first DFA search algorithm of +pcre. This sets tt(match), or the array given with tt(-a), to all the matches +found from the same start point in the subject. + The tt(zsh/pcre) module makes available the following test condition: startitem() diff --git a/Doc/Zsh/mod_private.yo b/Doc/Zsh/mod_private.yo index 184fa2be8..24c099f38 100644 --- a/Doc/Zsh/mod_private.yo +++ b/Doc/Zsh/mod_private.yo @@ -16,9 +16,10 @@ The tt(private) builtin accepts all the same options and arguments as tt(local) (ifzman(zmanref(zshbuiltins))ifnzman(noderef(Shell Builtin Commands))) except for the `tt(-)tt(T)' option. Tied parameters may not be made private. -The `tt(-)tt(p)' option is presently a no-op because the state of -private parameters cannot reliably be reloaded. This also applies -to printing private parameters with `tt(typeset -p)'. +The `tt(-)tt(p)' option is presently disabled because the state of +private parameters cannot reliably be reloaded. When `tt(typeset -)tt(p)' +outputs a private parameter, it is treated as a local with the +`tt(-)tt(h)' (hide) option enabled. If used at the top level (outside a function scope), tt(private) creates a normal parameter in the same manner as tt(declare) or tt(typeset). A @@ -84,6 +85,14 @@ created outside the local scope when it was not previously declared.) itemiz(An exported private remains in the environment of inner scopes but appears unset for the current shell in those scopes. Generally, exporting private parameters should be avoided.) +itemiz(Current shell command substitutions such as `tt(${|)...tt(})', +`tt(${|)var(var)tt(|)...tt(})' and `tt(${ )...tt( })' may read and assign +private parameters from the enclosing function.) +itemiz(Declaring a private parameter in a current shell command substitution +limits that parameter to the scope of the command substitution, just as if +the parameter were declared in a function. This also prevents access by +any enclosed current shell command substitutions, but other substitutions +may use the private parameter because those have the same calling scope.) enditemize() Note that this differs from the static scope defined by compiled languages diff --git a/Doc/Zsh/mod_random.yo b/Doc/Zsh/mod_random.yo new file mode 100644 index 000000000..4f5622e61 --- /dev/null +++ b/Doc/Zsh/mod_random.yo @@ -0,0 +1,56 @@ +COMMENT(!MOD!zsh/random +Some High-quality randomness parameters and functions. +!MOD!) +The tt(zsh/random) module gets random data from the kernel random pool. If no +kernel random pool can be found, the module will not load. + +subsect(Parameters) + +startitem() +vindex(SRANDOM) +item(tt(SRANDOM)) ( +A random positive 32-bit integer between 0 and 4,294,967,295. This parameter +is read-only. The name was chosen for compatibility with Bash and to +distinguish it from tt(RANDOM) which has a documented repeatable behavior. +) +enditem() + +subsect(Math Functions) + +startitem() +item(tt(zrand_float+LPAR()RPAR())) ( +Returns a random floating point number between 0 and 1 inclusive. +) +enditem() + +startitem() +item(tt(zrand_int)+LPAR()tt(upper), tt(lower), tt(inclusive)RPAR()) ( +Returns a random integer between tt(lower) and tt(upper). All parameters are +optional. If none are specified it is equivalent to +tt(SRANDOM). + +tt(upper) is the upper bound on the resultant number and defaults to +4,294,967,295. + +tt(lower) is the lower bound and defaults to 0. + +The defaults of these two arguments are also the maximum and minimum to which +either can be set. + +tt(inclusive) is a flag that controls whether the result is ever equal to +tt(upper). By default it is not. If this argument is set to a non-zero value +then it may be. + +This is to facilitate a construct like tt($a[zrand_int+LPAR()$#a+RPAR()+1]) rather +than tt($a[zrand_int+LPAR()$#a-1+RPAR()+1]). +For example, if $#a is 16, you would use tt(zrand_int+LPAR()16RPAR()) which has +16 possible return values 0-15. Because the function can return zero, in order +to use it as an array index from 1-16 you need to add one. It would +be an array index range error for it to also potentially return 16 ($#a). You +could, however, use the construct tt(zrand_int+LPAR()16,1,1+RPAR()) instead of +adding 1 to achieve the same result, but it is more verbose. + +Most statistics algorithms seem to also expect 0 to tt(upper)-1, so this was +deemed the most commonly desired case and chosen as the default. +) +enditem() diff --git a/Doc/Zsh/mod_system.yo b/Doc/Zsh/mod_system.yo index 884c3e753..e25201faa 100644 --- a/Doc/Zsh/mod_system.yo +++ b/Doc/Zsh/mod_system.yo @@ -74,6 +74,11 @@ truncate file to size 0 ) enditem() +A return status of 0 indicates the descriptor was successfully opened, +otherwise an error message is printed, and 1 is returned for an error +in the parameters to the command, or 2 is returned for a system error. +The parameter tt(ERRNO) is nonzero for system errors. + To close the file, use one of the following: example(tt(exec {)var(fd)tt(}<&-) @@ -123,11 +128,11 @@ error for which a message is printed to standard error. ) item(2)( There was an error on the read, or on polling the input file descriptor -for a timeout. The parameter tt(ERRNO) gives the error. +for a timeout. The parameter tt(ERRNO) identifies the error. ) item(3)( Data were successfully read, but there was an error writing them -to var(outfd). The parameter tt(ERRNO) gives the error. +to var(outfd). The parameter tt(ERRNO) identifies the error. ) item(4)( The attempt to read timed out. Note this does not set tt(ERRNO) as this @@ -147,6 +152,11 @@ expression. The tt(-u) option allows the file descriptor to be specified. By default the offset is specified relative to the start or the file but, with the tt(-w) option, it is possible to specify that the offset should be relative to the current position or the end of the file. + +The return status may be 0 for success, 1 for an error in the parameters +to the command, or 2 for an error on the seek; no error message is +printed in the last case, but the parameter tt(ERRNO) reflects +the error that occurred. ) item(tt(syswrite) [ tt(-c) var(countvar) ] [ tt(-o) var(outfd) ] var(data))( The data (a single string of bytes) are written to the file descriptor @@ -166,7 +176,7 @@ returning early. The return status may be 0 for success, 1 for an error in the parameters to the command, or 2 for an error on the write; no error message is -printed in the last case, but the parameter tt(ERRNO) will reflect +printed in the last case, but the parameter tt(ERRNO) reflects the error that occurred. ) xitem(tt(zsystem flock) [ tt(-t) var(timeout) ] [ tt(-i) var(interval) ] [ tt(-f) var(var) ] [tt(-er)] var(file)) diff --git a/Doc/Zsh/mod_zselect.yo b/Doc/Zsh/mod_zselect.yo index faf59c165..42287f116 100644 --- a/Doc/Zsh/mod_zselect.yo +++ b/Doc/Zsh/mod_zselect.yo @@ -13,7 +13,7 @@ blocks until a file descriptor is ready for reading or writing, or has an error condition, with an optional timeout. If this is not available on your system, the command prints an error message and returns status 2 (normal errors return status 1). For more information, see your system's -documentation for manref(select)(3). Note there is no connection with the +documentation for manref(select)(2). Note there is no connection with the shell builtin of the same name. Arguments and options may be intermingled in any order. Non-option diff --git a/Doc/Zsh/mod_zutil.yo b/Doc/Zsh/mod_zutil.yo index 3cf9e5028..b296d878c 100644 --- a/Doc/Zsh/mod_zutil.yo +++ b/Doc/Zsh/mod_zutil.yo @@ -11,6 +11,7 @@ xitem(tt(zstyle) [ tt(-L) [ var(metapattern) [ var(style) ] ] ]) xitem(tt(zstyle) [ tt(-e) | tt(-) | tt(-)tt(-) ] var(pattern) var(style) var(string) ...) xitem(tt(zstyle -d) [ var(pattern) [ var(style) ... ] ]) xitem(tt(zstyle -g) var(name) [ var(pattern) [ var(style) ] ]) +xitem(tt(zstyle -q) var(context) var(style)) xitem(tt(zstyle -){tt(a)|tt(b)|tt(s)} var(context) var(style) var(name) [ var(sep) ]) xitem(tt(zstyle -){tt(T)|tt(t)} var(context) var(style) [ var(string) ... ]) item(tt(zstyle -m) var(context) var(style) var(pattern))( @@ -105,6 +106,12 @@ enditem() The other forms can be used to look up or test styles for a given context. startitem() +item(tt(zstyle -q) var(context) var(style))( +Return tt(0) if var(style) is defined in var(context). This does not +evaluate expressions defined by tt(zstyle -e) and does not examine any +values set by var(style). The expected use is to test whether a style +has been defined for var(context) before asserting a new style. +) item(tt(zstyle -s) var(context) var(style) var(name) [ var(sep) ])( The parameter var(name) is set to the value of the style interpreted as a string. If the value contains several strings they are concatenated with @@ -221,7 +228,7 @@ item(tt(zregexparse))( This implements some internals of the tt(_regex_arguments) function. ) findex(zparseopts) -item(tt(zparseopts) [ tt(-D) tt(-E) tt(-F) tt(-K) tt(-M) ] [ tt(-a) var(array) ] [ tt(-A) var(assoc) ] [ tt(-) ] var(spec) ...)( +item(tt(zparseopts) [ tt(-D) tt(-E) tt(-F) tt(-G) tt(-K) tt(-M) ] [ tt(-a) var(array) ] [ tt(-A) var(assoc) ] [ tt(-v) var(argv) ] [ tt(-) ] var(spec) ...)( This builtin simplifies the parsing of options in positional parameters, i.e. the set of arguments given by tt($*). Each var(spec) describes one option and must be of the form `var(opt)[tt(=)var(array)]'. If an option @@ -235,8 +242,8 @@ Note that it is an error to give any var(spec) without an Unless the tt(-E) option is given, parsing stops at the first string that isn't described by one of the var(spec)s. Even with tt(-E), -parsing always stops at a positional parameter equal to `tt(-)' or -`tt(-)tt(-)'. See also tt(-F). +parsing always stops at a positional parameter equal to `tt(-)tt(-)' or +(without tt(-G)) `tt(-)'. See also tt(-F). The var(opt) description must be one of the following. Any of the special characters can appear in the option name provided it is preceded by a @@ -275,19 +282,19 @@ first colon. ) enditem() -In all cases, option-arguments must appear either immediately following the +By default, option-arguments may appear either immediately following the option in the same positional parameter or in the next one. Even an optional argument may appear in the next parameter, unless it begins with a `tt(-)'. -There is no special handling of `tt(=)' as with GNU-style argument parsers; -given the var(spec) `tt(-foo:)', the positional parameter `tt(-)tt(-foo=bar)' -is parsed as `tt(-)tt(-foo)' with an argument of `tt(=bar)'. +Additionally, there is no special consideration given to an `tt(=)' +between an option and its argument. To make parsing use the more common +GNU-style conventions, use the tt(-G) option. When the names of two options that take no arguments overlap, the longest one wins, so that parsing for the var(spec)s `tt(-foo -foobar)' (for example) is unambiguous. However, due to the aforementioned handling of option-arguments, ambiguities may arise when at least one overlapping var(spec) takes an argument, as in `tt(-foo: -foobar)'. In that case, the last matching -var(spec) wins. +var(spec) wins. (This is not an issue with GNU-style parsing.) The options of tt(zparseopts) itself cannot be stacked because, for example, the stack `tt(-DEK)' is indistinguishable from a var(spec) for @@ -307,9 +314,9 @@ as the values. item(tt(-D))( If this option is given, all options found are removed from the positional parameters of the calling shell or shell function, up to but not including -any not described by the var(spec)s. If the first such parameter is `tt(-)' -or `tt(-)tt(-)', it is removed as well. This is similar to using the -tt(shift) builtin. +any not described by the var(spec)s. If the first such parameter is +`tt(-)tt(-)' or (without tt(-G)) `tt(-)', it is removed as well. This is +similar to using the tt(shift) builtin. ) item(tt(-E))( This changes the parsing rules to em(not) stop at the first string @@ -331,6 +338,40 @@ Note that the appearance in the positional parameters of an option without its required argument always aborts parsing and returns an error as described above regardless of whether this option is used. ) +item(tt(-G))( +This option specifies that options are parsed in the GNU style, +similar to tt(getopt_long+LPAR()3+RPAR()). In particular: + +Given the var(spec) `tt(-foo:)', the positional parameter +`tt(-)tt(-foo=bar)' is interpreted as option `tt(-)tt(-foo)' with +argument `tt(bar)', rather than argument `tt(=bar)' as is the default, +whilst the positional parameter `tt(-)tt(-foobar)' is considered an +unknown option (unless another var(spec) describes it). This applies +to both singly and doubly hyphenated long options. + +An empty option-argument can be given to its long option in the same +parameter using a trailing `tt(=)'. + +An optional argument to a long option must be given with the +equals syntax, and an optional argument to a short option must +follow it immediately in the same parameter; in both cases the +following parameter is considered unrelated. + +Whenever a long option and its argument are stored in the same array +element, an `tt(=)' is used to separate them. + +A mandatory option-argument given in a separate parameter from its +option (as in `tt(-)tt(-foo) tt(bar)'), or any option-argument given to +a short option in the same parameter, is always treated the same +regardless of whether this option is in effect. + +Lastly, when this option is active, only `tt(-)tt(-)' is treated as an +explicit option-parsing terminator in the parsed arguments; a single +`tt(-)' is considered a normal operand. + +Note: Unlike most tt(getopt_long+LPAR()3+RPAR()) implementations, +tt(zparseopts) does not support abbreviating long options. +) item(tt(-K))( With this option, the arrays specified with the tt(-a) option and with the `tt(=)var(array)' forms are kept unchanged when none of the var(spec)s for @@ -348,6 +389,11 @@ is found, the values are stored as usual. This changes only the way the values are stored, not the way tt($*) is parsed, so results may be unpredictable if the `var(name)tt(+)' specifier is used inconsistently. ) +item(tt(-v) var(argv))( +With this option, the elements of the named array var(argv) are used as the +positional parameters to parse, rather than those given by tt($*). The +array may be modified according to the tt(-D) option. +) enditem() For example, diff --git a/Doc/Zsh/options.yo b/Doc/Zsh/options.yo index 443676b78..c3af8dd33 100644 --- a/Doc/Zsh/options.yo +++ b/Doc/Zsh/options.yo @@ -1214,6 +1214,9 @@ Note that, when the tt(HASH_LIST_ALL) option is not set or when some directories in the path are not readable, this may falsely report spelling errors the first time some commands are used. +Refer to the shell variable tt(SPROMPT) for an explanation of the +`tt([nyae])' (no/yes/abort/edit) prompt that is offered. + The shell variable tt(CORRECT_IGNORE) may be set to a pattern to match words that will never be offered as corrections. ) @@ -1222,7 +1225,10 @@ pindex(NO_CORRECT_ALL) pindex(CORRECTALL) pindex(NOCORRECTALL) item(tt(CORRECT_ALL) (tt(-O)))( -Try to correct the spelling of all arguments in a line. +Try to correct the spelling of all arguments in a line, in order from +left to right, treating each as a file name. Answering `tt(a)' or +`tt(e)' at any prompt stops all corrections, otherwise every correction +is prompted for. The shell variable tt(CORRECT_IGNORE_FILE) may be set to a pattern to match file names that will never be offered as corrections. @@ -1723,27 +1729,38 @@ pindex(NOERREXIT) cindex(exit status, trapping) item(tt(ERR_EXIT) (tt(-e), ksh: tt(-e)))( If a command has a non-zero exit status, execute the tt(ZERR) -trap, if set, and exit. This is disabled while running initialization -scripts. - -The behaviour is also disabled inside tt(DEBUG) traps. In this -case the option is handled specially: it is unset on entry to -the trap. If the option tt(DEBUG_BEFORE_CMD) is set, -as it is by default, and the option tt(ERR_EXIT) is found to have been set -on exit, then the command for which the tt(DEBUG) trap is being executed is -skipped. The option is restored after the trap exits. - -Non-zero status in a command list containing tt(&&) or tt(||) is ignored -for commands not at the end of the list. Hence - -example(false && true) - -does not trigger exit. +trap, if set, and exit. + +The option is ignored when executing the commands following tt(while), +tt(until), tt(if), or tt(elif), a pipeline beginning with tt(!), or +any command other than the last in command list containing tt(&&) or +tt(||). Hence neither `tt(if foo; then true; fi)', nor `tt(foo && +true)' trigger exit when tt(foo) returns with a non-zero exit status. +Note that if tt(foo) is a function, the option is also ignored during +its whole execution. + +The option is also ignored when executing a complex command (tt(if), +tt(for), tt(while), tt(until), tt(repeat), tt(case), tt(select), +tt(always), or a list in braces) if its exit status comes from a +command executed while the option is ignored. Hence, the tt(if) +command in `tt(if true; then false && true; fi)' does not trigger +exit. + +Finally, the option is also ignored while running initialization +scripts and inside tt(DEBUG) traps. In the latter case, the option is +handled specially: it is unset on entry to the trap. If the option +tt(DEBUG_BEFORE_CMD) is set, as it is by default, and the option +tt(ERR_EXIT) is found to have been set on exit, then the command for +which the tt(DEBUG) trap is being executed is skipped. The option is +restored after the trap exits. Exiting due to tt(ERR_EXIT) has certain interactions with asynchronous jobs noted in ifzman(the section JOBS in zmanref(zshmisc))\ ifnzman(noderef(Jobs & Signals)). + +Note this behaviour is not disabled in interactive shells --- +a non-zero status on the command line causes the shell to exit. ) pindex(ERR_RETURN) pindex(NO_ERR_RETURN) @@ -1752,26 +1769,29 @@ pindex(NOERRRETURN) cindex(function return, on error) cindex(return from function, on error) item(tt(ERR_RETURN))( -If a command has a non-zero exit status, return immediately from the -enclosing function. The logic is similar to that for tt(ERR_EXIT), -except that an implicit tt(return) statement is executed instead of an -tt(exit). This will trigger an exit at the outermost level of a -non-interactive script. - -Normally this option inherits the behaviour of tt(ERR_EXIT) that -code followed by `tt(&&)' `tt(||)' does not trigger a return. Hence -in the following: - -example(summit || true) -no return is forced as the combined effect always has a zero return -status. - -Note. however, that if tt(summit) in the above example is itself a -function, code inside it is considered separately: it may force a return -from tt(summit) (assuming the option remains set within tt(summit)), but -not from the enclosing context. This behaviour is different from -tt(ERR_EXIT) which is unaffected by function scope. +If a command has a non-zero exit status, return immediately from the +enclosing function. Except as explained below, an implicit tt(return) +statement is executed following the same logic described for +tt(ERR_EXIT). This will trigger an exit at the outermost level of a +non-interactive script. At the top level of an interactive shell, it +will trigger a return to the command prompt; in other words, the +sequence of commands typed by the user may be thought of as a function +for this purpose. + +Unlike for tt(ERR_EXIT), when a function is called while the option is +being ignored, the option is NOT ignored during the execution of the +function. Hence, if tt(foo) in `tt(foo && true)' is a function, code +inside it is considered separately: it may force a return from tt(foo) +(assuming the option remains set within tt(foo)). + +Like for tt(ERR_EXIT), the option is ignored inside tt(DEBUG) traps +but it's not unset on entry to the trap and setting or unsetting it +inside the trap has no special effect. + +If tt(ERR_RETURN) and tt(ERR_EXIT) are both set, it may happen that +both exit and return should be triggered. In that case only exit is +triggered. ) pindex(EVAL_LINENO) pindex(NO_EVAL_LINENO) @@ -1884,6 +1904,11 @@ fn2)var(...)tt(LPAR()RPAR())'; if the option is not set, this causes a parse error. Definition of multiple functions with the tt(function) keyword is always allowed. Multiple function definitions are not often used and can cause obscure errors. + +Note that no error is raised if multiple functions are defined as a +result of a set of names that were originally read as a single word on +the command line, for example `tt(TRAP{INT,QUIT})'. Although there are +no plans to change this behaviour at present, it is not guaranteed. ) pindex(MULTIOS) pindex(NO_MULTIOS) @@ -1952,7 +1977,7 @@ pindex(NOTYPESETTOUNSET) item(tt(TYPESET_TO_UNSET) <K> <S>)( When declaring a new parameter with any of the `tt(typeset)' family of related commands, the parameter remains unset unless and until a -value is explicity assigned to it, either in the `tt(typeset)' command +value is explicitly assigned to it, either in the `tt(typeset)' command itself or as a later assignment statement. ) pindex(VERBOSE) @@ -2545,10 +2570,12 @@ pindex(NO_EMACS) pindex(NOEMACS) item(tt(EMACS))( If ZLE is loaded, turning on this option has the equivalent effect -of `tt(bindkey -e)'. In addition, the VI option is unset. +of `tt(bindkey -e)'. In addition, the tt(VI) option is unset. Turning it off has no effect. The option setting is -not guaranteed to reflect the current keymap. This option is -provided for compatibility; tt(bindkey) is the recommended interface. +not guaranteed to reflect the current keymap, and the tt(LOCALOPTIONS) +option does not work correctly. This option is provided only for +compatibility, and its use is highly discouraged. tt(bindkey) is the +recommended interface. ) pindex(OVERSTRIKE) pindex(NO_OVERSTRIKE) @@ -2577,10 +2604,12 @@ pindex(NO_VI) pindex(NOVI) item(tt(VI))( If ZLE is loaded, turning on this option has the equivalent effect -of `tt(bindkey -v)'. In addition, the EMACS option is unset. +of `tt(bindkey -v)'. In addition, the tt(EMACS) option is unset. Turning it off has no effect. The option setting is -not guaranteed to reflect the current keymap. This option is -provided for compatibility; tt(bindkey) is the recommended interface. +not guaranteed to reflect the current keymap, and the tt(LOCALOPTIONS) +option does not work correctly. This option is provided only for +compatibility, and its use is highly discouraged. tt(bindkey) is the +recommended interface. ) pindex(ZLE) pindex(NO_ZLE) diff --git a/Doc/Zsh/params.yo b/Doc/Zsh/params.yo index b543d1c38..69298855f 100644 --- a/Doc/Zsh/params.yo +++ b/Doc/Zsh/params.yo @@ -52,6 +52,20 @@ cindex(assignment) ifzman() indent(var(name)tt(=)var(value)) +cindex(namespace) +The var(name) in an assignment may optionally include a em(namespace) +prefix: +ifzman() +indent(tt(.)var(namespace)tt(.)var(parameter)tt(=)var(value)) + +Namespaces have no special meaning to the shell except that parameters +with a `tt(.)' prefix are not listed by the `tt(set)' builtin, nor +shown by the `tt(typeset)' builtin unless explicitly named or the +`tt(-m)' option is used. They provide a convenient way to group +related variables. Note that, for support of possible future features, +the first `tt(.)' is optional, but omitting it is discouraged. Unlike +ksh, a namespace need not be declared before it is referenced. + 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. @@ -70,7 +84,8 @@ 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 +`tt(${)var(name)tt(})'. The latter form is required when var(name) +includes a namespace prefix. See ifzman(em(Parameter Expansion) in zmanref(zshexpn))\ ifnzman(noderef(Parameter Expansion)) for complete details. That section also explains the effect @@ -80,10 +95,13 @@ startmenu() menu(Array Parameters) menu(Positional Parameters) menu(Local Parameters) +menu(Named References) menu(Parameters Set By The Shell) menu(Parameters Used By The Shell) endmenu() texinode(Array Parameters)(Positional Parameters)()(Parameters) +cindex(array parameters) +cindex(parameters, array) sect(Array Parameters) To assign an array value, write one of: findex(set, use of) @@ -566,6 +584,8 @@ entire second parameter concatenated with the filename generation pattern `tt([3,5])'. texinode(Positional Parameters)(Local Parameters)(Array Parameters)(Parameters) +cindex(positional parameters) +cindex(parameters, positional) sect(Positional Parameters) The positional parameters provide access to the command-line arguments of a shell function, shell script, or the shell itself; see @@ -592,7 +612,9 @@ array assignment of the form `var(n)tt(=LPAR())var(value) ...tt(RPAR())' is allowed, and has the effect of shifting all the values at positions greater than var(n) by as many positions as necessary to accommodate the new values. -texinode(Local Parameters)(Parameters Set By The Shell)(Positional Parameters)(Parameters) +texinode(Local Parameters)(Named References)(Positional Parameters)(Parameters) +cindex(local parameters) +cindex(parameters, local) sect(Local Parameters) Shell function executions delimit scopes for shell parameters. (Parameters are dynamically scoped.) The tt(typeset) builtin, and its @@ -626,7 +648,53 @@ find the programs in tt(/new/directory) inside a function. Note that the restriction in older versions of zsh that local parameters were never exported has been removed. -texinode(Parameters Set By The Shell)(Parameters Used By The Shell)(Local Parameters)(Parameters) +texinode(Named References)(Parameters Set By The Shell)(Local Parameters)(Parameters) +cindex(named references) +cindex(references, named) +sect(Named References) +Zsh supports two different mechanisms for indirect parameter referencing: +ifzman() +example(tt(typeset )var(name)tt(=)var(rname) +tt(print -r -- ${LPAR()P)tt(RPAR())var(name)tt(})) +ifzman() +example(tt(typeset -n )var(pname)tt(=)var(rname) +tt(print -r -- ${)var(pname)tt(})) + +The `tt((P))' flag method is older and should be used when a script +needs to be backwards-compatible. This is described fully in +the Parameter Expansion Flags section of +ifzman(zmanref(zshexpn))ifnzman(noderef(Parameter Expansion)). Zsh +versions em(greater than) tt(5.9.0) are required for `tt(typeset -n)'. +This manual was generated with Zsh tt(version()). + +When a em(named reference) is created with `tt(typeset -n)', all uses +of var(pname) in assignments and expansions instead assign to or +expand var(rname). This also applies to `tt(unset )var(pname)' and to +most subsequent uses of `tt(typeset)' with the exceptions of declaring +a local in a called function, or updating a current-scope parameter with +`tt(typeset -n)' or `tt(typeset +n)'. Thus to remove a named reference, +use either `tt(unset -n )var(pname)' (preferred) or one of: +ifzman() +example(tt(typeset -n )var(pname=) +tt(typeset +n )var(pname)) + +followed by +ifzman() +indent(tt(unset )var(pname)) + +An empty reference such as one of +ifzman() +example(tt(typeset -n )var(pname) +tt(typeset -n )var(pname)tt(=) +tt(typeset -n )var(pname)tt(="")) + +acts as a placeholder. The first non-empty assignment to var(pname) +initializes the reference, and subsequently any expansions of, or +assignments to, var(pname) act on the referenced parameter. This +is explained in the Named References section of +ifzman(zmanref(zshexpn))ifnzman(noderef(Parameter Expansion)). + +texinode(Parameters Set By The Shell)(Parameters Used By The Shell)(Named References)(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 @@ -681,9 +749,13 @@ vindex(argv) item(tt(argv) <S> <Z>)( Same as tt(*). Assigning to tt(argv) changes the local positional parameters, but tt(argv) is em(not) itself a local parameter. -Deleting tt(argv) with tt(unset) in any function deletes it everywhere, -although only the innermost positional parameter array is deleted (so -tt(*) and tt(@) in other scopes are not affected). +Deleting tt(argv) with tt(unset) in any function deletes it everywhere. +This can be avoided by declaring `tt(local +h argv)' before unsetting. +Even when not so declared, only the innermost positional parameter +array is deleted (so tt(*) and tt(@) in other scopes are not affected). + +A named reference to tt(argv) em(does not) permit a called function to +access the positional parameters of its caller. ) vindex(@) item(tt(@) <S>)( @@ -712,7 +784,10 @@ last pipeline. ) vindex(_) item(tt(_) <S>)( -The last argument of the previous command. +Initially, if tt(_) exists in the environment, then this parameter is set to +its value. This value may be the full pathname of the current zsh +executable or the script command file. +Later, this parameter is set to the last argument of the previous command. Also, this parameter is set in the environment of every command executed to the full pathname of the command. ) @@ -851,7 +926,9 @@ referenced or seeded in the parent shell in between subshell invocations. ) vindex(SECONDS) item(tt(SECONDS) <S>)( -The number of seconds since shell invocation. If this parameter +The number of seconds since shell invocation. On most platforms, this +is a monotonic value, so it is not affected by NTP time jumps or other +clock changes (though it may be affected by slewing). If this parameter is assigned a value, then the value returned upon reference will be the value that was assigned plus the number of seconds since the assignment. @@ -861,8 +938,10 @@ be changed using the tt(typeset) command. The type may be changed only to one of the floating point types or back to integer. For example, `tt(typeset -F SECONDS)' causes the value to be reported as a floating point number. The -value is available to microsecond accuracy, although the shell may -show more or fewer digits depending on the use of tt(typeset). See +value is nominally available to nanosecond precision, although this +varies by platform (and probably isn't accurate to 1 ns regardless), +and the shell may show more or fewer digits depending on the +use of tt(typeset). See the documentation for the builtin tt(typeset) in ifzman(zmanref(zshbuiltins))\ ifnzman(noderef(Shell Builtin Commands)) for more details. @@ -879,7 +958,10 @@ has index 1, the signals are offset by 1 from the signal number used by the operating system. For example, on typical Unix-like systems tt(HUP) is signal number 1, but is referred to as tt($signals[2]). This is because of tt(EXIT) at position 1 in the array, which is used -internally by zsh but is not known to the operating system. +internally by zsh but is not known to the operating system. On many systems +there is a block of reserved or unused signal numbers before the POSIX +real-time signals so the array index can't be used as an accurate indicator +of their signal number. Use, for example, tt(kill -l SIGRTMIN) instead. ) vindex(TRY_BLOCK_ERROR) item(tt(TRY_BLOCK_ERROR) <S>)( @@ -953,11 +1035,12 @@ Code specified by the tt(-c) option to the command line that invoked the shell. ) item(tt(cmdsubst))( -Command substitution using the tt(`)var(...)tt(`) or -tt($+LPAR())var(...)tt(RPAR()) construct. +Command substitution using of the tt(`)var(...)tt(`), +tt($+LPAR())var(...)tt(RPAR()),tt(${{)var(name)tt(}) var(...)tt(}), +tt(${|)var(...)tt(}), or tt(${ )var(...)tt( }) constructs. ) item(tt(equalsubst))( -File substitution using the tt(=+LPAR())var(...)tt(RPAR()) construct. +The tt(=+LPAR())var(...)tt(RPAR()) form of process substitution. ) item(tt(eval))( Code executed by the tt(eval) builtin. @@ -985,13 +1068,13 @@ item(tt(globsort))( Code executed to order files by the tt(o) glob qualifier. ) item(tt(insubst))( -File substitution using the tt(<LPAR())var(...)tt(RPAR()) construct. +The tt(<LPAR())var(...)tt(RPAR()) form of process substitution. ) item(tt(loadautofunc))( Code read directly from a file to define an autoloaded function. ) item(tt(outsubst))( -File substitution using the tt(>LPAR())var(...)tt(RPAR()) construct. +The tt(>LPAR())var(...)tt(RPAR()) form of process substitution. ) item(tt(sched))( Code executed by the tt(sched) builtin. @@ -1042,6 +1125,10 @@ item(tt(ZSH_EXECUTION_STRING))( If the shell was started with the option tt(-c), this contains the argument passed to the option. Otherwise it is not set. ) +vindex(ZSH_EXEPATH) +item(tt(ZSH_EXEPATH))( +Full pathname of the executable file of the current zsh process. +) vindex(ZSH_NAME) item(tt(ZSH_NAME))( Expands to the basename of the command used to invoke this instance @@ -1251,15 +1338,18 @@ Internal field separators (by default space, tab, newline and NUL), that are used to separate words which result from command or parameter expansion and words read by the tt(read) builtin. Any characters from the set space, tab and -newline that appear in the IFS are called em(IFS white space). +newline that appear in the tt(IFS) are called em(IFS white space). One or more IFS white space characters or one non-IFS white space character together with any adjacent IFS white space character delimit a field. If an IFS white space character appears twice consecutively -in the IFS, this character is treated as if it were not an IFS white +in the tt(IFS), this character is treated as if it were not an IFS white space character. If the parameter is unset, the default is used. Note this has a different effect from setting the parameter to an empty string. + +If tt(MULTIBYTE) option is on and tt(IFS) contains invalid characters in +the current locale, it is reset to the default. ) vindex(KEYBOARD_HACK) item(tt(KEYBOARD_HACK))( @@ -1414,6 +1504,7 @@ An array (colon-separated list) of directories to search for commands. When this parameter is set, each directory is scanned and all files found are put in a hash table. +Directories named by relative path are not scanned for hashing. ) vindex(POSTEDIT) item(tt(POSTEDIT) <S>)( @@ -1553,9 +1644,13 @@ All other prompt escapes are also allowed. The actions available at the prompt are tt([nyae]): startsitem() -sitem(tt(n) +LPAR()`no'+RPAR() +LPAR()default+RPAR())(Discard the correction and run the command.) -sitem(tt(y) +LPAR()`yes'+RPAR())(Make the correction and run the command.) -sitem(tt(a) +LPAR()`abort'+RPAR())(Discard the entire command line without running it.) +sitem(tt(n) +LPAR()`no'+RPAR() +LPAR()default+RPAR())(Discard the correction. +If there are no more corrections, accept the command line, else (with +tt(CORRECT_ALL)) prompt for the next.) +sitem(tt(y) +LPAR()`yes'+RPAR())(Make the correction. If there are no more +corrections, accept the command line.) +sitem(tt(a) +LPAR()`abort'+RPAR())(Place the entire command line in the +history for later edit, but without accepting it.) sitem(tt(e) +LPAR()`edit'+RPAR())(Resume editing the command line.) endsitem() ) @@ -1644,8 +1739,12 @@ A star may be inserted between the percent sign and flags printing time (e.g., `tt(%*E)'); this causes the time to be printed in `var(hh)tt(:)var(mm)tt(:)var(ss)tt(.)var(ttt)' format (hours and minutes are only printed if they are not zero). -Alternatively, `tt(m)' or `tt(u)' may be used (e.g., `tt(%mE)') to produce -time output in milliseconds or microseconds, respectively. +Alternatively, `tt(m)', `tt(u)', or `tt(n)' may be used (e.g., +`tt(%mE)') to produce time output in milliseconds, microseconds, or +nanoseconds, respectively. Note that some timings on some platforms +are not actually nanosecond-precise (nor accurate to 1 ns when +they are); in fact on many systems user and kernel times are not +even microsecond-precise. ) vindex(TMOUT) item(tt(TMOUT))( @@ -1667,7 +1766,7 @@ well as any directory names. The default is `tt(/tmp/zsh)'. vindex(TMPSUFFIX) item(tt(TMPSUFFIX))( A filename suffix which the shell will use for temporary files created -by process substitutions (e.g., `tt(=LPAR()var(list)RPAR())'). +by process substitutions (e.g., `tt(=LPAR())var(list)tt(RPAR())'). Note that the value should include a leading dot `tt(.)' if intended to be interpreted as a file extension. The default is not to append any suffix, thus this parameter should be assigned only when needed diff --git a/Doc/Zsh/prompt.yo b/Doc/Zsh/prompt.yo index 909012c8e..108cb62e5 100644 --- a/Doc/Zsh/prompt.yo +++ b/Doc/Zsh/prompt.yo @@ -195,7 +195,8 @@ sitem(tt(%K))(the hour of the day on the 24-hour clock) sitem(tt(%L))(the hour of the day on the 12-hour clock) endsitem() -In addition, if the system supports the POSIX tt(gettimeofday) system +In addition, if the system supports the POSIX tt(clock_gettime) +or tt(gettimeofday) system call, tt(%.) provides decimal fractions of a second since the epoch with leading zeroes. By default three decimal places are provided, but a number of digits up to 9 may be given following the tt(%); hence tt(%6.) @@ -246,6 +247,14 @@ item(tt(%K) LPAR()tt(%k)RPAR())( Start (stop) using a different bacKground colour. The syntax is identical to that for tt(%F) and tt(%f). ) +item(tt(%H))( +Change all character visual attributes using a highlighting specification from +the tt(.zle.hlgroups) associative array. The key is specified in following +braces so, for example tt(%H{error}) will use the highlighting specification +for the `error' group. If the key is not found in the associative array then +it has no effect. Highlighting specifications are in the same format as for +the tt(zle_highlight) parameter. +) item(tt(%{)...tt(%}))( Include a string as a literal escape sequence. The string within the braces should not change the cursor diff --git a/Doc/Zsh/restricted.yo b/Doc/Zsh/restricted.yo index 33dfc96c6..a84fd28ea 100644 --- a/Doc/Zsh/restricted.yo +++ b/Doc/Zsh/restricted.yo @@ -65,10 +65,10 @@ variables. Except for the few listed above, zsh does not restrict the setting of environment variables. If a `tt(perl)', `tt(python)', `tt(bash)', or other general purpose -interpreted script it treated as a restricted +interpreted script is treated as a restricted command, the user can work around the restriction by setting specially crafted `tt(PERL5LIB)', `tt(PYTHONPATH)', -`tt(BASHENV)' (etc.) environment variables. On GNU systems, any +`tt(BASH_ENV)' (etc.) environment variables. On GNU systems, any command can be made to run arbitrary code when performing character set conversion (including zsh itself) by setting a `tt(GCONV_PATH)' environment variable. Those are only a few examples. diff --git a/Doc/Zsh/zle.yo b/Doc/Zsh/zle.yo index 2d033a0a1..31eb3f3ba 100644 --- a/Doc/Zsh/zle.yo +++ b/Doc/Zsh/zle.yo @@ -376,7 +376,7 @@ If the tt(-p) flag is given, the following string will be taken as the prompt to display at the left. If the tt(-r) flag is given, the following string gives the prompt to display at the right. If the tt(-h) flag is specified, the history can be accessed from ZLE. If the -tt(-e) flag is given, typing tt(^D) (Control-D) on an empty line +tt(-e) flag is given, typing tt(^D) (Control-D) in an empty buffer causes tt(vared) to exit immediately with a non-zero return value. The tt(-M) option gives a keymap to link to the tt(main) keymap during @@ -2470,10 +2470,11 @@ command. tt(run-help) is normally aliased to tt(man). tindex(vi-set-buffer) item(tt(vi-set-buffer) (unbound) (tt(")) (unbound))( Specify a buffer to be used in the following command. -There are 37 buffers that can be specified: +There are 39 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). +the nine `queued' buffers tt("1) to tt("9), the `black hole' buffer +tt("_) and the system selection tt("*) and clipboard 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 @@ -2482,6 +2483,10 @@ appended to the buffer instead of overwriting it. When using the tt("_) buffer, nothing happens. This can be useful for deleting text without affecting any buffers. +Updating the system clipboard relies on specific support from the terminal. +Reading it is not possible so a paste command with tt("*) or tt("+) will do +nothing. + 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 @@ -2686,6 +2691,9 @@ for different completions. item(tt(paste))( Following a command to paste text, the characters that were inserted. ) +item(tt(ellipsis))( +Markers used to indicate where the text doesn't fit within the terminal. +) enditem() When tt(region_highlight) is set, the contexts that describe a region DASH()- @@ -2775,9 +2783,13 @@ This works similarly to the foreground colour, except the background is not usually affected by the bold attribute. ) item(tt(bold))( -The characters in the given context are shown in a bold font. +The characters in the given context are shown with a bold font weight. Not all terminals distinguish bold fonts. ) +item(tt(faint))( +The characters in the given context are shown with a faint font weight. +Not all terminals distinguish faint fonts. +) item(tt(standout))( The characters in the given context are shown in the terminal's standout mode. The actual effect is specific to the terminal; on many terminals it @@ -2791,6 +2803,21 @@ The characters in the given context are shown underlined. Some terminals show the foreground in a different colour instead; in this case whitespace will not be highlighted. ) +item(tt(italic))( +The characters in the given context are shown in a italic font. +Not all terminals support italic fonts. +) +item(tt(hl=)var(group))( +Use the specified highlighting group. The var(group) is used as a key into +the associative array tt(.zle.hlgroups) to determine the actual highlighting. +) +item(tt(layer=)var(layer))( +The layer is used to determine precedence when multiple highlighting regions +overlap. The var(layer) is a decimal integer, with higher numbers taking +precedence over lower numbers. The default layer is 10 with 30 used as the +default for tt(special), 20 for tt(region) and tt(isearch) and 15 for +tt(paste). +) enditem() The characters described above as `special' are as follows. The diff --git a/Doc/intro.ms b/Doc/intro.ms index 4dd08f601..49f6cc07f 100644 --- a/Doc/intro.ms +++ b/Doc/intro.ms @@ -3,8 +3,32 @@ .if \n(.g \{\ .if "\*(.T"ascii" .ftr C R .if "\*(.T"latin1" .ftr C R +.if "\*(.T"html" .nr HTML 1 .nr De \n[.ss] .\} +.\" ----- macro defintions ----- +.\" Ds/De: start/end of example +.\" Sh: section header +.\" XXX: It seems we can't use the same definition for both pdf and html +.\" (at least with groff-12.3.0). +.\" +.\" for HTML output +.ie \n[HTML] \{\ +.de Ds +.DS I .5i +.ft C +.. +.de De +.DE +.ft R +.. +.de Sh +.NH +\\$1 +.. +.\} +.\" for other output (such as PDF) +.el \{\ .de Ds .DS I .5i .ft C @@ -21,12 +45,13 @@ .el .ss .. .de Sh -.SH -\\$1 -.XS -\\$1 -.XE +.NH +.XN \\$1 .. +.\} +.\" +.\" ----- Cover page ----- +.if !\n[HTML] \{\ .nr HM 4i .ce 99 .ps 18 @@ -50,6 +75,9 @@ bas@phys.uva.nl\fP .sv |1i .pn 1 .bp +.\} +.\" +.\" ----- main text ----- .TL An Introduction to the Z Shell .AU @@ -2712,6 +2740,7 @@ I (Bas de Bakker) would be happy to receive mail if anyone has any tricks or ideas to add to this document, or if there are some points that could be made clearer or covered more thoroughly. Please notify me of any errors in this document. +.if !\n[HTML] \{\ .if o \{\ .bp .sv 1i @@ -2719,3 +2748,4 @@ me of any errors in this document. .pn 1 .bp .PX +.\} |