Skip to content

reformatting About_* for 80 columns - part 7 #1914

New issue

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

Sign up for GitHub

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

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Dec 5, 2017
Merged

reformatting About_* for 80 columns - part 7 #1914

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

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
79 changes: 40 additions & 39 deletions reference/3.0/Microsoft.PowerShell.Core/About/about_Splatting.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
ms.date: 2017-06-09
ms.date: 2017-12-01
schema: 2.0.0
locale: en-us
keywords: powershell,cmdlet
Expand Down Expand Up @@ -74,20 +74,24 @@ are included.
Copy-Item -Path "test.txt" -Destination "test2.txt" -WhatIf
```

The second example uses hash table splatting. The first command creates
a hash table of parameter-name and parameter-value pairs and stores it
in the $HashArguments variable. The second command uses the `$HashArguments`
variable in a command with splatting. The At symbol (`@HashArguments`)
replaces the dollar sign (`$HashArguments`) in the command.
The second example uses hash table splatting. The first command creates a hash
table of parameter-name and parameter-value pairs and stores it in the
\$HashArguments variable. The second command uses the `$HashArguments` variable
in a command with splatting. The At symbol (`@HashArguments`) replaces the
dollar sign (`$HashArguments`) in the command.

To provide a value for the WhatIf switch parameter, use $True or $False.

```powershell
$HashArguments = @{ Path = "test.txt"; Destination = "test2.txt"; WhatIf = $true }
$HashArguments = @{
Path = "test.txt"
Destination = "test2.txt"
WhatIf = $true
}
Copy-Item @HashArguments
```

*Note: In the first command, the At symbol (@) indicates a hash table, not
Note: In the first command, the At symbol (@) indicates a hash table, not
a splatted value. The syntax for hash tables in Windows PowerShell is:
@{\<name\>=\<value\>; \<name\>=\<value\>; …}*

Expand All @@ -106,11 +110,12 @@ omitted. The parameter values appear in position order in the command.
Copy-Item "test.txt" "test2.txt" -WhatIf
```

The second example uses array splatting. The first command creates an array
of the parameter values and stores it in the `$ArrayArguments` variable. The
The second example uses array splatting. The first command creates an array of
the parameter values and stores it in the `$ArrayArguments` variable. The
values are in position order in the array. The second command uses the
`$ArrayArguments` variable in a command in splatting. The At symbol
(`@ArrayArguments`) replaces the dollar sign (`$ArrayArguments`) in the command.
(`@ArrayArguments`) replaces the dollar sign (`$ArrayArguments`) in the
command.

```powershell
$ArrayArguments = "test.txt", "test2.txt"
Expand All @@ -120,10 +125,10 @@ Copy-Item @ArrayArguments -WhatIf
# EXAMPLES


This example shows how to re-use splatted values in different commands.
The commands in this example use the Write-Host cmdlet to write messages
to the host program console. It uses splatting to specify the foreground
and background colors.
This example shows how to re-use splatted values in different commands. The
commands in this example use the Write-Host cmdlet to write messages to the
host program console. It uses splatting to specify the foreground and
background colors.

To change the colors of all commands, just change the value of the `$Colors`
variable.
Expand All @@ -143,7 +148,8 @@ Write-Host command. To use the `$Colors variable`, replace the dollar sign
#Write a message with the colors in $Colors
Write-Host "This is a test." @Colors

#Write second message with same colors. The position of splatted hash table does not matter.
#Write second message with same colors. The position of splatted
#hash table does not matter.
Write-Host @Colors "This is another test."
```

Expand Down Expand Up @@ -193,22 +199,19 @@ Test2 -a 1 -b 2 -c 3

# SPLATTING COMMAND PARAMETERS

You can use splatting to represent the parameters of
a command. This technique is useful when you are creating
a proxy function, that is, a function that calls another
command. This feature is introduced in Windows PowerShell 3.0.
You can use splatting to represent the parameters of a command. This technique
is useful when you are creating a proxy function, that is, a function that
calls another command. This feature is introduced in Windows PowerShell 3.0.

To splat the parameters of a command, use `@Args` to represent
the command parameters. This technique is easier than
enumerating command parameters and it works without revision
even if the parameters of the called command change.
To splat the parameters of a command, use `@Args` to represent the command
parameters. This technique is easier than enumerating command parameters and
it works without revision even if the parameters of the called command change.

The feature uses the `$Args` automatic variable, which contains
all unassigned parameter values.

For example, the following function calls the Get-Process
cmdlet. In this function, `@Args` represents all of the parameters
of the Get-Process cmdlet.
For example, the following function calls the Get-Process cmdlet. In this
function, `@Args` represents all of the parameters of the Get-Process cmdlet.

```powershell
function Get-MyProcess { Get-Process @Args }
Expand All @@ -223,20 +226,18 @@ Get-MyProcess -Name PowerShell

Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName
------- ------ ----- ----- ----- ------ -- -----------
463 46 225484 237196 719 15.86 3228 powershell
463 46 225484 237196 719 15.86 3228 powershell

Get-MyProcess -Name PowerShell_Ise -FileVersionInfo

ProductVersion FileVersion FileName
-------------- ----------- --------
6.2.9200.16384 6.2.9200.1638... C:\Windows\system32\WindowsPowerShell\v1.0\PowerShell_ISE.exe
6.2.9200.16384 6.2.9200.1638... C:\Windows\system32\WindowsPowerShell\...
```

You can use `@Args` in a function that has explicitly
declared parameters. You can use it more than once in
a function, but all parameters that you enter are passed
to all instances of `@Args`, as shown in the following
example.
You can use `@Args` in a function that has explicitly declared parameters. You
can use it more than once in a function, but all parameters that you enter are
passed to all instances of `@Args`, as shown in the following example.

```powershell
function Get-MyCommand
Expand All @@ -252,9 +253,9 @@ Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName
------- ------ ----- ----- ----- ------ -- -----------
408 28 75568 83176 620 1.33 1692 powershell

Path : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe
Path : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.e
Extension : .exe
Definition : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe
Definition : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.e
Visibility : Public
OutputType : {System.String}
Name : powershell.exe
Expand All @@ -265,10 +266,11 @@ RemotingCapability : PowerShell
Parameters :
ParameterSets :
HelpUri :
FileVersionInfo : File: C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe
FileVersionInfo : File: C:\Windows\System32\WindowsPowerShell
\v1.0\powershell.exe
InternalName: POWERSHELL
OriginalFilename: PowerShell.EXE.MUI
FileVersion: 10.0.14393.0 (rs1_release.160715-1616)
FileVersion: 10.0.14393.0 (rs1_release.160715-1616
FileDescription: Windows PowerShell
Product: Microsoft® Windows® Operating System
ProductVersion: 10.0.14393.0
Expand All @@ -289,4 +291,3 @@ FileVersionInfo : File: C:\Windows\System32\WindowsPowerShell\v1.
[about_Hash_Tables](about_Hash_Tables.md)

[about_Parameters](about_Parameters.md)

Loading