ConvertFrom-PowerShellDataFile

1.0.0

ConvertFrom-PowerShellDataFile.psm1

#
# ConvertFrom-PowerShellDataFile
# Version: 1.0.0
# Author: Nathaniel Walis Praytor
#

function ConvertFrom-PowerShellDataFile {
    <#
        .SYNOPSIS
            Generates a Hashtable from a specified PowerShell Data File.

        .DESCRIPTION
            Generates a Hashtable from the data stored within a specified valid PowerShell Data File (*.psd1 file), which is then stored within a Variable sharing its name with the source *.psd1 file's BaseName. (Example: If the Filename is 'Data.psd1', then the Hashtable generated from its contents can be referenced using the Variable: '$Data', and individual Keys referenced via dot notation: '$Data.Key1.Key2' etc.)

        .PARAMETER FilePath
            Specifies the Path to a PowerShell Data File.

        .PARAMETER RequireValidation
            When specified, the target *.psd1 file MUST be a VALID Module Manifest. (Uses Test-ModuleManifest to Validate contents of the Manifest.) If 'Test-ModuleManifest' returns a value of $false (File failed to pass Validation) then any issues discovered are highlighted and displayed to the User.

        .EXAMPLE
            PS C:\> ConvertFrom-PowerShellDataFile -FilePath 'C:\test\MyModule\PSScriptAnalyzerSettings.psd1'

        .EXAMPLE
            PS C:\> ConvertFrom-PowerShellDataFile -FilePath 'C:\test\MyModule\MyModule.psd1' -RequireValidation

        .INPUTS
            @param 'FilePath' - System.IO.Path

        .OUTPUTS
            '$<FileBaseName>' - 'System.Collections.Hashtable'

        .LINK
            https://github.com/SupernautFX/SFX.PoshUtilities.DataFileTools

        .NOTES
            Filename: 'ConvertFrom-PowerShellDataFile.psm1'
            Version: 1.0.0
            Author: Nathaniel Wallis Praytor

        .FORWARDHELPTARGETNAME ConvertFrom-PowerShellDataFile
        .FORWARDHELPCATEGORY Function
        .EXTERNALHELP Convert-PowerShellDataFile.psm1-help.xml

    #>

    [CmdletBinding(SupportsShouldProcess)]
    [OutputType([System.Collections.Hashtable])]
    param(
        [Parameter(
            Mandatory,
            Position = 0
        )]
        [string]$FilePath,

        [switch]$RequireValidation
    )

    BEGIN {
        if ($RequireValidation.IsPresent) {
            Try {
                Test-ModuleManifest $FilePath
                Write-Verbose "Success! PowerShell Data File passed Validation testing! This file is a VALID MODULE MANIFEST."
            } Catch {
                Write-Error $_
            }
        }
    }

    PROCESS {
        Try {
            $Manifest = New-Object hashtable
            $Filename = Split-Path $FilePath -Leaf
            $BaseName = $Filename.Split('.')[0]
            $Manifest.BaseName = (Import-PowerShellDataFile -Path $FilePath)
            New-Variable -Name $BaseName -Value $Manifest
        } Catch {
            Write-Error $_ -ErrorAction Stop
        }

        if ($ReturnValue.IsPresent) {
            return $Manifest.$ReturnValue
        }
    }

    END {
        Write-Information "New Hashtable created: `$$BaseName containing data stored in PowerShell Data File: $Filename"
    }
}

Export-ModuleMember -Function ConvertFrom-PowerShellDataFile