diff options
Diffstat (limited to 'Doc/zshexpn.1')
| -rw-r--r-- | Doc/zshexpn.1 | 175 |
1 files changed, 126 insertions, 49 deletions
diff --git a/Doc/zshexpn.1 b/Doc/zshexpn.1 index 9987820e8..9ec445400 100644 --- a/Doc/zshexpn.1 +++ b/Doc/zshexpn.1 @@ -1,4 +1,4 @@ -.TH "ZSHEXPN" "1" "February 12, 2022" "zsh 5\&.8\&.1" +.TH "ZSHEXPN" "1" "April 9, 2022" "zsh 5\&.8\&.1\&.2-test" .SH "NAME" zshexpn \- zsh expansion and substitution .\" Yodl file: Zsh/expn.yo @@ -66,7 +66,7 @@ EXPANSION OF PROMPT SEQUENCES in \fIzshmisc\fP(1)) is the number that is to be a A history expansion begins with the first character of the \fBhistchars\fP parameter, which is `\fB!\fP\&' by default, and may occur anywhere on the command line, including inside double quotes (but not inside single quotes -\fB\&'\&.\&.\&.'\fP or C\-style quotes \fB$'\&.\&.\&.'\fP nor when escaped with a backslash)\&. +\fB\&'\&.\&.\&.'\fP or C\-style quotes \fB$'\&.\&.\&.'\fP nor when escaped with a backslash)\&. .PP The first character is followed by an optional event designator (see the section `Event Designators\&') and then an optional word @@ -277,8 +277,10 @@ expansion\&. .TP \fBP\fP Turn a file name into an absolute path, like \fBrealpath(3)\fP\&. -The resulting path will be absolute, have neither `\fB\&.\fP\&' nor `\fB\&.\&.\fP' components, -and refer to the same directory entry as the input filename\&. +The resulting path will be absolute, +will refer to the same directory entry as the input filename, +and none of its components will be symbolic links or equal to +`\fB\&.\fP\&' or `\fB\&.\&.\fP'\&. .RS .PP Unlike \fBrealpath(3)\fP, non\-existent trailing components are @@ -490,7 +492,7 @@ which treats \fIarg\fP as a file name and replaces it with the file\&'s contents\&. .PP The \fB=\fP form is useful as both the \fB/dev/fd\fP and the named pipe -implementation of \fB<(\fP\fI\&.\&.\&.\fP\fB)\fP have drawbacks\&. In +implementation of \fB<(\fP\fI\&.\&.\&.\fP\fB)\fP have drawbacks\&. In the former case, some programmes may automatically close the file descriptor in question before examining the file on the command line, particularly if this is necessary for security reasons such as when the @@ -507,8 +509,7 @@ efficiently written (provided the \fBMULTIOS\fP option is set) as: .PP .RS .nf -\fB\fBpaste <(cut \-f1\fP \fIfile1\fP\fB) <(cut \-f3\fP \fIfile2\fP\fB)\fP \e -\fB> >(\fP\fIprocess1\fP\fB) > >(\fP\fIprocess2\fP\fB)\fP\fP +\fB\fBpaste <(cut \-f1\fP \fIfile1\fP\fB) <(cut \-f3\fP \fIfile2\fP\fB)\fP \fB> >(\fP\fIprocess1\fP\fB) > >(\fP\fIprocess2\fP\fB)\fP\fP .fi .RE .PP @@ -943,7 +944,11 @@ of the string \fB$\-\fP and the array \fB$*\fP respectively\&. If the \fB#\fP to be treated in this fashion\&. .RE .TP +.PD 0 \fB${^\fP\fIspec\fP\fB}\fP +.TP +.PD +\fB${^^\fP\fIspec\fP\fB}\fP Turn on the \fBRC_EXPAND_PARAM\fP option for the evaluation of \fIspec\fP; if the `\fB^\fP\&' is doubled, turn it off\&. When this option is set, array expansions of the form @@ -965,7 +970,11 @@ happening later\&. If word splitting is also in effect the elements\&. .RE .TP +.PD 0 \fB${=\fP\fIspec\fP\fB}\fP +.TP +.PD +\fB${==\fP\fIspec\fP\fB}\fP Perform word splitting using the rules for \fBSH_WORD_SPLIT\fP during the evaluation of \fIspec\fP, but regardless of whether the parameter appears in double quotes; if the `\fB=\fP\&' is doubled, turn it off\&. @@ -979,7 +988,11 @@ of \fIspec\fP \fIbefore\fP the assignment to \fIname\fP is performed\&. This affects the result of array assignments with the \fBA\fP flag\&. .RE .TP +.PD 0 \fB${~\fP\fIspec\fP\fB}\fP +.TP +.PD +\fB${~~\fP\fIspec\fP\fB}\fP Turn on the \fBGLOB_SUBST\fP option for the evaluation of \fIspec\fP; if the `\fB~\fP\&' is doubled, turn it off\&. When this option is set, the string resulting from the expansion will be interpreted as a @@ -1030,9 +1043,10 @@ following flags are supported: .TP .PD \fB#\fP -Evaluate the resulting words as numeric expressions and output the -characters corresponding to the resulting integer\&. Note that this form is -entirely distinct from use of the \fB#\fP without parentheses\&. +Evaluate the resulting words as numeric expressions and interpret +these as character codes\&. Output the corresponding characters\&. Note +that this form is entirely distinct from use of the \fB#\fP without +parentheses\&. .RS .PP If the \fBMULTIBYTE\fP option is set and the number is greater than 127 @@ -1041,7 +1055,7 @@ If the \fBMULTIBYTE\fP option is set and the number is greater than 127 .TP \fB%\fP Expand all \fB%\fP escapes in the resulting words in the same way as in -prompts (see +prompts (see EXPANSION OF PROMPT SEQUENCES in \fIzshmisc\fP(1))\&. If this flag is given twice, full prompt expansion is done on the resulting words, depending on the setting of the \fBPROMPT_PERCENT\fP, \fBPROMPT_SUBST\fP and \fBPROMPT_BANG\fP @@ -1171,22 +1185,31 @@ Convert all letters in the result to lower case\&. \fBn\fP Sort decimal integers numerically; if the first differing characters of two test strings are not digits, sorting -is lexical\&. Integers with more initial zeroes -are sorted before those with fewer or none\&. Hence the array `\fBfoo1 foo02 +is lexical\&. `\fB+\fP\&' and `\fB\-\fP' are not treated specially; they are treated as +any other non\-digit\&. Integers with more initial zeroes +are sorted before those with fewer or none\&. Hence the array `\fBfoo+24 foo1 foo02 foo2 foo3 foo20 foo23\fP\&' is sorted into the order shown\&. May be combined with `\fBi\fP\&' or `\fBO\fP'\&. .TP +\fB\-\fP +As \fBn\fP, but a leading minus sign indicates a negative decimal +integer\&. A leading minus sign not followed by an integer does not trigger +numeric sorting\&. +Note that `\fB+\fP\&' signs are not handled specially (this may change in the +future)\&. +.TP \fBo\fP Sort the resulting words in ascending order; if this appears on its own the sorting is lexical and case\-sensitive (unless the locale renders it case\-insensitive)\&. Sorting in ascending order is the default for other forms of sorting, so this is ignored if combined -with `\fBa\fP\&', `\fBi\fP' or `\fBn\fP'\&. +with `\fBa\fP\&', `\fBi\fP', `\fBn\fP' or `\fB\-\fP'\&. .TP \fBO\fP Sort the resulting words in descending order; `\fBO\fP\&' without `\fBa\fP', -`\fBi\fP\&' or `\fBn\fP' sorts in reverse lexical order\&. May be combined -with `\fBa\fP\&', `\fBi\fP' or `\fBn\fP' to reverse the order of sorting\&. +`\fBi\fP\&', `\fBn\fP' or `\fB\-\fP' sorts in reverse lexical order\&. May be +combined with `\fBa\fP\&', `\fBi\fP', `\fBn\fP' or `\fB\-\fP' to reverse the +order of sorting\&. .TP \fBP\fP This forces the value of the parameter \fIname\fP to be interpreted as a @@ -1277,6 +1300,11 @@ for readonly parameters \fBtag\fP for tagged parameters .TP +\fBtied\fP +for parameters tied to another parameter in the manner of \fBPATH\fP +(colon\-separated list) and \fBpath\fP (array), whether these are +special parameters or user\-defined with `\fBtypeset \-T\fP\&' +.TP \fBexport\fP for exported parameters .TP @@ -1487,17 +1515,32 @@ i\&.e\&. \fB"${(@s\&.:\&.)line}"\fP\&. \fBZ:\fP\fIopts\fP\fB:\fP As \fBz\fP but takes a combination of option letters between a following pair of delimiter characters\&. With no options the effect is identical -to \fBz\fP\&. \fB(Z+c+)\fP +to \fBz\fP\&. The following options are available: +.RS +.PP +.PD 0 +.TP +.PD +\fB(Z+c+)\fP causes comments to be parsed as a string and retained; any field in the resulting array beginning with an unquoted comment character is a -comment\&. \fB(Z+C+)\fP causes comments to be parsed +comment\&. +.TP +\fB(Z+C+)\fP +causes comments to be parsed and removed\&. The rule for comments is standard: anything between a word starting with the third character of \fB$HISTCHARS\fP, default \fB#\fP, up to -the next newline is a comment\&. \fB(Z+n+)\fP causes +the next newline is a comment\&. +.TP +\fB(Z+n+)\fP +causes unquoted newlines to be treated as ordinary whitespace, else they are treated as if they are shell code delimiters and converted to -semicolons\&. Options are combined within the same set of delimiters, +semicolons\&. +.PP +Options are combined within the same set of delimiters, e\&.g\&. \fB(Z+Cn+)\fP\&. +.RE .TP \fB_:\fP\fIflags\fP\fB:\fP The underscore (\fB_\fP) flag is reserved for future use\&. As of this @@ -1506,7 +1549,7 @@ underscore, other than an empty pair of delimiters, is treated as an error, and the flag itself has no effect\&. .PP The following flags are meaningful with the \fB${\fP\&.\&.\&.\fB#\fP\&.\&.\&.\fB}\fP or -\fB${\fP\&.\&.\&.\fB%\fP\&.\&.\&.\fB}\fP forms\&. The \fBS\fP and \fBI\fP flags may also be +\fB${\fP\&.\&.\&.\fB%\fP\&.\&.\&.\fB}\fP forms\&. The \fBS\fP, \fBI\fP, and \fB*\fP flags may also be used with the \fB${\fP\&.\&.\&.\fB/\fP\&.\&.\&.\fB}\fP forms\&. .PP .PD 0 @@ -1594,6 +1637,10 @@ form using `\fB%%\fP\&' will remove the same matches as for `\fB##\fP' in revers order\&. .RE .TP +\fB*\fP +Enable \fBEXTENDED_GLOB\fP for substitution via \fB${\fP\&.\&.\&.\fB/\fP\&.\&.\&.\fB}\fP or +\fB${\fP\&.\&.\&.\fB//\fP\&.\&.\&.\fB}\fP\&. +.TP \fBB\fP Include the index of the beginning of the match in the result\&. .TP @@ -1611,7 +1658,6 @@ Include the length of the match in the result\&. Include the unmatched portion in the result (the \fIR\fPest)\&. .PP .SS "Rules" -.PP Here is a summary of the rules for substitution; this assumes that braces are present around the substitution, i\&.e\&. \fB${\fP\fI\&.\&.\&.\fP\fB}\fP\&. Some particular examples are given below\&. Note that the Zsh Development Group accepts @@ -1840,7 +1886,7 @@ This produces the result \fBb\fP\&. First, the inner substitution \fB"${foo}"\fP, which has no array (\fB@\fP) flag, produces a single word result \fB"bar baz"\fP\&. The outer substitution \fB"${(@)\&.\&.\&.[1]}"\fP detects that this is a scalar, so that (despite the `\fB(@)\fP\&' flag) the subscript -picks the first character\&. +picks the first character\&. .TP \fB"${${(@)foo}[1]}"\fP This produces the result `\fBbar\fP\&'\&. In this case, the inner substitution @@ -1869,7 +1915,7 @@ empty string will then be elided, as it is not in double quotes\&. .PP .SH "COMMAND SUBSTITUTION" A command enclosed in parentheses preceded by a dollar sign, like -`\fB$(\fP\&.\&.\&.\fB)\fP\&', or quoted with grave +`\fB$(\fP\&.\&.\&.\fB)\fP\&', or quoted with grave accents, like `\fB`\fP\&.\&.\&.\fB`\fP\&', is replaced with its standard output, with any trailing newlines deleted\&. If the substitution is not enclosed in double quotes, the @@ -1952,7 +1998,7 @@ has similar effects\&. .PP To combine brace expansion with array expansion, see the \fB${^\fP\fIspec\fP\fB}\fP form described -in the section Parameter Expansion +in the section `Parameter Expansion\&' above\&. .PP .SH "FILENAME EXPANSION" @@ -1982,8 +2028,8 @@ The \fBPUSHD_MINUS\fP option exchanges the effects of `\fB~+\fP\&' and `\fB~\-\fP' where they are followed by a number\&. .PP -.SS "Dynamic named directories" .PP +.SS "Dynamic named directories" If the function \fBzsh_directory_name\fP exists, or the shell variable \fBzsh_directory_name_functions\fP exists and contains an array of function names, then the functions are used to implement dynamic @@ -2113,7 +2159,6 @@ exists by that name, the word is replaced by the full pathname of the command\&. .PP .SS "Notes" -.PP Filename expansion is performed on the right hand side of a parameter assignment, including those appearing after commands of the \fBtypeset\fP family\&. In this case, the right hand side will be treated @@ -2224,7 +2269,8 @@ is not sensitive to the locale: .PD \fB[:IDENT:]\fP The character is allowed to form part of a shell identifier, such -as a parameter name +as a parameter name; this test respects the \fBPOSIX_IDENTIFIERS\fP +option .TP \fB[:IFS:]\fP The character is used as an input field separator, i\&.e\&. is contained in the @@ -2558,7 +2604,7 @@ qualifiers are also not applied in ordinary pattern matching\&. .TP \fBu\fP Respect the current locale in determining the presence of multibyte -characters in a pattern, provided the shell was compiled with +characters in a pattern, provided the shell was compiled with \fBMULTIBYTE_SUPPORT\fP\&. This overrides the \fBMULTIBYTE\fP option; the default behaviour is taken from the option\&. Compare \fBU\fP\&. (Mnemonic: typically multibyte characters are from Unicode in the UTF\-8 @@ -2818,19 +2864,19 @@ expected, if combined with a `\fB=\fP\&', the value given must match the file\-modes exactly, with a `\fB+\fP\&', at least the bits in the given number must be set in the file\-modes, and with a `\fB\-\fP\&', the bits in the number must not be set\&. Giving a `\fB?\fP\&' instead of a -octal digit anywhere in the number ensures that the corresponding bits +octal digit anywhere in the number ensures that the corresponding bits in the file\-modes are not checked, this is only useful in combination with `\fB=\fP\&'\&. .RS .PP If the qualifier `\fBf\fP\&' is followed by any other character anything -up to the next matching character (`\fB[\fP\&', `\fB{\fP', and `\fB<\fP' match +up to the next matching character (`\fB[\fP\&', `\fB{\fP', and `\fB<\fP' match `\fB]\fP\&', `\fB}\fP', and `\fB>\fP' respectively, any other character matches itself) is taken as a list of comma\-separated \fIsub\-spec\fPs\&. Each \fIsub\-spec\fP may be either an octal number as described above or a list of any of the characters `\fBu\fP\&', `\fBg\fP', `\fBo\fP\&', and `\fBa\fP', followed by a `\fB=\fP', a `\fB+\fP', or a -`\fB\-\fP\&', followed by a list of any of the characters `\fBr\fP', `\fBw\fP', +`\fB\-\fP\&', followed by a list of any of the characters `\fBr\fP', `\fBw\fP', `\fBx\fP\&', `\fBs\fP', and `\fBt\fP', or an octal digit\&. The first list of characters specify which access rights are to be checked\&. If a `\fBu\fP\&' is given, those for the owner of the file are used, if a `\fBg\fP\&' is @@ -2839,7 +2885,7 @@ of other users, and the `\fBa\fP\&' says to test all three groups\&. The `\fB=\fP\&', `\fB+\fP', and `\fB\-\fP' again says how the modes are to be checked and have the same meaning as described for the first form above\&. The second list of characters finally says which access rights -are to be expected: `\fBr\fP\&' for read access, `\fBw\fP' for write access, +are to be expected: `\fBr\fP\&' for read access, `\fBw\fP' for write access, `\fBx\fP\&' for the right to execute the file (or to search a directory), `\fBs\fP\&' for the setuid and setgid bits, and `\fBt\fP' for the sticky bit\&. @@ -2848,7 +2894,7 @@ Thus, `\fB*(f70?)\fP\&' gives the files for which the owner has read, write, and execute permission, and for which other group members have no rights, independent of the permissions for other users\&. The pattern `\fB*(f\-100)\fP\&' gives all files for which the owner does not have -execute permission, and `\fB*(f:gu+w,o\-rx:)\fP\&' gives the files for which +execute permission, and `\fB*(f:gu+w,o\-rx:)\fP\&' gives the files for which the owner and the other members of the group have at least write permission, and for which other users don\&'t have read or execute permission\&. @@ -2981,7 +3027,9 @@ negates all qualifiers following it .TP \fB\-\fP toggles between making the qualifiers work on symbolic links (the -default) and the files they point to +default) and the files they point to, if any; any symbolic link for +whose target the `\fBstat\fP\&' system call fails (whatever the cause of the +failure) is treated as a file in its own right .TP \fBM\fP sets the \fBMARK_DIRS\fP option for the current pattern @@ -3009,22 +3057,50 @@ Implies \fBoN\fP when no \fBo\fP\fIc\fP qualifier is used\&. .RE .TP \fBo\fP\fIc\fP -specifies how the names of the files should be sorted\&. If \fIc\fP is -\fBn\fP they are sorted by name; if it is \fBL\fP they -are sorted depending on the size (length) of the files; if \fBl\fP -they are sorted by the number of links; if \fBa\fP, \fBm\fP, or \fBc\fP -they are sorted by the time of the last access, modification, or -inode change respectively; if \fBd\fP, files in subdirectories appear before +specifies how the names of the files should be sorted\&. The following values +of \fIc\fP sort in the following ways: +.RS +.PP +.PD 0 +.TP +\fBn\fP +By name\&. +.TP +\fBL\fP +By the size (length) of the files\&. +.TP +\fBl\fP +By number of links\&. +.TP +\fBa\fP +By time of last access, youngest first\&. +.TP +\fBm\fP +By time of last modification, youngest first\&. +.TP +\fBc\fP +By time of last inode change, youngest first\&. +.TP +\fBd\fP +By directories: files in subdirectories appear before those in the current directory at each level of the search \-\- this is best combined with other criteria, for example `\fBodon\fP\&' to sort on names for -files within the same directory; if \fBN\fP, no sorting is performed\&. -Note that \fBa\fP, \fBm\fP, and \fBc\fP compare -the age against the current time, hence the first name in the list is the -youngest file\&. Also note that the modifiers \fB^\fP and \fB\-\fP are used, +files within the same directory\&. +.TP +\fBN\fP +No sorting is performed\&. +.TP +.PD 0 +\fBe\fP\fIstring\fP +.TP +\fB+\fP\fIcmd\fP +Sort by shell code (see below)\&. +.PD +.PP +Note that the modifiers \fB^\fP and \fB\-\fP are used, so `\fB*(^\-oL)\fP\&' gives a list of all files sorted by file size in descending order, following any symbolic links\&. Unless \fBoN\fP is used, multiple order specifiers may occur to resolve ties\&. -.RS .PP The default sorting is \fBn\fP (by name) unless the \fBY\fP glob qualifier is used, in which case it is \fBN\fP (unsorted)\&. @@ -3041,9 +3117,10 @@ repeated, but note that the maximum number of sort operators of any kind that may appear in any glob expression is 12\&. .RE .TP +.PD \fBO\fP\fIc\fP -like `\fBo\fP\&', but sorts in descending order; i\&.e\&. `\fB*(^oc)\fP' is the -same as `\fB*(Oc)\fP\&' and `\fB*(^Oc)\fP' is the same as `\fB*(oc)\fP'; `\fBOd\fP' +like `\fBo\fP\&', but sorts in descending order; i\&.e\&. `\fB*(^o\fP\fIc\fP\fB)\fP' is the +same as `\fB*(O\fP\fIc\fP\fB)\fP\&' and `\fB*(^O\fP\fIc\fP\fB)\fP' is the same as `\fB*(o\fP\fIc\fP\fB)\fP'; `\fBOd\fP' puts files in the current directory before those in subdirectories at each level of the search\&. .TP @@ -3051,7 +3128,7 @@ level of the search\&. specifies which of the matched filenames should be included in the returned list\&. The syntax is the same as for array subscripts\&. \fIbeg\fP and the optional \fIend\fP may be mathematical -expressions\&. As in parameter subscripting they may be negative to make +expressions\&. As in parameter subscripting they may be negative to make them count from the last match backward\&. E\&.g\&.: `\fB*(\-OL[1,3])\fP\&' gives a list of the names of the three largest files\&. .TP |