Get-ReferenceToLastError.ps1

function Get-ReferenceToLastError {
    # .SYNOPSIS
    # Gets a reference (memory pointer) to the last error that occurred.
    #
    # .DESCRIPTION
    # Returns a reference (memory pointer) to $null ([ref]$null) if no
    # errors on on the $error stack; otherwise, returns a reference to the
    # last error that occurred.
    #
    # .EXAMPLE
    # # Intentionally empty trap statement to prevent terminating errors
    # # from halting processing
    # trap { }
    #
    # # Retrieve the newest error on the stack prior to doing work:
    # $refLastKnownError = Get-ReferenceToLastError
    #
    # # Store current error preference; we will restore it after we do some
    # # work:
    # $actionPreferenceFormerErrorPreference = $global:ErrorActionPreference
    #
    # # Set ErrorActionPreference to SilentlyContinue; this will suppress
    # # error output. Terminating errors will not output anything, kick to
    # # the empty trap statement and then continue on. Likewise, non-
    # # terminating errors will also not output anything, but they do not
    # # kick to the trap statement; they simply continue on.
    # $global:ErrorActionPreference = [System.Management.Automation.ActionPreference]::SilentlyContinue
    #
    # # Do something that might trigger an error
    # Get-Item -Path 'C:\MayNotExist.txt'
    #
    # # Restore the former error preference
    # $global:ErrorActionPreference = $actionPreferenceFormerErrorPreference
    #
    # # Retrieve the newest error on the error stack
    # $refNewestCurrentError = Get-ReferenceToLastError
    #
    # $boolErrorOccurred = $false
    # if (($null -ne $refLastKnownError.Value) -and ($null -ne $refNewestCurrentError.Value)) {
    #     # Both not $null
    #     if (($refLastKnownError.Value) -ne ($refNewestCurrentError.Value)) {
    #         $boolErrorOccurred = $true
    #     }
    # } else {
    #     # One is $null, or both are $null
    #     # NOTE: $refLastKnownError could be non-null, while
    #     # $refNewestCurrentError could be null if $error was cleared;
    #     # this does not indicate an error.
    #     # So:
    #     # If both are null, no error
    #     # If $refLastKnownError is null and $refNewestCurrentError is
    #     # non-null, error
    #     # If $refLastKnownError is non-null and $refNewestCurrentError is
    #     # null, no error
    #     if (($null -eq $refLastKnownError.Value) -and ($null -ne $refNewestCurrentError.Value)) {
    #         $boolErrorOccurred = $true
    #     }
    # }
    #
    # .INPUTS
    # None. You can't pipe objects to Get-ReferenceToLastError.
    #
    # .OUTPUTS
    # System.Management.Automation.PSReference ([ref]).
    # Get-ReferenceToLastError returns a reference (memory pointer) to the
    # last error that occurred. It returns a reference to $null
    # ([ref]$null) if there are no errors on on the $error stack.
    #
    # .NOTES
    # Version: 2.0.20241223.0

    #region License ####################################################
    # Copyright (c) 2024 Frank Lesniak
    #
    # Permission is hereby granted, free of charge, to any person obtaining
    # a copy of this software and associated documentation files (the
    # "Software"), to deal in the Software without restriction, including
    # without limitation the rights to use, copy, modify, merge, publish,
    # distribute, sublicense, and/or sell copies of the Software, and to
    # permit persons to whom the Software is furnished to do so, subject to
    # the following conditions:
    #
    # The above copyright notice and this permission notice shall be
    # included in all copies or substantial portions of the Software.
    #
    # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
    # EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
    # MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
    # NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
    # BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
    # ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
    # CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
    # SOFTWARE.
    #endregion License ####################################################

    if ($Error.Count -gt 0) {
        return ([ref]($Error[0]))
    } else {
        return ([ref]$null)
    }
}