Generates all permutations of n objects with the heap algorithm.

Add-Permutation .ps1

<#
.SYNOPSIS
    Generates all permutations of n objects with the heap algorithm.
.DESCRIPTION
    Generates all permutations of n objects with the heap algorithm.
.PARAMETER ToPermute
    Specifies the array with values to permute. For example (string): 'A','B','C'
.OUTPUTS
    Returns an array of all permutations.
.EXAMPLE
    PS> .\Add-Permutation.ps1 -ToPermute @('A','B','C')
    Result: 
    A,B,C
    B,A,C
    C,A,B
    ...
.LINK
    https://github.com/Calvindd2f
#>

# Variable Declaration
<#
readonly
######################################################
########## INPUT
######################################################
$ToPermute = @('A', 'B', 'C');
$ArrLength = $ToPermute.Length;

######################################################
########## OUTPUT
######################################################
$activityOutput = [pscustomobject]@{
    success = $true;
    error   = $null;
    debug   = $null;
    output  = @();
};
#>

param(
    [Parameter(Mandatory=$false)]
    [Array]$ToPermute = @('A','B','C')
)

function Verify {
    param(
        [Array]$ToPermute
    )
    
    $activityOutput = [pscustomobject]@{
        success = $true;
        error   = $null;
        debug   = $null;
        output  = $null;
    }

    try {
        if (-not $ToPermute) {
            throw "Input array cannot be empty."
        }

        $activityOutput.output = $true
    }
    catch {
        $activityOutput.success = $false
        $activityOutput.error   = $_.Exception.Message
        $activityOutput.debug   = $_.Exception
    }

    return $activityOutput
}

function Main {
    param(
        [Array]$ToPermute,
        [int]$ArrLength
    )

    if ($ArrLength -eq 1) {
        # Return the current permutation
        return @($ToPermute -join ',')
    }
    else {
        $permutations = @()
        for ($i = 0; $i -lt $ArrLength; $i++) {
            $permutations += Main-Activity -ToPermute $ToPermute -ArrLength ($ArrLength - 1)
            
            if ($ArrLength % 2 -eq 0) {
                $Temp = $ToPermute[$i]
                $ToPermute[$i] = $ToPermute[($ArrLength - 1)]
                $ToPermute[($ArrLength - 1)] = $Temp
            } else {
                $Temp = $ToPermute[0]
                $ToPermute[0] = $ToPermute[($ArrLength - 1)]
                $ToPermute[($ArrLength - 1)] = $Temp
            }
        }
        return $permutations
    }
}

function Execute {
    param(
        [Array]$ToPermute
    )

    $activityOutput = [pscustomobject]@{
        success = $true;
        error   = $null;
        debug   = $null;
        output  = $null;
    }

    try {
        # Verify input
        $verifyResult = Verify -ToPermute $ToPermute
        if (-not $verifyResult.success) {
            throw $verifyResult.error
        }

        # Generate permutations
        $ArrLength = $ToPermute.Length
        $activityOutput.output = Main-Activity -ToPermute $ToPermute -ArrLength $ArrLength
    }
    catch {
        $activityOutput.success = $false
        $activityOutput.error   = $_.Exception.Message
        $activityOutput.debug   = $_.Exception
    }

    return $activityOutput
}

# Execution
$result = Execute -ToPermute $ToPermute

# Output results
if ($result.success) {
    Write-Output "Permutations:"
    $result.output | ForEach-Object { Write-Output $_ }
} else {
    Write-Error $result.error
}

Key Changes:
Template Structure: We introduced the Verify-Activity, Main-Activity, and Execute-Activity functions to structure the script according to your convention.
activityOutput Object: This object now tracks the success, error messages, and output for the script. It helps manage the flow and debugging information.
Error Handling: Implemented in the Verify-Activity and Execute-Activity functions to catch issues and provide helpful error messages.
This structure helps you manage more complex scripts and handle various types of errors or debugging information efficiently.