Edit

Share via

2. Lexical Structure

  • Article

2.1 Grammars

This specification shows the syntax of the PowerShell language using two grammars. The lexical grammar (§B.1) shows how Unicode characters are combined to form line terminators, comments, white space, and tokens. The syntactic grammar (§B.2) shows how the tokens resulting from the lexical grammar are combined to form PowerShell scripts.

For convenience, fragments of these grammars are replicated in appropriate places throughout this specification.

Any use of the characters 'a' through 'z' in the grammars is case insensitive. This means that letter case in variables, aliases, function names, keywords, statements, and operators is ignored. However, throughout this specification, such names are written in lowercase, except for some automatic and preference variables.

2.2 Lexical analysis

2.2.1 Scripts

Syntax:

Tip

The ~opt~ notation in the syntax definitions indicates that the lexical entity is optional in the syntax.

input:
    input-elements~opt~   signature-block~opt~

input-elements:
    input-element
    input-elements   input-element

input-element:
    whitespace
    comment
    token

signature-block:
    signature-begin   signature   signature-end

signature-begin:
    new-line-character   # SIG # Begin signature block   new-line-character

signature:
    base64 encoded signature blob in multiple single-line-comments

signature-end:
    new-line-character   # SIG # End signature block   new-line-character

Description:

The input source stream to a PowerShell translator is the input in a script, which contains a sequence of Unicode characters. The lexical processing of this stream involves the reduction of those characters into a sequence of tokens, which go on to become the input of syntactic analysis.

A script is a group of PowerShell commands stored in a script-file. The script itself has no name, per se, and takes its name from its source file. The end of that file indicates the end of the script.

A script may optionally contain a digital signature. A host environment is not required to process any text that follows a signature or anything that looks like a signature. The creation and use of digital signatures are not covered by this specification.

2.2.2 Line terminators

Syntax:

new-line-character:
    Carriage return character (U+000D)
    Line feed character (U+000A)
    Carriage return character (U+000D) followed by line feed character (U+000A)

new-lines:
    new-line-character
    new-lines new-line-character

Description:

The presence of new-line-characters in the input source stream divides it into lines that can be used for such things as error reporting and the detection of the end of a single-line comment.

A line terminator can be treated as white space (§2.2.4).

2.2.3 Comments

Syntax:

comment:
    single-line-comment
    requires-comment
    delimited-comment

single-line-comment:
    # input-characters~opt~

input-characters:
    input-character
    input-characters input-character

input-character:
    Any Unicode character except a new-line-character

requires-comment:
    #requires whitespace command-arguments

dash:
    - (U+002D)
    EnDash character (U+2013)
    EmDash character (U+2014)
    Horizontal bar character (U+2015)

dashdash:
    dash dash

delimited-comment:
    < # delimited-comment-text~opt~ hashes >

delimited-comment-text:
    delimited-comment-section
    delimited-comment-text delimited-comment-section

delimited-comment-section:
    >
    hashes~opt~  not-greater-than-or-hash

hashes:
    #
    hashes #

not-greater-than-or-hash:
    Any Unicode character except > or #

Description:

Source code can be annotated by the use of comments.

A single-line-comment begins with the character # and ends with a new-line-character.

A delimited-comment begins with the character pair <# and ends with the character pair #>. It can occur as part of a source line, as a whole source line, or it can span any number of source lines.

A comment is treated as white space.

The productions above imply that

  • Comments do not nest.
  • The character sequences <# and #> have no special meaning in a single-line comment.
  • The character # has no special meaning in a delimited comment.

The lexical grammar implies that comments cannot occur inside tokens.

(See §A for information about creating script files that contain special-valued comments that are used to generate documentation from script files.)

A requires-comment specifies the criteria that have to be met for its containing script to be allowed to run. The primary criterion is the version of PowerShell being used to run the script. The minimum version requirement is specified as follows:

#requires -Version N[.n]

Where N is the (required) major version and n is the (optional) minor version.

A requires-comment can be present in any script file; however, it cannot be present inside a function or cmdlet. It must be the first item on a source line. A script can contain multiple requires-comments.

A character sequence is only recognized as a comment if that sequence begins with # or <#. For example, hello#there is considered a single token whereas hello #there is considered the token hello followed by a single-line comment. As well as following white space, the comment start sequence can also be preceded by any expression-terminating or statement-terminating character (such as ), }, ], ', ", or ;).

A requires-comment cannot be present inside a snap-in.

There are four other forms of a requires-comment:

#requires --Assembly AssemblyId
#requires --Module ModuleName
#requires --PsSnapIn PsSnapIn [ -Version *N* [.n] ]
#requires --ShellId ShellId

2.2.4 White space

Syntax:

whitespace:
    Any character with Unicode class Zs, Zl, or Zp
    Horizontal tab character (U+0009)
    Vertical tab character (U+000B)
    Form feed character (U+000C)
    ` (The backtick character U+0060) followed by new-line-character

Description:

White space consists of any sequence of one or more whitespace characters.

Except for the fact that white space may act as a separator for tokens, it is ignored.

Unlike some popular languages, PowerShell does not consider line-terminator characters (§2.2.2) to be white space. However, a line terminator can be treated as white space by preceding it immediately by a backtick character, ` (U+0060). This is necessary when the contents of a line are complete syntactically, yet the following line contains tokens intended to be associated with the previous line. For example,

$number = 10 # assigns 10 to $number; nothing is written to the pipeline
+ 20 # writes 20 to the pipeline
- 50 # writes -50 to the pipeline
$number # writes $number's value, 10, to the pipeline

In this example, the backtick indicates the source line is continued. The following expression is equivalent to $number = 10 + 20 - 50.

$number = 10 `
+ 20 `
- 50
$number # writes $number's value to the pipeline
-20

2.3 Tokens

Syntax:

token:
    keyword
    variable
    command
    command-parameter
    command-argument-token
    integer-literal
    real-literal
    string-literal
    type-literal
    operator-or-punctuator

Description:

A token is the smallest lexical element within the PowerShell language.

Tokens can be separated by new-lines, comments, white space, or any combination thereof.

2.3.1 Keywords

Syntax:

keyword: one of
    begin          break          catch       class
    continue       data           define      do
    dynamicparam   else           elseif      end
    exit           filter         finally     for
    foreach        from           function    if
    in             inlinescript   parallel    param
    process        return         switch      throw
    trap           try            until       using
    var            while          workflow

Description:

A keyword is a sequence of characters that has a special meaning when used in a context-dependent place. Most often, this is as the first token in a statement; however, there are other locations, as indicated by the grammar. (A token that looks like a keyword, but is not being used in a keyword context, is a command-name or a command-argument.)

The keywords class, define, from, using, and var are reserved for future use.

Note

Editor's Note: The class and using keywords were introduced in PowerShell 5.0. See about_Classes and about_Using.

2.3.2 Variables

Syntax:

variable:
    $$
    $?
    $^
    $   variable-scope~opt~  variable-characters
    @   variable-scope~opt~  variable-characters
    braced-variable


braced-variable:
    ${   variable-scope~opt~   braced-variable-characters   }

variable-scope:
    global:
    local:
    private:
    script:
    using:
    workflow:
    variable-namespace

variable-namespace:
    variable-characters   :

variable-characters:
    variable-character
    variable-characters   variable-character

variable-character:
    A Unicode character of classes Lu, Ll, Lt, Lm, Lo, or Nd
    _   (The underscore character U+005F)
    ?

braced-variable-characters:
    braced-variable-character
    braced-variable-characters   braced-variable-character

braced-variable-character:
    Any Unicode character except
        }   (The closing curly brace character U+007D)
        `   (The backtick character U+0060)
    escaped-character

escaped-character:
    `   (The backtick character U+0060) followed by any Unicode character

Description:

Variables are discussed in detail in (§5). The variable $? is discussed in §2.3.2.2. Scopes are discussed in §3.5.

The variables $$ and $^ are reserved for use in an interactive environment, which is outside the scope of this specification.

There are two ways of writing a variable name: A braced variable name, which begins with $, followed by a curly bracket-delimited set of one or more almost-arbitrary characters; and an ordinary variable name, which also begins with $, followed by a set of one or more characters from a more restrictive set than a braced variable name allows. Every ordinary variable name can be expressed using a corresponding braced variable name.

$totalCost
$Maximum_Count_26

$végösszeg # Hungarian
$итог # Russian
$総計 # Japanese (Kanji)

${Maximum_Count_26}
${Name with`twhite space and `{punctuation`}}
${E:\\File.txt}

There is no limit on the length of a variable name, all characters in a variable name are significant, and letter case is not distinct.

There are several different kinds of variables: user-defined (§2.3.2.1), automatic (§2.3.2.2), and preference (§2.3.2.3). They can all coexist in the same scope (§3.5).

Consider the following function definition and calls:

function Get-Power ([long]$base, [int]$exponent) { ... }

Get-Power 5 3 # $base is 5, $exponent is 3
Get-Power -exponent 3 -base 5 # " " "

Each argument is passed by position or name, one at a time. However, a set of arguments can be passed as a group with expansion into individual arguments being handled by the runtime environment. This automatic argument expansion is known as splatting. For example,

$values = 5,3 # put arguments into an array
Get-Power @values

$hash = @{ exponent = 3; base = 5 } # put arguments into a Hashtable
Get-Power @hash

function Get-Power2 { Get-Power @args } # arguments are in an array

Get-Power2 --exponent 3 --base 5 # named arguments splatted named in
@args
Get-Power2 5 3 # position arguments splatted positionally in @args

This is achieved by using @ instead of $ as the first character of the variable being passed. This notation can only be used in an argument to a command.

Names are partitioned into various namespaces each of which is stored on a virtual drive (§3.1). For example, variables are stored on Variable:, environment variables are stored on Env:, functions are stored on Function:, and aliases are stored on Alias:. All of these names can be accessed as variables using the variable-namespace production within variable-scope. For example,

function F { "Hello from F" }
$Function:F # invokes function F

Set-Alias A F
$Alias:A # invokes function F via A

$Count = 10
$Variable:Count # accesses variable Count
$Env:Path # accesses environment variable Path

Any use of a variable name with an explicit Variable: namespace is equivalent to the use of that same variable name without that qualification. For example, $v and $Variable:v are interchangeable.

As well as being defined in the language, variables can also be defined by the cmdlet New-Variable.

2.3.2.1 User-defined variables

Any variable name allowed by the grammar but not used by automatic or preference variables is available for user-defined variables.

User-defined variables are created and managed by user-defined script.

2.3.2.2 Automatic variables

Automatic variables store state information about the PowerShell environment. Their values can be read in user-written script but not written.

Note

The table originally found in this document was removed to reduce duplication. For a complete list of automatic variables, see about_Automatic_Variables.

2.3.2.3 Preference variables

Preference variables store user preferences for the session. They are created and initialized by the PowerShell runtime environment. Their values can be read and written in user-written script.

Note

The table originally found in this document was removed to reduce duplication. For a complete list of preference variables, see about_Preference_Variables.

2.3.3 Commands

Syntax:

generic-token:
    generic-token-parts

generic-token-parts:
    generic-token-part
    generic-token-parts generic-token-part

generic-token-part:
    expandable-string-literal
    verbatim-here-string-literal
    variable
    generic-token-char

generic-token-char:
    Any Unicode character except
        {   }   (   )   ;   ,   |   &   $
        ` (The backtick character U+0060)
        double-quote-character
        single-quote-character
        whitespace
        new-line-character
        escaped-character

generic-token-with-subexpr-start:
    generic-token-parts $(

2.3.4 Parameters

Syntax:

command-parameter:
    dash first-parameter-char parameter-chars colon~opt~

first-parameter-char:
    A Unicode character of classes Lu, Ll, Lt, Lm, or Lo
    _ (The underscore character U+005F)
    ?

parameter-chars:
    parameter-char
    parameter-chars parameter-char

parameter-char:
    Any Unicode character except
        { } ( ) ; , \| & . [
        colon
        whitespace
        new-line-character

colon:
    : (The colon character U+003A)

verbatim-command-argument-chars:
    verbatim-command-argument-part
    verbatim-command-argument-chars verbatim-command-argument-part

verbatim-command-argument-part:
    verbatim-command-string
    & non-ampersand-character
    Any Unicode character except
        |
        new-line-character

non-ampersand-character:
    Any Unicode character except &

verbatim-command-string:
    double-quote-character non-double-quote-chars
    double-quote-character

non-double-quote-chars:
    non-double-quote-char
    non-double-quote-chars non-double-quote-char

non-double-quote-char:
    Any Unicode character except
        double-quote-character

Description:

When a command is invoked, information may be passed to it via one or more arguments whose values are accessed from within the command through a set of corresponding parameters. The process of matching parameters to arguments is called parameter binding.

There are three kinds of argument:

  • Switch parameter (§8.10.5) -- This has the form command-parameter where first-parameter-char and parameter-chars together make up the switch name, which corresponds to the name of a parameter (without its leading -) in the command being invoked. If the trailing colon is omitted, the presence of this argument indicates that the corresponding parameter be set to $true. If the trailing colon is present, the argument immediately following must designate a value of type bool, and the corresponding parameter is set to that value. For example, the following invocations are equivalent:

    Set-MyProcess -Strict
Set-MyProcess -Strict: $true

  • Parameter with argument (§8.10.2) -- This has the form command-parameter where first-parameter-char and parameter-chars together make up the parameter name, which corresponds to the name of a parameter (without its leading -) in the command being invoked. There must be no trailing colon. The argument immediately following designates an associated value. For example, given a command Get-Power, which has parameters $base and $exponent, the following invocations are equivalent:

    Get-Power -base 5 -exponent 3
Get-Power -exponent 3 -base 5

  • Positional argument (§8.10.2) - Arguments and their corresponding parameters inside commands have positions with the first having position zero. The argument in position 0 is bound to the parameter in position 0; the argument in position 1 is bound to the parameter in position 1; and so on. For example, given a command Get-Power, that has parameters $base and $exponent in positions 0 and 1, respectively, the following invokes that command:

    Get-Power 5 3

See §8.2 for details of the special parameters -- and --%.

When a command is invoked, a parameter name may be abbreviated; any distinct leading part of the full name may be used, provided that is unambiguous with respect to the names of the other parameters accepted by the same command.

For information about parameter binding see §8.14.

2.3.5 Literals

Syntax:

literal:
    integer-literal
    real-literal
    string-literal

2.3.5.1 Numeric literals

There are two kinds of numeric literals: integer (§2.3.5.1.1) and real (§2.3.5.1.2). Both can have multiplier suffixes (§2.3.5.1.3).

2.3.5.1.1 Integer literals

Syntax:

integer-literal:
    decimal-integer-literal
    hexadecimal-integer-literal

decimal-integer-literal:
    decimal-digits numeric-type-suffix~opt~ numeric-multiplier~opt~

decimal-digits:
    decimal-digit
    decimal-digit decimal-digits

decimal-digit: one of
    0  1  2  3  4  5  6  7  8  9

numeric-type-suffix:
    long-type-suffix
    decimal-type-suffix

hexadecimal-integer-literal:
    0x hexadecimal-digits long-type-suffix~opt~
    numeric-multiplier~opt~

hexadecimal-digits:
    hexadecimal-digit
    hexadecimal-digit decimal-digits

hexadecimal-digit: one of
    0  1  2  3  4  5  6  7  8  9  a  b  c  d  e  f

long-type-suffix:
    l

numeric-multiplier: one of
    kb mb gb tb pb

Description:

The type of an integer literal is determined by its value, the presence or absence of long-type-suffix, and the presence of a numeric-multiplier (§2.3.5.1.3).

For an integer literal with no long-type-suffix

  • If its value can be represented by type int (§4.2.3), that is its type;
  • Otherwise, if its value can be represented by type long (§4.2.3), that is its type.
  • Otherwise, if its value can be represented by type decimal (§2.3.5.1.2), that is its type.
  • Otherwise, it is represented by type double (§2.3.5.1.2).

For an integer literal with long-type-suffix

  • If its value can be represented by type long (§4.2.3), that is its type;
  • Otherwise, that literal is ill formed.

In the twos-complement representation of integer values, there is one more negative value than there is positive. For the int type, that extra value is ‑2147483648. For the long type, that extra value is ‑9223372036854775808. Even though the token 2147483648 would ordinarily be treated as a literal of type long, if it is preceded immediately by the unary - operator, that operator and literal are treated as a literal of type int having the smallest value. Similarly, even though the token 9223372036854775808 would ordinarily be treated as a real literal of type decimal, if it is immediately preceded by the unary - operator, that operator and literal are treated as a literal of type long having the smallest value.

Some examples of integer literals are 123 (int), 123L (long), and 200000000000 (long).

There is no such thing as an integer literal of type byte.

2.3.5.1.2 Real literals

Syntax:

real-literal:
    decimal-digits . decimal-digits exponent-part~opt~ decimal-type-suffix~opt~ numeric-multiplier~opt~
    . decimal-digits exponent-part~opt~ decimal-type-suffix~opt~ numeric-multiplier~opt~
    decimal-digits exponent-part decimal-type-suffix~opt~ numeric-multiplier~opt~

exponent-part:
    e sign~opt~  decimal-digits

sign: one of
    +
    dash

decimal-type-suffix:
    d
    l

numeric-multiplier: one of
    kb mb gb tb pb

dash:
    - (U+002D)
    EnDash character (U+2013)
    EmDash character (U+2014)
    Horizontal bar character (U+2015)

Description:

A real literal may contain a numeric-multiplier (§2.3.5.1.3).

There are two kinds of real literal: double and decimal. These are indicated by the absence or presence, respectively, of decimal-type-suffix. (There is no such thing as a float real literal.)

A double real literal has type double (§4.2.4.1). A decimal real literal has type decimal (§4.2.4.2). Trailing zeros in the fraction part of a decimal real literal are significant.

If the value of exponent-part's decimal-digits in a double real literal is less than the minimum supported, the value of that double real literal is 0. If the value of exponent-part's decimal-digits in a decimal real literal is less than the minimum supported, that literal is ill formed. If the value of exponent-part's decimal-digits in a double or decimal real literal is greater than the maximum supported, that literal is ill formed.

Some examples of double real literals are 1., 1.23, .45e35, 32.e+12, and 123.456E-231.

Some examples of decimal real literals are 1d (which has scale 0), 1.20d (which has scale 2), 1.23450e1d (i.e., 12.3450, which has scale 4), 1.2345e3d (i.e., 1234.5, which has scale 1), 1.2345e-1d (i.e., 0.12345, which has scale 5), and 1.2345e-3d (i.e., 0.0012345, which has scale 7).

Note

Because a double real literal need not have a fraction or exponent part, the grouping parentheses in (123).M are needed to ensure that the property or method M is being selected for the integer object whose value is 123. Without those parentheses, the real literal would be ill-formed.

Note

Although PowerShell does not provide literals for infinities and NaNs, double real literal-like equivalents can be obtained from the static read-only properties PositiveInfinity, NegativeInfinity, and NaN of the types float and double (§4.2.4.1).

The grammar permits what starts out as a double real literal to have an l or L type suffix. Such a token is really an integer literal whose value is represented by type long.

Note

This feature has been retained for backwards compatibility with earlier versions of PowerShell. However, programmers are discouraged from using integer literals of this form as they can easily obscure the literal's actual value. For example, 1.2L has value 1, 1.2345e1L has value 12, and 1.2345e-5L has value 0, none of which is immediately obvious.

2.3.5.1.3 Multiplier suffixes

Syntax:

numeric-multiplier: *one of*
    kb mb gb tb pb

Description:

For convenience, integer and real literals can contain a numeric-multiplier, which indicates one of a set of commonly used powers of 10. numeric-multiplier can be written in any combination of upper- or lowercase letters.

Multiplier Meaning Example
kb kilobyte (1024) 1kb ≡ 1024
mb megabyte (1024 x 1024) 1.30Dmb ≡ 1363148.80
gb gigabyte (1024 x 1024 x 1024) 0x10Gb ≡ 17179869184
tb terabyte (1024 x 1024 x 1024 x 1024) 1.4e23tb ≡ 1.5393162788864E+35
pb petabyte (1024 x 1024 x 1024 x 1024 x 1024) 0x12Lpb ≡ 20266198323167232

2.3.5.2 String literals

Syntax:

string-literal:
    expandable-string-literal
    expandable-here-string-literal
    verbatim-string-literal
    verbatim-here-string-literal

expandable-string-literal:
    double-quote-character expandable-string-characters~opt~  dollars~opt~ double-quote-character

double-quote-character:
    " (U+0022)
    Left double quotation mark (U+201C)
    Right double quotation mark (U+201D)
    Double low-9 quotation mark (U+201E)

expandable-string-characters:
      expandable-string-part
      expandable-string-characters
      expandable-string-part

expandable-string-part:
    Any Unicode character except
        $
        double-quote-character
        ` (The backtick character U+0060)
    braced-variable
    $ Any Unicode character except
        (
        {
        double-quote-character
        ` (The backtick character U+0060)*
    $ escaped-character
    escaped-character
    double-quote-character double-quote-character

dollars:
    $
    dollars $

expandable-here-string-literal:
    @  double-quote-character  whitespace~opt~  new-line-character
        expandable-here-string-characters~opt~  new-line-character  double-quote-character  @

expandable-here-string-characters:
    expandable-here-string-part
    expandable-here-string-characters  expandable-here-string-part

expandable-here-string-part:
    Any Unicode character except
        $
        new-line-character
    braced-variable
    $ Any Unicode character except
        (
        new-line-character
    $ new-line-character  Any Unicode character except double-quote-char
    $ new-line-character double-quote-char  Any Unicode character except @
    new-line-character  Any Unicode character except double-quote-char
    new-line-character double-quote-char  Any Unicode character except @

expandable-string-with-subexpr-start:
    double-quote-character  expandable-string-chars~opt~  $(

expandable-string-with-subexpr-end:
    double-quote-char

expandable-here-string-with-subexpr-start:
    @  double-quote-character  whitespace~opt~  new-line-character  expandable-here-string-chars~opt~  $(

expandable-here-string-with-subexpr-end:
    new-line-character  double-quote-character  @

verbatim-string-literal:
    single-quote-character verbatim-string-characters~opt~ single-quote-char

single-quote-character:
    ' (U+0027)
    Left single quotation mark (U+2018)
    Right single quotation mark (U+2019)
    Single low-9 quotation mark (U+201A)
    Single high-reversed-9 quotation mark (U+201B)

verbatim-string-characters:
    verbatim-string-part
    verbatim-string-characters verbatim-string-part

verbatim-string-part:
    *Any Unicode character except* single-quote-character
    single-quote-character  single-quote-character

verbatim-here-string-literal:
    @ single-quote-character whitespace~opt~  new-line-character
        verbatim-here-string-characters~opt~  new-line-character
            single-quote-character *@*

verbatim-*here-string-characters:
    verbatim-here-string-part
    verbatim-here-string-characters  verbatim-here-string-part

verbatim-here-string-part:
    Any Unicode character except* new-line-character
    new-line-character  Any Unicode character except single-quote-character
    new-line-character  single-quote-character  Any Unicode character except @

Description:

There are four kinds of string literals:

  • verbatim-string-literal (single-line single-quoted), which is a sequence of zero or more characters delimited by a pair of single-quote-characters. Examples are '' and 'red'.

  • expandable-string-literal (single-line double-quoted), which is a sequence of zero or more characters delimited by a pair of double-quote-characters. Examples are "" and "red".

  • verbatim-here-string-literal (multi-line single-quoted), which is a sequence of zero or more characters delimited by the character pairs @single-quote-character and single-quote-character@, respectively, all contained on two or more source lines. Examples are:

    @'
'@

@'
line 1
'@

@'
line 1
line 2
'@

  • expandable-here-string-literal (multi-line double-quoted), which is a sequence of zero or more characters delimited by the character pairs @double-quote-character and double-quote-character@, respectively, all contained on two or more source lines. Examples are:

    @"
"@

@"
line 1
"@

@"
line 1
line 2
"@

For verbatim-here-string-literals and expandable-here-string-literals, except for white space (which is ignored) no characters may follow on the same source line as the opening delimiter-character pair, and no characters may precede on the same source line as the closing delimiter character pair.

The body of a verbatim-here-string-literal or an expandable-here-string-literal begins at the start of the first source line following the opening delimiter, and ends at the end of the last source line preceding the closing delimiter. The body may be empty. The line terminator on the last source line preceding the closing delimiter is not part of that literal's body.

A literal of any of these kinds has type string (§4.3.1).

The character used to delimit a verbatim-string-literal or expandable-string-literal can be contained in such a string literal by writing that character twice, in succession. For example, 'What''s the time?' and "I said, ""Hello"".". However, a single-quote-character has no special meaning inside an expandable-string-literal, and a double-quote-character has no special meaning inside a verbatim-string-literal.

An expandable-string-literal and an expandable-here-string-literal may contain escaped-characters (§2.3.7). For example, when the following string literal is written to the pipeline, the result is as shown below:

"column1`tcolumn2`nsecond line, `"Hello`", ```Q`5`!"

column1<horizontal-tab>column2<new-line>
second line, "Hello", `Q5!

If an expandable-string-literal or expandable-here-string-literal contains the name of a variable, unless that name is preceded immediately by an escape character, it is replaced by the string representation of that variable's value (§6.7). This is known as variable substitution.

Note

If the variable name is part of some larger expression, only the variable name is replaced. For example, if $a is an array containing the elements 100 and 200, ">$a.Length<" results in >100 200.Length< while ">$($a.Length)<" results in >2<. See sub-expression expansion below.

For example, the source code

$count = 10
"The value of `$count is $count"

results in the expandable-string-literal

The value of $count is 10.

Consider the following:

$a = "red","blue"
"`$a[0] is $a[0], `$a[0] is $($a[0])" # second [0] is taken literally

The result is

$a[0] is red blue[0], $a[0] is red

expandable-string-literals and expandable-here-string-literals also support a kind of substitution called sub-expression expansion, by treating text of the form $( ... ) as a sub-expression (§7.1.6). Such text is replaced by the string representation of that expression's value (§6.8). Any white space used to separate tokens within sub-expression's statement-list is ignored as far as the result string's construction is concerned.

The examples,

$count = 10
"$count + 5 is $($count + 5)"
"$count + 5 is `$($count + 5)"
"$count + 5 is `$(`$count + 5)"

result in the following expandable-string-literals:

10 + 5 is 15
10 + 5 is $(10 + 5)
10 + 5 is $($count + 5)

The following source,

$i = 5; $j = 10; $k = 15
"`$i, `$j, and `$k have the values $( $i; $j; $k )"

results in the following expandable-string-literal:

$i, $j, and $k have the values 5 10 15

These four lines could have been written more succinctly as follows:

"`$i, `$j, and `$k have the values $(($i = 5); ($j = 10); ($k = 15))"

In the following example,

"First 10 squares: $(for ($i = 1; $i -le 10; ++$i) { "$i $($i*$i) " })"

the resulting expandable-string-literal is as follows:

First 10 squares: 1 1 2 4 3 9 4 16 5 25 6 36 7 49 8 64 9 81 10 100

As shown, a sub-expression can contain string literals having both variable substitution and sub-expression expansion. Note also that the inner expandable-string-literal's delimiters need not be escaped; the fact that they are inside a sub-expression means they cannot be terminators for the outer expandable-string-literal.

An expandable-string-literal or expandable-here-string-literal containing a variable substitution or sub-expression expansion is evaluated each time that literal is used; for example,

$a = 10
$s1 = "`$a = $($a; ++$a)"
"`$s1 = >$s1<"
$s2 = "`$a = $($a; ++$a)"
"`$s2 = >$s2<"
$s2 = $s1
"`$s2 = >$s2<"

which results in the following expandable-string-literals:

$s1 = >$a = 10<
$s2 = >$a = 11<
$s2 = >$a = 10<

The contents of a verbatim-here-string-literal are taken verbatim, including any leading or trailing white space within the body. As such, embedded single-quote-characters need not be doubled-up, and there is no substitution or expansion. For example,

$lit = @'
That's it!
2 * 3 = $(2*3)
'@

which results in the literal

That's it!
2 * 3 = $(2*3)

The contents of an expandable-here-string-literal are subject to substitution and expansion, but any leading or trailing white space within the body but outside any sub-expressions is taken verbatim, and embedded double-quote-characters need not be doubled-up. For example,

$lit = @"
That's it!
2 * 3 = $(2*3)
"@

which results in the following literal when expanded:

That's it!
2 * 3 = 6

For both verbatim-here-string-literals and expandable-here-string-literals, each line terminator within the body is represented in the resulting literal in an implementation-defined manner. For example, in

$lit = @"
abc
xyz
"@

the second line of the body has two leading spaces, and the first and second lines of the body have line terminators; however, the terminator for the second line of the body is not part of that body. The resulting literal is equivalent to: "abc<implementation-defined character sequence>xyz".

Note

To aid readability of source, long string literals can be broken across multiple source lines without line terminators being inserted. This is done by writing each part as a separate literal and concatenating the parts with the + operator (§7.7.2). This operator allows its operands to designate any of the four kinds of string literal.

Note

Although there is no such thing as a character literal per se, the same effect can be achieved by accessing the first character in a 1-character string, as follows: [char]"A" or "A"[0].

For both verbatim-here-string-literals and expandable-here-string-literals, each line terminator within the body is represented exactly as it was provided.

2.3.5.3 Null literal

See the automatic variable $null (§2.3.2.2).

2.3.5.4 Boolean literals

See the automatic variables $false and $true (§2.3.2.2).

2.3.5.5 Array literals

PowerShell allows expressions of array type (§9) to be written using the unary comma operator (§7.2.1), array-expression (§7.1.7), the binary comma operator (§7.3), and the range operator (§7.4).

2.3.5.6 Hash literals

PowerShell allows expressions of type Hashtable (§10) to be written using a hash-literal-expression (§7.1.9)

2.3.5.7 Type names

Syntax:

type-name:
    type-identifier
    type-name . type-identifier

type-identifier:
    type-characters

type-characters:
    type-character
    type-characters type-character

type-character:
    A Unicode character of classes Lu, Ll, Lt, Lm, Lo, or Nd
    _ (The underscore character U+005F)

array-type-name:
    type-name [

generic-type-name:
    type-name [

2.3.6 Operators and punctuators

Syntax:

operator-or-punctuator: one of
    {   }   [   ]   (   )   @(   @{   $(   ;
    &&  ||  &   |   ,   ++  ..   ::   .
    !   *   /   %   +   -   --
    -and   -band   -bnot   -bor
    -bxor   -not   -or     -xor
    assignment-operator
    merging-redirection-operator
    file-redirection-operator
    comparison-operator
    format-operator

assignment-operator: one of
    =  -=  +=  *=  /=  %=

file-redirection-operator: one of
    >  >>  2>  2>>  3>  3>>  4>  4>>
    5>  5>>  6>  6>>  *>  *>>  <

merging-redirection-operator: one of
    *>&1  2>&1  3>&1  4>&1  5>&1  6>&1
    *>&2  1>&2  3>&2  4>&2  5>&2  6>&2

comparison-operator: *one of
    -as           -ccontains      -ceq
    -cge          -cgt            -cle
    -clike        -clt            -cmatch
    -cne          -cnotcontains   -cnotlike
    -cnotmatch    -contains       -creplace
    -csplit       -eq             -ge
    -gt           -icontains      -ieq
    -ige          -igt            -ile
    -ilike        -ilt            -imatch
    -in           -ine            -inotcontains
    -inotlike     -inotmatch      -ireplace
    -is           -isnot          -isplit
    -join         -le             -like
    -lt           -match          -ne
    -notcontains  -notin         -notlike
    -notmatch     -replace       -shl*
    -shr          -split

format-operator:
    -f

Description:

&& and || are reserved for future use.

Note

Editor's Note: The pipeline chain operators && and || were introduced in PowerShell 7. See about_Pipeline_Chain_Operators.

The name following dash in an operator is reserved for that purpose only in an operator context.

An operator that begins with dash must not have any white space between that dash and the token that follows it.

2.3.7 Escaped characters

Syntax:

escaped-character:
    ` (The backtick character U+0060) followed by any Unicode character

Description:

An escaped character is a way to assign a special interpretation to a character by giving it a prefix Backtick character (U+0060). The following table shows the meaning of each escaped-character:

Escaped Character Meaning
`a Alert (U+0007)
`b Backspace (U+0008)
`f Form-feed (U+000C)
`n New-line (U+000A)
`r Carriage return (U+000D)
`t Horizontal tab (U+0009)
`v Vertical tab (U+0009)
`' Single quote (U+0027)
`" Double quote (U+0022)
`` Backtick (U+0060)
`0 NUL (U+0000)
`x If x is a character other than those characters shown above, the backtick character is ignored and x is taken literally.

The implication of the final entry in the table above is that spaces that would otherwise separate tokens can be made part of a token instead. For example, a file name containing a space can be written as Test` Data.txt (as well as 'Test Data.txt' or "Test Data.txt").