function Get-SpecialFolderInfo - 2018.01.19.18.48.11

function Get-SpecialFolderInfo
    {
    #region >> CBH [Comment Based Help]

    <#
    .Synopsis
        Short description

    .DESCRIPTION
        Long description

    .EXAMPLE
        Example of how to use this cmdlet

    .EXAMPLE
        Another example of how to use this cmdlet

    .INPUTS
        Inputs to this cmdlet (if any)

    .OUTPUTS
        Output from this cmdlet (if any)

    .NOTES
        Version = 2018.01.19.18.48.11
    #>

    #endregion >> CBH [Comment Based Help]

    #region >> Parameters
    [CmdletBinding ()]

    Param
        (
        [Parameter (
            Position = 0)]
            [ValidateNotNullOrEmpty ()]
            [string[]]
            $SpecialFolderName = '*',

        [Parameter ()]
            [switch]
            $ReturnOnlyName,

        [Parameter ()]
            [switch]
            $ReturnOnlyPath

        )
    #endregion >> Parameters

    #region >> begin
    begin
        {
        Write-Verbose 'Building list of Special Folder names ...'
        $Full_SFN_List = [enum]::GetNames('System.Environment+SpecialFolder') |
            Sort-Object
        $NoPathFound = '--- No Path Found --'
        }
    #endregion >> begin

    #region >> process
    process
        {
        Write-Verbose 'Removing unwanted Special Folder names ...'
        $SFN_WorkingList = $Full_SFN_List -like $SpecialFolderName
        Write-Verbose ('    Found {0} matching items.' -f $SFN_WorkingList.Count)
        foreach ($SWL_Item in $SFN_WorkingList)
            {
            Write-Verbose ('    Processing [ {0} ] ...' -f $SWL_Item)
            $SFPath = [environment]::GetFolderPath($SWL_Item)
            # fill in blank path with $NoPathFound value
            $SFPath = ($NoPathFound, $SFPath)[[bool]$SFPath]
            $TempObject = [PSCustomObject]@{
                SpecialFolderName = $SWL_Item
                Path = $SFPath
                }

            if ($ReturnOnlyName -or $ReturnOnlyPath)
                {
                switch ($True)
                    {
                    $ReturnOnlyName
                        {
                        $TempObject.SpecialFolderName
                        break
                        }
                    $ReturnOnlyPath
                        {
                        $TempObject.Path
                        break
                        }
                    } # end >> switch ($True)
                }
                else
                {
                $TempObject
                } # end >> if ($ReturnOnlyName -or $ReturnOnlyPath)
            } # end >> foreach ($SWL_Item in $SFN_WorkingList)
        } # end >> process
    #endregion >> process

    #region >> end
    end
        {
        # nothing here for now
        }
    #endregion >> end

    } # end >> function Get-SpecialFolderInfo

#region >> testing parameters
Get-SpecialFolderInfo
#Get-SpecialFolderInfo 'mymusic'
#Get-SpecialFolderInfo -SpecialFolderName 'common*' -Verbose
#Get-SpecialFolderInfo -SpecialFolderName 'common*' -ReturnOnlyName
#Get-SpecialFolderInfo -SpecialFolderName 'mydocuments' -ReturnOnlyPath
#endregion >> testing parameters