PR Summary

Adds support for assigning ITuple types (System.Tuple, System.ValueTuple) and types with Deconstruct methods (DictionaryEntry, KeyValuePair<,>, etc.) to multiple variables using array assignment syntax.

Fixes #7471

PR Context

Problem

When assigning a Tuple, ValueTuple, DictionaryEntry, or KeyValuePair to multiple variables, PowerShell previously assigned the entire object to the first variable instead of deconstructing it:

$tuple = [Tuple]::Create(1, 2)
$a, $b = $tuple
# Result: $a contains the entire tuple, $b is $null

$de = [System.Collections.DictionaryEntry]::new("key", "value")
$k, $v = $de
# Result: $k contains the entire DictionaryEntry, $v is $null

This prevented convenient use of APIs that return tuples (like [Math]::DivRem()) and made hashtable enumeration cumbersome.

Solution

Added special handling in PSGetMemberBinder for two cases:

1. ITuple types - Detected via System.Runtime.CompilerServices.ITuple interface, elements extracted using the indexer
2. Deconstruct methods - Types with a public Deconstruct method with all out parameters (like DictionaryEntry and KeyValuePair<,>)

Both handle three scenarios: exact match, fewer elements than variables (fills with null), more elements than variables (remaining go to last variable as array).

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. If this PR is a work in progress, please open this as a Draft Pull Request and mark it as Ready to Review when it is ready to merge.
• Breaking changes
  • None
• 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

Changes Made

1. Compiler.cs (+18 lines)

• Added cached reflection references for ITuple.Length property and ITuple.get_Item method
• Added references for EnumerableOps.GetTupleSlice, GetDeconstructMethod, InvokeDeconstruct, and GetDeconstructSlice methods

2. Binders.cs (+120 lines)

• Added ITuple detection and handling in PSGetMemberBinder.FallbackGetMember
• Added Deconstruct method detection and handling
• Implemented three-case logic for both: exact element count, fewer elements, more elements

3. MiscOps.cs (+97 lines)

• Added GetTupleSlice - extracts remaining elements from ITuple
• Added GetDeconstructMethod - finds Deconstruct method on a type
• Added InvokeDeconstruct - invokes Deconstruct and returns values
• Added GetDeconstructSlice - extracts remaining values from already-deconstructed array (avoids calling Deconstruct multiple times)

4. Indexer.Tests.ps1 (+136 lines)

• Added 13 comprehensive tests covering ITuple and Deconstruct scenarios

Total: 4 files changed, 371 insertions(+)

Behavior Examples

Tuple assignment

$tuple = [Tuple]::Create(1, 2)
$a, $b = $tuple

DictionaryEntry assignment

$de = [System.Collections.DictionaryEntry]::new("key", "value")
$k, $v = $de

KeyValuePair assignment

$kvp = [System.Collections.Generic.KeyValuePair[string,int]]::new("count", 42)
$k, $v = $kvp

Hashtable enumeration

$ht = @{ name = "test" }
foreach ($entry in $ht.GetEnumerator()) {
    $key, $value = $entry
}

Math.DivRem

$quotient, $remainder = [Math]::DivRem(17, 5)

Testing

Test Cases (13 new tests)

ITuple tests:

1. Tuple with exact element count (2 elements)
2. Single element Tuple (1 element) - boundary
3. Tuple with 7 elements - boundary (max without nesting)
4. Tuple with 8 elements - boundary (uses internal Rest nesting)
5. ValueTuple with 3 elements
6. More elements than variables (overflow to last)
7. Fewer elements than variables (null for extras)
8. Math.DivRem practical example

Deconstruct tests:
9. DictionaryEntry assignment
10. KeyValuePair assignment
11. DictionaryEntry with more variables than elements
12. Hashtable enumeration practical example
13. Deconstruct method called only once (verifies no redundant calls)

Test Results

Implementation Details

Supported Types

Via ITuple interface:

• System.Tuple<> (1-8 elements)
• System.ValueTuple<> (1-8 elements)
• Any type implementing System.Runtime.CompilerServices.ITuple

Via Deconstruct method:

• System.Collections.DictionaryEntry
• System.Collections.Generic.KeyValuePair<,>
• Any type with a public Deconstruct(out T1, out T2, ...) method

Design Decisions

1. ITuple first, then Deconstruct - ITuple is checked first as it's more specific; Deconstruct is a fallback for types like DictionaryEntry
2. Length-based restriction for ITuple - Dynamic binding includes tuple length in restrictions for correct caching
3. Instance Deconstruct only - Extension methods are not supported (consistent with PowerShell's general behavior)
4. Consistent overflow/underflow behavior - Follows same patterns as array/IList assignment
5. Single Deconstruct invocation - GetDeconstructSlice takes the already-deconstructed array to avoid calling Deconstruct() multiple times