PowerShell Splat Operator

There is a new “splat” operator in PowerShell v2 which is quite useful but not well documented. The best info I can find is from this blog. From a PowerShell console I can see help content of “about_Split” and “about_Join”, but not “about_Splat”, or anything mentioned in “about_Operators”.

It is described that this new splat operator “@” can be used to pass a collection as parameters to a function. It’s easy to find out the details by experiments. First, draft a test function:

PS> function Echo-Args
>>  {
>>      echo "=== Args: ($($args.Length)) ==="
>>      echo $args
>>  }
PS>
PS> Echo-Args a b c 1 2 3
=== Args: (6) ===
a
b
c
1
2
3

Try it out with an array:

PS> $a = @(1,2,3)
PS> Echo-Args $a
=== Args: (1) ===
1
2
3
PS> Echo-Args @a
=== Args: (3) ===
1
2
3

See the difference of passing “$a” and “@a”? “$a” passes the whole array as one parameter. “@a” passes the elements as parameters.

To admit it, I was testing this for several days, but every time I ran into an “invalid operator” kind of error, because I was using “@$a”.

Now try it out with a hash table:

PS> $a = @{a=1;b=2;c=3}
PS> Echo-Args @a
=== Args: (6) ===
c
3
b
2
a
1
PS> function f($A, $B, $C) { $PSBoundParameters }
PS> f @a

Key                                                                       Value
---                                                                       -----
C                                                                             3
B                                                                             2
A                                                                             1


PS> $a = @{"-a"=1;"-b"=2;"-c"=3}
PS> f @a

Key                                                                       Value
---                                                                       -----
A                                                                             1
C                                                                             3
B                                                                             2

Now this is interesting. So you can splat and pass a hash table of parameters to a function, and PowerShell will always try to “do it right”. When the function is expecting named parameters, PowerShell can match them with or without leading “-“.

In summary, this splat operator is quite useful when you just want to pass some collection of parameters to another function, e.g. the current “$args” or “$PSBoundParameters”, with or without modification.

Technorati Tags: PowerShell,splat