Refactor Expand-MemberExpression Function (#21)

* Move sub-function ToPascalCase to utility class

Move the ToPascalCase outside of the ConvertTo-FunctionDefinition
function and into a shared utility class for reuse.

* Refactor Expand-MemberExpression

This change refactors Expand-MemberExpression significantly.

- Breaking Change - Remove TemplateName and NoParameterNameComments
  parameters

- Remove the overly complicated logic for targeting a specific overload
  and replace it with a QuickOpen choice prompt

- Change expression generation to use StringBuilder instead of
  PSStringTemplate. This is the first step in removing the dependancy.

- Improve logic for determining the Type.Get* overload required to
  resolve a non-public member

- Fix a variety of scenarios where invalid expressions would be
  generated

- Add ShowOnThrow parameter to internal function GetAncestorOrThrow

- Fix an issue where detection of shortest resolvable type name would
  use the TypeResolutionScope, resulting in invalid type expressions

* Update help to reflect changes

Author: SeeminglyScience

docs/en-US/EditorServicesCommandSuite.md

@@ -52,7 +52,7 @@ The Expand-Expression function replaces text at a specified range with it's outp
 
 ### [Expand-MemberExpression](Expand-MemberExpression.md)
 
-The Expand-MemberExpression function creates an expression for the closest MemberExpressionAst to the cursor in the current editor context. This is mainly to assist with creating expressions to access private members of .NET classes through reflection.
+The Expand-MemberExpression function expands member expressions to a more explicit statement.
 
 ### [Expand-TypeImplementation](Expand-TypeImplementation.md)
 

docs/en-US/Expand-MemberExpression.md

@@ -8,7 +8,7 @@ schema: 2.0.0
 
 ## SYNOPSIS
 
-Builds an expression for accessing or invoking a member through reflection.
+Expands a member expression into a more explicit form.
 
 ## SYNTAX
 
@@ -18,44 +18,115 @@ Expand-MemberExpression [[-Ast] <Ast>] [-TemplateName <String>] [-NoParameterNam
 
 ## DESCRIPTION
 
-The Expand-MemberExpression function creates an expression for the closest MemberExpressionAst to the cursor in the current editor context. This is mainly to assist with creating expressions to access private members of .NET classes through reflection.
+The Expand-MemberExpression function expands member expressions to a more explicit statement. This
+function has two main purposes.
 
-The expression is created using string templates. There are templates for several ways of accessing members including InvokeMember, GetProperty/GetValue, and a more verbose GetMethod/Invoke. If using the GetMethod/Invoke template it will automatically build type expressions for the "types" argument including nonpublic and generic types. If a template is not specified, this function will attempt to determine the most fitting template. If you have issues invoking a method with the default, try the VerboseInvokeMethod template. This function currently works on member expressions attached to the following:
+* Add parameter name comments (e.g. <# parameterName: #>) to method invocation arguments
 
-1. Type literal expressions (including invalid expressions with non public types)
+* Invokable expressions that target non-public class members using reflection
 
-2. Variable expressions where the variable exists within a currently existing scope.
+As an editor command, this function will expand the AST closest to the current cursor location
+if applicable.
 
-3. Any other scenario where standard completion works.
+## EXAMPLES
 
-4. Any number of nested member expressions where one of the above is true at some point in the chain.
+### -------------------------- EXAMPLE 1 --------------------------
 
+```powershell
+'[ConsoleKeyInfo]::new' | Out-File .\example1.ps1
+psedit .\example1.ps1
+$psEditor.GetEditorContext().SetSelection(1, 20, 1, 20)
+Expand-MemberExpression
+$psEditor.GetEditorContext().CurrentFile.GetText()
 
-Additionally chains may break if a member returns a type that is too generic like System.Object or a vague interface.
+# [System.ConsoleKeyInfo]::new(
+#    <# keyChar: #> $keyChar,
+#    <# key: #> $key,
+#    <# shift: #> $shift,
+#    <# alt: #> $alt,
+#    <# control: #> $control)
 
-## EXAMPLES
+```
 
-### -------------------------- EXAMPLE 1 --------------------------
+* Creates a new file with an unfinished member expression
+* Opens it in the editor
+* Sets the cursor within the member expression
+* Invokes Expand-MemberExpression
+* Returns the new expression
+
+The new expression is expanded to include arguments and parameter name comments for every parameter.
+
+### -------------------------- EXAMPLE 2 --------------------------
 
 ```powershell
+'[sessionstatescope]::createfunction' | Out-File .\example2.ps1
+psedit .\example2.ps1
+$psEditor.GetEditorContext().SetSelection(1, 30, 1, 30)
 Expand-MemberExpression
+$psEditor.GetEditorContext().CurrentFile.GetText()
+
+# $createFunction = [ref].Assembly.GetType('System.Management.Automation.SessionStateScope').
+#     GetMethod('CreateFunction', [System.Reflection.BindingFlags]'Static, NonPublic').
+#     Invoke($null, @(
+#         <# name: #> $name,
+#         <# function: #> $function,
+#         <# originalFunction: #> $originalFunction,
+#         <# options: #> $options,
+#         <# context: #> $context,
+#         <# helpFile: #> $helpFile))
+
 ```
 
-Expands the member expression closest to the cursor in the current editor context using an automatically determined template.
+* Creates a new file with an unfinished member expression
+* Opens it in the editor
+* Sets the cursor within the member expression
+* Invokes Expand-MemberExpression
+* Returns the new expression
 
-### -------------------------- EXAMPLE 2 --------------------------
+The new expression generated will resolve the non-public type and invoke the non-public method.
+
+### -------------------------- EXAMPLE 3 --------------------------
 
 ```powershell
-Expand-MemberExpression -Template VerboseInvokeMethod
+'$ExecutionContext.SessionState.Internal.RemoveVariableAtScope' | Out-File .\example3.ps1
+psedit .\example3.ps1
+$psEditor.GetEditorContext().SetSelection(1, 60, 1, 60)
+Expand-MemberExpression
+# Manually select the last overload in the menu opened in the editor.
+$psEditor.GetEditorContext().CurrentFile.GetText()
+
+# $internal = $ExecutionContext.SessionState.GetType().
+#     GetProperty('Internal', [System.Reflection.BindingFlags]'Instance, NonPublic').
+#     GetValue($ExecutionContext.SessionState)
+#
+# $removeVariableAtScope = $internal.GetType().
+#     GetMethod(
+#         <# name: #> 'RemoveVariableAtScope',
+#         <# bindingAttr: #> [System.Reflection.BindingFlags]'Instance, NonPublic',
+#         <# binder: #> $null,
+#         <# types: #> @([string], [string], [bool]),
+#         <# modifiers: #> 3).
+#     Invoke($internal, @(
+#         <# name: #> $name,
+#         <# scopeID: #> $scopeID,
+#         <# force: #> $force))
 ```
 
-Expands the member expression closest to the cursor in the current editor context using the VerboseInvokeMethod template.
+* Creates a new file with an unfinished member expression
+* Opens it in the editor
+* Sets the cursor within the member expression
+* Invokes Expand-MemberExpression
+* Returns the new expression
+
+This example shows that an expression will be generated for each non-public member in the chain. It
+also demonstrates the ability to select an overload from a menu in the editor and the more alternate
+syntax generated for harder to resolve methods.
 
 ## PARAMETERS
 
 ### -Ast
 
-Specifies the member expression ast (or child of) to expand.
+Specifies the AST of the member expression to expand.
 
 ```yaml
 Type: Ast
@@ -69,38 +140,6 @@ Accept pipeline input: True (ByPropertyName, ByValue)
 Accept wildcard characters: False
 ```
 
-### -TemplateName
-
-A template is automatically chosen based on member type and visibility.  You can use this parameter to force the use of a specific template.
-
-```yaml
-Type: String
-Parameter Sets: (All)
-Aliases:
-
-Required: False
-Position: Named
-Default value: None
-Accept pipeline input: False
-Accept wildcard characters: False
-```
-
-### -NoParameterNameComments
-
-By default expanded methods will have a comment with the parameter name on each line. (e.g. `<# paramName: #> $paramName,`) If you specify this parameter it will be omitted.
-
-```yaml
-Type: SwitchParameter
-Parameter Sets: (All)
-Aliases:
-
-Required: False
-Position: Named
-Default value: False
-Accept pipeline input: False
-Accept wildcard characters: False
-```
-
 ### CommonParameters
 
 This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216).
@@ -115,5 +154,16 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable
 
 ## NOTES
 
-## RELATED LINKS
+* When this function is building reflection statements, it will automatically choose the simpliest form
+  of the Type.Get* methods that will resolve the target member.
+
+* Member resolution is currently only possible in the following scenarios:
+  * Type literal expressions, including invalid expressions with non public types like [localpipeline]
+  * Variable expressions where the variable exists within a currently existing scope
+  * Any other scenario where standard completion works
+  * Any number of nested member expressions where one of the above is true at some point in the chain
 
+* Member resolution may break in member chains if a member returns a type that is too generic like
+  System.Object or IEnumerable
+
+## RELATED LINKS

module/Classes/Expressions.ps1

@@ -1,6 +1,5 @@
-using namespace System.Reflection
-using namespace System.Collections.ObjectModel
-using namespace System.Management.Automation.Language
+using namespace System.Text
+using namespace Microsoft.PowerShell
 
 class TypeExpressionHelper {
     [type] $Type;
@@ -33,11 +32,16 @@ class TypeExpressionHelper {
         }
     }
     hidden [string] CreateProxy () {
-        $builder = [System.Text.StringBuilder]::new('[')
+        $builder = [StringBuilder]::new('[')
         $assembly = $this.Type.Assembly
 
         # First check if there are any type accelerators in the same assembly.
-        $choices = $this.GetAccelerators().GetEnumerator().Where{ $PSItem.Value.Assembly -eq $assembly }.Key
+        $choices = [ref].
+            Assembly.
+            GetType('System.Management.Automation.TypeAccelerators')::
+            Get.
+            GetEnumerator().
+            Where{ $PSItem.Value.Assembly -eq $assembly }.Key
 
         if (-not $choices) {
             # Then as a last resort pull every type from the assembly. This takes a extra second or
@@ -64,7 +68,7 @@ class TypeExpressionHelper {
         }
     }
     hidden [string] CreateLiteral () {
-        $builder = [System.Text.StringBuilder]::new()
+        $builder = [StringBuilder]::new()
         # If we are building the type name as a generic type argument in a type literal we don't want
         # to enclose it with brackets.
         if ($this.encloseWithBrackets) { $builder.Append('[') }
@@ -77,13 +81,14 @@ class TypeExpressionHelper {
                 Append(']')
         }
         else {
-            $name = $this.GetAccelerators().
-                GetEnumerator().
-                Where{ $PSItem.Value -eq $this.Type }.
-                Key |
-                Sort-Object Length
+            $name = [string]::Empty
+            # Try to resolve the type name with a code method that won't take this script's
+            # using statements into account. This also handles type accelerators for us.
+            $resolvableName = [ToStringCodeMethods]::Type($this.Type)
+            if ($resolvableName -as [type]) {
+                $name = $resolvableName
+            }
 
-            if (-not $name) { $name = ($this.Type.Name -as [type]).Name }
             if (-not $name) { $name = $this.Type.ToString() }
 
             if ($name.Count -gt 1) { $name = $name[0] }
@@ -105,59 +110,4 @@ class TypeExpressionHelper {
             [TypeExpressionHelper]::Create($PSItem, $enclose)
         } -join ', '
     }
-    hidden [System.Collections.Generic.Dictionary[string, type]] GetAccelerators () {
-       return [ref].Assembly.GetType('System.Management.Automation.TypeAccelerators')::Get
-    }
-}
-
-class ExtendedMemberExpressionAst : MemberExpressionAst {
-    [type] $InferredType;
-    [MemberInfo] $InferredMember;
-    [BindingFlags] $BindingFlags;
-    [ReadOnlyCollection[ExpressionAst]] $Arguments;
-
-    ExtendedMemberExpressionAst ([IScriptExtent] $extent,
-                                 [ExpressionAst] $expression,
-                                 [CommandElementAst] $member,
-                                 [bool] $static,
-                                 [ReadOnlyCollection[ExpressionAst]] $arguments) :
-                                 base($extent, $expression, $member, $static) {
-
-        try {
-            $this.Arguments      = $arguments
-            $this.InferredMember = GetInferredMember -Ast $this
-            $this.InferredType   = ($this.InferredMember.ReturnType,
-                                    $this.InferredMember.PropertyType,
-                                    $this.InferredMember.FieldType).
-                                    Where({ $PSItem }, 'First')[0]
-
-            $this.BindingFlags   = $this.InferredMember.GetType().
-                GetProperty('BindingFlags', [BindingFlags]'Instance, NonPublic').
-                GetValue($this.InferredMember)
-        } catch {
-            $this.InferredType = [object]
-        }
-    }
-    static [ExtendedMemberExpressionAst] op_Implicit ([MemberExpressionAst] $ast) {
-
-        $expression = $ast.Expression.Copy()
-        if ($expression -is [MemberExpressionAst]) {
-            $expression = [ExtendedMemberExpressionAst]$expression
-        }
-        $newAst = [ExtendedMemberExpressionAst]::new(
-            $ast.Extent,
-            $expression,
-            $ast.Member.Copy(),
-            $ast.Static,
-            $ast.Arguments
-        )
-
-        if ($ast.Parent) {
-            $ast.Parent.GetType().
-                GetMethod('SetParent', [BindingFlags]'Instance, NonPublic').
-                Invoke($ast.Parent, $newAst)
-        }
-
-        return $newAst
-    }
 }