feat: Use-Module ( Fixes #1130 )

Author: James Brundage

Commands/Module/Use-Module.ps.ps1

@@ -0,0 +1,71 @@
+[ValidatePattern('Use[-\.]Module')]
+param()
+function Use-Module
+{
+    <#
+    .SYNOPSIS
+        Uses a module.
+    .DESCRIPTION
+        Uses a module.  
+        
+        This can either:
+        
+        * Invoke a ScriptBlock in the module's context
+        * Run a module's `Use` function, if present
+        * Call a module's `Use` method, if present
+
+        In all cases, the script block should be run in the module's context, using dot-sourcing.
+    .EXAMPLE
+        Get-Module PipeScript | Use-Module -ScriptBlock { $myInvocation.MyCommand.ScriptBlock.Module }    
+    #>    
+    [Alias('Use.Module','Module.Use')]
+    param(
+    # The name of the module
+    [vfp()]
+    [Alias('ModuleName')]
+    [string]
+    $Name,
+
+    # The script block to use.
+    [ScriptBlock]
+    $ScriptBlock = {},
+
+    [Parameter(ValueFromRemainingArguments)]
+    [Alias('Arguments','Args')]
+    [PSObject[]]
+    $ArgumentList,
+
+    [Parameter(ValueFromPipelineByPropertyName)]
+    [Collection.IDictionary]
+    $Parameter
+    )
+
+    process {
+        # Get the piped in object
+        $pipedIn = $_
+        # 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
+        }
+
+        
+        return if -not $moduleContext
+
+        if ($ArgumentList) {
+            if ($Parameter) {
+                . $moduleContext $ScriptBlock @ArgumentList @Parameter
+            } else {
+                . $moduleContext $ScriptBlock @ArgumentList
+            }
+        } elseif ($Parameter) {
+            . $moduleContext $ScriptBlock @Parameter
+        } else {
+            . $moduleContext $ScriptBlock
+        }                            
+    }
+}