Get-PSModulePath: Improve the command with Scope (#120)

dsccommunity · Jan 27, 2024 · cb72a3e · cb72a3e
1 parent b3e889e
commit cb72a3e
Show file tree

Hide file tree

Showing 3 changed files with 289 additions and 56 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- `Get-PSModulePath`
+  - Can now return the individual module path for different scopes when
+    using the parameter `-Scope`. If no parameter is specified the command
+    return the path for the scope CurrentUser.
+
+### Fixed
+
+- `Get-PSModulePath`
+  - Was using the wrong path separator on Linux and macOS.
+
 ## [0.17.0] - 2024-01-23
 
 ### Added

diff --git a/source/Public/Get-PSModulePath.ps1 b/source/Public/Get-PSModulePath.ps1
@@ -1,19 +1,46 @@
 <#
     .SYNOPSIS
-        Returns the environment variable PSModulePath from the specified target.
+        Returns the individual scope path or the environment variable PSModulePath
+        from one or more of the specified targets.
 
     .DESCRIPTION
-        Returns the environment variable PSModulePath from the specified target.
-        If more than one target is provided the return will contain all the
-        concatenation of all unique paths from the targets. If there are no paths
-        to return the command will return an empty string.
+        Returns the individual scope path or the environment variable PSModulePath
+        from one or more of the specified targets.
+
+        If more than one target is provided in the parameter FromTarget the return
+        value will contain the concatenation of all unique paths from the targets.
+        If there are no paths to return the command will return an empty string.
 
     .PARAMETER FromTarget
-        Specifies the target to get the PSModulePath from.
+        Specifies the environment target to get the PSModulePath from.
+
+    .PARAMETER Scope
+        Specifies the scope to get the individual module path of.
 
     .OUTPUTS
         System.String
 
+    .EXAMPLE
+        Get-PSModulePath
+
+        Returns the module path to the CurrentUser scope.
+
+    .EXAMPLE
+        Get-PSModulePath -Scope 'CurrentUser'
+
+        Returns the module path to the CurrentUser scope.
+
+    .EXAMPLE
+        Get-PSModulePath -Scope 'AllUsers'
+
+        Returns the module path to the AllUsers scope.
+
+    .EXAMPLE
+        Get-PSModulePath -Scope 'Builtin'
+
+        Returns the module path to the Builtin scope. This is the module path
+        containing the modules that ship with PowerShell.
+
     .EXAMPLE
         Get-PSModulePath -FromTarget 'Session'
 
@@ -31,49 +58,115 @@
 #>
 function Get-PSModulePath
 {
-    [CmdletBinding()]
+    [CmdletBinding(DefaultParameterSetName = 'Scope')]
     [OutputType([System.String])]
     param
     (
-        [Parameter(Mandatory = $true)]
+        [Parameter(Mandatory = $true, ParameterSetName = 'FromTarget')]
         [ValidateSet('Session', 'User', 'Machine')]
         [System.String[]]
-        $FromTarget
-    )
+        $FromTarget,
 
-    $modulePathSession = $modulePathUser = $modulePathMachine = $null
+        [Parameter(ParameterSetName = 'Scope')]
+        [ValidateSet('CurrentUser', 'AllUsers', 'Builtin')]
+        [System.String]
+        $Scope = 'CurrentUser'
+    )
 
-    <#
-        Get the environment variables from required targets. The value returned
-        is cast to System.String to convert $null values to empty string.
-    #>
-    switch ($FromTarget)
+    if ($PSCmdlet.ParameterSetName -eq 'FromTarget')
     {
-        'Session'
-        {
-            $modulePathSession = Get-EnvironmentVariable -Name 'PSModulePath'
-        }
+        $modulePathSession = $modulePathUser = $modulePathMachine = $null
 
-        'User'
+        <#
+            Get the environment variables from required targets. The value returned
+            is cast to System.String to convert $null values to empty string.
+        #>
+        switch ($FromTarget)
         {
-            $modulePathUser = Get-EnvironmentVariable -Name 'PSModulePath' -FromTarget 'User'
-        }
+            'Session'
+            {
+                $modulePathSession = Get-EnvironmentVariable -Name 'PSModulePath' -FromTarget 'Session'
 
-        'Machine'
-        {
-            $modulePathMachine = Get-EnvironmentVariable -Name 'PSModulePath' -FromTarget 'Machine'
+                continue
+            }
+
+            'User'
+            {
+                $modulePathUser = Get-EnvironmentVariable -Name 'PSModulePath' -FromTarget 'User'
+
+                continue
+            }
+
+            'Machine'
+            {
+                $modulePathMachine = Get-EnvironmentVariable -Name 'PSModulePath' -FromTarget 'Machine'
+
+                continue
+            }
         }
-    }
 
-    $modulePath = $modulePathSession, $modulePathUser, $modulePathMachine -join ';'
+        $modulePath = $modulePathSession, $modulePathUser, $modulePathMachine -join [System.IO.Path]::PathSeparator
 
-    $modulePathArray = $modulePath -split ';' |
-        Where-Object -FilterScript {
-            -not [System.String]::IsNullOrEmpty($_)
-        } |
-        Sort-Object -Unique
+        $modulePathArray = $modulePath -split [System.IO.Path]::PathSeparator |
+            Where-Object -FilterScript {
+                -not [System.String]::IsNullOrEmpty($_)
+            } |
+            Sort-Object -Unique
+
+        $modulePath = $modulePathArray -join [System.IO.Path]::PathSeparator
+    }
 
-    $modulePath = $modulePathArray -join ';'
+    if ($PSCmdlet.ParameterSetName -eq 'Scope')
+    {
+        switch ($Scope)
+        {
+            'CurrentUser'
+            {
+                $modulePath = if ($IsLinux -or $IsMacOS)
+                {
+                    # Must be correct case on case-sensitive file systems.
+                    Join-Path -Path $HOME -ChildPath '.local/share/powershell/Modules'
+                }
+                else
+                {
+                    $documentsFolder = [Environment]::GetFolderPath('MyDocuments')
+
+                    if ($IsCoreCLR)
+                    {
+                        Join-Path -Path $documentsFolder -ChildPath 'PowerShell/Modules'
+                    }
+                    else
+                    {
+                        Join-Path -Path $documentsFolder -ChildPath 'WindowsPowerShell/Modules'
+                    }
+                }
+
+                break
+            }
+
+            'AllUsers'
+            {
+                $modulePath = if ($IsLinux -or $IsMacOS)
+                {
+                    '/usr/local/share/powershell/Modules'
+                }
+                else
+                {
+                    Join-Path -Path $env:ProgramFiles -ChildPath 'WindowsPowerShell/Modules'
+                }
+
+                break
+            }
+
+            'BuiltIn'
+            {
+                # cSPell: ignore PSHOME
+                $modulePath = Join-Path -Path $PSHOME -ChildPath 'Modules'
+
+                break
+            }
+        }
+    }
 
     return $modulePath
 }