1ZSHEXPN(1) General Commands Manual ZSHEXPN(1)
2
6 zshexpn - zsh expansion and substitution
7
9 The following types of expansions are performed in the indicated order
10 in five steps:
11 History Expansion
13 This is performed only in interactive shells.
14 Alias Expansion
16 Aliases are expanded immediately before the command line is
17 parsed as explained under Aliasing in zshmisc(1).
18 Process Substitution
20 Parameter Expansion
21 Command Substitution
22 Arithmetic Expansion
23 Brace Expansion
24 These five are performed in one step in left-to-right fashion.
25 After these expansions, all unquoted occurrences of the charac‐
26 ters `\', `'' and `"' are removed.
27 Filename Expansion
29 If the SH_FILE_EXPANSION option is set, the order of expansion
30 is modified for compatibility with sh and ksh. In that case
31 filename expansion is performed immediately after alias expan‐
32 sion, preceding the set of five expansions mentioned above.
33 Filename Generation
35 This expansion, commonly referred to as globbing, is always done
36 last.
37 The following sections explain the types of expansion in detail.
39
41 History expansion allows you to use words from previous command lines
42 in the command line you are typing. This simplifies spelling correc‐
43 tions and the repetition of complicated commands or arguments. Immedi‐
44 ately before execution, each command is saved in the history list, the
45 size of which is controlled by the HISTSIZE parameter. The one most
46 recent command is always retained in any case. Each saved command in
47 the history list is called a history event and is assigned a number,
48 beginning with 1 (one) when the shell starts up. The history number
49 that you may see in your prompt (see Prompt Expansion in zshmisc(1)) is
50 the number that is to be assigned to the next command.
51 Overview
53 A history expansion begins with the first character of the histchars
54 parameter, which is `!' by default, and may occur anywhere on the com‐
55 mand line; history expansions do not nest. The `!' can be escaped with
56 `\' or can be enclosed between a pair of single quotes ('') to suppress
57 its special meaning. Double quotes will not work for this. Following
58 this history character is an optional event designator (see the section
59 `Event Designators') and then an optional word designator (the section
60 `Word Designators'); if neither of these designators is present, no
61 history expansion occurs.
62 Input lines containing history expansions are echoed after being
64 expanded, but before any other expansions take place and before the
65 command is executed. It is this expanded form that is recorded as the
66 history event for later references.
67 By default, a history reference with no event designator refers to the
69 same event as any preceding history reference on that command line; if
70 it is the only history reference in a command, it refers to the previ‐
71 ous command. However, if the option CSH_JUNKIE_HISTORY is set, then
72 every history reference with no event specification always refers to
73 the previous command.
74 For example, `!' is the event designator for the previous command, so
76 `!!:1' always refers to the first word of the previous command, and
77 `!!$' always refers to the last word of the previous command. With
78 CSH_JUNKIE_HISTORY set, then `!:1' and `!$' function in the same manner
79 as `!!:1' and `!!$', respectively. Conversely, if CSH_JUNKIE_HISTORY
80 is unset, then `!:1' and `!$' refer to the first and last words,
81 respectively, of the same event referenced by the nearest other history
82 reference preceding them on the current command line, or to the previ‐
83 ous command if there is no preceding reference.
84 The character sequence `^foo^bar' (where `^' is actually the second
86 character of the histchars parameter) repeats the last command, replac‐
87 ing the string foo with bar. More precisely, the sequence `^foo^bar^'
88 is synonymous with `!!:s^foo^bar^', hence other modifiers (see the sec‐
89 tion `Modifiers') may follow the final `^'.
90 If the shell encounters the character sequence `!"' in the input, the
92 history mechanism is temporarily disabled until the current list (see
93 zshmisc(1)) is fully parsed. The `!"' is removed from the input, and
94 any subsequent `!' characters have no special significance.
95 A less convenient but more comprehensible form of command history sup‐
97 port is provided by the fc builtin.
98 Event Designators
100 An event designator is a reference to a command-line entry in the his‐
101 tory list. In the list below, remember that the initial `!' in each
102 item may be changed to another character by setting the histchars
103 parameter.
104 ! Start a history expansion, except when followed by a blank, new‐
106 line, `=' or `('. If followed immediately by a word designator
107 (see the section `Word Designators'), this forms a history ref‐
108 erence with no event designator (see the section `Overview').
109 !! Refer to the previous command. By itself, this expansion
111 repeats the previous command.
112 !n Refer to command-line n.
114 !-n Refer to the current command-line minus n.
116 !str Refer to the most recent command starting with str.
118 !?str[?]
120 Refer to the most recent command containing str. The trailing
121 `?' is necessary if this reference is to be followed by a modi‐
122 fier or followed by any text that is not to be considered part
123 of str.
124 !# Refer to the current command line typed in so far. The line is
126 treated as if it were complete up to and including the word
127 before the one with the `!#' reference.
128 !{...} Insulate a history reference from adjacent characters (if neces‐
130 sary).
131 Word Designators
133 A word designator indicates which word or words of a given command line
134 are to be included in a history reference. A `:' usually separates the
135 event specification from the word designator. It may be omitted only
136 if the word designator begins with a `^', `$', `*', `-' or `%'. Word
137 designators include:
138 0 The first input word (command).
140 n The nth argument.
141 ^ The first argument. That is, 1.
142 $ The last argument.
143 % The word matched by (the most recent) ?str search.
144 x-y A range of words; x defaults to 0.
145 * All the arguments, or a null value if there are none.
146 x* Abbreviates `x-$'.
147 x- Like `x*' but omitting word $.
148 Note that a `%' word designator works only when used in one of `!%',
150 `!:%' or `!?str?:%', and only when used after a !? expansion (possibly
151 in an earlier command). Anything else results in an error, although
152 the error may not be the most obvious one.
153 Modifiers
155 After the optional word designator, you can add a sequence of one or
156 more of the following modifiers, each preceded by a `:'. These modi‐
157 fiers also work on the result of filename generation and parameter
158 expansion, except where noted.
159 h Remove a trailing pathname component, leaving the head. This
161 works like `dirname'.
162 r Remove a filename extension of the form `.xxx', leaving the root
164 name.
165 e Remove all but the extension.
167 t Remove all leading pathname components, leaving the tail. This
169 works like `basename'.
170 p Print the new command but do not execute it. Only works with
172 history expansion.
173 q Quote the substituted words, escaping further substitutions.
175 Works with history expansion and parameter expansion, though for
176 parameters it is only useful if the resulting text is to be
177 re-evaluated such as by eval.
178 Q Remove one level of quotes from the substituted words.
180 x Like q, but break into words at whitespace. Does not work with
182 parameter expansion.
183 l Convert the words to all lowercase.
185 u Convert the words to all uppercase.
187 s/l/r[/]
189 Substitute r for l as described below. Unless preceded immedi‐
190 ately by a g, with no colon between, the substitution is done
191 only for the first string that matches l. For arrays and for
192 filename generation, this applies to each word of the expanded
193 text.
194 & Repeat the previous s substitution. Like s, may be preceded
196 immediately by a g. In parameter expansion the & must appear
197 inside braces, and in filename generation it must be quoted with
198 a backslash.
199 The s/l/r/ substitution works as follows. The left-hand side of sub‐
201 stitutions are not regular expressions, but character strings. Any
202 character can be used as the delimiter in place of `/'. A backslash
203 quotes the delimiter character. The character `&', in the
204 right-hand-side r, is replaced by the text from the left-hand-side l.
205 The `&' can be quoted with a backslash. A null l uses the previous
206 string either from the previous l or from the contextual scan string s
207 from `!?s'. You can omit the rightmost delimiter if a newline immedi‐
208 ately follows r; the rightmost `?' in a context scan can similarly be
209 omitted. Note the same record of the last l and r is maintained across
210 all forms of expansion.
211 The following f, F, w and W modifiers work only with parameter expan‐
213 sion and filename generation. They are listed here to provide a single
214 point of reference for all modifiers.
215 f Repeats the immediately (without a colon) following modifier
217 until the resulting word doesn't change any more.
218 F:expr:
220 Like f, but repeats only n times if the expression expr evalu‐
221 ates to n. Any character can be used instead of the `:'; if
222 `(', `[', or `{' is used as the opening delimiter, the closing
223 delimiter should be ')', `]', or `}', respectively.
224 w Makes the immediately following modifier work on each word in
226 the string.
227 W:sep: Like w but words are considered to be the parts of the string
229 that are separated by sep. Any character can be used instead of
230 the `:'; opening parentheses are handled specially, see above.
231
233 Each command argument of the form `<(list)', `>(list)' or `=(list)' is
234 subject to process substitution. In the case of the < or > forms, the
235 shell runs process list asynchronously. If the system supports the
236 /dev/fd mechanism, the command argument is the name of the device file
237 corresponding to a file descriptor; otherwise, if the system supports
238 named pipes (FIFOs), the command argument will be a named pipe. If the
239 form with > is selected then writing on this special file will provide
240 input for list. If < is used, then the file passed as an argument will
241 be connected to the output of the list process. For example,
242 paste <(cut -f1 file1) <(cut -f3 file2) |
244 tee >(process1) >(process2) >/dev/null
245 cuts fields 1 and 3 from the files file1 and file2 respectively, pastes
247 the results together, and sends it to the processes process1 and
248 process2.
249 If =(...) is used instead of <(...), then the file passed as an argu‐
251 ment will be the name of a temporary file containing the output of the
252 list process. This may be used instead of the < form for a program
253 that expects to lseek (see lseek(2)) on the input file.
254 The = form is useful as both the /dev/fd and the named pipe implementa‐
256 tion of <(...) have drawbacks. In the former case, some programmes may
257 automatically close the file descriptor in question before examining
258 the file on the command line, particularly if this is necessary for
259 security reasons such as when the programme is running setuid. In the
260 second case, if the programme does not actually open the file, the sub‐
261 shell attempting to read from or write to the pipe will (in a typical
262 implementation, different operating systems may have different behav‐
263 iour) block for ever and have to be killed explicitly. In both cases,
264 the shell actually supplies the information using a pipe, so that pro‐
265 grammes that expect to lseek (see lseek(2)) on the file will not work.
266 Also note that the previous example can be more compactly and effi‐
268 ciently written (provided the MULTIOS option is set) as:
269 paste <(cut -f1 file1) <(cut -f3 file2) \
271 > >(process1) > >(process2)
272 The shell uses pipes instead of FIFOs to implement the latter two
274 process substitutions in the above example.
275 There is an additional problem with >(process); when this is attached
277 to an external command, the parent shell does not wait for process to
278 finish and hence an immediately following command cannot rely on the
279 results being complete. The problem and solution are the same as
280 described in the section MULTIOS in zshmisc(1). Hence in a simplified
281 version of the example above:
282 paste <(cut -f1 file1) <(cut -f3 file2) > >(process)
284 (note that no MULTIOS are involved), process will be run asyn‐
286 chronously. The workaround is:
287 { paste <(cut -f1 file1) <(cut -f3 file2) } > >(process)
289 The extra processes here are spawned from the parent shell which will
291 wait for their completion.
292
294 The character `$' is used to introduce parameter expansions. See zsh‐
295 param(1) for a description of parameters, including arrays, associative
296 arrays, and subscript notation to access individual array elements.
297 Note in particular the fact that words of unquoted parameters are not
299 automatically split on whitespace unless the option SH_WORD_SPLIT is
300 set; see references to this option below for more details. This is an
301 important difference from other shells.
302 In the expansions discussed below that require a pattern, the form of
304 the pattern is the same as that used for filename generation; see the
305 section `Filename Generation'. Note that these patterns, along with
306 the replacement text of any substitutions, are themselves subject to
307 parameter expansion, command substitution, and arithmetic expansion.
308 In addition to the following operations, the colon modifiers described
309 in the section `Modifiers' in the section `History Expansion' can be
310 applied: for example, ${i:s/foo/bar/} performs string substitution on
311 the expansion of parameter $i.
312 ${name}
314 The value, if any, of the parameter name is substituted. The
315 braces are required if the expansion is to be followed by a let‐
316 ter, digit, or underscore that is not to be interpreted as part
317 of name. In addition, more complicated forms of substitution
318 usually require the braces to be present; exceptions, which only
319 apply if the option KSH_ARRAYS is not set, are a single sub‐
320 script or any colon modifiers appearing after the name, or any
321 of the characters `^', `=', `~', `#' or `+' appearing before the
322 name, all of which work with or without braces.
323 If name is an array parameter, and the KSH_ARRAYS option is not
325 set, then the value of each element of name is substituted, one
326 element per word. Otherwise, the expansion results in one word
327 only; with KSH_ARRAYS, this is the first element of an array.
328 No field splitting is done on the result unless the
329 SH_WORD_SPLIT option is set.
330 ${+name}
332 If name is the name of a set parameter `1' is substituted, oth‐
333 erwise `0' is substituted.
334 ${name:-word}
336 If name is set and is non-null then substitute its value; other‐
337 wise substitute word. If name is missing, substitute word.
338 ${name:=word}
340 ${name::=word}
341 In the first form, if name is unset or is null then set it to
342 word; in the second form, unconditionally set name to word. In
343 both forms, the value of the parameter is then substituted.
344 ${name:?word}
346 If name is set and is non-null then substitute its value; other‐
347 wise, print word and exit from the shell. Interactive shells
348 instead return to the prompt. If word is omitted, then a stan‐
349 dard message is printed.
350 ${name:+word}
352 If name is set and is non-null then substitute word; otherwise
353 substitute nothing.
354 If the colon is omitted from one of the above expressions containing a
356 colon, then the shell only checks whether name is set, not whether its
357 value is null.
358 In the following expressions, when name is an array and the substitu‐
360 tion is not quoted, or if the `(@)' flag or the name[@] syntax is used,
361 matching and replacement is performed on each array element separately.
362 ${name#pattern}
364 ${name##pattern}
365 If the pattern matches the beginning of the value of name, then
366 substitute the value of name with the matched portion deleted;
367 otherwise, just substitute the value of name. In the first
368 form, the smallest matching pattern is preferred; in the second
369 form, the largest matching pattern is preferred.
370 ${name%pattern}
372 ${name%%pattern}
373 If the pattern matches the end of the value of name, then sub‐
374 stitute the value of name with the matched portion deleted; oth‐
375 erwise, just substitute the value of name. In the first form,
376 the smallest matching pattern is preferred; in the second form,
377 the largest matching pattern is preferred.
378 ${name:#pattern}
380 If the pattern matches the value of name, then substitute the
381 empty string; otherwise, just substitute the value of name. If
382 name is an array the matching array elements are removed (use
383 the `(M)' flag to remove the non-matched elements).
384 ${name/pattern/repl}
386 ${name//pattern/repl}
387 Replace the longest possible match of pattern in the expansion
388 of parameter name by string repl. The first form replaces just
389 the first occurrence, the second form all occurrences. Both
390 pattern and repl are subject to double-quoted substitution, so
391 that expressions like ${name/$opat/$npat} will work, but note
392 the usual rule that pattern characters in $opat are not treated
393 specially unless either the option GLOB_SUBST is set, or $opat
394 is instead substituted as ${~opat}.
395 The pattern may begin with a `#', in which case the pattern must
397 match at the start of the string, or `%', in which case it must
398 match at the end of the string. The repl may be an empty
399 string, in which case the final `/' may also be omitted. To
400 quote the final `/' in other cases it should be preceded by a
401 single backslash; this is not necessary if the `/' occurs inside
402 a substituted parameter. Note also that the `#' and `%' are not
403 active if they occur inside a substituted parameter, even at the
404 start.
405 The first `/' may be preceded by a `:', in which case the match
407 will only succeed if it matches the entire word. Note also the
408 effect of the I and S parameter expansion flags below; however,
409 the flags M, R, B, E and N are not useful.
410 For example,
412 foo="twinkle twinkle little star" sub="t*e" rep="spy"
414 print ${foo//${~sub}/$rep}
415 print ${(S)foo//${~sub}/$rep}
416 Here, the `~' ensures that the text of $sub is treated as a pat‐
418 tern rather than a plain string. In the first case, the longest
419 match for t*e is substituted and the result is `spy star', while
420 in the second case, the shortest matches are taken and the
421 result is `spy spy lispy star'.
422 ${#spec}
424 If spec is one of the above substitutions, substitute the length
425 in characters of the result instead of the result itself. If
426 spec is an array expression, substitute the number of elements
427 of the result. Note that `^', `=', and `~', below, must appear
428 to the left of `#' when these forms are combined.
429 ${^spec}
431 Turn on the RC_EXPAND_PARAM option for the evaluation of spec;
432 if the `^' is doubled, turn it off. When this option is set,
433 array expansions of the form foo${xx}bar, where the parameter xx
434 is set to (a b c), are substituted with `fooabar foobbar
435 foocbar' instead of the default `fooa b cbar'.
436 Internally, each such expansion is converted into the equivalent
438 list for brace expansion. E.g., ${^var} becomes
439 {$var[1],$var[2],...}, and is processed as described in the sec‐
440 tion `Brace Expansion' below. If word splitting is also in
441 effect the $var[N] may themselves be split into different list
442 elements.
443 ${=spec}
445 Perform word splitting using the rules for SH_WORD_SPLIT during
446 the evaluation of spec, but regardless of whether the parameter
447 appears in double quotes; if the `=' is doubled, turn it off.
448 This forces parameter expansions to be split into separate words
449 before substitution, using IFS as a delimiter. This is done by
450 default in most other shells.
451 Note that splitting is applied to word in the assignment forms
453 of spec before the assignment to name is performed. This
454 affects the result of array assignments with the A flag.
455 ${~spec}
457 Turn on the GLOB_SUBST option for the evaluation of spec; if the
458 `~' is doubled, turn it off. When this option is set, the
459 string resulting from the expansion will be interpreted as a
460 pattern anywhere that is possible, such as in filename expansion
461 and filename generation and pattern-matching contexts like the
462 right hand side of the `=' and `!=' operators in conditions.
463 If a ${...} type parameter expression or a $(...) type command substi‐
465 tution is used in place of name above, it is expanded first and the
466 result is used as if it were the value of name. Thus it is possible to
467 perform nested operations: ${${foo#head}%tail} substitutes the value
468 of $foo with both `head' and `tail' deleted. The form with $(...) is
469 often useful in combination with the flags described next; see the
470 examples below. Each name or nested ${...} in a parameter expansion
471 may also be followed by a subscript expression as described in Array
472 Parameters in zshparam(1).
473 Note that double quotes may appear around nested expressions, in which
475 case only the part inside is treated as quoted; for example,
476 ${(f)"$(foo)"} quotes the result of $(foo), but the flag `(f)' (see
477 below) is applied using the rules for unquoted expansions. Note fur‐
478 ther that quotes are themselves nested in this context; for example, in
479 "${(@f)"$(foo)"}", there are two sets of quotes, one surrounding the
480 whole expression, the other (redundant) surrounding the $(foo) as
481 before.
482 Parameter Expansion Flags
484 If the opening brace is directly followed by an opening parenthesis,
485 the string up to the matching closing parenthesis will be taken as a
486 list of flags. In cases where repeating a flag is meaningful, the rep‐
487 etitions need not be consecutive; for example, `(q%q%q)' means the same
488 thing as the more readable `(%%qqq)'. The following flags are sup‐
489 ported:
490 % Expand all % escapes in the resulting words in the same way as
492 in in prompts (see the section `Prompt Expansion'). If this flag
493 is given twice, full prompt expansion is done on the resulting
494 words, depending on the setting of the PROMPT_PERCENT,
495 PROMPT_SUBST and PROMPT_BANG options.
496 @ In double quotes, array elements are put into separate words.
498 E.g., `"${(@)foo}"' is equivalent to `"${foo[@]}"' and
499 `"${(@)foo[1,2]}"' is the same as `"$foo[1]" "$foo[2]"'. This
500 is distinct from field splitting by the the f, s or z flags,
501 which still applies within each array element.
502 A Create an array parameter with `${...=...}', `${...:=...}' or
504 `${...::=...}'. If this flag is repeated (as in `AA'), create
505 an associative array parameter. Assignment is made before sort‐
506 ing or padding. The name part may be a subscripted range for
507 ordinary arrays; the word part must be converted to an array,
508 for example by using `${(AA)=name=...}' to activate field split‐
509 ting, when creating an associative array.
510 a With o or O, sort in array index order. Note that `oa' is there‐
512 fore equivalent to the default but `Oa' is useful for obtaining
513 an array's elements in reverse order.
514 c With ${#name}, count the total number of characters in an array,
516 as if the elements were concatenated with spaces between them.
517 C Capitalize the resulting words. `Words' in this case refers to
519 sequences of alphanumeric characters separated by non-alphanu‐
520 merics, not to words that result from field splitting.
521 e Perform parameter expansion, command substitution and arithmetic
523 expansion on the result. Such expansions can be nested but too
524 deep recursion may have unpredictable effects.
525 f Split the result of the expansion to lines. This is a shorthand
527 for `ps:\n:'.
528 F Join the words of arrays together using newline as a separator.
530 This is a shorthand for `pj:\n:'.
531 i With o or O, sort case-independently.
533 k If name refers to an associative array, substitute the keys
535 (element names) rather than the values of the elements. Used
536 with subscripts (including ordinary arrays), force indices or
537 keys to be substituted even if the subscript form refers to val‐
538 ues. However, this flag may not be combined with subscript
539 ranges.
540 L Convert all letters in the result to lower case.
542 n With o or O, sort numerically.
544 o Sort the resulting words in ascending order.
546 O Sort the resulting words in descending order.
548 P This forces the value of the parameter name to be interpreted as
550 a further parameter name, whose value will be used where appro‐
551 priate. If used with a nested parameter or command substitution,
552 the result of that will be taken as a parameter name in the same
553 way. For example, if you have `foo=bar' and `bar=baz', the
554 strings ${(P)foo}, ${(P)${foo}}, and ${(P)$(echo bar)} will be
555 expanded to `baz'.
556 q Quote the resulting words with backslashes. If this flag is
558 given twice, the resulting words are quoted in single quotes and
559 if it is given three times, the words are quoted in double
560 quotes. If it is given four times, the words are quoted in sin‐
561 gle quotes preceded by a $.
562 Q Remove one level of quotes from the resulting words.
564 t Use a string describing the type of the parameter where the
566 value of the parameter would usually appear. This string con‐
567 sists of keywords separated by hyphens (`-'). The first keyword
568 in the string describes the main type, it can be one of
569 `scalar', `array', `integer', `float' or `association'. The
570 other keywords describe the type in more detail:
571 local for local parameters
573 left for left justified parameters
575 right_blanks
577 for right justified parameters with leading blanks
578 right_zeros
580 for right justified parameters with leading zeros
581 lower for parameters whose value is converted to all lower case
583 when it is expanded
584 upper for parameters whose value is converted to all upper case
586 when it is expanded
587 readonly
589 for readonly parameters
590 tag for tagged parameters
592 export for exported parameters
594 unique for arrays which keep only the first occurrence of dupli‐
596 cated values
597 hide for parameters with the `hide' flag
599 special
601 for special parameters defined by the shell
602 u Expand only the first occurrence of each unique word.
604 U Convert all letters in the result to upper case.
606 v Used with k, substitute (as two consecutive words) both the key
608 and the value of each associative array element. Used with sub‐
609 scripts, force values to be substituted even if the subscript
610 form refers to indices or keys.
611 V Make any special characters in the resulting words visible.
613 w With ${#name}, count words in arrays or strings; the s flag may
615 be used to set a word delimiter.
616 W Similar to w with the difference that empty words between
618 repeated delimiters are also counted.
619 X With this flag parsing errors occurring with the Q and e flags
621 or the pattern matching forms such as `${name#pattern}' are
622 reported. Without the flag they are silently ignored.
623 z Split the result of the expansion into words using shell parsing
625 to find the words, i.e. taking into account any quoting in the
626 value.
627 Note that this is done very late, as for the `(s)' flag. So to
629 access single words in the result, one has to use nested expan‐
630 sions as in `${${(z)foo}[2]}'. Likewise, to remove the quotes in
631 the resulting words one would do: `${(Q)${(z)foo}}'.
632 The following flags (except p) are followed by one or more arguments as
634 shown. Any character, or the matching pairs `(...)', `{...}', `[...]',
635 or `<...>', may be used in place of a colon as delimiters, but note
636 that when a flag takes more than one argument, a matched pair of delim‐
637 iters must surround each argument.
638 p Recognize the same escape sequences as the print builtin in
640 string arguments to any of the flags described below.
641 j:string:
643 Join the words of arrays together using string as a separator.
644 Note that this occurs before field splitting by the
645 SH_WORD_SPLIT option.
646 l:expr::string1::string2:
648 Pad the resulting words on the left. Each word will be trun‐
649 cated if required and placed in a field expr characters wide.
650 The space to the left will be filled with string1 (concatenated
651 as often as needed) or spaces if string1 is not given. If both
652 string1 and string2 are given, this string is inserted once
653 directly to the left of each word, before padding.
654 r:expr::string1::string2:
656 As l, but pad the words on the right and insert string2 on the
657 right.
658 s:string:
660 Force field splitting (see the option SH_WORD_SPLIT) at the sep‐
661 arator string. Note that a string of two or more characters
662 means all must all match in sequence; this differs from the
663 treatment of two or more characters in the IFS parameter.
664 The following flags are meaningful with the ${...#...} or ${...%...}
666 forms. The S and I flags may also be used with the ${.../...} forms.
667 S Search substrings as well as beginnings or ends; with # start
669 from the beginning and with % start from the end of the string.
670 With substitution via ${.../...} or ${...//...}, specifies
671 non-greedy matching, i.e. that the shortest instead of the long‐
672 est match should be replaced.
673 I:expr:
675 Search the exprth match (where expr evaluates to a number).
676 This only applies when searching for substrings, either with the
677 S flag, or with ${.../...} (only the exprth match is substi‐
678 tuted) or ${...//...} (all matches from the exprth on are sub‐
679 stituted). The default is to take the first match.
680 The exprth match is counted such that there is either one or
682 zero matches from each starting position in the string, although
683 for global substitution matches overlapping previous replace‐
684 ments are ignored. With the ${...%...} and ${...%%...} forms,
685 the starting position for the match moves backwards from the end
686 as the index increases, while with the other forms it moves for‐
687 ward from the start.
688 Hence with the string
690 which switch is the right switch for Ipswich?
691 substitutions of the form ${(SI:N:)string#w*ch} as N increases
692 from 1 will match and remove `which', `witch', `witch' and
693 `wich'; the form using `##' will match and remove `which switch
694 is the right switch for Ipswich', `witch is the right switch for
695 Ipswich', `witch for Ipswich' and `wich'. The form using `%'
696 will remove the same matches as for `#', but in reverse order,
697 and the form using `%%' will remove the same matches as for `##'
698 in reverse order.
699 B Include the index of the beginning of the match in the result.
701 E Include the index of the end of the match in the result.
703 M Include the matched portion in the result.
705 N Include the length of the match in the result.
707 R Include the unmatched portion in the result (the Rest).
709 Rules
711 Here is a summary of the rules for substitution; this assumes that
712 braces are present around the substitution, i.e. ${...}. Some particu‐
713 lar examples are given below. Note that the Zsh Development Group
714 accepts no responsibility for any brain damage which may occur during
715 the reading of the following rules.
716 1. Nested Substitution
718 If multiple nested ${...} forms are present, substitution is
719 performed from the inside outwards. At each level, the substi‐
720 tution takes account of whether the current value is a scalar or
721 an array, whether the whole substitution is in double quotes,
722 and what flags are supplied to the current level of substitu‐
723 tion, just as if the nested substitution were the outermost.
724 The flags are not propagated up to enclosing substitutions; the
725 nested substitution will return either a scalar or an array as
726 determined by the flags, possibly adjusted for quoting. All the
727 following steps take place where applicable at all levels of
728 substitution. Note that, unless the `(P)' flag is present, the
729 flags and any subscripts apply directly to the value of the
730 nested substitution; for example, the expansion ${${foo}}
731 behaves exactly the same as ${foo}.
732 2. Parameter Subscripting
734 If the value is a raw parameter reference with a subscript, such
735 as ${var[3]}, the effect of subscripting is applied directly to
736 the parameter. Subscripts are evaluated left to right; subse‐
737 quent subscripts apply to the scalar or array value yielded by
738 the previous subscript. Thus if var is an array, ${var[1][2]}
739 is the second character of the first word, but ${var[2,4][2]} is
740 the entire third word (the second word of the range of words two
741 through four of the original array). Any number of subscripts
742 may appear.
743 3. Parameter Name Replacement
745 The effect of any (P) flag, which treats the value so far as a
746 parameter name and replaces it with the corresponding value, is
747 applied.
748 4. Double-Quoted Joining
750 If the value after this process is an array, and the substitu‐
751 tion appears in double quotes, and no (@) flag is present at the
752 current level, the words of the value are joined with the first
753 character of the parameter $IFS, by default a space, between
754 each word (single word arrays are not modified). If the (j)
755 flag is present, that is used for joining instead of $IFS.
756 5. Nested Subscripting
758 Any remaining subscripts (i.e. of a nested substitution) are
759 evaluated at this point, based on whether the value is an array
760 or a scalar. As with 2., multiple subscripts can appear. Note
761 that ${foo[2,4][2]} is thus equivalent to ${${foo[2,4]}[2]} and
762 also to "${${(@)foo[2,4]}[2]}" (the nested substitution returns
763 an array in both cases), but not to "${${foo[2,4]}[2]}" (the
764 nested substitution returns a scalar because of the quotes).
765 6. Modifiers
767 Any modifiers, as specified by a trailing `#', `%', `/' (possi‐
768 bly doubled) or by a set of modifiers of the form :... (see the
769 section `Modifiers' in the section `History Expansion'), are
770 applied to the words of the value at this level.
771 7. Forced Joining
773 If the `(j)' flag is present, or no `(j)' flag is present but
774 the string is to be split as given by rules 8. or 9., and join‐
775 ing did not take place at step 4., any words in the value are
776 joined together using the given string or the first character of
777 $IFS if none. Note that the `(F)' flag implicitly supplies a
778 string for joining in this manner.
779 8. Forced Splitting
781 If one of the `(s)', `(f)' or `(z)' flags are present, or the
782 `=' specifier was present (e.g. ${=var}), the word is split on
783 occurrences of the specified string, or (for = with neither of
784 the two flags present) any of the characters in $IFS.
785 9. Shell Word Splitting
787 If no `(s)', `(f)' or `=' was given, but the word is not quoted
788 and the option SH_WORD_SPLIT is set, the word is split on occur‐
789 rences of any of the characters in $IFS. Note this step, too,
790 takes place at all levels of a nested substitution.
791 10. Uniqueness
793 If the result is an array and the `(u)' flag was present, dupli‐
794 cate elements are removed from the array.
795 11. Ordering
797 If the result is still an array and one of the `(o)' or `(O)'
798 flags was present, the array is reordered.
799 12. Re-Evaluation
801 Any `(e)' flag is applied to the value, forcing it to be
802 re-examined for new parameter substitutions, but also for com‐
803 mand and arithmetic substitutions.
804 13. Padding
806 Any padding of the value by the `(l.fill.)' or `(r.fill.)' flags
807 is applied.
808 14. Semantic Joining
810 In contexts where expansion semantics requires a single word to
811 result, all words are rejoined with the first character of IFS
812 between. So in `${(P)${(f)lines}}' the value of ${lines} is
813 split at newlines, but then must be joined again before the P
814 flag can be applied.
815 If a single word is not required, this rule is skipped.
817 Examples
819 The flag f is useful to split a double-quoted substitution line by
820 line. For example, ${(f)"$(<file)"} substitutes the contents of file
821 divided so that each line is an element of the resulting array. Com‐
822 pare this with the effect of $(<file) alone, which divides the file up
823 by words, or the same inside double quotes, which makes the entire con‐
824 tent of the file a single string.
825 The following illustrates the rules for nested parameter expansions.
827 Suppose that $foo contains the array (bar baz):
828 "${(@)${foo}[1]}"
830 This produces the result b. First, the inner substitution
831 "${foo}", which has no array (@) flag, produces a single word
832 result "bar baz". The outer substitution "${(@)...[1]}" detects
833 that this is a scalar, so that (despite the `(@)' flag) the sub‐
834 script picks the first character.
835 "${${(@)foo}[1]}"
837 This produces the result `bar'. In this case, the inner substi‐
838 tution "${(@)foo}" produces the array `(bar baz)'. The outer
839 substitution "${...[1]}" detects that this is an array and picks
840 the first word. This is similar to the simple case "${foo[1]}".
841 As an example of the rules for word splitting and joining, suppose $foo
843 contains the array `(ax1 bx1)'. Then
844 ${(s/x/)foo}
846 produces the words `a', `1 b' and `1'.
847 ${(j/x/s/x/)foo}
849 produces `a', `1', `b' and `1'.
850 ${(s/x/)foo%%1*}
852 produces `a' and ` b' (note the extra space). As substitution
853 occurs before either joining or splitting, the operation first
854 generates the modified array (ax bx), which is joined to give
855 "ax bx", and then split to give `a', ` b' and `'. The final
856 empty string will then be elided, as it is not in double quotes.
857
859 A command enclosed in parentheses preceded by a dollar sign, like
860 `$(...)', or quoted with grave accents, like ``...`', is replaced with
861 its standard output, with any trailing newlines deleted. If the sub‐
862 stitution is not enclosed in double quotes, the output is broken into
863 words using the IFS parameter. The substitution `$(cat foo)' may be
864 replaced by the equivalent but faster `$(<foo)'. In either case, if
865 the option GLOB_SUBST is set, the output is eligible for filename gen‐
866 eration.
867
869 A string of the form `$[exp]' or `$((exp))' is substituted with the
870 value of the arithmetic expression exp. exp is subjected to parameter
871 expansion, command substitution and arithmetic expansion before it is
872 evaluated. See the section `Arithmetic Evaluation'.
873
875 A string of the form `foo{xx,yy,zz}bar' is expanded to the individual
876 words `fooxxbar', `fooyybar' and `foozzbar'. Left-to-right order is
877 preserved. This construct may be nested. Commas may be quoted in
878 order to include them literally in a word.
879 An expression of the form `{n1..n2}', where n1 and n2 are integers, is
881 expanded to every number between n1 and n2 inclusive. If either number
882 begins with a zero, all the resulting numbers will be padded with lead‐
883 ing zeroes to that minimum width. If the numbers are in decreasing
884 order the resulting sequence will also be in decreasing order.
885 If a brace expression matches none of the above forms, it is left
887 unchanged, unless the BRACE_CCL option is set. In that case, it is
888 expanded to a sorted list of the individual characters between the
889 braces, in the manner of a search set. `-' is treated specially as in
890 a search set, but `^' or `!' as the first character is treated nor‐
891 mally.
892 Note that brace expansion is not part of filename generation (glob‐
894 bing); an expression such as */{foo,bar} is split into two separate
895 words */foo and */bar before filename generation takes place. In par‐
896 ticular, note that this is liable to produce a `no match' error if
897 either of the two expressions does not match; this is to be contrasted
898 with */(foo|bar), which is treated as a single pattern but otherwise
899 has similar effects.
900
902 Each word is checked to see if it begins with an unquoted `~'. If it
903 does, then the word up to a `/', or the end of the word if there is no
904 `/', is checked to see if it can be substituted in one of the ways
905 described here. If so, then the `~' and the checked portion are
906 replaced with the appropriate substitute value.
907 A `~' by itself is replaced by the value of $HOME. A `~' followed by a
909 `+' or a `-' is replaced by the value of $PWD or $OLDPWD, respectively.
910 A `~' followed by a number is replaced by the directory at that posi‐
912 tion in the directory stack. `~0' is equivalent to `~+', and `~1' is
913 the top of the stack. `~+' followed by a number is replaced by the
914 directory at that position in the directory stack. `~+0' is equivalent
915 to `~+', and `~+1' is the top of the stack. `~-' followed by a number
916 is replaced by the directory that many positions from the bottom of the
917 stack. `~-0' is the bottom of the stack. The PUSHD_MINUS option
918 exchanges the effects of `~+' and `~-' where they are followed by a
919 number.
920 A `~' followed by anything not already covered is looked up as a named
922 directory, and replaced by the value of that named directory if found.
923 Named directories are typically home directories for users on the sys‐
924 tem. They may also be defined if the text after the `~' is the name of
925 a string shell parameter whose value begins with a `/'. It is also
926 possible to define directory names using the -d option to the hash
927 builtin.
928 In certain circumstances (in prompts, for instance), when the shell
930 prints a path, the path is checked to see if it has a named directory
931 as its prefix. If so, then the prefix portion is replaced with a `~'
932 followed by the name of the directory. The shortest way of referring
933 to the directory is used, with ties broken in favour of using a named
934 directory, except when the directory is / itself. The parameters $PWD
935 and $OLDPWD are never abbreviated in this fashion.
936 If a word begins with an unquoted `=' and the EQUALS option is set, the
938 remainder of the word is taken as the name of a command. If a command
939 exists by that name, the word is replaced by the full pathname of the
940 command.
941 Filename expansion is performed on the right hand side of a parameter
943 assignment, including those appearing after commands of the typeset
944 family. In this case, the right hand side will be treated as a
945 colon-separated list in the manner of the PATH parameter, so that a `~'
946 or an `=' following a `:' is eligible for expansion. All such behav‐
947 iour can be disabled by quoting the `~', the `=', or the whole expres‐
948 sion (but not simply the colon); the EQUALS option is also respected.
949 If the option MAGIC_EQUAL_SUBST is set, any unquoted shell argument in
951 the form `identifier=expression' becomes eligible for file expansion as
952 described in the previous paragraph. Quoting the first `=' also
953 inhibits this.
954
956 If a word contains an unquoted instance of one of the characters `*',
957 `(', `|', `<', `[', or `?', it is regarded as a pattern for filename
958 generation, unless the GLOB option is unset. If the EXTENDED_GLOB
959 option is set, the `^' and `#' characters also denote a pattern; other‐
960 wise they are not treated specially by the shell.
961 The word is replaced with a list of sorted filenames that match the
963 pattern. If no matching pattern is found, the shell gives an error
964 message, unless the NULL_GLOB option is set, in which case the word is
965 deleted; or unless the NOMATCH option is unset, in which case the word
966 is left unchanged.
967 In filename generation, the character `/' must be matched explicitly;
969 also, a `.' must be matched explicitly at the beginning of a pattern or
970 after a `/', unless the GLOB_DOTS option is set. No filename genera‐
971 tion pattern matches the files `.' or `..'. In other instances of pat‐
972 tern matching, the `/' and `.' are not treated specially.
973 Glob Operators
975 * Matches any string, including the null string.
976 ? Matches any character.
978 [...] Matches any of the enclosed characters. Ranges of characters
980 can be specified by separating two characters by a `-'. A `-'
981 or `]' may be matched by including it as the first character in
982 the list. There are also several named classes of characters,
983 in the form `[:name:]' with the following meanings: `[:alnum:]'
984 alphanumeric, `[:alpha:]' alphabetic, `[:ascii:]' 7-bit,
985 `[:blank:]' space or tab, `[:cntrl:]' control character,
986 `[:digit:]' decimal digit, `[:graph:]' printable character
987 except whitespace, `[:lower:]' lowercase letter, `[:print:]'
988 printable character, `[:punct:]' printable character neither
989 alphanumeric nor whitespace, `[:space:]' whitespace character,
990 `[:upper:]' uppercase letter, `[:xdigit:]' hexadecimal digit.
991 These use the macros provided by the operating system to test
992 for the given character combinations, including any modifica‐
993 tions due to local language settings: see ctype(3). Note that
994 the square brackets are additional to those enclosing the whole
995 set of characters, so to test for a single alphanumeric charac‐
996 ter you need `[[:alnum:]]'. Named character sets can be used
997 alongside other types, e.g. `[[:alpha:]0-9]'.
998 [^...]
1000 [!...] Like [...], except that it matches any character which is not in
1001 the given set.
1002 <[x]-[y]>
1004 Matches any number in the range x to y, inclusive. Either of
1005 the numbers may be omitted to make the range open-ended; hence
1006 `<->' matches any number. To match individual digits, the [...]
1007 form is more efficient.
1008 Be careful when using other wildcards adjacent to patterns of
1010 this form; for example, <0-9>* will actually match any number
1011 whatsoever at the start of the string, since the `<0-9>' will
1012 match the first digit, and the `*' will match any others. This
1013 is a trap for the unwary, but is in fact an inevitable conse‐
1014 quence of the rule that the longest possible match always suc‐
1015 ceeds. Expressions such as `<0-9>[^[:digit:]]*' can be used
1016 instead.
1017 (...) Matches the enclosed pattern. This is used for grouping. If
1019 the KSH_GLOB option is set, then a `@', `*', `+', `?' or `!'
1020 immediately preceding the `(' is treated specially, as detailed
1021 below. The option SH_GLOB prevents bare parentheses from being
1022 used in this way, though the KSH_GLOB option is still available.
1023 Note that grouping cannot extend over multiple directories: it
1025 is an error to have a `/' within a group (this only applies for
1026 patterns used in filename generation). There is one exception:
1027 a group of the form (pat/)# appearing as a complete path segment
1028 can match a sequence of directories. For example, foo/(a*/)#bar
1029 matches foo/bar, foo/any/bar, foo/any/anyother/bar, and so on.
1030 x|y Matches either x or y. This operator has lower precedence than
1032 any other. The `|' character must be within parentheses, to
1033 avoid interpretation as a pipeline.
1034 ^x (Requires EXTENDED_GLOB to be set.) Matches anything except the
1036 pattern x. This has a higher precedence than `/', so `^foo/bar'
1037 will search directories in `.' except `./foo' for a file named
1038 `bar'.
1039 x~y (Requires EXTENDED_GLOB to be set.) Match anything that matches
1041 the pattern x but does not match y. This has lower precedence
1042 than any operator except `|', so `*/*~foo/bar' will search for
1043 all files in all directories in `.' and then exclude `foo/bar'
1044 if there was such a match. Multiple patterns can be excluded by
1045 `foo~bar~baz'. In the exclusion pattern (y), `/' and `.' are
1046 not treated specially the way they usually are in globbing.
1047 x# (Requires EXTENDED_GLOB to be set.) Matches zero or more occur‐
1049 rences of the pattern x. This operator has high precedence;
1050 `12#' is equivalent to `1(2#)', rather than `[1m(12)#'. It is an
1051 error for an unquoted `#' to follow something which cannot be
1052 repeated; this includes an empty string, a pattern already fol‐
1053 lowed by `##', or parentheses when part of a KSH_GLOB pattern
1054 (for example, `!(foo)#' is invalid and must be replaced by
1055 `*(!(foo))').
1056 x## (Requires EXTENDED_GLOB to be set.) Matches one or more occur‐
1058 rences of the pattern x. This operator has high precedence;
1059 `12##' is equivalent to `1(2##)', rather than `[1m(12)##'. No more
1060 than two active `#' characters may appear together.
1061 ksh-like Glob Operators
1063 If the KSH_GLOB option is set, the effects of parentheses can be modi‐
1064 fied by a preceding `@', `*', `+', `?' or `!'. This character need not
1065 be unquoted to have special effects, but the `(' must be.
1066 @(...) Match the pattern in the parentheses. (Like `(...)'.)
1068 *(...) Match any number of occurrences. (Like `(...)#'.)
1070 +(...) Match at least one occurrence. (Like `(...)##'.)
1072 ?(...) Match zero or one occurrence. (Like `(|...)'.)
1074 !(...) Match anything but the expression in parentheses. (Like
1076 `(^(...))'.)
1077 Precedence
1079 The precedence of the operators given above is (highest) `^', `/', `~',
1080 `|' (lowest); the remaining operators are simply treated from left to
1081 right as part of a string, with `#' and `##' applying to the shortest
1082 possible preceding unit (i.e. a character, `?', `[...]', `<...>', or a
1083 parenthesised expression). As mentioned above, a `/' used as a direc‐
1084 tory separator may not appear inside parentheses, while a `|' must do
1085 so; in patterns used in other contexts than filename generation (for
1086 example, in case statements and tests within `[[...]]'), a `/' is not
1087 special; and `/' is also not special after a `~' appearing outside
1088 parentheses in a filename pattern.
1089 Globbing Flags
1091 There are various flags which affect any text to their right up to the
1092 end of the enclosing group or to the end of the pattern; they require
1093 the EXTENDED_GLOB option. All take the form (#X) where X may have one
1094 of the following forms:
1095 i Case insensitive: upper or lower case characters in the pattern
1097 match upper or lower case characters.
1098 l Lower case characters in the pattern match upper or lower case
1100 characters; upper case characters in the pattern still only
1101 match upper case characters.
1102 I Case sensitive: locally negates the effect of i or l from that
1104 point on.
1105 b Activate backreferences for parenthesised groups in the pattern;
1107 this does not work in filename generation. When a pattern with
1108 a set of active parentheses is matched, the strings matched by
1109 the groups are stored in the array $match, the indices of the
1110 beginning of the matched parentheses in the array $mbegin, and
1111 the indices of the end in the array $mend, with the first ele‐
1112 ment of each array corresponding to the first parenthesised
1113 group, and so on. These arrays are not otherwise special to the
1114 shell. The indices use the same convention as does parameter
1115 substitution, so that elements of $mend and $mbegin may be used
1116 in subscripts; the KSH_ARRAYS option is respected. Sets of
1117 globbing flags are not considered parenthesised groups; only the
1118 first nine active parentheses can be referenced.
1119 For example,
1121 foo="a string with a message"
1123 if [[ $foo = (a|an)' '(#b)(*)' '* ]]; then
1124 print ${foo[$mbegin[1],$mend[1]]}
1125 fi
1126 prints `string with a'. Note that the first parenthesis is
1128 before the (#b) and does not create a backreference.
1129 Backreferences work with all forms of pattern matching other
1131 than filename generation, but note that when performing matches
1132 on an entire array, such as ${array#pattern}, or a global sub‐
1133 stitution, such as ${param//pat/repl}, only the data for the
1134 last match remains available. In the case of global replace‐
1135 ments this may still be useful. See the example for the m flag
1136 below.
1137 The numbering of backreferences strictly follows the order of
1139 the opening parentheses from left to right in the pattern
1140 string, although sets of parentheses may be nested. There are
1141 special rules for parentheses followed by `#' or `##'. Only the
1142 last match of the parenthesis is remembered: for example, in `[[
1143 abab = (#b)([ab])# ]]', only the final `b' is stored in
1144 match[1]. Thus extra parentheses may be necessary to match the
1145 complete segment: for example, use `X((ab|cd)#)Y' to match a
1146 whole string of either `ab' or `cd' between `X' and `Y', using
1147 the value of $match[1] rather than $match[2].
1148 If the match fails none of the parameters is altered, so in some
1150 cases it may be necessary to initialise them beforehand. If
1151 some of the backreferences fail to match --- which happens if
1152 they are in an alternate branch which fails to match, or if they
1153 are followed by # and matched zero times --- then the matched
1154 string is set to the empty string, and the start and end indices
1155 are set to -1.
1156 Pattern matching with backreferences is slightly slower than
1158 without.
1159 B Deactivate backreferences, negating the effect of the b flag
1161 from that point on.
1162 m Set references to the match data for the entire string matched;
1164 this is similar to backreferencing and does not work in filename
1165 generation. The flag must be in effect at the end of the pat‐
1166 tern, i.e. not local to a group. The parameters $MATCH, $MBEGIN
1167 and $MEND will be set to the string matched and to the indices
1168 of the beginning and end of the string, respectively. This is
1169 most useful in parameter substitutions, as otherwise the string
1170 matched is obvious.
1171 For example,
1173 arr=(veldt jynx grimps waqf zho buck)
1175 print ${arr//(#m)[aeiou]/${(U)MATCH}}
1176 forces all the matches (i.e. all vowels) into uppercase, print‐
1178 ing `vEldt jynx grImps wAqf zhO bUck'.
1179 Unlike backreferences, there is no speed penalty for using match
1181 references, other than the extra substitutions required for the
1182 replacement strings in cases such as the example shown.
1183 M Deactivate the m flag, hence no references to match data will be
1185 created.
1186 anum Approximate matching: num errors are allowed in the string
1188 matched by the pattern. The rules for this are described in the
1189 next subsection.
1190 s, e Unlike the other flags, these have only a local effect, and each
1192 must appear on its own: `(#s)' and `(#e)' are the only valid
1193 forms. The `(#s)' flag succeeds only at the start of the test
1194 string, and the `(#e)' flag succeeds only at the end of the test
1195 string; they correspond to `^' and `$' in standard regular
1196 expressions. They are useful for matching path segments in pat‐
1197 terns other than those in filename generation (where path seg‐
1198 ments are in any case treated separately). For example,
1199 `*((#s)|/)test((#e)|/)*' matches a path segment `test' in any of
1200 the following strings: test, test/at/start, at/end/test,
1201 in/test/middle.
1202 Another use is in parameter substitution; for example
1204 `${array/(#s)A*Z(#e)}' will remove only elements of an array
1205 which match the complete pattern `A*Z'. There are other ways of
1206 performing many operations of this type, however the combination
1207 of the substitution operations `/' and `//' with the `(#s)' and
1208 `(#e)' flags provides a single simple and memorable method.
1209 Note that assertions of the form `(^(#s))' also work, i.e. match
1211 anywhere except at the start of the string, although this actu‐
1212 ally means `anything except a zero-length portion at the start
1213 of the string'; you need to use `(""~(#s))' to match a
1214 zero-length portion of the string not at the start.
1215 q A `q' and everything up to the closing parenthesis of the glob‐
1217 bing flags are ignored by the pattern matching code. This is
1218 intended to support the use of glob qualifiers, see below. The
1219 result is that the pattern `(#b)(*).c(#q.)' can be used both for
1220 globbing and for matching against a string. In the former case,
1221 the `(#q.)' will be treated as a glob qualifier and the `(#b)'
1222 will not be useful, while in the latter case the `(#b)' is use‐
1223 ful for backreferences and the `(#q.)' will be ignored. Note
1224 that colon modifiers in the glob qualifiers are also not applied
1225 in ordinary pattern matching.
1226 For example, the test string fooxx can be matched by the pattern
1228 (#i)FOOXX, but not by (#l)FOOXX, (#i)FOO(#I)XX or ((#i)FOOX)X. The
1229 string (#ia2)readme specifies case-insensitive matching of readme with
1230 up to two errors.
1231 When using the ksh syntax for grouping both KSH_GLOB and EXTENDED_GLOB
1233 must be set and the left parenthesis should be preceded by @. Note
1234 also that the flags do not affect letters inside [...] groups, in other
1235 words (#i)[a-z] still matches only lowercase letters. Finally, note
1236 that when examining whole paths case-insensitively every directory must
1237 be searched for all files which match, so that a pattern of the form
1238 (#i)/foo/bar/... is potentially slow.
1239 Approximate Matching
1241 When matching approximately, the shell keeps a count of the errors
1242 found, which cannot exceed the number specified in the (#anum) flags.
1243 Four types of error are recognised:
1244 1. Different characters, as in fooxbar and fooybar.
1246 2. Transposition of characters, as in banana and abnana.
1248 3. A character missing in the target string, as with the pattern
1250 road and target string rod.
1251 4. An extra character appearing in the target string, as with stove
1253 and strove.
1254 Thus, the pattern (#a3)abcd matches dcba, with the errors occurring by
1256 using the first rule twice and the second once, grouping the string as
1257 [d][cb][a] and [a][bc][d].
1258 Non-literal parts of the pattern must match exactly, including charac‐
1260 ters in character ranges: hence (#a1)??? matches strings of length
1261 four, by applying rule 4 to an empty part of the pattern, but not
1262 strings of length two, since all the ? must match. Other characters
1263 which must match exactly are initial dots in filenames (unless the
1264 GLOB_DOTS option is set), and all slashes in filenames, so that a/bc is
1265 two errors from ab/c (the slash cannot be transposed with another char‐
1266 acter). Similarly, errors are counted separately for non-contiguous
1267 strings in the pattern, so that (ab|cd)ef is two errors from aebf.
1268 When using exclusion via the ~ operator, approximate matching is
1270 treated entirely separately for the excluded part and must be activated
1271 separately. Thus, (#a1)README~READ_ME matches READ.ME but not READ_ME,
1272 as the trailing READ_ME is matched without approximation. However,
1273 (#a1)README~(#a1)READ_ME does not match any pattern of the form READ?ME
1274 as all such forms are now excluded.
1275 Apart from exclusions, there is only one overall error count; however,
1277 the maximum errors allowed may be altered locally, and this can be
1278 delimited by grouping. For example, (#a1)cat((#a0)dog)fox allows one
1279 error in total, which may not occur in the dog section, and the pattern
1280 (#a1)cat(#a0)dog(#a1)fox is equivalent. Note that the point at which
1281 an error is first found is the crucial one for establishing whether to
1282 use approximation; for example, (#a1)abc(#a0)xyz will not match
1283 abcdxyz, because the error occurs at the `x', where approximation is
1284 turned off.
1285 Entire path segments may be matched approximately, so that
1287 `(#a1)/foo/d/is/available/at/the/bar' allows one error in any path seg‐
1288 ment. This is much less efficient than without the (#a1), however,
1289 since every directory in the path must be scanned for a possible
1290 approximate match. It is best to place the (#a1) after any path seg‐
1291 ments which are known to be correct.
1292 Recursive Globbing
1294 A pathname component of the form `(foo/)#' matches a path consisting of
1295 zero or more directories matching the pattern foo.
1296 As a shorthand, `**/' is equivalent to `(*/)#'; note that this there‐
1298 fore matches files in the current directory as well as subdirectories.
1299 Thus:
1300 ls (*/)#bar
1302 or
1304 ls **/bar
1306 does a recursive directory search for files named `bar' (potentially
1308 including the file `bar' in the current directory). This form does not
1309 follow symbolic links; the alternative form `***/' does, but is other‐
1310 wise identical. Neither of these can be combined with other forms of
1311 globbing within the same path segment; in that case, the `*' operators
1312 revert to their usual effect.
1313 Glob Qualifiers
1315 Patterns used for filename generation may end in a list of qualifiers
1316 enclosed in parentheses. The qualifiers specify which filenames that
1317 otherwise match the given pattern will be inserted in the argument
1318 list.
1319 If the option BARE_GLOB_QUAL is set, then a trailing set of parentheses
1321 containing no `|' or `(' characters (or `~' if it is special) is taken
1322 as a set of glob qualifiers. A glob subexpression that would normally
1323 be taken as glob qualifiers, for example `(^x)', can be forced to be
1324 treated as part of the glob pattern by doubling the parentheses, in
1325 this case producing `((^x))'.
1326 If the option EXTENDED_GLOB is set, a different syntax for glob quali‐
1328 fiers is available, namely `(#qx)' where x is any of the same glob
1329 qualifiers used in the other format. The qualifiers must still appear
1330 at the end of the pattern. However, with this syntax multiple glob
1331 qualifiers may be chained together. They are treated as a logical AND
1332 of the individual sets of flags. Also, as the syntax is unambiguous,
1333 the expression will be treated as glob qualifiers just as long any
1334 parentheses contained within it are balanced; appearance of `|', `(' or
1335 `~' does not negate the effect. Note that qualifiers will be recog‐
1336 nised in this form even if a bare glob qualifier exists at the end of
1337 the pattern, for example `*(#q*)(.)' will recognise executable regular
1338 files if both options are set; however, mixed syntax should probably be
1339 avoided for the sake of clarity.
1340 A qualifier may be any one of the following:
1342 / directories
1344 F `full' (i.e. non-empty) directories. Note that the opposite
1346 sense (^F) expands to empty directories and all non-directories.
1347 Use (/^F) for empty directories
1348 . plain files
1350 @ symbolic links
1352 = sockets
1354 p named pipes (FIFOs)
1356 * executable plain files (0100)
1358 % device files (character or block special)
1360 %b block special files
1362 %c character special files
1364 r owner-readable files (0400)
1366 w owner-writable files (0200)
1368 x owner-executable files (0100)
1370 A group-readable files (0040)
1372 I group-writable files (0020)
1374 E group-executable files (0010)
1376 R world-readable files (0004)
1378 W world-writable files (0002)
1380 X world-executable files (0001)
1382 s setuid files (04000)
1384 S setgid files (02000)
1386 t files with the sticky bit (01000)
1388 fspec files with access rights matching spec. This spec may be a octal
1390 number optionally preceded by a `=', a `+', or a `-'. If none of
1391 these characters is given, the behavior is the same as for `='.
1392 The octal number describes the mode bits to be expected, if com‐
1393 bined with a `=', the value given must match the file-modes
1394 exactly, with a `+', at least the bits in the given number must
1395 be set in the file-modes, and with a `-', the bits in the number
1396 must not be set. Giving a `?' instead of a octal digit anywhere
1397 in the number ensures that the corresponding bits in the
1398 file-modes are not checked, this is only useful in combination
1399 with `='.
1400 If the qualifier `f' is followed by any other character anything
1402 up to the next matching character (`[', `{', and `<' match `]',
1403 `}', and `>' respectively, any other character matches itself)
1404 is taken as a list of comma-separated sub-specs. Each sub-spec
1405 may be either an octal number as described above or a list of
1406 any of the characters `u', `g', `o', and `a', followed by a `=',
1407 a `+', or a `-', followed by a list of any of the characters
1408 `r', `w', `x', `s', and `t', or an octal digit. The first list
1409 of characters specify which access rights are to be checked. If
1410 a `u' is given, those for the owner of the file are used, if a
1411 `g' is given, those of the group are checked, a `o' means to
1412 test those of other users, and the `a' says to test all three
1413 groups. The `=', `+', and `-' again says how the modes are to be
1414 checked and have the same meaning as described for the first
1415 form above. The second list of characters finally says which
1416 access rights are to be expected: `r' for read access, `w' for
1417 write access, `x' for the right to execute the file (or to
1418 search a directory), `s' for the setuid and setgid bits, and `t'
1419 for the sticky bit.
1420 Thus, `*(f70?)' gives the files for which the owner has read,
1422 write, and execute permission, and for which other group members
1423 have no rights, independent of the permissions for other users.
1424 The pattern `*(f-100)' gives all files for which the owner does
1425 not have execute permission, and `*(f:gu+w,o-rx:)' gives the
1426 files for which the owner and the other members of the group
1427 have at least write permission, and for which other users don't
1428 have read or execute permission.
1429 estring
1431 +cmd The string will be executed as shell code. The filename will be
1432 included in the list if and only if the code returns a zero sta‐
1433 tus (usually the status of the last command). The first charac‐
1434 ter after the `e' will be used as a separator and anything up to
1435 the next matching separator will be taken as the string; `[',
1436 `{', and `<' match `]', `}', and `>', respectively, while any
1437 other character matches itself. Note that expansions must be
1438 quoted in the string to prevent them from being expanded before
1439 globbing is done.
1440 During the execution of string the filename currently being
1442 tested is available in the parameter REPLY; the parameter may be
1443 altered to a string to be inserted into the list instead of the
1444 original filename. In addition, the parameter reply may be set
1445 to an array or a string, which overrides the value of REPLY. If
1446 set to an array, the latter is inserted into the command line
1447 word by word.
1448 For example, suppose a directory contains a single file
1450 `lonely'. Then the expression `*(e:'reply=(${REPLY}{1,2})':)'
1451 will cause the words `lonely1 lonely2' to be inserted into the
1452 command line. Note the quotation marks.
1453 The form +cmd has the same effect, but no delimiters appear
1455 around cmd. Instead, cmd is taken as the longest sequence of
1456 characters following the + that are alphanumeric or underscore.
1457 Typically cmd will be the name of a shell function that contains
1458 the appropriate test. For example,
1459 nt() { [[ $REPLY -nt $NTREF ]] }
1461 NTREF=reffile
1462 ls -l *(+nt)
1463 lists all files in the directory that have been modified more
1465 recently than reffile.
1466 ddev files on the device dev
1468 l[-|+]ct
1470 files having a link count less than ct (-), greater than ct (+),
1471 or equal to ct
1472 U files owned by the effective user ID
1474 G files owned by the effective group ID
1476 uid files owned by user ID id if it is a number, if not, than the
1478 character after the `u' will be used as a separator and the
1479 string between it and the next matching separator (`[', `{', and
1480 `<' match `]', `}', and `>' respectively, any other character
1481 matches itself) will be taken as a user name, and the user ID of
1482 this user will be taken (e.g. `u:foo:' or `u[foo]' for user
1483 `foo')
1484 gid like uid but with group IDs or names
1486 a[Mwhms][-|+]n
1488 files accessed exactly n days ago. Files accessed within the
1489 last n days are selected using a negative value for n (-n).
1490 Files accessed more than n days ago are selected by a positive n
1491 value (+n). Optional unit specifiers `M', `w', `h', `m' or `s'
1492 (e.g. `ah5') cause the check to be performed with months (of 30
1493 days), weeks, hours, minutes or seconds instead of days, respec‐
1494 tively. For instance, `echo *(ah-5)' would echo files accessed
1495 within the last five hours.
1496 m[Mwhms][-|+]n
1498 like the file access qualifier, except that it uses the file
1499 modification time.
1500 c[Mwhms][-|+]n
1502 like the file access qualifier, except that it uses the file
1503 inode change time.
1504 L[+|-]n
1506 files less than n bytes (-), more than n bytes (+), or exactly n
1507 bytes in length. If this flag is directly followed by a `k'
1508 (`K'), `m' (`M'), or `p' (`P') (e.g. `Lk-50') the check is per‐
1509 formed with kilobytes, megabytes, or blocks (of 512 bytes)
1510 instead.
1511 ^ negates all qualifiers following it
1513 - toggles between making the qualifiers work on symbolic links
1515 (the default) and the files they point to
1516 M sets the MARK_DIRS option for the current pattern
1518 T appends a trailing qualifier mark to the filenames, analogous to
1520 the LIST_TYPES option, for the current pattern (overrides M)
1521 N sets the NULL_GLOB option for the current pattern
1523 D sets the GLOB_DOTS option for the current pattern
1525 n sets the NUMERIC_GLOB_SORT option for the current pattern
1527 oc specifies how the names of the files should be sorted. If c is n
1529 they are sorted by name (the default); if it is L they are
1530 sorted depending on the size (length) of the files; if l they
1531 are sorted by the number of links; if a, m, or c they are sorted
1532 by the time of the last access, modification, or inode change
1533 respectively; if d, files in subdirectories appear before those
1534 in the current directory at each level of the search --- this is
1535 best combined with other criteria, for example `odon' to sort on
1536 names for files within the same directory. Note that a, m, and
1537 c compare the age against the current time, hence the first name
1538 in the list is the youngest file. Also note that the modifiers ^
1539 and - are used, so `*(^-oL)' gives a list of all files sorted by
1540 file size in descending order, following any symbolic links.
1541 Oc like `o', but sorts in descending order; i.e. `*(^oc)' is the
1543 same as `*(Oc)' and `*(^Oc)' is the same as `*(oc)'; `Od' puts
1544 files in the current directory before those in subdirectories at
1545 each level of the search.
1546 [beg[,end]]
1548 specifies which of the matched filenames should be included in
1549 the returned list. The syntax is the same as for array sub‐
1550 scripts. beg and the optional end may be mathematical expres‐
1551 sions. As in parameter subscripting they may be negative to make
1552 them count from the last match backward. E.g.: `*(-OL[1,3])'
1553 gives a list of the names of the three largest files.
1554 More than one of these lists can be combined, separated by commas. The
1556 whole list matches if at least one of the sublists matches (they are
1557 `or'ed, the qualifiers in the sublists are `and'ed). Some qualifiers,
1558 however, affect all matches generated, independent of the sublist in
1559 which they are given. These are the qualifiers `M', `T', `N', `D',
1560 `n', `o', `O' and the subscripts given in brackets (`[...]').
1561 If a `:' appears in a qualifier list, the remainder of the expression
1563 in parenthesis is interpreted as a modifier (see the section `Modi‐
1564 fiers' in the section `History Expansion'). Note that each modifier
1565 must be introduced by a separate `:'. Note also that the result after
1566 modification does not have to be an existing file. The name of any
1567 existing file can be followed by a modifier of the form `(:..)' even if
1568 no actual filename generation is performed. Thus:
1569 ls *(-/)
1571 lists all directories and symbolic links that point to directories, and
1573 ls *(%W)
1575 lists all world-writable device files in the current directory, and
1577 ls *(W,X)
1579 lists all files in the current directory that are world-writable or
1581 world-executable, and
1582 echo /tmp/foo*(u0^@:t)
1584 outputs the basename of all root-owned files beginning with the string
1586 `foo' in /tmp, ignoring symlinks, and
1587 ls *.*~(lex|parse).[ch](^D^l1)
1589 lists all files having a link count of one whose names contain a dot
1591 (but not those starting with a dot, since GLOB_DOTS is explicitly
1592 switched off) except for lex.c, lex.h, parse.c and parse.h.
1593 print b*.pro(#q:s/pro/shmo/)(#q.:s/builtin/shmiltin/)
1595 demonstrates how colon modifiers and other qualifiers may be chained
1597 together. The ordinary qualifier `.' is applied first, then the colon
1598 modifiers in order from left to right. So if EXTENDED_GLOB is set and
1599 the base pattern matches the regular file builtin.pro, the shell will
1600 print `shmiltin.shmo'.
1601zsh 4.2.6 November 28, 2005 ZSHEXPN(1)