Skip to content

Update description of end-of-parameters token #8824

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
michaeltlombardi merged 1 commit into from
May 17, 2022
Merged

Update description of end-of-parameters token #8824

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
76 changes: 53 additions & 23 deletions reference/5.1/Microsoft.PowerShell.Core/About/about_Parsing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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)
76 changes: 53 additions & 23 deletions reference/7.0/Microsoft.PowerShell.Core/About/about_Parsing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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)
76 changes: 53 additions & 23 deletions reference/7.1/Microsoft.PowerShell.Core/About/about_Parsing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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)
Loading