function Get-SpecialFolderInfo - 2018.01.20.15.54.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.20.15.54.11
        #>

        #endregion >> CBH [Comment Based Help]

        #region >> Parameters
        [CmdletBinding ()]

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

            [Parameter (
                Position = 1)]
                [ValidateSet ('All', 'NameOnly', 'PathOnly')]
                [string]
                $WhatToReturn = 'All'


            )
        #endregion >> Parameters

        #region >> begin
        begin
            {
            Write-Verbose 'Building list of Special Folder names ...'
            $Full_SFN_List = [enum]::GetNames('System.Environment+SpecialFolder') |
                Sort-Object
            Write-Verbose ('    {0} Special Folder names found.' -f $Full_SFN_List.Count)

            $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
                    }

                switch ($WhatToReturn)
                    {
                    'All'
                        {
                        $TempObject
                        break
                        }
                    'NameOnly'
                        {
                        $TempObject.SpecialFolderName
                        break
                        }
                    'PathOnly'
                        {
                        $TempObject.Path
                        break
                        }
                    } # end >> switch ($WhatToReturn)
                } # 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 -Verbose

    #Get-SpecialFolderInfo 'mymusic'
    #Get-SpecialFolderInfo 'mymusic' -WhatToReturn PathOnly

    #Get-SpecialFolderInfo -SpecialFolderName 'common*' -Verbose
    #Get-SpecialFolderInfo -SpecialFolderName 'common*'

    Get-SpecialFolderInfo -SpecialFolderName 'mydocuments' -WhatToReturn All -Verbose
    #Get-SpecialFolderInfo -SpecialFolderName '*music*' -WhatToReturn NameOnly
    #Get-SpecialFolderInfo -SpecialFolderName '*video*' -WhatToReturn PathOnly

    #endregion >> testing parameters