Updates from: 05/22/2021 03:08:39
Service Microsoft Docs article Related commit history on GitHub Change details
Microsoft.PowerShell.Security Get Credential (5.1) https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/5.1/Microsoft.PowerShell.Security/Get-Credential.md
--- external help file: Microsoft.PowerShell.Security.dll-Help.xml
-keywords: powershell,cmdlet
Locale: en-US Module Name: Microsoft.PowerShell.Security Previously updated : 10/23/2020 Last updated : 05/21/2021 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.security/get-credential?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 Title: Get-Credential
the **Credential** parameter.
### Example 2
-```powershell
-$c = Get-Credential
-Get-CimInstance Win32_DiskDrive -ComputerName Server01 -Credential $c
-```
-
-These commands use a credential object that the `Get-Credential` cmdlet returns to authenticate a
-user on a remote computer so they can use Windows Management Instrumentation (WMI) to manage the
-computer.
-
-The first command gets a credential object and saves it in the `$c` variable. The second command
-uses the credential object in a `Get-CimInstance` command. This command gets information about the
-disk drives on the Server01 computer.
-
-### Example 3
-
-```powershell
-Get-CimInstance Win32_BIOS -ComputerName Server01 -Credential (Get-Credential -Credential Domain01\User01)
-```
-
-This command shows how to include a `Get-Credential` command in a `Get-CimInstance` command.
-
-This command uses the `Get-CimInstance` cmdlet to get information about the BIOS on the Server01
-computer. It uses the **Credential** parameter to authenticate the user, Domain01\User01, and a
-`Get-Credential` command as the value of the **Credential** parameter.
-
-### Example 4
- ```powershell $c = Get-Credential -credential User01 $c.Username
The first command gets a credential with the user name User01 and stores it in t
The second command displays the value of the **Username** property of the resulting credential object.
-### Example 5
+### Example 3
```powershell $Credential = $host.ui.PromptForCredential("Need credentials", "Please enter your user name and password.", "", "NetBiosUserName")
For more information, see the
[PromptForCredential](/dotnet/api/system.management.automation.host.pshostuserinterface.promptforcredential) documentation in the SDK.
-### Example 6
+### Example 4
```powershell Set-ItemProperty "HKLM:\SOFTWARE\Microsoft\PowerShell\1\ShellIds" -Name ConsolePrompting -Value $true
the `Remove-ItemProperty` cmdlet to delete it.
The ConsolePrompting registry entry works in some host programs, such as the PowerShell console. It might not work in all host programs.
-### Example 7
+### Example 5
This example shows how to create a credential object that is identical to the object that `Get-Credential` returns without prompting the user. This method requires a plain text password,
text and the **Force** parameter to confirm that you understand the risks of usi
The third command uses the `New-Object` cmdlet to create a **PSCredential** object from the values in the `$User` and `$PWord` variables.
-### Example 8
+### Example 6
```powershell Get-Credential -Message "Credential are required for access to the \\Server1\Scripts file share." -User Server01\PowerUser
This command uses the **Message** and **UserName** parameters of the `Get-Creden
command format is designed for shared scripts and functions. In this case, the message tells the user why credentials are needed and gives them confidence that the request is legitimate.
-### Example 9
+### Example 7
```powershell Invoke-Command -ComputerName Server01 {Get-Credential Domain01\User02}
Microsoft.PowerShell.Security Get Credential (7.0) https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.0/Microsoft.PowerShell.Security/Get-Credential.md
--- external help file: Microsoft.PowerShell.Security.dll-Help.xml
-keywords: powershell,cmdlet
Locale: en-US Module Name: Microsoft.PowerShell.Security Previously updated : 10/23/2020 Last updated : 05/21/2021 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.security/get-credential?view=powershell-7&WT.mc_id=ps-gethelp schema: 2.0.0 Title: Get-Credential
the **Credential** parameter.
### Example 2
-```powershell
-$c = Get-Credential
-Get-CimInstance Win32_DiskDrive -ComputerName Server01 -Credential $c
-```
-
-These commands use a credential object that the `Get-Credential` cmdlet returns to authenticate a
-user on a remote computer so they can use Windows Management Instrumentation (WMI) to manage the
-computer.
-
-The first command gets a credential object and saves it in the `$c` variable. The second command
-uses the credential object in a `Get-CimInstance` command. This command gets information about the
-disk drives on the Server01 computer.
-
-### Example 3
-
-```powershell
-Get-CimInstance Win32_BIOS -ComputerName Server01 -Credential (Get-Credential -Credential Domain01\User01)
-```
-
-This command shows how to include a `Get-Credential` command in a `Get-CimInstance` command.
-
-This command uses the `Get-CimInstance` cmdlet to get information about the BIOS on the Server01
-computer. It uses the **Credential** parameter to authenticate the user, Domain01\User01, and a
-`Get-Credential` command as the value of the **Credential** parameter.
-
-### Example 4
- ```powershell $c = Get-Credential -credential User01 $c.Username
The first command gets a credential with the user name User01 and stores it in t
The second command displays the value of the **Username** property of the resulting credential object.
-### Example 5
+### Example 3
```powershell $Credential = $host.ui.PromptForCredential("Need credentials", "Please enter your user name and password.", "", "NetBiosUserName")
For more information, see the
[PromptForCredential](/dotnet/api/system.management.automation.host.pshostuserinterface.promptforcredential) documentation in the SDK.
-### Example 6
+### Example 4
This example shows how to create a credential object that is identical to the object that `Get-Credential` returns without prompting the user. This method requires a plain text password,
text and the **Force** parameter to confirm that you understand the risks of usi
The third command uses the `New-Object` cmdlet to create a **PSCredential** object from the values in the `$User` and `$PWord` variables.
-### Example 7
+### Example 5
```powershell Get-Credential -Message "Credential are required for access to the \\Server1\Scripts file share." -User Server01\PowerUser
This command uses the **Message** and **UserName** parameters of the `Get-Creden
command format is designed for shared scripts and functions. In this case, the message tells the user why credentials are needed and gives them confidence that the request is legitimate.
-### Example 8
+### Example 6
```powershell Invoke-Command -ComputerName Server01 {Get-Credential Domain01\User02}
Microsoft.PowerShell.Security Get Credential (7.1) https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.1/Microsoft.PowerShell.Security/Get-Credential.md
--- external help file: Microsoft.PowerShell.Security.dll-Help.xml
-keywords: powershell,cmdlet
Locale: en-US Module Name: Microsoft.PowerShell.Security Previously updated : 10/23/2020 Last updated : 05/21/2021 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.security/get-credential?view=powershell-7.1&WT.mc_id=ps-gethelp schema: 2.0.0 Title: Get-Credential
the **Credential** parameter.
### Example 2
-```powershell
-$c = Get-Credential
-Get-CimInstance Win32_DiskDrive -ComputerName Server01 -Credential $c
-```
-
-These commands use a credential object that the `Get-Credential` cmdlet returns to authenticate a
-user on a remote computer so they can use Windows Management Instrumentation (WMI) to manage the
-computer.
-
-The first command gets a credential object and saves it in the `$c` variable. The second command
-uses the credential object in a `Get-CimInstance` command. This command gets information about the
-disk drives on the Server01 computer.
-
-### Example 3
-
-```powershell
-Get-CimInstance Win32_BIOS -ComputerName Server01 -Credential (Get-Credential -Credential Domain01\User01)
-```
-
-This command shows how to include a `Get-Credential` command in a `Get-CimInstance` command.
-
-This command uses the `Get-CimInstance` cmdlet to get information about the BIOS on the Server01
-computer. It uses the **Credential** parameter to authenticate the user, Domain01\User01, and a
-`Get-Credential` command as the value of the **Credential** parameter.
-
-### Example 4
- ```powershell $c = Get-Credential -credential User01 $c.Username
The first command gets a credential with the user name User01 and stores it in t
The second command displays the value of the **Username** property of the resulting credential object.
-### Example 5
+### Example 3
```powershell $Credential = $host.ui.PromptForCredential("Need credentials", "Please enter your user name and password.", "", "NetBiosUserName")
For more information, see the
[PromptForCredential](/dotnet/api/system.management.automation.host.pshostuserinterface.promptforcredential) documentation in the SDK.
-### Example 6
+### Example 4
This example shows how to create a credential object that is identical to the object that `Get-Credential` returns without prompting the user. This method requires a plain text password,
text and the **Force** parameter to confirm that you understand the risks of usi
The third command uses the `New-Object` cmdlet to create a **PSCredential** object from the values in the `$User` and `$PWord` variables.
-### Example 7
+### Example 5
```powershell Get-Credential -Message "Credential are required for access to the \\Server1\Scripts file share." -User Server01\PowerUser
This command uses the **Message** and **UserName** parameters of the `Get-Creden
command format is designed for shared scripts and functions. In this case, the message tells the user why credentials are needed and gives them confidence that the request is legitimate.
-### Example 8
+### Example 6
```powershell Invoke-Command -ComputerName Server01 {Get-Credential Domain01\User02}
Microsoft.PowerShell.Security Get Credential (7.2) https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.2/Microsoft.PowerShell.Security/Get-Credential.md
external help file: Microsoft.PowerShell.Security.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Security Previously updated : 10/23/2020 Last updated : 05/21/2021 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.security/get-credential?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 Title: Get-Credential
the **Credential** parameter.
### Example 2
-```powershell
-$c = Get-Credential
-Get-CimInstance Win32_DiskDrive -ComputerName Server01 -Credential $c
-```
-
-These commands use a credential object that the `Get-Credential` cmdlet returns to authenticate a
-user on a remote computer so they can use Windows Management Instrumentation (WMI) to manage the
-computer.
-
-The first command gets a credential object and saves it in the `$c` variable. The second command
-uses the credential object in a `Get-CimInstance` command. This command gets information about the
-disk drives on the Server01 computer.
-
-### Example 3
-
-```powershell
-Get-CimInstance Win32_BIOS -ComputerName Server01 -Credential (Get-Credential -Credential Domain01\User01)
-```
-
-This command shows how to include a `Get-Credential` command in a `Get-CimInstance` command.
-
-This command uses the `Get-CimInstance` cmdlet to get information about the BIOS on the Server01
-computer. It uses the **Credential** parameter to authenticate the user, Domain01\User01, and a
-`Get-Credential` command as the value of the **Credential** parameter.
-
-### Example 4
- ```powershell $c = Get-Credential -credential User01 $c.Username
The first command gets a credential with the user name User01 and stores it in t
The second command displays the value of the **Username** property of the resulting credential object.
-### Example 5
+### Example 3
```powershell $Credential = $host.ui.PromptForCredential("Need credentials", "Please enter your user name and password.", "", "NetBiosUserName")
For more information, see the
[PromptForCredential](/dotnet/api/system.management.automation.host.pshostuserinterface.promptforcredential) documentation in the SDK.
-### Example 6
+### Example 4
This example shows how to create a credential object that is identical to the object that `Get-Credential` returns without prompting the user. This method requires a plain text password,
text and the **Force** parameter to confirm that you understand the risks of usi
The third command uses the `New-Object` cmdlet to create a **PSCredential** object from the values in the `$User` and `$PWord` variables.
-### Example 7
+### Example 5
```powershell Get-Credential -Message "Credential are required for access to the \\Server1\Scripts file share." -User Server01\PowerUser
This command uses the **Message** and **UserName** parameters of the `Get-Creden
command format is designed for shared scripts and functions. In this case, the message tells the user why credentials are needed and gives them confidence that the request is legitimate.
-### Example 8
+### Example 6
```powershell Invoke-Command -ComputerName Server01 {Get-Credential Domain01\User02}
install Installing Powershell Core On Windows https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/install/Installing-PowerShell-Core-on-Windows.md
values are changed for each major release.
## <a id="zip" />Installing the ZIP package PowerShell binary ZIP archives are provided to enable advanced deployment scenarios. Download one of
-the following ZIP archives from the [releases][releases] page.
+the following ZIP archives from the [releases][] page.
- PowerShell-7.1.3-win-x64.zip - PowerShell-7.1.3-win-x86.zip
For more information, see
> supported. The package is built for testing purposes during the preview period. To manually install the MSIX package on a Windows 10 client, download the MSIX package from our
-GitHub [releases][releases] page. Scroll down to the **Assets** section of the Release you want to
+GitHub [releases][] page. Scroll down to the **Assets** section of the Release you want to
install. The Assets section may be collapsed, so you may need to click to expand it. The MSIX file looks like this - `PowerShell-<version>-win-<os-arch>.msix`
support those methods.
<!-- link references -->
+[releases]: https://aka.ms/powershell-release?tag=stable
[preview]: https://aka.ms/powershell-release?tag=preview [latest]: https://aka.ms/powershell-release?tag=stable [ssh-remoting]: ../learn/remoting/SSH-Remoting-in-PowerShell-Core.md
lang-spec Chapter 01 https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/lang-spec/chapter-01.md
and minor errors have been corrected.
> version. There is no plan to update this documentation to reflect the current state. This > documentation is presented here for historical reference.
-## Introduction
+## 1. Introduction
PowerShell is a command-line *shell* and scripting language, designed especially for system administrators.
another.)
PowerShell includes a very rich scripting language that supports constructs for looping, conditions, flow-control, and variable assignment. This language has syntax features and keywords similar to
-those used in the C# programming language (§C. References).
+those used in the C# programming language ([§C.][]).
There are four kinds of commands in PowerShell: scripts, functions and methods, cmdlets, and native commands.
the pipeline.
Unlike most shells, which accept and return text, Windows PowerShell is built on top of the .NET Framework common language runtime (CLR) and the .NET Framework, and accepts and returns .NET Framework objects.+
+<!-- reference links -->
+[§C.]: chapter-16.md
lang-spec Chapter 02 https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/lang-spec/chapter-02.md
description: This specification shows the syntax of the PowerShell language usin
Last updated 05/19/2021 Title: Lexical structure ---
-# Lexical Structure
+# 2. Lexical Structure
-## Grammars
+## 2.1 Grammars
This specification shows the syntax of the PowerShell language using two grammars. The *lexical
-grammar* (§B.1) shows how Unicode characters are combined to form line terminators, comments, white
-space, and tokens. The *syntactic grammar* (§B.2) shows how the tokens resulting from the lexical
-grammar are combined to form PowerShell scripts.
+grammar* ([§B.1][]) shows how Unicode characters are combined to form line terminators, comments,
+white space, and tokens. The *syntactic grammar* ([§B.2][]) shows how the tokens resulting from the
+lexical grammar are combined to form PowerShell scripts.
For convenience, fragments of these grammars are replicated in appropriate places throughout this specification.
letter case in variables, aliases, function names, keywords, statements, and ope
However, throughout this specification, such names are written in lowercase, except for some automatic and preference variables.
-## Lexical analysis
+## 2.2 Lexical analysis
-### Scripts
+### 2.2.1 Scripts
Syntax:
A script may optionally contain a digital signature. A host environment is not r
any text that follows a signature or anything that looks like a signature. The creation and use of digital signatures are not covered by this specification.
-### Line terminators
+### 2.2.2 Line terminators
Syntax:
Description:
The presence of *new-line-character*s in the input source stream divides it into lines that can be used for such things as error reporting and the detection of the end of a single-line comment.
-A line terminator can be treated as white space (§2.2.4).
+A line terminator can be treated as white space ([§2.2.4][]).
-### Comments
+### 2.2.3 Comments
Syntax:
There are four other forms of a *requires-comment*:
#requires --ShellId ShellId ```
-### White space
+### 2.2.4 White space
Syntax:
Description:
Except for the fact that white space may act as a separator for tokens, it is ignored.
-Unlike some popular languages, PowerShell does not consider line-terminator characters (§2.2.2) to
-be white space. However, a line terminator can be treated as white space by preceding it immediately
-by a backtick character, `` ` `` (U+0060). This is necessary when the contents of a line are
-complete syntactically, yet the following line contains tokens intended to be associated with the
-previous line. For example,
+Unlike some popular languages, PowerShell does not consider line-terminator characters ([§2.2.2][])
+to be white space. However, a line terminator can be treated as white space by preceding it
+immediately by a backtick character, `` ` `` (U+0060). This is necessary when the contents of a line
+are complete syntactically, yet the following line contains tokens intended to be associated with
+the previous line. For example,
```powershell $number = 10 # assigns 10 to $number; nothing is written to the pipeline
$number # writes $number's value, 10, to the pipeline
``` In this example, the backtick indicates the source line is continued. The following expression is
-equivalent to `$number = 10 + 20 - 50 `.
+equivalent to `$number = 10 + 20 - 50`.
```powershell $number = 10 `
$number # writes $number's value to the pipeline
-20 ```
-## Tokens
+## 2.3 Tokens
Syntax:
A *token* is the smallest lexical element within the PowerShell language.
Tokens can be separated by *new-lines*, comments, white space, or any combination thereof.
-### Keywords
+### 2.3.1 Keywords
Syntax: ```Syntax keyword: one of
- begin break catch class
- continue data define do
- dynamicparam else elseif end
- exit filter finally for
- foreach from function if
- in inlinescript parallel param
- process return switch throw
- trap try until using
+ begin break catch class
+ continue data define do
+ dynamicparam else elseif end
+ exit filter finally for
+ foreach from function if
+ in inlinescript parallel param
+ process return switch throw
+ trap try until using
var while workflow ```
context, is a *command-name* or a *command-argument*.)
The keywords `class`, `define`, `from`, `using`, and `var` are reserved for future use.
-### Variables
+### 2.3.2 Variables
Syntax:
escaped-character:
Description:
-Variables are discussed in detail in (§5). The variable $? is discussed in §2.3.2.2. Scopes are
-discussed in §3.5.
+Variables are discussed in detail in (§5). The variable $? is discussed in [§2.3.2.2][]. Scopes are
+discussed in [§3.5][].
The variables `$$` and `$^` are reserved for use in an interactive environment, which is outside the scope of this specification.
${E:\\File.txt}
There is no limit on the length of a variable name, all characters in a variable name are significant, and letter case is *not* distinct.
-There are several different kinds of variables: user-defined (§2.3.2.1), automatic (§2.3.2.2), and
-preference (§2.3.2.3). They can all coexist in the same scope (§3.5).
+There are several different kinds of variables: user-defined ([§2.3.2.1][]), automatic
+([§2.3.2.2][]), and preference ([§2.3.2.3][]). They can all coexist in the same scope ([§3.5][]).
Consider the following function definition and calls:
Get-Power2 5 3 # position arguments splatted positionally in @args
This is achieved by using `@` instead of `$` as the first character of the variable being passed. This notation can only be used in an argument to a command.
-Names are partitioned into various namespaces each of which is stored on a virtual drive (§3.1). For
-example, variables are stored on `Variable:`, environment variables are stored on `Env:`, functions
-are stored on `Function:`, and aliases are stored on `Alias:`. All of these names can be accessed as
-variables using the *variable-namespace* production within *variable-scope*. For example,
+Names are partitioned into various namespaces each of which is stored on a virtual drive
+([§3.1][]). For example, variables are stored on `Variable:`, environment variables are stored on
+`Env:`, functions are stored on `Function:`, and aliases are stored on `Alias:`. All of these names
+can be accessed as variables using the *variable-namespace* production within *variable-scope*. For
+example,
```powershell function F { "Hello from F" }
Any use of a variable name with an explicit `Variable:` namespace is equivalent
same variable name without that qualification. For example, `$v` and `$Variable:v` are interchangeable.
-As well as being defined in the language, variables can also be defined by the cmdlet `New-Variable`
-(§13.37).
+As well as being defined in the language, variables can also be defined by the cmdlet
+[New-Variable](xref:Microsoft.PowerShell.Utility.New-Variable).
-#### User-defined variables
+#### 2.3.2.1 User-defined variables
Any variable name allowed by the grammar but not used by automatic or preference variables is available for user-defined variables. User-defined variables are created and managed by user-defined script.
-#### Automatic variables
+#### 2.3.2.2 Automatic variables
Automatic variables store state information about the PowerShell environment. Their values can be read in user-written script but not written.
read in user-written script but not written.
> of automatic variables, see > [about_Automatic_Variables](/powershell/module/microsoft.powershell.core/about/about_automatic_variables).
-#### Preference variables
+#### 2.3.2.3 Preference variables
Preference variables store user preferences for the session. They are created and initialized by the PowerShell runtime environment. Their values can be read and written in user-written script.
PowerShell runtime environment. Their values can be read and written in user-wri
> of preference variables, see > [about_Preference_Variables](/powershell/module/microsoft.powershell.core/about/about_preference_variables). -
-### Commands
+### 2.3.3 Commands
Syntax:
generic-token-part:
generic-token-char generic-token-char:
- *Any Unicode character except
- { } ( ) ; , | & $
- ` (The backtick character U+0060)
- * double-quote-character
- single-quote-character
- whitespace
- new-line-character
- escaped-character
+ Any Unicode character except
+ { } ( ) ; , | & $
+ ` (The backtick character U+0060)
+ double-quote-character
+ single-quote-character
+ whitespace
+ new-line-character
+ escaped-character
generic-token-with-subexpr-start: generic-token-parts $( ```
-### Parameters
+### 2.3.4 Parameters
Syntax: ```Syntax command-parameter:
- dash first-parameter-char parameter-chars
- colon~opt~ first-parameter-char:
+ dash first-parameter-char parameter-chars colon~opt~
+
+first-parameter-char:
A Unicode character of classes Lu, Ll, Lt, Lm, or Lo _ (The underscore character U+005F) ?
verbatim-command-argument-part:
new-line-character non-ampersand-character:
- Any Unicode character except
- &
+ Any Unicode character except &
verbatim-command-string: double-quote-character non-double-quote-chars
matching parameters to arguments is called *parameter binding*.
There are three kinds of argument: -- Switch parameter (§8.10.5) -- This has the form *command-parameter* where *first-parameter-char*
- and *parameter-chars* together make up the switch name, which corresponds to the name of a
- parameter (without its leading `-`) in the command being invoked. If the trailing colon is
- omitted, the presence of this argument indicates that the corresponding parameter be set to
- `$true`. If the trailing colon is present, the argument immediately following must designate a
+- Switch parameter ([§8.10.5][]) -- This has the form *command-parameter* where
+ *first-parameter-char* and *parameter-chars* together make up the switch name, which corresponds
+ to the name of a parameter (without its leading `-`) in the command being invoked. If the trailing
+ colon is omitted, the presence of this argument indicates that the corresponding parameter be set
+ to `$true`. If the trailing colon is present, the argument immediately following must designate a
value of type bool, and the corresponding parameter is set to that value. For example, the following invocations are equivalent:
There are three kinds of argument:
Set-MyProcess -Strict: $true ``` -- Parameter with argument (§8.10.2) -- This has the form *command-parameter* where
+- Parameter with argument ([§8.10.2][]) -- This has the form *command-parameter* where
*first-parameter-char* and *parameter-chars* together make up the parameter name, which corresponds to the name of a parameter (without its leading -) in the command being invoked. There must be no trailing colon. The argument immediately following designates an associated value. For
There are three kinds of argument:
Get-Power -exponent 3 -base 5 ``` -- Positional argument (§8.10.2) -- Arguments and their corresponding parameters inside commands have
- positions with the first having position zero. The argument in position 0 is bound to the
+- Positional argument ([§8.10.2][]) -- Arguments and their corresponding parameters inside commands
+ have positions with the first having position zero. The argument in position 0 is bound to the
parameter in position 0; the argument in position 1 is bound to the parameter in position 1; and so on. For example, given a command `Get-Power`, that has parameters `$base` and `$exponent` in positions 0 and 1, respectively, the following invokes that command:
There are three kinds of argument:
Get-Power 5 3 ```
-See §8.2 for details of the special parameters `--` and `--%`.
+See [§8.2][] for details of the special parameters `--` and `--%`.
When a command is invoked, a parameter name may be abbreviated; any distinct leading part of the full name may be used, provided that is unambiguous with respect to the names of the other parameters accepted by the same command.
-For information about parameter binding see §8.14.
+For information about parameter binding see [§8.14][].
-### Literals
+### 2.3.5 Literals
Syntax:
literal:
string-literal ```
-#### Numeric literals
+#### 2.3.5.1 Numeric literals
-There are two kinds of numeric literals: integer (§2.3.5.1.1) and real (§2.3.5.1.2). Both can have
-multiplier suffixes (§2.3.5.1.3).
+There are two kinds of numeric literals: integer ([§2.3.5.1.1][]) and real ([§2.3.5.1.2][]). Both
+can have multiplier suffixes ([§2.3.5.1.3][]).
-##### Integer literals
+##### 2.3.5.1.1 Integer literals
Syntax:
integer-literal:
hexadecimal-integer-literal decimal-integer-literal:
- decimal-digits numeric-type-suffix~opt~
- numeric-multiplier~opt~
+ decimal-digits numeric-type-suffix~opt~ numeric-multiplier~opt~
decimal-digits: decimal-digit decimal-digit decimal-digits decimal-digit: one of
- 0 1 2 3 4 5 6 7 8 9
+ 0 1 2 3 4 5 6 7 8 9
numeric-type-suffix: long-type-suffix
hexadecimal-digits:
hexadecimal-digit decimal-digits hexadecimal-digit: one of
-0 1 2 3 4 5 6 7 8 9 a b c d e f
+ 0 1 2 3 4 5 6 7 8 9 a b c d e f
long-type-suffix: l
numeric-multiplier: one of
Description: The type of an integer literal is determined by its value, the presence or absence of
-*long-type-suffix*, and the presence of a *numeric-multiplier* (§2.3.5.1.3).
+*long-type-suffix*, and the presence of a *numeric-multiplier* ([§2.3.5.1.3][]).
For an integer literal with no *long-type-suffix* -- If its value can be represented by type int (§4.2.3), that is its type;-- Otherwise, if its value can be represented by type long (§4.2.3), that is its type.-- Otherwise, if its value can be represented by type decimal (§2.3.5.1.2), that is its type.-- Otherwise, it is represented by type double (§2.3.5.1.2).
+- If its value can be represented by type int ([§4.2.3][]), that is its type;
+- Otherwise, if its value can be represented by type long ([§4.2.3][]), that is its type.
+- Otherwise, if its value can be represented by type decimal ([§2.3.5.1.2][]), that is its type.
+- Otherwise, it is represented by type double ([§2.3.5.1.2][]).
For an integer literal with *long-type-suffix* -- If its value can be represented by type long (§4.2.3), that is its type;
+- If its value can be represented by type long ([§4.2.3][]), that is its type;
- Otherwise, that literal is ill formed. In the twos-complement representation of integer values, there is one more negative value than there
Some examples of integer literals are 123 (int), 123L (long), and 200000000000 (
There is no such thing as an integer literal of type byte.
-##### Real literals
+##### 2.3.5.1.2 Real literals
Syntax: ```Syntax real-literal:
- decimal-digits *.* decimal-digits exponent-part~opt~
- decimal-type-suffix~opt~ numeric-multiplier~opt~
- *.* decimal-digits exponent-part~opt~ decimal-type-suffix~opt~
- numeric-multiplier~opt~
- decimal-digits exponent-part decimal-type-suffix~opt~
- numeric-multiplier~opt~
+ decimal-digits . decimal-digits exponent-part~opt~ decimal-type-suffix~opt~ numeric-multiplier~opt~
+ . decimal-digits exponent-part~opt~ decimal-type-suffix~opt~ numeric-multiplier~opt~
+ decimal-digits exponent-part decimal-type-suffix~opt~ numeric-multiplier~opt~
exponent-part: e sign~opt~ decimal-digits
dash:
Description:
-A real literal may contain a *numeric-multiplier* (§2.3.5.1.3).
+A real literal may contain a *numeric-multiplier* ([§2.3.5.1.3][]).
There are two kinds of real literal: *double* and *decimal*. These are indicated by the absence or presence, respectively, of *decimal-type-suffix*. (There is no such thing as a *float real literal*.)
-A double real literal has type double (§4.2.4.1). A decimal real literal has type decimal
-(§4.2.4.2). Trailing zeros in the fraction part of a decimal real literal are significant.
+A double real literal has type double ([§4.2.4.1][]). A decimal real literal has type decimal
+([§4.2.4.2][]). Trailing zeros in the fraction part of a decimal real literal are significant.
If the value of *exponent-part*'s *decimal-digits* in a double real literal is less than the minimum supported, the value of that double real literal is 0. If the value of *exponent-part*'s
Some examples of decimal real literals are 1d (which has scale 0), 1.20d (which
> [!NOTE] > Although PowerShell does not provide literals for infinities and NaNs, double real literal-like > equivalents can be obtained from the static read-only properties PositiveInfinity,
-> NegativeInfinity, and NaN of the types float and double (§4.2.4.1).
+> NegativeInfinity, and NaN of the types float and double ([§4.2.4.1][]).
The grammar permits what starts out as a double real literal to have an `l` or `L` type suffix. Such a token is really an integer literal whose value is represented by type long.
a token is really an integer literal whose value is represented by type long.
> obscure the literal's actual value. For example, 1.2L has value 1, 1.2345e1L has value 12, and > 1.2345e-5L has value 0, none of which is immediately obvious.
-##### Multiplier suffixes
+##### 2.3.5.1.3 Multiplier suffixes
Syntax:
upper- or lowercase letters.
| tb | terabyte (1024 x 1024 x 1024 x 1024) | 1.4e23tb Γëí 1.5393162788864E+35 | | pb | petabyte (1024 x 1024 x 1024 x 1024 x 1024) | 0x12Lpb Γëí 20266198323167232 |
-#### String literals
+#### 2.3.5.2 String literals
Syntax:
dollars:
dollars $ expandable-here-string-literal:
- @ double-quote-character whitespace~opt~ new-line-character expandable-here-string-characters~opt~ new-line-character double-quote-character @
+ @ double-quote-character whitespace~opt~ new-line-character
+ expandable-here-string-characters~opt~ new-line-character double-quote-character @
expandable-here-string-characters: expandable-here-string-part
expandable-here-string-part:
braced-variable $ Any Unicode character except (
- *new-line-character
+ new-line-character
$ new-line-character Any Unicode character except double-quote-char $ new-line-character double-quote-char Any Unicode character except @ new-line-character Any Unicode character except double-quote-char
start of the first source line following the opening delimiter, and ends at the
source line preceding the closing delimiter. The body may be empty. The line terminator on the last source line preceding the closing delimiter is not part of that literal's body.
-A literal of any of these kinds has type string (§4.3.1).
+A literal of any of these kinds has type string ([§4.3.1][]).
The character used to delimit a *verbatim-string-literal* or *expandable-string-literal* can be contained in such a string literal by writing that character twice, in succession. For example,
special meaning inside an *expandable-string-literal*, and a *double-quote-chara
meaning inside a *verbatim-string-literal*. An *expandable-string-literal* and an *expandable-here-string-literal* may contain
-*escaped-character*s (§2.3.7). For example, when the following string literal is written to the
+*escaped-character*s ([§2.3.7][]). For example, when the following string literal is written to the
pipeline, the result is as shown below: ```powershell
second line, "Hello", `Q5!
If an *expandable-string-literal* or *expandable-here-string-literal* contains the name of a variable, unless that name is preceded immediately by an escape character, it is replaced by the
-string representation of that variable's value (§6.7). This is known as *variable substitution*.
+string representation of that variable's value ([§6.7][]). This is known as *variable substitution*.
> [!NOTE] > If the variable name is part of some larger expression, only the variable name is replaced. For
$a[0] is red blue[0], $a[0] is red
*expandable-string-literal*s and *expandable-here-string-literal*s also support a kind of substitution called *sub-expression expansion*, by treating text of the form `$( ... )` as a
-*sub-expression* (§7.1.6). Such text is replaced by the string representation of that expression's
-value (§6.8). Any white space used to separate tokens within *sub-expression*'s *statement-list* is
-ignored as far as the result string's construction is concerned.
+*sub-expression* ([§7.1.6][]). Such text is replaced by the string representation of that
+expression's value ([§6.8][]). Any white space used to separate tokens within *sub-expression*'s
+*statement-list* is ignored as far as the result string's construction is concerned.
The examples,
body. The resulting literal is equivalent to:
`"abc<implementation-defined character sequence>xyz"`. > [!NOTE]
-> To aid readability of source, long string literals can be broken across multiple source
-> lines without line terminators being inserted. This is done by writing each part as a separate
-> literal and concatenating the parts with the + operator (§7.7.2). This operator allows its operands
-> to designate any of the four kinds of string literal.
+> To aid readability of source, long string literals can be broken across multiple source lines
+> without line terminators being inserted. This is done by writing each part as a separate literal
+> and concatenating the parts with the + operator ([§7.7.2][]). This operator allows its operands to
+> designate any of the four kinds of string literal.
> [!NOTE] > Although there is no such thing as a character literal per se, the same effect can be achieved by
body. The resulting literal is equivalent to:
For both *verbatim-here-string-literal*s and *expandable-here-string-literal*s, each line terminator within the body is represented exactly as it was provided.
-#### Null literal
+#### 2.3.5.3 Null literal
-See the automatic variable `$null` (§2.3.2.2).
+See the automatic variable `$null` ([§2.3.2.2][]).
-#### Boolean literals
+#### 2.3.5.4 Boolean literals
-See the automatic variables `$false` and `$true` (§2.3.2.2).
+See the automatic variables `$false` and `$true` ([§2.3.2.2][]).
-#### Array literals
+#### 2.3.5.5 Array literals
PowerShell allows expressions of array type (§9) to be written using the unary comma operator
-(§7.2.1), *array-expression* (§7.1.7), the binary comma operator (§7.3), and the range operator
-(§7.4).
+([§7.2.1][]), *array-expression* ([§7.1.7][]), the binary comma operator ([§7.3][]), and the range
+operator ([§7.4][]).
-#### Hash literals
+#### 2.3.5.6 Hash literals
PowerShell allows expressions of type Hashtable (§10) to be written using a
-*hash-literal-expression* (§7.1.9)
+*hash-literal-expression* ([§7.1.9][])
-#### Type names
+#### 2.3.5.7 Type names
Syntax:
generic-type-name:
type-name [ ```
-### Operators and punctuators
+### 2.3.6 Operators and punctuators
Syntax:
The name following *dash* in an operator is reserved for that purpose only in an
An operator that begins with *dash* must not have any white space between that *dash* and the token that follows it.
-### Escaped characters
+### 2.3.7 Escaped characters
Syntax:
prefix Backtick character (U+0060). The following table shows the meaning of eac
The implication of the final entry in the table above is that spaces that would otherwise separate tokens can be made part of a token instead. For example, a file name containing a space can be written as ``Test` Data.txt`` (as well as `'Test Data.txt'` or `"Test Data.txt"`).+
+<!-- reference links -->
+[§2.2.2]: chapter-02.md#222-line-terminators
+[§2.2.4]: chapter-02.md#224-white-space
+[§2.3.2.1]: chapter-02.md#2321-user-defined-variables
+[§2.3.2.2]: chapter-02.md#2322-automatic-variables
+[§2.3.2.3]: chapter-02.md#2323-preference-variables
+[§2.3.5.1.1]: chapter-02.md#23511-integer-literals
+[§2.3.5.1.2]: chapter-02.md#23512-real-literals
+[§2.3.5.1.3]: chapter-02.md#23513-multiplier-suffixes
+[§2.3.7]: chapter-02.md#237-escaped-characters
+[§3.1]: chapter-03.md#31-providers-and-drives
+[§3.5]: chapter-03.md#35-scopes
+[§4.2.3]: chapter-04.md#423-integer
+[§4.2.4.1]: chapter-04.md#4241-float-and-double
+[§4.2.4.2]: chapter-04.md#4242-decimal
+[§4.3.1]: chapter-04.md#431-strings
+[§6.7]: chapter-06.md#67-conversion-to-object
+[§6.8]: chapter-06.md#68-conversion-to-string
+[§7.1.6]: chapter-07.md#716--operator
+[§7.1.7]: chapter-07.md#717--operator
+[§7.1.9]: chapter-07.md#719-hash-literal-expression
+[§7.2.1]: chapter-07.md#721-unary-comma-operator
+[§7.3]: chapter-07.md#73-binary-comma-operator
+[§7.4]: chapter-07.md#74-range-operator
+[§7.7.2]: chapter-07.md#772-string-concatentaion
+[§8.10.2]: chapter-08.md#8102-workflow-functions
+[§8.10.5]: chapter-08.md#8105-the-switch-type-constraint
+[§8.14]: chapter-08.md#814-parameter-binding
+[§8.2]: chapter-08.md#82-pipeline-statements
+[§B.1]: chapter-15.md#b1-lexical-grammar
+[§B.2]: chapter-15.md#b2-syntactic-grammar
lang-spec Chapter 03 https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/lang-spec/chapter-03.md
description: PowerShell providers allow access to data and components from the c
Last updated 05/19/2021 Title: Basic concepts ---
-# Basic concepts
+# 3. Basic concepts
-## Providers and drives
+## 3.1 Providers and drives
A *provider* allows access to data and components that would not otherwise be easily accessible at the command line. The data is presented in a consistent format that resembles a file system drive.
stores:
| **Provider** | **Drive Name** | **Description** | **Ref.** | |--------------|-----------------|-------------------------------------|----------|
-| Alias | Alias: | PowerShell aliases | §3.1.1 |
-| Environment | Env: | Environment variables | §3.1.2 |
-| FileSystem | A:, B:, C:, ... | Disk drives, directories, and files | §3.1.3 |
-| Function | Function: | PowerShell functions | §3.1.4 |
-| Variable | Variable: | PowerShell variables | §3.1.5 |
+| Alias | Alias: | PowerShell aliases | [§3.1.1][] |
+| Environment | Env: | Environment variables | [§3.1.2][] |
+| FileSystem | A:, B:, C:, ... | Disk drives, directories, and files | [§3.1.3][] |
+| Function | Function: | PowerShell functions | [§3.1.4][] |
+| Variable | Variable: | PowerShell variables | [§3.1.5][] |
Windows PowerShell:
Windows PowerShell:
The following cmdlets deal with providers and drives: -- `Get-PSProvider`: Gets information about one or more providers (see §13.25)-- `Get-PSDrive`: Gets information about one or more drives (see §13.24)
+- [Get-PSProvider](xref:Microsoft.PowerShell.Management.Get-PSProvider): Gets information about one
+ or more providers
+- [Get-PSDrive](xref:Microsoft.PowerShell.Management.Get-PSDrive): Gets information about one or more drives
-The type of an object that represents a provider is described in §4.5.1. The type of an object that
-represents a drive is described in §4.5.2.
+The type of an object that represents a provider is described in [§4.5.1][]. The type of an object
+that represents a drive is described in [§4.5.2][].
-### Aliases
+### 3.1.1 Aliases
An *alias* is an alternate name for a command. A command can have multiple aliases, and the original name and all of its aliases can be used interchangeably. An alias can be reassigned. An alias is an
-item (§3.3).
+item ([§3.3][]).
An alias can be assigned to another alias; however, the new alias is not an alias of the original command.
command.
The provider Alias is a flat namespace that contains only objects that represent the aliases. The variables have no child items.
-Some aliases are built in to PowerShell. (For those built-in cmdlets having aliases, those aliases
-follow their cmdlets name in the section heading of §13.)
+Some aliases are built in to PowerShell.
The following cmdlets deal with aliases: -- `New-Alias`: Creates an alias (see §13.33)-- `Set-Alias`: Creates or changes one or more aliases (see §13.46)-- `Get-Alias`: Gets information about one or more aliases (see §13.13)-- `Export-Alias`: Exports one or more aliases to a file (see §13.10)
+- [New-Alias](xref:Microsoft.PowerShell.Utility.New-Alias): Creates an alias
+- [Set-Alias](xref:Microsoft.PowerShell.Utility.Set-Alias): Creates or changes one or more aliases
+- [Get-Alias](xref:Microsoft.PowerShell.Utility.Get-Alias): Gets information about one or more
+ aliases
+- [Export-Alias](xref:Microsoft.PowerShell.Utility.Export-Alias): Exports one or more aliases to a
+ file
When an alias is created for a command using `New-Alias`, parameters to that command cannot be included in that alias. However, direct assignment to a variable in the Alias: namespace does permit
parameters to be included.
> It is a simple matter, however, to create a function that does nothing more than contain the > invocation of that command with all desired parameters, and to assign an alias to that function.
-The type of an object that represents an alias is described in §4.5.4.
+The type of an object that represents an alias is described in [§4.5.4][].
-Alias objects are stored on the drive Alias: (§3.1).
+Alias objects are stored on the drive Alias: ([§3.1][]).
-### Environment variables
+### 3.1.2 Environment variables
The PowerShell environment provider allows operating system environment variables to be retrieved, added, changed, cleared, and deleted.
An environment variable's name cannot include the equal sign (`=`).
Changes to the environment variables affect the current session only.
-An environment variable is an item (§3.3).
+An environment variable is an item ([§3.3][]).
-The type of an object that represents an environment variable is described in §4.5.6.
+The type of an object that represents an environment variable is described in [§4.5.6][].
-Environment variable objects are stored on the drive Env: (§3.1).
+Environment variable objects are stored on the drive Env: ([§3.1][]).
-### File system
+### 3.1.3 File system
The PowerShell file system provider allows directories and files to be created, opened, changed, and deleted.
deleted.
The file system provider is a hierarchical namespace that contains objects that represent the underlying file system.
-Files are stored on drives with names like A:, B:, C:, and so on (§3.1). Directories and files are
-accessed using path notation (§3.4).
+Files are stored on drives with names like A:, B:, C:, and so on ([§3.1][]). Directories and files
+are accessed using path notation ([§3.4][]).
-A directory or file is an item (§3.3).
+A directory or file is an item ([§3.3][]).
-### Functions
+### 3.1.4 Functions
-The PowerShell function provider allows functions (§8.10) and filters (§8.10.1) to be retrieved,
-added, changed, cleared, and deleted.
+The PowerShell function provider allows functions ([§8.10][]) and filters ([§8.10][].1) to be
+retrieved, added, changed, cleared, and deleted.
The provider Function is a flat namespace that contains only the function and filter objects. Neither functions nor filters have child items. Changes to the functions affect the current session only.
-A function is an item (§3.3).
+A function is an item ([§3.3][]).
-The type of an object that represents a function is described in §4.5.10. The type of an object that
-represents a filter is described in §4.5.11.
+The type of an object that represents a function is described in [§4.5.10][]. The type of an object
+that represents a filter is described in [§4.5.11][].
-Function objects are stored on drive Function: (§3.1).
+Function objects are stored on drive Function: ([§3.1][]).
-### Variables
+### 3.1.5 Variables
Variables can be defined and manipulated directly in the PowerShell language.
The variables have no child items.
The following cmdlets also deal with variables: -- `New-Variable`: Creates a variable (see §13.37)-- `Set-Variable`: Creates or changes the characteristics of one or more variables (see §13.50)-- `Get-Variable`: Gets information about one or more variables (see §13.26)-- `Clear-Variable`: Deletes the value of one or more variables (see §13.5)-- `Remove-Variable`: Deletes one or more variables (see §13.42)
+- [New-Variable](xref:Microsoft.PowerShell.Utility.New-Variable): Creates a variable
+- [Set-Variable](xref:Microsoft.PowerShell.Utility.Set-Variable): Creates or changes the
+ characteristics of one or more variables
+- [Get-Variable](xref:Microsoft.PowerShell.Utility.Get-Variable): Gets information about one or more
+ variables
+- [Clear-Variable](xref:Microsoft.PowerShell.Utility.Clear-Variable): Deletes the value of one or
+ more variables
+- [Remove-Variable](xref:Microsoft.PowerShell.Utility.Remove-Variable): Deletes one or more
+ variables
-As a variable is an item (§3.3), it can be manipulated by most Item-related cmdlets.
+As a variable is an item ([§3.3][]), it can be manipulated by most Item-related cmdlets.
-The type of an object that represents a variable is described in §4.5.3.
+The type of an object that represents a variable is described in [§4.5.3][].
-Variable objects are stored on drive Variable: (§3.1).
+Variable objects are stored on drive Variable: ([§3.1][]).
-## Working locations
+## 3.2 Working locations
The *current working location* is the default location to which commands point. This is the location
-used if an explicit path (§3.4) is not supplied when a command is invoked. This location includes
-the *current drive*.
+used if an explicit path ([§3.4][]) is not supplied when a command is invoked. This location
+includes the *current drive*.
A PowerShell host may have multiple drives, in which case, each drive has its own current location.
working location stack.
The following cmdlets deal with locations: -- `Set-Location`: Establishes the current working location (see §13.49)-- `Get-Location`: Determines the current working location for the specified drive(s), or the working
- locations for the specified stack(s) (see §13.21)
-- `Push-Location`: Saves the current working location on the top of a specified stack of locations
- (see §13.39)
-- `Pop-Location`: Restores the current working location from the top of a specified stack of
- locations (see §13.38)
+- [Set-Location](xref:Microsoft.PowerShell.Management.Set-Location): Establishes the current working
+ location
+- [Get-Location](xref:Microsoft.PowerShell.Management.Get-Location): Determines the current working
+ location for the specified drive(s), or the working locations for the specified stack(s)
+- [Push-Location](xref:Microsoft.PowerShell.Management.Push-Location): Saves the current working
+ location on the top of a specified stack of locations
+- [Pop-Location](xref:Microsoft.PowerShell.Management.Pop-Location): Restores the current working
+ location from the top of a specified stack of locations
The object types that represents a working location and a stack of working locations are described
-in §4.5.5.
+in [§4.5.5][].
-## Items
+## 3.3 Items
-An *item* is an alias (§3.1.1), a variable (§3.1.5), a function (§3.1.4), an environment variable
-(§3.1.2), or a file or directory in a file system (§3.1.3).
+An *item* is an alias ([§3.1.1][]), a variable ([§3.1.5][]), a function ([§3.1.4][]), an environment
+variable ([§3.1.2][]), or a file or directory in a file system ([§3.1.3][]).
The following cmdlets deal with items: -- `New-Item`: Creates a new item (see §13.34)-- `Set-Item`: Changes the value of one or more items (see §13.48)-- `Get-Item`: Gets the items at the specified location (see §13.17)-- `Get-ChildItem`: Gets the items and child items at the specified location (see §13.14)-- `Copy-Item`: Copies one or more items from one location to another (see §13.9)-- `Move-Item`: Moves one or more items from one location to another (see §13.32)-- `Rename-Item`: Renames an item (see §13.43)-- `Invoke-Item`: Performs the default action on one or more items (see §13.29)-- `Clear-Item`: Deletes the contents of one or more items, but does not delete the items (see §13.4)-- `Remove-Item`: Deletes the specified items (see §13.40)
+- [New-Item](xref:Microsoft.PowerShell.Management.New-Item): Creates a new item
+- [Set-Item](xref:Microsoft.PowerShell.Management.Set-Item): Changes the value of one or more items
+- [Get-Item](xref:Microsoft.PowerShell.Management.Get-Item): Gets the items at the specified
+ location
+- [Get-ChildItem](xref:Microsoft.PowerShell.Management.Get-ChildItem): Gets the items and child
+ items at the specified location
+- [Copy-Item](xref:Microsoft.PowerShell.Management.Copy-Item): Copies one or more items from one
+ location to another
+- [Move-Item](xref:Microsoft.PowerShell.Management.Move-Item): Moves one or more items from one
+ location to another
+- [Rename-Item](xref:Microsoft.PowerShell.Management.Rename-Item): Renames an item
+- [Invoke-Item](xref:Microsoft.PowerShell.Management.Invoke-Item): Performs the default action on
+ one or more items
+- [Clear-Item](xref:Microsoft.PowerShell.Management.Clear-Item): Deletes the contents of one or more
+ items, but does not delete the items (see
+- [Remove-Item](xref:Microsoft.PowerShell.Management.Remove-Item): Deletes the specified items
The following cmdlets deal with the content of items: -- `Get-Content`: Gets the content of the item (see §13.16)-- `Add-Content`: Adds content to the specified items (see §13.1)-- `Set-Content`: Writes or replaces the content in an item (see §13.47)-- `Clear-Content`: Deletes the contents of an item (see §13.3)
+- [Get-Content](xref:Microsoft.PowerShell.Management.Get-Content): Gets the content of the item
+- [Add-Content](xref:Microsoft.PowerShell.Management.Add-Content): Adds content to the specified
+ items
+- [Set-Content](xref:Microsoft.PowerShell.Management.Set-Content): Writes or replaces the content in
+ an item
+- [Clear-Content](xref:Microsoft.PowerShell.Management.Clear-Content): Deletes the contents of an
+ item
-The type of an object that represents a directory is described in §4.5.17. The type of an object
-that represents a file is described in §4.5.18.
+The type of an object that represents a directory is described in [§4.5.17][]. The type of an object
+that represents a file is described in [§4.5.18][].
-## Path names
+## 3.4 Path names
All items in a data store accessible through a PowerShell provider can be identified uniquely by their path names. A *path name* is a combination of the item name, the container and subcontainers
relative path name.
The following cmdlets deal with paths: -- `Convert-Path`: Converts a path from a PowerShell path to a PowerShell provider path (see §13.8)-- `Join-Path`: Combines a path and a child path into a single path (see §13.30)-- `Resolve-Path`: Resolves the wildcard characters in a path (see §13.44)-- `Split-Path`: Returns the specified part of a path (see §13.52)-- `Test-Path`: Determines whether the elements of a path exist or if a path is well formed (see
- §13.54)
+- [Convert-Path](xref:Microsoft.PowerShell.Management.Convert-Path): Converts a path from a
+ PowerShell path to a PowerShell provider path
+- [Join-Path](xref:Microsoft.PowerShell.Management.Join-Path): Combines a path and a child path into
+ a single path
+- [Resolve-Path](xref:Microsoft.PowerShell.Management.Resolve-Path): Resolves the wildcard
+ characters in a path
+- [Split-Path](xref:Microsoft.PowerShell.Management.Split-Path): Returns the specified part of a
+ path
+- [Test-Path](xref:Microsoft.PowerShell.Management.Test-Path): Determines whether the elements of a
+ path exist or if a path is well formed
-Some cmdlets (such as `Add-Content` (§13.1) and `Copy-Item` (§13.9)) use file filters. A *file
-filter* is a mechanism for specifying the criteria for selecting from a set of paths.
+Some cmdlets (such as [Add-Content](xref:Microsoft.PowerShell.Management.Add-Content) and
+`Copy-Item` use file filters. A *file filter* is a mechanism for specifying the criteria for
+selecting from a set of paths.
-The object type that represents a resolved path is described in §4.5.5. Paths are often manipulated
-as strings.
+The object type that represents a resolved path is described in [§4.5.5][]. Paths are often
+manipulated as strings.
-## Scopes
+## 3.5 Scopes
-### Introduction
+### 3.5.1 Introduction
A name can denote a variable, a function, an alias, an environment variable, or a drive. The same name may denote different items at different places in a script. For each different item that a name
scopes are *child scopes* of that parent. The scope of a name is the scope in wh
and all child scopes, unless it is made private. Within a child scope, a name defined there hides any items defined with the same name in parent scopes.
-Unless dot source notation (§3.5.5) is used, each of the following creates a new scope:
+Unless dot source notation ([§3.5.5][]) is used, each of the following creates a new scope:
- A script file - A script block
else { return 1 }
# end of script ```
-The scope of the variables `$x` and `$y` created in the script is the body of that script, including the
-function defined inside it. Function `Get-Power` defines two parameters with those same names. As
-each function has its own scope, these variables are different from those defined in the parent
+The scope of the variables `$x` and `$y` created in the script is the body of that script, including
+the function defined inside it. Function `Get-Power` defines two parameters with those same names.
+As each function has its own scope, these variables are different from those defined in the parent
scope, and they hide those from the parent scope. The function scope is nested inside the script scope.
function F3 { # start of function scope
# end of script scope ```
-### Scope names and numbers
+### 3.5.2 Scope names and numbers
PowerShell supports the following scopes:
another. Scope 0 denotes the local scope, scope 1 denotes a 1-generation ancesto
denotes a 2-generation ancestor scope, and so on. (Scope numbers are used by cmdlets that manipulate variables.)
-### Variable name scope
+### 3.5.3 Variable name scope
As shown by the following production, a variable name can be specified with any one of six different scopes:
also shows the scope when no scope is specified explicitly:
| none | Global/Script/Local scope | Local scope | Local scope | Variable scope information can also be specified when using the family of cmdlets listed in
-(§3.1.5). In particular, refer to the parameter `Scope`, and the parameters `Option Private` and
+([§3.1.5][]). In particular, refer to the parameter `Scope`, and the parameters `Option Private` and
`Option AllScope` for more information. The scope `using` is used to access variables defined in another scope while running scripts via
foo # returns "Hello"
The scope workflow is used with a *parallel-statement* or *sequence-statement* to access a variable defined in the workflow.
-### Function name scope
+### 3.5.4 Function name scope
A function name may also have one of the four different scopes, and the visibility of that name is
-the same as for variables (§3.5.3).
+the same as for variables ([§3.5.3][]).
-### Dot source notation
+### 3.5.5 Dot source notation
When a script file, script block, or function is executed from within another script file, script block, or function, the executed script file creates a new nested scope. For example,
instead. For example,
. FunctionA ```
-### Modules
+### 3.5.6 Modules
Just like a top-level script file is at the root of a hierarchical nested scope tree, so too is each
-module (§3.14). However, by default, only those names exported by a module are available by name
-from within the importing context. The Global parameter of the cmdlet `Import-Module` (§13.28) allows
-exported names to have increased visibility.
+module ([§3.14][]). However, by default, only those names exported by a module are available by name
+from within the importing context. The Global parameter of the cmdlet
+[Import-Module](xref:Microsoft.PowerShell.Core.Import-Module) allows exported names to have
+increased visibility.
-## ReadOnly and Constant Properties
+## 3.6 ReadOnly and Constant Properties
Variables and aliases are described by objects that contain a number of properties. These properties
-are set and manipulated by two families of cmdlets (§3.1.5, §3.1.1). One such property is Options,
-which can be set to ReadOnly or Constant (using the Option parameter). A variable or alias marked
-ReadOnly can be removed, and its properties can changed provided the Force parameter is specified.
-However, a variable or alias marked Constant cannot be removed nor have its properties changed.
+are set and manipulated by two families of cmdlets ([§3.1.5][], [§3.1.1][]). One such property is
+Options, which can be set to ReadOnly or Constant (using the Option parameter). A variable or alias
+marked ReadOnly can be removed, and its properties can changed provided the Force parameter is
+specified. However, a variable or alias marked Constant cannot be removed nor have its properties
+changed.
-## Method overloads and call resolution
+## 3.7 Method overloads and call resolution
-### Introduction
+### 3.7.1 Introduction
As stated in §1, an external procedure made available by the execution environment (and written in some language other than PowerShell) is called a *method*.
The name of a method along with the number and types of its parameters are colle
method's *signature*. (Note that the signature does not include the method's return type.) The execution environment may allow a type to have multiple methods with the same name provided each has a different signature. When multiple versions of some method are defined, that method is said to be
-*overloaded*. For example, the type Math (§4.3.8) contains a set of methods called `Abs`, which
+*overloaded*. For example, the type Math ([§4.3.8][]) contains a set of methods called `Abs`, which
computes the absolute value of a specified number, where the specified number can have one of a number of types. The methods in that set have the following signatures:
Abs(Int16)
In this case, all of the methods have the same number of arguments; their signatures differ by argument type only.
-Another example involves the type Array (§4.3.2), which contains a set of methods called Copy that
-copies a range of elements from one array to another, starting at the beginning of each array (by
-default) or at some designated element. The methods in that set have the following signatures:
+Another example involves the type Array ([§4.3.2][]), which contains a set of methods called Copy
+that copies a range of elements from one array to another, starting at the beginning of each array
+(by default) or at some designated element. The methods in that set have the following signatures:
```powershell Copy(Array, Array, int)
exactly, PowerShell does not itself provide a way to define overloaded methods.
> Editor's Note: PowerShell 5.0 added the ability to define script-based classes. These classes can > contain overloaded methods.
-### Method overload resolution
+### 3.7.2 Method overload resolution
-Given a method call (§7.1.3) having a list of argument expressions, and a set of *candidate method*s
-(i.e., those methods that could be called), the mechanism for selecting the *best method* is called
-*overload resolution*.
+Given a method call ([§7.1.3][]) having a list of argument expressions, and a set of *candidate
+method*s (i.e., those methods that could be called), the mechanism for selecting the *best method*
+is called *overload resolution*.
-Given the set of applicable candidate methods (§3.7.3), the best method in that set is selected. If
-the set contains only one method, then that method is the best method. Otherwise, the best method is
-the one method that is better than all other methods with respect to the given argument list using
-the rules shown in §3.7.4. If there is not exactly one method that is better than all other methods,
-then the method invocation is ambiguous and an error is reported.
+Given the set of applicable candidate methods ([§3.7.3][]), the best method in that set is selected.
+If the set contains only one method, then that method is the best method. Otherwise, the best method
+is the one method that is better than all other methods with respect to the given argument list
+using the rules shown in [§3.7.4][]. If there is not exactly one method that is better than all
+other methods, then the method invocation is ambiguous and an error is reported.
The best method must be accessible in the context in which it is called. For example, a PowerShell script cannot call a method that is private or protected.
script cannot call a method that is private or protected.
The best method for a call to a static method must be a static method, and the best method for a call to an instance method must be an instance method.
-### Applicable method
+### 3.7.3 Applicable method
A method is said to be *applicable* with respect to an argument list A when one of the following is true:
In addition to having an appropriate number of arguments, each argument in A mus
parameter-passing mode of the argument, and the argument type must match the parameter type, or there must be a conversion from the argument type to the parameter type.
-If the argument type is ref (§4.3.6), the corresponding parameter must also be ref, and the argument
-type for conversion purposes is the type of the property Value from the ref argument.
+If the argument type is ref ([§4.3.6][]), the corresponding parameter must also be ref, and the
+argument type for conversion purposes is the type of the property Value from the ref argument.
If the argument type is `ref`, the corresponding parameter could be `out` instead of `ref`.
each unmatched argument in A. Each additional parameter type is the element type
for the last parameter in the original method. The above rules for an applicable method are applied to this new method and argument list A.
-### Better method
+### 3.7.4 Better method
Given an argument list A with a set of argument expressions `{ E~1~, E~2~, ..., E~N~ }` and two application methods `M~P~` and `M~Q~` with parameter types `{ P~1~, P~2~, ..., P~N~ }` and
have the same value, then the following tie breaking rules are used, applied in
- If one method uses the expanded form and the other uses normal form, the method using normal form is the better method.
-### Better conversion
+### 3.7.5 Better conversion
The text below marked like this is specific to Windows PowerShell.
Conversions are ranked in the following manner, from lowest to highest:
- `T~1~[]` to `T~2~[]` where no assignable conversion between `T~1~` and `T~2~` exists - T to string where T is any type-- `T~1~` to `T~2~` where `T~1~` or `T~2~` define a custom conversion in an implementation-defined manner
+- `T~1~` to `T~2~` where `T~1~` or `T~2~` define a custom conversion in an implementation-defined
+ manner
- `T~1~` to `T~2~` where `T~1~` implements IConvertible - `T~1~` to `T~2~` where `T~1~` or `T~2~` implements the method `T~2~ op_Implicit(T1)` - `T~1~` to `T~2~` where `T~1~` or `T~2~` implements the method `T~2~ op_Explicit(T1)` - `T~1~` to `T~2~` where `T~2~` implements a constructor taking a single argument of type `T~1~` - Either of the following conversions:
- - string to `T` where `T` implements a static method `T Parse(string)` or `T Parse(string, IFormatProvider)`
- - `T~1~` to `T~2~` where `T~2~` is any enum and `T~1~` is either string or a collection of objects that
- can be converted to string
+ - string to `T` where `T` implements a static method `T Parse(string)` or
+ `T Parse(string, IFormatProvider)`
+ - `T~1~` to `T~2~` where `T~2~` is any enum and `T~1~` is either string or a collection of objects
+ that can be converted to string
- `T` to PSObject where `T` is any type - Any of the following conversions: `Language` - T to bool where `T` is any numeric type
Conversions are ranked in the following manner, from lowest to highest:
- `UInt32` to `T` where `T` is `long`, or `UInt64`, `single`, `double`, or `decimal` - `int` to `T` where `T` is `long`, `UInt64`, `single`, `double`, or `decimal` - `single` to `double`-- `T~1~` to `T~2~` where `T~2~` is a base class or interface of `T~1~`. This conversion is considered an
- assignable conversion.
+- `T~1~` to `T~2~` where `T~2~` is a base class or interface of `T~1~`. This conversion is
+ considered an assignable conversion.
- `string` to `char[]` - `T` to `T` -- This conversion is considered an assignable conversion.
conversion applies, if there is a conversion from `T~1~` to `T~2~`, the rank of
worse than the conversion from `T~1~` to `T~2~`, but better than any conversion ranked less than the conversion from `T~1~` to `T~2~`
-## Name lookup
+## 3.8 Name lookup
It is possible to have commands of different kinds all having the same name. The order in which name lookup is performed in such a case is alias, function, cmdlet, and external command.
-## Type name lookup
+## 3.9 Type name lookup
-§7.1.10 contains the statement, "A *type-literal* is represented in an implementation by some
+[§7.1.10][] contains the statement, "A *type-literal* is represented in an implementation by some
unspecified *underlying type*. As a result, a type name is a synonym for its underlying type." Example of types are `int`, `double`, `long[]`, and `Hashtable`.
the type. Otherwise, the type name is in error. This algorithm is applied for ea
generic types. However, there is no need to specify the arity (the number of arguments or operands taken by a function or operator).
-## Automatic memory management
+## 3.10 Automatic memory management
Various operators and cmdlets result in the allocation of memory for reference-type objects, such as strings and arrays. The allocation and freeing of this memory is managed by the PowerShell runtime system. That is, PowerShell provides automatic *garbage collection*.
-## Execution order
+## 3.11 Execution order
A *side effect* is a change in the state of a command's execution environment. A change to the value of a variable (via the assignment operators or the pre- and post-increment and decrement
An expression that invokes a command involves the expression that designates the
or more expressions that designate the arguments whose values are to be passed to that command. The order in which these expressions are evaluated relative to each other is unspecified.
-## Error handling
+## 3.12 Error handling
When a command fails, this is considered an *error*, and information about that error is recorded in
-an *error record*, whose type is unspecified (§4.5.15); however, this type supports subscripting.
+an *error record*, whose type is unspecified ([§4.5.15][]); however, this type supports
+subscripting.
An error falls into one of two categories. Either it terminates the operation (a *terminating error*) or it doesn't (a *non-terminating error*). With a terminating error, the error is recorded
continues.
Non-terminating errors are written to the error stream. Although that information can be redirected to a file, the error objects are first converted to strings and important information in those objects would not be captured making diagnosis difficult if not impossible. Instead, the error text
-can be redirected (§7.12) and the error object saved in a variable, as in `$Error1 = command 2>&1`.
+can be redirected ([§7.12][]) and the error object saved in a variable, as in
+`$Error1 = command 2>&1`.
The automatic variable `$Error` contains a collection of error records that represent recent errors,
-and the most recent error is in `$Error[0]`. This collection is maintained in a buffer such that
-old records are discarded as new ones are added. The automatic variable `$MaximumErrorCount` controls
+and the most recent error is in `$Error[0]`. This collection is maintained in a buffer such that old
+records are discarded as new ones are added. The automatic variable `$MaximumErrorCount` controls
the number of records that can be stored.
-`$Error` contains all of the errors from all commands mixed in together in one collection. To collect
-the errors from a specific command, use the common parameter ErrorVariable (§13.56), which allows a
-user-defined variable to be specified to hold the collection.
+`$Error` contains all of the errors from all commands mixed in together in one collection. To
+collect the errors from a specific command, use the common parameter [ErrorVariable][],
+which allows a user-defined variable to be specified to hold the collection.
-## Pipelines
+## 3.13 Pipelines
A *pipeline* is a series of one or more commands each separated by the pipe operator `|` (U+007C). Each command receives input from its predecessor and writes output to its successor. Unless the
become available, not when the entire collection has been produced.
When processing a collection, a command can be written such that it can do special processing before the initial element and after the final element.
-## Modules
+## 3.14 Modules
A *module* is a self-contained reusable unit that allows PowerShell code to be partitioned, organized, and abstracted. A module can contain commands (such as cmdlets and functions) and items
organized, and abstracted. A module can contain commands (such as cmdlets and fu
Once a module has been created, it must be *imported* into a session before the commands and items within it can be used. Once imported, commands and items behave as if they were defined locally. A
-module is imported explicitly with the `Import-Module` (§13.28) command. A module may also be
-imported automatically as determined in an implementation defined manner.
+module is imported explicitly with the `Import-Module` command. A module may also be imported
+automatically as determined in an implementation defined manner.
-The type of an object that represents a module is described in §4.5.12.
+The type of an object that represents a module is described in [§4.5.12][].
-Modules are discussed in detail in §11.
+Modules are discussed in detail in [§11.][]
-## Wildcard expressions
+## 3.15 Wildcard expressions
A wildcard expression may contain zero or more of the following elements:
A wildcard expression may contain zero or more of the following elements:
> [The Open Group Base Specifications: Pattern Matching", IEEE Std 1003.1, 2004 Edition.](http://www.opengroup.org/onlinepubs/000095399/utilities/xcu_chap02.html#tag_02_13_01). > However, in PowerShell, the escape character is backtick, not backslash.
-## Regular expressions
+## 3.16 Regular expressions
A regular expression may contain zero or more of the following elements:
Quantifiers available in Microsoft .NET Framework regular expressions are suppor
| `{n}` | Specifies exactly *n* matches; for example, `(pizza){2}`. | | `{n,}` | Specifies at least *n* matches; for example, `(abc){2,}`. | | `{n,m}` | Specifies at least *n*, but no more than *m*, matches. |+
+<!-- reference links -->
+[§11.]: chapter-11.md#11-modules
+[§3.1.1]: chapter-03.md#311-aliases
+[§3.1.2]: chapter-03.md#312-environment-variables
+[§3.1.3]: chapter-03.md#313-file-system
+[§3.1.4]: chapter-03.md#314-functions
+[§3.1.5]: chapter-03.md#315-variables
+[§3.1]: chapter-03.md#31-providers-and-drives
+[§3.14]: chapter-03.md#314-modules
+[§3.3]: chapter-03.md#33-items
+[§3.4]: chapter-03.md#34-path-names
+[§3.5.3]: chapter-03.md#353-variable-name-scope
+[§3.5.5]: chapter-03.md#355-dot-source-notation
+[§3.7.3]: chapter-03.md#373-applicable-method
+[§3.7.4]: chapter-03.md#374-better-method
+[§4.3.2]: chapter-04.md#432-arrays
+[§4.3.6]: chapter-04.md#436-the-ref-type
+[§4.3.8]: chapter-04.md#438-the-math-type
+[§4.5.1]: chapter-04.md#451-provider-description-type
+[§4.5.10]: chapter-04.md#4510-function-description-type
+[§4.5.11]: chapter-04.md#4511-filter-description-type
+[§4.5.12]: chapter-04.md#4512-module-description-type
+[§4.5.15]: chapter-04.md#4515-error-record-description-type
+[§4.5.17]: chapter-04.md#4517-directory-description-type
+[§4.5.18]: chapter-04.md#4518-file-description-type
+[§4.5.2]: chapter-04.md#452-drive-description-type
+[§4.5.3]: chapter-04.md#453-variable-description-type
+[§4.5.4]: chapter-04.md#454-alias-description-type
+[§4.5.5]: chapter-04.md#455-working-location-description-type
+[§4.5.6]: chapter-04.md#456-environment-variable-description-type
+[§7.1.10]: chapter-07.md#7110-type-literal-expression
+[§7.1.3]: chapter-07.md#713-invocation-expressions
+[§7.12]: chapter-07.md#712-redirection-operators
+[§8.10.1]: chapter-08.md#8101-filter-functions
+[§8.10]: chapter-08.md#810-function-definitions
+[ErrorVariable]: /powershell/module/microsoft.powershell.core/about/about_commonparameters
lang-spec Chapter 04 https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/lang-spec/chapter-04.md
description: In PowerShell, each value has a type, and types fall into one of tw
Last updated 05/19/2021 Title: Types ---
-# Types
+# 4. Types
In PowerShell, each value has a type, and types fall into one of two main categories: *value types* and *reference types*. Consider the type `int`, which is typical of value types. A value of type
making a copy of the object as well.
A *numeric* type is one that allows representation of integer or fractional values, and that supports arithmetic operations on those values. The set of numerical types includes the integer
-(§4.2.3) and real number (§4.2.4) types, but does not include bool (§4.2.1) or char (§4.2.2). An
-implementation may provide other numeric types (such as signed byte, unsigned integer, and integers
-of other sizes).
+([§4.2.3][]) and real number ([§4.2.4][]) types, but does not include bool ([§4.2.1][]) or char
+([§4.2.2][]). An implementation may provide other numeric types (such as signed byte, unsigned
+integer, and integers of other sizes).
A *collection* is a group of one or more related items, which need not have the same type. Examples of collection types are arrays, stacks, queues, lists, and hash tables. A program can *enumerate* (or *iterate*) over the elements in a collection, getting access to each element one at a time.
-Common ways to do this are with the foreach statement (§8.4.4) and the `ForEach-Object` cmdlet
-(§13.12). The type of an object that represents an enumerator is described in §4.5.16.
+Common ways to do this are with the foreach statement ([§8.4.4][]) and the
+[ForEach-Object](xref:Microsoft.PowerShell.Core.ForEach-Object) cmdlet. The type of an object that
+represents an enumerator is described in [§4.5.16][].
In this chapter, there are tables that list the accessible members for a given type. For methods, the **Type** is written with the following form: *returnType*/*argumentTypeList*. If the argument
Many collection classes are defined as part of the **System.Collections** or
`ICollection`, `IComparer`, `IEnumerable`, `IList`, `IDictionary`, and `IDictionaryEnumerator` and their generic equivalents.
-## Special types
+## 4.1 Special types
-### The void type
+### 4.1.1 The void type
This type cannot be instantiated. It provides a means to discard a value explicitly using the cast
-operator (§7.2.9).
+operator ([§7.2.9][]).
-### The null type
+### 4.1.2 The null type
-The *null type* has one instance, the automatic variable $null (§2.3.2.2), also known as the null
-value. This value provides a means for expressing "nothingness" in reference contexts. The
+The *null type* has one instance, the automatic variable $null ([§2.3.2.2][]), also known as the
+null value. This value provides a means for expressing "nothingness" in reference contexts. The
characteristics of this type are unspecified.
-### The object type
+### 4.1.3 The object type
-Every type in PowerShell except the null type (§4.1.2) is derived directly or indirectly from the
-type object, so object is the ultimate base type of all non-null types. A variable constrained
-(§5.3) to type object is really not constrained at all, as it can contain a value of any type.
+Every type in PowerShell except the null type ([§4.1.2][]) is derived directly or indirectly from
+the type object, so object is the ultimate base type of all non-null types. A variable constrained
+([§5.3][]) to type object is really not constrained at all, as it can contain a value of any type.
-## Value types
+## 4.2 Value types
-### Boolean
+### 4.2.1 Boolean
The Boolean type is `bool`. There are only two values of this type, Fal****se and **True**,
-represented by the automatic variables `$false `and `$true`, respectively (§2.3.2.2).
+represented by the automatic variables `$false` and `$true`, respectively ([§2.3.2.2][]).
In PowerShell, `bool` maps to `System.Boolean`.
-### Character
+### 4.2.2 Character
A character value has type char, which is capable of storing any UTF-16-encoded 16-bit Unicode code point.
The type char has the following accessible members:
Windows PowerShell: char maps to System.Char.
-### Integer
+### 4.2.3 Integer
There are two signed integer types, both of use two's-complement representation for negative values:
Type `byte` has the following accessible members:
In PowerShell, `byte`, `int`, and `long` map to `System.Byte`, `System.Int32`, and `System.Int64`, respectively.
-### Real number
+### 4.2.4 Real number
-#### float and double
+#### 4.2.4.1 float and double
There are two real (or floating-point) types:
Type double has the following accessible members:
In PowerShell, `float` and `double` map to `System.Single` and `System.Double`, respectively.
-#### decimal
+#### 4.2.4.2 decimal
Type decimal uses a 128-bit representation. At a minimum it must support a scale *s* such that 0 <= *s* <= at least 28, and a value range -79228162514264337593543950335 to
In PowerShell, `decimal` maps to `System.Decimal`. The representation of decimal
- bits 24ΓÇæ30 are zero - bit 31 is the sign (0 for positive, 1 for negative)
-### The switch type
+### 4.2.5 The switch type
-This type is used to constrain the type of a parameter in a command (§8.10.5). If an argument having
-the corresponding parameter name is present the parameter tests $true; otherwise, it tests `$false`.
+This type is used to constrain the type of a parameter in a command ([§8.10.5][]). If an argument
+having the corresponding parameter name is present the parameter tests $true; otherwise, it tests
+`$false`.
In PowerShell, `switch` maps to `System.Management.Automation.SwitchParameter`.
-### Enumeration types
+### 4.2.6 Enumeration types
An enumeration type is one that defines a set of named constants representing all the possible values that can be assigned to an object of that enumeration type. In some cases, the set of values are such that only one value can be represented at a time. In other cases, the set of values are
-distinct powers of two, and by using the -bor operator (§7.8.5), multiple values can be encoded in
-the same object.
+distinct powers of two, and by using the -bor operator ([§7.8.5][]), multiple values can be encoded
+in the same object.
The PowerShell environment provides a number of enumeration types, as described in the following sections.
-#### Action-Preference type
+#### 4.2.6.1 Action-Preference type
This implementation-defined type has the following mutually exclusive-valued accessible members:
exclusive-valued accessible members:
In PowerShell, this type is `System.Management.Automation.ActionPreference`.
-#### Confirm-Impact type
+#### 4.2.6.2 Confirm-Impact type
This implementation-defined type has the following mutually exclusive-valued accessible members:
This implementation-defined type has the following mutually exclusive-valued acc
In PowerShell, this type is `System.Management.Automation.ConfirmImpact`.
-#### File-Attributes type
+#### 4.2.6.3 File-Attributes type
This implementation-defined type has the following accessible members, which can be combined:
This implementation-defined type has the following accessible members, which can
In PowerShell, this type is System.IO.FileAttributes with attribute FlagsAttribute.
-#### Regular-Expression-Option type
+#### 4.2.6.4 Regular-Expression-Option type
This implementation-defined type has the following accessible members, which can be combined:
In PowerShell, this type is `System.Text.RegularExpressions.RegexOptions` with a
`ECMAScript`, `ExplicitCapture`, `IgnorePatternWhitespace`, `Multiline`, `RightToLeft`, `Singleline`.
-## Reference types
+## 4.3 Reference types
-### Strings
+### 4.3.1 Strings
A string value has type string and is an immutable sequence of zero or more characters of type char each containing a UTF-16-encoded 16-bit Unicode code point.
Type string has the following accessible members:
In PowerShell, `string` maps to `System.String`.
-### Arrays
+### 4.3.2 Arrays
All array types are derived from the type `Array`. This type has the following accessible members:
Copy(<em>source</em>, <em>sourceIndex</em>, <em>destination</em>, <em>destinatio
</tbody> </table>
-For more details on arrays, see §9.
+For more details on arrays, see [§9.][]
In PowerShell, `Array` maps to `System.Array`.
-### Hashtables
+### 4.3.3 Hashtables
Type Hashtable has the following accessible members:
In PowerShell, `Hashtable` maps to `System.Collections.Hashtable`. `Hashtable` e
in an object of type `DictionaryEntry`, and the collections returned by Keys and Values have type `ICollection`.
-### The xml type
+### 4.3.4 The xml type
Type xml implements the W3C Document Object Model (DOM) Level 1 Core and the Core DOM Level 2. The DOM is an in-memory (cache) tree representation of an XML document and enables the navigation and
-editing of this document. This type supports the subscript operator [] (§7.1.4.4).
+editing of this document. This type supports the subscript operator [] ([§7.1.4.4][]).
In PowerShell, `xml` maps to `System.Xml.XmlDocument`.
-### The regex type
+### 4.3.5 The regex type
Type `regex` provides machinery for supporting regular expression processing. It is used to
-constrain the type of a parameter (§5.3) whose corresponding argument might contain a regular
+constrain the type of a parameter ([§5.3][]) whose corresponding argument might contain a regular
expression. In PowerShell, `regex` maps to `System.Text.RegularExpressions.Regex`.
-### The ref type
+### 4.3.6 The ref type
Ordinarily, arguments are passed to commands by value. In the case of an argument having some value type a copy of the value is passed. In the case of an argument having some reference type a copy of
As shown, both the argument and its corresponding parameter must be declared `re
In PowerShell, `ref` maps to `System.Management.Automation.PSReference`.
-### The scriptblock type
+### 4.3.7 The scriptblock type
-Type `scriptblock` represents a precompiled block of script text (§7.1.8) that can be used as a
+Type `scriptblock` represents a precompiled block of script text ([§7.1.8][]) that can be used as a
single unit. It has the following accessible members: <table>
single unit. It has the following accessible members:
<tr class="odd"> <td>Module</td> <td>Instance property (read-only)</td>
-<td>implementation defined (§4.5.12)</td>
+<td>implementation defined ([§4.5.12][])</td>
<td>Gets information about the module in which the script block is defined.</td> </tr> <tr class="even">
single unit. It has the following accessible members:
In PowerShell, `scriptblock` maps to `System.Management.Automation.ScriptBlock`. `Invoke` returns a collection of `PsObject`.
-### The math type
+### 4.3.8 The math type
Type `math` provides access to some constants and methods useful in mathematical computations. It has the following accessible members:
has the following accessible members:
In PowerShell, `Math` maps to `System.Math`.
-### The ordered type
+### 4.3.9 The ordered type
Type `ordered` is a pseudo type used only for conversions.
-### The pscustomobject type
+### 4.3.10 The pscustomobject type
Type `pscustomobject` is a pseudo type used only for conversions.
-## Generic types
+## 4.4 Generic types
A number of programming languages and environments provide types that can be *specialized*. Many of these types are referred to as *container types*, as instances of them are able to contain objects
handling some subset of types when it is used. For example,
- A stack of stack of strings might be written as `Stack[Stack[string]]`. Although PowerShell does not define any built-in generic types, it can use such types if they are
-provided by the host environment. See the syntax in §7.1.10.
+provided by the host environment. See the syntax in [§7.1.10][].
The complete name for the type `Stack[string]` suggested above is `System.Collections.Generic.Stack[string]`. The complete name for the type `Dictionary[int,string]` suggested above is `System.Collections.Generic.Dictionary[int,string]`.
-## Anonymous types
+## 4.5 Anonymous types
In some circumstances, an implementation of PowerShell creates objects of some type, and those objects have members accessible to script. However, the actual name of those types need not be
specified, so long as the accessible members are specified sufficiently for them
is, scripts can save objects of those types and access their members without actually knowing those types' names. The following subsections specify these types.
-### Provider description type
+### 4.5.1 Provider description type
This type encapsulates the state of a provider. It has the following accessible members:
-| **Member** | **Member Kind** | **Type** | **Purpose** |
-| ---------- | ----------------------------- | ------------------------------- | ----------------------------------------- |
-| Drives | Instance property (read-only) | Implementation defined (§4.5.2) | A collection of drive description objects |
-| Name | Instance property (read-only) | string | The name of the provider |
+| **Member** | **Member Kind** | **Type** | **Purpose** |
+| ---------- | ----------------------------- | ----------------------------------- | ----------------------------------------- |
+| Drives | Instance property (read-only) | Implementation defined ([§4.5.2][]) | A collection of drive description objects |
+| Name | Instance property (read-only) | string | The name of the provider |
In PowerShell, this type is `System.Management.Automation.ProviderInfo`.
-### Drive description type
+### 4.5.2 Drive description type
This type encapsulates the state of a drive. It has the following accessible members:
-| **Member** | **Member Kind** | **Type** | **Purpose** |
-| --------------- | ------------------------------ | -------- | -------------------------------------------------- |
-| CurrentLocation | Instance property (read-write) | string | The current working location (§3.1.4) of the drive |
-| Description | Instance property (read-write) | string | The description of the drive |
-| Name | Instance property (read-only) | string | The name of the drive |
-| Root | Instance property (read-only) | string | The name of the drive |
+| **Member** | **Member Kind** | **Type** | **Purpose** |
+| --------------- | ------------------------------ | -------- | ------------------------------------------------------ |
+| CurrentLocation | Instance property (read-write) | string | The current working location ([§3.1.4][]) of the drive |
+| Description | Instance property (read-write) | string | The description of the drive |
+| Name | Instance property (read-only) | string | The name of the drive |
+| Root | Instance property (read-only) | string | The name of the drive |
In PowerShell, this type is `System.Management.Automation.PSDriveInfo`.
-### Variable description type
+### 4.5.3 Variable description type
This type encapsulates the state of a variable. It has the following accessible members:
-| **Member** | **Member Kind** | **Type** | **Purpose** |
-| ----------- | ------------------------------ | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Attributes | Instance property (read-only) | Implementation defined | A collection of attributes |
-| Description | Instance property (read-write) | string | The description assigned to the variable via the New-Variable (§13.37) or Set-Variable (§13.50) cmdlets. |
-| Module | Instance property (read-only) | Implementation defined (§4.5.12) | The module from which this variable was exported |
-| ModuleName | Instance property (read-only) | string | The module in which this variable was defined |
-| Name | Instance property (read-only) | string | The name assigned to the variable when it was created in the PowerShell language or via the New-Variable (§13.37) and Set-Variable (§13.50) cmdlets. |
-| Options | Instance property (read-write) | string | The options assigned to the variable via the New-Variable (§13.37) or Set-Variable (§13.50) cmdlets. |
-| Value | Instance property (read-write) | object | The value assigned to the variable when it was assigned in the PowerShell language or via the New-Variable (§13.37) and Set-Variable (§13.50) cmdlets. |
+| **Member** | **Member Kind** | **Type** | **Purpose** |
+| ----------- | ------------------------------ | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Attributes | Instance property (read-only) | Implementation defined | A collection of attributes |
+| Description | Instance property (read-write) | string | The description assigned to the variable via the [New-Variable](xref:Microsoft.PowerShell.Utility.New-Variable) or [Set-Variable](xref:Microsoft.PowerShell.Utility.Set-Variable) cmdlets. |
+| Module | Instance property (read-only) | Implementation defined ([§4.5.12][]) | The module from which this variable was exported |
+| ModuleName | Instance property (read-only) | string | The module in which this variable was defined |
+| Name | Instance property (read-only) | string | The name assigned to the variable when it was created in the PowerShell language or via the `New-Variable` and `Set-Variable` cmdlets. |
+| Options | Instance property (read-write) | string | The options assigned to the variable via the `New-Variable` and `Set-Variable` cmdlets. |
+| Value | Instance property (read-write) | object | The value assigned to the variable when it was assigned in the PowerShell language or via the `New-Variable` and `Set-Variable` cmdlets. |
In PowerShell, this type is `System.Management.Automation.PSVariable`. Windows PowerShell: The type of the attribute collection is System.Management.Automation.PSVariableAttributeCollection.
-### Alias description type
+### 4.5.4 Alias description type
This type encapsulates the state of an alias. It has the following accessible members:
-| **Member** | **Member Kind** | **Type** | **Purpose** |
-| ----------------- | ------------------------------ | --------------------------------- | -------------------------------------------------------------------------------------------------------------- |
-| CommandType | Instance property (read-only) | Implementation defined | Should compare equal with "Alias". |
-| Definition | Instance property (read-only) | string | The command or alias to which the alias was assigned via the New-Alias (§13.33) or Set-Alias (§13.46) cmdlets. |
-| Description | Instance property (read-write) | string | The description assigned to the alias via the New-Alias (§13.33) or Set-Alias (§13.46) cmdlets. |
-| Module | Instance property (read-only) | Implementation defined (§4.5.12) | The module from which this alias was exported |
-| ModuleName | Instance property (read-only) | string | The module in which this alias was defined |
-| Name | Instance property (read-only) | string | The name assigned to the alias when it was created via the New-Alias (§13.33) or Set-Alias (§13.46) cmdlets. |
-| Options | Instance property (read-write) | string | The options assigned to the alias via the New-Alias (§13.33) or Set-Alias (§13.46) cmdlets. |
-| OutputType | Instance property (read-only) | Implementation defined collection | Specifies the types of the values output by the command to which the alias refers. |
-| Parameters | Instance property (read-only) | Implementation defined collection | The parameters of the command. |
-| ParameterSets | Instance property (read-only) | Implementation defined collection | Information about the parameter sets associated with the command. |
-| ReferencedCommand | Instance property (read-only) | Implementation defined | Information about the command that is immediately referenced by this alias. |
-| ResolvedCommand | Instance property (read-only) | Implementation defined | Information about the command to which the alias eventually resolves. |
+| **Member** | **Member Kind** | **Type** | **Purpose** |
+| ----------------- | ------------------------------ | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| CommandType | Instance property (read-only) | Implementation defined | Should compare equal with "Alias". |
+| Definition | Instance property (read-only) | string | The command or alias to which the alias was assigned via the [New-Alias](xref:Microsoft.PowerShell.Utility.New-Alias) or [Set-Alias](xref:Microsoft.PowerShell.Utility.Set-Alias) cmdlets. |
+| Description | Instance property (read-write) | string | The description assigned to the alias via the `New-Alias` or `Set-Alias` cmdlets. |
+| Module | Instance property (read-only) | Implementation defined ([§4.5.12][]) | The module from which this alias was exported |
+| ModuleName | Instance property (read-only) | string | The module in which this alias was defined |
+| Name | Instance property (read-only) | string | The name assigned to the alias when it was created via the `New-Alias` or `Set-Alias` cmdlets. |
+| Options | Instance property (read-write) | string | The options assigned to the alias via the New-Alias `New-Alias` or `Set-Alias` cmdlets. |
+| OutputType | Instance property (read-only) | Implementation defined collection | Specifies the types of the values output by the command to which the alias refers. |
+| Parameters | Instance property (read-only) | Implementation defined collection | The parameters of the command. |
+| ParameterSets | Instance property (read-only) | Implementation defined collection | Information about the parameter sets associated with the command. |
+| ReferencedCommand | Instance property (read-only) | Implementation defined | Information about the command that is immediately referenced by this alias. |
+| ResolvedCommand | Instance property (read-only) | Implementation defined | Information about the command to which the alias eventually resolves. |
In PowerShell, this type is `System.Management.Automation.AliasInfo`.
-### Working location description type
+### 4.5.5 Working location description type
This type encapsulates the state of a working location. It has the following accessible members:
-| **Member** | **Member Kind** | **Type** | **Purpose** |
-| ------------ | ----------------------------- | ------------------------------- | -------------------------------- |
-| Drive | Instance property (read-only) | Implementation defined (§4.5.2) | A drive description object |
-| Path | Instance property (read-only) | string | The working location |
-| Provider | Instance property (read-only) | Implementation defined (§4.5.1) | The provider |
-| ProviderPath | Instance property (read-only) | string | The current path of the provider |
+| **Member** | **Member Kind** | **Type** | **Purpose** |
+| ------------ | ----------------------------- | ----------------------------------- | -------------------------------- |
+| Drive | Instance property (read-only) | Implementation defined ([§4.5.2][]) | A drive description object |
+| Path | Instance property (read-only) | string | The working location |
+| Provider | Instance property (read-only) | Implementation defined ([§4.5.1][]) | The provider |
+| ProviderPath | Instance property (read-only) | string | The current path of the provider |
A stack of working locations is a collection of working location objects, as described above.
In PowerShell, a current working location is represented by an object of type
`System.Management.Automation.PathInfo`. A stack of working locations is represented by an object of type `System.Management.Automation.PathInfoStack`, which is a collection of `PathInfo` objects.
-### Environment variable description type
+### 4.5.6 Environment variable description type
This type encapsulates the state of an environment variable. It has the following accessible members:
In PowerShell, this type is `System.Collections.DictionaryEntry`. The name of th
dictionary key. The value of the environment variable is the dictionary value. **Name** is an `AliasProperty` that equates to **Key**.
-### Application description type
+### 4.5.7 Application description type
This type encapsulates the state of an application. It has the following accessible members:
-| **Member** | **Member Kind** | **Type** | **Purpose** |
-| ------------- | ------------------------------ | --------------------------------- | ----------------------------------------------------------------- |
-| CommandType | Instance property (read-only) | Implementation defined | Should compare equal with "Application". |
-| Definition | Instance property (read-only) | string | A description of the application. |
-| Extension | Instance property (read-write) | string | The extension of the application file. |
-| Module | Instance property (read-only) | Implementation defined (§4.5.12) | The module that defines this command. |
-| ModuleName | Instance property (read-only) | string | The name of the module that defines the command. |
-| Name | Instance property (read-only) | string | The name of the command. |
-| OutputType | Instance property (read-only) | Implementation defined collection | Specifies the types of the values output by the command. |
-| Parameters | Instance property (read-only) | Implementation defined collection | The parameters of the command. |
-| ParameterSets | Instance property (read-only) | Implementation defined collection | Information about the parameter sets associated with the command. |
-| Path | Instance property (read-only) | string | Gets the path of the application file. |
+| **Member** | **Member Kind** | **Type** | **Purpose** |
+| ------------- | ------------------------------ | ------------------------------------ | ----------------------------------------------------------------- |
+| CommandType | Instance property (read-only) | Implementation defined | Should compare equal with "Application". |
+| Definition | Instance property (read-only) | string | A description of the application. |
+| Extension | Instance property (read-write) | string | The extension of the application file. |
+| Module | Instance property (read-only) | Implementation defined ([§4.5.12][]) | The module that defines this command. |
+| ModuleName | Instance property (read-only) | string | The name of the module that defines the command. |
+| Name | Instance property (read-only) | string | The name of the command. |
+| OutputType | Instance property (read-only) | Implementation defined collection | Specifies the types of the values output by the command. |
+| Parameters | Instance property (read-only) | Implementation defined collection | The parameters of the command. |
+| ParameterSets | Instance property (read-only) | Implementation defined collection | Information about the parameter sets associated with the command. |
+| Path | Instance property (read-only) | string | Gets the path of the application file. |
In PowerShell, this type is `System.Management.Automation.ApplicationInfo`.
-### Cmdlet description type
+### 4.5.8 Cmdlet description type
This type encapsulates the state of a cmdlet. It has the following accessible members:
-| **Member** | **Member Kind** | **Type** | **Purpose** |
-| ------------------- | ------------------------------ | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
-| CommandType | Instance property (read-only) | Implementation defined | Should compare equal with "Cmdlet". |
-| DefaultParameterSet | Instance property (read-only) | Implementation defined | The default parameter set that is used if PowerShell cannot determine which parameter set to use based on the supplied arguments. |
-| Definition | Instance property (read-only) | string | A description of the cmdlet. |
-| HelpFile | Instance property (read-write) | string | The path to the Help file for the cmdlet. |
-| ImplementingType | Instance property (read-write) | Implementation defined | The type that implements the cmdlet. |
-| Module | Instance property (read-only) | Implementation defined (§4.5.12) | The module that defines this cmdlet. |
-| ModuleName | Instance property (read-only) | string | The name of the module that defines the cmdlet. |
-| Name | Instance property (read-only) | string | The name of the cmdlet. |
-| Noun | Instance property (read-only) | string | The noun name of the cmdlet. |
-| OutputType | Instance property (read-only) | Implementation defined collection | Specifies the types of the values output by the cmdlet. |
-| Parameters | Instance property (read-only) | Implementation defined collection | The parameters of the cmdlet. |
-| ParameterSets | Instance property (read-only) | Implementation defined collection | Information about the parameter sets associated with the cmdlet. |
-| Verb | Instance property (read-only) | string | The verb name of the cmdlet. |
-| PSSnapIn | Instance property (read-only) | Implementation defined | Windows PowerShell: Information about the Windows Powershell snap-in that is used to register the cmdlet. |
+| **Member** | **Member Kind** | **Type** | **Purpose** |
+| ------------------- | ------------------------------ | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
+| CommandType | Instance property (read-only) | Implementation defined | Should compare equal with "Cmdlet". |
+| DefaultParameterSet | Instance property (read-only) | Implementation defined | The default parameter set that is used if PowerShell cannot determine which parameter set to use based on the supplied arguments. |
+| Definition | Instance property (read-only) | string | A description of the cmdlet. |
+| HelpFile | Instance property (read-write) | string | The path to the Help file for the cmdlet. |
+| ImplementingType | Instance property (read-write) | Implementation defined | The type that implements the cmdlet. |
+| Module | Instance property (read-only) | Implementation defined ([§4.5.12][]) | The module that defines this cmdlet. |
+| ModuleName | Instance property (read-only) | string | The name of the module that defines the cmdlet. |
+| Name | Instance property (read-only) | string | The name of the cmdlet. |
+| Noun | Instance property (read-only) | string | The noun name of the cmdlet. |
+| OutputType | Instance property (read-only) | Implementation defined collection | Specifies the types of the values output by the cmdlet. |
+| Parameters | Instance property (read-only) | Implementation defined collection | The parameters of the cmdlet. |
+| ParameterSets | Instance property (read-only) | Implementation defined collection | Information about the parameter sets associated with the cmdlet. |
+| Verb | Instance property (read-only) | string | The verb name of the cmdlet. |
+| PSSnapIn | Instance property (read-only) | Implementation defined | Windows PowerShell: Information about the Windows Powershell snap-in that is used to register the cmdlet. |
In PowerShell, this type is `System.Management.Automation.CmdletInfo`.
-### External script description type
+### 4.5.9 External script description type
This type encapsulates the state of an external script (one that is directly executable by PowerShell, but is not built in). It has the following accessible members:
-| **Member** | **Member Kind** | **Type** | **Purpose** |
-| ---------------- | ----------------------------- | --------------------------------- | ---------------------------------------------------------------------------- |
-| CommandType | Instance property (read-only) | Implementation defined | Should compare equal with "ExternalScript". |
-| Definition | Instance property (read-only) | string | A definition of the script. |
-| Module | Instance property (read-only) | Implementation defined (§4.5.12) | The module that defines this script. |
-| ModuleName | Instance property (read-only) | string | The name of the module that defines the script. |
-| Name | Instance property (read-only) | string | The name of the script. |
-| OriginalEncoding | Instance property (read-only) | Implementation defined | The original encoding used to convert the characters of the script to bytes. |
-| OutputType | Instance property (read-only) | Implementation defined collection | Specifies the types of the values output by the script. |
-| Parameters | Instance property (read-only) | Implementation defined collection | The parameters of the script. |
-| ParameterSets | Instance property (read-only) | Implementation defined collection | Information about the parameter sets associated with the script. |
-| Path | Instance property (read-only) | string | The path to the script file. |
-| ScriptBlock | Instance property (read-only) | scriptblock | The external script. |
-| ScriptContents | Instance property (read-only) | string | The original contents of the script. |
+| **Member** | **Member Kind** | **Type** | **Purpose** |
+| ---------------- | ----------------------------- | ------------------------------------ | ---------------------------------------------------------------------------- |
+| CommandType | Instance property (read-only) | Implementation defined | Should compare equal with "ExternalScript". |
+| Definition | Instance property (read-only) | string | A definition of the script. |
+| Module | Instance property (read-only) | Implementation defined ([§4.5.12][]) | The module that defines this script. |
+| ModuleName | Instance property (read-only) | string | The name of the module that defines the script. |
+| Name | Instance property (read-only) | string | The name of the script. |
+| OriginalEncoding | Instance property (read-only) | Implementation defined | The original encoding used to convert the characters of the script to bytes. |
+| OutputType | Instance property (read-only) | Implementation defined collection | Specifies the types of the values output by the script. |
+| Parameters | Instance property (read-only) | Implementation defined collection | The parameters of the script. |
+| ParameterSets | Instance property (read-only) | Implementation defined collection | Information about the parameter sets associated with the script. |
+| Path | Instance property (read-only) | string | The path to the script file. |
+| ScriptBlock | Instance property (read-only) | scriptblock | The external script. |
+| ScriptContents | Instance property (read-only) | string | The original contents of the script. |
In PowerShell, this type is `System.Management.Automation.ExternalScriptInfo`.
-### Function description type
+### 4.5.10 Function description type
This type encapsulates the state of a function. It has the following accessible members:
-| **Member** | **Member Kind** | **Type** | **Purpose** |
-| ------------------- | ------------------------------ | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| CmdletBinding | Instance property (read-only) | bool | Indicates whether the function uses the same parameter binding that compiled cmdlets use (see §12.3.5). |
-| CommandType | Instance property (read-only) | Implementation defined | Can be compared for equality with "Function" or "Filter" to see which of those this object represents. |
-| DefaultParameterSet | Instance property (read-only) | string | Specifies the parameter set to use if that cannot be determined from the arguments (see §12.3.5). |
-| Definition | Instance property (read-only) | string | A string version of ScriptBlock |
-| Description | Instance property (read-write) | string | The description of the function. |
-| Module | Instance property (read-only) | Implementation defined (§4.5.12) | The module from which this function was exported |
-| ModuleName | Instance property (read-only) | string | The module in which this function was defined |
-| Name | Instance property (read-only) | string | The name of the function |
-| Options | Instance property (read-write) | Implementation defined | The scope options for the function (§3.5.4). |
-| OutputType | Instance property (read-only) | Implementation defined collection | Specifies the types of the values output, in order (see §12.3.6). |
-| Parameters | Instance property (read-only) | Implementation defined collection | Specifies the parameter names, in order. If the function acts like a cmdlet (see CmdletBinding above) the common parameters (§13.56) are included at the end of the collection. |
-| ParameterSets | Instance property (read-only) | Implementation defined collection | Information about the parameter sets associated with the command. For each parameter, the result shows the parameter name and type, and indicates if the parameter is mandatory, by position or a switch parameter. If the function acts like a cmdlet (see CmdletBinding above) the common parameters (§13.56) are included at the end of the collection. |
-| ScriptBlock | Instance property (read-only) | scriptblock (§4.3.6) | The body of the function |
+| **Member** | **Member Kind** | **Type** | **Purpose** |
+| ------------------- | ------------------------------ | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| CmdletBinding | Instance property (read-only) | bool | Indicates whether the function uses the same parameter binding that compiled cmdlets use (see [§12.3.5][]). |
+| CommandType | Instance property (read-only) | Implementation defined | Can be compared for equality with "Function" or "Filter" to see which of those this object represents. |
+| DefaultParameterSet | Instance property (read-only) | string | Specifies the parameter set to use if that cannot be determined from the arguments (see [§12.3.5][]). |
+| Definition | Instance property (read-only) | string | A string version of ScriptBlock |
+| Description | Instance property (read-write) | string | The description of the function. |
+| Module | Instance property (read-only) | Implementation defined ([§4.5.12][]) | The module from which this function was exported |
+| ModuleName | Instance property (read-only) | string | The module in which this function was defined |
+| Name | Instance property (read-only) | string | The name of the function |
+| Options | Instance property (read-write) | Implementation defined | The scope options for the function ([§3.5.4][]). |
+| OutputType | Instance property (read-only) | Implementation defined collection | Specifies the types of the values output, in order (see [§12.3.6][]). |
+| Parameters | Instance property (read-only) | Implementation defined collection | Specifies the parameter names, in order. If the function acts like a cmdlet (see CmdletBinding above) the [common parameters][] are included at the end of the collection. |
+| ParameterSets | Instance property (read-only) | Implementation defined collection | Information about the parameter sets associated with the command. For each parameter, the result shows the parameter name and type, and indicates if the parameter is mandatory, by position or a switch parameter. If the function acts like a cmdlet (see CmdletBinding above) the [common parameters][] are included at the end of the collection. |
+| ScriptBlock | Instance property (read-only) | scriptblock ([§4.3.6][]) | The body of the function |
In PowerShell, this type is `System.Management.Automation.FunctionInfo`.
In PowerShell, this type is `System.Management.Automation.FunctionInfo`.
- Visibility has type `System.Management.Automation.SessionStateEntryVisibility`. - PowerShell also has a property called **Visibility**.
-### Filter description type
+### 4.5.11 Filter description type
This type encapsulates the state of a filter. It has the same set of accessible members as the
-function description type (§4.5.10).
+function description type ([§4.5.10][]).
In PowerShell, this type is `System.Management.Automation.FilterInfo`. It has the same set of
-properties as `System.Management.Automation.FunctionInfo` (§4.5.11).
+properties as `System.Management.Automation.FunctionInfo` ([§4.5.11][]).
-### Module description type
+### 4.5.12 Module description type
This type encapsulates the state of a module. It has the following accessible members:
This type encapsulates the state of a module. It has the following accessible me
In PowerShell, this type is `System.Management.Automation.PSModuleInfo`. The type of `ModuleType` is `System.Management.Automation.ModuleType`.
-### Custom object description type
+### 4.5.13 Custom object description type
This type encapsulates the state of a custom object. It has no accessible members. In PowerShell, this type is `System.Management.Automation.PSCustomObject`. The cmdlets `Import-Module` and `New-Object` can generate an object of this type.
-### Command description type
+### 4.5.14 Command description type
The automatic variable `$PsCmdlet` is an object that represents the cmdlet or function being executed. The type of this object is implementation defined; it has the following accessible
members:
In PowerShell, this type is System.Management.Automation.PSScriptCmdlet.
-### Error record description type
+### 4.5.15 Error record description type
The automatic variable `$Error` contains a collection of error records that represent recent errors
-(§3.12). Although the type of this collection is unspecified, it does support subscripting to get
+([§3.12][]). Although the type of this collection is unspecified, it does support subscripting to get
access to individual error records. In PowerShell, the collection type is `System.Collections.ArrayList`. The type of an individual
following public properties:
- PipelineIterationInfo - Gets the status of the pipeline when this error record was created - TargetObject - Gets the object that was being processed when the error occurred.
-### Enumerator description type
+### 4.5.16 Enumerator description type
A number of variables are enumerators for collections (§4). The automatic variable `$foreach` is the enumerator created for any `foreach` statement. The automatic variable `$input` is the enumerator
collection, an exception of type `InvalidOperationException` is raised. For `$fo
`System.Collections.ArrayList+ArrayListEnumeratorSimple`. For `$switch`, this type is `System.Array+SZArrayEnumerator`.
-### Directory description type
+### 4.5.17 Directory description type
-The cmdlet `New-Item` (§13.34) can create items of various kinds including FileSystem directories.
-The type of a directory description object is implementation defined; it has the following
-accessible members:
+The cmdlet [New-Item](xref:Microsoft.PowerShell.Management.New-Item) can create items of various
+kinds including FileSystem directories. The type of a directory description object is implementation
+defined; it has the following accessible members:
-| **Member** | **Member Kind** | **Type** | **Purpose** |
-| ------------- | ------------------------------ | --------------------------------- | ------------------------------------------------------------------- |
-| Attributes | Instance property (read-write) | Implementation defined (§4.2.6.3) | Gets or sets one or more of the attributes of the directory object. |
-| CreationTime | Instance property (read-write) | Implementation defined (§4.5.19) | Gets and sets the creation time of the directory object. |
-| Extension | Instance property (read- only) | string | Gets the extension part of the directory name. |
-| FullName | Instance property (read-only) | string | Gets the full path of the directory. |
-| LastWriteTime | Instance property (read-write) | Implementation defined (§4.5.19) | Gets and sets the time when the directory was last written to. |
-| Name | Instance property (read- only) | string | Gets the name of the directory. |
+| **Member** | **Member Kind** | **Type** | **Purpose** |
+| ------------- | ------------------------------ | ------------------------------------- | ------------------------------------------------------------------- |
+| Attributes | Instance property (read-write) | Implementation defined ([§4.2.6.3][]) | Gets or sets one or more of the attributes of the directory object. |
+| CreationTime | Instance property (read-write) | Implementation defined ([§4.5.19][]) | Gets and sets the creation time of the directory object. |
+| Extension | Instance property (read- only) | string | Gets the extension part of the directory name. |
+| FullName | Instance property (read-only) | string | Gets the full path of the directory. |
+| LastWriteTime | Instance property (read-write) | Implementation defined ([§4.5.19][]) | Gets and sets the time when the directory was last written to. |
+| Name | Instance property (read- only) | string | Gets the name of the directory. |
In PowerShell, this type is `System.IO.DirectoryInfo`. The type of the **Attributes** property is `System.IO.FileAttributes`.
-### File description type
+### 4.5.18 File description type
-The cmdlet `New-Item` (§13.34) can create items of various kinds including FileSystem files. The
-type of a file description object is implementation defined; it has the following accessible
-members:
+The cmdlet `New-Item` can create items of various kinds including FileSystem files. The type of a
+file description object is implementation defined; it has the following accessible members:
-| **Member** | **Member Kind** | **Type** | **Purpose** |
-| ------------- | ------------------------------ | --------------------------------- | -------------------------------------------------------------------------------------------------- |
-| Attributes | Instance property (read-write) | Implementation defined (§4.2.6.3) | Gets or sets one or more of the attributes of the file object. |
-| BaseName | Instance property (read- only) | string | Gets the name of the file excluding the extension. |
-| CreationTime | Instance property (read-write) | Implementation defined (§4.5.19) | Gets and sets the creation time of the file object. |
-| Extension | Instance property (read- only) | string | Gets the extension part of the file name. |
-| FullName | Instance property (read-only) | string | Gets the full path of the file. |
-| LastWriteTime | Instance property (read-write) | Implementation defined (§4.5.19) | Gets and sets the time when the file was last written to. |
-| Length | Instance property (read- only) | long | Gets the size of the file, in bytes. |
-| Name | Instance property (read- only) | string | Gets the name of the file. |
-| VersionInfo | Instance property (read- only) | Implementation defined | Windows PowerShell: This ScriptProperty returns a System.Diagnostics.FileVersionInfo for the file. |
+| **Member** | **Member Kind** | **Type** | **Purpose** |
+| ------------- | ------------------------------ | ------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| Attributes | Instance property (read-write) | Implementation defined ([§4.2.6.3][]) | Gets or sets one or more of the attributes of the file object. |
+| BaseName | Instance property (read- only) | string | Gets the name of the file excluding the extension. |
+| CreationTime | Instance property (read-write) | Implementation defined ([§4.5.19][]) | Gets and sets the creation time of the file object. |
+| Extension | Instance property (read- only) | string | Gets the extension part of the file name. |
+| FullName | Instance property (read-only) | string | Gets the full path of the file. |
+| LastWriteTime | Instance property (read-write) | Implementation defined ([§4.5.19][]) | Gets and sets the time when the file was last written to. |
+| Length | Instance property (read- only) | long | Gets the size of the file, in bytes. |
+| Name | Instance property (read- only) | string | Gets the name of the file. |
+| VersionInfo | Instance property (read- only) | Implementation defined | Windows PowerShell: This ScriptProperty returns a System.Diagnostics.FileVersionInfo for the file. |
In PowerShell, this type is `System.IO.FileInfo`.
-### Date-Time description type
+### 4.5.19 Date-Time description type
The type of a date-time description object is implementation defined; it has the following accessible members:
accessible members:
| Second | Instance property (read-only) | int | Gets the seconds component of the date represented by this instance. | | Year | Instance property (read-only) | int | Gets the year component of the date represented by this instance. |
-An object of this type can be created by cmdlet `Get-Date` (§13.18).
+An object of this type can be created by cmdlet [Get-Date](xref:Microsoft.PowerShell.Utility.Get-Date).
In PowerShell, this type is `System.DateTime`.
-### Group-Info description type
+### 4.5.20 Group-Info description type
The type of a **group-info** description object is implementation defined; it has the following accessible members:
accessible members:
| Name | Instance property (read-only) | string | Gets the name of the group. | | Values | Instance property (read-only) | Implementation-defined collection | Gets the values of the elements of the group. |
-An object of this type can be created by cmdlet `Group-Object` (§13.27).
+An object of this type can be created by cmdlet [Group-Object](xref:Microsoft.PowerShell.Utility.Group-Object).
In PowerShell, this type is `Microsoft.PowerShell.Commands.GroupInfo`.
-### Generic-Measure-Info description type
+### 4.5.21 Generic-Measure-Info description type
The type of a **generic-measure-info** description object is implementation defined; it has the following accessible members:
following accessible members:
| Property | Instance property (read-only) | string | Gets the property to be measured. | | Sum | Instance property (read-only) | double | Gets the sum of the values of the specified properties. |
-An object of this type can be created by cmdlet `Measure-Object` (§13.31).
+An object of this type can be created by cmdlet [Measure-Object](xref:Microsoft.PowerShell.Utility.Measure-Object).
In PowerShell, this type is `Microsoft.PowerShell.Commands.GenericMeasureInfo`.
-### Text-Measure-Info description type
+### 4.5.22 Text-Measure-Info description type
The type of a **text-info** description object is implementation defined; it has the following accessible members:
accessible members:
| Property | Instance property (read-only) | string | Gets the property to be measured. | | Words | Instance property (read-only) | int | Gets the number of words in the target object. |
-An object of this type can be created by cmdlet `Measure-Object` (§13.31).
+An object of this type can be created by cmdlet `Measure-Object`.
In PowerShell, this type is `Microsoft.PowerShell.Commands.TextMeasureInfo`.
-### Credential type
+### 4.5.23 Credential type
A credential object can then be used in various security operations. The type of a credential object is implementation defined; it has the following accessible members:
is implementation defined; it has the following accessible members:
| Password | Instance property (read-only) | Implementation defined | Gets the password. | | UserName | Instance property (read-only) | string | Gets the username. |
-An object of this type can be created by cmdlet `Get-Credential` (§13.17).
+An object of this type can be created by cmdlet [Get-Credential](xref:Microsoft.PowerShell.Security.Get-Credential).
In PowerShell, this type is `System.Management.Automation.PSCredential`.
-### Method designator type
+### 4.5.24 Method designator type
The type of a method designator is implementation defined; it has the following accessible members:
following accessible members:
| ---------- | --------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | Invoke | Instance method | object/variable number and type | Takes a variable number of arguments, and indirectly calls the method referred to by the parent method designator, passing in the arguments. |
-An object of this type can be created by an *invocation-expression* (§7.1.3).
+An object of this type can be created by an *invocation-expression* ([§7.1.3][]).
In PowerShell, this type is System.Management.Automation.PSMethod.
-### Member definition type
+### 4.5.25 Member definition type
This type encapsulates the definition of a member. It has the following accessible members:
This type encapsulates the definition of a member. It has the following accessib
In PowerShell, this type is `Microsoft.PowerShell.Commands.MemberDefinition`.
-## Type extension and adaptation
+## 4.6 Type extension and adaptation
A PowerShell implementation includes a family of core types (which are documented in this chapter) that each contain their own set of *base members*. Those members can be methods or properties, and
-they can be instance or static members. For example, the base members of the type string (§4.3.1)
-are the instance property Length and the instance methods ToLower and ToUpper.
+they can be instance or static members. For example, the base members of the type string
+([§4.3.1][]) are the instance property Length and the instance methods ToLower and ToUpper.
When an object is created, it contains all the instance properties of that object's type, and the instance methods of that type can be called on that object. An object may be customized via the
unaffected.
The base member set of a type can be augmented by the addition of the following kinds of members: - *adapted members*, via the *Extended Type System* (ETS), most details of which are unspecified.-- *extended members*, via the cmdlet Add-Member (§13.2).
+- *extended members*, via the cmdlet [Add-Member](xref:Microsoft.PowerShell.Utility.Add-Member).
In PowerShell, extended members can also be added via `types.ps1xml` files. Adapted and extended members are collectively called *synthetic* *members*. The ETS adds the following members to all PowerShell objects: **psbase**, **psadapted**, **psextended**, and **pstypenames**. See the **Force** and **View** parameters in the cmdlet
-`Get-Member` (§13.22) for more information on these members.
+[Get-Member](xref:Microsoft.PowerShell.Utility.Get-Member) for more information on these members.
An instance member may hide an extended and/or adapted member of the same name, and an extended member may hide an adapted member. In such cases, the member sets **psadapted** and **psextended**
There are three ways create a custom object having a new member M:
``` `PsObject` is the base type of all PowerShell types.+
+<!-- reference links -->
+[§12.3.5]: chapter-12.md#1235-the-cmdletbinding-attribute
+[§12.3.6]: chapter-12.md#1236-the-outputtype-attribute
+[§2.3.2.2]: chapter-02.md#2322-automatic-variables
+[§3.1.4]: chapter-03.md#314-functions
+[§3.12]: chapter-03.md#312-error-handling
+[§3.5.4]: chapter-03.md#354-function-name-scope
+[§4.1.2]: chapter-04.md#412-the-null-type
+[§4.2.1]: chapter-04.md#421-boolean
+[§4.2.2]: chapter-04.md#422-character
+[§4.2.3]: chapter-04.md#423-integer
+[§4.2.4]: chapter-04.md#424-real-number
+[§4.2.6.3]: chapter-04.md#4263-file-attributes-type
+[§4.3.1]: chapter-04.md#431-strings
+[§4.3.6]: chapter-04.md#436-the-ref-type
+[§4.5.1]: chapter-04.md#451-provider-description-type
+[§4.5.10]: chapter-04.md#4510-function-description-type
+[§4.5.11]: chapter-04.md#4511-filter-description-type
+[§4.5.12]: chapter-04.md#4512-module-description-type
+[§4.5.16]: chapter-04.md#4516-enumerator-description-type
+[§4.5.19]: chapter-04.md#4519-date-time-description-type
+[§4.5.2]: chapter-04.md#452-drive-description-type
+[§5.3]: chapter-05.md#53-constrained-variables
+[§7.1.10]: chapter-07.md#7110-type-literal-expression
+[§7.1.3]: chapter-07.md#713-invocation-expressions
+[§7.1.4.4]: chapter-07.md#7144-subscripting-an-xml-document
+[§7.1.8]: chapter-07.md#718-script-block-expression
+[§7.2.9]: chapter-07.md#729-cast-operator
+[§7.8.5]: chapter-07.md#785-shift-operators
+[§8.10.5]: chapter-08.md#8105-the-switch-type-constraint
+[§8.4.4]: chapter-08.md#844-the-foreach-statement
+[§9.]: chapter-09.md#9-arrays
+[common parameters]: /powershell/module/microsoft.powershell.core/about/about_commonparameters
lang-spec Chapter 05 https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/lang-spec/chapter-05.md
description: A variable represents a storage location for a value, and that valu
Last updated 05/19/2021 Title: Variables ---
-# Variables
+# 5. Variables
A variable represents a storage location for a value, and that value has a type. Traditional procedural programming languages are statically typed; that is, the runtime type of a variable is
that with which it was declared at compile time. Object-oriented languages add t
inheritance, which allows the runtime type of a variable to be that with which it was declared at compile time or some type derived from that type. Being a dynamically typed language, PowerShell's variables do not have types, per se. In fact, variables are not defined; they simply come into being
-when they are first assigned a value. And while a variable may be constrained (§5.3) to holding a
-value of a given type, type information in an assignment cannot always be verified statically.
+when they are first assigned a value. And while a variable may be constrained ([§5.3][]) to holding
+a value of a given type, type information in an assignment cannot always be verified statically.
At different times, a variable may be associated with values of different types either through
-assignment (§7.11) or the use of the `++` and `‑‑` operators (§7.1.5, 7.2.6). When the value
-associated with a variable is changed, that value's type may change. For example,
+assignment ([§7.11][]) or the use of the `++` and `‑‑` operators ([§7.1.5][], [§7.2.6][]). When the
+value associated with a variable is changed, that value's type may change. For example,
```powershell $i = "abc" # $i holds a value of type string
$i = 2147483647 # $i holds a value of type int
``` Any use of a variable that has not been created results in the value $null. To see if a variable has
-been defined, use the `Test-Path` cmdlet (§13.54).
+been defined, use the [Test-Path](xref:Microsoft.PowerShell.Management.Test-Path) cmdlet.
-## Writable location
+## 5.1 Writable location
A *writable location* is an expression that designates a resource to which a command has both read and write access. A writable location may be a variable (§5), an array element (§9), an associated
-value in a Hashtable accessed via a subscript (§10), a property (§7.1.2), or storage managed by a
-provider (§3.1).
+value in a Hashtable accessed via a subscript (§10), a property ([§7.1.2][]), or storage managed by
+a provider ([§3.1][]).
-## Variable categories
+## 5.2 Variable categories
PowerShell defines the following categories of variables: static variables, instance variables, array elements, Hashtable key/value pairs, parameters, ordinary variables, and variables on provider
function F ($p1, $p2) {
provider drives. - `$Variable:v` is actually an ordinary variable written with its fully qualified provider drive.
-### Static variables
+### 5.2.1 Static variables
A data member of an object that belongs to the object's type rather than to that particular instance
-of the type is called a *static variable*. See §4.2.3, §4.2.4.1, and §4.3.8 for some examples.
+of the type is called a *static variable*. See [§4.2.3][], [§4.2.4.1][], and [§4.3.8][] for some
+examples.
PowerShell provides no way to create new types that contain static variables; however, objects of such types may be provided by the host environment.
such types may be provided by the host environment.
Memory for creating and deleting objects containing static variables is managed by the host environment and the garbage collection system.
-See §7.1.2 for information about accessing a static variable.
+See [§7.1.2][] for information about accessing a static variable.
A static data member can be a field or a property.
-### Instance variables
+### 5.2.2 Instance variables
A data member of an object that belongs to a particular instance of the object's type rather than to
-the type itself is called an *instance variable*. See §4.3.1, §4.3.2, and §4.3.3 for some examples.
+the type itself is called an *instance variable*. See [§4.3.1][], [§4.3.2][], and [§4.3.3][] for
+some examples.
A PowerShell host environment might provide a way to create new types that contain instance variables or to add new instance variables to existing types.
variables or to add new instance variables to existing types.
Memory for creating and deleting objects containing static variables is managed by the host environment and the garbage collection system.
-See §7.1.2 for information about accessing an instance variable.
+See [§7.1.2][] for information about accessing an instance variable.
An instance data member can be a field or a property.
-### Array elements
+### 5.2.3 Array elements
-An array can be created via a unary comma operator (§7.2.1), *sub-expression* (§7.1.6),
-*array-expression* (§7.1.7), binary comma operator (§7.3), range operator (§7.4), or `New-Object`
-cmdlet (§13.36).
+An array can be created via a unary comma operator ([§7.2.1][]), *sub-expression* ([§7.1.6][]),
+*array-expression* ([§7.1.7][]), binary comma operator ([§7.3][]), range operator ([§7.4][]), or
+[New-Object](xref:Microsoft.PowerShell.Utility.New-Object) cmdlet.
Memory for creating and deleting arrays is managed by the host environment and the garbage collection system.
-Arrays and array elements are discussed in §9.
+Arrays and array elements are discussed in [§9.][]
-### Hashtable key/value pairs
+### 5.2.4 Hashtable key/value pairs
-A Hashtable is created via a hash literal (§2.3.5.6) or the `New-Object` cmdlet (§13.36). A new
-key/value pair can be added via the `[]` operator (§7.1.4.3).
+A Hashtable is created via a hash literal ([§2.3.5.6][]) or the
+[New-Object](xref:Microsoft.PowerShell.Utility.New-Object) cmdlet. A new key/value pair can be added
+via the `[]` operator ([§7.1.4.3][]).
Memory for creating and deleting Hashtables is managed by the host environment and the garbage collection system. Hashtables are discussed in §10.
-### Parameters
+### 5.2.5 Parameters
A parameter is created when its parent command is invoked, and it is initialized with the value of the argument provided in the invocation or by the host environment. A parameter ceases to exist when its parent command terminates.
-Parameters are discussed in §8.10.
+Parameters are discussed in [§8.10][].
-### Ordinary variables
+### 5.2.6 Ordinary variables
-An *ordinary variable* is defined by an *assignment-expression* (§7.11) or a *foreach-statement*
-(§8.4.4). Some ordinary variables are predefined by the host environment while others are transient,
-coming and going as needed at runtime.
+An *ordinary variable* is defined by an *assignment-expression* ([§7.11][]) or a *foreach-statement*
+([§8.4.4][]). Some ordinary variables are predefined by the host environment while others are
+transient, coming and going as needed at runtime.
The lifetime of an ordinary variable is that part of program execution during which storage is guaranteed to be reserved for it. This lifetime begins at entry into the scope with which it is
entered recursively or iteratively, a new instance of the local variable is crea
The storage referred to by an ordinary variable is reclaimed independently of the lifetime of that variable.
-An ordinary variable can be named explicitly with a **Variable:** namespace prefix (§5.2.7).
+An ordinary variable can be named explicitly with a **Variable:** namespace prefix ([§5.2.7][]).
-### Variables on provider drives
+### 5.2.7 Variables on provider drives
-The concept of providers and drives is introduced in §3.1, with each provider being able to provide
-its own namespace drive(s). This allows resources on those drives to be accessed as though they were
-ordinary variables (§5.2.6). In fact, an ordinary variable is stored on the file system provider
-drive Variable: (§3.1.5) and can be accessed by its ordinary name or its fully qualified namespace
-name.
+The concept of providers and drives is introduced in [§3.1][], with each provider being able to
+provide its own namespace drive(s). This allows resources on those drives to be accessed as though
+they were ordinary variables ([§5.2.6][]). In fact, an ordinary variable is stored on the file
+system provider drive Variable: ([§3.1.5][]) and can be accessed by its ordinary name or its fully
+qualified namespace name.
-Some namespace variable types are constrained implicitly (§5.3).
+Some namespace variable types are constrained implicitly ([§5.3][]).
-## Constrained variables
+## 5.3 Constrained variables
By default, a variable may designate a value of any type. However, a variable may be *constrained* to designating values of a given type by specifying that type as a type literal before its name in
function F ([int]$p1, [switch]$p2, [regex]$p3) { ... }
``` Any variable belonging to the namespace **Env:**, **Alias:**, or to the file system namespace
-(§2.3.2, §3.1) is constrained implicitly to the type `string`. Any variable belonging to the
-namespace **Function:** (§2.3.2, §3.1) is constrained implicitly to the type `scriptblock`.
+([§2.3.2][], [§3.1][]) is constrained implicitly to the type `string`. Any variable belonging to the
+namespace **Function:** ([§2.3.2][], [§3.1][]) is constrained implicitly to the type `scriptblock`.
+
+<!-- reference links -->
+[§2.3.2]: chapter-02.md#232-variables
+[§2.3.5.6]: chapter-02.md#2356-hash-literals
+[§3.1.5]: chapter-03.md#315-variables
+[§3.1]: chapter-03.md#31-providers-and-drives
+[§4.2.3]: chapter-04.md#423-integer
+[§4.2.4.1]: chapter-04.md#4241-float-and-double
+[§4.3.1]: chapter-04.md#431-strings
+[§4.3.2]: chapter-04.md#432-arrays
+[§4.3.3]: chapter-04.md#433-hashtables
+[§4.3.8]: chapter-04.md#438-the-math-type
+[§5.2.6]: chapter-05.md#526-ordinary-variables
+[§5.2.7]: chapter-05.md#527-variables-on-provider-drives
+[§5.3]: chapter-05.md#53-constrained-variables
+[§7.1.2]: chapter-07.md#712-member-access
+[§7.1.4.3]: chapter-07.md#7143-subscripting-a-hashtable
+[§7.1.5]: chapter-07.md#715-postfix-increment-and-decrement-operators
+[§7.1.6]: chapter-07.md#716--operator
+[§7.1.7]: chapter-07.md#717--operator
+[§7.11]: chapter-07.md#711-assignment-operators
+[§7.2.1]: chapter-07.md#721-unary-comma-operator
+[§7.2.6]: chapter-07.md#726-prefix-increment-and-decrement-operators
+[§7.3]: chapter-07.md#73-binary-comma-operator
+[§7.4]: chapter-07.md#74-range-operator
+[§8.10]: chapter-08.md#810-function-definitions
+[§8.4.4]: chapter-08.md#844-the-foreach-statement
+[§9.]: chapter-09.md#9-arrays
lang-spec Chapter 06 https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/lang-spec/chapter-06.md
description: A type conversion is performed when a value of one type is used in
Last updated 05/19/2021 Title: Conversions ---
-# Conversions
+# 6. Conversions
A *type conversion* is performed when a value of one type is used in a context that requires a different type. If such a conversion happens automatically it is known as *implicit conversion*. (A
common example of this is with some operators that need to convert one or more o
designated by their operands.) Implicit conversion is permitted provided the sense of the source value is preserved, such as no loss of precision of a number when it is converted.
-The cast operator (§7.2.9) allows for *explicit conversion*.
+The cast operator ([§7.2.9][]) allows for *explicit conversion*.
Conversions are discussed below, with supplementary information being provided as necessary in the
-description of each operator in §6.19.
+description of each operator in [§6.19][].
Explicit conversion of a value to the type it already has causes no change to that value or its representation. The rules for handing conversion when the value of an expression is being bound to a parameter are
-covered in §6.17.
+covered in [§6.17][].
-## Conversion to void
+## 6.1 Conversion to void
A value of any type can be discarded explicitly by casting it to type void. There is no result.
-## Conversion to bool
+## 6.2 Conversion to bool
The rules for converting any value to type bool are as follows:
The rules for converting any value to type bool are as follows:
converted to True. - A value of null type is converted to False. - A string of length 0 is converted to False; a string of length > 0 is converted to True.-- A switch parameter with value `$true` is converted to True, and one with value `$false` is converted
- to False.
+- A switch parameter with value `$true` is converted to True, and one with value `$false` is
+ converted to False.
- All other non-null reference type values are converted to True. If the type implements IList:
If the type implements IList:
- Otherwise, if the first element's Count >= 1, the value is converted to True. - Otherwise, the value is converted to False.
-## Conversion to char
+## 6.3 Conversion to char
The rules for converting any value to type char are as follows:
The rules for converting any value to type char are as follows:
- For other reference type values, if the reference type supports such a conversion, that conversion is used; otherwise, the conversion is in error.
-## Conversion to integer
+## 6.4 Conversion to integer
The rules for converting any value to type byte, int, or long are as follows:
follows:
- A numeric type value whose value after rounding of any fractional part can be represented in the destination type has that rounded value; otherwise, the conversion is in error. - A value of null type is converted to zero.-- A string that represents a number is converted as described in §6.16. If after truncation of the
- fractional part the result can be represented in the destination type the string is well formed
- and it has the destination type; otherwise, the conversion is in error. If the string does not
- represent a number, the conversion is in error.
+- A string that represents a number is converted as described in [§6.16][]. If after truncation of
+ the fractional part the result can be represented in the destination type the string is well
+ formed and it has the destination type; otherwise, the conversion is in error. If the string does
+ not represent a number, the conversion is in error.
- For other reference type values, if the reference type supports such a conversion, that conversion is used; otherwise, the conversion is in error.
-## Conversion to float and double
+## 6.5 Conversion to float and double
The rules for converting any value to type float or double are as follows:
follows:
conversions to float, and for long and decimal conversions to double, some of the least significant bits of the integer value may be lost. - A value of null type is converted to zero.-- A string that represents a number is converted as described in §6.16; otherwise, the conversion is
- in error.
+- A string that represents a number is converted as described in [§6.16][]; otherwise, the
+ conversion is in error.
- For other reference type values, if the reference type supports such a conversion, that conversion is used; otherwise, the conversion is in error.
-## Conversion to decimal
+## 6.6 Conversion to decimal
The rules for converting any value to type decimal are as follows:
The rules for converting any value to type decimal are as follows:
- A numeric type value is represented exactly; however, if that value is too large or too small to fit in the destination type, the conversion is in error. - A value of null type is converted to zero.-- A string that represents a number is converted as described in §6.16; otherwise, the conversion is
- in error.
+- A string that represents a number is converted as described in [§6.16][]; otherwise, the
+ conversion is in error.
- For other reference type values, if the reference type supports such a conversion, that conversion is used; otherwise, the conversion is in error. - The scale of the result of a successful conversion is such that the fractional part has no trailing zeros.
-## Conversion to object
+## 6.7 Conversion to object
The value of any type except the null type (4.1.2) can be converted to type object. The value retains its type and representation.
-## Conversion to string
+## 6.8 Conversion to string
The rules for converting any value to type string are as follows:
The rules for converting any value to type string are as follows:
- A value of null type is converted to the empty string. - For a 1-dimensional array, the result is a string containing the value of each element in that array, from start to end, converted to string, with elements being separated by the current Output
- Field Separator (§2.3.2.2). For an array having elements that are themselves arrays, only the
+ Field Separator ([§2.3.2.2][]). For an array having elements that are themselves arrays, only the
top-level elements are converted. The string used to represent the value of an element that is an
- array, is implementation defined. For a multi-dimensional array, it is flattened (§9.12) and then
- treated as a 1ΓÇædimensional array.
+ array, is implementation defined. For a multi-dimensional array, it is flattened ([§9.12][]) and
+ then treated as a 1ΓÇædimensional array.
- A value of null type is converted to the empty string. - A scriptblock type value is converted to a string containing the text of that block without the delimiting { and } characters.
The string used to represent the value of an element that is an array has the fo
`System.type[,]`, and so on. For other reference types, the method `ToString` is called. For other enumerable types, the source value is treated like a 1-dimensional array.
-## Conversion to array
+## 6.9 Conversion to array
The rules for converting any value to an array type are as follows:
The rules for converting any value to an array type are as follows:
created whose value is the scalar after conversion to the target element type. - For a 1-dimensional array value, a new array of the target type is created, and each element is copied with conversion from the source array to the corresponding element in the target array.-- For a multi-dimensional array value, that array is first flattened (§9.12), and then treated as a
- 1-dimensional array value.
+- For a multi-dimensional array value, that array is first flattened ([§9.12][]), and then treated
+ as a 1-dimensional array value.
- A string value is converted to an array of char having the same length with successive characters from the string occupying corresponding positions in the array.
For other enumerable types, a new 1-element array is created whose value is the
element after conversion to the target element type, if such a conversion exists. Otherwise, the conversion is in error.
-## Conversion to xml
+## 6.10 Conversion to xml
The object is converted to type string and then into an XML Document object of type `xml`.
-## Conversion to regex
+## 6.11 Conversion to regex
An expression that designates a value of type string may be converted to type `regex`.
-## Conversion to scriptblock
+## 6.12 Conversion to scriptblock
The rules for converting any value to type `scriptblock` are as follows: - A string value is treated as the name of a command optionally following by arguments to a call to that command.
-## Conversion to enumeration types
+## 6.13 Conversion to enumeration types
The rules for converting any value to an enumeration type are as follows:
follows:
- A value of type string that contains a comma-separated list of named values (with regard for case) for an enumeration type is converted to the bitwise-OR of all those named values.
-## Conversion to other reference types
+## 6.14 Conversion to other reference types
The rules for converting any value to a reference type other than an array type or string are as follows:
argument constructors or default constructors if the value is a hashtable, impli
conversion operators, and Parse methods for the target type; the use of Convert.ConvertTo; and the ETS conversion mechanism.
-## Usual arithmetic conversions
+## 6.15 Usual arithmetic conversions
If neither operand designates a value having numeric type, then
If neither operand designates a value having numeric type, then
- Otherwise, if the left operand designates a value of type char and the right operand designates a value of type bool, the conversion is in error. - Otherwise, if the left operand designates a value of type string but does not represent a number
- (§6.16), the conversion is in error.
+ ([§6.16][]), the conversion is in error.
- Otherwise, if the right operand designates a value of type string but does not represent a number
- (§6.16), the conversion is in error.
-- Otherwise, all operands designating values of type string are converted to numbers (§6.16), and
- the process continues with the numeric conversions listed below.
+ ([§6.16][]), the conversion is in error.
+- Otherwise, all operands designating values of type string are converted to numbers ([§6.16][]),
+ and the process continues with the numeric conversions listed below.
- Otherwise, the conversion is in error. Numeric conversions:
Numeric conversions:
result has the first in the sequence int, long, double that can represent its value without truncation.
-## Conversion from string to numeric type
+## 6.16 Conversion from string to numeric type
Depending on its contents, a string can be converted explicitly or implicitly to a numeric value. Specifically,
implicitly to a numeric value. Specifically,
- The case-distinct strings "-Infinity", "Infinity", and "NaN" are recognized as the values -∞, +∞, and NaN, respectively.
-## Conversion during parameter binding
+## 6.17 Conversion during parameter binding
-For information about parameter binding see §8.14.
+For information about parameter binding see [§8.14][].
When the value of an expression is being bound to a parameter, there are extra conversion considerations, as described below: -- If the parameter type is bool or switch (§4.2.5, §8.10.5) and the parameter has no argument, the
- value of the parameter in the called command is set to `$true`. If the parameter type is other
- than bool or switch, a parameter having no argument is in error.
+- If the parameter type is bool or switch ([§4.2.5][], [§8.10.5][]) and the parameter has no
+ argument, the value of the parameter in the called command is set to `$true`. If the parameter
+ type is other than bool or switch, a parameter having no argument is in error.
- If the parameter type is switch and the argument value is `$null`, the parameter value is set to `$false`. - If the parameter type is object or is the same as the type of the argument, the argument's value
considerations, as described below:
argument collection. If necessary, the argument collection element values are converted to type T2 using the conversion rules of this section. - If the steps above and the conversions specified earlier in this chapter do not suffice, the rules
- in §6.18 are applied. If those fail, the parameter binding fails.
+ in [§6.18][] are applied. If those fail, the parameter binding fails.
-## .NET Conversion
+## 6.18 .NET Conversion
For an implicit conversion, PowerShell's built-in conversions are tried first. If they cannot resolve the conversion, the .NET custom converters below are tried, in order, from top to bottom. If
a conversion is found, but it throws an exception, the conversion has failed.
an explicit cast operator that converts from the source type, that operator is called to perform the conversion. -- **IConvertable**:` System.Convert.ChangeType` is called to perform the conversion.
+- **IConvertable**: `System.Convert.ChangeType` is called to perform the conversion.
-## Conversion to ordered
+## 6.19 Conversion to ordered
The rules for converting any value to the pseudo-type ordered are as follows: -- If the value is a hash literal (§2.3.5.6), the result is an object with an implementation defined
- type that behaves like a hashtable and the order of the keys matches the order specified in the
- hash literal.
+- If the value is a hash literal ([§2.3.5.6][]), the result is an object with an implementation
+ defined type that behaves like a hashtable and the order of the keys matches the order specified
+ in the hash literal.
- Otherwise, the behavior is implementation defined.
-Only hash literals (§2.3.5.6) can be converted to ordered. The result is an instance of
+Only hash literals ([§2.3.5.6][]) can be converted to ordered. The result is an instance of
`System.Collections.Specialized.OrderedDictionary`.
-## Conversion to pscustomobject
+## 6.20 Conversion to pscustomobject
The rules for converting any value to the pseudo-type pscustomobject are as follows:
as follows:
- Otherwise, the behavior is implementation defined. The conversion is always allowed but does not change the type of the value.+
+<!-- reference links -->
+[§2.3.2.2]: chapter-02.md#2322-automatic-variables
+[§2.3.5.6]: chapter-02.md#2356-hash-literals
+[§4.2.5]: chapter-04.md#425-the-switch-type
+[§6.16]: chapter-06.md#616-conversion-from-string-to-numeric-type
+[§6.17]: chapter-06.md#617-conversion-during-parameter-binding
+[§6.18]: chapter-06.md#618-net-conversion
+[§6.19]: chapter-06.md#619-conversion-to-ordered
+[§7.2.9]: chapter-07.md#729-cast-operator
+[§8.10.5]: chapter-08.md#8105-the-switch-type-constraint
+[§8.14]: chapter-08.md#814-parameter-binding
+[§9.12]: chapter-09.md#912-multidimensional-array-flattening
lang-spec Chapter 07 https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/lang-spec/chapter-07.md
description: An expression is a sequence of operators and operands that designat
Last updated 05/19/2021 Title: Expressions ---
-# Expressions
+# 7. Expressions
Syntax: ```Syntax expression:
- logical-expressionDescription:
+ logical-expression
```
+Description:
+ An *expression* is a sequence of operators and operands that designates a method, a function, a writable location, or a value; specifies the computation of a value; produces one or more side effects; or performs some combination thereof. For example,
operations defined on them. All details of such types and operations are impleme
A *top-level expression* is one that is not part of some larger expression. If a top-level expression contains a side-effect operator the value of that expression is not written to the
-pipeline; otherwise, it is. See §7.1.1 for a detailed discussion of this.
+pipeline; otherwise, it is. See [§7.1.1][] for a detailed discussion of this.
Ordinarily, an expression that designates a collection (§4) is enumerated into its constituent elements when the value of that expression is used. However, this is not the case when the
the third case, the expression is a direct call to a cmdlet, so the result is no
If an operation is not defined by PowerShell, the type of the value designated by the left operand is inspected to see if it has a corresponding `op_<operation>` method.
-## Primary expressions
+## 7.1 Primary expressions
Syntax:
value:
variable ```
-### Grouping parentheses
+### 7.1.1 Grouping parentheses
Syntax:
expression in parentheses, as follows:
As such, the grouping parentheses in this case are not redundant.
-In the following example, we have variable substitution (§2.3.5.2) taking place in a string literal:
+In the following example, we have variable substitution ([§2.3.5.2][]) taking place in a string
+literal:
```powershell ">$($a = -23)<" # value not written to pipeline, get
Consider the following example that has two side effects, neither of which is at
The result is written to the pipeline, as the top-level expression has no side effects.
-### Member access
+### 7.1.2 Member access
Syntax:
$a = @{ID = 1 }, @{ID = 2 }, @{ID = 3 }
$a.ID # get ID from each element in the array ```
-### Invocation expressions
+### 7.1.3 Invocation expressions
Syntax:
unspecified.
This operator is left associative.
-The type of the result of an *invocation-expression* is a *method designator* (§4.5.24).
+The type of the result of an *invocation-expression* is a *method designator* ([§4.5.24][]).
Examples:
$a = [char]::ToLower # get method descriptor for ToLower
$a.Invoke("X") # call ToLower via the descriptor ```
-### Element access
+### 7.1.4 Element access
Syntax:
Description:
There must not be any white space between *primary-expression* and the left square bracket (`[`).
-#### Subscripting an array
+#### 7.1.4.1 Subscripting an array
Description:
-Arrays are discussed in detail in §9. If *expression* is a 1-dimensional array, see §7.1.4.5.
+Arrays are discussed in detail in [§9.][] If *expression* is a 1-dimensional array, see
+[§7.1.4.5][].
When *primary-expression* designates a 1-dimensional array *A*, the operator `[]` returns the element located at `A[0 + expression]` after the value of *expression* has been converted to `int`.
For a multidimensional-array subscript expression, the order of evaluation of th
expressions is unspecified. For example, given a 3-dimensional array `$a`, the behavior of `$a[$i++,$i,++$i]` is unspecified.
-If *expression* is an array, see §7.1.4.5.
+If *expression* is an array, see [§7.1.4.5][].
This operator is left associative.
$a = "red","green"
$a[1][4] # returns string "n" from string in $a[1] ```
-If a write access to a non-existing element is attempted, an **IndexOutOfRange** exception is raised.
+If a write access to a non-existing element is attempted, an **IndexOutOfRange** exception is
+raised.
-#### Subscripting a string
+#### 7.1.4.2 Subscripting a string
Description:
$c = $s[20] # no such position, returns $null
$c = $s[-1] # returns "o", i.e., $s[$s.Length-1] ```
-#### Subscripting a Hashtable
+#### 7.1.4.3 Subscripting a Hashtable
Description:
with the key(s) designated by *expression*. The type of *expression* is not rest
When *expression* is a single key name, the result is the associated value and has that type, unless no such key exists, in which case, the result is `$null`. If `$null` is used as the key the behavior
-is implementation defined. If *expression* is an array of key names, see §7.1.4.5.
+is implementation defined. If *expression* is an array of key names, see [§7.1.4.5][].
-If *expression* is an array, see §7.1.4.5.
+If *expression* is an array, see [§7.1.4.5][].
Examples:
$h1[$true] # returns value 123 using key $true
When *expression* is a single key name, if `$null` is used as the only value to subscript a Hashtable, a **NullArrayIndex** exception is raised.
-#### Subscripting an XML document
+#### 7.1.4.4 Subscripting an XML document
Description:
$x['FirstName'] # No such child element at the top level, result is `$
The type of the result is `System.Xml.XmlElement` or `System.String`.
-#### Generating array slices
+#### 7.1.4.5 Generating array slices
When *primary-expression* designates an object of a type that is enumerable (§4) or a Hashtable, and
-*expression* is a 1-dimensional array, the result is an array slice (§9.9) containing the elements
-of *primary-expression* designated by the elements of *expression*.
+*expression* is a 1-dimensional array, the result is an array slice ([§9.9][]) containing the
+elements of *primary-expression* designated by the elements of *expression*.
In the case of a Hashtable, the array slice contains the associated values to the keys provided, unless no such key exists, in which case, the corresponding element is `$null`. If `$null` is used
$h1[$null,'IDNum'] # returns [object[]], Length 1 (123)
Windows PowerShell: When *expression* is a collection of two or more key names, if `$null` is used as any key name that key is ignored and has no corresponding element in the resulting array.
-### Postfix increment and decrement operators
+### 7.1.5 Postfix increment and decrement operators
Syntax:
Description:
The *primary-expression* must designate a writable location having a value of numeric type (§4) or the value `$null`. If the value designated by the operand is `$null`, that value is converted to type int and value zero before the operator is evaluated. The type of the value designated by
-*primary-expression* may change when the result is stored. See §7.11 for a discussion of type change
-via assignment.
+*primary-expression* may change when the result is stored. See [§7.11][] for a discussion of type
+change via assignment.
The result produced by the postfix `++` operator is the value designated by the operand. After that result is obtained, the value designated by the operand is incremented by 1 of the appropriate type. The type of the result of expression `E++` is the same as for the result of the expression `E + 1`
-(§7.7).
+([§7.7][]).
The result produced by the postfix `--` operator is the value designated by the operand. After that result is obtained, the value designated by the operand is decremented by 1 of the appropriate type. The type of the result of expression `E--` is the same as for the result of the expression `E - 1`
-(§7.7).
+([§7.7][]).
These operators are left associative.
$x = $null # target is unconstrained, $null goes to [int]0
$x++ # value treated as int, 0->1 ```
-### $(...) operator
+### 7.1.6 $(...) operator
Syntax: - ```Syntax sub-expression: $( new-lines~opt~ statement-list~opt~ new-lines~opt~ )
$($i = 10; ++$j) # pipeline gets nothing
$(2,4,6) # pipeline gets [object[]](2,4,6) ``` -
-### @(...) operator
+### 7.1.7 @(...) operator
Syntax:
$a = @(2,4,6) # result is array of 3
@(@($a)) # result is the same array of 3 ```
-### Script block expression
+### 7.1.8 Script block expression
Syntax:
script-block-body:
Description:
-*param-block* is described in §8.10.9. *named-block-list* is described in §8.10.7.
+*param-block* is described in [§8.10.9][]. *named-block-list* is described in [§8.10.7][].
A script block is an unnamed block of statements that can be used as a single unit. Script blocks can be used to invoke a block of code as if it was a single command, or they can be assigned to
variables that can be executed.
The *named-block-list* or *statement-list* is executed and the type and value(s) of the result are the type and value(s) of the results of those statement sets.
-A *script-block-expression* has type scriptblock (§4.3.7).
+A *script-block-expression* has type scriptblock ([§4.3.7][]).
If *param-block* is omitted, any arguments passed to the script block are available via `$args`
-(§8.10.1).
+([§8.10.1][]).
During parameter binding, a script block can be passed either as a script block object or as the
-result after the script block has been evaluated. See §6.17 for further information.
+result after the script block has been evaluated. See [§6.17][] for further information.
-### Hash literal expression
+### 7.1.9 Hash literal expression
Syntax:
$h4 = @{ 10 = "James"; 20.5 = "Anderson"; $true = 123 }
which creates two Hashtables, `$h1` and `$h2`, each containing three key/value pairs, and a third, `$h3`, that is empty. Hashtable `$h4` has keys of various types.
-### Type literal expression
+### 7.1.10 Type literal expression
Syntax:
result, a type name is a synonym for its underlying type.
Type literals are used in a number of contexts: -- Specifying an explicit conversion (§6, §7.2.9)-- Creating a type-constrained array (§9.4)-- Accessing the static members of an object (§7.1.2)-- Specifying a type constraint on a variable (§5.3) or a function parameter (§8.10.2)
+- Specifying an explicit conversion (§6, [§7.2.9][])
+- Creating a type-constrained array ([§9.4][])
+- Accessing the static members of an object ([§7.1.2][])
+- Specifying a type constraint on a variable ([§5.3][]) or a function parameter ([§8.10.2][])
Examples:
-Examples of type literals are `[int]`, `[object[]`, and `[int[,,]]`. A generic stack type (§4.4)
+Examples of type literals are `[int]`, `[object[]`, and `[int[,,]]`. A generic stack type ([§4.4][])
that is specialized to hold strings might be written as `[Stack[string]]`, and a generic dictionary type that is specialized to hold `int` keys with associated string values might be written as `[Dictionary[int,string]]`.
The type of a *type-literal* is `System.Type`. The complete name for the type `S
suggested above is `System.Collections.Generic.Stack[int]`. The complete name for the type `Dictionary[int,string]` suggested above is `System.Collections.Generic.Dictionary[int,string]`.
-## Unary operators
+## 7.2 Unary operators
Syntax:
dashdash:
dash dash ```
-### Unary comma operator
+### 7.2.1 Unary comma operator
Description:
$a = ,,10 # create an unconstrained array of 1 element, which is
# $a[0][0] is the int. Contrast this with @(@(10)) ```
-### Logical NOT
+### 7.2.2 Logical NOT
Description:
-The operator -not converts the value designated by *unary-expression* to type bool (§6.2), if
+The operator -not converts the value designated by *unary-expression* to type bool ([§6.2][]), if
necessary, and produces a result of that type. If *unary-expression*'s value is True, the result is False, and vice versa. The operator ! is an alternate spelling for -not.
Examples:
!"xyz" # False ```
-### Bitwise NOT
+### 7.2.3 Bitwise NOT
Description:
-The operator -bnot converts the value designated by *unary-expression* to an integer type (§6.4), if
-necessary. If the converted value can be represented in type int then that is the result type. Else,
-if the converted value can be represented in type long then that is the result type. Otherwise, the
-expression is ill formed. The resulting value is the ones-complement of the converted value.
+The operator -bnot converts the value designated by *unary-expression* to an integer type
+([§6.4][]), if necessary. If the converted value can be represented in type int then that is the
+result type. Else, if the converted value can be represented in type long then that is the result
+type. Otherwise, the expression is ill formed. The resulting value is the ones-complement of the
+converted value.
This operator is right associative.
Examples:
-bnot "0xabc" # int with value 0xFFFFF543 ```
-### Unary plus
+### 7.2.4 Unary plus
Description: An expression of the form +*unary-expression* is treated as if it were written as
-`0 + unary-expression` (§7.7). The integer literal 0 has type `int`.
+`0 + unary-expression` ([§7.7][]). The integer literal 0 has type `int`.
This operator is right associative.
Examples:
+"0xabc" # type int, value 2748 ``` -
-### Unary minus
+### 7.2.5 Unary minus
Description: An expression of the form -*unary-expression* is treated as if it were written as
-`0 - unary-expression` (§7.7). The integer literal 0 has type `int`.
+`0 - unary-expression` ([§7.7][]). The integer literal 0 has type `int`.
This operator is right associative.
Examples:
-123L # type long, value -123 -0.12340D # type decimal, value -0.12340
-### Prefix increment and decrement operators
+### 7.2.6 Prefix increment and decrement operators
Description:
value is converted to type int and value zero before the operator is evaluated.
> [!NOTE] > The type of the value designated by *unary-expression* may change when the result is stored. See
-> §7.11 for a discussion of type change via assignment.
+> [§7.11][] for a discussion of type change via assignment.
For the prefix `++` operator, the value of *unary-expression* is incremented by 1 of the appropriate type. The result is the new value after incrementing has taken place. The expression `++E` is
-equivalent to `E += 1` (§7.11.2).
+equivalent to `E += 1` ([§7.11.2][]).
For the prefix `--` operator, the value of *unary-expression* is decremented by 1 of the appropriate type. The result is the new value after decrementing has taken place. The expression `--E` is
-equivalent to `E -= 1` (§7.11.2).
+equivalent to `E -= 1` ([§7.11.2][]).
These operators are right associative.
$x = $null # target is unconstrained, $null goes to [int]0
$--x # value treated as int, 0->-1 ```
-### The unary -join operator
+### 7.2.7 The unary -join operator
Description: The unary `-join` operator produces a string that is the concatenation of the value of one or more objects designated by *unary-expression*. (A separator can be inserted by using the binary version
-of this operator (§7.8.4.4).)
+of this operator ([§7.8.4.4][]).)
*unary-expression* can be a scalar value or a collection.
Examples:
-join $null # result is "" ```
-### The unary -split operator
+### 7.2.8 The unary -split operator
Description: The unary `-split` operator splits one or more strings designated by *unary-expression*, returning their subparts in a constrained 1-dimensional array of string. It treats any contiguous group of white space characters as the delimiter between successive subparts. (An explicit delimiter string
-can be specified by using the binary version of this operator (§7.8.4.5).) This operator has two
-variants (§7.8).
+can be specified by using the binary version of this operator ([§7.8.4.5][]).) This operator has two
+variants ([§7.8][]).
The delimiter text is not included in the resulting strings. Leading and trailing white space in the input string is ignored. An input string that is empty or contains white space only results in an
Examples:
-split " " # 1 (empty) string ```
-### Cast operator
+### 7.2.9 Cast operator
Description:
Examples:
[char[]]"Hello" # an array of 5 char with values H, e, l, l, and o. ```
-## Binary comma operator
+## 7.3 Binary comma operator
Syntax:
Examples:
The addition of grouping parentheses to certain binary comma expressions does not document the default precedence; instead, it changes the result.
-## Range operator
+## 7.4 Range operator
Syntax:
Description:
A *range-expression* creates an unconstrained 1-dimensional array whose elements are the values of the int sequence specified by the range bounds. The values designated by the operands are converted
-to int, if necessary (§6.4). The operand designating the lower value after conversion is the *lower
-bound*, while the operand designating the higher value after conversion is the *upper bound*. Both
-bounds may be the same, in which case, the resulting array has length 1. If the left operand
+to int, if necessary ([§6.4][]). The operand designating the lower value after conversion is the
+*lower bound*, while the operand designating the higher value after conversion is the *upper bound*.
+Both bounds may be the same, in which case, the resulting array has length 1. If the left operand
designates the lower bound, the sequence is in ascending order. If the left operand designates the upper bound, the sequence is in descending order.
example, the range `5..8` can also be generated using `5,6,7,8`. However, if an
descending sequence is needed without having an array, an implementation may avoid generating an actual array. For example, in `foreach ($i in 1..5) { ... }`, no array need be created.
-A *range-expression* can be used to specify an array slice (§9.9).
+A *range-expression* can be used to specify an array slice ([§9.9][]).
Examples:
$true..3 # ascending range 1..3
"0xf".."0xa" # descending range 15..10 ```
-## Format operator
+## 7.5 Format operator
Syntax:
following form:
display width, and *FormatString* indicates the (optional) format. If the width of a formatted value exceeds the specified width, the width is increased accordingly. Values whose positions are not referenced in *FormatString* are ignored after being evaluated for any side effects. If *N* refers
-to a non-existent position, the behavior is implementation defined. Value of type `$null` and void are
-formatted as empty strings. Arrays are formatted as for *sub-expression* (§7.1.6). To include the
-characters "{" and "}" in a format specification without their being interpreted as format
-delimiters, write them as "{{" and "}}", respectively.
+to a non-existent position, the behavior is implementation defined. Value of type `$null` and void
+are formatted as empty strings. Arrays are formatted as for *sub-expression* ([§7.1.6][]). To
+include the characters "{" and "}" in a format specification without their being interpreted as
+format delimiters, write them as "{{" and "}}", respectively.
For a complete definition of format specifications, see the type `System.IFormattable` in Ecma Technical Report TR/84.
$format -f 123455 # >0001e23f<
In a format specification if *N* refers to a non-existent position, a **FormatError** is raised.
-## Multiplicative operators
+## 7.6 Multiplicative operators
Syntax:
multiplicative-expression:
multiplicative-expression % new-lines~opt~ format-expression ```
-### Multiplication
+### 7.6.1 Multiplication
Description: The result of the multiplication operator `*` is the product of the values designated by the two
-operands after the usual arithmetic conversions (§6.15) have been applied.
+operands after the usual arithmetic conversions ([§6.15][]) have been applied.
This operator is left associative.
Examples:
12 * "0xabc" # int result 32976 ```
-### String replication
+### 7.6.2 String replication
Description: When the left operand designates a string the binary `*` operator creates a new string that contains the one designated by the left operand replicated the number of times designated by the value of the
-right operand as converted to integer type (§6.4).
+right operand as converted to integer type ([§6.4][]).
This operator is left associative.
Examples:
"red" * 2.7 # string replicated 3 times ```
-### Array replication
+### 7.6.3 Array replication
Description: When the left operand designates an array the binary `*` operator creates a new unconstrained 1ΓÇædimensional array that contains the value designated by the left operand replicated the number of
-times designated by the value of the right operand as converted to integer type (§6.4). A
+times designated by the value of the right operand as converted to integer type ([§6.4][]). A
replication count of zero results in an array of length 1. If the left operand designates a
-multidimensional array, it is flattened (§9.12) before being used.
+multidimensional array, it is flattened ([§9.12][]) before being used.
This operator is left associative.
$a * 2.7 # [object[]], Length 2*3
(New-Object 'float[,]' 2,3) * 2 # [object[]], Length 2*2 ```
-### Division
+### 7.6.4 Division
Description: The result of the division operator `/` is the quotient when the value designated by the left operand is divided by the value designated by the right operand after the usual arithmetic
-conversions (§6.15) have been applied.
+conversions ([§6.15][]) have been applied.
If an attempt is made to perform integer or decimal division by zero, an implementation-defined terminating error is raised.
Examples:
If an attempt is made to perform integer or decimal division by zero, a **RuntimeException** exception is raised.
-### Remainder
+### 7.6.5 Remainder
Description: The result of the remainder operator `%` is the remainder when the value designated by the left operand is divided by the value designated by the right operand after the usual arithmetic
-conversions (§6.15) have been applied.
+conversions ([§6.15][]) have been applied.
If an attempt is made to perform integer or decimal division by zero, an implementation-defined terminating error is raised.
Examples:
If an attempt is made to perform integer or decimal division by zero, a **RuntimeException** exception is raised.
-## Additive operators
+## 7.7 Additive operators
Syntax:
additive-expression:
additive-expression dash new-lines~opt~ multiplicative-expression ```
-### Addition
+### 7.7.1 Addition
Description: The result of the addition operator `+` is the sum of the values designated by the two operands
-after the usual arithmetic conversions (§6.15) have been applied.
+after the usual arithmetic conversions ([§6.15][]) have been applied.
This operator is left associative.
Examples:
12 + "0xabc" # int result 2760 ```
-### String concatentaion
+### 7.7.2 String concatentaion
Description: When the left operand designates a string the binary `+` operator creates a new string that contains the value designated by the left operand followed immediately by the value(s) designated by the
-right operand as converted to type string (§6.8).
+right operand as converted to type string ([§6.8][]).
This operator is left associative.
Examples:
"red" + (20,30,40) # "red20 30 40" ```
-### Array concatenation
+### 7.7.3 Array concatenation
Description: When the left operand designates an array the binary `+` operator creates a new unconstrained 1ΓÇædimensional array that contains the elements designated by the left operand followed immediately by the value(s) designated by the right operand. Multidimensional arrays present in either operand
-are flattened (§9.12) before being used.
+are flattened ([§9.12][]) before being used.
This operator is left associative.
$a + (New-Object 'float[,]' 2,3) # [object[]], Length 8
(New-Object 'float[,]' 2,3) + $a # [object[]], Length 8 ```
-### Hashtable concatenation
+### 7.7.4 Hashtable concatenation
Description:
$h3 = $h1 + $h2 # new Hashtable, Count = 3
If the Hashtables contain the same key, an exception of type **BadOperatorArgument** is raised.
-### Subtraction
+### 7.7.5 Subtraction
Description: The result of the subtraction operator `-` is the difference when the value designated by the right operand is subtracted from the value designated by the left operand after the usual arithmetic
-conversions (§6.15) have been applied.
+conversions ([§6.15][]) have been applied.
This operator is left associative.
Examples:
12 - "0xabc" # int result -2736 ```
-## Comparison operators
+## 7.8 Comparison operators
Syntax:
two variants behave the same.
These operators are left associative.
-### Equality and relational operators
+### 7.8.1 Equality and relational operators
Description: There are two *equality* *operators*: equality (`-eq`) and inequality (`-ne`); and four *relational operators*: less-than (`-lt`), less-than-or-equal-to (`-le`), greater-than (`-gt`), and
-greater-than-or-equal-to (`-ge`). Each of these has two variants (§7.8).
+greater-than-or-equal-to (`-ge`). Each of these has two variants ([§7.8][]).
For two strings to compare equal, they must have the same length and contents, and letter case, if appropriate.
Examples:
0,"00" -eq "0" # 0 (int), Length 1 ```
-### Containment operators
+### 7.8.2 Containment operators
Description:
-There are four *containment* *operators*: contains (`-contains`), does-not-contain (`ΓÇænotcontains`), in
-(`-in`) and not-in (`-notin`). Each of these has two variants (§7.8).
+There are four *containment* *operators*: contains (`-contains`), does-not-contain (`ΓÇænotcontains`),
+in (`-in`) and not-in (`-notin`). Each of these has two variants ([§7.8][]).
The containment operators return a result of type bool that indicates whether a value occurs (or does not occur) at least once in the elements of an array. With `-contains` and `ΓÇænotcontains`, the value is designated by the right operand and the array is designated by the left operand. With -in
-and `-notin`, the operands are reversed. The value is designated by the left operand and the array is
-designated by the right operand.
+and `-notin`, the operands are reversed. The value is designated by the left operand and the array
+is designated by the right operand.
For the purposes of these operators, if the array operand has a scalar value, the scalar value is treated as an array of one element.
Examples:
"Red",20,30 -ccontains "RED" # False ```
-### Type testing and conversion operators
+### 7.8.3 Type testing and conversion operators
Description:
foreach ($t in [int],$x,[decimal],"string") {
} # decimal 21.20, and string "10.6010.60" ```
-### Pattern matching and text manipulation operators
+### 7.8.4 Pattern matching and text manipulation operators
-#### The -like and -notlike operators
+#### 7.8.4.1 The -like and -notlike operators
Description: If the left operand does not designate a collection, the result has type `bool`. Otherwise, the result is a possibly empty unconstrained 1-dimensional array containing the elements of the collection that test True when compared to the value designated by the right operand. The right
-operand may designate a string that contains wildcard expressions (§3.15). These operators have two
-variants (§7.8).
+operand may designate a string that contains wildcard expressions ([§3.15][]). These operators have
+two variants ([§7.8][]).
Examples:
Examples:
"abc" and "abcgh" ```
-#### The -match and -notmatch operators
+#### 7.8.4.2 The -match and -notmatch operators
Description:
is `$true`, the elements of the Hashtable `$matches` are set to the strings that
do-not-match) the value designated by the right operand. Otherwise, the result is a possibly empty unconstrained 1-dimensional array containing the elements of the collection that test True when compared to the value designated by the right operand, and `$matches` is not set. The right operand
-may designate a string that contains regular expressions (§3.16), in which case, it is referred to
-as a *pattern*. These operators have two variants (§7.8).
+may designate a string that contains regular expressions ([§3.16][]), in which case, it is referred
+to as a *pattern*. These operators have two variants ([§7.8][]).
-These operators support submatches (§7.8.4.6).
+These operators support submatches ([§7.8.4.6][]).
Examples:
Examples:
"abc","abbcde","abcgh" -match "abc.*" # Length is 2, values "abc", "abcgh" ```
-#### The -replace operator
+#### 7.8.4.3 The -replace operator
Description: The `-replace` operator allows text replacement in one or more strings designated by the left
-operand using the values designated by the right operand. This operator has two variants (§7.8). The
-right operand has one of the following forms:
+operand using the values designated by the right operand. This operator has two variants
+([§7.8][]). The right operand has one of the following forms:
-- The string to be located, which may contain regular expressions (§3.16). In this case, the
+- The string to be located, which may contain regular expressions ([§3.16][]). In this case, the
replacement string is implicitly "". - An array of 2 objects containing the string to be located, followed by the replacement string.
If the left operand designates a string, the result has type string. If the left
a 1ΓÇædimensional array of string, the result is an unconstrained 1-dimensional array, whose length is the same as for left operand's array, containing the input strings after replacement has completed.
-This operator supports submatches (§7.8.4.6).
+This operator supports submatches ([§7.8.4.6][]).
Examples:
Examples:
"Analogous" -replace "[aeiou]",'$&$&' # "AAnaaloogoouus" ```
-#### The binary -join operator
+#### 7.8.4.4 The binary -join operator
Description: The binary `-join` operator produces a string that is the concatenation of the value of one or more
-objects designated by the left operand after having been converted to string (§6.7), if necessary.
-The string designated by the right operand is used to separate the (possibly empty) values in the
-resulting string.
+objects designated by the left operand after having been converted to string ([§6.7][]), if
+necessary. The string designated by the right operand is used to separate the (possibly empty)
+values in the resulting string.
The left operand can be a scalar value or a collection.
Examples:
($null,$null) -join "<->" # result is "<->", two zero-length values ```
-#### The binary -split operator
+#### 7.8.4.5 The binary -split operator
Description: The binary `-split` operator splits one or more strings designated by the left operand, returning their subparts in a constrained 1-dimensional array of string. This operator has two variants
-(§7.8). The left operand can designate a scalar value or an array of strings. The right operand has
-one of the following forms:
+([§7.8][]). The left operand can designate a scalar value or an array of strings. The right operand
+has one of the following forms:
- A *delimiter string* - An array of 2 objects containing a delimiter string followed by a numeric *split count*
one of the following forms:
- A script block - An array of 2 objects containing a script block followed by a numeric split count
-The delimiter string may contain regular expressions (§3.16). It is used to locate subparts with the
-input strings. The delimiter is not included in the resulting strings. If the left operand
+The delimiter string may contain regular expressions ([§3.16][]). It is used to locate subparts with
+the input strings. The delimiter is not included in the resulting strings. If the left operand
designates an empty string, that results in an empty string element. If the delimiter string is an empty string, it is found at every character position in the input strings.
Here is the set of option names:
| SimpleMatch | Use simple string comparison when evaluating the delimiter. | | Singleline | This mode recognizes only the start and end of strings. It is the default mode. |
-The script block (§7.1.8) specifies the rules for determining the delimiter, and must evaluate to
-type bool.
+The script block ([§7.1.8][]) specifies the rules for determining the delimiter, and must evaluate
+to type bool.
Examples:
Examples:
# 4 strings: "" "n" "l" "gous" ```
-#### Submatches
+#### 7.8.4.6 Submatches
The pattern being matched by `-match`, `-notmatch`, and `-replace` may contain subparts (called *submatches*) delimited by parentheses. Consider the following example:
Again, key 0 contains "red". Key 1 contains "re", key 2 contains "r", and key 3
key/value pairs are in matching order from left-to-right in the pattern, with longer string matches preceding shorter ones.
-In the case of `-replace`, the replacement text can access the submatches via names of the form `$n`,
-where the first match is `$1`, the second is `$3`, and so on. For example,
+In the case of `-replace`, the replacement text can access the submatches via names of the form
+`$n`, where the first match is `$1`, the second is `$3`, and so on. For example,
```powershell "Monday morning" -replace '(Monday|Tuesday) (morning|afternoon|evening)','the $2 of $1'
Instead of having keys in `$matches` be zero-based indexes, submatches can be na
`?<*name*>`. For example, `"((r)e)(d)"` can be written with three named submatches, m1, m2, and m3, as follows: `"(?<m1>(?<m2>r)e)(?<m3>d)"`.
-### Shift operators
+### 7.8.5 Shift operators
Description: The shift left (`-shl`) operator and shift right (`-shr`) operator convert the value designed by the left operand to an integer type and the value designated by the right operand to int, if necessary,
-using the usual arithmetic conversions (§6.15).
+using the usual arithmetic conversions ([§6.15][]).
The shift left operator shifts the left operand left by a number of bits computed as described below. The low-order empty bit positions are set to zero.
Examples:
0x100000000 -shr 0xfff81 # long with value 0x80000000 ```
-## Bitwise operators
+## 7.9 Bitwise operators
Syntax:
Description:
The bitwise AND operator `-band`, the bitwise OR operator `-bor`, and the bitwise XOR operator -bxor convert the values designated by their operands to integer types, if necessary, using the usual
-arithmetic conversions (§6.15). After conversion, if both values have type int that is the type of
-the result. Otherwise, if both values have type long, that is the type of the result. If one value
-has type int and the other has type long, the type of the result is long. Otherwise, the expression
-is ill formed. The result is the bitwise AND, bitwise OR, or bitwise XOR, respectively, of the
-possibly converted operand values.
+arithmetic conversions ([§6.15][]). After conversion, if both values have type int that is the type
+of the result. Otherwise, if both values have type long, that is the type of the result. If one
+value has type int and the other has type long, the type of the result is long. Otherwise, the
+expression is ill formed. The result is the bitwise AND, bitwise OR, or bitwise XOR, respectively,
+of the possibly converted operand values.
These operators are left associative. They are commutative if neither operand contains a side effect.
Examples:
0x0F0F -bxor 14.6 # long with value 0xF00 ```
-## Logical operators
+## 7.10 Logical operators
Syntax:
logical-expression:
Description: The logical AND operator `-and` converts the values designated by its operands to `bool`, if
-necessary (§6.2). The result is the logical AND of the possibly converted operand values, and has
-type `bool`. If the left operand evaluates to False the right operand is not evaluated.
+necessary ([§6.2][]). The result is the logical AND of the possibly converted operand values, and
+has type `bool`. If the left operand evaluates to False the right operand is not evaluated.
The logical OR operator `-or` converts the values designated by its operands to `bool`, if necessary
-(§6.2). The result is the logical OR of the possibly converted operand values, and has type `bool`.
-If the left operand evaluates to True the right operand is not evaluated.
+([§6.2][]). The result is the logical OR of the possibly converted operand values, and has type
+`bool`. If the left operand evaluates to True the right operand is not evaluated.
-The logical XOR operator `-xor` converts the values designated by its operands to `bool` (§6.2). The
-result is the logical XOR of the possibly converted operand values, and has type `bool`.
+The logical XOR operator `-xor` converts the values designated by its operands to `bool`
+([§6.2][]). The result is the logical XOR of the possibly converted operand values, and has type
+`bool`.
These operators are left associative.
$k = 20
($j -gt 10) -xor (++$k -le 25) # True -xor True -> False ```
-## Assignment operators
+## 7.11 Assignment operators
Syntax:
assignment-operator: *one of
Description: An assignment operator stores a value in the writable location designated by *expression*. For a
-discussion of *assignment-operator* `=` see §7.11.1. For a discussion of all other
-*assignment-operator*s see §7.11.2.
+discussion of *assignment-operator* `=` see [§7.11.1][]. For a discussion of all other
+*assignment-operator*s see [§7.11.2][].
An assignment expression has the value designated by *expression* after the assignment has taken place; however, that assignment expression does not itself designate a writable location. If
-*expression* is type-constrained (§5.3), the type used in that constraint is the type of the result;
-otherwise, the type of the result is the type after the usual arithmetic conversions (§6.15) have
-been applied.
+*expression* is type-constrained ([§5.3][]), the type used in that constraint is the type of the
+result; otherwise, the type of the result is the type after the usual arithmetic conversions
+([§6.15][]) have been applied.
This operator is right associative.
-### Simple assignment
+### 7.11.1 Simple assignment
Description:
values. The commas in either operand list are part of the multiple-assignment sy
represent the binary comma operator. Values are taken from the list designated by *statement*, in lexical order, and stored in the corresponding writable location designated by *expression*. If the list designated by *statement* has fewer values than there are *expression* writable locations, the
-excess locations take on the value `$null`. If the list designated by *statement* has more values than
-there are *expression* writable locations, all but the right-most *expression* location take on the
-corresponding *statement* value and the right-most *expression* location becomes an unconstrained
-1-dimensional array with all the remaining *statement* values as elements.
+excess locations take on the value `$null`. If the list designated by *statement* has more values
+than there are *expression* writable locations, all but the right-most *expression* location take on
+the corresponding *statement* value and the right-most *expression* location becomes an
+unconstrained 1-dimensional array with all the remaining *statement* values as elements.
-For statements that have values (§8.1.2), *statement* can be a statement.
+For statements that have values ([§8.1.2][]), *statement* can be a statement.
Examples:
$Alias:A = "Demo" # create alias for function Demo
A # invoke function Demo via the alias ```
-### Compound assignment
+### 7.11.2 Compound assignment
Description: A *compound assignment* has the form `E1 op= E2`, and is equivalent to the simple assignment expression `E1 = E1 op (E2)` except that in the compound assignment case the expression *E1* is
-evaluated only once. If *expression* is type-constrained (§5.3), the type used in that constraint is
-the type of the result; otherwise, the type of the result is determined by *op*. (For `*=`, see
-§7.6.1, §7.6.2, §7.6.3; for `/=`, see §7.6.4; for `%=`, see §7.6.5; for `+=`, see §7.7.1, §7.7.2, §7.7.3;
-for `-=`, see §7.7.5.)
+evaluated only once. If *expression* is type-constrained ([§5.3][]), the type used in that
+constraint is the type of the result; otherwise, the type of the result is determined by *op*. For
+`*=`, see [§7.6.1][], [§7.6.2][], [§7.6.3][]; for `/=`, see [§7.6.4][]; for `%=`, see [§7.6.5][];
+for `+=`, see [§7.7.1][], [§7.7.2][], [§7.7.3][]; for `-=`, see [§7.7.5][].
> [!NOTE] > An operand designating an unconstrained value of numeric type may have its type changed by an
${E:output.txt} += "b" # append text to the file giving ab
${E:output.txt} *= 4 # replicate ab 4 times giving abababab ```
-## Redirection operators
+## 7.12 Redirection operators
Syntax:
dir -Verbose -Debug -WarningAction Continue *> output2.txt
# to the same location as error output dir -Verbose 4>&2 2> error2.txt ```+
+<!-- reference links -->
+[§2.3.5.2]: chapter-02.md#2352-string-literals
+[§3.15]: chapter-03.md#315-wildcard-expressions
+[§3.16]: chapter-03.md#316-regular-expressions
+[§4.3.7]: chapter-04.md#437-the-scriptblock-type
+[§4.4]: chapter-04.md#44-generic-types
+[§4.5.24]: chapter-04.md#4524-method-designator-type
+[§5.3]: chapter-05.md#53-constrained-variables
+[§6.15]: chapter-06.md#615-usual-arithmetic-conversions
+[§6.17]: chapter-06.md#617-conversion-during-parameter-binding
+[§6.2]: chapter-06.md#62-conversion-to-bool
+[§6.4]: chapter-06.md#64-conversion-to-integer
+[§6.7]: chapter-06.md#67-conversion-to-object
+[§6.8]: chapter-06.md#68-conversion-to-string
+[§7.1.1]: chapter-07.md#711-grouping-parentheses
+[§7.1.2]: chapter-07.md#712-member-access
+[§7.1.4.5]: chapter-07.md#7145-generating-array-slices
+[§7.1.6]: chapter-07.md#716--operator
+[§7.1.8]: chapter-07.md#718-script-block-expression
+[§7.11.1]: chapter-07.md#7111-simple-assignment
+[§7.11.2]: chapter-07.md#7112-compound-assignment
+[§7.11]: chapter-07.md#711-assignment-operators
+[§7.2.9]: chapter-07.md#729-cast-operator
+[§7.6.1]: chapter-07.md#761-multiplication
+[§7.6.2]: chapter-07.md#762-string-replication
+[§7.6.3]: chapter-07.md#763-array-replication
+[§7.6.4]: chapter-07.md#764-division
+[§7.6.5]: chapter-07.md#765-remainder
+[§7.7.1]: chapter-07.md#771-addition
+[§7.7.2]: chapter-07.md#772-string-concatentaion
+[§7.7.3]: chapter-07.md#773-array-concatenation
+[§7.7.5]: chapter-07.md#775-subtraction
+[§7.7]: chapter-07.md#77-additive-operators
+[§7.8.4.4]: chapter-07.md#7844-the-binary--join-operator
+[§7.8.4.5]: chapter-07.md#7845-the-binary--split-operator
+[§7.8.4.6]: chapter-07.md#7846-submatches
+[§7.8]: chapter-07.md#78-comparison-operators
+[§8.1.2]: chapter-08.md#812-statement-values
+[§8.10.1]: chapter-08.md#8101-filter-functions
+[§8.10.2]: chapter-08.md#8102-workflow-functions
+[§8.10.7]: chapter-08.md#8107-named-blocks
+[§8.10.9]: chapter-08.md#8109-param-block
+[§9.]: chapter-09.md#9-arrays
+[§9.12]: chapter-09.md#912-multidimensional-array-flattening
+[§9.4]: chapter-09.md#94-constraining-element-types
+[§9.9]: chapter-09.md#99-array-slices
lang-spec Chapter 08 https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/lang-spec/chapter-08.md
description: A statement specifies some sort of action that is to be performed.
Last updated 05/19/2021 Title: Statements ---
-# Statements
+# 8. Statements
-## Statement blocks and lists
+## 8.1 Statement blocks and lists
Syntax:
within this clause, statements are executed in lexical order.
A *statement-block* allows a set of statements to be grouped into a single syntactic unit.
-### Labeled statements
+### 8.1.1 Labeled statements
Syntax:
labeled-statement:
Description:
-An iteration statement (§8.4) or a switch statement (§8.6) may optionally be preceded immediately by
-one statement label, *label*. A statement label is used as the optional target of a break (§8.5.1)
-or continue (§8.5.2) statement. However, a label does not alter the flow of control.
+An iteration statement ([§8.4][]) or a switch statement ([§8.6][]) may optionally be preceded
+immediately by one statement label, *label*. A statement label is used as the optional target of a
+break ([§8.5.1][]) or continue ([§8.5.2][]) statement. However, a label does not alter the flow of
+control.
White space is not permitted between the colon (`:`) and the token that follows it.
for ($i = 1; $i -le 5; ++$i) {
} ```
-### Statement values
+### 8.1.2 Statement values
The value of a statement is the cumulative set of values that it writes to the pipeline. If the statement writes a single scalar value, that is the value of the statement. If the statement writes
$v = while ($i -le 5) {
# $v is object[], Length 8, value 1,"odd",2,3,"odd",4,5,"odd" ```
-## Pipeline statements
+## 8.2 Pipeline statements
Syntax:
verbatim-command-argument:
Description:
-*redirections* is discussed in §7.12; *assignment-expression* is discussed in §7.11; and the
-*command-invocation-operator* dot (`.`) is discussed in §3.5.5. For a discussion of
-argument-to-parameter mapping in command invocations, see §8.14.
+*redirections* is discussed in [§7.12][]; *assignment-expression* is discussed in [§7.11][]; and the
+*command-invocation-operator* dot (`.`) is discussed in [§3.5.5][]. For a discussion of
+argument-to-parameter mapping in command invocations, see [§8.14][].
The first command in a *pipeline* is an expression or a command invocation. Typically, a command invocation begins with a *command-name*, which is usually a bare identifier. *command-elements*
governing arguments are as follows:
- An argument that is not an expression, but which contains arbitrary text without unescaped white space, is treated as though it were double quoted. Letter case is preserved. -- Variable substitution and sub-expression expansion (§2.3.5.2) takes place inside
+- Variable substitution and sub-expression expansion ([§2.3.5.2][]) takes place inside
*expandable-string-literal*s and *expandable-here-string-literal*s. - Text inside quotes allows leading, trailing, and embedded white space to be included in the
governing arguments are as follows:
- Putting parentheses around an argument causes that expression to be evaluated with the result being passed instead of the text of the original expression. -- To pass an argument that looks like a switch parameter (§2.3.4) but is not intended as such,
+- To pass an argument that looks like a switch parameter ([§2.3.4][]) but is not intended as such,
enclose that argument in quotes. - When specifying an argument that matches a parameter having the `[switch]` type constraint
- (§8.10.5), the presence of the argument name on its own causes that parameter to be set to
+ ([§8.10.5][]), the presence of the argument name on its own causes that parameter to be set to
`$true`. However, the parameter's value can be set explicitly by appending a suffix to the argument. For example, given a type constrained parameter *p*, an argument of `-p:$true` sets p to True, while `-p:$false` sets p to False.
governing arguments are as follows:
- An argument of `--` indicates that all arguments following it are to be passed in their actual form as though double quotes were placed around them. -- An argument of `--%` indicates that all arguments following it are to be passed with minimal parsing
- and processing. This argument is called the verbatim parameter. Arguments after the verbatim
- parameter are not PowerShell expressions even if they are syntactically valid PowerShell
+- An argument of `--%` indicates that all arguments following it are to be passed with minimal
+ parsing and processing. This argument is called the verbatim parameter. Arguments after the
+ verbatim parameter are not PowerShell expressions even if they are syntactically valid PowerShell
expressions. If the command type is Application, the parameter `--%` is not passed to the command. The arguments
echoargs.exe --% "%path%" # %path% is replaced with the value $env:path
The order of evaluation of arguments is unspecified.
-For information about parameter binding see §8.14. For information about name lookup see §3.8.
+For information about parameter binding see [§8.14][]. For information about name lookup see
+[§3.8][].
Once argument processing has been completed, the command is invoked. If the invoked command
-terminates normally (§8.5.4), control reverts to the point in the script or function immediately
+terminates normally ([§8.5.4][]), control reverts to the point in the script or function immediately
following the command invocation. For a description of the behavior on abnormal termination see
-`break` (§8.5.1), `continue` (§8.5.2), `throw` (§8.5.3), `exit` (§8.5.5), `try` (§8.7), and `trap`
-(§8.8).
+`break` ([§8.5.1][]), `continue` ([§8.5.2][]), `throw` ([§8.5.3][]), `exit` ([§8.5.5][]), `try`
+([§8.7][]), and `trap` ([§8.8][]).
Ordinarily, a command is invoked by using its name followed by any arguments. However, the command-invocation operator, &, can be used. If the command name contains unescaped white space, it
dir e:\PowerShell\Scripts\*statement*.ps1 | Foreach-Object {$_.Length}
dir e:\PowerShell\Scripts\*.ps1 | Select-String -List "catch" | Format-Table path,linenumber -AutoSize ```
-## The if statement
+## 8.3 The if statement
Syntax:
elseif ($grade -ge 60) { "Grade D" }
else { "Grade F" } ```
-## Iteration statements
+## 8.4 Iteration statements
-### The while statement
+### 8.4.1 The while statement
Syntax:
while ($i -le 5) { # loop 5 times
} ```
-### The do statement
+### 8.4.2 The do statement
Syntax:
do {
until (++$i -gt 5) # loop 5 times ```
-### The for statement
+### 8.4.3 The for statement
Syntax:
for (; $i -ge 1; ) { # equivalent behavior
} ```
-### The foreach statement
+### 8.4.4 The foreach statement
Syntax:
value `$null`, *pipeline* is treated as a collection of zero elements.
If the *foreach-parameter* `-parallel` is specified, the behavior is implementation defined.
-The *foreach-parameter* `‑parallel` is only allowed in a workflow (§8.10.2).
+The *foreach-parameter* `‑parallel` is only allowed in a workflow ([§8.10.2][]).
-Every foreach statement has its own enumerator, `$foreach` (§2.3.2.2, §4.5.16), which exists only
-while that loop is executing.
+Every foreach statement has its own enumerator, `$foreach` ([§2.3.2.2][], [§4.5.16][]), which exists
+only while that loop is executing.
The objects produced by *pipeline* are collected before *statement-block* begins to execute.
-However, with the `ForEach-Object` cmdlet (§13.12), *statement-block* is executed on each object as
-it is produced.
+However, with the [ForEach-Object](xref:Microsoft.PowerShell.Core.ForEach-Object) cmdlet,
+*statement-block* is executed on each object as it is produced.
Examples:
foreach ($e in $h1.Keys) {
} ```
-## Flow control statements
+## 8.5 Flow control statements
Syntax:
Description:
A flow-control statement causes an unconditional transfer of control to some other location.
-### The break statement
+### 8.5.1 The break statement
Description: A break statement with a *label-expression* is referred to as a *labeled break statement*. A break statement without a *label-expression* is referred to as an *unlabeled break statement*.
-Outside a trap statement, an unlabeled break statement directly within an iteration statement (§8.4)
-terminates execution of that smallest enclosing iteration statement. An unlabeled break statement
-directly within a switch statement (§8.6) terminates pattern matching for the current switch's
-*switch-condition*. See (§8.8) for details of using break from within a trap statement.
+Outside a trap statement, an unlabeled break statement directly within an iteration statement
+([§8.4][]) terminates execution of that smallest enclosing iteration statement. An unlabeled break
+statement directly within a switch statement ([§8.6][]) terminates pattern matching for the current
+switch's *switch-condition*. See ([§8.8][]) for details of using break from within a trap statement.
An iteration statement or a switch statement may optionally be preceded immediately by one statement
-label (§8.1.1).Such a statement label may be used as the target of a labeled break statement, in
+label ([§8.1.1][]).Such a statement label may be used as the target of a labeled break statement, in
which case, that statement terminates execution of the targeted enclosing iteration statement. A labeled break need not be resolved in any local scope; the search for a matching label may
for ($i = 1; $i -le 2; $i++) {
} ```
-### The continue statement
+### 8.5.2 The continue statement
Description: A `continue` statement with a *label-expression* is referred to as a *labeled continue statement*. A continue statement without a *label-expression* is referred to as an *unlabeled continue statement*.
-The use of `continue` from within a trap statement is discussed in §8.8.
+The use of `continue` from within a trap statement is discussed in [§8.8][].
An unlabeled `continue` statement within a loop terminates execution of the current loop and
-transfers control to the closing brace of the smallest enclosing iteration statement (§8.4). An
+transfers control to the closing brace of the smallest enclosing iteration statement ([§8.4][]). An
unlabeled `continue` statement within a switch terminates execution of the current `switch`
-iteration and transfers control to the smallest enclosing `switch`'s *switch-condition* (§8.6).
+iteration and transfers control to the smallest enclosing `switch`'s *switch-condition* ([§8.6][]).
-An iteration statement or a `switch` statement (§8.6) may optionally be preceded immediately by one
-statement label (§8.1.1). Such a statement label may be used as the target of an enclosed labeled
-`continue` statement, in which case, that statement terminates execution of the current loop or
-`switch` iteration, and transfers control to the targeted enclosing iteration or `switch` statement
-label.
+An iteration statement or a `switch` statement ([§8.6][]) may optionally be preceded immediately by
+one statement label ([§8.1.1][]). Such a statement label may be used as the target of an enclosed
+labeled `continue` statement, in which case, that statement terminates execution of the current loop
+or `switch` iteration, and transfers control to the targeted enclosing iteration or `switch`
+statement label.
A labeled `continue` need not be resolved in any local scope; the search for a matching label may `continue` up the calling stack even across script and function-call boundaries. If no matching
for ($i = 1; $i -le 2; $i++) {
} ```
-### The throw statement
+### 8.5.3 The throw statement
Description: An exception is a way of handling a system- or application-level error condition. The throw
-statement raises an exception. (See §8.7 for a discussion of exception handling.)
+statement raises an exception. (See [§8.7][] for a discussion of exception handling.)
If *pipeline* is omitted and the throw statement is not in a *catch-clause*, the behavior is implementation defined. If *pipeline* is present and the throw statement is in a *catch-clause*, the
If *pipeline* is present, the type of the exception thrown is implementation def
When an exception is thrown, control is transferred to the first catch clause in an enclosing try statement that can handle the exception. The location at which the exception is thrown initially is
-called the *throw point*. Once an exception is thrown the steps described in §8.7 are followed
+called the *throw point*. Once an exception is thrown the steps described in [§8.7][] are followed
repeatedly until a catch clause that matches the exception is found or none can be found. Examples:
Example 3: `throw 10,20` results in an exception of type **RuntimeException**. F
block, `$_.TargetObject` contains the object wrapped inside, in this case, a `System.Object[]`, an unconstrained array of two elements with the `System`.Int32` values 10 and 20.
-### The return statement
+### 8.5.4 The return statement
Description:
function Test {
The caller to `Test` gets back an unconstrained 1-dimensional array of three elements.
-### The exit statement
+### 8.5.5 The exit statement
Description:
Examples:
exit $count # terminate the script with some accumulated count ```
-## The switch statement
+## 8.6 The switch statement
Syntax:
patterns with different types.
If the value of *switch-condition* matches a pattern value, that pattern's *statement-block* is executed. If multiple pattern values match the value of *switch-condition*, each matching pattern's *statement-block* is executed, in lexical order, unless any of those *statement-block*s contains a
-`break` statement (§8.5.1).
+`break` statement ([§8.5.1][]).
If the value of *switch-condition* does not match any pattern value, if a `default` switch clause exists, its *statement-block* is executed; otherwise, pattern matching for that *switch-condition*
On entry to each *statement-block*, `$_` is automatically assigned the value of
*switch-condition* that caused control to go to that *statement-block*. `$_` is also available in that *statement-block*'s *switch-clause-condition*.
-Matching of non-strings is done by testing for equality (§7.8.1).
+Matching of non-strings is done by testing for equality ([§7.8.1][]).
If the matching involves strings, by default, the comparison is case-insensitive. The presence of the *switch-parameter* `-casesensitive` makes the comparison case-sensitive.
-A pattern may contain wildcard characters (§3.15), in which case, wildcard string comparisons are
-performed, but only if the *switch-parameter* -wildcard is present. By default, the comparison is
-case-insensitive.
+A pattern may contain wildcard characters ([§3.15][]), in which case, wildcard string comparisons
+are performed, but only if the *switch-parameter* -wildcard is present. By default, the comparison
+is case-insensitive.
-A pattern may contain a regular expression (§3.16), in which case, regular expression string
+A pattern may contain a regular expression ([§3.16][]), in which case, regular expression string
comparisons are performed, but only if the *switch-parameter* `-regex` is present. By default, the comparison is case-insensitive. If `-regex` is present and a pattern is matched, `$matches` is defined in the *switch-clause* *statement-block* for that pattern.
If conflicting *switch-parameter*s are specified, the lexically final one prevai
If the *switch-parameter* `ΓÇæparallel` is specified, the behavior is implementation defined.
-The *switch-parameter* `‑parallel` is only allowed in a workflow (§8.10.2).
+The *switch-parameter* `‑parallel` is only allowed in a workflow ([§8.10.2][]).
If a pattern is a *script-block-expression*, that block is evaluated and the result is converted to bool, if necessary. If the result has the value `$true`, the corresponding *statement-block* is
executed; otherwise, it is not.
If *switch-condition* designates multiple values, the switch is applied to each value in lexical order using the rules described above for a *switch-condition* that designates a single value. Every
-switch statement has its own enumerator, `$switch` (§2.3.2.2, §4.5.16), which exists only while that
-switch is executing.
+switch statement has its own enumerator, `$switch` ([§2.3.2.2][], [§4.5.16][]), which exists only
+while that switch is executing.
-A switch statement may have a label, and it may contain labeled and unlabeled break (§8.5.1) and
-continue (§8.5.2) statements.
+A switch statement may have a label, and it may contain labeled and unlabeled break ([§8.5.1][]) and
+continue ([§8.5.2][]) statements.
If *switch-condition* is `-file` *switch-filename*, instead of iterating over the values in an expression, the switch iterates over the values in the file designated by *switch-filename*.The file
switch (0, 1, 19, 20, 21) {
} ```
-## The try/finally statement
+## 8.7 The try/finally statement
Syntax:
Description:
The try statement provides a mechanism for catching exceptions that occur during execution of a block. The try statement also provides the ability to specify a block of code that is always executed when control leaves the try statement. The process of raising an exception via the throw
-statement is described in §8.5.3.
+statement is described in [§8.5.3][].
A *try block* is the *statement-block* associated with the try statement. A *catch block* is the *statement-block* associated with a *catch-clause*. A *finally block* is the *statement-block*
next enclosing `try` statement. If another exception was in the process of being
exception is lost. The process of generating an exception is further discussed in the description of the `throw` statement.
-`try` statements can co-exist with `trap` statements; see §8.8 for details.
+`try` statements can co-exist with `trap` statements; see [§8.8][] for details.
Examples:
Each exception thrown is raised as a `System.Management.Automation.RuntimeExcept
type-specific *catch-clause*s in the `try` block, the **InnerException** property of the exception is inspected to try and find a match, such as with the type `System.IndexOutOfRangeException` above.
-## The trap statement
+## 8.8 The trap statement
Syntax:
trap-statement:
Description:
-A `trap` statement with and without *type-literal* is analogous to a `catch` block (§8.7) with and
-without *catch-type-list*, respectively, except that a `trap` statement can trap only one type at a
-time.
+A `trap` statement with and without *type-literal* is analogous to a `catch` block ([§8.7][]) with
+and without *catch-type-list*, respectively, except that a `trap` statement can trap only one type
+at a time.
Multiple `trap` statements can be defined in the same *statement-block*, and their order of definition is irrelevant. If two `trap` statements with the same *type-literal* are defined in the
same scope, the lexically first one is used to process an exception of matching
Unlike a `catch` block, a `trap` statement matches an exception type exactly; no derived type matching is performed.
-When an exception occurs, if no matching `trap` statement is present in the current scope, a matching
-trap statement is searched for in the enclosing scope, which may involve looking in the calling
-script, function, or filter, and then in its caller, and so on. If the lookup ends up terminating
-all scopes, indicating that no handler exists for the exception, then the behavior is unspecified.
+When an exception occurs, if no matching `trap` statement is present in the current scope, a
+matching trap statement is searched for in the enclosing scope, which may involve looking in the
+calling script, function, or filter, and then in its caller, and so on. If the lookup ends up
+terminating all scopes, indicating that no handler exists for the exception, then the behavior is
+unspecified.
-A `trap` statement's *statement-body* only executes to process the corresponding exception; otherwise,
-execution passes over it.
+A `trap` statement's *statement-body* only executes to process the corresponding exception;
+otherwise, execution passes over it.
If a `trap`'s *statement-body* exits normally, by default, an error object is written to the error stream, the exception is considered handled, and execution continues with the statement immediately following the one in the scope containing the `trap` statement that made the exception visible. The cause of the exception might be in a command called by the command containing the `trap` statement.
-If the final statement executed in a `trap`'s *statement-body* is continue (§8.5.2), the writing of
-the error object to the error stream is suppressed, and execution continues with the statement
+If the final statement executed in a `trap`'s *statement-body* is continue ([§8.5.2][]), the writing
+of the error object to the error stream is suppressed, and execution continues with the statement
immediately following the one in the scope containing the trap statement that made the exception
-visible. If the final statement executed in a `trap`'s *statement-body* is break (§8.5.1), the
+visible. If the final statement executed in a `trap`'s *statement-body* is break ([§8.5.1][]), the
writing of the error object to the error stream is suppressed, and the exception is re-thrown. Within a `trap` statement the variable `$_` contains a description of the current error.
After the exception is caught and handled, execution resumes with writing 2 (not
trap{} &{throw '\...'; 1}; 2 ```
-## The data statement
+## 8.9 The data statement
Syntax:
only:
- Pipelines - Statements separated by semicolons (`;`) - Literals-- Calls to the `ConvertFrom-StringData` cmdlet (§13.7)
+- Calls to the [ConvertFrom-StringData](xref:Microsoft.PowerShell.Utility.ConvertFrom-StringData)
+ cmdlet
- Any other cmdlets identified via the **supportedcommand** parameter If the `ConvertFrom-StringData` cmdlet is used, the key/value pairs can be expressed using any form
If *dataname* is present, it names the variable (without using a leading `$`) in
of the data statement is to be stored. Specifically, `$name = data { ... }` is equivalent to `data name { ... }`.
-## Function definitions
+## 8.10 Function definitions
Syntax:
achieve that function's purpose.
Each function is an instance of the class `System.Management.Automation.FunctionInfo`.
-### Filter functions
+### 8.10.1 Filter functions
Whereas an ordinary function runs once in a pipeline and accesses the input collection via `$input`, a *filter* is a special kind of function that executes once for each object in the input collection. The object currently being processed is available via the variable `$_`.
-A filter with no named blocks (§8.10.7) is equivalent to a function with a process block, but
+A filter with no named blocks ([§8.10.7][]) is equivalent to a function with a process block, but
without any begin block or end block. Consider the following filter function definition and calls:
filter Get-Square2 { # make the function a filter
6, 10, -3 | Get-Square2 # collection has 3 elements ```
-Each filter is an instance of the class `System.Management.Automation.FilterInfo` (§4.5.11).
+Each filter is an instance of the class `System.Management.Automation.FilterInfo` ([§4.5.11][]).
-### Workflow functions
+### 8.10.2 Workflow functions
A workflow function is like an ordinary function with implementation defined semantics. A workflow function is translated to a sequence of Windows Workflow Foundation activities and executed in the Windows Workflow Foundation engine.
-### Argument processing
+### 8.10.3 Argument processing
Consider the following definition for a function called `Get-Power`:
that, for non-negative exponent values, computes `$base^$exponent^` and returns
`Get-Power`'s caller. When a script, function, or filter begins execution, each parameter is initialized to its
-corresponding argument's value. If there is no corresponding argument and a default value (§8.10.4)
-is supplied, that value is used; otherwise, the value `$null` is used. As such, each parameter is a
-new variable just as if it was initialized by assignment at the start of the *script-block*.
+corresponding argument's value. If there is no corresponding argument and a default value
+([§8.10.4][]) is supplied, that value is used; otherwise, the value `$null` is used. As such, each
+parameter is a new variable just as if it was initialized by assignment at the start of the
+*script-block*.
If a *script-parameter* contains a type constraint (such as `[long]` and `[int]` above), the value of the corresponding argument is converted to that type, if necessary; otherwise, no conversion
F -a 2 -d 3 4 5 # $a is 2, $b is 4, $c is 5, $d is 3, $args Length 0
F 2 3 4 5 -c 7 -a 1 # $a is 1, $b is 2, $c is 7, $d is 3, $args Length 2 ```
-For more information about parameter binding see §8.14.
+For more information about parameter binding see [§8.14][].
-### Parameter initializers
+### 8.10.4 Parameter initializers
The declaration of a parameter *p* may contain an initializer, in which case, that initializer's value is used to initialize *p* provided *p* is not bound to any arguments in the call.
Find-Str "abcabc" # 2nd argument omitted, 0 used for $start_pos
Find-Str "abcabc" 2 # 2nd argument present, so it is used for $start_pos ```
-### The [switch] type constraint
+### 8.10.5 The [switch] type constraint
When a switch parameter is passed, the corresponding parameter in the command must be constrained by the type switch. Type switch has two values, True and False.
Process 10 20 -trace:$false # $trace is False, $p1 is 10, $p2 is 20
Process 10 20 -trace:$true # $trace is True, $p1 is 10, $p2 is 20 ``` -
-### Pipelines and functions
+### 8.10.6 Pipelines and functions
When a script, function, or filter is used in a pipeline, a collection of values is delivered to that script or function. The script, function, or filter gets access to that collection via the
-enumerator $input (§2.3.2.2, §4.5.16), which is defined on entry to that script, function, or
-filter.
+enumerator $input ([§2.3.2.2][], [§4.5.16][]), which is defined on entry to that script, function,
+or filter.
Consider the following function definition and calls:
function Get-Square1 {
6, 10, -3 | Get-Square1 # collection has 3 elements ```
-### Named blocks
+### 8.10.7 Named blocks
The statements within a *script-block* can belong to one large unnamed block, or they can be distributed into one or more named blocks. Named blocks allow custom processing of collections
as there is no current collection object.
The statements in an *end block* (i.e.; one marked with the keyword end) are executed once, after the last pipeline object has been delivered.
-### dynamicParam block
+### 8.10.8 dynamicParam block
-The subsections of §8.10 thus far deal with *static parameters*, which are defined as part of the
-source code. It is also possible to define *dynamic parameters* via a *dynamicParam block*, another
-form of named block (§8.10.7), which is marked with the keyword `dynamicParam`. Much of this
-machinery is implementation defined.
+The subsections of [§8.10][] thus far deal with *static parameters*, which are defined as part of
+the source code. It is also possible to define *dynamic parameters* via a *dynamicParam block*,
+another form of named block ([§8.10.7][]), which is marked with the keyword `dynamicParam`. Much of
+this machinery is implementation defined.
Dynamic parameters are parameters of a cmdlet, function, filter, or script that are available under certain conditions only. One such case is the **Encoding** parameter of the `Set-Item` cmdlet. In the *statement-block*, use an if statement to specify the conditions under which the parameter is
-available in the function. Use the `New-Object` cmdlet (§13.35) to create an object of an
-implementation-defined type to represent the parameter, and specify its name. Also, use `New-Object`
-to create an object of a different implementation-defined type to represent the
-implementation-defined attributes of the parameter.
+available in the function. Use the [New-Object](xref:Microsoft.PowerShell.Utility.New-Object) cmdlet
+to create an object of an implementation-defined type to represent the parameter, and specify its
+name. Also, use `New-Object` to create an object of a different implementation-defined type to
+represent the implementation-defined attributes of the parameter.
The following example shows a function with standard parameters called Name and Path, and an optional dynamic parameter named **DP1**. The **DP1** parameter is in the PSet1 parameter set and
The type used to create an object to represent the attributes of the parameter i
The implementation-defined attributes of the parameter include **Mandatory**, **Position**, and **ValueFromPipeline**.
-### param block
+### 8.10.9 param block
A *param-block* provides an alternate way of declaring parameters. For example, the following sets of parameter declarations are equivalent:
param ( [Parameter(Mandatory = $true, ValueFromPipeline=$true)]
The one parameter, `$ComputerName`, has type `string[]`, it is required, and it takes input from the pipeline.
-See §12.3.7 for a discussion of the **Parameter** attribute and for more examples.
+See [§12.3.7][] for a discussion of the **Parameter** attribute and for more examples.
-## The parallel statement
+## 8.11 The parallel statement
Syntax:
parallel-statement:
The parallel statement contains zero or more statements that are executed in an implementation defined manner.
-A parallel statement is only allowed in a workflow (§8.10.2).
+A parallel statement is only allowed in a workflow ([§8.10.2][]).
-## The sequence statement
+## 8.12 The sequence statement
Syntax:
sequence-statement:
The sequence statement contains zero or more statements that are executed in an implementation defined manner.
-A sequence statement is only allowed in a workflow (§8.10.2).
+A sequence statement is only allowed in a workflow ([§8.10.2][]).
-## The inlinescript statement
+## 8.13 The inlinescript statement
Syntax:
inlinescript-statement:
The inlinescript statement contains zero or more statements that are executed in an implementation defined manner.
-A inlinescript statement is only allowed in a workflow (§8.10.2).
+A inlinescript statement is only allowed in a workflow ([§8.10.2][]).
-## Parameter binding
+## 8.14 Parameter binding
When a script, function, filter, or cmdlet is invoked, each argument can be bound to the corresponding parameter by position, with the first parameter having position zero.
parameter by name. This is done by using a *parameter with argument*, which is a
the parameter's name with a leading dash (-), followed by the associated value for that argument. The parameter name used can have any case-insensitive spelling and can use any prefix that uniquely designates the corresponding parameter. When choosing parameter names, avoid using the names of the
-common parameters (§13.56).
+[common parameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters).
Consider the following calls to function `Get-Power`:
The same parameter name cannot be used multiple times with or without different
values. Parameters can have attributes (§12). For information about the individual attributes see the
-sections within §12.3. For information about parameter sets see §12.3.7.
+sections within [§12.3][]. For information about parameter sets see [§12.3][].7.
A script, function, filter, or cmdlet can receive arguments via the invocation command line, from the pipeline, or from both. Here are the steps, in order, for resolving parameter binding: 1. Bind all named parameters, then 1. Bind positional parameters, then
-1. Bind from the pipeline by value (§12.3.7) with exact match, then
-1. Bind from the pipeline by value (§12.3.7) with conversion, then
-1. Bind from the pipeline by name (§12.3.7) with exact match, then
-1. Bind from the pipeline by name (§12.3.7) with conversion
+1. Bind from the pipeline by value ([§12.3.7][]) with exact match, then
+1. Bind from the pipeline by value ([§12.3.7][]) with conversion, then
+1. Bind from the pipeline by name ([§12.3.7][]) with exact match, then
+1. Bind from the pipeline by name ([§12.3.7][]) with conversion
-Several of these steps involve conversion, as described in §6. However, the set of conversions used
-in binding is not exactly the same as that used in language conversions. Specifically,
+Several of these steps involve conversion, as described in [§6.][] However, the set of conversions
+used in binding is not exactly the same as that used in language conversions. Specifically,
- Although the value `$null` can be cast to bool, `$null` cannot be bound to `bool`.-- When the value `$null` is passed to a switch parameter for a cmdlet, it is treated as if `$true` was
- passed. However, when passed to a switch parameter for a function, it is treated as if `$false` was
- passed.
+- When the value `$null` is passed to a switch parameter for a cmdlet, it is treated as if `$true`
+ was passed. However, when passed to a switch parameter for a function, it is treated as if
+ `$false` was passed.
- Parameters of type bool or switch can only bind to numeric or bool arguments. - If the parameter type is not a collection, but the argument is some sort of collection, no conversion is attempted unless the parameter type is object or PsObject. (The main point of this
function Test {
Test 42d # outputs "SetA" Test 42 # outputs "SetB" ```+
+<!-- reference links -->
+[§12.3.7]: chapter-12.md#1237-the-parameter-attribute
+[§12.3]: chapter-12.md#123-reserved-attributes
+[§2.3.2.2]: chapter-02.md#2322-automatic-variables
+[§2.3.4]: chapter-02.md#234-parameters
+[§2.3.5.2]: chapter-02.md#2352-string-literals
+[§3.15]: chapter-03.md#315-wildcard-expressions
+[§3.16]: chapter-03.md#316-regular-expressions
+[§3.5.5]: chapter-03.md#355-dot-source-notation
+[§3.8]: chapter-03.md#38-name-lookup
+[§4.5.11]: chapter-04.md#4511-filter-description-type
+[§4.5.16]: chapter-04.md#4516-enumerator-description-type
+[§6.]: chapter-06.md#6-conversions
+[§7.11]: chapter-07.md#711-assignment-operators
+[§7.12]: chapter-07.md#712-redirection-operators
+[§7.8.1]: chapter-07.md#781-equality-and-relational-operators
+[§8.1.1]: chapter-08.md#811-labeled-statements
+[§8.10.2]: chapter-08.md#8102-workflow-functions
+[§8.10.4]: chapter-08.md#8104-parameter-initializers
+[§8.10.5]: chapter-08.md#8105-the-switch-type-constraint
+[§8.10.7]: chapter-08.md#8107-named-blocks
+[§8.10]: chapter-08.md#810-function-definitions
+[§8.14]: chapter-08.md#814-parameter-binding
+[§8.4]: chapter-08.md#84-iteration-statements
+[§8.5.1]: chapter-08.md#851-the-break-statement
+[§8.5.2]: chapter-08.md#852-the-continue-statement
+[§8.5.3]: chapter-08.md#853-the-throw-statement
+[§8.5.4]: chapter-08.md#854-the-return-statement
+[§8.5.5]: chapter-08.md#855-the-exit-statement
+[§8.6]: chapter-08.md#86-the-switch-statement
+[§8.7]: chapter-08.md#87-the-tryfinally-statement
+[§8.8]: chapter-08.md#88-the-trap-statement
lang-spec Chapter 09 https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/lang-spec/chapter-09.md
description: PowerShell supports arrays of one or more dimensions with each dime
Last updated 05/19/2021 Title: Arrays ---
-# Arrays
+# 9. Arrays
-## Introduction
+## 9.1 Introduction
PowerShell supports arrays of one or more dimensions with each dimension having zero or more *elements*. Within a dimension, elements are numbered in ascending integer order starting at zero.
-Any individual element can be accessed via the array subscript operator `[]` (§7.1.4). The number of
-dimensions in an array is called its *rank*.
+Any individual element can be accessed via the array subscript operator `[]` ([§7.1.4][]). The
+number of dimensions in an array is called its *rank*.
An element can contain a value of any type including an array type. An array having one or more elements whose values are of any array type is called a *jagged array*. A *multidimensional array*
$a[1,1] = $null
A 1-dimensional array has type `type[]`, a 2-dimensional array has type `type[,]`, a 3-dimensional array has type `type[,,]`, and so on, where *type* is object for an unconstrained type array, or the
-constrained type for a constrained array (§9.4).
+constrained type for a constrained array ([§9.4][]).
-All array types are derived from the type Array (§4.3.2).
+All array types are derived from the type Array ([§4.3.2][]).
-## Array creation
+## 9.2 Array creation
An array is created via an *array creation expression*, which has the following forms: unary comma
-operator (§7.2.1) ,*array-expression* (§7.1.7), binary comma operator (§7.3), range operator (§7.4),
-or New-Object cmdlet (§13.36).
+operator ([§7.2.1][]) ,*array-expression* ([§7.1.7][]), binary comma operator ([§7.3][]), range
+operator ([§7.4][]), or [New-Object](xref:Microsoft.PowerShell.Utility.New-Object) cmdlet.
Here are some examples of array creation and usage:
red
The default initial value of any element not explicitly initialized is the default value for that element's type (that is, `$false`, zero, or `$null`).
-## Array concatenation
+## 9.3 Array concatenation
Arrays of arbitrary type and length can be concatenated via the `+` and `+=` operators, both of which result in the creation of a new unconstrained 1-dimensional array. The existing arrays are
-unchanged. See §7.7.3 for more information, and §9.4 for a discussion of adding to an array of
-constrained type.
+unchanged. See [§7.7.3][] for more information, and [§9.4][] for a discussion of adding to an array
+of constrained type.
-## Constraining element types
+## 9.4 Constraining element types
A 1-dimensional array can be created so that it is type-constrained by prefixing the array-creation expression with an array type cast. For example,
$a[1] = "abc" # implementation-defined behavior
$a += 1.23 # new array is unconstrained ```
-The syntax for creating a multidimensional array requires the specification of a type (§13.36), and
-that type becomes the constraint type for that array. However, by specifying type `object[]`, there
-really is no constraint as a value of any type can be assigned to an element of an array of that
-type.
+The syntax for creating a multidimensional array requires the specification of a type, and that type
+becomes the constraint type for that array. However, by specifying type `object[]`, there really is
+no constraint as a value of any type can be assigned to an element of an array of that type.
-Concatenating two arrays (§7.7.3) always results in a new array that is unconstrained even if both
-arrays are constrained by the same type. For example,
+Concatenating two arrays ([§7.7.3][]) always results in a new array that is unconstrained even if
+both arrays are constrained by the same type. For example,
```powershell $a = [int[]](1,2,3) # constrained to int
$c = $a + $b # constraint not preserved
$c = [int[]]($a + $b) # result explicitly constrained to int ```
-## Arrays as reference types
+## 9.5 Arrays as reference types
As array types are reference types, a variable designating an array can be made to refer to any array of any rank, length, and element type. For example,
The following is written to the pipeline:
>6 20 30 40< ``` -
-## Arrays as array elements
+## 9.6 Arrays as array elements
Any element of an array can itself be an array. For example,
$a[1,0] = $y # element is an array of 3 objects
$a[1,1] = [int[]](92,93) # element is an array of 2 ints ```
-## Negative subscripting
+## 9.7 Negative subscripting
-This is discussed in §7.1.4.1.
+This is discussed in [§7.1.4.1][].
-## Bounds checking
+## 9.8 Bounds checking
-This is discussed in §7.1.4.1.
+This is discussed in [§7.1.4.1][].
-## Array slices
+## 9.9 Array slices
An *array slice* is an unconstrained 1-dimensional array whose elements are copies of zero or more
-elements from a collection. An array slice is created via the subscript operator `[]` (§7.1.4.5).
+elements from a collection. An array slice is created via the subscript operator `[]`
+([§7.1.4.5][]).
-## Copying an array
+## 9.10 Copying an array
A contiguous set of elements can be copied from one array to another using the method `[Array]::Copy`. For example,
$a[1]->$b[1]
$a[2]->$b[4] ```
-## Enumerating over an array
+## 9.11 Enumerating over an array
Although it is possible to loop through an array accessing each of its elements via the subscript operator, we can enumerate over that array's elements using the foreach statement. For a
foreach ($elem in $a) {
} ```
-## Multidimensional array flattening
+## 9.12 Multidimensional array flattening
-Some operations on a multidimensional array (such as replication (§7.6.3) and concatenation
-(§7.7.3)) require that array to be *flattened*; that is, to be turned into a 1-dimensional array of
-unconstrained type. The resulting array takes on all the elements in row-major order.
+Some operations on a multidimensional array (such as replication ([§7.6.3][]) and concatenation
+([§7.7.3][])) require that array to be *flattened*; that is, to be turned into a 1-dimensional array
+of unconstrained type. The resulting array takes on all the elements in row-major order.
Consider the following example:
$c = $a + $b
``` The array designated by `$c` contains the elements "red", `$true`, 10, 20, 30, and 40.+
+<!-- reference links -->
+[§4.3.2]: chapter-04.md#432-arrays
+[§7.1.4.1]: chapter-07.md#7141-subscripting-an-array
+[§7.1.4.5]: chapter-07.md#7145-generating-array-slices
+[§7.1.4]: chapter-07.md#714-element-access
+[§7.1.7]: chapter-07.md#717--operator
+[§7.2.1]: chapter-07.md#721-unary-comma-operator
+[§7.3]: chapter-07.md#73-binary-comma-operator
+[§7.4]: chapter-07.md#74-range-operator
+[§7.6.3]: chapter-07.md#763-array-replication
+[§7.7.3]: chapter-07.md#773-array-concatenation
+[§9.4]: chapter-09.md#94-constraining-element-types
lang-spec Chapter 10 https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/lang-spec/chapter-10.md
description: A Hashtable represents a collection of key/value pair objects that
Last updated 05/19/2021 Title: Hashtables ---
-# Hashtables
+# 10. Hashtables
Syntax:
statement-terminator:
new-line-character ```
-## Introduction
+## 10.1 Introduction
The type Hashtable represents a collection of *key/value pair* objects that supports efficient retrieval of a value when indexed by the key. Each key/value pair is an *element*, which is stored
Given a key/value pair object, the key and associated value can be obtained by u
properties Key and Value, respectively. Given one or more keys, the corresponding value(s) can be accessed via the Hashtable subscript
-operator `[]` (§7.1.4.3).
+operator `[]` ([§7.1.4.3][]).
-All Hashtables have type `Hashtable` (§4.3.3).
+All Hashtables have type `Hashtable` ([§4.3.3][]).
The order of the keys in the collection returned by Keys is unspecified; however, it is the same order as the associated values in the collection returned by Values.
$h1.Keys # gets the collection of keys
`Hashtable` elements are stored in an object of type **DictionaryEntry**, and the collections returned by Keys and Values have type **ICollection**.
-## Hashtable creation
+## 10.2 Hashtable creation
-A `Hashtable` is created via a hash literal (§7.1.9) or the `New-Object` cmdlet (§13.36). It can be
-created with zero or more elements. The Count property returns the current element count.
+A `Hashtable` is created via a hash literal ([§7.1.9][]) or the
+[New-Object](xref:Microsoft.PowerShell.Utility.New-Object) cmdlet. It can be created with zero or
+more elements. The Count property returns the current element count.
-## Adding and removing Hashtable elements
+## 10.3 Adding and removing Hashtable elements
-An element can be added to a `Hashtable` by assigning (§7.11.1) a value to a non-existent key name or
-to a subscript (§7.1.4.3) that uses a non-existent key name. Removal of an element requires the use
-of the Remove method. For example,
+An element can be added to a `Hashtable` by assigning ([§7.11.1][]) a value to a non-existent key
+name or to a subscript ([§7.1.4.3][]) that uses a non-existent key name. Removal of an element
+requires the use of the Remove method. For example,
```powershell $h1 = @{ FirstName = "James"; LastName = "Anderson"; IDNum = 123 }
$h1["Salaried"] = $false # adds element Salaried
$h1.Remove("Salaried") # removes element Salaried ```
-## Hashtable concatenation
+## 10.4 Hashtable concatenation
Hashtables can be concatenated via the `+` and `+=` operators, both of which result in the creation
-of a new `Hashtable`. The existing Hashtables are unchanged. See §7.7.4 for more information.
+of a new `Hashtable`. The existing Hashtables are unchanged. See [§7.7.4][] for more information.
-## Hashtables as reference types
+## 10.5 Hashtables as reference types
As `Hashtable` is a reference type, assignment of a `Hashtable` involves a shallow copy; that is, the variable assigned to refers to the same `Hashtable`; no copy of the `Hashtable` is made. For
$h1.FirstName = "John" # change key's value in $h1
$h2.FirstName # change is reflected in $h2 ```
-## Enumerating over a Hashtable
+## 10.6 Enumerating over a Hashtable
To process every pair in a `Hashtable`, use the **Keys** property to retrieve the list of keys as an array, and then enumerate over the elements of that array getting the associated value via the
foreach ($e in $h1.Keys) {
"Key is " + $e + ", Value is " + $h1[$e] } ```+
+<!-- reference links -->
+[§4.3.3]: chapter-04.md#433-hashtables
+[§7.1.4.3]: chapter-07.md#7143-subscripting-a-hashtable
+[§7.1.9]: chapter-07.md#719-hash-literal-expression
+[§7.11.1]: chapter-07.md#7111-simple-assignment
+[§7.7.4]: chapter-07.md#774-hashtable-concatenation
lang-spec Chapter 11 https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/lang-spec/chapter-11.md
description: A module is a self-contained reusable unit of PowerShell code. A mo
Last updated 05/19/2021 Title: Modules ---
-# Modules
+# 11. Modules
-## Introduction
+## 11.1 Introduction
-As stated in §3.14, a module is a self-contained reusable unit that allows PowerShell code to be
+As stated in [§3.14][], a module is a self-contained reusable unit that allows PowerShell code to be
partitioned, organized, and abstracted. A module can contain one or more *module members*, which are commands (such as cmdlets and functions) and items (such as variables and aliases). The names of these members can be kept private to the module or they may be *exported* to the session into which
variable **PSModulePath**.
The following cmdlets deal with modules: -- `Get-Module`: Identifies the modules that have been, or that can be, imported (see §13.23)-- `Import-Modul`e: Adds one or more modules to the current session (see §11.4, §13.28)-- `Export-ModuleMember`: Identifies the module members that are to be exported (see §13.11)-- `Remove-Module`: Removes one or more modules from the current session (see §11.5, §13.41)-- `New-Module`: Creates a dynamic module (see §11.7, §13.35)
+- [Get-Module](xref:Microsoft.PowerShell.Core.Get-Module): Identifies the modules that have been, or that can be, imported
+- [Import-Module](xref:Microsoft.PowerShell.Core.Import-Module): Adds one or more modules to the current session (see [§11.4][])
+- [Export-ModuleMember](xref:Microsoft.PowerShell.Core.Export-ModuleMember): Identifies the module members that are to be exported
+- [Remove-Module](xref:Microsoft.PowerShell.Core.Remove-Module): Removes one or more modules from the current session (see [§11.5][])
+- [New-Module](xref:Microsoft.PowerShell.Core.New-Module): Creates a dynamic module (see [§11.7][])
-## Writing a script module
+## 11.2 Writing a script module
A script module is a script file. Consider the following script module:
export anything, then only those things exported explicitly will be exported. A
and items can be exported in one call or a number of calls to this cmdlet; such calls are cumulative for the current session.
-## Installing a script module
+## 11.3 Installing a script module
A script module is defined in a script file, and modules can be stored in any directory. The environment variable PSModulePath points to a set of directories to be searched when module-related
can be provided; for example,
Any additional paths added affect the current session only.
-Alternatively, a fully qualified path can be specified when a module is imported (§13.28).
+Alternatively, a fully qualified path can be specified when a module is imported.
-## Importing a script module
+## 11.4 Importing a script module
Before the resources in a module can be used, that module must be imported into the current session,
-using the cmdlet `Import-Module` (§13.28). `Import-Module` can restrict the resources that it
-actually imports.
+using the cmdlet `Import-Module`. `Import-Module` can restrict the resources that it actually
+imports.
When a module is imported, its script file is executed. That process can be configured by defining one or more parameters in the script file, and passing in corresponding arguments via the ArgumentList parameter of `Import-Module`.
-Consider the following script that uses these functions and aliases defined in §11.2:
+Consider the following script that uses these functions and aliases defined in [§11.2][]:
`Import-Module` "E:\Scripts\Modules\PSTest\_Temperature" -Verbose
the argument 100.
When the session includes commands of the same kind with the same name, such as two cmdlets with the same name, by default it runs the most recently added command.
-See §3.5.6 for a discussion of scope as it relates to modules.
+See [§3.5.6][] for a discussion of scope as it relates to modules.
-## Removing a script module
+## 11.5 Removing a script module
-One or more modules can be removed from a session via the cmdlet `Remove-Module` (§13.41).
+One or more modules can be removed from a session via the cmdlet `Remove-Module`.
Removing a module does not uninstall the module.
removal, as follows:
`$MyInvocation.MyCommand.ScriptBlock.Module.OnRemove = { *on-removal-code* }`
-## Module manifests
+## 11.6 Module manifests
-As stated in §11.1, a manifest module is a file that contains information about a module, and
+As stated in [§11.1][], a manifest module is a file that contains information about a module, and
controls certain aspects of that module's use. A module need not have a corresponding manifest, but if it does, that manifest has the same name as
The key **GUID** has a `string` value. This specifies a Globally Unique IDentifi
module. The **GUID** can be used to distinguish among modules having the same name. To create a new GUID, call the method `[guid]::NewGuid()`.
-## Dynamic modules
+## 11.7 Dynamic modules
-A *dynamic module* is a module that is created in memory at runtime by the cmdlet `New-Module`
-(§13.35); it is not loaded from disk. Consider the following example:
+A *dynamic module* is a module that is created in memory at runtime by the cmdlet `New-Module`; it
+is not loaded from disk. Consider the following example:
```powershell $sb = {
or pipe the module object that `New-Module` returns, to `Import-Module`. This ac
dynamic module to the `Get-Module` list, but it does not save the module to disk or make it persistent.
-## Closures
+## 11.8 Closures
A dynamic module can be used to create a *closure*, a function with attached data. Consider the following example:
$v2 = Get-NextID 100 # get a scriptblock with $startValue of 100
The intent here is that `Get-NextID` return the next ID in a sequence whose start value can be specified. However, multiple sequences must be supported, each with its own `$startValue` and `$nextID` context. This is achieved by the call to the method `[scriptblock]::GetNewClosure`
-(§4.3.7).
+([§4.3.7][]).
Each time a new closure is created by `GetNewClosure`, a new dynamic module is created, and the variables in the caller's scope (in this case, the script block containing the increment) are copied
$v3 = & { # get a scriptblock with $startValue of 200
& $v3 # invoke script getting back 200 & $v3 # invoke script getting back 201 ```+
+<!-- reference links -->
+[§11.1]: chapter-11.md#111-introduction
+[§11.2]: chapter-11.md#112-writing-a-script-module
+[§11.4]: chapter-11.md#114-importing-a-script-module
+[§11.5]: chapter-11.md#115-removing-a-script-module
+[§11.7]: chapter-11.md#117-dynamic-modules
+[§3.14]: chapter-03.md#314-modules
+[§3.5.6]: chapter-03.md#356-modules
+[§4.3.7]: chapter-04.md#437-the-scriptblock-type
lang-spec Chapter 12 https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/lang-spec/chapter-12.md
description: An attribute object associates predefined system information with a
Last updated 05/19/2021 Title: Attributes ---
-# Attributes
+# 12. Attributes
An *attribute* object associates predefined system information with a *target element*, which can be
-a param block or a parameter (§8.10). Each attribute object has an *attribute type*.
+a param block or a parameter ([§8.10][]). Each attribute object has an *attribute type*.
Information provided by an attribute is also known as *metadata*. Metadata can be examined by the command or the execution environment to control how the command processes data or before run time by
external tools to control how the command itself is processed or maintained.
Multiple attributes can be applied to the same target element.
-## Attribute specification
+## 12.1 Attribute specification
> [!TIP] > The `~opt~` notation in the syntax definitions indicates that the lexical entity is optional in
The positional arguments (if any) precede the named arguments. A named argument
*simple-name*, optionally followed by an equal sign and followed by an *expression*. If the expression is omitted, the value `$true` is assumed.
-The *attribute-name* is a reserved attribute type (§12.3) or some implementation-defined attribute
-type.
+The *attribute-name* is a reserved attribute type ([§12.3][]) or some implementation-defined
+attribute type.
-## Attribute instances
+## 12.2 Attribute instances
An attribute instance is an object of an attribute type. The instance represents an attribute at run-time. To create an object of some attribute type *A*, use the notation `A()`. An attribute is declared by enclosing its instance inside `[]`, as in `[A()]`. Some attribute types have positional and named
-parameters (§8.14), just like functions and cmdlets. For example,
+parameters ([§8.14][]), just like functions and cmdlets. For example,
`[A(10,IgnoreCase=$true)]` shows an instance of type *A* being created using a positional parameter whose argument value is 10, and a named parameter, **IgnoreCase**, whose argument value is `$true`.
-## Reserved attributes
+## 12.3 Reserved attributes
The attributes described in the following sections can be used to augment or modify the behavior of PowerShell functions, filters, scripts, and cmdlets.
-### The Alias attribute
+### 12.3.1 The Alias attribute
This attribute is used in a *script-parameter* to specify an alternate name for a parameter. A parameter may have multiple aliases, and each alias name must be unique within a *parameter-list*.
Get-ChildItem "E:\*.txt" | Test2
Cmdlet `Get-ChildItem` (alias `Dir`) adds to the object it returns a new **NoteProperty** of type `string`, called **PSPath**.
-### The AllowEmptyCollection attribute
+### 12.3.2 The AllowEmptyCollection attribute
This attribute is used in a *script-parameter* to allow an empty collection as the argument of a mandatory parameter.
Test "Red" # $computerName has Length 1
Test -comp @() # $computerName has Length 0 ```
-### The AllowEmptyString attribute
+### 12.3.3 The AllowEmptyString attribute
This attribute is used in a *script-parameter* to allow an empty string as the argument of a mandatory parameter.
Test "" # empty string is permitted
Test -comp "" # empty string is permitted ```
-### The AllowNull attribute
+### 12.3.4 The AllowNull attribute
This attribute is used in a *script-parameter* to allow $null as the argument of a mandatory parameter for which no implicit conversion is available.
Test -val $null # $values has value $null
Note that the second case above does not need this attribute; there is already an implicit conversion from `$null` to int.
-### The CmdletBinding attribute
+### 12.3.5 The CmdletBinding attribute
This attribute is used in the *attribute-list* of *param-block* of a function to indicate that function acts similar to a cmdlet. Specifically, it allows functions to access a number of methods and properties through the $PsCmdlet variable by using begin, process, and end named blocks
-(§8.10.7).
+([§8.10.7][]).
When this attribute is present, positional arguments that have no matching positional parameters cause parameter binding to fail and $args is not defined. (Without this attribute $args would take
The following arguments are used to define the characteristics of the parameter:
<tr class="odd"> <td>DefaultParameterSetName (named)</td> <td><p>Type: string; Default value: "__AllParameterSets"</p>
-<p>Specifies the parameter set to use if that cannot be determined from the arguments. See the named argument ParameterSetName in the attribute Parameter (§12.3.7).</p></td>
+<p>Specifies the parameter set to use if that cannot be determined from the arguments. See the named argument ParameterSetName in the attribute Parameter ([§12.3.7][]).</p></td>
</tr> <tr class="even"> <td>PositionalBinding (named)</td> <td><p>Type: bool; Default value: $true</p>
-<p>Specifies whether positional binding is supported or not. The value of this argument is ignored if any parameters specify non-default values for either the named argument Position or the named argument ParameterSetName in the attribute Parameter (§12.3.7). Otherwise, if the argument is $false then no parameters are positional, otherwise parameters are assigned a position based on the order the parameters are specified.</p></td>
+<p>Specifies whether positional binding is supported or not. The value of this argument is ignored if any parameters specify non-default values for either the named argument Position or the named argument ParameterSetName in the attribute Parameter ([§12.3.7][]). Otherwise, if the argument is $false then no parameters are positional, otherwise parameters are assigned a position based on the order the parameters are specified.</p></td>
</tr> </tbody> </table>
Get-process { ... }
end { ... } ```
-### The OutputType attribute
+### 12.3.6 The OutputType attribute
This attribute is used in the *attribute-list* of *param-block* to specify the types returned. The following arguments are used to define the characteristics of the parameter:
Here are several examples of this attribute's use:
```
-### The Parameter attribute
+### 12.3.7 The Parameter attribute
This attribute is used in a *script-parameter*. The following named arguments are used to define the characteristics of the parameter:
HelpMessage = "An array of computer names.")]<br />
<p>For parameters that belong to multiple parameter sets, add a Parameter attribute for each parameter set. This allows the parameter to be defined differently for each parameter set.</p> <p>A parameter set that contains multiple positional parameters must define unique positions for each parameter. No two positional parameters can specify the same position.</p> <p>If no parameter set is specified for a parameter, the parameter belongs to all parameter sets.</p>
-<p>When multiple parameter sets are defined, the named argument DefaultParameterSetName of the attribute CmdletBinding (§12.3.5) is used to specify the default parameter set. The runtime uses the default parameter set if it cannot determine the parameter set to use based on the information provided by the command, or raises an exception if no default parameter set has been specified.</p>
+<p>When multiple parameter sets are defined, the named argument DefaultParameterSetName of the attribute CmdletBinding ([§12.3.5][]) is used to specify the default parameter set. The runtime uses the default parameter set if it cannot determine the parameter set to use based on the information provided by the command, or raises an exception if no default parameter set has been specified.</p>
<p>The following example shows a function Test with a parameter declaration of two parameters that belong to two different parameter sets, and a third parameter that belongs to both sets:</p> <p>param ( [Parameter(Mandatory = $true,<br /> ParameterSetName = "Computer")]<br />
Test -UserName "Mary","Jack" -SharedParam 20</p></td>
<p>param ( [Parameter(Mandatory = $true,<br /> ValueFromPipeline=$true)]<br /> [string[]] $ComputerName )</p>
-<p>For an example of using this parameter in conjunction with the Alias attribute see §12.3.1.</p></td>
+<p>For an example of using this parameter in conjunction with the Alias attribute see [§12.3.1][]. </p></td>
</tr> <tr class="even"> <td>ValueFromPipelineByPropertyName (named)</td>
The following attributes are provided as well:
localized. - **HelpMessageResourceId**: Specifies the resource identifier for a Help message.
-### The PSDefaultValue attribute
+### 12.3.8 The PSDefaultValue attribute
This attribute is used in a *script-parameter* to provide additional information about the parameter. The attribute is used in an implementation defined manner. The following arguments are
used to define the characteristics of the parameter:
<td>Help (named)</td> <td><p>Type: string</p> <p>This argument specifies a message that is intended to contain a short description of the default value of a parameter. This message is used in an implementation-defined manner.</p>
-<p>Windows PowerShell: The message is used as part of the description of the parameter for the help topic displayed by the Get-Help (§13.19) cmdlet.</p></td>
+<p>Windows PowerShell: The message is used as part of the description of the parameter for the help topic displayed by the [Get-Help](xref:Microsoft.PowerShell.Core.Get-Help) cmdlet.</p></td>
</tr> <tr class="even"> <td>Value (named)</td> <td><p>Type: object</p> <p>This argument specifies a value that is intended to be the default value of a parameter. The value is used in an implementation-defined manner.</p>
-<p>Windows PowerShell: The value is used as part of the description of the parameter for the help topic displayed by the Get-Help (§13.19) cmdlet when the Help property is not specified.</p></td>
+<p>Windows PowerShell: The value is used as part of the description of the parameter for the help topic displayed by the [Get-Help](xref:Microsoft.PowerShell.Core.Get-Help)cmdlet when the Help property is not specified.</p></td>
</tr> </tbody> </table>
-### The SupportsWildcards attribute
+### 12.3.9 The SupportsWildcards attribute
This attribute is used in a *script-parameter* to provide additional information about the parameter. The attribute is used in an implementation defined manner. This attribute is used as part of the description of the parameter for the help topic displayed by
-the `Get-Help` (§13.19) cmdlet.
+the [Get-Help](xref:Microsoft.PowerShell.Core.Get-Help) cmdlet.
-### The ValidateCount attribute
+### 12.3.10 The ValidateCount attribute
This attribute is used in a *script-parameter* to specify the minimum and maximum number of argument values that the parameter can accept. The following arguments are used to define the characteristics
$Array = 10 # too few argument values
$Array = 1..100 # too many argument values ```
-### The ValidateLength attribute
+### 12.3.11 The ValidateLength attribute
This attribute is used in a *script-parameter* or *variable* to specify the minimum and maximum length of the parameter's argument, which must have type string. The following arguments are used to
Test "Io","Mars" # "Io" is too short
Test "Thor","Jupiter" # "Jupiter" is too long ```
-### The ValidateNotNull attribute
+### 12.3.12 The ValidateNotNull attribute
This attribute is used in a *script-parameter* or *variable* to specify that the argument of the parameter cannot be `$null` or be a collection containing a null-valued element.
Test $null # null array not allowed
$Name = $null # null value not allowed ```
-### The ValidateNotNullOrEmpty attribute
+### 12.3.13 The ValidateNotNullOrEmpty attribute
This attribute is used in a *script-parameter* or *variable* to specify that the argument if the parameter cannot be $null, an empty string, or an empty array, or be a collection containing a
$Name = "" # empty string not allowed
$Name = $null # null value not allowed ```
-### The ValidatePattern attribute
+### 12.3.14 The ValidatePattern attribute
This attribute is used in a *script-parameter* or *variable* to specify a regular expression for matching the pattern of the parameter's argument. The following arguments are used to define the
characteristics of the parameter:
<tr class="even"> <td>Options (named)</td> <td><p>Type: Regular-Expression-Option</p>
-<p>See §4.2.6.4 for the allowed values.</p></td>
+<p>See [§4.2.6.4][] for the allowed values.</p></td>
</tr> </tbody> </table>
Test -m -12 # matches pattern, but is too long
$ident = "123" # does not match pattern ```
-### The ValidateRange attribute
+### 12.3.15 The ValidateRange attribute
This attribute is used in a *script-parameter* or *variable* to specify the minimum and maximum values of the parameter's argument. The following arguments are used to define the characteristics
Test3 "0.005" # value is too large
$teenager = 20 # value is too large ```
-### The ValidateScript attribute
+### 12.3.16 The ValidateScript attribute
This attribute is used in a *script-parameter* or *variable* to specify a script that is to be used to validate the parameter's argument.
Test 0 # invalid value
$password = "abc123" # invalid value ```
-### The ValidateSet attribute
+### 12.3.17 The ValidateSet attribute
This attribute is used in a *script-parameter* or *variable* to specify a set of valid values for the argument of the parameter. The following arguments are used to define the characteristics of the
Test -dir "Up" # case is not ignored, is not a member of the set
[ValidateSet(("Red", "Green", "Blue")]$color = "RED" # ok, case is ignored $color = "Purple" # case is ignored, is not a member of the set ```+
+<!-- reference links -->
+[§12.3.1]: chapter-12.md#1231-the-alias-attribute
+[§12.3.5]: chapter-12.md#1235-the-cmdletbinding-attribute
+[§12.3.7]: chapter-12.md#1237-the-parameter-attribute
+[§12.3]: chapter-12.md#123-reserved-attributes
+[§4.2.6.4]: chapter-04.md#4264-regularexpressionoption-type
+[§8.10.7]: chapter-08.md#8107-named-blocks
+[§8.10]: chapter-08.md#810-function-definitions
+[§8.14]: chapter-08.md#814-parameter-binding
lang-spec Chapter 13 https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/lang-spec/chapter-13.md
description: A cmdlet is a single-feature command that manipulates objects in Po
Last updated 05/19/2021 Title: Cmdlets ---
-# Cmdlets
+# 13. Cmdlets
A cmdlet is a single-feature command that manipulates objects in PowerShell. Cmdlets can be recognized by their name format, a verb and noun separated by a dash (`-`), such as `Get-Help`,
case-sensitive.
> information about cmdlet, consult the **Reference** section of the > [PowerShell documentation](/powershell/scripting/overview).
-## Common parameters
+## 13.1 Common parameters
The *common parameters* are a set of cmdlet parameters that can be used with any cmdlet. They are implemented by the PowerShell runtime environment itself, not by the cmdlet developer, and they are
-automatically available to any cmdlet or function that uses the **Parameter** attribute (§12.3.7) or
-**CmdletBinding** attribute (§12.3.5).
+automatically available to any cmdlet or function that uses the **Parameter** attribute
+([§12.3.7][]) or **CmdletBinding** attribute ([§12.3.5][]).
Although the common parameters are accepted by any cmdlet, they might not have any semantics for that cmdlet. For example, if a cmdlet does not generate any verbose output, using the **Verbose** common parameter has no effect. Several common parameters override system defaults or preferences that can be set via preference
-variables (§2.3.2.3). Unlike the preference variables, the common parameters affect only the
+variables ([§2.3.2.3][]). Unlike the preference variables, the common parameters affect only the
commands in which they are used. > [!NOTE] > Editor's note: The original document contains a list of the Common Parameters. This information is > incomplete and out dated. For current information see > [about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters).+
+<!-- reference links -->
+[§12.3.5]: chapter-12.md#1235-the-cmdletbinding-attribute
+[§12.3.7]: chapter-12.md#1237-the-parameter-attribute
+[§2.3.2.3]: chapter-02.md#2323-preference-variables
lang-spec Chapter 14 https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/lang-spec/chapter-14.md
Last updated 05/19/2021
Title: Comment-Based Help ---
-# Comment-Based Help
+# A. Comment-Based Help
PowerShell provides a mechanism for programmers to document their scripts using special comment
-directives. Comments using such syntax are called *help comments*. The cmdlet `Get-Help` (§13.19)
-generates documentation from these directives.
+directives. Comments using such syntax are called *help comments*. The cmdlet
+[Get-Help](xref:Microsoft.PowerShell.Core.Get-Help) generates documentation from these directives.
-## Introduction
+## A.1 Introduction
A help comment contains a *help directive* of the form .*name* followed on one or more subsequent lines by the help content text. The help comment can be made up of a series of
-*single-line-comment*s or a *delimited-comment* (§2.2.3). The set of comments comprising the
+*single-line-comment*s or a *delimited-comment* ([§2.2.3][]). The set of comments comprising the
documentation for a single entity is called a *help topic*. For example,
When documenting a script file, help topics may appear in one of two locations:
be interpreted as applying to the function instead of the script file. - At the end of the script file.
-## Help directives
+## A.2 Help directives
-### .DESCRIPTION
+### A.2.1 .DESCRIPTION
Syntax:
Syntax:
Description: This directive allows for a detailed description of the function or script. (The `.SYNOPSIS`
-directive (§A.2.11) is intended for a brief description.) This directive can be used only once in
-each topic.
+directive ([§A.2.11][]) is intended for a brief description.) This directive can be used only once
+in each topic.
Examples:
powers only.
#> ```
-### .EXAMPLE
+### A.2.2 .EXAMPLE
Syntax:
Get-Power -Base 3 -Exponent 4
#> ```
-### .EXTERNALHELP
+### A.2.3 .EXTERNALHELP
Syntax:
Examples:
#> ```
-### .FORWARDHELPCATEGORY
+### A.2.4 .FORWARDHELPCATEGORY
Syntax:
Syntax:
Description:
-Specifies the help category of the item in **ForwardHelpTargetName** (§A.2.5). Valid values are
+Specifies the help category of the item in **ForwardHelpTargetName** ([§A.2.5][]). Valid values are
**Alias**, **All**, **Cmdlet**, **ExternalScript**, **FAQ**, **Filter**, **Function**, **General**, **Glossary**, **HelpFile**, **Provider**, and **ScriptCommand**. Use this directive to avoid conflicts when there are commands with the same name. Examples:
-See §A.2.5.
+See [§A.2.5][].
-### .FORWARDHELPTARGETNAME
+### A.2.5 .FORWARDHELPTARGETNAME
Syntax:
function Help {
The command `Get-Help help` is treated as if it were `Get-Help Get-Help` instead.
-### .INPUTS
+### A.2.6 .INPUTS
Syntax:
function Process-Thing {
} ```
-### .LINK
+### A.2.7 .LINK
Syntax:
Set-ProcedureName
#> ``` -
-### .NOTES
+### A.2.8 .NOTES
Syntax:
Examples:
#> ```
-### .OUTPUTS
+### A.2.9 .OUTPUTS
Syntax:
None unless the -PassThru switch parameter is used.
#> ```
-### .PARAMETER
+### A.2.10 .PARAMETER
Syntax:
function Get-Power {
} ```
-### .SYNOPSIS
+### A.2.11 .SYNOPSIS
Syntax:
Syntax:
Description: This directive allows for a brief description of the function or script. (The `.DESCRIPTION`
-directive (§A.2.1) is intended for a detailed description.) This directive can be used only once in
-each topic.
+directive ([§A.2.1][]) is intended for a detailed description.) This directive can be used only once
+in each topic.
Examples:
Examples:
Computes Base to the power Exponent. #> ```+
+<!-- reference links -->
+[§2.2.3]: chapter-02.md#223-comments
+[§A.2.1]: chapter-14.md#a21-description
+[§A.2.11]: chapter-14.md#a211-synopsis
+[§A.2.5]: chapter-14.md#a25-forwardhelptargetname
lang-spec Chapter 15 https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/lang-spec/chapter-15.md
description: This appendix contains summaries of the lexical and syntactic gramm
Last updated 05/19/2021 Title: Appendix A - Grammar ---
-# Grammar
+# B. Grammar
This appendix contains summaries of the lexical and syntactic grammars found in the main document.
This appendix contains summaries of the lexical and syntactic grammars found in
> The `~opt~` notation in the syntax definitions indicates that the lexical entity is optional in > the syntax.
-## Lexical grammar
+## B.1 Lexical grammar
+```Syntax
input:
-input-elements~opt~ signature-block~opt~
+ input-elements~opt~ signature-block~opt~
input-elements:
-input-element
-input-elements input-element
+ input-element
+ input-elements input-element
input-element:
-whitespace
-comment
-token
+ whitespace
+ comment
+ token
signature-block:
-signature-begin signature signature-end
+ signature-begin signature signature-end
signature-begin:
-new-line-character *\# SIG \# Begin signature block* new-line-character
+ new-line-character # SIG # Begin signature block new-line-character
signature:
-*base64 encoded signature blob in multiple* single-line-comments
+ base64 encoded signature blob in multiple single-line-comments
signature-end:
-new-line-character *\# SIG \# End signature block* new-line-character
+ new-line-character # SIG # End signature block new-line-character
+```
-### Line terminators
+### B.1.1 Line terminators
+```Syntax
new-line-character:
-*Carriage return character (U+000D)*
-*Line feed character (U+000A)*
-*Carriage return character (U+000D) followed by line feed character
-(U+000A)*
+ Carriage return character (U+000D)
+ Line feed character (U+000A)
+ Carriage return character (U+000D) followed by line feed character (U+000A)
new-lines:
-new-line-character
-new-lines new-line-character
+ new-line-character
+ new-lines new-line-character
+```
-### Comments
+### B.1.2 Comments
+```Syntax
comment:
-single-line-comment
-requires-comment
-delimited-comment
+ single-line-comment
+ requires-comment
+ delimited-comment
single-line-comment:
-*\#* input-characters~opt~
+ # input-characters~opt~
input-characters:
-input-character
-input-characters input-character
+ input-character
+ input-characters input-character
input-character:
-*Any Unicode character except a* new-line-character
+ Any Unicode character except a new-line-character
requires-comment:
-*\#requires* whitespace command-arguments
+ #requires whitespace command-arguments
-dash:*
-- (U+002D)
-EnDash character (U+2013)
-EmDash character (U+2014)
-Horizontal bar character (U+2015)*
+dash:
+ - (U+002D)
+ EnDash character (U+2013)
+ EmDash character (U+2014)
+ Horizontal bar character (U+2015)
dashdash:
-dash dash
+ dash dash
delimited-comment:
-*&lt;\#* delimited-comment-text~opt~ hashes *&gt;*
+ <# delimited-comment-text~opt~ hashes >
delimited-comment-text:
-delimited-comment-section
-delimited-comment-text delimited-comment-section
+ delimited-comment-section
+ delimited-comment-text delimited-comment-section
delimited-comment-section:
-*&gt;*
-hashes~opt~ not-greater-than-or-hash
+ >
+ hashes~opt~ not-greater-than-or-hash
hashes:
-*\#*
-hashes *\#*
+ #
+ hashes #
not-greater-than-or-hash:
-*Any Unicode character except &gt; or \#*
+ Any Unicode character except > or #
+```
-### White space
+### B.1.3 White space
+```Syntax
whitespace:
-*Any character with Unicode class Zs, Zl, or Zp*
-*Horizontal tab character (U+0009)*
-*Vertical tab character (U+000B)*
-*Form feed character (U+000C)
-\` (The backtick character U+0060) followed by* new-line-character
+ Any character with Unicode class Zs, Zl, or Zp
+ Horizontal tab character (U+0009)
+ Vertical tab character (U+000B)
+ Form feed character (U+000C)
+ ` (The backtick character U+0060) followed by new-line-character
+```
-### Tokens
+### B.1.4 Tokens
+```Syntax
token:
-keyword
-variable
-command
-command-parameter
-command-argument-token
-integer-literal
-real-literal
-string-literal
-type-literal
-operator-or-punctuator
-
-### Keywords
-
-keyword: *one of*
-*begin break catch class
-continue data define do
-dynamicparam else elseif end
-exit filter finally for
-foreach from function if
-in inlinescript parallel param
-process return switch throw
-trap try until using
-var while workflow*
-
-### Variables
-
+ keyword
+ variable
+ command
+ command-parameter
+ command-argument-token
+ integer-literal
+ real-literal
+ string-literal
+ type-literal
+ operator-or-punctuator
+```
+
+### B.1.5 Keywords
+
+```Syntax
+keyword: one of
+ begin break catch class
+ continue data define do
+ dynamicparam else elseif end
+ exit filter finally for
+ foreach from function if
+ in inlinescript parallel param
+ process return switch throw
+ trap try until using
+ var while workflow
+```
+
+### B.1.6 Variables
+
+```Syntax
variable:
-*\$\$
-\$?
-\$\^*
-*\$* variable-scope~opt~ variable-characters*
-@* variable-scope~opt~ variable-characters*
-braced-variable*
+ $$
+ $?
+ $^
+ $ variable-scope~opt~ variable-characters
+ @ variable-scope~opt~ variable-characters
+ braced-variable
+
-*braced-variable:
-\${* variable-scope~opt~ braced-variable-characters *}*
+braced-variable:
+ ${ variable-scope~opt~ braced-variable-characters }
variable-scope:
-*global:
-local:
-private:
-script:
-using:
-workflow:
-*variable-namespace
+ global:
+ local:
+ private:
+ script:
+ using:
+ workflow:
+ variable-namespace
variable-namespace:
-variable-characters *:*
+ variable-characters :
variable-characters:
-variable-character
-variable-characters variable-character
+ variable-character
+ variable-characters variable-character
variable-character:
-*A Unicode character of classes Lu, Ll, Lt, Lm, Lo, or Nd
-\_ (The underscore character U+005F)
-?*
+ A Unicode character of classes Lu, Ll, Lt, Lm, Lo, or Nd
+ _ (The underscore character U+005F)
+ ?
braced-variable-characters:
-braced-variable-character
-braced-variable-characters braced-variable-character
+ braced-variable-character
+ braced-variable-characters braced-variable-character
braced-variable-character:
-*Any Unicode character except
-} (The closing curly brace character U+007D)
-\` (The backtick character U+0060)
-*escaped-character
+ Any Unicode character except
+ } (The closing curly brace character U+007D)
+ ` (The backtick character U+0060)
+ escaped-character
escaped-character:
-*\` (The backtick character U+0060) followed by any Unicode character*
+ ` (The backtick character U+0060) followed by any Unicode character
+```
-### Commands
+### B.1.7 Commands
+```Syntax
generic-token:
-generic-token-parts
+ generic-token-parts
generic-token-parts:
-generic-token-part
-generic-token-parts generic-token-part
+ generic-token-part
+ generic-token-parts generic-token-part
generic-token-part:
-expandable-string-literal
-verbatim-here-string-literal
-variable
-generic-token-char
+ expandable-string-literal
+ verbatim-here-string-literal
+ variable
+ generic-token-char
generic-token-char:
-*Any Unicode character except
-{ } ( ) ; , \| & \$
-\` (The backtick character U+0060)
-* double-quote-character
-single-quote-character
-whitespace
-new-line-character
-escaped-character
+ Any Unicode character except
+ { } ( ) ; , | & $
+ ` (The backtick character U+0060)
+ double-quote-character
+ single-quote-character
+ whitespace
+ new-line-character
+ escaped-character
generic-token-with-subexpr-start:
-generic-token-parts *\$(*
+ generic-token-parts $(
+```
+
+### B.1.8 Parameters
+```Syntax
command-parameter:
-dash first-parameter-char parameter-chars colon~opt~
+ dash first-parameter-char parameter-chars colon~opt~
first-parameter-char:
-*A Unicode character of classes Lu, Ll, Lt, Lm, or Lo
-\_* *(The underscore character U+005F)
-?*
+ A Unicode character of classes Lu, Ll, Lt, Lm, or Lo
+ _ (The underscore character U+005F)
+ ?
parameter-chars:
-parameter-char
-parameter-chars parameter-char
+ parameter-char
+ parameter-chars parameter-char
parameter-char:
-*Any Unicode character except
-{ } ( ) ; , \| & . \[
-*colon*
-*whitespace
-new-line-character
+ Any Unicode character except
+ { } ( ) ; , | & . [
+ colon
+ whitespace
+ new-line-character
colon:
-*:* *(The colon character U+003A)*
+ : (The colon character U+003A)
verbatim-command-argument-chars:
-verbatim-command-argument-part
-verbatim-command-argument-chars verbatim-command-argument-part
+ verbatim-command-argument-part
+ verbatim-command-argument-chars verbatim-command-argument-part
verbatim-command-argument-part:
-verbatim-command-string
-& non-ampersand-character
-*Any Unicode character except
-\|
-*new-line-character
+ verbatim-command-string
+ & non-ampersand-character
+ Any Unicode character except
+ |
+ new-line-character
non-ampersand-character:
-*Any Unicode character except
-* &
+ Any Unicode character except &
verbatim-command-string:
-double-quote-character non-double-quote-chars double-quote-character
+ double-quote-character non-double-quote-chars
+ double-quote-character
non-double-quote-chars:
-non-double-quote-char
-non-double-quote-chars non-double-quote-chars
+ non-double-quote-char
+ non-double-quote-chars non-double-quote-char
non-double-quote-char:
-*Any Unicode character except
-* double-quote-character
+ Any Unicode character except
+ double-quote-character
+```
-### Literals
+### B.1.9 Literals
+```Syntax
literal:
-integer-literal
-real-literal
-string-literal
+ integer-literal
+ real-literal
+ string-literal
+```
-#### Integer Literals
+#### B.1.9.1 Integer Literals
+```Syntax
integer-literal:
-decimal-integer-literal
-hexadecimal-integer-literal
+ decimal-integer-literal
+ hexadecimal-integer-literal
decimal-integer-literal:
-decimal-digits numeric-type-suffix~opt~ numeric-multiplier~opt~
+ decimal-digits numeric-type-suffix~opt~ numeric-multiplier~opt~
decimal-digits:
-decimal-digit
-decimal-digit decimal-digits
+ decimal-digit
+ decimal-digit decimal-digits
-decimal-digit: *one of
-0 1 2 3 4 5 6 7 8 9*
+decimal-digit: one of
+ 0 1 2 3 4 5 6 7 8 9
numeric-type-suffix:
-long-type-suffix
-decimal-type-suffix
+ long-type-suffix
+ decimal-type-suffix
hexadecimal-integer-literal:
-*0x* hexadecimal-digits long-type-suffix~opt~ numeric-multiplier~opt~
+ 0x hexadecimal-digits long-type-suffix~opt~
+ numeric-multiplier~opt~
hexadecimal-digits:
-hexadecimal-digit
-hexadecimal-digit decimal-digits
+ hexadecimal-digit
+ hexadecimal-digit decimal-digits
-hexadecimal-digit: *one of
-0 1 2 3 4 5 6 7 8 9 a b c d e f*
+hexadecimal-digit: one of
+ 0 1 2 3 4 5 6 7 8 9 a b c d e f
long-type-suffix:
-*l*
+ l
-numeric-multiplier: *one of*
-*kb mb gb tb pb*
+numeric-multiplier: one of
+ kb mb gb tb pb
+```
-#### Real Literals
+#### B.1.9.2 Real Literals
+```Syntax
real-literal:
-decimal-digits *.* decimal-digits exponent-part~opt~
-decimal-type-suffix~opt~ numeric-multiplier~opt~
-*.* decimal-digits exponent-part~opt~ decimal-type-suffix~opt~
-numeric-multiplier~opt~
-decimal-digits exponent-part decimal-type-suffix~opt~
-numeric-multiplier~opt~
+ decimal-digits . decimal-digits exponent-part~opt~ decimal-type-suffix~opt~ numeric-multiplier~opt~
+ . decimal-digits exponent-part~opt~ decimal-type-suffix~opt~ numeric-multiplier~opt~
+ decimal-digits exponent-part decimal-type-suffix~opt~ numeric-multiplier~opt~
exponent-part:
-*e* sign~opt~ decimal-digits
+ e sign~opt~ decimal-digits
-sign: *one of
-+
-dash*
+sign: one of
+ +
+ dash
decimal-type-suffix:
-*d
-l*
+ d
+ l
+```
-#### String Literals
+#### B.1.9.3 String Literals
+```Syntax
string-literal:
-expandable-string-literal
-expandable-here-string-literal
-verbatim-string-literal
-verbatim-here-string-literal
+ expandable-string-literal
+ expandable-here-string-literal
+ verbatim-string-literal
+ verbatim-here-string-literal
expandable-string-literal:
-double-quote-character expandable-string-characters~opt~ dollars~opt~
-double-quote-character
+ double-quote-character expandable-string-characters~opt~ dollars~opt~ double-quote-character
double-quote-character:
-*\" (U+0022)
-Left double quotation mark (U+201C)
-Right double quotation mark (U+201D)
-Double low-9 quotation mark (U+201E)*
+ " (U+0022)
+ Left double quotation mark (U+201C)
+ Right double quotation mark (U+201D)
+ Double low-9 quotation mark (U+201E)
expandable-string-characters:
-expandable-string-part
-expandable-string-characters expandable-string-part
+ expandable-string-part
+ expandable-string-characters
+ expandable-string-part
expandable-string-part:
-*Any Unicode character except
-\$
-*double-quote-character*
-\` (The backtick character U+0060)*
-braced-variable*
-\$ Any Unicode character except
-(
-{
-*double-quote-character
-*\` (The backtick character U+0060)*
-*\$ escaped-character
-escaped-character
-double-quote-character double-quote-character*
-
-*dollars:
-\$
-dollars \$*
+ Any Unicode character except
+ $
+ double-quote-character
+ ` (The backtick character U+0060)
+ braced-variable
+ $ Any Unicode character except
+ (
+ {
+ double-quote-character
+ ` (The backtick character U+0060)*
+ $ escaped-character
+ escaped-character
+ double-quote-character double-quote-character
+
+dollars:
+ $
+ dollars $
expandable-here-string-literal:
-*@* double-quote-character whitespace~opt~ new-line-character
-expandable-here-string-characters~opt~ new-line-character
-double-quote-character *@*
+ @ double-quote-character whitespace~opt~ new-line-character
+ expandable-here-string-characters~opt~ new-line-character double-quote-character @
expandable-here-string-characters:
-expandable-here-string-part
-expandable-here-string-characters expandable-here-string-part
+ expandable-here-string-part
+ expandable-here-string-characters expandable-here-string-part
expandable-here-string-part:
-*Any Unicode character except
-\$
-*new-line-character*
-*braced-variable*
-\$ Any Unicode character except
-(
-*new-line-character
-*\$* new-line-character *Any Unicode character except*
-double-quote-char
-*\$* new-line-character double-quote-char *Any Unicode character except
-@
-*new-line-character *Any Unicode character except* double-quote-char
-new-line-character double-quote-char *Any Unicode character except @*
+ Any Unicode character except
+ $
+ new-line-character
+ braced-variable
+ $ Any Unicode character except
+ (
+ new-line-character
+ $ new-line-character Any Unicode character except double-quote-char
+ $ new-line-character double-quote-char Any Unicode character except @
+ new-line-character Any Unicode character except double-quote-char
+ new-line-character double-quote-char Any Unicode character except @
expandable-string-with-subexpr-start:
-double-quote-character expandable-string-chars~opt~ *\$(*
+ double-quote-character expandable-string-chars~opt~ $(
expandable-string-with-subexpr-end:
-double-quote-char
+ double-quote-char
expandable-here-string-with-subexpr-start:
-*@* double-quote-character whitespace~opt~ new-line-character
-expandable-here-string-chars~opt~ *\$(*
+ @ double-quote-character whitespace~opt~ new-line-character expandable-here-string-chars~opt~ $(
expandable-here-string-with-subexpr-end:
-new-line-character double-quote-character *@*
+ new-line-character double-quote-character @
verbatim-string-literal:
-single-quote-character verbatim-string-characters~opt~ single-quote-char
+ single-quote-character verbatim-string-characters~opt~ single-quote-char
single-quote-character:
-*\' (U+0027)
-Left single quotation mark (U+2018)
-Right single quotation mark (U+2019)
-Single low-9 quotation mark (U+201A)
-Single high-reversed-9 quotation mark (U+201B)*
+ ' (U+0027)
+ Left single quotation mark (U+2018)
+ Right single quotation mark (U+2019)
+ Single low-9 quotation mark (U+201A)
+ Single high-reversed-9 quotation mark (U+201B)
verbatim-string-characters:
-verbatim-string-part
-verbatim-string-characters verbatim-string-part
+ verbatim-string-part
+ verbatim-string-characters verbatim-string-part
verbatim-string-part:
-*Any Unicode character except* single-quote-character
-single-quote-character single-quote-character
+ *Any Unicode character except* single-quote-character
+ single-quote-character single-quote-character
verbatim-here-string-literal:
-*@* single-quote-character whitespace~opt~ new-line-character
-verbatim-here-string-characters~opt~ new-line-character
-single-quote-character *@*
+ @ single-quote-character whitespace~opt~ new-line-character
+ verbatim-here-string-characters~opt~ new-line-character
+ single-quote-character *@*
verbatim-*here-string-characters:
-verbatim-here-string-part
-verbatim-here-string-characters verbatim-here-string-part*
+ verbatim-here-string-part
+ verbatim-here-string-characters verbatim-here-string-part
-*verbatim-here-string-part:
-Any Unicode character except* new-line-character
-new-line-character *Any Unicode character except*
-single-quote-character
-new-line-character single-quote-character *Any Unicode character except
-@*
+verbatim-here-string-part:
+ Any Unicode character except* new-line-character
+ new-line-character Any Unicode character except single-quote-character
+ new-line-character single-quote-character Any Unicode character except @
+```
-### Simple Names
+### B.1.10 Simple Names
+```Syntax
simple-name:
-simple-name-first-char simple-name-chars
+ simple-name-first-char simple-name-chars
simple-name-first-char:
-*A Unicode character of classes Lu, Ll, Lt, Lm, or Lo
-\_ (The underscore character U+005F)*
+ A Unicode character of classes Lu, Ll, Lt, Lm, or Lo
+ _ (The underscore character U+005F)
simple-name-chars:
-simple-name-char
-simple-name-chars simple-name-char
+ simple-name-char
+ simple-name-chars simple-name-char
simple-name-char:
-*A Unicode character of classes Lu, Ll, Lt, Lm, Lo, or Nd
-\_ (The underscore character U+005F)*
+ A Unicode character of classes Lu, Ll, Lt, Lm, Lo, or Nd
+ _ (The underscore character U+005F)
+```
-### Type Names
+### B.1.11 Type Names
+```Syntax
type-name:
-type-identifier
-type-name *.* type-identifier
+ type-identifier
+ type-name . type-identifier
type-identifier:
-type-characters
+ type-characters
type-characters:
-type-character
-type-characters type-character
+ type-character
+ type-characters type-character
type-character:
-*A Unicode character of classes Lu, Ll, Lt, Lm, Lo, or Nd
-\_ (The underscore character U+005F)*
+ A Unicode character of classes Lu, Ll, Lt, Lm, Lo, or Nd
+ _ (The underscore character U+005F)
array-type-name:
-type-name *\[*
+ type-name [
generic-type-name:
-type-name *\[*
-
-### Operators and punctuators
-
-operator-or-punctuator: *one of*
-*{ } \[ \] ( ) @( @{ \$( ;
-&& \|\| & \| , ++ .. :: .
-! \* / % +
-*dash dash dash*
-*dash *and* dash *band* dash *bnot
-*dash *bor* dash *bxor* dash *not
-*dash *or* dash *xor
-*assignment-operator
-merging-redirection-operator
-file-redirection-operator
-comparison-operator
-format-operator
-
-assignment-operator: *one of
-=* dash *= += \*= /= %=*
-
-merging-redirection-operator: *one of*
-*\*&gt;&1 2&gt;&1 3&gt;&1 4&gt;&1 5&gt;&1 6&gt;&1
-\*&gt;&2 1&gt;&2 3&gt;&2 4&gt;&2 5&gt;&2 6&gt;&2*
-
-file-redirection-operator: *one of*
-*&gt; &gt;&gt; 2&gt; 2&gt;&gt; 3&gt; 3&gt;&gt; 4&gt; 4&gt;&gt;
-5&gt; 5&gt;&gt; 6&gt; 6&gt;&gt; \*&gt; \*&gt;&gt; &lt;*
-
-comparison-operator: *one of
-*dash *as* dash *ccontains* dash *ceq
-*dash *cge* dash *cgt* dash *cle
-*dash *clike* dash *clt* dash *cmatch
-*dash *cne* dash *cnotcontains* dash *cnotlike
-*dash *cnotmatch* dash *contains* dash *creplace
-*dash *csplit* dash *eq* dash *ge
-*dash *gt* dash *icontains* dash *ieq
-*dash *ige* dash *igt* dash *ile
-*dash *ilike* dash *ilt* dash *imatch
-*dash *in* dash *ine* dash *inotcontains
-*dash *inotlike* dash *inotmatch* dash *ireplace
-*dash *is* dash *isnot* dash *isplit
-*dash *join* dash *le* dash *like
-*dash *lt* dash *match* dash *ne
-*dash *notcontains* dash *notin* dash *notlike
-*dash *notmatch* dash *replace* dash *shl*
-dash *shr* dash *split*
+ type-name [
+```
+
+### B.1.12 Operators and punctuators
+
+```Syntax
+operator-or-punctuator: one of
+ { } [ ] ( ) @( @{ $( ;
+ && || & | , ++ .. :: .
+ ! * / % +
+ dash dashdash
+ dash and dash band dash bnot dash bor
+ dash bxor dash not dash or dash xor
+ assignment-operator
+ merging-redirection-operator
+ file-redirection-operator
+ comparison-operator
+ format-operator
+
+assignment-operator: one of
+ = dash = += *= /= %=
+
+file-redirection-operator: one of
+ > >> 2> 2>> 3> 3>> 4> 4>>
+ 5> 5>> 6> 6>> *> *>> <
+
+merging-redirection-operator: one of
+ *>&1 2>&1 3>&1 4>&1 5>&1 6>&1
+ *>&2 1>&2 3>&2 4>&2 5>&2 6>&2
+
+comparison-operator: one of
+ dash as dash ccontains dash ceq
+ dash cge dash cgt dash cle
+ dash clike dash clt dash cmatch
+ dash cne dash cnotcontains dash cnotlike
+ dash cnotmatch dash contains dash creplace
+ dash csplit dash eq dash ge
+ dash gt dash icontains dash ieq
+ dash ige dash igt dash ile
+ dash ilike dash ilt dash imatch
+ dash in dash ine dash inotcontains
+ dash inotlike dash inotmatch dash ireplace
+ dash is dash isnot dash isplit
+ dash join dash le dash like
+ dash lt dash match dash ne
+ dash notcontains dash notin dash notlike
+ dash notmatch dash replace dash shl*
+ dash shr dash split
format-operator:
-dash *f*
+ dash f
+```
-## Syntactic grammar
+## B.2 Syntactic grammar
-### Basic concepts
+### B.2.1 Basic concepts
+```Syntax
script-file:
-script-block
+ script-block
module-file:
-script-block
+ script-block
interactive-input:
-script-block
+ script-block
data-file:
-statement-list
+ statement-list
+```
-### Statements
+### B.2.2 Statements
+```Syntax
script-block:
-param-block~opt~ statement-terminators~opt~ script-block-body~opt~
+ param-block~opt~ statement-terminators~opt~ script-block-body~opt~
param-block:
-new-lines~opt~ attribute-list~opt~ new-lines~opt~ *param*
-new-lines~opt~
-*(* parameter-list~opt~ new-lines~opt~ *)*
+ new-lines~opt~ attribute-list~opt~ new-lines~opt~ param new-lines~opt~
+ ( parameter-list~opt~ new-lines~opt~ )
parameter-list:
-script-parameter
-parameter-list new-lines~opt~ *,* script-parameter
+ script-parameter
+ parameter-list new-lines~opt~ , script-parameter
script-parameter:
-new-lines~opt~ attribute-list~opt~ new-lines~opt~ variable
-script-parameter-default~opt~
+ new-lines~opt~ attribute-list~opt~ new-lines~opt~ variable script-parameter-default~opt~
script-parameter-default:
-new-lines~opt~ *=* new-lines~opt~ expression
+ new-lines~opt~ = new-lines~opt~ expression
script-block-body:
-named-block-list
-statement-list
+ named-block-list
+ statement-list
named-block-list:
-named-block
-named-block-list named-block
+ named-block
+ named-block-list named-block
named-block:
-block-name statement-block statement-terminators~opt~
+ block-name statement-block statement-terminators~opt~
-block-name: *one of*
-*dynamicparam begin process end*
+block-name: one of
+ dynamicparam begin process end
statement-block:
-new-lines~opt~ *{* statement-list~opt~ new-lines~opt~ *}*
+ new-lines~opt~ { statement-list~opt~ new-lines~opt~ }
statement-list:
-statement
-statement-list statement
+ statement
+ statement-list statement
statement:
-if-statement
-label~opt~ labeled-statement
-function-statement
-flow-control-statement statement-terminator
-trap-statement
-try-statement
-data-statement
-inlinescript-statement
-parallel-statement
-sequence-statement
-pipeline statement-terminator
+ if-statement
+ label~opt~ labeled-statement
+ function-statement
+ flow-control-statement statement-terminator
+ trap-statement
+ try-statement
+ data-statement
+ inlinescript-statement
+ parallel-statement
+ sequence-statement
+ pipeline statement-terminator
statement-terminator:
-*;*
-new-line-character
+ ;
+ new-line-character
statement-terminators:
-statement-terminator
-statement-terminators statement-terminator
+ statement-terminator
+ statement-terminators statement-terminator
if-statement:
-*if* new-lines~opt~ *(* new-lines~opt~ pipeline new-lines~opt~ *)*
-statement-block
-elseif-clauses~opt~ else-clause~opt~
+ if new-lines~opt~ ( new-lines~opt~ pipeline new-lines~opt~ ) statement-block
+ elseif-clauses~opt~ else-clause~opt~
elseif-clauses:
-elseif-clause
-elseif-clauses elseif-clause
+ elseif-clause
+ elseif-clauses elseif-clause
elseif-clause:
-new-lines~opt~ *elseif* new-lines~opt~ *(* new-lines~opt~ pipeline
-new-lines~opt~ *)* statement-block
+ new-lines~opt~ elseif new-lines~opt~ ( new-lines~opt~ pipeline new-lines~opt~ ) statement-block
else-clause:
-new-lines~opt~ *else* statement-block
+ new-lines~opt~ else statement-block
labeled-statement:
-switch-statement
-foreach-statement
-for-statement
-while-statement
-do-statement
+ switch-statement
+ foreach-statement
+ for-statement
+ while-statement
+ do-statement
switch-statement:
-*switch* new-lines~opt~ switch-parameters~opt~ switch-condition
-switch-body
+ switch new-lines~opt~ switch-parameters~opt~ switch-condition switch-body
switch-parameters:
-switch-parameter
-switch-parameters switch-parameter
+ switch-parameter
+ switch-parameters switch-parameter
switch-parameter:
-*-regex
--wildcard--exact--casesensitive--parallel*
+ -regex
+ -wildcard
+ -exact
+ -casesensitive
+ -parallel
switch-condition:
-*(* new-lines~opt~ pipeline new-lines~opt~ *)
--file* new-lines~opt~ switch-filename
+ ( new-lines~opt~ pipeline new-lines~opt~ )
+ -file new-lines~opt~ switch-filename
switch-filename:
-command-argument
-primary-expression
+ command-argument
+ primary-expression
switch-body:
-new-lines~opt~ *{* new-lines~opt~ switch-clauses *}*
+ new-lines~opt~ { new-lines~opt~ switch-clauses }
switch-clauses:
-switch-clause
-switch-clauses switch-clause
+ switch-clause
+ switch-clauses switch-clause
switch-clause:
-switch-clause-condition statement-block statement-terimators~opt~
+ switch-clause-condition statement-block statement-terimators~opt~
switch-clause-condition:
-command-argument
-primary-expression
+ command-argument
+ primary-expression
foreach-statement:
-*foreach* new-lines~opt~ foreach-parameter~opt~ new-lines~opt~
-*(* new-lines~opt~ variable new-lines~opt~ *in* new-lines~opt~
-pipeline
-new-lines~opt~ *)* statement-block
+ foreach new-lines~opt~ foreach-parameter~opt~ new-lines~opt~
+ ( new-lines~opt~ variable new-lines~opt~ in new-lines~opt~ pipeline
+ new-lines~opt~ ) statement-block
foreach-parameter:
-*-parallel*
+ -parallel
for-statement:
-*for* new-lines~opt~ *(*
-new-lines~opt~ for-initializer~opt~ statement-terminator
-new-lines~opt~ for-condition~opt~ statement-terminator*
-* new-lines~opt~ for-iterator~opt~
-new-lines~opt~ *)* statement-block
-*for* new-lines~opt~ *(*
-new-lines~opt~ for-initializer~opt~ statement-terminator*
-*new-lines~opt~ for-condition~opt~
-new-lines~opt~ *)* statement-block
-*for* new-lines~opt~ *(
-*new-lines~opt~ for-initializer~opt~
-new-lines~opt~ *)* statement-block
+ for new-lines~opt~ (
+ new-lines~opt~ for-initializer~opt~ statement-terminator
+ new-lines~opt~ for-condition~opt~ statement-terminator
+ new-lines~opt~ for-iterator~opt~
+ new-lines~opt~ ) statement-block
+ for new-lines~opt~ (
+ new-lines~opt~ for-initializer~opt~ statement-terminator
+ new-lines~opt~ for-condition~opt~
+ new-lines~opt~ ) statement-block
+ for new-lines~opt~ (
+ new-lines~opt~ for-initializer~opt~
+ new-lines~opt~ ) statement-block
for-initializer:
-pipeline
+ pipeline
for-condition:
-pipeline
+ pipeline
for-iterator:
-pipeline
+ pipeline
while-statement:
-*while* new-lines~opt~ *(* new-lines~opt~ while-condition new-lines~opt~
-*)* statement-block
+ while new-lines~opt~ ( new-lines~opt~ while-condition new-lines~opt~ ) statement-block
do-statement:
-*do* statement-block new-lines~opt~ *while* new-lines~opt~ *(*
-while-condition new-lines~opt~ *)*
-*do* statement-block new-lines~opt~ *until* new-lines~opt~ *(*
-while-condition new-lines~opt~ *)*
+ do statement-block new-lines~opt~ while new-lines~opt~ ( while-condition new-lines~opt~ )
+ do statement-block new-lines~opt~ until new-lines~opt~ ( while-condition new-lines~opt~ )
while-condition:
-new-lines~opt~ pipeline
+ new-lines~opt~ pipeline
function-statement:
-*function* new-lines~opt~ function-name
-function-parameter-declaration~opt~ *{* script-block *}*
-*filter* new-lines~opt~ function-name
-function-parameter-declaration~opt~ *{* script-block *}
-workflow* new-lines~opt~ function-name
-function-parameter-declaration~opt~ *{* script-block *}*
+ function new-lines~opt~ function-name function-parameter-declaration~opt~ { script-block }
+ filter new-lines~opt~ function-name function-parameter-declaration~opt~ { script-block }
+ workflow new-lines~opt~ function-name function-parameter-declaration~opt~ { script-block }
function-name:
-command-argument
+ command-argument
function-parameter-declaration:
-new-lines~opt~ *(* parameter-list new-lines~opt~ *)*
+ new-lines~opt~ ( parameter-list new-lines~opt~ )
flow-control-statement:
-*break* label-expression~opt~
-*continue* label-expression~opt~
-*throw* pipeline~opt~
-*return* pipeline~opt~
-*exit* pipeline~opt~
+ break label-expression~opt~
+ continue label-expression~opt~
+ throw pipeline~opt~
+ return pipeline~opt~
+ exit pipeline~opt~
label-expression:
-simple-name
-unary-expression
+ simple-name
+ unary-expression
trap-statement:
-*trap* new-lines~opt~ type-literal~opt~ new-lines~opt~ statement-block
+ trap new-lines~opt~ type-literal~opt~ new-lines~opt~ statement-block
try-statement:
-*try* statement-block catch-clauses
-*try* statement-block finally-clause
-*try* statement-block catch-clauses finally-clause
+ try statement-block catch-clauses
+ try statement-block finally-clause
+ try statement-block catch-clauses finally-clause
catch-clauses:
-catch-clause
-catch-clauses catch-clause
+ catch-clause
+ catch-clauses catch-clause
catch-clause:
-new-lines~opt~ catch catch-type-list~opt~ statement-block
+ new-lines~opt~ catch catch-type-list~opt~ statement-block
catch-type-list:
-new-lines~opt~ type-literal
-catch-type-list new-lines~opt~ *,* new-lines~opt~ type-literal
+ new-lines~opt~ type-literal
+ catch-type-list new-lines~opt~ , new-lines~opt~ type-literal
finally-clause:
-new-lines~opt~ *finally* statement-block
+ new-lines~opt~ finally statement-block
data-statement:
-*data* new-lines~opt~ data-name data-commands-allowed~opt~
-statement-block
+ data new-lines~opt~ data-name data-commands-allowed~opt~
+ statement-block
data-name:
-simple-name
+ simple-name
data-commands-allowed:
-new-lines~opt~ *-supportedcommand* data-commands-list
+ new-lines~opt~ -supportedcommand data-commands-list
data-commands-list:
-new-lines~opt~ data-command
-data-commands-list *,* new-lines~opt~ data-command
+ new-lines~opt~ data-command
+ data-commands-list , new-lines~opt~ data-command
data-command:
-command-name-expr
+ command-name-expr
inlinescript-statement:
-*inlinescript* statement-block
+ inlinescript statement-block
parallel-statement:
-*parallel* statement-block
+ parallel statement-block
sequence-statement:
-*sequence* statement-block
+ sequence statement-block
pipeline:
-assignment-expression
-expression redirections~opt~ pipeline-tail~opt~
-command verbatim-command-argument~opt~ pipeline-tail~opt~
+ assignment-expression
+ expression redirections~opt~ pipeline-tail~opt~
+ command verbatim-command-argument~opt~ pipeline-tail~opt~
assignment-expression:
-expression assignment-operator statement
+ expression assignment-operator statement
pipeline-tail:
-*\|* new-lines~opt~ command
-*\|* new-lines~opt~ command pipeline-tail
+ | new-lines~opt~ command
+ | new-lines~opt~ command pipeline-tail
command:
-command-name command-elements~opt~
-command-invocation-operator command-module~opt~ command-name-expr
-command-elements~opt~
+ command-name command-elements~opt~
+ command-invocation-operator command-module~opt~ command-name-expr command-elements~opt~
-command-invocation-operator: *one of*
-*&* *.*
+command-invocation-operator: one of
+ & .
command-module:
-primary-expression
+ primary-expression
command-name:
-generic-token
-generic-token-with-subexpr
+ generic-token
+ generic-token-with-subexpr
generic-token-with-subexpr:
-*No whitespace is allowed between ) and* command-name.
-generic-token-with-subexpr-start statement-list~opt~ *)* command-name
+ No whitespace is allowed between ) and command-name.
+ generic-token-with-subexpr-start statement-list~opt~ ) command-name
command-name-expr:
-command-name
-primary-expression
+ command-name
+ primary-expression
command-elements:
-command-element
-command-elements command-element
+ command-element
+ command-elements command-element
command-element:
-command-parameter
-command-argument
-redirection
+ command-parameter
+ command-argument
+ redirection
command-argument:
-command-name-expr
+ command-name-expr
verbatim-command-argument:
-*\--%* verbatim-command-argument-chars
+ --% verbatim-command-argument-chars
redirections:
-redirection
-redirections redirection
+ redirection
+ redirections redirection
redirection:
-merging-redirection-operator
-file-redirection-operator redirected-file-name
+ merging-redirection-operator
+ file-redirection-operator redirected-file-name
redirected-file-name:
-command-argument
-primary-expression
+ command-argument
+ primary-expression
+```
-### Expressions
+### B.2.3 Expressions
+```Syntax
expression:
-logical-expression
+ logical-expression
logical-expression:
-bitwise-expression
-logical-expression *-and* new-lines~opt~ bitwise-expression
-logical-expression *-or* new-lines~opt~ bitwise-expression
-logical-expression *-xor* new-lines~opt~ bitwise-expression
+ bitwise-expression
+ logical-expression -and new-lines~opt~ bitwise-expression
+ logical-expression -or new-lines~opt~ bitwise-expression
+ logical-expression -xor new-lines~opt~ bitwise-expression
bitwise-expression:
-comparison-expression
-bitwise-expression *-band* new-lines~opt~ comparison-expression
-bitwise-expression *-bor* new-lines~opt~ comparison-expression
-bitwise-expression *-bxor* new-lines~opt~ comparison-expression
+ comparison-expression
+ bitwise-expression -band new-lines~opt~ comparison-expression
+ bitwise-expression -bor new-lines~opt~ comparison-expression
+ bitwise-expression -bxor new-lines~opt~ comparison-expression
comparison-expression:
-additive-expression
-comparison-expression comparison-operator new-lines~opt~
-additive-expression
+ additive-expression
+ comparison-expression comparison-operator new-lines~opt~
+ additive-expression
additive-expression:
-multiplicative-expression
-additive-expression *+* new-lines~opt~ multiplicative-expression
-additive-expression dash new-lines~opt~ multiplicative-expression
+ multiplicative-expression
+ additive-expression + new-lines~opt~ multiplicative-expression
+ additive-expression dash new-lines~opt~ multiplicative-expression
multiplicative-expression:
-format-expression
-multiplicative-expression *\** new-lines~opt~ format-expression
-multiplicative-expression */* new-lines~opt~ format-expression
-multiplicative-expression *%* new-lines~opt~ format-expression
+ format-expression
+ multiplicative-expression \ new-lines~opt~ format-expression
+ multiplicative-expression / new-lines~opt~ format-expression
+ multiplicative-expression % new-lines~opt~ format-expression
format-expression:
-range-expression
-format-expression format-operator new-lines~opt~ range-expression
+ range-expression
+ format-expression format-operator new-lines~opt~ range-expression
range-expression:
-array-literal-expression
-range-expression *..* new-lines~opt~ array-literal-expression
+ array-literal-expression
+ range-expression .. new-lines~opt~ array-literal-expression
array-literal-expression:
-unary-expression
-unary-expression *,* new-lines~opt~ array-literal-expression
+ unary-expression
+ unary-expression , new-lines~opt~ array-literal-expression
unary-expression:
-primary-expression
-expression-with-unary-operator
+ primary-expression
+ expression-with-unary-operator
expression-with-unary-operator:
-*,* new-lines~opt~ unary-expression
-*-not* new-lines~opt~ unary-expression
-*!* new-lines~opt~ unary-expression
-*-bnot* new-lines~opt~ unary-expression
-*+* new-lines~opt~ unary-expression
-dash new-lines~opt~ unary-expression
-pre-increment-expression
-pre-decrement-expression
-cast-expression
-*-split* new-lines~opt~ unary-expression*
--join* new-lines~opt~ unary-expression
+ , new-lines~opt~ unary-expression
+ -not new-lines~opt~ unary-expression
+ ! new-lines~opt~ unary-expression
+ -bnot new-lines~opt~ unary-expression
+ + new-lines~opt~ unary-expression
+ dash new-lines~opt~ unary-expression
+ pre-increment-expression
+ pre-decrement-expression
+ cast-expression
+ -split new-lines~opt~ unary-expression
+ -join new-lines~opt~ unary-expression
pre-increment-expression:
-*++* new-lines~opt~ unary-expression
+ ++ new-lines~opt~ unary-expression
pre-decrement-expression:
-dashdash new-lines~opt~ unary-expression
+ dashdash new-lines~opt~ unary-expression
cast-expression:
-type-literal unary-expression
+ type-literal unary-expression
attributed-expression:
-type-literal variable
+ type-literal variable
primary-expression:
-value
-member-access
-element-access
-invocation-expression
-post-increment-expression
-post-decrement-expression
+ value
+ member-access
+ element-access
+ invocation-expression
+ post-increment-expression
+ post-decrement-expression
value:
-parenthesized-expression
-sub-expression
-array-expression
-script-block-expression
-hash-literal-expression
-literal
-type-literal
-variable
+ parenthesized-expression
+ sub-expression
+ array-expression
+ script-block-expression
+ hash-literal-expression
+ literal
+ type-literal
+ variable
parenthesized-expression:
-*(* new-lines~opt~ pipeline new-lines~opt~ *)*
+ ( new-lines~opt~ pipeline new-lines~opt~ )
sub-expression:
-*\$(* new-lines~opt~ statement-list~opt~ new-lines~opt~ *)*
+ $( new-lines~opt~ statement-list~opt~ new-lines~opt~ )
array-expression:
-*@(* new-lines~opt~ statement-list~opt~ new-lines~opt~ *)*
+ @( new-lines~opt~ statement-list~opt~ new-lines~opt~ )
script-block-expression:
-*{* new-lines~opt~ script-block new-lines~opt~ *}*
+ { new-lines~opt~ script-block new-lines~opt~ }
hash-literal-expression:
-*@{* new-lines~opt~ hash-literal-body~opt~ new-lines~opt~ *}*
+ @{ new-lines~opt~ hash-literal-body~opt~ new-lines~opt~ }
hash-literal-body:
-hash-entry
-hash-literal-body statement-terminators hash-entry
+ hash-entry
+ hash-literal-body statement-terminators hash-entry
hash-entry:
-key-expression = new-lines~opt~ statement
+ key-expression = new-lines~opt~ statement
key-expression:
-simple-name
-unary-expression
+ simple-name
+ unary-expression
post-increment-expression:
-primary-expression *++*
+ primary-expression ++
post-decrement-expression:
-primary-expression dashdash
+ primary-expression dashdash
-member-access: *Note no whitespace is allowed after*
-primary-expression*.*
-primary-expression *.* member-name
-primary-expression *::* member-name
+member-access: Note no whitespace is allowed after
+ primary-expression.
+ primary-expression . member-name
+ primary-expression :: member-name
-element-access: *Note no whitespace is allowed between*
-primary-expression *and \[.*
-primary-expression *\[* new-lines~opt~ expression new-lines~opt~ *\]*
+element-access: Note no whitespace is allowed between primary-expression and [.
+ primary-expression [ new-lines~opt~ expression new-lines~opt~ ]
-invocation-expression: *Note no whitespace is allowed after*
-primary-expression*.*
-primary-expression *.* member-name argument-list
-primary-expression *::* member-name argument-list
+invocation-expression: Note no whitespace is allowed after
+ primary-expression.
+ primary-expression . member-name argument-list
+ primary-expression :: member-name argument-list
argument-list:
-*(* argument-expression-list~opt~ new-lines~opt~ *)*
+ ( argument-expression-list~opt~ new-lines~opt~ )
argument-expression-list:
-argument-expression
-argument-expression new-lines~opt~ *,* argument-expression-list
+ argument-expression
+ argument-expression new-lines~opt~ , argument-expression-list
argument-expression:
-new-lines~opt~ logical-argument-expression
+ new-lines~opt~ logical-argument-expression
logical-argument-expression:
-bitwise-argument-expression
-logical-argument-expression *-and* new-lines~opt~
-bitwise-argument-expression
-logical-argument-expression *-or* new-lines~opt~
-bitwise-argument-expression
-logical-argument-expression *-xor* new-lines~opt~
-bitwise-argument-expression
+ bitwise-argument-expression
+ logical-argument-expression -and new-lines~opt~ bitwise-argument-expression
+ logical-argument-expression -or new-lines~opt~ bitwise-argument-expression
+ logical-argument-expression -xor new-lines~opt~ bitwise-argument-expression
bitwise-argument-expression:
-comparison-argument-expression
-bitwise-argument-expression *-band* new-lines~opt~
-comparison-argument-expression
-bitwise-argument-expression *-bor* new-lines~opt~
-comparison-argument-expression
-bitwise-argument-expression *-bxor* new-lines~opt~
-comparison-argument-expression
+ comparison-argument-expression
+ bitwise-argument-expression -band new-lines~opt~ comparison-argument-expression
+ bitwise-argument-expression -bor new-lines~opt~ comparison-argument-expression
+ bitwise-argument-expression -bxor new-lines~opt~ comparison-argument-expression
comparison-argument-expression:
-additive-argument-expression
-comparison-argument-expression comparison-operator
-new-lines~opt~ additive-argument-expression
+ additive-argument-expression
+ comparison-argument-expression comparison-operator
+ new-lines~opt~ additive-argument-expression
additive-argument-expression:
-multiplicative-argument-expression
-additive-argument-expression *+* new-lines~opt~
-multiplicative-argument-expression
-additive-argument-expression dash new-lines~opt~
-multiplicative-argument-expression
+ multiplicative-argument-expression
+ additive-argument-expression + new-lines~opt~ multiplicative-argument-expression
+ additive-argument-expression dash new-lines~opt~ multiplicative-argument-expression
multiplicative-argument-expression:
-format-argument-expression
-multiplicative-argument-expression *\** new-lines~opt~
-format-argument-expression
-multiplicative-argument-expression */* new-lines~opt~
-format-argument-expression
-multiplicative-argument-expression *%* new-lines~opt~
-format-argument-expression
+ format-argument-expression
+ multiplicative-argument-expression \ new-lines~opt~ format-argument-expression
+ multiplicative-argument-expression / new-lines~opt~ format-argument-expression
+ multiplicative-argument-expression % new-lines~opt~ format-argument-expression
format-argument-expression:
-range-argument-expression
-format-argument-expression format-operator new-lines~opt~
-range-argument-expression
+ range-argument-expression
+ format-argument-expression format-operator new-lines~opt~ range-argument-expression
range-argument-expression:
-unary-expression
-range-expression *..* new-lines~opt~ unary-expression
+ unary-expression
+ range-expression .. new-lines~opt~ unary-expression
member-name:
-simple -name
-string-literal
-string-literal-with-subexpression
-expression-with-unary-operator
-value
+ simple-name
+ string-literal
+ string-literal-with-subexpression
+ expression-with-unary-operator
+ value
string-literal-with-subexpression:
-expandable-string-literal-with-subexpr
-expandable-here-string-literal-with-subexpr
+ expandable-string-literal-with-subexpr
+ expandable-here-string-literal-with-subexpr
expandable-string-literal-with-subexpr:
-expandable-string-with-subexpr-start statement-list~opt~ *)
-*expandable-string-with-subexpr-characters
-expandable-string-with-subexpr-end
-expandable-here-string-with-subexpr-start statement-list~opt~ *)*
-expandable-here-string-with-subexpr-characters
-expandable-here-string-with-subexpr-end
+ expandable-string-with-subexpr-start statement-list~opt~ )
+ expandable-string-with-subexpr-characters expandable-string-with-subexpr-end
+ expandable-here-string-with-subexpr-start statement-list~opt~ )
+ expandable-here-string-with-subexpr-characters
+ expandable-here-string-with-subexpr-end
expandable-string-with-subexpr-characters:
-expandable-string-with-subexpr-part
-expandable-string-with-subexpr-characters
-expandable-string-with-subexpr-part
+ expandable-string-with-subexpr-part
+ expandable-string-with-subexpr-characters expandable-string-with-subexpr-part
expandable-string-with-subexpr-part:
-sub-expression
-expandable-string-part
+ sub-expression
+ expandable-string-part
expandable-here-string-with-subexpr-characters:
-expandable-here-string-with-subexpr-part
-expandable-here-string-with-subexpr-characters
-expandable-here-string-with-subexpr-part
+ expandable-here-string-with-subexpr-part
+ expandable-here-string-with-subexpr-characters expandable-here-string-with-subexpr-part
expandable-here-string-with-subexpr-part:
-sub-expression
-expandable-here-string-part
+ sub-expression
+ expandable-here-string-part
type-literal:
-*\[* type-spec *\]*
+ [ type-spec ]
type-spec:
-array-type-name new-lines~opt~ dimension~opt~ *\]
-*generic-type-name new-lines~opt~ generic-type-arguments *\]*
-type-name
+ array-type-name new-lines~opt~ dimension~opt~ ]
+ generic-type-name new-lines~opt~ generic-type-arguments ]
+ type-name
dimension:
-*,
-dimension* *,*
+ ,
+ dimension ,
generic-type-arguments:
-type-spec new-lines~opt~
-generic-type-arguments *,* new-lines~opt~ type-spec
+ type-spec new-lines~opt~
+ generic-type-arguments , new-lines~opt~ type-spec
+```
-### Attributes
+### B.2.4 Attributes
+```Syntax
attribute-list:
-attribute
-attribute-list new-lines~opt~ attribute
+ attribute
+ attribute-list new-lines~opt~ attribute
attribute:
-*\[* new-lines~opt~ attribute-name *(* attribute-arguments
-new-lines~opt~ *)* new-lines~opt~ *\]
-*type-literal
+ [ new-lines~opt~ attribute-name ( attribute-arguments new-lines~opt~ ) new-lines~opt~ ]
+ type-literal
attribute-name:
-type-spec
+ type-spec
attribute-arguments:
-attribute-argument
-attribute-argument new-lines~opt~ *,* attribute-arguments
+ attribute-argument
+ attribute-argument new-lines~opt~ , attribute-arguments
attribute-argument:
-new-lines~opt~ expression
-new-lines~opt~ simple-name
-new-lines~opt~ simple-name *=* new-lines~opt~ expression
+ new-lines~opt~ expression
+ new-lines~opt~ simple-name
+ new-lines~opt~ simple-name = new-lines~opt~ expression
+```
+<!-- reference links -->
lang-spec Chapter 16 https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/lang-spec/chapter-16.md
description: This appendix contains a list of references to computing standards
Last updated 05/19/2021 Title: Appendix B - References ---
-# References
+# C. References
ANSI/IEEE 754−2008, *Binary floating-point arithmetic for microprocessor systems*.
ISO/IEC 10646-1/AMD1:1996, Amendment 1 to ISO/IEC 10646-1:1993, *Transformation
*The Unicode Standard*, Edition 5.2. The Unicode Consortium, [http://www.unicode.org/standard/standard.html](http://www.unicode.org/standard/standard.html).+
+<!-- reference links -->