Functions/GenXdev.Data.Preferences/Set-GenXdevPreference.ps1

################################################################################
<#
.SYNOPSIS
Sets a preference value in the GenXdev preferences store.
 
.DESCRIPTION
This function manages preferences in the GenXdev local store. It can set new
preferences, update existing ones, or remove them when a null/empty value is
provided. The preferences are stored with synchronization set to "Local".
 
.PARAMETER Name
Specifies the name (key) of the preference to set. This is required and must not
be null or empty.
 
.PARAMETER Value
Specifies the value to store for the preference. If null or empty, the preference
will be removed instead of being set.
 
.PARAMETER SessionOnly
Use alternative settings stored in session for Data preferences like Language,
Database paths, etc.
 
.PARAMETER ClearSession
Clear the session setting (Global variable) before retrieving.
 
.PARAMETER PreferencesDatabasePath
Database path for preference data files.
 
.PARAMETER SkipSession
Dont use alternative settings stored in session for Data preferences like
Language, Database paths, etc.
 
.EXAMPLE
Set-GenXdevPreference -Name "Theme" -Value "Dark"
Sets the "Theme" preference to "Dark" in the local store.
 
.EXAMPLE
setPreference Theme Light
Uses the alias and positional parameters to set the Theme preference to Light.
#>

################################################################################
function Set-GenXdevPreference {

    [CmdletBinding(
        SupportsShouldProcess = $true
    )]
    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidGlobalVars', '')]
    [Alias("setPreference")]
    param(
        ################################################################################
        [Parameter(
            Mandatory = $true,
            Position = 0,
            ValueFromPipeline = $true,
            ValueFromPipelineByPropertyName = $true,
            HelpMessage = "The name of the preference to set"
        )]
        [ValidateNotNullOrEmpty()]
        [Alias("PreferenceName")]
        [string]$Name,
        ################################################################################
        [Parameter(
            Mandatory = $false,
            Position = 1,
            ValueFromPipelineByPropertyName = $true,
            HelpMessage = "The value to store for the preference"
        )]
        [AllowNull()]
        [AllowEmptyString()]
        [Alias("PreferenceValue")]
        [string]$Value,
        ################################################################################
        [Parameter(
            Mandatory = $false,
            HelpMessage = ("Use alternative settings stored in session for Data " +
                          "preferences like Language, Database paths, etc")
        )]
        [switch]$SessionOnly,
        ################################################################################
        [Parameter(
            Mandatory = $false,
            HelpMessage = ("Clear the session setting (Global variable) before " +
                          "retrieving")
        )]
        [switch]$ClearSession,
        ################################################################################
        [Parameter(
            Mandatory = $false,
            HelpMessage = "Database path for preference data files"
        )]
        [string]$PreferencesDatabasePath,
        ################################################################################
        [Parameter(
            Mandatory = $false,
            HelpMessage = ("Dont use alternative settings stored in session for " +
                          "Data preferences like Language, Database paths, etc")
        )]
        [Alias("FromPreferences")]
        [switch]$SkipSession
        ################################################################################
    )

    begin {

        # copy identical parameter values to prepare for database path lookup
        $params = GenXdev.Helpers\Copy-IdenticalParamValues `
            -BoundParameters $PSBoundParameters `
            -FunctionName "GenXdev.Data\Get-GenXdevPreferencesDatabasePath" `
            -DefaultValues (Microsoft.PowerShell.Utility\Get-Variable `
                -Scope Local `
                -ErrorAction SilentlyContinue)

        # resolve the actual database path using the helper function
        $PreferencesDatabasePath = `
            GenXdev.Data\Get-GenXdevPreferencesDatabasePath @params

        # create global variable name for this preference
        $globalVariableName = "GenXdevPreference_$Name"

        # output verbose information about the database path being used
        Microsoft.PowerShell.Utility\Write-Verbose `
            "Using database path: $PreferencesDatabasePath"

        # output verbose information about starting preference operation
        Microsoft.PowerShell.Utility\Write-Verbose (
            "Beginning preference operation for preference name: '$Name'")
    }


    process {

        # handle clearing session variables
        if ($ClearSession) {

            # confirm the operation with the user before proceeding
            if ($PSCmdlet.ShouldProcess(
                "GenXdev.Data Preference Configuration",
                "Clear session preference setting: $Name"
            )) {

                # clear the global variable
                Microsoft.PowerShell.Utility\Set-Variable `
                    -Name $globalVariableName `
                    -Value $null `
                    -Scope Global `
                    -Force

                # output verbose confirmation of session clearing
                Microsoft.PowerShell.Utility\Write-Verbose (
                    "Cleared session preference setting: $globalVariableName")
            }
            return
        }

        # handle session-only storage
        if ($SessionOnly) {

            # confirm the operation with the user before proceeding
            if ($PSCmdlet.ShouldProcess(
                "GenXdev.Data Preference Configuration",
                "Set session-only preference '$Name' to: [$Value]"
            )) {

                # set global variable for session-only storage
                Microsoft.PowerShell.Utility\Set-Variable `
                    -Name $globalVariableName `
                    -Value $Value `
                    -Scope Global `
                    -Force

                # output verbose confirmation of session-only setting
                Microsoft.PowerShell.Utility\Write-Verbose (
                    "Set session-only preference: $globalVariableName = $Value")
            }
            return
        }

        # handle persistent storage (default behavior)
        # check if preference should be removed due to null/empty value
        if ([string]::IsNullOrWhiteSpace($Value)) {

            # confirm the operation with the user before proceeding with removal
            if ($PSCmdlet.ShouldProcess(
                "GenXdev.Data Preference Configuration",
                "Remove preference '$Name' from persistent storage"
            )) {

                # copy identical parameter values for Remove-GenXdevPreference
                $removeParams = GenXdev.Helpers\Copy-IdenticalParamValues `
                    -BoundParameters $PSBoundParameters `
                    -FunctionName "GenXdev.Data\Remove-GenXdevPreference" `
                    -DefaultValues (Microsoft.PowerShell.Utility\Get-Variable `
                        -Scope Local `
                        -ErrorAction SilentlyContinue)

                # assign specific parameters for the removal operation
                $removeParams.Name = $Name
                $removeParams.SkipSession = $true  # we handle session separately

                # remove the preference from the local store
                GenXdev.Data\Remove-GenXdevPreference @removeParams

                Microsoft.PowerShell.Utility\Write-Verbose `
                    "Successfully removed preference '$Name'"
            }
            return
        }

        # store the preference if user confirms the action
        if ($PSCmdlet.ShouldProcess(
            "GenXdev.Data Preference Configuration",
            "Set preference '$Name' to: [$Value]"
        )) {

            # copy identical parameter values for Set-ValueByKeyInStore
            $setParams = GenXdev.Helpers\Copy-IdenticalParamValues `
                -BoundParameters $PSBoundParameters `
                -FunctionName "GenXdev.Data\Set-ValueByKeyInStore" `
                -DefaultValues (Microsoft.PowerShell.Utility\Get-Variable `
                    -Scope Local `
                    -ErrorAction SilentlyContinue)

            # assign specific parameters for the set operation
            $setParams.StoreName = "GenXdev.PowerShell.Preferences"
            $setParams.KeyName = $Name
            $setParams.Value = $Value
            $setParams.SynchronizationKey = "Local"
            $setParams.DatabasePath = $PreferencesDatabasePath

            # store the preference value in the database store
            GenXdev.Data\Set-ValueByKeyInStore @setParams

            Microsoft.PowerShell.Utility\Write-Verbose `
                "Successfully configured preference '$Name' in GenXdev.Data module: [$Value]"
        }
    }

    end {
    }
}
################################################################################