🚀 [Feature]: Add functions Import-Hashtable and Export-Hashtable (#7)

## Description

This pull request introduces two new functions and updates to existing
functions for handling hashtables in PowerShell scripts.

### New Functions

* `Export-Hashtable`: A new function to export a hashtable to a
specified file in PSD1, PS1, or JSON format.
* `Import-Hashtable`: A new function to import a hashtable from a
specified file, supporting PSD1, PS1, and JSON formats.

### Tests

* Added tests for the new `Export-Hashtable` and `Import-Hashtable`
functions to verify their functionality with different file formats.

## Type of change

<!-- Use the check-boxes [x] on the options that are relevant. -->

- [ ] 📖 [Docs]
- [ ] 🪲 [Fix]
- [ ] 🩹 [Patch]
- [ ] ⚠️ [Security fix]
- [x] 🚀 [Feature]
- [ ] 🌟 [Breaking change]

## Checklist

<!-- Use the check-boxes [x] on the options that are relevant. -->

- [x] I have performed a self-review of my own code
- [x] I have commented my code, particularly in hard-to-understand areas

Author: MariusStorhaug

src/functions/public/ConvertTo-HashTable.ps1

@@ -49,7 +49,7 @@
         converting complex nested structures recursively.
 
         .LINK
-        https://psmodule.io/ConvertTo/Functions/ConvertTo-Hashtable
+        https://psmodule.io/Hashtable/Functions/ConvertTo-Hashtable
     #>
     [OutputType([hashtable])]
     [CmdletBinding()]

src/functions/public/Export-Hashtable.ps1

@@ -0,0 +1,89 @@
+filter Export-Hashtable {
+    <#
+        .SYNOPSIS
+        Exports a hashtable to a specified file in PSD1, PS1, or JSON format.
+
+        .DESCRIPTION
+        This function takes a hashtable and exports it to a file in one of the supported formats: PSD1, PS1, or JSON.
+        The format is determined based on the file extension provided in the Path parameter. If the extension is not
+        recognized, the function throws an error. This function supports pipeline input.
+
+        .EXAMPLE
+        $myHashtable = @{ Key = 'Value'; Number = 42 }
+        $myHashtable | Export-Hashtable -Path 'C:\config.psd1'
+
+        Exports the hashtable to a PSD1 file.
+
+        .EXAMPLE
+        $myHashtable = @{ Key = 'Value'; Number = 42 }
+        Export-Hashtable -Hashtable $myHashtable -Path 'C:\script.ps1'
+
+        Exports the hashtable as a PowerShell script that returns the hashtable when executed.
+
+        .EXAMPLE
+        $myHashtable = @{ Key = 'Value'; Number = 42 }
+        Export-Hashtable -Hashtable $myHashtable -Path 'C:\data.json'
+
+        Exports the hashtable as a JSON file.
+
+        .OUTPUTS
+        void
+
+        .NOTES
+        This function does not return an output. It writes the exported data to a file.
+
+        .LINK
+        https://psmodule.io/Export/Functions/Export-Hashtable/
+    #>
+    [OutputType([void])]
+    [CmdletBinding()]
+    param(
+        # The hashtable to export.
+        [Parameter(
+            Mandatory,
+            ValueFromPipeline,
+            ValueFromPipelineByPropertyName
+        )]
+        [hashtable] $Hashtable,
+
+        # The file path where the hashtable will be exported.
+        [Parameter(Mandatory)]
+        [string] $Path
+    )
+
+    # Determine file extension and select export format.
+    $extension = [System.IO.Path]::GetExtension($Path).ToLower()
+
+    switch ($extension) {
+        '.psd1' {
+            try {
+                # Use Format-Hashtable to generate a PSD1-like output.
+                $formattedHashtable = Format-Hashtable -Hashtable $Hashtable
+                Set-Content -Path $Path -Value $formattedHashtable -Force
+            } catch {
+                throw "Failed to export hashtable to PSD1 file '$Path'. Error details: $_"
+            }
+        }
+        '.ps1' {
+            try {
+                # Format the hashtable and wrap it in a function so that when the script is run it returns the hashtable.
+                $formattedHashtable = Format-Hashtable -Hashtable $Hashtable
+                Set-Content -Path $Path -Value $formattedHashtable -Force
+            } catch {
+                throw "Failed to export hashtable to PS1 file '$Path'. Error details: $_"
+            }
+        }
+        '.json' {
+            try {
+                # Convert the hashtable to JSON. You might adjust the Depth parameter as needed.
+                $jsonContent = $Hashtable | ConvertTo-Json -Depth 10
+                Set-Content -Path $Path -Value $jsonContent -Force
+            } catch {
+                throw "Failed to export hashtable to JSON file '$Path'. Error details: $_"
+            }
+        }
+        default {
+            throw "Unsupported file extension '$extension'. Only .psd1, .ps1, and .json files are supported."
+        }
+    }
+}

src/functions/public/Format-Hashtable.ps1

@@ -47,7 +47,7 @@
         Useful for serialization and exporting hashtables to files.
 
         .LINK
-        https://psmodule.io/Format/Functions/Format-Hashtable
+        https://psmodule.io/Hashtable/Functions/Format-Hashtable
     #>
     [OutputType([string])]
     [CmdletBinding()]

src/functions/public/Import-Hashtable.ps1

@@ -0,0 +1,114 @@
+filter Import-Hashtable {
+    <#
+        .SYNOPSIS
+        Imports a hashtable from a specified file.
+
+        .DESCRIPTION
+        This function reads a file and imports its contents as a hashtable. It supports `.psd1`, `.ps1`, and `.json` files.
+        - `.psd1` files are imported using `Import-PowerShellDataFile`. This process is safe and does not execute any code.
+        - `.ps1` scripts are executed, and their output must be a hashtable. If the script does not return a hashtable, an error is thrown.
+        - `.json` files are read and converted to a hashtable using `ConvertFrom-Json -AsHashtable`.
+        This process is safe and does not execute any code.
+
+        If the specified file does not exist or has an unsupported format, an error is thrown.
+
+        .EXAMPLE
+        Import-Hashtable -Path 'C:\config.psd1'
+
+        Output:
+        ```powershell
+        Name       Value
+        ----       -----
+        Setting1   Enabled
+        Setting2   42
+        ```
+
+        Imports a hashtable from a `.psd1` file.
+
+        .EXAMPLE
+        Import-Hashtable -Path 'C:\script.ps1'
+
+        Output:
+        ```powershell
+        Name       Value
+        ----       -----
+        Key1       Value1
+        Key2       Value2
+        ```
+
+        Executes the script and imports the hashtable returned by the `.ps1` file.
+
+        .EXAMPLE
+        Import-Hashtable -Path 'C:\data.json'
+
+        Output:
+        ```powershell
+        Name       Value
+        ----       -----
+        username   johndoe
+        roles      {Admin, User}
+        ```
+
+        Reads a JSON file and converts its content into a hashtable.
+
+        .OUTPUTS
+        hashtable
+
+        .NOTES
+        A hashtable containing the data from the imported file.
+        The hashtable structure depends on the contents of the imported file.
+
+        .LINK
+        https://psmodule.io/Hashtable/Functions/Import-Hashtable
+    #>
+    [CmdletBinding()]
+    param(
+        # Path to the file containing the hashtable.
+        [Parameter(
+            Mandatory,
+            ValueFromPipeline,
+            ValueFromPipelineByPropertyName
+        )]
+        [string] $Path
+    )
+
+    if (-not (Test-Path -Path $Path)) {
+        throw "File '$Path' does not exist."
+    }
+
+    $extension = [System.IO.Path]::GetExtension($Path).ToLower()
+
+    switch ($extension) {
+        '.psd1' {
+            try {
+                $hashtable = Import-PowerShellDataFile -Path $Path
+            } catch {
+                throw "Failed to import hashtable from PSD1 file '$Path'. Error details: $_"
+            }
+        }
+        '.ps1' {
+            try {
+                $hashtable = & $Path
+                if (-not ($hashtable -is [hashtable])) {
+                    throw 'The PS1 script did not return a hashtable. Verify its content.'
+                }
+            } catch {
+                throw "Failed to import hashtable from PS1 file '$Path'. Error details: $_"
+            }
+        }
+        '.json' {
+            try {
+                # Read the entire JSON file and convert it to a hashtable.
+                $jsonContent = Get-Content -Path $Path -Raw
+                $hashtable = $jsonContent | ConvertFrom-Json -AsHashtable
+            } catch {
+                throw "Failed to import hashtable from JSON file '$Path'. Error details: $_"
+            }
+        }
+        default {
+            throw "Unsupported file extension '$extension'. Only .psd1, .ps1, and .json files are supported."
+        }
+    }
+
+    return $hashtable
+}

src/functions/public/Remove-HashtableEntry.ps1

@@ -1,38 +1,54 @@
 filter Remove-HashtableEntry {
     <#
         .SYNOPSIS
-        Removes specific entries from a hashtable based on value, type, or name.
+        Removes specific entries from a hashtable based on given criteria.
 
         .DESCRIPTION
-        This version applies keep filters with the highest precedence. If a key
-        qualifies based on the provided Keep parameters (KeepTypes and/or KeepKeys),
-        it is preserved no matter what removal conditions might say.
+        This function filters out entries from a hashtable based on different conditions. You can remove keys with
+        null or empty values, keys of a specific type, or keys matching certain names. It also allows keeping entries
+        based on the opposite criteria. If the `-All` parameter is used, all entries in the hashtable will be removed.
 
-        If no keep filters are provided, the function applies removal conditions:
-        - NullOrEmptyValues: Remove keys with null or empty values.
-        - RemoveTypes: Remove keys whose values are of the specified type(s).
-        - RemoveKeys: Remove keys with the specified name(s).
+        .EXAMPLE
+        $myHashtable = @{ Name = 'John'; Age = 30; Country = $null }
+        $myHashtable | Remove-HashtableEntry -NullOrEmptyValues
 
-        When Keep filters are provided, only keys that match ALL specified keep criteria
-        will be preserved; keys that do not match are removed regardless of removal settings.
+        Output:
+        ```powershell
+        @{ Name = 'John'; Age = 30 }
+        ```
 
-        At the end, the original hashtable is cleared and repopulated with the filtered results.
+        Removes entries with null or empty values from the hashtable.
 
         .EXAMPLE
-        $ht = @{
-            KeepThis   = 'Value1'
-            RemoveThis = 'Delete'
-            Other      = 42
-        }
-        $ht | Remove-HashtableEntry -KeepKeys 'KeepThis' -RemoveKeys 'RemoveThis'
+        $myHashtable = @{ Name = 'John'; Age = 30; Active = $true }
+        $myHashtable | Remove-HashtableEntry -Types 'Boolean'
+
+        Output:
+        ```powershell
+        @{ Name = 'John'; Age = 30 }
+        ```
+
+        Removes entries where the value type is Boolean.
 
-        This will keep only the key "KeepThis", regardless of other removal flags.
+        .EXAMPLE
+        $myHashtable = @{ Name = 'John'; Age = 30; Country = 'USA' }
+        $myHashtable | Remove-HashtableEntry -Keys 'Age'
+
+        Output:
+        ```powershell
+        @{ Name = 'John'; Country = 'USA' }
+        ```
+
+        Removes the key 'Age' from the hashtable.
 
         .OUTPUTS
-        hashtable
+        void
 
         .NOTES
-        The function modifies the input hashtable in place.
+        The function modifies the input hashtable but does not return output.
+
+        .LINK
+        https://psmodule.io/Hashtable/Functions/Remove-HashtableEntry/
     #>
     [Diagnostics.CodeAnalysis.SuppressMessageAttribute(
         'PSUseShouldProcessForStateChangingFunctions', '',

tests/Hashtable.Tests.ps1

@@ -529,4 +529,74 @@
             }
         }
     }
+
+    Describe 'Export/Import-Hashtable' {
+        $testData = @(
+            @{ Path = "$HOME/config.psd1"; Extension = '.psd1' }
+            @{ Path = "$HOME/config.ps1"; Extension = '.ps1' }
+            @{ Path = "$HOME/config.json"; Extension = '.json' }
+        )
+
+        It 'Exports a hashtable to a <Extension> file at <Path>' -ForEach $testData {
+            $hashtable = [ordered]@{
+                StringKey       = "Hello 'PowerShell'!"
+                NumberKey       = 42
+                BooleanKey      = $true
+                NullKey         = $null
+                ArrayKey        = @(
+                    'FirstItem'
+                    123
+                    $false
+                    @('NestedArray1', 'NestedArray2')
+                    [ordered]@{
+                        NestedHashtableKey1 = 'NestedValue1'
+                        NestedHashtableKey2 = @(
+                            @{ DeepNestedKey = 'DeepValue' }
+                            999
+                        )
+                    }
+                )
+                NestedHashtable = [ordered]@{
+                    SubKey1 = 'SubValue1'
+                    SubKey2 = @(
+                        'ArrayInsideHashtable1'
+                        'ArrayInsideHashtable2'
+                        ''
+                        @{
+                            EvenDeeper = "Yes, it's deep!"
+                        }
+                    )
+                }
+            }
+
+            Export-Hashtable -Hashtable $hashtable -Path $Path
+            Write-Verbose (Get-Content -Path $Path | Out-String) -Verbose
+            $result = Test-Path -Path $path
+            $result | Should -Be $true
+        }
+        It 'Imports a <Extension> file at <Path> to a hashtable' -ForEach $testData {
+            $hashtable = Import-Hashtable -Path $Path
+
+            Write-Verbose ($hashtable | Format-Hashtable | Out-String) -Verbose
+
+            $hashtable | Should -BeOfType [hashtable]
+            $hashtable.StringKey | Should -Be "Hello 'PowerShell'!"
+            $hashtable.NumberKey | Should -Be 42
+            $hashtable.BooleanKey | Should -Be $true
+            $hashtable.NullKey | Should -Be $null
+            $hashtable.ArrayKey[0] | Should -Be 'FirstItem'
+            $hashtable.ArrayKey[1] | Should -Be 123
+            $hashtable.ArrayKey[2] | Should -Be $false
+            $hashtable.ArrayKey[3] | Should -Be 'NestedArray1'
+            $hashtable.ArrayKey[4] | Should -Be 'NestedArray2'
+            $hashtable.ArrayKey[5].NestedHashtableKey1 | Should -Be 'NestedValue1'
+            $hashtable.ArrayKey[5].NestedHashtableKey2[0].DeepNestedKey | Should -Be 'DeepValue'
+            $hashtable.ArrayKey[5].NestedHashtableKey2[1] | Should -Be 999
+            $hashtable.NestedHashtable.SubKey1 | Should -Be 'SubValue1'
+            $hashtable.NestedHashtable.SubKey2[0] | Should -Be 'ArrayInsideHashtable1'
+            $hashtable.NestedHashtable.SubKey2[1] | Should -Be 'ArrayInsideHashtable2'
+            $hashtable.NestedHashtable.SubKey2[2] | Should -Be ''
+            $hashtable.NestedHashtable.SubKey2[3].EvenDeeper | Should -Be "Yes, it's deep!"
+        }
+    }
 }