PR Summary

Adds support for using named arguments when calling .NET methods.
For example:

[System.IO.Path]::GetFullPath(path: "test")

# Both of the below are the same
[string]::new('a', count: 20)
[string]::new(
    c: 'a',
    count: 20)
# aaaaaaaaaaaaaaaaaaaa

Through named args we can provide optional parameters without relying on the position or by specifying all preceding defaults:

Add-Type -TypeDefinition @'
using System;

public class TestClass
{
    public static string Method(string arg1, string default1 = "foo", string default2 = "bar")
    {
        return $"{arg1}-{default1}-{default2}";
    }
}
'@

[TestClass]::Method("test", default2: "other")
# test-foo-other

What is not in scope of this PR

• Support for named arguments for other method binders (COM) - COM is already piped in, other binder can work already if they support CallInfo.ArgumentNames.
• This only works for a .NET method (PSMethod)
  • PSScriptMethod could be expanded in the future to support passing in args through a parameter name
  • PSCodeMethod could be expanded in the future to support the same optional argument passing
  • Currently the names are just ignored for everything except PSMethod, this aligns to how Generics are handled for these method invocations
• PowerShell classes can use named arguments but optional values cannot be omitted
  • This is covered by a different issue Make methods in custom classes support optional parameters #9701
• Autocompletion support
  • Maybe @MartinGC94 can provide some hints/help there :)

PR Context

Issue to track this has closed due to no activity but it is still relevant #13307 and #7506 (sans splatting).

The changes here are done through

• New AST class LabeledExpressionAst which is only parsed on method invocations
• Argument names are provided to the binder through the CallInfo.ArgumentNames property
• Selecting the .NET overload now takes into account the caller supplied argument name

Assumptions Made

Named labels only support the simple name rules in PowerShell

A simple label supports the a subset of the rules as a C# identifier.
A quick test shows chars in the Nl, Pc, Mn, Mc, and Cf Unicode categories might be invalid.

Future work could be introduced to expand support these invalid chars through an escape char like \u0000, \U00000000, or the backtick ```u{}`` syntax but considering the rarity of these identifiers I'm not sure it's worth the effort.

Named labels cannot be following by unnamed/positional argument

When specifying a named argument, any subsequent args must also be named.

[System.IO.FileStream]::new(
    "file.txt",
    mode: 'Open',
    access: 'Read',
    share: 'ReadWrite')

While C# allows named arguments before positional arguments it is only if the name also aligns with the position.
Supporting such a scenario is not feasible in PowerShell as:

• CallInfo.ArgumentNames only allows names at the end of the arguments
• The way C# works is more compiler magic, using a dynamic class doesn't allow this syntax due to the above
• Supporting this in the parser just isn't feasible in PowerShell as both the method and overload selection is reliant on runtime values in the majority of cases

Named argument can be in any order but positional takes priority

Further to the above, the order of the named args do not matter but they will only apply after the positional arguments are checked.
For example the overload

public FileStream (string path, System.IO.FileMode mode, System.IO.FileAccess access, System.IO.FileShare share);

[System.IO.FileStream]::new(
    "file.txt",
    'Open',
    mode: 'Read',
    share: 'ReadWrite')

The above will not work because file.txt will be provided to path, Open will be set to mode, making the next named argument invalid because mode is already specified.

[System.IO.FileStream]::new(
    "file.txt",
    access: 'Read',
    share: 'ReadWrite',
    mode: 'Open')

Will work as the first positional argument is set to the path argument while the rest are all named and relate to the remaining args.

Named arguments are case insensitive

Edit: This was originally case sensitive but was changed in a recent commit base on feedback.

This follows the normal standard in PowerShell where most things are case insensitive allowing you to do

[System.IO.Path]::Combine(path1: 'foo', path2: 'bar')
[System.IO.Path]::Combine(Path1: 'foo', pAth2: 'bar')
...

This only applies to the .NET binder, COM will be case sensitive as well as any other customer binder that is used as the original case is preserved in the AST and it's up to the binder to decide on how to treat them.

Unnamed arguments in .NET cannot be used with a name

Edit: originally an automatic name based on the index like arg$idx was used but based on feedback the logic was removed.

It is possible to use reflection to define a method where each argument has no name.
Such method parameters need to be invoked positionally.

Name conflicts have the first one wins logic

Edit: originally a suffix like setup was used to ensure a unique name but based on feedback the logic was removed.

While rare it is possible to have a collision with the argument names when the method uses arguments that differ in case only, or the method was defined using MethodBuilder and reflection with the same name

These scenarios would be quite rare but it's still something that should be considered.
In the case of a conflict the named entries apply after the positional binding is done and from there the first match wins.

For example this C# signature shows 2 arguments that are the same when treated case insensitively

public static void Test(string value = "first", string Value = "second");

This is how the logic works based on this PR

Test()
# value - first
# Value - second

Test("customFirst", "customSecond")
# value - customFirst
# Value - customSecond

Test(value: "customFirst")
# value - customFirst
# Value - second

# due to the case insensitive match this binds to the first arg
Test(Value: "customFirst")
# value - customFirst
# Value - second

# As the positional binding will bind to the first value, the second
# value will bind to the next match which is the second arg
Test("customFirst", value: "customSecond")
# value - customFirst
# Value - customSecond

Things are more complex for reflection based methods where there can be more than 2 matches but the logic is the same.
The named argument will be bound to the first entry after positional binding is done.
Tests have been added for this to ensure no regression in the logic but it is a very rare edge case due to how hard it is to build such methods.

A named param argument must be set as an array if multiple values are specified

When specifying a value for a params argument through a named arg the value supplied can only be provided through the one argument value.
Just like a normal param specification this value can be a single value which is casted to the array at runtime or as the array itself.

[System.IO.Path]::Combine(paths: 'a')
[System.IO.Path]::Combine(paths: [string[]]@('a', 'b'))

This behaviour is the same as how a positional params argument can be supplied when only as one argument.

PR Checklist

• PR has a meaningful title
  • Use the present tense and imperative mood when describing your changes
• Summarized changes
• Make sure all .h, .cpp, .cs, .ps1 and .psm1 files have the correct copyright header
• This PR is ready to merge and is not Work in Progress.
  • If the PR is work in progress, please add the prefix WIP: or [ WIP ] to the beginning of the title (the WIP bot will keep its status check at Pending while the prefix is present) and remove the prefix when the PR is ready.
• Breaking changes
  • None
  • OR
  • Experimental feature(s) needed
    • Experimental feature name(s):
• User-facing changes
  • Not Applicable
  • OR
  • Documentation needed
    • Issue filed:
• Testing - New and feature
  • N/A or can only be tested interactively
  • OR
  • Make sure you've added a new test if existing tests do not effectively test the code changed
• Tooling
  • I have considered the user experience from a tooling perspective and don't believe tooling will be impacted.
  • OR
  • I have considered the user experience from a tooling perspective and opened an issue in the relevant tool repository. This may include:
    • Impact on PowerShell Editor Services which is used in the PowerShell extension for VSCode
      (which runs in a different PS Host).
      • Issue filed:
    • Impact on Completions (both in the console and in editors) - one of PowerShell's most powerful features.
      • Issue filed:
    • Impact on PSScriptAnalyzer (which provides linting & formatting in the editor extensions).
      • Issue filed:
    • Impact on EditorSyntax (which provides syntax highlighting with in VSCode, GitHub, and many other editors).
      • Issue filed: