From 60be90d7edd0f2f8c3de2d51beb07310b08dc1fc Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Tue, 17 May 2022 12:17:38 -0500 Subject: [PATCH] Update description of end-of-parameters token --- .../About/about_Parsing.md | 76 +++++++++++++------ .../About/about_Parsing.md | 76 +++++++++++++------ .../About/about_Parsing.md | 76 +++++++++++++------ .../About/about_Parsing.md | 76 +++++++++++++------ .../About/about_Parsing.md | 76 +++++++++++++------ 5 files changed, 265 insertions(+), 115 deletions(-) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Parsing.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Parsing.md index 4fd68546e9f2..d73b54a412bf 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Parsing.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Parsing.md @@ -1,7 +1,7 @@ --- description: Describes how PowerShell parses commands. Locale: en-US -ms.date: 05/16/2022 +ms.date: 05/17/2022 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 @@ -200,15 +200,14 @@ 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_ (`--%`) and -_end-of-parameters_ tokens (`--`) to stop PowerShell from interpreting input as -PowerShell commands or expressions. +### The stop-parsing token + +Beginning in PowerShell 3.0, you can use the _stop-parsing_ (`--%`) token to +stop PowerShell from interpreting input as PowerShell commands or expressions. > [!NOTE] > The stop-parsing token is only intended for use on Windows platforms. -### The stop-parsing token - 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. @@ -239,23 +238,6 @@ 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. -### The end-of-parameters token - -The end-of-parameters token (`--`) indicates that all arguments following it -are to be passed in their actual form as though double quotes were placed -around them. For example, using `--` you can output the string `-InputObject` -without using quotes or having it interpreted as a parameter: - -```powershell -Write-Output -- -InputObject -``` - -```Output --InputObject -``` - -This is a convention specified in the POSIX Shell and Utilities specification. - ### Passing arguments that contain quote characters Some native commands expect arguments that contain quote characters. Normally, @@ -299,6 +281,54 @@ 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). +## Passing arguments to PowerShell commands + +Beginning in PowerShell 3.0, you can use the _end-of-parameters_ token (`--`) +to stop PowerShell from interpreting input as PowerShell parameters. This is a +convention specified in the POSIX Shell and Utilities specification. + +The end-of-parameters token (`--`) indicates that all arguments following it +are to be passed in their actual form as though double quotes were placed +around them. For example, using `--` you can output the string `-InputObject` +without using quotes or having it interpreted as a parameter: + +```powershell +Write-Output -- -InputObject +``` + +```Output +-InputObject +``` + +Unlike the stop-parsing (`--%`) token, any values following the `--` token can +be interpreted as expressions by PowerShell. + +```powershell +Write-Output -- -InputObject $env:PROCESSOR_ARCHITECTURE +``` + +```Output +-InputObject +AMD64 +``` + +This behavior only applies to PowerShell commands. If you use the `--` token +when calling an external command, the `--` string is passed as an argument to +that command. + +```powershell +TestExe -echoargs -a -b -- -c +``` + +The output shows that `--` is passed as an argument to `TestExe`. + +```Output +Arg 0 is <-a> +Arg 1 is <-b> +Arg 2 is <--> +Arg 3 is <-c> +``` + ## See also - [about_Command_Syntax](about_Command_Syntax.md) diff --git a/reference/7.0/Microsoft.PowerShell.Core/About/about_Parsing.md b/reference/7.0/Microsoft.PowerShell.Core/About/about_Parsing.md index c15fb9099f4b..f488e90d602d 100644 --- a/reference/7.0/Microsoft.PowerShell.Core/About/about_Parsing.md +++ b/reference/7.0/Microsoft.PowerShell.Core/About/about_Parsing.md @@ -1,7 +1,7 @@ --- description: Describes how PowerShell parses commands. Locale: en-US -ms.date: 05/16/2022 +ms.date: 05/17/2022 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 @@ -200,15 +200,14 @@ 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_ (`--%`) and -_end-of-parameters_ tokens (`--`) to stop PowerShell from interpreting input as -PowerShell commands or expressions. +### The stop-parsing token + +Beginning in PowerShell 3.0, you can use the _stop-parsing_ (`--%`) token to +stop PowerShell from interpreting input as PowerShell commands or expressions. > [!NOTE] > The stop-parsing token is only intended for use on Windows platforms. -### The stop-parsing token - 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. @@ -239,23 +238,6 @@ 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. -### The end-of-parameters token - -The end-of-parameters token (`--`) indicates that all arguments following it -are to be passed in their actual form as though double quotes were placed -around them. For example, using `--` you can output the string `-InputObject` -without using quotes or having it interpreted as a parameter: - -```powershell -Write-Output -- -InputObject -``` - -```Output --InputObject -``` - -This is a convention specified in the POSIX Shell and Utilities specification. - ### Passing arguments that contain quote characters Some native commands expect arguments that contain quote characters. Normally, @@ -300,6 +282,54 @@ 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). +## Passing arguments to PowerShell commands + +Beginning in PowerShell 3.0, you can use the _end-of-parameters_ token (`--`) +to stop PowerShell from interpreting input as PowerShell parameters. This is a +convention specified in the POSIX Shell and Utilities specification. + +The end-of-parameters token (`--`) indicates that all arguments following it +are to be passed in their actual form as though double quotes were placed +around them. For example, using `--` you can output the string `-InputObject` +without using quotes or having it interpreted as a parameter: + +```powershell +Write-Output -- -InputObject +``` + +```Output +-InputObject +``` + +Unlike the stop-parsing (`--%`) token, any values following the `--` token can +be interpreted as expressions by PowerShell. + +```powershell +Write-Output -- -InputObject $env:PROCESSOR_ARCHITECTURE +``` + +```Output +-InputObject +AMD64 +``` + +This behavior only applies to PowerShell commands. If you use the `--` token +when calling an external command, the `--` string is passed as an argument to +that command. + +```powershell +TestExe -echoargs -a -b -- -c +``` + +The output shows that `--` is passed as an argument to `TestExe`. + +```Output +Arg 0 is <-a> +Arg 1 is <-b> +Arg 2 is <--> +Arg 3 is <-c> +``` + ## See also - [about_Command_Syntax](about_Command_Syntax.md) diff --git a/reference/7.1/Microsoft.PowerShell.Core/About/about_Parsing.md b/reference/7.1/Microsoft.PowerShell.Core/About/about_Parsing.md index 27673c04cdd4..a3908f5d2ec1 100644 --- a/reference/7.1/Microsoft.PowerShell.Core/About/about_Parsing.md +++ b/reference/7.1/Microsoft.PowerShell.Core/About/about_Parsing.md @@ -1,7 +1,7 @@ --- description: Describes how PowerShell parses commands. Locale: en-US -ms.date: 05/16/2022 +ms.date: 05/17/2022 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 @@ -200,15 +200,14 @@ 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_ (`--%`) and -_end-of-parameters_ tokens (`--`) to stop PowerShell from interpreting input as -PowerShell commands or expressions. +### The stop-parsing token + +Beginning in PowerShell 3.0, you can use the _stop-parsing_ (`--%`) token to +stop PowerShell from interpreting input as PowerShell commands or expressions. > [!NOTE] > The stop-parsing token is only intended for use on Windows platforms. -### The stop-parsing token - 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. @@ -239,23 +238,6 @@ 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. -### The end-of-parameters token - -The end-of-parameters token (`--`) indicates that all arguments following it -are to be passed in their actual form as though double quotes were placed -around them. For example, using `--` you can output the string `-InputObject` -without using quotes or having it interpreted as a parameter: - -```powershell -Write-Output -- -InputObject -``` - -```Output --InputObject -``` - -This is a convention specified in the POSIX Shell and Utilities specification. - ### Passing arguments that contain quote characters Some native commands expect arguments that contain quote characters. Normally, @@ -300,6 +282,54 @@ 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). +## Passing arguments to PowerShell commands + +Beginning in PowerShell 3.0, you can use the _end-of-parameters_ token (`--`) +to stop PowerShell from interpreting input as PowerShell parameters. This is a +convention specified in the POSIX Shell and Utilities specification. + +The end-of-parameters token (`--`) indicates that all arguments following it +are to be passed in their actual form as though double quotes were placed +around them. For example, using `--` you can output the string `-InputObject` +without using quotes or having it interpreted as a parameter: + +```powershell +Write-Output -- -InputObject +``` + +```Output +-InputObject +``` + +Unlike the stop-parsing (`--%`) token, any values following the `--` token can +be interpreted as expressions by PowerShell. + +```powershell +Write-Output -- -InputObject $env:PROCESSOR_ARCHITECTURE +``` + +```Output +-InputObject +AMD64 +``` + +This behavior only applies to PowerShell commands. If you use the `--` token +when calling an external command, the `--` string is passed as an argument to +that command. + +```powershell +TestExe -echoargs -a -b -- -c +``` + +The output shows that `--` is passed as an argument to `TestExe`. + +```Output +Arg 0 is <-a> +Arg 1 is <-b> +Arg 2 is <--> +Arg 3 is <-c> +``` + ## See also - [about_Command_Syntax](about_Command_Syntax.md) diff --git a/reference/7.2/Microsoft.PowerShell.Core/About/about_Parsing.md b/reference/7.2/Microsoft.PowerShell.Core/About/about_Parsing.md index c989823195a1..57cb810b11c4 100644 --- a/reference/7.2/Microsoft.PowerShell.Core/About/about_Parsing.md +++ b/reference/7.2/Microsoft.PowerShell.Core/About/about_Parsing.md @@ -1,7 +1,7 @@ --- description: Describes how PowerShell parses commands. Locale: en-US -ms.date: 05/16/2022 +ms.date: 05/17/2022 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 @@ -200,15 +200,14 @@ 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_ (`--%`) and -_end-of-parameters_ tokens (`--`) to stop PowerShell from interpreting input as -PowerShell commands or expressions. +### The stop-parsing token + +Beginning in PowerShell 3.0, you can use the _stop-parsing_ (`--%`) token to +stop PowerShell from interpreting input as PowerShell commands or expressions. > [!NOTE] > The stop-parsing token is only intended for use on Windows platforms. -### The stop-parsing token - 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. @@ -239,23 +238,6 @@ 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. -### The end-of-parameters token - -The end-of-parameters token (`--`) indicates that all arguments following it -are to be passed in their actual form as though double quotes were placed -around them. For example, using `--` you can output the string `-InputObject` -without using quotes or having it interpreted as a parameter: - -```powershell -Write-Output -- -InputObject -``` - -```Output --InputObject -``` - -This is a convention specified in the POSIX Shell and Utilities specification. - ### Passing arguments that contain quote characters Some native commands expect arguments that contain quote characters. Normally, @@ -300,6 +282,54 @@ 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). +## Passing arguments to PowerShell commands + +Beginning in PowerShell 3.0, you can use the _end-of-parameters_ token (`--`) +to stop PowerShell from interpreting input as PowerShell parameters. This is a +convention specified in the POSIX Shell and Utilities specification. + +The end-of-parameters token (`--`) indicates that all arguments following it +are to be passed in their actual form as though double quotes were placed +around them. For example, using `--` you can output the string `-InputObject` +without using quotes or having it interpreted as a parameter: + +```powershell +Write-Output -- -InputObject +``` + +```Output +-InputObject +``` + +Unlike the stop-parsing (`--%`) token, any values following the `--` token can +be interpreted as expressions by PowerShell. + +```powershell +Write-Output -- -InputObject $env:PROCESSOR_ARCHITECTURE +``` + +```Output +-InputObject +AMD64 +``` + +This behavior only applies to PowerShell commands. If you use the `--` token +when calling an external command, the `--` string is passed as an argument to +that command. + +```powershell +TestExe -echoargs -a -b -- -c +``` + +The output shows that `--` is passed as an argument to `TestExe`. + +```Output +Arg 0 is <-a> +Arg 1 is <-b> +Arg 2 is <--> +Arg 3 is <-c> +``` + ## Experimental feature Powershell 7.2 includes the **PSNativeCommandArgumentPassing** experimental diff --git a/reference/7.3/Microsoft.PowerShell.Core/About/about_Parsing.md b/reference/7.3/Microsoft.PowerShell.Core/About/about_Parsing.md index f417b8d37541..8dd1b9f124b9 100644 --- a/reference/7.3/Microsoft.PowerShell.Core/About/about_Parsing.md +++ b/reference/7.3/Microsoft.PowerShell.Core/About/about_Parsing.md @@ -1,7 +1,7 @@ --- description: Describes how PowerShell parses commands. Locale: en-US -ms.date: 05/16/2022 +ms.date: 05/17/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_parsing?view=powershell-7.3&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Parsing @@ -200,15 +200,14 @@ 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_ (`--%`) and -_end-of-parameters_ tokens (`--`) to stop PowerShell from interpreting input as -PowerShell commands or expressions. +### The stop-parsing token + +Beginning in PowerShell 3.0, you can use the _stop-parsing_ (`--%`) token to +stop PowerShell from interpreting input as PowerShell commands or expressions. > [!NOTE] > The stop-parsing token is only intended for use on Windows platforms. -### The stop-parsing token - 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. @@ -239,23 +238,6 @@ 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. -### The end-of-parameters token - -The end-of-parameters token (`--`) indicates that all arguments following it -are to be passed in their actual form as though double quotes were placed -around them. For example, using `--` you can output the string `-InputObject` -without using quotes or having it interpreted as a parameter: - -```powershell -Write-Output -- -InputObject -``` - -```Output --InputObject -``` - -This is a convention specified in the POSIX Shell and Utilities specification. - ### Passing arguments that contain quote characters Some native commands expect arguments that contain quote characters. Normally, @@ -300,6 +282,54 @@ 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). +## Passing arguments to PowerShell commands + +Beginning in PowerShell 3.0, you can use the _end-of-parameters_ token (`--`) +to stop PowerShell from interpreting input as PowerShell parameters. This is a +convention specified in the POSIX Shell and Utilities specification. + +The end-of-parameters token (`--`) indicates that all arguments following it +are to be passed in their actual form as though double quotes were placed +around them. For example, using `--` you can output the string `-InputObject` +without using quotes or having it interpreted as a parameter: + +```powershell +Write-Output -- -InputObject +``` + +```Output +-InputObject +``` + +Unlike the stop-parsing (`--%`) token, any values following the `--` token can +be interpreted as expressions by PowerShell. + +```powershell +Write-Output -- -InputObject $env:PROCESSOR_ARCHITECTURE +``` + +```Output +-InputObject +AMD64 +``` + +This behavior only applies to PowerShell commands. If you use the `--` token +when calling an external command, the `--` string is passed as an argument to +that command. + +```powershell +TestExe -echoargs -a -b -- -c +``` + +The output shows that `--` is passed as an argument to `TestExe`. + +```Output +Arg 0 is <-a> +Arg 1 is <-b> +Arg 2 is <--> +Arg 3 is <-c> +``` + ## Experimental feature Powershell 7.2 includes the **PSNativeCommandArgumentPassing** experimental