Draft

Author: tibmeister

1-Draft/.vscode/spellchecker.json

@@ -0,0 +1,21 @@
+{
+    "language": "en_US",
+    "ignoreWordsList": [
+        "PowerShell",
+        "cmdlet",
+        "WSMan",
+        "remoting",
+        "SSHRemoting",
+        "seperate",
+        "TestConnection",
+        "ICMP"
+    ],
+    "documentTypes": [
+        "markdown",
+        "latex",
+        "plaintext"
+    ],
+    "ignoreRegExp": [],
+    "ignoreFileExtensions": [],
+    "checkInterval": 5000
+}

1-Draft/RFC-Test-Connection-Cross-Platform.md

@@ -1,251 +1,31 @@
 ---
-RFC: 0002
-Author: Jason Shirk
+RFC: 
+Author: Jody Whitlock
 Status: Draft
-Area: Splatting
-Comments Due: 3/31/2016
+Area: Commands
+Comments Due: 
 ---
 
-# Generalized Splatting
+# Get-TestConnection cmdlet for non-Windows Systems
 
-Splatting was introduced in PowerShell v2
-as a way of passing named arguments to a command
-using an expression (e.g. `@PSBoundParameters`)
-instead of explicit parameter syntax (e.g. `-Param1 $value`).
-The expression syntax introduced was limited
-to variable references and is more restrictive than necessary.
+Test-Connection, introduced in PowerShell 2.0 under the Microsoft.PowerShell.Management class provided a mechanism for sending ICMP echo requests within the PowerShell language and have the results returned as a PowerShell object that could be manipulated as such.
 
-Proxy functions are much easier to write using splatting.
-A proxy function might add or remove parameters to another command,
-but might not care about all of the parameters to the proxied command.
-The proxy still needs to pass those parameters through to the proxy,
-and it does this with splatting.
-
-Scripters have found splatting useful beyond proxy functions,
-but the current syntax limits broader use of splatting.
+While it's true that Test-Connection has evolved very little over the years and versions of PowerShell, on only need to look at the legacy that this cmdlet builds on, the ping command.  This simple command has mostly remained unchanged for as long as the ICMP protocol has existed.  It's a very simplistic function that while simplistic fills a massive void in network troubleshooting and validation of communication capabilities.
 
 ## Motivation
 
-One common use of splatting is to provide an alternate syntax for calling a command with many parameters.
-For example, consider a command like the following
-
-```PowerShell
-Update-TypeData -TypeName MyCustomType `
-             -MemberName MyCustomProperty `
-             -MemberType NoteProperty `
-             -Value 42
-```
-
-In the above example, note the use of backticks at the end of every line.
-Those backticks are difficult to read and easy to forget.
-Splatting can help some here:
+The motivation for this RFC is as simple as the ping command itself; provide a Test-Connection cmdlet that can run on any platform that PowerShell can.  This means stripping out some of the WSMan specific remoting capabilities that have been added to allow for distributed execution and removing WMI based methods and classes in favor of pure C# code.
 
-```PowerShell
-$addTypeParams = @{
-    TypeName = 'MyCustomType'
-    MemberName = 'MyCustomProperty'
-    MemberType = 'NoteProperty'
-    Value = 42
-}
-Update-TypeData @addTypeParams 
-```
+This could also be back-ported into the Windows implementation, which while immediately removing the remoting capability would increase the performance of the cmdlet by not requiring WMI accessors and allow for tighter integration between multiple platforms that this cmdlet could run on.
 
-This works, but feels a bit messy because of the need for a variable,
-when the hashtable could start on the same line as the command name.
+It would also serve as a framework for further enhancement, such as using SSHRemoting to enable the distributed approach to performing a distributed ping, while allowing for some built in governor mechanism to prevent abuse of the distributed nature.
 
-Another common use of splatting is to remove a specific parameter when splatting:
-
-```PowerShell
-$PSBoundParameters.Remove('SomeExtraParam')
-Command @PSBoundParameters
-```  
-
-This proposal suggesst a syntax that improves this scenario as well.
+Lastly, and most importantly, while the current Test-Connection cmdlet in the Windows invocation of PowerShell is limited, it is used extensively to check for the existence and responsiveness of remote systems.  By not providing a non-Windows specific implementation that is as close in parameter set and return types then existing code must be re-written to overcome this limitation, or adoption of PowerShell on non-Windows platforms may be barred by the lack of this simple but widely used functionality.
 
 ## Specification
 
-This RFC proposes a more generalized syntax for splatting to support:
-
-- Splatting general expressions (as opposed to simple variables)
-- Splatting in method invocations
-- Splatting in switch cases
-
-Today, the syntax for splatting is a sigil used on a variable name.
-This proposal expands the use of the sigil to be allowed on an expression.
-For example:
-
-```PowerShell
-# Existing usage:
-command @PSBoundParameters
-
-# Equivalent - but splatting an expression (the value of a variable) 
-command @$PSBoundParameters
-
-# Splat another expression - a hashtable
-Update-TypeData @@{
-    TypeName = 'MyCustomType'
-    MemberName = 'MyCustomProperty'
-    MemberType = 'NoteProperty'
-    Value = 42
-}
-```
-
-Note the two '@' characters in the hashtable example above.
-If the second '@' was omitted, the example would pass a hashtable (no splatting)
-in all versions of PowerShell, even V1, which means splatting without the second '@'
-would be a breaking change.
-
-We can use more general expressions as well:
-
-```PowerShell
-# Call a command that returns a hashtable or array to splat
-Get-ChildItem @$(Get-ChildItemArgs)
-
-# a method that returns a hashtable or array to splat
-Invoke-Something @$($obj.GetInvokerArgs())
-```
-
-### Relaxed splatting
-
-In some cases, it is desirable to splat only the arguments that are available,
-and ignore the others.
-We will call this relaxed splatting.
-For example:
-
-```PowerShell
-$myArgs = @{ Path = $pwd; ExtraStuff = 1234 }
-Get-ChildItem @$myArgs
-```
-
-The above example would fail with a "parameter not found" because of the 'ExtraStuff' key.
-Here is a possible syntax to allow the above without resulting in an error: 
-
-```PowerShell
-$myArgs = @{ Path = $pwd; ExtraStuff = 1234 }
-Get-ChildItem @?$myArgs
-```
-
-We can think of '@?' as the 'relaxed splatting' operator.
-If '@' is the splatting operator,
-adding the '?' is suggestive of being more permissive,
-much like the C# '?.' member access operator.
-
-### Splatting in method invocations
-
-Today, named arguments are only supported when calling commands,
-named arguments do not work when calling methods.
-PowerShell could adopt a C# like syntax to name arguments,
-but splatting provides a similar capability with some additional flexibility.
-The obvious syntax would mirror command invocation:
-
-```PowerShell
-# Splat a hashtable defined outside the method call
-$subStringArgs = @{startIndex = 2}
-$str.SubString(@$subStringArgs)
-
-# Splat a hashtable defined inline in the method call
-$str.SubString(@@{startIndex = 2; length=2})
-```
-
-Mixing splatting and positional arguments is supported.
-
-```PowerShell
-$str.SubString(2, @@{length=2})
-```
-
-A runtime check (or parse time if possible) is necessary to make sure an argument is not specified positionally
-and via splatting in the same invocation:
-
-```PowerShell
-# Must be an error, parse time or runtime, because startIndex
-# is specified positionally and via splatting.
-$subStringArgs = @{startIndex = 2}
-$str.SubString(2, @$subStringArgs)
-```
-
-Multiple splatted arguments are not allowed:
-
-```PowerShell
-# Error, multiple splatted arguments
-$str.SubString(@@{startIndex = 2}, @@{length=2})
-```
-
-The splatted argument must be last.
-
-```PowerShell
-# Error, splatted argument is not last
-$str.SubString(@@{length=2}, 2)
-```
-
-### Splatting in switch cases
-
-It can be awkward to match multiple conditions with a single switch statement.
-For example:
-
-```PowerShell
-switch ($color) {
-  { $_ -eq 'Red' -or $_ -eq 'Blue' -or $_ -eq 'Green' } { $true }
-  default { $false }
-}
-```
-
-With splatting, this can be simplified:
-
-```PowerShell
-switch ($color) {
-  @@('Red','Blue','Green') { $true }
-  default { $false }
-}
-```
-
-### Modifying hashtables for splatting
-
-Sometimes it is useful to provide a 'slice' of a hashtable,
-e.g. you want to remove or include specific keys.
-The Add/Remove methods on a hashtable work, but can be verbose.
-This proposal suggests overloading the '+' and '-' operators to provide a hashtable 'slice':
-
-```PowerShell
-Get-ChildItem @$($PSBoundParameters - 'Force') # Splat all parameters but 'Force'
-Get-ChildItem @$($PSBoundParameters - 'Force','WhatIf') # Splat all parameters but 'Force' and 'WhatIf'
-Get-ChildItem @$($PSBOundParameters + 'LiteralPath','Path') # Only splat 'LiteralPath' and 'Path'
-```
-
-Today, PowerShell supports "adding" two hashtables with the '+' operator,
-the result is a new hashtable with all of the key value pairs from both hashtables.
-It is an error for a key to be specified in both operands.
-
-This proposal adds semantics for adding and subtracting other values.
-If the value is enumerable, the effect is to treat each value in the collection as a key,
-otherwise the value is treated as a single key.
-The result is always a new hashtable,
-the left hashtable operand is unmodified.
-
-When using '+', the result will only include keys found in the right hand side.
-When using '-', the result will exclude all keys from the right hand side.
-
-In either case,
-it is not an error to specify a key in the right hand side operand that is not present in the left hand side.  
-
 ## Alternate Proposals and Considerations
 
-### Slicing operators
-
-The suggested use of '+' and '-' is perhaps surprising
-even though they correspond to Add and Remove, respectively.
-The actual operation is also similar to a union or intersection,
-so other operators should be considered, perhaps bitwise operators
-like '-bnot' and '-bor', or maybe new general purpose set operators. 
-
-### Postfix operator
-
-The use of a sigil is not always well received.
-This proposal nearly considers '@' a prefix unary operator,
-but it doesn't quite specify it as such.
+An alternate proposal is to not implement Test-Connection but rather build a new cmdlet from the ground up to replace Test-Connection entirely.  This would be similar in impact to not implementing Test-Connection cross-platform by requiring an unknown amount of code changes to occur before adoption on non-Windows platforms can occur.
 
-A postfix operator is another possiblity and would look less like a sigil.
-This idea was rejected because, when reading a command invocation from left to right,
-it's important to understand how a hash literal is to be used.
-The sigil makes it clear a hash literal is really specifying command arguments.
-Furthermore, the sigil simplifies the analysis required for good parameter completion,
-and does not require a complete expression to begin providing parameter name completion.
+This may also lend to those that require this functionality to create seperate code-bases and modules to fill the gap, leading to many custom solutions and suffering from the lack of standards and community collaboration.