feat: Use-Module ( Fixes #1130 )

Fixing parameters and fulfilling promise

Author: James Brundage

Commands/Module/Use-Module.ps.ps1

@@ -10,7 +10,9 @@ function Use-Module
         
         This can either:
         
-        * Invoke a ScriptBlock in the module's context
+        * If present, run a module's `Use` function, method, or script property.
+        * Otherwise, run a script block in the module's context.
+        
         * Run a module's `Use` function, if present
         * Call a module's `Use` method, if present
 
@@ -30,13 +32,16 @@ function Use-Module
     [ScriptBlock]
     $ScriptBlock = {},
 
+    # The list of arguments to pass to the script block.
     [Parameter(ValueFromRemainingArguments)]
     [Alias('Arguments','Args')]
     [PSObject[]]
     $ArgumentList,
 
+    # Any named parameters to pass to the script block.
     [Parameter(ValueFromPipelineByPropertyName)]
-    [Collection.IDictionary]
+    [Alias('Parameters')]
+    [Collections.IDictionary]
     $Parameter
     )
 
@@ -46,26 +51,67 @@ function Use-Module
         # If we have no name, return
         return if -not $name
 
-        $moduleContext = if ($pipedIn -is [Management.Automation.PSModuleInfo]) {
-            $name = $pipedIn
-            $pipedIn
-        } else {
-            Get-Module $Name | Select-Object -First 1
-        }
+        # Get the module context 
+        $moduleContext = 
+            # (if it was already piped in, we already have it)
+            if ($pipedIn -is [Management.Automation.PSModuleInfo]) {
+                $name = $pipedIn
+                $pipedIn
+            } else {
+                Get-Module $Name | Select-Object -First 1
+            }
 
-        
+        # Return if there is no module context.
         return if -not $moduleContext
+        
+        # Get the use commands.
+        $useCommands = $moduleContent.ExportedCommands[@(
+            "Use-$($moduleContext.Name)",
+            "Use.$($moduleContext.Name)"
+            "$($moduleContext.Name).Use"
+        )]
+
+        # Get the use method.
+        $useMethod = $moduleContext.psobject.methods["Use"]
+
+        $ToRun = 
+            # If we have a method            
+            if ($useMethod) 
+            {
+                $useMethod.Script # use it
+                # (and pass the script block as an argument)
+                $ArgumentList = @($ScriptBlock) + @($ArgumentList)
+            }
+            # If we have any use commands, use the first one
+            elseif ($useCommands -ne $null)
+            {
+                @($useCommands -ne $null)[0]
+                # (and pass the script block as an argument)
+                $ArgumentList = @($ScriptBlock) + @($ArgumentList)
+            } 
+            else             
+            {
+                # Otherwise, use the script block
+                $ScriptBlock
+            }
+
+        # We're running in the module context, and now we know what we want `$toRun`.
+        $runningIn = $moduleContext
 
+        # The rest of the code is tedium.
+        # If there were arguments and parameters, pass them both with splatting.
         if ($ArgumentList) {
             if ($Parameter) {
-                . $moduleContext $ScriptBlock @ArgumentList @Parameter
+                . $runningIn $ToRun @ArgumentList @Parameter
             } else {
-                . $moduleContext $ScriptBlock @ArgumentList
+                . $runningIn $ToRun @ArgumentList
             }
         } elseif ($Parameter) {
-            . $moduleContext $ScriptBlock @Parameter
+            # If there were only parameters, pass them with splatting.
+            . $runningIn $ToRun @Parameter
         } else {
-            . $moduleContext $ScriptBlock
+            # If there were no arguments or parameters, just run the script block.
+            . $runningIn $ToRun
         }                            
     }
 }