Updates from: 09/08/2021 03:15:35
Service Microsoft Docs article Related commit history on GitHub Change details
Microsoft.PowerShell.Core About Parsing (5.1) https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/5.1/Microsoft.PowerShell.Core/About/about_Parsing.md
---
-description: Describes how PowerShell parses commands.
-keywords: powershell,cmdlet
+description: Describes how PowerShell parses commands.
Locale: en-US Previously updated : 09/14/2020 Last updated : 09/07/2021 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_parsing?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 Title: about Parsing ---- # about_Parsing
-## SHORT DESCRIPTION
+## Short description
Describes how PowerShell parses commands.
-## LONG DESCRIPTION
+## Long description
When you enter a command at the command prompt, PowerShell breaks the command text into a series of segments called _tokens_ and then determines how to
expression mode and argument mode.
> execute intended cmdlet. > - `Get-Help` and `Get-Command` don't recognize verb-less names.
-### Expression mode
+## Expression mode
Expression mode is intended for combining expressions, required for value manipulation in a scripting language. Expressions are representations of values
in PowerShell syntax, and can be simple or composite, for example:
Literal expressions are direct representations of their values: ```powershell
-'hello', 32
+'hello'
+32
``` Variable expressions carry the value of the variable they reference: ```powershell
-$x, $script:path
+$x
+$script:path
``` Operators combine other expressions for evaluation: ```powershell-- 12, -not $Quiet, 3 + 7, $input.Length -gt 1
+-12
+-not $Quiet
+3 + 7
+$input.Length -gt 1
``` - _Character string literals_ must be contained in quotation marks.
Operators combine other expressions for evaluation:
pasting prefilled parameter sets) is forbidden and causes a parser error. - Anything else will be treated as a command to be invoked.
-### Argument mode
+## Argument mode
When parsing, PowerShell first looks to interpret input as an expression. But when a command invocation is encountered, parsing continues in argument mode.
+If you have arguments that contain spaces, such as paths, then you must
+enclose those argument values in quotes.
Argument mode is designed for parsing arguments and parameters for commands in a shell environment. All input is treated as an expandable string unless it uses one of the following syntaxes: -- Dollar sign (`$`) begins a variable reference (only if it is followed by a
- valid variable name, otherwise it is interpreted as part of the expandable
- string).
-- Quotation marks (`'` and `"`) begin string values-- Parentheses (`(` and `)`) demarcate new expressions.-- Subexpression operator (`$(`…`)`) demarcates embedded expressions.-- Braces (`{` and `}`) demarcate new script blocks.-- Initial at sign (`@`) begins expression syntaxes such as splatting (`@args`),
- arrays (`@(1,2,3)`) and hash tables (`@{a=1;b=2}`).
+- Dollar sign (`$`) followed by a variable name begins a variable reference,
+ otherwise it is interpreted as part of the expandable string. The variable
+ reference can include member access or indexing.
+ - Additional characters following simple variable references, such as
+ `$HOME`, are considered part of the same argument. Enclose the variable
+ name in braces (`{}`) to separate it from subsequent characters. For
+ example, `${HOME}`.
+ - When the variable reference include member access, the first of any
+ additional characters is considered the start of a new argument. For
+ example `$HOME.Length-more` results in two arguments: the value of
+ `$HOME.Length` and string literal `-more`.
+
+- Quotation marks (`'` and `"`) begin strings
+
+- Braces (`{}`) begin a new script blocks
+ - Commas (`,`) introduce lists passed as arrays, except when the command to be called is a native application, in which case they are interpreted as part of the expandable string. Initial, consecutive or trailing commas are not supported.
-Values of embedded expressions are converted to strings.
-
-The following table provides several examples of values processed in expression
-mode and argument mode and the evaluation of those values. We assume that the
-value of the variable `a` is `4`.
+- Parentheses (`()`) begin a new expression
+- Subexpression operator (`$()`) begins an embedded expression
+- Initial at sign (`@`) begins expression syntaxes such as splatting (`@args`),
+ arrays (`@(1,2,3)`), and hash table literals (`@{a=1;b=2}`).
+- `()`, `$()`, and `@()` at the start of a token create a new parsing context
+ that can contain expressions or nested commands.
+ - When followed by additional characters, the first additional character is
+ considered the start of a new, separate argument.
+ - When preceded by an unquoted literal `$()` works like an expandable string,
+ `()` starts a new argument that is an expression, and `@()` is taken as
+ literal `@` with `()` starting a new argument that is an expression.
+
+- Everything else is treated as an expandable string, except
+ metacharacters that still need escaping.
+ - The argument-mode metacharacters (characters with special syntactic
+ meaning) are: ``<space> ' " ` , ; ( ) { } | & < > @ #``. Of these, `< > @ #`
+ are only special at the start of a token.
+
+- The stop-parsing token (`--%`) changes the interpretation of all remaining
+ arguments. For more information, see the
+ [stop-parsing token](#the-stop-parsing-token) section below.
+
+### Examples
+
+The following table provides several examples of tokens processed in expression
+mode and argument mode and the evaluation of those tokens. For these examples,
+the value of the variable `$a` is `4`.
| Example | Mode | Result | | -------------------- | ---------- | ----------------- | | `2` | Expression | 2 (integer) | | `` `2`` | Expression | "2" (command) |
-| `echo 2` | Expression | 2 (integer) |
+| `Write-Output 2` | Expression | 2 (integer) |
| `2+2` | Expression | 4 (integer) |
-| `echo 2+2` | Argument | "2+2" (string) |
-| `echo(2+2)` | Expression | 4 (integer) |
+| `Write-Output 2+2` | Argument | "2+2" (string) |
+| `Write-Output(2+2)` | Expression | 4 (integer) |
| `$a` | Expression | 4 (integer) |
-| `echo $a` | Expression | 4 (integer) |
+| `Write-Output $a` | Expression | 4 (integer) |
| `$a+2` | Expression | 6 (integer) |
-| `echo $a+2` | Argument | 4+2 (string) |
+| `Write-Output $a+2` | Argument | "4+2" (string) |
| `$-` | Argument | "$-" (command) |
-| `echo $-` | Argument | "$-" (string) |
+| `Write-Output $-` | Argument | "$-" (string) |
| `a$a` | Expression | "a$a" (command) |
-| `echo a$a` | Argument | "a4" (string) |
+| `Write-Output a$a` | Argument | "a4" (string) |
| `a'$a'` | Expression | "a$a" (command) |
-| `echo a'$a'` | Argument | "a$a" (string) |
+| `Write-Output a'$a'` | Argument | "a$a" (string) |
| `a"$a"` | Expression | "a$a" (command) |
-| `echo a"$a"` | Argument | "a4" (string) |
+| `Write-Output a"$a"` | Argument | "a4" (string) |
| `a$(2)` | Expression | "a$(2)" (command) |
-| `echo a$(2)` | Argument | "a2" (string) |
-
-Every token can be interpreted as some kind of object type, such as Boolean or
-string. PowerShell attempts to determine the object type from the expression.
-The object type depends on the type of parameter a command expects and on
-whether PowerShell knows how to convert the argument to the correct type. The
-following table shows several examples of the types assigned to values returned
-by the expressions.
-
-| Example | Mode | Result |
-| ---------------------- | ---------- | --------------- |
-| `Write-Output !1` | argument | "!1" (string) |
-| `Write-Output (!1)` | expression | False (Boolean) |
-| `Write-Output (2)` | expression | 2 (integer) |
-| `Set-Variable AB A,B` | argument | 'A','B' (array) |
-| `CMD /CECHO A,B` | argument | 'A,B' (string) |
-| `CMD /CECHO $AB` | expression | 'A','B' (array) |
-| `CMD /CECHO :$AB` | argument | ':A B' (string) |
-
-The stop-parsing symbol (`--%`), introduced in PowerShell 3.0, directs
-PowerShell to refrain from interpreting input as PowerShell commands or
-expressions.
-
-When calling an executable program in PowerShell, place the stop-parsing symbol
-before the program arguments. This technique is much easier than using escape
-characters to prevent misinterpretation.
-
-When it encounters a stop-parsing symbol, PowerShell treats the remaining
-characters in the line as a literal. The only interpretation it performs is to
-substitute values for environment variables that use standard Windows notation,
-such as `%USERPROFILE%`.
+| `Write-Output a$(2)` | Argument | "a2" (string) |
-The stop-parsing symbol is effective only until the next newline or pipeline
-character. You cannot use a continuation character (`` ` ``) to extend its
-effect or use a command delimiter (`;`) to terminate its effect.
+Every token can be interpreted as some kind of object type, such as **Boolean**
+or **String**. PowerShell attempts to determine the object type from the
+expression. The object type depends on the type of parameter a command expects
+and on whether PowerShell knows how to convert the argument to the correct
+type. The following table shows several examples of the types assigned to
+values returned by the expressions.
+
+| Example | Mode | Result |
+| --------------------- | ---------- | --------------- |
+| `Write-Output !1` | argument | "!1" (string) |
+| `Write-Output (!1)` | expression | False (Boolean) |
+| `Write-Output (2)` | expression | 2 (integer) |
+| `Set-Variable AB A,B` | argument | 'A','B' (array) |
+| `CMD /CECHO A,B` | argument | 'A,B' (string) |
+| `CMD /CECHO $AB` | expression | 'A B' (array) |
+| `CMD /CECHO :$AB` | argument | ':A B' (string) |
+
+## Passing arguments to native commands
-For example, the following command calls the **Icacls** program.
+When running native commands from PowerShell, the arguments are first parsed
+by PowerShell. The parsed arguments are then joined into a single string with
+each parameter separated by a space.
+
+For example, the following command calls the `icacls.exe` program.
```powershell icacls X:\VMS /grant Dom\HVAdmin:(CI)(OI)F
prevent PowerShell from misinterpreting the parentheses.
icacls X:\VMS /grant Dom\HVAdmin:`(CI`)`(OI`)F ```
-Beginning in PowerShell 3.0, you can use the stop-parsing symbol.
+### The stop-parsing token
+
+Beginning in PowerShell 3.0, you can use the stop-parsing token (`--%`) to
+stop PowerShell from interpreting input asPowerShell commands or expressions.
+
+> [!NOTE]
+> The stop-parsing token is only intended for use on Windows platforms.
+
+When calling a native command, place the stop-parsing token before the program
+arguments. This technique is much easier than using escape characters to
+prevent misinterpretation.
+
+When it encounters a stop-parsing token, PowerShell treats the remaining
+characters in the line as a literal. The only interpretation it performs is to
+substitute values for environment variables that use standard Windows notation,
+such as `%USERPROFILE%`.
```powershell icacls X:\VMS --% /grant Dom\HVAdmin:(CI)(OI)F ```
-PowerShell sends the following command string to the **Icacls** program:
+PowerShell sends the following command string to the `icacls.exe` program:
`X:\VMS /grant Dom\HVAdmin:(CI)(OI)F`
-## SEE ALSO
+The stop-parsing token is effective only until the next newline or pipeline
+character. You cannot use a continuation character (`` ` ``) to extend its
+effect or use a command delimiter (`;`) to terminate its effect.
+
+Other than `%variable%` environment-variable references, you cannot embed any
+other dynamic elements in the command. Escaping a `%` character as `%%`, the
+way you can do inside batch files, is not supported. `%<name>%` tokens are
+invariably expanded. If `<name>` does not refer to a defined environment
+variable the token is passed through as-is.
+
+You cannot use stream redirection (like `>file.txt`) because they are passed
+verbatim as arguments to the target command.
+
+### Passing arguments that contain quote characters
+
+Some native commands expect arguments that contain quote characters. Normally,
+PowerShell's command line parsing removes the quote character you provided. The
+parsed arguments are then joined into a single string with each parameter
+separated by a space. This string is then assigned to the **Arguments**
+property of a `ProcessStartInfo` object. Quotes within the string must be
+escaped using extra quotes or backslash (`\`) characters.
+
+> [!NOTE]
+> The backslash (`\`) character is not recognized as an escape character by
+> PowerShell. It is the escape character used by the underlying API for
+> `ProcessStartInfo.Arguments`.
+
+For more information about the escape requirements, see the documentation for
+[ProcessStartInfo.Arguments](/dotnet/api/system.diagnostics.processstartinfo.arguments).
+
+The following examples using the `TestExe.exe` tool. This tool is used by the
+Pester tests in the PowerShell source repo. The goal of these examples is to
+pass the directory path `"C:\Program Files (x86)\Microsoft\"` to a native
+command so that it received the path as a quoted string.
+
+The **echoargs** parameter of `TestExe` displays the values received as
+arguments to the executable. You can use this tool to verify that you have
+properly escaped the characters in your arguments.
+
+```powershell
+TestExe -echoargs """""${env:ProgramFiles(x86)}\Microsoft\\"""""
+TestExe -echoargs """""C:\Program Files (x86)\Microsoft\\"""""
+TestExe -echoargs --% ""\""C:\Program Files (x86)\Microsoft\\""
+TestExe -echoargs --% """C:\Program Files (x86)\Microsoft\\""
+TestExe -echoargs --% """%ProgramFiles(x86)%\Microsoft\\""
+```
+
+The output is the same for all examples:
+
+```Output
+Arg 0 is <"C:\Program Files (x86)\Microsoft\">
+```
+
+You can build `TestExe` from the source code. See
+[TestExe](https://github.com/PowerShell/PowerShell/blob/master/test/tools/TestExe/TestExe.cs).
+
+## See also
[about_Command_Syntax](about_Command_Syntax.md)
Microsoft.PowerShell.Core About Quoting Rules (5.1) https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/5.1/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md
--- description: Describes rules for using single and double quotation marks in PowerShell. Locale: en-US Previously updated : 12/14/2020 Last updated : 09/07/2021 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_quoting_rules?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 Title: about Quoting Rules
command that are run on the remote computer. In a remote session, quotation
marks also determine whether the variables in a command are interpreted first on the local computer or on the remote computer.
-## Single and double-quoted strings
+## Double-quoted strings
A string enclosed in double quotation marks is an _expandable_ string. Variable names preceded by a dollar sign (`$`) are replaced with the variable's value
The output of this command is:
The value of 5 is 5. ```
-A string enclosed in single-quotation marks is a _verbatim_ string. The string
-is passed to the command exactly as you type it. No substitution is performed.
+Only simple variable references can be directly embedded in an expandable
+string. Variables references using array indexing or member access must be
+enclosed in a subexpression. For example:
+
+```powershell
+"PS version: $($PSVersionTable.PSVersion)"
+```
+
+```Output
+PS version: 5.1.19041.1151
+```
+
+To separate a variable name from subsequent characters in the string,
+enclose it in braces (`{}`). This is especially important if the variable name
+is followed by a colon (`:`). PowerShell considers everything between the `$`
+and the `:` a scope specifier, typically causing the interpretation to fail.
+For example, `"$HOME: where the heart is."` throws an error, but
+`"${HOME}: where the heart is."` works as intended.
+
+To prevent the substitution of a variable value in a double-quoted string, use
+the backtick character (`` ` ``), which is the PowerShell escape character.
+
+In the following example, the backtick character that precedes the first `$i`
+variable prevents PowerShell from replacing the variable name with its value.
For example: ```powershell $i = 5
-'The value of $i is $i.'
+"The value of `$i is $i."
``` The output of this command is: ```Output
-The value $i is $i.
+The value $i is 5.
```
-Similarly, expressions in single-quoted strings are not evaluated. They are
-interpreted as literals. For example:
+## Single-quoted strings
+
+A string enclosed in single-quotation marks is a _verbatim_ string. The string
+is passed to the command exactly as you type it. No substitution is performed.
+For example:
```powershell
-'The value of $(2+3) is 5.'
+$i = 5
+'The value of $i is $i.'
``` The output of this command is: ```Output
-The value of $(2+3) is 5.
+The value $i is $i.
```
-To prevent the substitution of a variable value in a double-quoted string, use
-the backtick character (`` ` ``)(ASCII 96), which is the PowerShell escape
-character.
-
-In the following example, the backtick character that precedes the first `$i`
-variable prevents PowerShell from replacing the variable name with its value.
-For example:
+Similarly, expressions in single-quoted strings are not evaluated. They are
+interpreted as literals. For example:
```powershell
-$i = 5
-"The value of `$i is $i."
+'The value of $(2+3) is 5.'
``` The output of this command is: ```Output
-The value $i is 5.
+The value of $(2+3) is 5.
```
+## Including quote characters in a string
+ To make double-quotation marks appear in a string, enclose the entire string in single quotation marks. For example:
backtick character. This prevents PowerShell from interpreting the quotation
mark as a string delimiter. For example: ```powershell
-PS> "Use a quotation mark (`") to begin a string."
-Use a quotation mark (") to begin a string.
-PS> 'Use a quotation mark (`") to begin a string.'
-Use a quotation mark (`") to begin a string.
+"Use a quotation mark (`") to begin a string."
+'Use a quotation mark (`") to begin a string.'
```
-Because the contents of single-quoted strings are interpreted literally,
-the backtick character is treated as a literal character and displayed in the
+Because the contents of single-quoted strings are interpreted literally, the
+backtick character is treated as a literal character and displayed in the
output.
+```Output
+Use a quotation mark (") to begin a string.
+Use a quotation mark (`") to begin a string.
+```
+ ## Here-strings The quotation rules for here-strings are slightly different.
Here-strings are also a convenient format for input to the
`ConvertFrom-StringData` cmdlet, which converts here-strings to hash tables. For more information, see `ConvertFrom-StringData`.
+## Interpretation of expandable strings
+
+Expanded strings don't necessarily look the same as the default output that you
+see in the console.
+
+Collections, including arrays, are converted to strings by placing a single
+space between the string representations of the elements. A different separator
+can be specified by setting preference variable `$OFS`. For more information,
+see the [`$OFS` preference variable](about_preference_variables.md#ofs).
+
+Instances of any other type are converted to strings by calling the
+`ToString()` method which may not give a meaningful representation. For
+example:
+
+```powershell
+"hashtable: $(@{ key = 'value' })"
+```
+
+```Output
+hashtable: System.Collections.Hashtable
+```
+
+To get the same output as in the console, use a subexpression in which you pipe
+to `Out-String`. Apply the `Trim()` method if you want to remove any leading
+and trailing empty lines.
+
+```powershell
+"hashtable:`n$((@{ key = 'value' } | Out-String).Trim())"
+```
+
+```Output
+hashtable:
+Name Value
+---- -----
+key value
+```
+ ## See also [about_Special_Characters](about_Special_Characters.md)
Microsoft.PowerShell.Core About Scripts (5.1) https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/5.1/Microsoft.PowerShell.Core/About/about_Scripts.md
PowerShell has many useful features that you can use in scripts.
- `#Requires` - You can use a `#Requires` statement to prevent a script from running without specified modules or snap-ins and a specified version of
- PowerShell. For more information, see about_Requires.
+ PowerShell. For more information, see [about_Requires](about_Requires.md).
- `$PSCommandPath` - Contains the full path and name of the script that is being run. This parameter is valid in all scripts. This automatic variable is
Microsoft.PowerShell.Core About Parsing (7.0) https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.0/Microsoft.PowerShell.Core/About/about_Parsing.md
---
-description: Describes how PowerShell parses commands.
-keywords: powershell,cmdlet
+description: Describes how PowerShell parses commands.
Locale: en-US Previously updated : 09/14/2020 Last updated : 09/07/2021 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_parsing?view=powershell-7&WT.mc_id=ps-gethelp schema: 2.0.0 Title: about Parsing --- # about_Parsing
-## SHORT DESCRIPTION
+## Short description
Describes how PowerShell parses commands.
-## LONG DESCRIPTION
+## Long description
When you enter a command at the command prompt, PowerShell breaks the command text into a series of segments called _tokens_ and then determines how to
expression mode and argument mode.
> execute intended cmdlet. > - `Get-Help` and `Get-Command` don't recognize verb-less names.
-### Expression mode
+## Expression mode
Expression mode is intended for combining expressions, required for value manipulation in a scripting language. Expressions are representations of values in PowerShell syntax, and can be simple or composite, for example:
-Literal expressions are direct representations of their values:
+Literal expressions are direct representations of their values:
```powershell
-'hello', 32
+'hello'
+32
```
-Variable expressions carry the value of the variable they reference:
+Variable expressions carry the value of the variable they reference:
```powershell
-$x, $script:path
+$x
+$script:path
```
-Operators combine other expressions for evaluation:
+
+Operators combine other expressions for evaluation:
```powershell-- 12, -not $Quiet, 3 + 7, $input.Length -gt 1
+-12
+-not $Quiet
+3 + 7
+$input.Length -gt 1
``` - _Character string literals_ must be contained in quotation marks.
Operators combine other expressions for evaluation:
pasting prefilled parameter sets) is forbidden and causes a parser error. - Anything else will be treated as a command to be invoked.
-### Argument mode
+## Argument mode
When parsing, PowerShell first looks to interpret input as an expression. But when a command invocation is encountered, parsing continues in argument mode.
+If you have arguments that contain spaces, such as paths, then you must
+enclose those argument values in quotes.
Argument mode is designed for parsing arguments and parameters for commands in
-in a shell environment. All input is treated as an expandable string
-unless it uses one of the following syntaxes:
--- Dollar sign (`$`) begins a variable reference (only if it is followed by a
- valid variable name, otherwise it is interpreted as part of the expandable
- string).
-- Quotation marks (`'` and `"`) begin string values-- Parentheses (`(` and `)`) demarcate new expressions.-- Subexpression operator (`$(`…`)`) demarcates embedded expressions.-- Braces (`{` and `}`) demarcate new script blocks.-- Initial at sign (`@`) begins expression syntaxes such as splatting (`@args`),
- arrays (`@(1,2,3)`) and hash tables (`@{a=1;b=2}`).
+a shell environment. All input is treated as an expandable string unless it
+uses one of the following syntaxes:
+
+- Dollar sign (`$`) followed by a variable name begins a variable reference,
+ otherwise it is interpreted as part of the expandable string. The variable
+ reference can include member access or indexing.
+ - Additional characters following simple variable references, such as
+ `$HOME`, are considered part of the same argument. Enclose the variable
+ name in braces (`{}`) to separate it from subsequent characters. For
+ example, `${HOME}`.
+ - When the variable reference include member access, the first of any
+ additional characters is considered the start of a new argument. For
+ example `$HOME.Length-more` results in two arguments: the value of
+ `$HOME.Length` and string literal `-more`.
+
+- Quotation marks (`'` and `"`) begin strings
+
+- Braces (`{}`) begin a new script blocks
+ - Commas (`,`) introduce lists passed as arrays, except when the command to be called is a native application, in which case they are interpreted as part of the expandable string. Initial, consecutive or trailing commas are not supported.
-Values of embedded expressions are converted to strings.
-
-The following table provides several examples of values processed in expression
-mode and argument mode and the evaluation of those values. We assume that the
-value of the variable `a` is `4`.
+- Parentheses (`()`) begin a new expression
+- Subexpression operator (`$()`) begins an embedded expression
+- Initial at sign (`@`) begins expression syntaxes such as splatting (`@args`),
+ arrays (`@(1,2,3)`), and hash table literals (`@{a=1;b=2}`).
+- `()`, `$()`, and `@()` at the start of a token create a new parsing context
+ that can contain expressions or nested commands.
+ - When followed by additional characters, the first additional character is
+ considered the start of a new, separate argument.
+ - When preceded by an unquoted literal `$()` works like an expandable string,
+ `()` starts a new argument that is an expression, and `@()` is taken as
+ literal `@` with `()` starting a new argument that is an expression.
+
+- Everything else is treated as an expandable string, except
+ metacharacters that still need escaping.
+ - The argument-mode metacharacters (characters with special syntactic
+ meaning) are: ``<space> ' " ` , ; ( ) { } | & < > @ #``. Of these, `< > @ #`
+ are only special at the start of a token.
+
+- The stop-parsing token (`--%`) changes the interpretation of all remaining
+ arguments. For more information, see the
+ [stop-parsing token](#the-stop-parsing-token) section below.
+
+### Examples
+
+The following table provides several examples of tokens processed in expression
+mode and argument mode and the evaluation of those tokens. For these examples,
+the value of the variable `$a` is `4`.
| Example | Mode | Result | | -------------------- | ---------- | ----------------- | | `2` | Expression | 2 (integer) | | `` `2`` | Expression | "2" (command) |
-| `echo 2` | Expression | 2 (integer) |
+| `Write-Output 2` | Expression | 2 (integer) |
| `2+2` | Expression | 4 (integer) |
-| `echo 2+2` | Argument | "2+2" (string) |
-| `echo(2+2)` | Expression | 4 (integer) |
+| `Write-Output 2+2` | Argument | "2+2" (string) |
+| `Write-Output(2+2)` | Expression | 4 (integer) |
| `$a` | Expression | 4 (integer) |
-| `echo $a` | Expression | 4 (integer) |
+| `Write-Output $a` | Expression | 4 (integer) |
| `$a+2` | Expression | 6 (integer) |
-| `echo $a+2` | Argument | 4+2 (string) |
+| `Write-Output $a+2` | Argument | "4+2" (string) |
| `$-` | Argument | "$-" (command) |
-| `echo $-` | Argument | "$-" (string) |
+| `Write-Output $-` | Argument | "$-" (string) |
| `a$a` | Expression | "a$a" (command) |
-| `echo a$a` | Argument | "a4" (string) |
+| `Write-Output a$a` | Argument | "a4" (string) |
| `a'$a'` | Expression | "a$a" (command) |
-| `echo a'$a'` | Argument | "a$a" (string) |
+| `Write-Output a'$a'` | Argument | "a$a" (string) |
| `a"$a"` | Expression | "a$a" (command) |
-| `echo a"$a"` | Argument | "a4" (string) |
+| `Write-Output a"$a"` | Argument | "a4" (string) |
| `a$(2)` | Expression | "a$(2)" (command) |
-| `echo a$(2)` | Argument | "a2" (string) |
-
-Every token can be interpreted as some kind of object type, such as Boolean or
-string. PowerShell attempts to determine the object type from the expression.
-The object type depends on the type of parameter a command expects and on
-whether PowerShell knows how to convert the argument to the correct type. The
-following table shows several examples of the types assigned to values returned
-by the expressions.
-
-| Example | Mode | Result |
-| ---------------------- | ---------- | --------------- |
-| `Write-Output !1` | argument | "!1" (string) |
-| `Write-Output (!1)` | expression | False (Boolean) |
-| `Write-Output (2)` | expression | 2 (integer) |
-| `Set-Variable AB A,B` | argument | 'A','B' (array) |
-| `CMD /CECHO A,B` | argument | 'A,B' (string) |
-| `CMD /CECHO $AB` | expression | 'A','B' (array) |
-| `CMD /CECHO :$AB` | argument | ':A B' (string) |
-
-The stop-parsing symbol (`--%`), introduced in PowerShell 3.0, directs
-PowerShell to refrain from interpreting input as PowerShell commands or
-expressions.
-
-When calling an executable program in PowerShell, place the stop-parsing symbol
-before the program arguments. This technique is much easier than using escape
-characters to prevent misinterpretation.
-
-When it encounters a stop-parsing symbol, PowerShell treats the remaining
-characters in the line as a literal. The only interpretation it performs is to
-substitute values for environment variables that use standard Windows notation,
-such as `%USERPROFILE%`.
+| `Write-Output a$(2)` | Argument | "a2" (string) |
-The stop-parsing symbol is effective only until the next newline or pipeline
-character. You cannot use a continuation character (`` ` ``) to extend its
-effect or use a command delimiter (`;`) to terminate its effect.
+Every token can be interpreted as some kind of object type, such as **Boolean**
+or **String**. PowerShell attempts to determine the object type from the
+expression. The object type depends on the type of parameter a command expects
+and on whether PowerShell knows how to convert the argument to the correct
+type. The following table shows several examples of the types assigned to
+values returned by the expressions.
+
+| Example | Mode | Result |
+| --------------------- | ---------- | --------------- |
+| `Write-Output !1` | argument | "!1" (string) |
+| `Write-Output (!1)` | expression | False (Boolean) |
+| `Write-Output (2)` | expression | 2 (integer) |
+| `Set-Variable AB A,B` | argument | 'A','B' (array) |
+| `CMD /CECHO A,B` | argument | 'A,B' (string) |
+| `CMD /CECHO $AB` | expression | 'A B' (array) |
+| `CMD /CECHO :$AB` | argument | ':A B' (string) |
+
+## Passing arguments to native commands
+
+When running native commands from PowerShell, the arguments are first parsed
+by PowerShell. The parsed arguments are then joined into a single string with
+each parameter separated by a space.
-For example, the following command calls the **Icacls** program.
+For example, the following command calls the `icacls.exe` program.
```powershell icacls X:\VMS /grant Dom\HVAdmin:(CI)(OI)F
prevent PowerShell from misinterpreting the parentheses.
icacls X:\VMS /grant Dom\HVAdmin:`(CI`)`(OI`)F ```
-Beginning in PowerShell 3.0, you can use the stop-parsing symbol.
+### The stop-parsing token
+
+Beginning in PowerShell 3.0, you can use the stop-parsing token (`--%`) to
+stop PowerShell from interpreting input asPowerShell commands or expressions.
+
+> [!NOTE]
+> The stop-parsing token is only intended for use on Windows platforms.
+
+When calling a native command, place the stop-parsing token before the program
+arguments. This technique is much easier than using escape characters to
+prevent misinterpretation.
+
+When it encounters a stop-parsing token, PowerShell treats the remaining
+characters in the line as a literal. The only interpretation it performs is to
+substitute values for environment variables that use standard Windows notation,
+such as `%USERPROFILE%`.
```powershell icacls X:\VMS --% /grant Dom\HVAdmin:(CI)(OI)F ```
-PowerShell sends the following command string to the **Icacls** program:
+PowerShell sends the following command string to the `icacls.exe` program:
`X:\VMS /grant Dom\HVAdmin:(CI)(OI)F`
+The stop-parsing token is effective only until the next newline or pipeline
+character. You cannot use a continuation character (`` ` ``) to extend its
+effect or use a command delimiter (`;`) to terminate its effect.
+
+Other than `%variable%` environment-variable references, you cannot embed any
+other dynamic elements in the command. Escaping a `%` character as `%%`, the
+way you can do inside batch files, is not supported. `%<name>%` tokens are
+invariably expanded. If `<name>` does not refer to a defined environment
+variable the token is passed through as-is.
+
+You cannot use stream redirection (like `>file.txt`) because they are passed
+verbatim as arguments to the target command.
+
+### Passing arguments that contain quote characters
+
+Some native commands expect arguments that contain quote characters. Normally,
+PowerShell's command line parsing removes the quote character you provided. The
+parsed arguments are then joined into a single string with each parameter
+separated by a space. This string is then assigned to the **Arguments**
+property of a `ProcessStartInfo` object. Quotes within the string must be
+escaped using extra quotes or backslash (`\`) characters.
+ > [!NOTE]
-> The stop-parsing symbol only intended for use on Windows platforms.
+> The backslash (`\`) character is not recognized as an escape character by
+> PowerShell. It is the escape character used by the underlying API for
+> `ProcessStartInfo.Arguments`.
+
+For more information about the escape requirements, see the documentation for
+[ProcessStartInfo.Arguments](/dotnet/api/system.diagnostics.processstartinfo.arguments).
+
+The following examples using the `TestExe.exe` tool. This tool is used by the
+Pester tests in the PowerShell source repo. The goal of these examples is to
+pass the directory path `"C:\Program Files (x86)\Microsoft\"` to a native
+command so that it received the path as a quoted string.
+
+The **echoargs** parameter of `TestExe` displays the values received as
+arguments to the executable. You can use this tool to verify that you have
+properly escaped the characters in your arguments.
+
+```powershell
+TestExe -echoargs """""${env:ProgramFiles(x86)}\Microsoft\\"""""
+TestExe -echoargs """""C:\Program Files (x86)\Microsoft\\"""""
+TestExe -echoargs "\""C:\Program Files (x86)\Microsoft\\"""
+TestExe -echoargs --% "\"C:\Program Files (x86)\Microsoft\\"
+TestExe -echoargs --% """C:\Program Files (x86)\Microsoft\\""
+TestExe -echoargs --% """%ProgramFiles(x86)%\Microsoft\\""
+```
+
+The output is the same for all examples:
+
+```Output
+Arg 0 is <"C:\Program Files (x86)\Microsoft\">
+```
+
+You can build `TestExe` from the source code. See
+[TestExe](https://github.com/PowerShell/PowerShell/blob/master/test/tools/TestExe/TestExe.cs).
-## SEE ALSO
+## See also
[about_Command_Syntax](about_Command_Syntax.md)
Microsoft.PowerShell.Core About Quoting Rules (7.0) https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.0/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md
--- description: Describes rules for using single and double quotation marks in PowerShell. Locale: en-US Previously updated : 12/14/2020 Last updated : 09/07/2021 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_quoting_rules?view=powershell-7&WT.mc_id=ps-gethelp schema: 2.0.0 Title: about Quoting Rules
command that are run on the remote computer. In a remote session, quotation
marks also determine whether the variables in a command are interpreted first on the local computer or on the remote computer.
-## Single and double-quoted strings
+## Double-quoted strings
A string enclosed in double quotation marks is an _expandable_ string. Variable names preceded by a dollar sign (`$`) are replaced with the variable's value
The output of this command is:
The value of 5 is 5. ```
-A string enclosed in single-quotation marks is a _verbatim_ string. The string
-is passed to the command exactly as you type it. No substitution is performed.
+Only simple variable references can be directly embedded in an expandable
+string. Variables references using array indexing or member access must be
+enclosed in a subexpression. For example:
+
+```powershell
+"PS version: $($PSVersionTable.PSVersion)"
+```
+
+```Output
+PS version: 7.0.7
+```
+
+To separate a variable name from subsequent characters in the string,
+enclose it in braces (`{}`). This is especially important if the variable name
+is followed by a colon (`:`). PowerShell considers everything between the `$`
+and the `:` a scope specifier, typically causing the interpretation to fail.
+For example, `"$HOME: where the heart is."` throws an error, but
+`"${HOME}: where the heart is."` works as intended.
+
+To prevent the substitution of a variable value in a double-quoted string, use
+the backtick character (`` ` ``), which is the PowerShell escape character.
+
+In the following example, the backtick character that precedes the first `$i`
+variable prevents PowerShell from replacing the variable name with its value.
For example: ```powershell $i = 5
-'The value of $i is $i.'
+"The value of `$i is $i."
``` The output of this command is: ```Output
-The value $i is $i.
+The value $i is 5.
```
-Similarly, expressions in single-quoted strings are not evaluated. They are
-interpreted as literals. For example:
+## Single-quoted strings
+
+A string enclosed in single-quotation marks is a _verbatim_ string. The string
+is passed to the command exactly as you type it. No substitution is performed.
+For example:
```powershell
-'The value of $(2+3) is 5.'
+$i = 5
+'The value of $i is $i.'
``` The output of this command is: ```Output
-The value of $(2+3) is 5.
+The value $i is $i.
```
-To prevent the substitution of a variable value in a double-quoted string, use
-the backtick character (`` ` ``)(ASCII 96), which is the PowerShell escape
-character.
-
-In the following example, the backtick character that precedes the first `$i`
-variable prevents PowerShell from replacing the variable name with its value.
-For example:
+Similarly, expressions in single-quoted strings are not evaluated. They are
+interpreted as literals. For example:
```powershell
-$i = 5
-"The value of `$i is $i."
+'The value of $(2+3) is 5.'
``` The output of this command is: ```Output
-The value $i is 5.
+The value of $(2+3) is 5.
```
+## Including quote characters in a string
+ To make double-quotation marks appear in a string, enclose the entire string in single quotation marks. For example:
backtick character. This prevents PowerShell from interpreting the quotation
mark as a string delimiter. For example: ```powershell
-PS> "Use a quotation mark (`") to begin a string."
-Use a quotation mark (") to begin a string.
-PS> 'Use a quotation mark (`") to begin a string.'
-Use a quotation mark (`") to begin a string.
+"Use a quotation mark (`") to begin a string."
+'Use a quotation mark (`") to begin a string.'
```
-Because the contents of single-quoted strings are interpreted literally,
-the backtick character is treated as a literal character and displayed in the
+Because the contents of single-quoted strings are interpreted literally, the
+backtick character is treated as a literal character and displayed in the
output.
+```Output
+Use a quotation mark (") to begin a string.
+Use a quotation mark (`") to begin a string.
+```
+ ## Here-strings The quotation rules for here-strings are slightly different.
Here-strings are also a convenient format for input to the
`ConvertFrom-StringData` cmdlet, which converts here-strings to hash tables. For more information, see `ConvertFrom-StringData`.
+## Interpretation of expandable strings
+
+Expanded strings don't necessarily look the same as the default output that you
+see in the console.
+
+Collections, including arrays, are converted to strings by placing a single
+space between the string representations of the elements. A different separator
+can be specified by setting preference variable `$OFS`. For more information,
+see the [`$OFS` preference variable](about_preference_variables.md#ofs).
+
+Instances of any other type are converted to strings by calling the
+`ToString()` method which may not give a meaningful representation. For
+example:
+
+```powershell
+"hashtable: $(@{ key = 'value' })"
+```
+
+```Output
+hashtable: System.Collections.Hashtable
+```
+
+To get the same output as in the console, use a subexpression in which you pipe
+to `Out-String`. Apply the `Trim()` method if you want to remove any leading
+and trailing empty lines.
+
+```powershell
+"hashtable:`n$((@{ key = 'value' } | Out-String).Trim())"
+```
+
+```Output
+hashtable:
+Name Value
+---- -----
+key value
+```
+ ## See also [about_Special_Characters](about_Special_Characters.md)
Microsoft.PowerShell.Core About Scripts (7.0) https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.0/Microsoft.PowerShell.Core/About/about_Scripts.md
PowerShell has many useful features that you can use in scripts.
- `#Requires` - You can use a `#Requires` statement to prevent a script from running without specified modules or snap-ins and a specified version of
- PowerShell. For more information, see about_Requires.
+ PowerShell. For more information, see [about_Requires](about_Requires.md).
- `$PSCommandPath` - Contains the full path and name of the script that is being run. This parameter is valid in all scripts. This automatic variable is
Microsoft.PowerShell.Core About Parsing (7.1) https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.1/Microsoft.PowerShell.Core/About/about_Parsing.md
---
-description: Describes how PowerShell parses commands.
-keywords: powershell,cmdlet
+description: Describes how PowerShell parses commands.
Locale: en-US Previously updated : 09/14/2020 Last updated : 09/07/2021 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_parsing?view=powershell-7.1&WT.mc_id=ps-gethelp schema: 2.0.0 Title: about Parsing --- # about_Parsing
-## SHORT DESCRIPTION
+## Short description
+ Describes how PowerShell parses commands.
-## LONG DESCRIPTION
+## Long description
When you enter a command at the command prompt, PowerShell breaks the command text into a series of segments called _tokens_ and then determines how to
expression mode and argument mode.
> execute intended cmdlet. > - `Get-Help` and `Get-Command` don't recognize verb-less names.
-### Expression mode
+## Expression mode
Expression mode is intended for combining expressions, required for value manipulation in a scripting language. Expressions are representations of values in PowerShell syntax, and can be simple or composite, for example:
-Literal expressions are direct representations of their values:
+Literal expressions are direct representations of their values:
```powershell
-'hello', 32
+'hello'
+32
```
-Variable expressions carry the value of the variable they reference:
+Variable expressions carry the value of the variable they reference:
```powershell
-$x, $script:path
+$x
+$script:path
```
-Operators combine other expressions for evaluation:
+
+Operators combine other expressions for evaluation:
```powershell-- 12, -not $Quiet, 3 + 7, $input.Length -gt 1
+-12
+-not $Quiet
+3 + 7
+$input.Length -gt 1
``` - _Character string literals_ must be contained in quotation marks.
Operators combine other expressions for evaluation:
pasting prefilled parameter sets) is forbidden and causes a parser error. - Anything else will be treated as a command to be invoked.
-### Argument mode
+## Argument mode
When parsing, PowerShell first looks to interpret input as an expression. But when a command invocation is encountered, parsing continues in argument mode.
+If you have arguments that contain spaces, such as paths, then you must
+enclose those argument values in quotes.
Argument mode is designed for parsing arguments and parameters for commands in a shell environment. All input is treated as an expandable string unless it uses one of the following syntaxes: -- Dollar sign (`$`) begins a variable reference (only if it is followed by a
- valid variable name, otherwise it is interpreted as part of the expandable
- string).
-- Quotation marks (`'` and `"`) begin string values-- Parentheses (`(` and `)`) demarcate new expressions.-- Subexpression operator (`$(`…`)`) demarcates embedded expressions.-- Braces (`{` and `}`) demarcate new script blocks.-- Initial at sign (`@`) begins expression syntaxes such as splatting (`@args`),
- arrays (`@(1,2,3)`) and hash tables (`@{a=1;b=2}`).
+- Dollar sign (`$`) followed by a variable name begins a variable reference,
+ otherwise it is interpreted as part of the expandable string. The variable
+ reference can include member access or indexing.
+ - Additional characters following simple variable references, such as
+ `$HOME`, are considered part of the same argument. Enclose the variable
+ name in braces (`{}`) to separate it from subsequent characters. For
+ example, `${HOME}`.
+ - When the variable reference include member access, the first of any
+ additional characters is considered the start of a new argument. For
+ example `$HOME.Length-more` results in two arguments: the value of
+ `$HOME.Length` and string literal `-more`.
+
+- Quotation marks (`'` and `"`) begin strings
+
+- Braces (`{}`) begin a new script blocks
+ - Commas (`,`) introduce lists passed as arrays, except when the command to be called is a native application, in which case they are interpreted as part of the expandable string. Initial, consecutive or trailing commas are not supported.
-<!--
-01234567890123456789012345678901234567890123456789012345678901234567890123456789
-Values of embedded expressions are converted to strings.
-
-The following table provides several examples of values processed in expression
-mode and argument mode and the evaluation of those values. We assume that the
-value of the variable `a` is `4`.
+- Parentheses (`()`) begin a new expression
+- Subexpression operator (`$()`) begins an embedded expression
+- Initial at sign (`@`) begins expression syntaxes such as splatting (`@args`),
+ arrays (`@(1,2,3)`), and hash table literals (`@{a=1;b=2}`).
+- `()`, `$()`, and `@()` at the start of a token create a new parsing context
+ that can contain expressions or nested commands.
+ - When followed by additional characters, the first additional character is
+ considered the start of a new, separate argument.
+ - When preceded by an unquoted literal `$()` works like an expandable string,
+ `()` starts a new argument that is an expression, and `@()` is taken as
+ literal `@` with `()` starting a new argument that is an expression.
+
+- Everything else is treated as an expandable string, except
+ metacharacters that still need escaping.
+ - The argument-mode metacharacters (characters with special syntactic
+ meaning) are: ``<space> ' " ` , ; ( ) { } | & < > @ #``. Of these, `< > @ #`
+ are only special at the start of a token.
+
+- The stop-parsing token (`--%`) changes the interpretation of all remaining
+ arguments. For more information, see the
+ [stop-parsing token](#the-stop-parsing-token) section below.
+
+### Examples
+
+The following table provides several examples of tokens processed in expression
+mode and argument mode and the evaluation of those tokens. For these examples,
+the value of the variable `$a` is `4`.
| Example | Mode | Result | | -------------------- | ---------- | ----------------- | | `2` | Expression | 2 (integer) | | `` `2`` | Expression | "2" (command) |
-| `echo 2` | Expression | 2 (integer) |
+| `Write-Output 2` | Expression | 2 (integer) |
| `2+2` | Expression | 4 (integer) |
-| `echo 2+2` | Argument | "2+2" (string) |
-| `echo(2+2)` | Expression | 4 (integer) |
+| `Write-Output 2+2` | Argument | "2+2" (string) |
+| `Write-Output(2+2)` | Expression | 4 (integer) |
| `$a` | Expression | 4 (integer) |
-| `echo $a` | Expression | 4 (integer) |
+| `Write-Output $a` | Expression | 4 (integer) |
| `$a+2` | Expression | 6 (integer) |
-| `echo $a+2` | Argument | 4+2 (string) |
+| `Write-Output $a+2` | Argument | "4+2" (string) |
| `$-` | Argument | "$-" (command) |
-| `echo $-` | Argument | "$-" (string) |
+| `Write-Output $-` | Argument | "$-" (string) |
| `a$a` | Expression | "a$a" (command) |
-| `echo a$a` | Argument | "a4" (string) |
+| `Write-Output a$a` | Argument | "a4" (string) |
| `a'$a'` | Expression | "a$a" (command) |
-| `echo a'$a'` | Argument | "a$a" (string) |
+| `Write-Output a'$a'` | Argument | "a$a" (string) |
| `a"$a"` | Expression | "a$a" (command) |
-| `echo a"$a"` | Argument | "a4" (string) |
+| `Write-Output a"$a"` | Argument | "a4" (string) |
| `a$(2)` | Expression | "a$(2)" (command) |
-| `echo a$(2)` | Argument | "a2" (string) |
-
-Every token can be interpreted as some kind of object type, such as Boolean or
-string. PowerShell attempts to determine the object type from the expression.
-The object type depends on the type of parameter a command expects and on
-whether PowerShell knows how to convert the argument to the correct type. The
-following table shows several examples of the types assigned to values returned
-by the expressions.
-
-| Example | Mode | Result |
-| ---------------------- | ---------- | --------------- |
-| `Write-Output !1` | argument | "!1" (string) |
-| `Write-Output (!1)` | expression | False (Boolean) |
-| `Write-Output (2)` | expression | 2 (integer) |
-| `Set-Variable AB A,B` | argument | 'A','B' (array) |
-| `CMD /CECHO A,B` | argument | 'A,B' (string) |
-| `CMD /CECHO $AB` | expression | 'A','B' (array) |
-| `CMD /CECHO :$AB` | argument | ':A B' (string) |
-
-The stop-parsing symbol (`--%`), introduced in PowerShell 3.0, directs
-PowerShell to refrain from interpreting input as PowerShell commands or
-expressions.
-
-When calling an executable program in PowerShell, place the stop-parsing symbol
-before the program arguments. This technique is much easier than using escape
-characters to prevent misinterpretation.
-
-When it encounters a stop-parsing symbol, PowerShell treats the remaining
-characters in the line as a literal. The only interpretation it performs is to
-substitute values for environment variables that use standard Windows notation,
-such as `%USERPROFILE%`.
+| `Write-Output a$(2)` | Argument | "a2" (string) |
-The stop-parsing symbol is effective only until the next newline or pipeline
-character. You cannot use a continuation character (`` ` ``) to extend its
-effect or use a command delimiter (`;`) to terminate its effect.
+Every token can be interpreted as some kind of object type, such as **Boolean**
+or **String**. PowerShell attempts to determine the object type from the
+expression. The object type depends on the type of parameter a command expects
+and on whether PowerShell knows how to convert the argument to the correct
+type. The following table shows several examples of the types assigned to
+values returned by the expressions.
+
+| Example | Mode | Result |
+| --------------------- | ---------- | --------------- |
+| `Write-Output !1` | argument | "!1" (string) |
+| `Write-Output (!1)` | expression | False (Boolean) |
+| `Write-Output (2)` | expression | 2 (integer) |
+| `Set-Variable AB A,B` | argument | 'A','B' (array) |
+| `CMD /CECHO A,B` | argument | 'A,B' (string) |
+| `CMD /CECHO $AB` | expression | 'A B' (array) |
+| `CMD /CECHO :$AB` | argument | ':A B' (string) |
+
+## Passing arguments to native commands
+
+When running native commands from PowerShell, the arguments are first parsed
+by PowerShell. The parsed arguments are then joined into a single string with
+each parameter separated by a space.
-For example, the following command calls the **Icacls** program.
+For example, the following command calls the `icacls.exe` program.
```powershell icacls X:\VMS /grant Dom\HVAdmin:(CI)(OI)F
prevent PowerShell from misinterpreting the parentheses.
icacls X:\VMS /grant Dom\HVAdmin:`(CI`)`(OI`)F ```
-Beginning in PowerShell 3.0, you can use the stop-parsing symbol.
+### The stop-parsing token
+
+Beginning in PowerShell 3.0, you can use the stop-parsing token (`--%`) to
+stop PowerShell from interpreting input asPowerShell commands or expressions.
+
+> [!NOTE]
+> The stop-parsing token is only intended for use on Windows platforms.
+
+When calling a native command, place the stop-parsing token before the program
+arguments. This technique is much easier than using escape characters to
+prevent misinterpretation.
+
+When it encounters a stop-parsing token, PowerShell treats the remaining
+characters in the line as a literal. The only interpretation it performs is to
+substitute values for environment variables that use standard Windows notation,
+such as `%USERPROFILE%`.
```powershell icacls X:\VMS --% /grant Dom\HVAdmin:(CI)(OI)F ```
-PowerShell sends the following command string to the **Icacls** program:
+PowerShell sends the following command string to the `icacls.exe` program:
`X:\VMS /grant Dom\HVAdmin:(CI)(OI)F`
+The stop-parsing token is effective only until the next newline or pipeline
+character. You cannot use a continuation character (`` ` ``) to extend its
+effect or use a command delimiter (`;`) to terminate its effect.
+
+Other than `%variable%` environment-variable references, you cannot embed any
+other dynamic elements in the command. Escaping a `%` character as `%%`, the
+way you can do inside batch files, is not supported. `%<name>%` tokens are
+invariably expanded. If `<name>` does not refer to a defined environment
+variable the token is passed through as-is.
+
+You cannot use stream redirection (like `>file.txt`) because they are passed
+verbatim as arguments to the target command.
+
+### Passing arguments that contain quote characters
+
+Some native commands expect arguments that contain quote characters. Normally,
+PowerShell's command line parsing removes the quote character you provided. The
+parsed arguments are then joined into a single string with each parameter
+separated by a space. This string is then assigned to the **Arguments**
+property of a `ProcessStartInfo` object. Quotes within the string must be
+escaped using extra quotes or backslash (`\`) characters.
+ > [!NOTE]
-> The stop-parsing symbol only intended for use on Windows platforms.
+> The backslash (`\`) character is not recognized as an escape character by
+> PowerShell. It is the escape character used by the underlying API for
+> `ProcessStartInfo.Arguments`.
+
+For more information about the escape requirements, see the documentation for
+[ProcessStartInfo.Arguments](/dotnet/api/system.diagnostics.processstartinfo.arguments).
+
+The following examples using the `TestExe.exe` tool. This tool is used by the
+Pester tests in the PowerShell source repo. The goal of these examples is to
+pass the directory path `"C:\Program Files (x86)\Microsoft\"` to a native
+command so that it received the path as a quoted string.
+
+The **echoargs** parameter of `TestExe` displays the values received as
+arguments to the executable. You can use this tool to verify that you have
+properly escaped the characters in your arguments.
+
+```powershell
+TestExe -echoargs """""${env:ProgramFiles(x86)}\Microsoft\\"""""
+TestExe -echoargs """""C:\Program Files (x86)\Microsoft\\"""""
+TestExe -echoargs "\""C:\Program Files (x86)\Microsoft\\"""
+TestExe -echoargs --% "\"C:\Program Files (x86)\Microsoft\\"
+TestExe -echoargs --% """C:\Program Files (x86)\Microsoft\\""
+TestExe -echoargs --% """%ProgramFiles(x86)%\Microsoft\\""
+```
+
+The output is the same for all examples:
+
+```Output
+Arg 0 is <"C:\Program Files (x86)\Microsoft\">
+```
+
+You can build `TestExe` from the source code. See
+[TestExe](https://github.com/PowerShell/PowerShell/blob/master/test/tools/TestExe/TestExe.cs).
-## SEE ALSO
+## See also
[about_Command_Syntax](about_Command_Syntax.md)
Microsoft.PowerShell.Core About Quoting Rules (7.1) https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.1/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md
--- description: Describes rules for using single and double quotation marks in PowerShell. Locale: en-US Previously updated : 12/14/2020 Last updated : 09/07/2021 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_quoting_rules?view=powershell-7.1&WT.mc_id=ps-gethelp schema: 2.0.0 Title: about Quoting Rules
command that are run on the remote computer. In a remote session, quotation
marks also determine whether the variables in a command are interpreted first on the local computer or on the remote computer.
-## Single and double-quoted strings
+## Double-quoted strings
A string enclosed in double quotation marks is an _expandable_ string. Variable names preceded by a dollar sign (`$`) are replaced with the variable's value
The output of this command is:
The value of 5 is 5. ```
-A string enclosed in single-quotation marks is a _verbatim_ string. The string
-is passed to the command exactly as you type it. No substitution is performed.
+Only simple variable references can be directly embedded in an expandable
+string. Variables references using array indexing or member access must be
+enclosed in a subexpression. For example:
+
+```powershell
+"PS version: $($PSVersionTable.PSVersion)"
+```
+
+```Output
+PS version: 7.1.4
+```
+
+To separate a variable name from subsequent characters in the string,
+enclose it in braces (`{}`). This is especially important if the variable name
+is followed by a colon (`:`). PowerShell considers everything between the `$`
+and the `:` a scope specifier, typically causing the interpretation to fail.
+For example, `"$HOME: where the heart is."` throws an error, but
+`"${HOME}: where the heart is."` works as intended.
+
+To prevent the substitution of a variable value in a double-quoted string, use
+the backtick character (`` ` ``), which is the PowerShell escape character.
+
+In the following example, the backtick character that precedes the first `$i`
+variable prevents PowerShell from replacing the variable name with its value.
For example: ```powershell $i = 5
-'The value of $i is $i.'
+"The value of `$i is $i."
``` The output of this command is: ```Output
-The value $i is $i.
+The value $i is 5.
```
-Similarly, expressions in single-quoted strings are not evaluated. They are
-interpreted as literals. For example:
+## Single-quoted strings
+
+A string enclosed in single-quotation marks is a _verbatim_ string. The string
+is passed to the command exactly as you type it. No substitution is performed.
+For example:
```powershell
-'The value of $(2+3) is 5.'
+$i = 5
+'The value of $i is $i.'
``` The output of this command is: ```Output
-The value of $(2+3) is 5.
+The value $i is $i.
```
-To prevent the substitution of a variable value in a double-quoted string, use
-the backtick character (`` ` ``)(ASCII 96), which is the PowerShell escape
-character.
-
-In the following example, the backtick character that precedes the first `$i`
-variable prevents PowerShell from replacing the variable name with its value.
-For example:
+Similarly, expressions in single-quoted strings are not evaluated. They are
+interpreted as literals. For example:
```powershell
-$i = 5
-"The value of `$i is $i."
+'The value of $(2+3) is 5.'
``` The output of this command is: ```Output
-The value $i is 5.
+The value of $(2+3) is 5.
```
+## Including quote characters in a string
+ To make double-quotation marks appear in a string, enclose the entire string in single quotation marks. For example:
backtick character. This prevents PowerShell from interpreting the quotation
mark as a string delimiter. For example: ```powershell
-PS> "Use a quotation mark (`") to begin a string."
-Use a quotation mark (") to begin a string.
-PS> 'Use a quotation mark (`") to begin a string.'
-Use a quotation mark (`") to begin a string.
+"Use a quotation mark (`") to begin a string."
+'Use a quotation mark (`") to begin a string.'
```
-Because the contents of single-quoted strings are interpreted literally,
-the backtick character is treated as a literal character and displayed in the
+Because the contents of single-quoted strings are interpreted literally, the
+backtick character is treated as a literal character and displayed in the
output.
+```Output
+Use a quotation mark (") to begin a string.
+Use a quotation mark (`") to begin a string.
+```
+ ## Here-strings The quotation rules for here-strings are slightly different.
Here-strings are also a convenient format for input to the
`ConvertFrom-StringData` cmdlet, which converts here-strings to hash tables. For more information, see `ConvertFrom-StringData`.
+## Interpretation of expandable strings
+
+Expanded strings don't necessarily look the same as the default output that you
+see in the console.
+
+Collections, including arrays, are converted to strings by placing a single
+space between the string representations of the elements. A different separator
+can be specified by setting preference variable `$OFS`. For more information,
+see the [`$OFS` preference variable](about_preference_variables.md#ofs).
+
+Instances of any other type are converted to strings by calling the
+`ToString()` method which may not give a meaningful representation. For
+example:
+
+```powershell
+"hashtable: $(@{ key = 'value' })"
+```
+
+```Output
+hashtable: System.Collections.Hashtable
+```
+
+To get the same output as in the console, use a subexpression in which you pipe
+to `Out-String`. Apply the `Trim()` method if you want to remove any leading
+and trailing empty lines.
+
+```powershell
+"hashtable:`n$((@{ key = 'value' } | Out-String).Trim())"
+```
+
+```Output
+hashtable:
+Name Value
+---- -----
+key value
+```
+ ## See also [about_Special_Characters](about_Special_Characters.md)
Microsoft.PowerShell.Core About Scripts (7.1) https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.1/Microsoft.PowerShell.Core/About/about_Scripts.md
PowerShell has many useful features that you can use in scripts.
- `#Requires` - You can use a `#Requires` statement to prevent a script from running without specified modules or snap-ins and a specified version of
- PowerShell. For more information, see about_Requires.
+ PowerShell. For more information, see [about_Requires](about_Requires.md).
- `$PSCommandPath` - Contains the full path and name of the script that is being run. This parameter is valid in all scripts. This automatic variable is
Microsoft.PowerShell.Core About Automatic Variables (7.2) https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.2/Microsoft.PowerShell.Core/About/about_Automatic_Variables.md
The following members control how or when ANSI formatting is used:
- `$PSStyle.Progress` allows you to control progress view bar rendering. - **Style** - An ANSI string setting the rendering style.
- - **MaxWidth**` - Sets the max width of the view. Set to `0` for console
+ - **MaxWidth** - Sets the max width of the view. Set to `0` for console
width. Defaults to `120` - **View** - An enum with values, `Minimal` and `Classic`. `Classic` is the existing rendering with no changes. `Minimal` is a single line minimal
Microsoft.PowerShell.Core About Parsing (7.2) https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.2/Microsoft.PowerShell.Core/About/about_Parsing.md
--- description: Describes how PowerShell parses commands. Locale: en-US Previously updated : 09/14/2020 Last updated : 09/07/2021 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_parsing?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 Title: about Parsing --- # about_Parsing
-## SHORT DESCRIPTION
+## Short description
+ Describes how PowerShell parses commands.
-## LONG DESCRIPTION
+## Long description
When you enter a command at the command prompt, PowerShell breaks the command text into a series of segments called _tokens_ and then determines how to
expression mode and argument mode.
> execute intended cmdlet. > - `Get-Help` and `Get-Command` don't recognize verb-less names.
-### Expression mode
+## Expression mode
Expression mode is intended for combining expressions, required for value manipulation in a scripting language. Expressions are representations of values in PowerShell syntax, and can be simple or composite, for example:
-Literal expressions are direct representations of their values:
+Literal expressions are direct representations of their values:
```powershell
-'hello', 32
+'hello'
+32
```
-Variable expressions carry the value of the variable they reference:
+Variable expressions carry the value of the variable they reference:
```powershell
-$x, $script:path
+$x
+$script:path
```
-Operators combine other expressions for evaluation:
+
+Operators combine other expressions for evaluation:
```powershell-- 12, -not $Quiet, 3 + 7, $input.Length -gt 1
+-12
+-not $Quiet
+3 + 7
+$input.Length -gt 1
``` - _Character string literals_ must be contained in quotation marks.
Operators combine other expressions for evaluation:
pasting prefilled parameter sets) is forbidden and causes a parser error. - Anything else will be treated as a command to be invoked.
-### Argument mode
+## Argument mode
When parsing, PowerShell first looks to interpret input as an expression. But when a command invocation is encountered, parsing continues in argument mode.
+If you have arguments that contain spaces, such as paths, then you must
+enclose those argument values in quotes.
Argument mode is designed for parsing arguments and parameters for commands in a shell environment. All input is treated as an expandable string unless it uses one of the following syntaxes: -- Dollar sign (`$`) begins a variable reference (only if it is followed by a
- valid variable name, otherwise it is interpreted as part of the expandable
- string).
-- Quotation marks (`'` and `"`) begin string values-- Parentheses (`(` and `)`) demarcate new expressions.-- Subexpression operator (`$(`…`)`) demarcates embedded expressions.-- Braces (`{` and `}`) demarcate new script blocks.-- Initial at sign (`@`) begins expression syntaxes such as splatting (`@args`),
- arrays (`@(1,2,3)`) and hash tables (`@{a=1;b=2}`).
+- Dollar sign (`$`) followed by a variable name begins a variable reference,
+ otherwise it is interpreted as part of the expandable string. The variable
+ reference can include member access or indexing.
+ - Additional characters following simple variable references, such as
+ `$HOME`, are considered part of the same argument. Enclose the variable
+ name in braces (`{}`) to separate it from subsequent characters. For
+ example, `${HOME}`.
+ - When the variable reference include member access, the first of any
+ additional characters is considered the start of a new argument. For
+ example `$HOME.Length-more` results in two arguments: the value of
+ `$HOME.Length` and string literal `-more`.
+
+- Quotation marks (`'` and `"`) begin strings
+
+- Braces (`{}`) begin a new script blocks
+ - Commas (`,`) introduce lists passed as arrays, except when the command to be called is a native application, in which case they are interpreted as part of the expandable string. Initial, consecutive or trailing commas are not supported.
-<!--
-01234567890123456789012345678901234567890123456789012345678901234567890123456789
-Values of embedded expressions are converted to strings.
-
-The following table provides several examples of values processed in expression
-mode and argument mode and the evaluation of those values. We assume that the
-value of the variable `a` is `4`.
+- Parentheses (`()`) begin a new expression
+- Subexpression operator (`$()`) begins an embedded expression
+- Initial at sign (`@`) begins expression syntaxes such as splatting (`@args`),
+ arrays (`@(1,2,3)`), and hash table literals (`@{a=1;b=2}`).
+- `()`, `$()`, and `@()` at the start of a token create a new parsing context
+ that can contain expressions or nested commands.
+ - When followed by additional characters, the first additional character is
+ considered the start of a new, separate argument.
+ - When preceded by an unquoted literal `$()` works like an expandable string,
+ `()` starts a new argument that is an expression, and `@()` is taken as
+ literal `@` with `()` starting a new argument that is an expression.
+
+- Everything else is treated as an expandable string, except
+ metacharacters that still need escaping.
+ - The argument-mode metacharacters (characters with special syntactic
+ meaning) are: ``<space> ' " ` , ; ( ) { } | & < > @ #``. Of these, `< > @ #`
+ are only special at the start of a token.
+
+- The stop-parsing token (`--%`) changes the interpretation of all remaining
+ arguments. For more information, see the
+ [stop-parsing token](#the-stop-parsing-token) section below.
+
+### Examples
+
+The following table provides several examples of tokens processed in expression
+mode and argument mode and the evaluation of those tokens. For these examples,
+the value of the variable `$a` is `4`.
| Example | Mode | Result | | -------------------- | ---------- | ----------------- | | `2` | Expression | 2 (integer) | | `` `2`` | Expression | "2" (command) |
-| `echo 2` | Expression | 2 (integer) |
+| `Write-Output 2` | Expression | 2 (integer) |
| `2+2` | Expression | 4 (integer) |
-| `echo 2+2` | Argument | "2+2" (string) |
-| `echo(2+2)` | Expression | 4 (integer) |
+| `Write-Output 2+2` | Argument | "2+2" (string) |
+| `Write-Output(2+2)` | Expression | 4 (integer) |
| `$a` | Expression | 4 (integer) |
-| `echo $a` | Expression | 4 (integer) |
+| `Write-Output $a` | Expression | 4 (integer) |
| `$a+2` | Expression | 6 (integer) |
-| `echo $a+2` | Argument | 4+2 (string) |
+| `Write-Output $a+2` | Argument | "4+2" (string) |
| `$-` | Argument | "$-" (command) |
-| `echo $-` | Argument | "$-" (string) |
+| `Write-Output $-` | Argument | "$-" (string) |
| `a$a` | Expression | "a$a" (command) |
-| `echo a$a` | Argument | "a4" (string) |
+| `Write-Output a$a` | Argument | "a4" (string) |
| `a'$a'` | Expression | "a$a" (command) |
-| `echo a'$a'` | Argument | "a$a" (string) |
+| `Write-Output a'$a'` | Argument | "a$a" (string) |
| `a"$a"` | Expression | "a$a" (command) |
-| `echo a"$a"` | Argument | "a4" (string) |
+| `Write-Output a"$a"` | Argument | "a4" (string) |
| `a$(2)` | Expression | "a$(2)" (command) |
-| `echo a$(2)` | Argument | "a2" (string) |
-
-Every token can be interpreted as some kind of object type, such as Boolean or
-string. PowerShell attempts to determine the object type from the expression.
-The object type depends on the type of parameter a command expects and on
-whether PowerShell knows how to convert the argument to the correct type. The
-following table shows several examples of the types assigned to values returned
-by the expressions.
-
-| Example | Mode | Result |
-| ---------------------- | ---------- | --------------- |
-| `Write-Output !1` | argument | "!1" (string) |
-| `Write-Output (!1)` | expression | False (Boolean) |
-| `Write-Output (2)` | expression | 2 (integer) |
-| `Set-Variable AB A,B` | argument | 'A','B' (array) |
-| `CMD /CECHO A,B` | argument | 'A,B' (string) |
-| `CMD /CECHO $AB` | expression | 'A','B' (array) |
-| `CMD /CECHO :$AB` | argument | ':A B' (string) |
-
-The stop-parsing symbol (`--%`), introduced in PowerShell 3.0, directs
-PowerShell to refrain from interpreting input as PowerShell commands or
-expressions.
-
-When calling an executable program in PowerShell, place the stop-parsing symbol
-before the program arguments. This technique is much easier than using escape
-characters to prevent misinterpretation.
-
-When it encounters a stop-parsing symbol, PowerShell treats the remaining
-characters in the line as a literal. The only interpretation it performs is to
-substitute values for environment variables that use standard Windows notation,
-such as `%USERPROFILE%`.
+| `Write-Output a$(2)` | Argument | "a2" (string) |
-The stop-parsing symbol is effective only until the next newline or pipeline
-character. You cannot use a continuation character (`` ` ``) to extend its
-effect or use a command delimiter (`;`) to terminate its effect.
+Every token can be interpreted as some kind of object type, such as **Boolean**
+or **String**. PowerShell attempts to determine the object type from the
+expression. The object type depends on the type of parameter a command expects
+and on whether PowerShell knows how to convert the argument to the correct
+type. The following table shows several examples of the types assigned to
+values returned by the expressions.
+
+| Example | Mode | Result |
+| --------------------- | ---------- | --------------- |
+| `Write-Output !1` | argument | "!1" (string) |
+| `Write-Output (!1)` | expression | False (Boolean) |
+| `Write-Output (2)` | expression | 2 (integer) |
+| `Set-Variable AB A,B` | argument | 'A','B' (array) |
+| `CMD /CECHO A,B` | argument | 'A,B' (string) |
+| `CMD /CECHO $AB` | expression | 'A B' (array) |
+| `CMD /CECHO :$AB` | argument | ':A B' (string) |
-For example, the following command calls the **Icacls** program.
+## Passing arguments to native commands
+
+When running native commands from PowerShell, the arguments are first parsed
+by PowerShell. The parsed arguments are then joined into a single string with
+each parameter separated by a space.
+
+For example, the following command calls the `icacls.exe` program.
```powershell icacls X:\VMS /grant Dom\HVAdmin:(CI)(OI)F
prevent PowerShell from misinterpreting the parentheses.
icacls X:\VMS /grant Dom\HVAdmin:`(CI`)`(OI`)F ```
-Beginning in PowerShell 3.0, you can use the stop-parsing symbol.
+### The stop-parsing token
+
+Beginning in PowerShell 3.0, you can use the stop-parsing token (`--%`) to
+stop PowerShell from interpreting input asPowerShell commands or expressions.
+
+> [!NOTE]
+> The stop-parsing token is only intended for use on Windows platforms.
+
+When calling a native command, place the stop-parsing token before the program
+arguments. This technique is much easier than using escape characters to
+prevent misinterpretation.
+
+When it encounters a stop-parsing token, PowerShell treats the remaining
+characters in the line as a literal. The only interpretation it performs is to
+substitute values for environment variables that use standard Windows notation,
+such as `%USERPROFILE%`.
```powershell icacls X:\VMS --% /grant Dom\HVAdmin:(CI)(OI)F ```
-PowerShell sends the following command string to the **Icacls** program:
+PowerShell sends the following command string to the `icacls.exe` program:
`X:\VMS /grant Dom\HVAdmin:(CI)(OI)F`
+The stop-parsing token is effective only until the next newline or pipeline
+character. You cannot use a continuation character (`` ` ``) to extend its
+effect or use a command delimiter (`;`) to terminate its effect.
+
+Other than `%variable%` environment-variable references, you cannot embed any
+other dynamic elements in the command. Escaping a `%` character as `%%`, the
+way you can do inside batch files, is not supported. `%<name>%` tokens are
+invariably expanded. If `<name>` does not refer to a defined environment
+variable the token is passed through as-is.
+
+You cannot use stream redirection (like `>file.txt`) because they are passed
+verbatim as arguments to the target command.
+
+### Passing arguments that contain quote characters
+
+Some native commands expect arguments that contain quote characters. Normally,
+PowerShell's command line parsing removes the quote character you provided. The
+parsed arguments are then joined into a single string with each parameter
+separated by a space. This string is then assigned to the **Arguments**
+property of a `ProcessStartInfo` object. Quotes within the string must be
+escaped using extra quotes or backslash (`\`) characters.
+ > [!NOTE]
-> The stop-parsing symbol only intended for use on Windows platforms.
+> The backslash (`\`) character is not recognized as an escape character by
+> PowerShell. It is the escape character used by the underlying API for
+> `ProcessStartInfo.Arguments`.
+
+For more information about the escape requirements, see the documentation for
+[ProcessStartInfo.Arguments](/dotnet/api/system.diagnostics.processstartinfo.arguments).
+
+The following examples using the `TestExe.exe` tool. This tool is used by the
+Pester tests in the PowerShell source repo. The goal of these examples is to
+pass the directory path `"C:\Program Files (x86)\Microsoft\"` to a native
+command so that it received the path as a quoted string.
+
+The **echoargs** parameter of `TestExe` displays the values received as
+arguments to the executable. You can use this tool to verify that you have
+properly escaped the characters in your arguments.
+
+```powershell
+TestExe -echoargs """""${env:ProgramFiles(x86)}\Microsoft\\"""""
+TestExe -echoargs """""C:\Program Files (x86)\Microsoft\\"""""
+TestExe -echoargs "\""C:\Program Files (x86)\Microsoft\\"""
+TestExe -echoargs --% "\"C:\Program Files (x86)\Microsoft\\"
+TestExe -echoargs --% """C:\Program Files (x86)\Microsoft\\""
+TestExe -echoargs --% """%ProgramFiles(x86)%\Microsoft\\""
+```
+
+The output is the same for all examples:
+
+```Output
+Arg 0 is <"C:\Program Files (x86)\Microsoft\">
+```
+
+You can build `TestExe` from the source code. See
+[TestExe](https://github.com/PowerShell/PowerShell/blob/master/test/tools/TestExe/TestExe.cs).
+
+## Experimental feature
+
+Powershell 7.2 includes the **PSNativeCommandArgumentPassing** experimental
+feature. When this experimental feature is enabled PowerShell uses the
+**ArgumentList** property of the `StartProcessInfo` object rather than our
+current mechanism of reconstructing a string when invoking a native executable.
+
+For more information, see
+[PSNativeCommandArgumentPassing](/powershell/scripting/learn/experimental-features#psnativecommandargumentpassing).
-## SEE ALSO
+## See also
[about_Command_Syntax](about_Command_Syntax.md)
Microsoft.PowerShell.Core About Quoting Rules (7.2) https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.2/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md
--- description: Describes rules for using single and double quotation marks in PowerShell. Locale: en-US Previously updated : 12/14/2020 Last updated : 09/07/2021 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_quoting_rules?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 Title: about Quoting Rules
command that are run on the remote computer. In a remote session, quotation
marks also determine whether the variables in a command are interpreted first on the local computer or on the remote computer.
-## Single and double-quoted strings
+## Double-quoted strings
A string enclosed in double quotation marks is an _expandable_ string. Variable names preceded by a dollar sign (`$`) are replaced with the variable's value
The output of this command is:
The value of 5 is 5. ```
-A string enclosed in single-quotation marks is a _verbatim_ string. The string
-is passed to the command exactly as you type it. No substitution is performed.
+Only simple variable references can be directly embedded in an expandable
+string. Variables references using array indexing or member access must be
+enclosed in a subexpression. For example:
+
+```powershell
+"PS version: $($PSVersionTable.PSVersion)"
+```
+
+```Output
+PS version: 7.2.0
+```
+
+To separate a variable name from subsequent characters in the string,
+enclose it in braces (`{}`). This is especially important if the variable name
+is followed by a colon (`:`). PowerShell considers everything between the `$`
+and the `:` a scope specifier, typically causing the interpretation to fail.
+For example, `"$HOME: where the heart is."` throws an error, but
+`"${HOME}: where the heart is."` works as intended.
+
+To prevent the substitution of a variable value in a double-quoted string, use
+the backtick character (`` ` ``), which is the PowerShell escape character.
+
+In the following example, the backtick character that precedes the first `$i`
+variable prevents PowerShell from replacing the variable name with its value.
For example: ```powershell $i = 5
-'The value of $i is $i.'
+"The value of `$i is $i."
``` The output of this command is: ```Output
-The value $i is $i.
+The value $i is 5.
```
-Similarly, expressions in single-quoted strings are not evaluated. They are
-interpreted as literals. For example:
+## Single-quoted strings
+
+A string enclosed in single-quotation marks is a _verbatim_ string. The string
+is passed to the command exactly as you type it. No substitution is performed.
+For example:
```powershell
-'The value of $(2+3) is 5.'
+$i = 5
+'The value of $i is $i.'
``` The output of this command is: ```Output
-The value of $(2+3) is 5.
+The value $i is $i.
```
-To prevent the substitution of a variable value in a double-quoted string, use
-the backtick character (`` ` ``)(ASCII 96), which is the PowerShell escape
-character.
-
-In the following example, the backtick character that precedes the first `$i`
-variable prevents PowerShell from replacing the variable name with its value.
-For example:
+Similarly, expressions in single-quoted strings are not evaluated. They are
+interpreted as literals. For example:
```powershell
-$i = 5
-"The value of `$i is $i."
+'The value of $(2+3) is 5.'
``` The output of this command is: ```Output
-The value $i is 5.
+The value of $(2+3) is 5.
```
+## Including quote characters in a string
+ To make double-quotation marks appear in a string, enclose the entire string in single quotation marks. For example:
backtick character. This prevents PowerShell from interpreting the quotation
mark as a string delimiter. For example: ```powershell
-PS> "Use a quotation mark (`") to begin a string."
-Use a quotation mark (") to begin a string.
-PS> 'Use a quotation mark (`") to begin a string.'
-Use a quotation mark (`") to begin a string.
+"Use a quotation mark (`") to begin a string."
+'Use a quotation mark (`") to begin a string.'
```
-Because the contents of single-quoted strings are interpreted literally,
-the backtick character is treated as a literal character and displayed in the
+Because the contents of single-quoted strings are interpreted literally, the
+backtick character is treated as a literal character and displayed in the
output.
+```Output
+Use a quotation mark (") to begin a string.
+Use a quotation mark (`") to begin a string.
+```
+ ## Here-strings The quotation rules for here-strings are slightly different.
Here-strings are also a convenient format for input to the
`ConvertFrom-StringData` cmdlet, which converts here-strings to hash tables. For more information, see `ConvertFrom-StringData`.
+## Interpretation of expandable strings
+
+Expanded strings don't necessarily look the same as the default output that you
+see in the console.
+
+Collections, including arrays, are converted to strings by placing a single
+space between the string representations of the elements. A different separator
+can be specified by setting preference variable `$OFS`. For more information,
+see the [`$OFS` preference variable](about_preference_variables.md#ofs).
+
+Instances of any other type are converted to strings by calling the
+`ToString()` method which may not give a meaningful representation. For
+example:
+
+```powershell
+"hashtable: $(@{ key = 'value' })"
+```
+
+```Output
+hashtable: System.Collections.Hashtable
+```
+
+To get the same output as in the console, use a subexpression in which you pipe
+to `Out-String`. Apply the `Trim()` method if you want to remove any leading
+and trailing empty lines.
+
+```powershell
+"hashtable:`n$((@{ key = 'value' } | Out-String).Trim())"
+```
+
+```Output
+hashtable:
+Name Value
+---- -----
+key value
+```
+ ## See also [about_Special_Characters](about_Special_Characters.md)
Microsoft.PowerShell.Core About Scripts (7.2) https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.2/Microsoft.PowerShell.Core/About/about_Scripts.md
PowerShell has many useful features that you can use in scripts.
- `#Requires` - You can use a `#Requires` statement to prevent a script from running without specified modules or snap-ins and a specified version of
- PowerShell. For more information, see about_Requires.
+ PowerShell. For more information, see [about_Requires](about_Requires.md).
- `$PSCommandPath` - Contains the full path and name of the script that is being run. This parameter is valid in all scripts. This automatic variable is
module Index https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/module/index.md
archive_url: ''
layout: ApiBrowserPage apiPlatform: powershell quickFilterColumn1: powershell-7.1,windowsserver2019-ps
-quickFilterColumn2: azps-6.3.0,win-mdop2-ps
+quickFilterColumn2: azps-6.4.0,win-mdop2-ps
quickFilterColumn3: sqlserver-ps,systemcenter-ps-2019 ---