Parameter expansions

The format for parameter expansion is as follows:

${expression}

where expression consists of all characters until the matching right brace (}). Any right brace characters escaped by a backslash or within a string with quotation marks, as well as characters in embedded arithmetic expansions, command substitutions, and variable expansions, are not examined in determining the matching right brace.

The simplest form for parameter expansion is:

${parameter}

The value, if any, of parameter is substituted. The parameter name or symbol can be enclosed in braces, which are optional except for positional parameters with more than one digit or when parameter is followed by a character that might be interpreted as part of the name. If a parameter expansion occurs inside double quotation marks, then:

1. Path name expansion is not performed on the results of the expansion.
2. Field splitting is not performed on the results of the expansion, with the exception of @ special parameter.

A parameter expansion can be modified by using one of the following formats:

${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. In all cases, the final value of parameter is substituted. Only variables, not positional parameters or special parameters, can be assigned in this way.

${parameter:?word]}

Indicate Error if Null or Unset. If parameter is unset or null, the expansion of word (or a message indicating it is unset if word is omitted) is written to standard error and a non-interactive shell exits with a nonzero exit status. Otherwise, the value of parameter is substituted.

${parameter:+word}

Use Alternate Value. If parameter is unset or null, null is substituted. Otherwise, the expansion of word is substituted.

In the preceding four parameter expansions, using a colon in the format results in a test for a parameter that is unset or null; removing the colon results in a test for a parameter that is only unset.

${#parameter}

String Length. If parameter is @ or *, the number of positional parameters is substituted. Otherwise, the length of the value of parameter is substituted.

${parameter%word}

Remove Smallest Suffix Pattern. The word is expanded to produce a pattern. Then the result is parameter after removing the smallest portion of the suffix matched by the pattern.

${parameter%%word}

Remove Largest Suffix Pattern. The word is expanded to produce a pattern. Then the result is parameter after removing the largest portion of the suffix matched by the pattern.

${parameter#word}

Remove Smallest Prefix Pattern. The word is expanded to produce a pattern. Then the result is parameter after removing the smallest portion of the prefix matched by the pattern.

${parameter##word}

Remove Largest Prefix Pattern. The word is expanded to produce a pattern. Then the result is parameter after removing the largest portion of the prefix matched by the pattern.

${parameter:offset}

${parameter:offset:length}

Substring Starting at Offset. The value of this expansion is the substring starting at the byte specified by offset for length bytes. If length is not specified or the value of length causes the expansion to exceed the length of parameter, the substring ends with the last byte of parameter. Both offset and length are arithmetic expressions and must evaluate to a value that is greater than or equal to zero. The first byte of parameter is defined by an offset of zero.

${parameter/pattern/string}

${parameter//pattern/string}

Substitute String for Pattern. The value of this expansion is the value of parameter with the longest match of pattern replaced with string. In the first form, only the first match of pattern is replaced. In the second form, all matches of pattern are replaced. If pattern begins with #, it must match at the beginning of parameter. If pattern begins with a %, it must match at the end of parameter.

Examples

1. Expand the variable QSH_VERSION.

   echo ${QSH_VERSION}
   

2. Expand the variable filename and use a default value.

   echo ${filename:-/tmp/default.txt}
   

3. Expand the variable index and assign a default value.

   echo ${index:=0}
   

4. Expand the variable filename and indicate an error if unset.

   echo ${filename:?Variable is not set}
   

5. Expand the variable DIRLIST using string length.

   DIRLIST=/usr/bin:/home/mike
   echo ${#DIRLIST}
   

6. Expand the variable DIRLIST using remove smallest suffix pattern.

   DIRLIST=/usr/bin:/home/mike
   echo ${DIRLIST%/*}
   

7. Expand the variable DIRLIST using remove largest suffix pattern.

   DIRLIST=/usr/bin:/home/mike
   echo ${DIRLIST%%:*}
   

8. Expand the variable DIRLIST using remove smallest prefix pattern.

   DIRLIST=/usr/bin:/home/mike
   echo ${DIRLIST#/usr}
   

9. Expand the variable DIRLIST using remove largest prefix pattern.

   DIRLIST=/usr/bin:/home/mike
   echo ${DIRLIST##*/}
   

10. Expand the variable DIRLIST using a substring starting at offset.

    DIRLIST=/usr/bin:/home/mike
    echo ${DIRLIST:5:3}
    

11. Expand the variable DIRLIST using a substitute string for pattern.

    DIRLIST=/usr/bin:/home/mike
    echo ${DIRLIST/m?ke/joel}