diff options
Diffstat (limited to 'Etc/FAQ.yo')
| -rw-r--r-- | Etc/FAQ.yo | 200 |
1 files changed, 184 insertions, 16 deletions
diff --git a/Etc/FAQ.yo b/Etc/FAQ.yo index 8c795685a..4e11637ea 100644 --- a/Etc/FAQ.yo +++ b/Etc/FAQ.yo @@ -101,6 +101,10 @@ Chapter 2: How does zsh differ from...? 2.6. Shouldn't zsh be more/less like ksh/(t)csh? 2.7. What is zsh's support for Unicode/UTF-8? 2.8. Why does my bash script report an error when I run it under zsh? +2.9. What is a `namespace' anyway? +2.10. What about named references? +2.11. What is zsh's support for non-forking command substitution? +2.12. Comparisons of forking and non-forking command substitution Chapter 3: How to get various things to work 3.1. Why does `$var' where `var="foo bar"' not do what I expect? @@ -445,7 +449,14 @@ label(21) invoked with the appropriate name. Including the command `emulate sh; setopt localoptions' in a shell function will turn on sh emulation for that function only. In version 4 (and in - 3.0.6 through 8), this can be abbreviated as `emulate -L sh'. + 3.0.6 through 8), this can be abbreviated as `emulate -L sh'; + myeit() in versions after 5.9, the myem(namespace) syntax and + myem(named references) (ksh mytt(nameref)) are available, but + differ in some details from the ksh93+ semantics; + myeit() also after 5.9, myem(non-forking command substitutions) are + available. These are described by ksh as myem(a brace group preceded + by a dollar sign) (mytt(${ list;})), but zsh has both some added + features adopted from mksh, and some limitations, see link(2.11)(211) ) The classic difference is word splitting, discussed in question \ @@ -496,9 +507,9 @@ tt(RM_STAR_SILENT), those are a completely different type of object.) it() Coprocesses are established by mytt(coproc); mytt(|&) behaves like csh. Handling of coprocess file descriptors is also different. - it() In mytt(cmd1 && cmd2 &), only mytt(cmd2) instead of the whole - expression is run in the background in zsh. The manual implies - this is a bug. Use mytt({ cmd1 && cmd2 } &) as a workaround. + it() In mytt(cmd1 && cmd2 &), instead of backgrounding the whole + expression, only mytt(cmd2) is run in the background in zsh. + Use mytt(( cmd1 && cmd2 ) &) as a workaround. ) it() Command line substitutions, globbing etc.: itemization( @@ -960,6 +971,164 @@ label(28) languages and adjusting it accordingly, just like you would when translating a book from American English to British English. +sect(What is a mytt(namespace) anyway?) +label(29) + + As of this writing, namespaces in zsh are little more than syntactic + sugar for grouping related parameters. For example, as of the update + to PCRE2, the parameters ${.pcre.match} and ${.pcre.subject} are used + for regular expression substring capture. The mytt(.pcre.) part is + the namespace, and when you refer to a parameter that has one, you + mybf(must) use the mytt(${...}) braces around the name. Assignments + are not special, they have the form mytt(.nspace.var=value) as usual. + + Parameters using a namespace have the additional property that, like + file names beginning with a dot for globbing, they're hidden from + mytt(typeset) output unless explicitly asked for. + + Namespaces appear in releases after but not including zsh 5.9. + +sect(What about named references?) +label(210) + + Named references are a bit like aliases, but for parameters. A named + reference would typically be usable in the same cases as ${(P)name} + (see link(3.22)(322)). The value of a named reference is the name + of another parameter, and when you expand or assign to the named + reference, that other parameter is expanded or assigned instead. + Thus a trivial example is + verb( + % target=RING + % typeset -n ref=target + % print $ref + RING + % ref=BULLSEYE + % print $target + BULLSEYE + ) + + One exception to this behavior is when a named reference is used as + the loop variable in a mytt(for) loop. In that case the reference is + unset and reset on each iteration of the loop. + verb( + % target=RING bullseye=SPOT other=MISS + % typeset -n ref=other + % for ref in target bullseye; do + > print $ref + > ref=HIT:$ref + > done + RING + SPOT + % print $other + MISS + % print $ref + HIT:SPOT + ) + + Dynamic scoping applies to named references, so for example a named + reference declared in global scope may be used in function scopes. + In ksh, local parameters have static scope, so named references in + zsh may have side-effects that do not occur in ksh. To limit those + effects, mytt(zmodload zsh/param/private) and declare all named + references mytt(private). + + Named references may be used in zsh versions later than 5.9. + +sect(What is zsh's support for non-forking command substitution?) +label(211) + + This is for cases where you'd write mytt($(command)) but you don't want + the overhead or other issues associated with forking a subshell. + There are 3 variations: + itemization( + eit() Borrowed from mksh + verb( + ${| code } + ) + Runs code in the current shell context and then substitutes mytt(${REPLY}). + The result is not split into words unless the tt(SH_WORD_SPLIT) option + is set, for example by mytt(${=${| code }}). mytt($REPLY) is a local + parameter within the substitution so its value in the surrounding scope + is not changed. + + eit() An extension to #1 + verb( + ${{var} code } + ) + Runs code in the current shell and then substitutes mytt(${var}). If + mytt(${var}) names an array, the result is an array of those elements, + but no further splitting is done without tt(SH_WORD_SPLIT). mytt(${var}) + is myem(not) local to the substitution. + + eit() The traditional ksh form, except that the closing mytt(;) + may usually be omitted: + verb( + ${ code } + ) + Runs code in the current shell and substitutes its standard output. + (this is done with a temporary file ala mytt($(<=( code ))) but + without the fork implied by mytt(=(...))). The result is not split + into words without tt(SH_WORD_SPLIT). + ) + + In all three forms mytt(code) behaves myem(similarly) to an anonymous + function invoked like: + verb( + () { code } "$@" + ) + Thus, all parameters declared inside the substitution are local by + default, and positional parameters mytt($1), mytt($2), etc. are those + of the calling context. + + The most significant limitation is that braces (mytt({) and mytt(})) + within the substitutions must either be in balanced pairs, or must be + quoted, that is, included in a quoted string or prefixed by backslash. + These substitutions first become usable after zsh 5.9. + +sect(Comparisons of forking and non-forking command substitution) + + mytt(${ command }) and variants may change the caller's options by using + mytt(setopt) and may modify the caller's local parameters, including the + positional parameters mytt($1), mytt($2), etc., via both assignments and + mytt(set -- pos1 pos2 etc). Nothing that happens within mytt($(command)) + affects the caller. + + When not enclosed in double quotes, the expansion of mytt($(command)) is + split on tt(IFS) into an array of words. In contrast, and unlike both + bash and ksh, unquoted non-forking substitutions behave like parameter + expansions with respect to the tt(SH_WORD_SPLIT) option. + + Both mytt(${|...}) and mytt(${{var} ...}) retain any trailing newlines, + except as handled by the tt(SH_WORD_SPLIT) option, consistent with + mytt(${|...}) from mksh. mytt(${ command }) removes a single final + newline, but mytt("${ command }") retains it. This differs from + bash and ksh, so in emulation modes, newlines are stripped even from + quoted command output. In all cases, mytt($(command)) removes all + trailing newlines from the output of mytt(command). + + When mytt(command) is myem(not) a builtin, mytt(${ command }) does + fork, and typically forks the same number of times as + mytt($(command)), because in the latter case zsh usually optimizes + the final fork into an exec. + + Redirecting input from files has subtle differences: + itemization( + it() mytt($(<file)) is optimized to read from mytt(file) without forking, + but per above it removes trailing newlines. + it() mytt(${<file}) is a substitution error. + it() mytt(${ <file }) copies mytt(file) using the mytt(NULLCMD) programs, + then reads and substitutes the contents of the copy. Also, this + fails if the tt(CSH_NULLCMD) or tt(SH_NULLCMD) options are in effect, + so it does not work in emulation modes. + it() mytt(${|<file}) copies mytt(file) to the standard output using + tt(NULLCMD) but substitutes nothing because there is no assignment + to tt(REPLY). It also fails in emulation modes. + ) + mytt(${|IFS= read -rd '' <file}) is therefore the best solution for files + that do not contain nul bytes, because it copies the file directly into + the local mytt(REPLY) and then substitutes that. For very large files, + refer to mytt(Functions/Misc/zslurp). + chapter(How to get various things to work) sect(Why does mytt($var) where mytt(var="foo bar") not do what I expect?) @@ -1641,6 +1810,7 @@ label(321) manual. sect(How do I get a variable's value to be evaluated as another variable?) +label(322) The problem is that you have a variable tt($E) containing the string mytt(EDITOR), and a variable tt($EDITOR) containing the string mytt(emacs), @@ -1833,7 +2003,7 @@ sect(Why is my output duplicated with `tt(foo 2>&1 >foo.out | bar)'?) to both files when the redirector appears twice. What's going on in the first example is exactly the same, however the second redirector is disguised as a pipe. So if you want to turn this effect off, you need - to unset the option mytt(MULTIOS), or alternatively write the following: + to unset the option tt(MULTIOS), or alternatively write the following: verb( % { print output; print error >&2 } 2>&1 >&- >foo.out | sed 's/error/erratic/' erratic @@ -2509,14 +2679,11 @@ sect(What's on the wish-list?) characters. Initial support for this appeared in version 4.3; it is reasonably complete in the line editor but patchy elsewhere (note this may require the configuration option --enable-multibyte). - it() The parameter code could do with tidying up, maybe with more of the - features made available in ksh93. + it() The parameter code could do with tidying up. it() Configuration files to enable zsh startup files to be created with the Dotfile Generator. it() Further improvements in integrating the line editor with shell functions. - it() POSIX compatibility could be improved. - it() Option for glob qualifiers to follow perl syntax (a traditional item). ) sect(Did zsh have problems in the year 2000?) @@ -2618,11 +2785,12 @@ https://github.com/chrisbra/vim_faq/blob/de424bd8e08bcf0e6b1e0563ee49514dfed926a nsect(Acknowledgments:) -Thanks to zsh-list, in particular Bart Schaefer, for suggestions +Thanks to zsh-workers, in particular Bart Schaefer, for suggestions regarding this document. Zsh has been in the hands of archivists Jim Mattson, Bas de Bakker, Richard Coleman, Zoltan Hidvegi and Andrew -Main, and the mailing list has been run by Peter Gray, Rick Ohnemus, -Richard Coleman, Karsten Thygesen and Geoff Wing, all of whom deserve +Main, and the mailing lists have been managed or hosted by Peter Gray, +Rick Ohnemus, Richard Coleman, Karsten Thygesen, Geoff Wing, Phil +Pennock, Daniel Shahaf, and Oliver Kiddle, all of whom deserve thanks. The world is eternally in the debt of Paul Falstad for inventing zsh in the first place (though the wizzo extended completion is by Sven Wischnowsky). @@ -2630,15 +2798,15 @@ Wischnowsky). nsect(Copyright Information:) This document is copyright (C) P.W. Stephenson, 1995, 1996, 1997, -1998, 1999, 2000, 2012, 2020. This text originates in the U.K. and the author -asserts his moral rights under the Copyrights, Designs and Patents Act, -1988. +1998, 1999, 2000, 2012, 2020, 2023. This text originates in the U.K. +and the author asserts his moral rights under the Copyrights, Designs +and Patents Act, 1988. Permission is hereby granted, without written agreement and without license or royalty fees, to use, copy, modify, and distribute this documentation for any purpose, provided that the above copyright notice appears in all copies of this documentation. Remember, -however, that this document changes monthly and it may be more useful +however, this document changes occasionally and it may be more useful to provide a pointer to it rather than the entire text. A suitable pointer is "information on the Z-shell can be obtained on the World Wide Web at URL https://zsh.sourceforge.io/". |