zshexpn

Hurricane Electric Internet Services: Accounts starting at $9.95/month
Hurricane Electric Internet Services

NAME

       zshexpn - zsh command and parameter expansion


DESCRIPTION

       Expansion  is  performed  on the command line after it has
       been parsed.  The types of expansions performed are  file-
       name expansion, process substitution, parameter expansion,
       command substitution, arithmetic expansion,  brace  expan-
       sion, and filename generation.  (Where does History expan-
       sion fit in here?)


FILENAME EXPANSION

       Each word is checked to see if it begins with an  unquoted
       ~.   If it does, then the word up to a / is checked to see
       if it matches the name of a named directory.  If so,  then
       the  ~ and the matched portion are replaced with the value
       of the named directory.  A ~ by itself or followed by a  /
       is  replaced by the value of the HOME parameter.  A ~ fol-
       lowed by a + or a - is replaced by the  value  of  PWD  or
       OLDPWD, respectively.

       Named  directories  are  typically  login  directories for
       users on the system.  They may also be defined if the text
       after  the ~ is the name of a string shell parameter whose
       value begins with  a  /.   In  certain  circumstances  (in
       prompts,  for instance), when the shell prints a path, the
       path is checked to see if it has a named directory as  its
       prefix.  If so, then the prefix portion is replaced with a
       ~ followed by the name  of  the  directory.   The  longest
       match is preferred.

       If  a  word  begins  with  an unquoted = and the NO_EQUALS
       option is not set, the remainder of the word is  taken  as
       the  name  of  a command or alias.  If a command exists by
       that name, the word is replaced by the  full  pathname  of
       the command.  If an alias exists by that name, the word is
       replaced with the text of the alias.  Otherwise  the  word
       is  checked up to a / to see if it is a number or a -.  If
       so, the matched portion is replaced with the nth directory
       in  the directory stack, where n is the number matched, or
       the last directory in  the  directory  stack  if  a  -  is
       matched.

       Filename  expansion is performed on the right hand side of
       a parameter assignment, including  those  appearing  after
       commands  of  the typeset family.  In this case, the right
       hand side will be treated as a colon-separated list in the
       manner of PATH so that a ~ or an = following a : is eligi-
       ble for expansion.  All such behavior can be  disabled  by
       quoting  the  ~,  the  =, or the whole expression (but not
       simply the colon); the NO_EQUALS option is also respected.

       If the option MAGIC_EQUAL_SUBST is set, any unquoted shell
       argument  in  the   form   identifier=expression   becomes
       eligible  for  file expansion as described in the previous
       paragraph.  Quoting the first = also inhibits this.


PROCESS SUBSTITUTION

       Each command argument of the form <(list)  or  >(list)  or
       =(list)  is  subject to process substitution.  In the case
       of the < or > forms, the shell will run process list asyn-
       chronously  connected to a named pipe (FIFO).  The name of
       this pipe will become the argument to the command.  If the
       form  with  >  is  selected then writing on this file will
       provide input for list.  If  <  is  used,  then  the  file
       passed  as  an  argument will be a named pipe connected to
       the output of the list process.  For example,

              paste <(cut -f1  file1)  <(cut  -f3  file2)  |  tee
              >(process1) >(process2) >/dev/null

       cuts fields 1 and 3 from the files file1 and file2 respec-
       tively, pastes the results together, and sends it  to  the
       processes  process1  and  process2.   Note  that the file,
       which is passed as an argument to the command, is a system
       pipe  so programs that expect to lseek(2) on the file will
       not work.  Also note that the previous example can be more
       compactly and efficiently written as:

              paste  <(cut  -f1  file1) <(cut -f3 file2) > >(pro-
              cess1) > >(process2)

       The shell uses pipes instead of  FIFOs  to  implement  the
       latter two process substitutions in the above example.

       If  = is used, then the file passed as an argument will be
       the name of a temporary file containing the output of  the
       list  process.  This may be used instead of the < form for
       a program that expects to lseek(2) on the input file.


PARAMETER EXPANSION

       The character $ is used to introduce parameter expansions.
       See  PARAMETERS below for a description of parameters.  In
       the expansions discussed below that require a pattern, the
       form  of the pattern is the same as that used for filename
       generation; see Filename Generation.

              ${name}
                     The value, if any, of the parameter name  is
                     substituted.   The  braces  are  required if
                     name is followed  by  a  letter,  digit,  or
                     underscore  that is not to be interpreted as
                     part of its  name.   If  name  is  an  array
                     parameter,  then  the values of each element
                     of name  is  substituted,  one  element  per
                     word.   Otherwise,  the expansion results in
                     one word only; no word splitting is done  on
                     the result.

              ${+name}
                     If  name  is the name of a set parameter `1'
                     is substituted,  otherwise  `0'  is  substi-
                     tuted.

              ${name:-word}
                     If  name is set and is non-null then substi-
                     tute its value; otherwise substitute word.

              ${name:=word}
                     If name is unset or is null then set  it  to
                     word;  the  value  of  the parameter is then
                     substituted.

              ${name:?word}
                     If name is set and is non-null, then substi-
                     tute  its  value;  otherwise, print word and
                     exit from the shell.  If  word  is  omitted,
                     then a standard message is printed.

              ${name:+word}
                     If  name is set and is non-null then substi-
                     tute word; otherwise substitute nothing.
              ${name#pattern}
              ${name##pattern}
                     If the pattern matches the beginning of  the
                     value  of name, then substitute the value of
                     name with the matched portion deleted;  oth-
                     erwise,  just  substitute the value of name.
                     In the first  form,  the  smallest  matching
                     pattern  is  preferred;  in the second form,
                     the largest matching pattern is preferred.
              ${name%pattern}
              ${name%%pattern}
                     If the pattern matches the end of the  value
                     of  name,  then substitute the value of name
                     with the matched portion deleted; otherwise,
                     just  substitute  the value of name.  In the
                     first form, the smallest matching pattern is
                     preferred;  in  the second form, the largest
                     matching pattern is preferred.

              ${#spec}
                     If spec is one of the  above  substitutions,
                     substitute  the  length in characters of the
                     result instead of  the  result  itself.   If
                     spec  is an array expression, substitute the
                     number of elements of the result.

              ${^spec}
                     Turn on the RC_EXPAND_PARAM option  for  the
                     evaluation  of  spec;  if  the ^ is doubled,
                     turn it off.  When this option is set, array
                     expansions  of  the  form foo${xx}bar, where
                     the parameter xx is set to (a b c), are sub-
                     stituted   with   fooabar   foobbar  foocbar
                     instead of the default fooa b cbar.

              ${=spec}
                     Turn on the  SH_WORD_SPLIT  option  for  the
                     evaluation  of  spec;  if  the = is doubled,
                     turn it  off.   When  this  option  is  set,
                     parameter  values  are  split  into separate
                     words using IFS as a delimiter  before  sub-
                     stitution.   This is done by default in most
                     other shells.

              ${~spec}
                     Turn on the GLOB_SUBST option for the evalu-
                     ation  of spec; if the ~ is doubled, turn it
                     off.  When this option is set,  any  pattern
                     characters  resulting  from the substitution
                     become eligible for file expansion and file-
                     name generation.

       If  the colon is omitted from one of the above expressions
       containing a colon, then the  shell  only  checks  whether
       name is set or not, not whether it is null.

       If  the  opening  brace is directly followed by an opening
       parentheses the string up to the matching  closing  paren-
       theses  will be taken as a list of flags.  Where arguments
       are valid, any character, or the matching  pairs  `(...)',
       `{...}', `[...]', or `<...>',  may be used in place of the
       colon as delimiters.  The following flags are supported:

              o      Sort the resulting words in ascending order.

              O      Sort   the  resulting  words  in  descending
                     order.

              i      With o or O, sort case-independently.

              L      Convert all letters in the result  to  lower
                     case.

              U      Convert  all  letters in the result to upper
                     case.

              C      Capitalize the resulting words.

              c      With ${#name}, count  the  total  number  of
                     characters  in  an array, as if the elements
                     were concatenated with spaces between  them.

              w      With  ${#name},  count  words  in  arrays or
                     strings; the s flag may be  used  to  set  a
                     word delimiter.

              l:expr::string1::string2:
                     Pad  the  resulting words on the left.  Each
                     word  will  be  truncated  if  required  and
                     placed in a field expr characters wide.  The
                     space  to  the  left  will  be  filled  with
                     string1 (concatenated as often as needed) or
                     spaces if string1 is  not  given.   If  both
                     string1  and  string2 are given, this string
                     will be placed exactly once directly to  the
                     left of the resulting word.

              r:expr::string1::string2:
                     As l..., but pad the words on the right.

              j:string:
                     Join  the  words  of  arrays  together using
                     string  as  a  separator.   Note  that  this
                     occurs   before   word   splitting   by  the
                     SH_WORD_SPLIT option.

              s:string:
                     Force  word  splitting   (see   the   option
                     SH_WORD_SPLIT)   at  the  separator  string.
                     Splitting only occurs  in  places  where  an
                     array value is valid.

              S      (This  and all remaining flags are used with
                     the ${...#...} or ${...%...} forms):  search
                     substrings as well as beginnings or ends.

              I:expr:
                     Search  the expr'th match (where expr evalu-
                     ates to a number).

              M      Include the matched portion in the result.

              R      Include the unmatched portion in the  result
                     (the Rest).

              B      Include  the  index  of the beginning of the
                     match in the result.

              E      Include the index of the end of the match in
                     the result.

              N      Include  the  length  of  the  match  in the
                     result.



COMMAND SUBSTITUTION

       A command enclosed in parentheses  preceded  by  a  dollar
       sign,  like so: $(...) or quoted with grave accents: `...`
       is replaced with its standard output.  If the substitution
       is  not  enclosed  in  double quotes, the output is broken
       into words using  the  IFS  parameter.   The  substitution
       $(cat  foo)  may  be replaced by the equivalent but faster
       $(<foo).  In either case, if the option GLOB_SUBST is  set
       the output is eligible for filename generation.


ARITHMETIC EXPANSION

       A  string  of  the  form $[exp] or $((exp)) is substituted
       with the value of  the  arithmetic  expression  exp.   See
       ARITHMETIC EVALUATION below.


BRACE EXPANSION

       A  string  of the form foo{xx,yy,zz}bar is expanded to the
       individual words fooxxbar, fooyybar, and foozzbar.   Left-
       to-right  order  is  preserved.   This  construct  may  be
       nested.  Commas may be quoted in  order  to  include  them
       literally in a word.

       An  expression of the form {x-y}, where x and y are single
       characters, is expanded to every character between  x  and
       y, inclusive.

       An  expression  of  the form {n1..n2}, where n1 and n2 are
       integers, is expanded to every number between n1  and  n2,
       inclusive.   If  either number begins with a zero, all the
       resulting numbers will be padded with  leading  zeroes  to
       that  minimum  width.   If  the  numbers are in decreasing
       order the resulting sequence will also  be  in  decreasing
       order.

       If  a brace expression matches none of the above forms, it
       is left unchanged, unless the BRACE_CCL option is set.  In
       that case, it is expanded to a sorted list of the individ-
       ual characters between the braces,  in  the  manner  of  a
       search  set.  `-' is treated specially as in a search set,
       but `^' or `!' as the first character is treated normally.


FILENAME GENERATION (GLOBBING)

       If  a  word  contains  an  unquoted instance of one of the
       characters *, |, <, [, or ?, it is regarded as  a  pattern
       for filename generation, unless the NO_GLOB option is set.
       If the EXTENDED_GLOB option is set, the ^,  ~ and #  char-
       acters  also  denote  a  pattern; otherwise (except for an
       initial ~, see Filename  Expansion  above)  they  are  not
       treated specially by the shell.  The word is replaced with
       a list of sorted filenames that match the pattern.  If  no
       matching  pattern  is found, the shell gives an error mes-
       sage, unless the NULL_GLOB option is set,  in  which  case
       the  word  is  deleted; or unless the NO_NOMATCH option is
       set, in which case the word is left unchanged.   In  file-
       name  generation,  the character / must be matched explic-
       itly; also, a . must be matched explicitly at  the  begin-
       ning  of  a  pattern  or  after  a /, unless the GLOB_DOTS
       option is set.  No filename generation pattern matches the
       files   "."  or  "..".   In  other  instances  of  pattern
       matching, the / and . are not treated specially.

              *      matches  any  string,  including  the   null
                     string.
              ?      matches any character.
              [ ... ]
                     matches any of the enclosed characters.
              [^ ... ]
                     matches  any  character  except the enclosed
                     characters.  [! ... ] is  the  same  as  the
                     above.
              <x-y>  matches  any  number  in  the  range x to y,
                     inclusive.  If x is omitted, the number must
                     be  less  than or equal to y.  If y is omit-
                     ted, the number  must  be  greater  than  or
                     equal  to  x.   A pattern of the form <-> or
                     simply <> matches any number.
              ^x     matches anything except the pattern x.
              x|y    matches either x or y.
              x#     matches zero or more occurrences of the pat-
                     tern x.
              x##    matches  one or more occurrences of the pat-
                     tern x.

       Parentheses may be used for grouping.   Note  that  the  |
       character  must be within parentheses, so that the lexical
       analyzer does not think it is a pipe character.  Also note
       that "/" has a higher precedence than "^"; that is:

              ls ^foo/bar

       will  search  directories in "." except "./foo" for a file
       named bar.

       A pathname component of the form (foo/)#  matches  a  path
       consisting  of  zero or more directories matching the pat-
       tern foo.  As a shorthand, **/  is  equivalent  to  (*/)#.
       Thus:

              ls (*/)#bar

       or

              ls **/bar

       does a recursive directory search for files named bar, not
       following symbolic links.  For this you can use  the  form
       ***/.

       If  used for filename generation, a pattern may contain an
       exclusion  specifier.   Such  patterns  are  of  the  form
       pat1~pat2.   This pattern will generate all files matching
       pat1, but which do not match pat2.  For example, *.c~lex.c
       will  match all files ending in .c, except the file lex.c.
       This may appear inside parentheses.  Note that "~"  has  a
       higher precedence than "|", so that pat1|pat2~pat3 matches
       any time that pat1 matches, or if pat2 matches while  pat3
       does  not.   Note also that "/" characters are not treated
       specially in the exclusion specifier so that  a  "*"  will
       match multiple path segments if they appear in the pattern
       to the left of the "~".

       Patterns used for filename generation may also  end  in  a
       list  of  qualifiers  enclosed in parentheses.  The quali-
       fiers specify which filenames  that  otherwise  match  the
       given  pattern  will  be inserted in the argument list.  A
       qualifier may be any one of the following:
              /      directories
              .      plain files
              @      symbolic links
              =      sockets
              p      named pipes (FIFOs)
              *      executable plain files (0100)
              %      device files (character or block special)
              %b     block special files
              %c     character special files
              r      readable files (0400)
              w      writable files (0200)
              x      executable files (0100)
              R      world-readable files (0004)
              W      world-writable files (0002)
              X      world-executable files (0001)
              s      setuid files (04000)
              S      setgid files (02000)
              ddev   files on the device dev
              l[-|+]ct
                     files having a link count less than ct  (-),
                     greater than ct (+), or is equal to ct
              U      files owned by the effective user id
              G      files owned by the effective group id
              uid    files owned by user id id if it is a number,
                     if not, than the character after the u  will
                     be  used  as  a  separator  and  the  string
                     between it and the next  matching  separator
                     (`(', `[', `{', and `<' match `)', `]', `}',
                     and `>' respectively,  any  other  character
                     matches itself) will be taken as a user name
                     and the user id of this user will  be  taken
                     (e.g. u:foo: or u[foo] for user foo)
              gid    like uid but with group ids or names
              a[-|+]n
                     files  accessed within last n days (-), more
                     than n days ago (+), or n days ago
              m[-|+]n
                     files modified within last n days (-),  more
                     than n days ago (+), or n days ago
              c[-|+]n
                     files whose inode changed within last n days
                     (-), more than n days ago  (+),  or  n  days
                     ago.   If  any  of  the  flags a, m, or c is
                     directly followed by a M, w, h, or  m  (e.g.
                     mh+5) the check is performed with months (of
                     30 days), weeks, hours, or  minutes  instead
                     of days, respectively.
              L[+|-]n
                     files  less  than  n  bytes (-), more than n
                     bytes (+), or exactly n bytes in length.
              ^      negates all qualifiers following it
              -      toggles between making the  qualifiers  work
                     on  symbolic  links  (the  default)  and the
                     files they point to
              M      sets the MARK_DIRS option  for  the  current
                     pattern
              T      appends a traling qualifier mark to the file
                     names, analogous to the  LIST_TYPES  option,
                     for the current pattern (overrides M)
              N      sets  the  NULL_GLOB  option for the current
                     pattern
              D      sets the GLOB_DOTS option  for  the  current
                     pattern

       More than one of these lists can be combined, separated by
       commas. The whole list matches if at least one of the sub-
       lists  matches  (they  are  `or'ed', the qualifiers in the
       sublists are `and'ed').

       If a : appears in a qualifier list, the remainder  of  the
       expression  in  parenthesis  is  interpreted as a modifier
       (see the subsection Modifiers  of  the  section  HISTORY).
       Note  that  each modifier must be introduced by a separate
       :.  Note also that the result after modification does  not
       have  to  be  an  existing file.  The name of any existing
       file can be followed by a modifier of the form (:..)  even
       if no filename generation is performed.

       Thus:

              ls *(-/)

       lists  all  directories  and  symbolic links that point to
       directories, and

              ls *(%W)

       lists all  world-writable  device  files  in  the  current
       directory, and

              ls *(W,X)

       lists  all  files in the current directory that are world-
       writable or world-executable, and

              echo /tmp/foo*(u0^@:t)

       outputs the basename of  all  root-owned  files  beginning
       with the string "foo" in /tmp, ignoring symlinks, and

              ls *.*~(lex|parse).[ch](^D^l1)

       lists  all  files  having  a link count of one whose names
       contain a dot (but not those starting with  a  dot,  since
       GLOB_DOTS  is  explicitly  switched off) except for lex.c,
       lex.h, parse.c, and parse.h.  A "/" at the end of  a  pat-
       tern is equivalent to "(/)".


HISTORY EXPANSION

       History substitution allows you to use words from previous
       command lines in the command line you  are  typing.   This
       simplifies spelling corrections and the repetition of com-
       plicated commands or arguments.  Command lines  are  saved
       in  the  history  list, the size of which is controlled by
       the  HISTSIZE  variable.   The  most  recent  command   is
       retained  in any case.  A history substitution begins with
       a !  and may occur anywhere on the command  line;  history
       substitutions  do  not nest.  The !  can be escaped with \
       to suppress its special meaning.  Single or double  quotes
       will not work for this.

       Input lines containing history substitutions are echoed on
       the terminal after being expanded, but  before  any  other
       substitutions take place or the command gets executed.

   Event Designators
       An event designator is a reference to a command-line entry
       in the history list.
              !      Start a history  substitution,  except  when
                     followed by a blank, newline, =, or (.
              !!     Refer  to  the previous command.  By itself,
                     this substitution repeats the previous  com-
                     mand.
              !n     Refer to command-line n.
              !-n    Refer to the current command-line minus n.
              !str   Refer  to  the  most recent command starting
                     with str.
              !?str[?]
                     Refer to the most recent command  containing
                     str.
              !#     Refer  to  the current command line typed in
                     so far.
              !{...} Insulate a history reference  from  adjacent
                     characters (if necessary).

   Word Designators
       A word designator indicates which word or words of a given
       command line will be included in a history  reference.   A
       `:'  separates  the  event  specification  from  the  word
       designator.  It can be  omitted  if  the  word  designator
       begins with a ^, $, *, - or %.  Word designators include:
              0      The first input word (command).
              n      The n'th argument.
              ^      The first argument, that is, 1.
              $      The last argument.
              %      The  word  matched by (the most recent) ?str
                     search.
              x-y    A range of words; -y abbreviates 0-y.
              *      All the arguments, or a null value if  there
                     is just one word in the event.
              x*     Abbreviates x-$.
              x-     Like x* but omitting word $.
       Note  that  a `%' word designator will only work when used
       as !%, !:%, !?str?:% and only when used after a !? substi-
       tution.   Anything  else will result in an error, although
       the error may not be the most obvious one.


   Modifiers
       After the optional word designator, you can add a sequence
       of  one  or more of the following modifiers, each preceded
       by a :.  These modifiers also work on the result of  file-
       name and parameter expansion.

              h      Remove  a trailing pathname component, leav-
                     ing the head.
              r      Remove a trailing suffix of the form `.xxx',
                     leaving the basename.
              e      Remove all but the suffix.
              t      Remove   all  leading  pathname  components,
                     leaving the tail.
              &      Repeat the previous substitution.
              g      Apply the change to the first occurrence  of
                     a match in each word, by prefixing the above
                     (for example, g&).
              p      Print the new command but do not execute it.
              q      Quote  the  substituted words, escaping fur-
                     ther substitutions.
              x      Like q, but break into words at each  blank.
              l      Convert the words to all lowercase.
              u      Convert the words to all uppercase.
              f      Repeats  the  immediately  (without a colon)
                     following modifier until the resulting  word
                     doesn't  change  any  more. This one and the
                     following four only work with parameter  and
                     filename expansion.
              F:expr:
                     Like  f,  but  repeats  only  n times if the
                     expression expr evaluates to n. Any  charac-
                     ter  can  be used instead of the `:', if any
                     of `(', `[', or `{' is used as  the  opening
                     delimiter the second one has to be ')', `]',
                     or `}' respectively.

              w      Makes  the  immediately  following  modifier
                     work on each word in the string.
              W:sep: Like  w  but  words are considered to be the
                     parts of the string that  are  separated  by
                     sep.  Any  character  can be used instead of
                     the `:',  opening  parentheses  are  handled
                     specially, see above.
              s/l/r[/]
                     Substitute r for l.

       Unless  preceded by a g, the substitution is done only for
       the first string that matches l.

       The  left-hand  side  of  substitutions  are  not  regular
       expressions,  but character strings.  Any character can be
       used as the delimiter in place of /.  A  backslash  quotes
       the  delimiter  character.   The character &, in the right
       hand side, is replaced by the  text  from  the  left-hand-
       side.   The  &  can  be quoted with a backslash.  A null l
       uses the previous string either from a l or from a contex-
       tual  scan  string s from !?s.  You can omit the rightmost
       delimiter if a newline immediately follows r;  the  right-
       most ?  in a context scan can similarly be omitted.

       By  default,  a history reference with no event specifica-
       tion refers to the same line as the last history reference
       on  that command line, unless it is the first history ref-
       erence in a command.  In that case,  a  history  reference
       with  no event specification always refers to the previous
       command.  However, if  the  option  CSH_JUNKIE_HISTORY  is
       set,  then  history  reference with no event specification
       will always refer to the previous command.   For  example,
       !!:1  will  always refer to the first word of the previous
       command and !!$ will always refer to the last word of  the
       previous  command.   And with CSH_JUNKIE_HISTORY set, then
       !:1 and !$ will function in the same manner  as  !!:1  and
       !!$,  respectively.   However,  if  CSH_JUNKIE_HISTORY  is
       unset, then !:1 and !$ will refer to the  first  and  last
       words  respectively, of the last command referenced on the
       current command line.  However, if they are the first his-
       tory reference on the command line, then they refer to the
       previous command.

       The character sequence ^foo^bar repeats the last  command,
       replacing the string "foo" with the string "bar".

       If  the shell encounters the character sequence !"  in the
       input, the history mechanism is temporarily disabled until
       the current list is fully parsed.  The !"  is removed from
       the input, and any subsequent !  characters have  no  spe-
       cial significance.

       A  less convenient but more comprehensible form of command
       history support is provided by the fc builtin (see below).
Hurricane Electric Internet Services: Accounts starting at $9.95/month
Hurricane Electric Internet Services
Copyright (C) 1998 Hurricane Electric. All Rights Reserved.