Parameter Extensions

• %~f1 Expand %1 to a Fully qualified path name - C:\utils\MyFile.txt
• %~d1 Expand %1 to a Drive letter only - C:
• %~p1 Expand %1 to a Path only e.g. \utils\ this includes a trailing \ which will be interpreted as an escape character by some commands.
• %~n1 Expand %1 to a file Name without file extension or path - MyFile or if only a path is present, with no trailing backslash, the last folder in that path.
• %~x1 Expand %1 to a file eXtension only - .txt
• %~s1 Change the meaning of f, n, s and x to reference the Short 8.3 name (if it exists.)
• %~1 Expand %1 removing any surrounding quotes (")
• %~a1 Display the file attributes of %1
• %~t1 Display the date/time of %1
• %~z1 Display the file size of %1
• %~$PATH:1 Search the PATH environment variable and expand %1 to the fully qualified name of the first match found.

${parameter:-word}
Use Default Values. If parameter is unset or null, the expansion of word is substituted. Otherwise,
the value of parameter is substituted.
${parameter:=word}
Assign Default Values. If parameter is unset or null, the expansion of word is assigned to parameter.
The value of parameter is then substituted. Positional parameters and special parameters may not be
assigned to in this way.
${parameter:?word}
Display Error if Null or Unset. If parameter is null or unset, the expansion of word (or a message to
that effect if word is not present) is written to the standard error and the shell, if it is not inter‐
active, exits. Otherwise, the value of parameter is substituted.
${parameter:+word}
Use Alternate Value. If parameter is null or unset, nothing is substituted, otherwise the expansion of
word is substituted.
${parameter:offset}
${parameter:offset:length}
Substring Expansion. Expands to up to length characters of the value of parameter starting at the
character specified by offset. If parameter is @, an indexed array subscripted by @ or *, or an asso‐
ciative array name, the results differ as described below. If length is omitted, expands to the sub‐
string of the value of parameter starting at the character specified by offset and extending to the end
of the value. length and offset are arithmetic expressions (see ARITHMETIC EVALUATION below).

          If offset evaluates to a number less than zero, the value is used as an offset in characters  from  the
          end of the value of parameter.  If length evaluates to a number less than zero, it is interpreted as an
          offset in characters from the end of the value of parameter rather than a number of characters, and the
          expansion  is the characters between offset and that result.  Note that a negative offset must be sepa‐
          rated from the colon by at least one space to avoid being confused with the :- expansion.

          If parameter is @, the result is length positional parameters beginning at offset.  A  negative  offset
          is  taken  relative to one greater than the greatest positional parameter, so an offset of -1 evaluates
          to the last positional parameter.  It is an expansion error if length evaluates to a number  less  than
          zero.

          If  parameter  is  an indexed array name subscripted by @ or *, the result is the length members of the
          array beginning with ${parameter[offset]}.  A negative offset is taken relative to one greater than the
          maximum  index  of  the specified array.  It is an expansion error if length evaluates to a number less
          than zero.

          Substring expansion applied to an associative array produces undefined results.

          Substring indexing is zero-based unless the positional parameters are used, in which case the  indexing
          starts  at 1 by default.  If offset is 0, and the positional parameters are used, $0 is prefixed to the
          list.

   ${!prefix*}
   ${!prefix@}
          Names matching prefix.  Expands to the names of variables whose names begin with prefix,  separated  by
          the  first character of the IFS special variable.  When @ is used and the expansion appears within dou‐
          ble quotes, each variable name expands to a separate word.

   ${!name[@]}
   ${!name[*]}
          List of array keys.  If name is an array variable, expands to the list of array indices (keys) assigned
          in  name.  If name is not an array, expands to 0 if name is set and null otherwise.  When @ is used and
          the expansion appears within double quotes, each key expands to a separate word.

  ${#parameter}
          Parameter length.  The length in characters of the value of parameter is substituted.  If parameter  is
          *  or  @,  the value substituted is the number of positional parameters.  If parameter is an array name
          subscripted by * or @, the value substituted is the number of elements in the array.  If  parameter  is
          an  indexed  array name subscripted by a negative number, that number is interpreted as relative to one
          greater than the maximum index of parameter, so negative indices count back from the end of the  array,
          and an index of -1 references the last element.

   ${parameter#word}
   ${parameter##word}
          Remove  matching  prefix pattern.  The word is expanded to produce a pattern just as in pathname expan‐
          sion, and matched against the expanded value of parameter  using  the  rules  described  under  Pattern
          Matching below.  If the pattern matches the beginning of the value of parameter, then the result of the
          expansion is the expanded value of parameter with the shortest matching pattern (the ``#'' case) or the
          longest matching pattern (the ``##'' case) deleted.  If parameter is @ or *, the pattern removal opera‐
          tion is applied to each positional parameter in turn, and the expansion is the resultant list.  If  pa‐
          rameter  is an array variable subscripted with @ or *, the pattern removal operation is applied to each
          member of the array in turn, and the expansion is the resultant list.

   ${parameter%word}
   ${parameter%%word}
          Remove matching suffix pattern.  The word is expanded to produce a pattern just as in  pathname  expan‐
          sion,  and  matched  against  the  expanded  value of parameter using the rules described under Pattern
          Matching below.  If the pattern matches a trailing portion of the expanded value of parameter, then the
          result  of  the  expansion  is  the expanded value of parameter with the shortest matching pattern (the
          ``%'' case) or the longest matching pattern (the ``%%'' case) deleted.  If parameter is  @  or  *,  the
          pattern removal operation is applied to each positional parameter in turn, and the expansion is the re‐
          sultant list.  If parameter is an array variable subscripted with @ or *, the pattern removal operation
          is applied to each member of the array in turn, and the expansion is the resultant list.

   ${parameter/pattern/string}
          Pattern  substitution.  The pattern is expanded to produce a pattern just as in pathname expansion, Pa‐
          rameter is expanded and the longest match of pattern against its value is replaced  with  string.   The
          match  is  performed using the rules described under Pattern Matching below.  If pattern begins with /,
          all matches of pattern are replaced with string.  Normally only the first match is replaced.   If  pat‐
          tern  begins with #, it must match at the beginning of the expanded value of parameter.  If pattern be‐
          gins with %, it must match at the end of the expanded value of parameter.  If string is  null,  matches
          of  pattern are deleted and the / following pattern may be omitted.  If the nocasematch shell option is
          enabled, the match is performed without regard to the case of alphabetic characters.  If parameter is @
          or  *, the substitution operation is applied to each positional parameter in turn, and the expansion is
          the resultant list.  If parameter is an array variable subscripted with @ or *, the substitution opera‐
          tion is applied to each member of the array in turn, and the expansion is the resultant list.

   ${parameter^pattern}
   ${parameter^^pattern}
   ${parameter,pattern}
   ${parameter,,pattern}
          Case  modification.   This expansion modifies the case of alphabetic characters in parameter.  The pat‐
          tern is expanded to produce a pattern just as in pathname expansion.  Each character  in  the  expanded
          value  of  parameter  is tested against pattern, and, if it matches the pattern, its case is converted.
          The pattern should not attempt to match more than one character.  The  ^  operator  converts  lowercase
          letters matching pattern to uppercase; the , operator converts matching uppercase letters to lowercase.
          The ^^ and ,, expansions convert each matched character in the expanded value; the ^ and  ,  expansions
          match and convert only the first character in the expanded value.  If pattern is omitted, it is treated
          like a ?, which matches every character.  If parameter is @ or *, the case  modification  operation  is
          applied to each positional parameter in turn, and the expansion is the resultant list.  If parameter is
          an array variable subscripted with @ or *, the case modification operation is applied to each member of
          the array in turn, and the expansion is the resultant list.

   ${parameter@operator}
          Parameter transformation.  The expansion is either a transformation of the value of parameter or infor‐
          mation about parameter itself, depending on the value of operator.  Each operator is a single letter:

          Q      The expansion is a string that is the value of parameter quoted in a format that can  be  reused
                 as input.
          E      The  expansion  is  a  string that is the value of parameter with backslash escape sequences ex‐
                 panded as with the $'...' quoting mechanism.
          P      The expansion is a string that is the result of expanding the value of parameter as if it were a
                 prompt string (see PROMPTING below).
          A      The  expansion  is  a  string in the form of an assignment statement or declare command that, if
                 evaluated, will recreate parameter with its attributes and value.
          a      The expansion is a string consisting of flag values representing parameter's attributes.

          If parameter is @ or *, the operation is applied to each positional parameter in turn, and  the  expan‐
          sion  is  the resultant list.  If parameter is an array variable subscripted with @ or *, the operation
          is applied to each member of the array in turn, and the expansion is the resultant list.

          The result of the expansion is subject to word splitting and pathname expansion as described below.

Introduction

One core functionality of Bash is to manage parameters. A parameter is an entity that stores values and is referenced by a name, a number or a special symbol.

parameters referenced by a name are called variables (this also applies to arrays)
parameters referenced by a number are called positional parameters and reflect the arguments given to a shell
parameters referenced by a special symbol are auto-set parameters that have different special meanings and uses

Parameter expansion is the procedure to get the value from the referenced entity, like expanding a variable to print its value. On expansion time you can do very nasty things with the parameter or its value. These things are described here.

If you saw some parameter expansion syntax somewhere, and need to check what it can be, try the overview section below!

Arrays can be special cases for parameter expansion, every applicable description mentions arrays below. Please also see the article about arrays.

For a more technical view what a parameter is and which types exist, see the dictionary entry for "parameter".