Latest 1.0.1
Homepage https://github.com/mxcl/LegibleError
License Unlicense
Platforms osx 10.10, ios 8.0, tvos 10.0, watchos 2.0
Authors

LegibleError badge-platforms badge-languages badge-ci badge-codecov badge-version

LegibleError’s goal is to prevent you showing the user a string like this:

The operation couldn’t be completed. (ThirdPartyModule.(unknown context at 0xx10d6b4a44).SomeError error 0.)

That string is the default localizedDescription for a Swift Error. Instead use LegibleError and you’ll get something more like this:

The operation couldn’t be completed. (ThirdPartyModule.SomeError.networkFailure)

Masthead

Error.legibleLocalizedDescription

If you have an Error like this:

enum SystemError: Error {
    case databaseFailure(internalCode: Int)
}

let error = SystemError.databaseFailure
// ^^ obviously you’d get this from a callback or `catch` in the real-world

let alert = UIAlertController(…)
alert.message = error.localizedDescription
present(alert)

The alert will show:

The operation couldn’t be completed. (MyModule.(unknown context at 0xx10d6b4a44).SystemError error 0.)

But if we were to use .legibleLocalizedDescription:

import LegibleError

let alert = UIAlertController(…)
alert.message = error.legibleLocalizedDescription
present(alert)

The alert will show:

The operation couldn’t be completed. (SystemError.databaseFailure(internalCode: 34))

Still not great, but way more useful in a bug report.

If you want a great message, implement LocalizedError this will make both
localizedDescription and legibleLocalizedDescription return the string
you specify:

enum SystemError: LocalizedError {
    case databaseFailure

    var errorDescription: String? {
        switch self {
        case databaseFailure(let code):
            return "A serious database failure occurred. Contact support. (#(code))"
        }
    }
}

The alert will show:

A serious database failure occurred. Contact support. (#34)


LegibleError exists because:

  1. You have no control over third parties and cannot force them to implement
    LocalizedError
  2. Some Errors in your codebase are very unlikely and thus “localizing” them is
    not a good maintenance burden.
  3. When logging errors you want the full information without any risk that the localized version has “fallen behind”, get the compiler to do the work, in such cases use legibleDescription (see the next section).

Loggable Error Descriptions

This:

let msg = "There was an error ((error))"

Will give you this:

There was an error (databaseFailure)

Which loses the context of the enum’s type; use legibleDescription:

let msg = "There was an error! (error.legibleDescription)"

There was an error (SystemError.databaseFailure)

legibleDescription is to description where legibleLocalizedDescription is
to localizedDescription. legibleDescription is always appropriate for
communicating to you, the developer, which error happened. Use it in logs and
to supplement a good message for the user.

Way better descriptions on Linux

Linux is a little behind, usually you only get The operation could not be completed on Linux. We fully support Linux.

Supporting mxcl

Hi, I’m Max Howell and I have written a lot of open source software, and
probably you already use some of it (Homebrew anyone?). I work full-time on
open source and it’s hard; currently I earn less than minimum wage. Please
help me continue my work, I appreciate it x

LegibleError

Other donation/tipping options

Installation

SwiftPM:

package.append(.package(url: "https://github.com/mxcl/LegibleError.git", from: "1.0.0"))

CocoaPods:

pod 'LegibleError', '~> 1.0'

Carthage:

Waiting on: @Carthage#1945.

Latest podspec

{
    "name": "LegibleError",
    "version": "1.0.1",
    "summary": "Beating `Error.localizedDescription` at its own game.",
    "homepage": "https://github.com/mxcl/LegibleError",
    "license": {
        "type": "Unlicense",
        "file": "LICENSE"
    },
    "authors": {
        "mxcl": "[email protected]"
    },
    "source": {
        "git": "https://github.com/mxcl/LegibleError.git",
        "tag": "1.0.1"
    },
    "social_media_url": "https://twitter.com/mxcl",
    "platforms": {
        "osx": "10.10",
        "ios": "8.0",
        "tvos": "10.0",
        "watchos": "2.0"
    },
    "source_files": "Sources/*",
    "swift_version": "4.2",
    "static_framework": true
}

Pin It on Pinterest

Share This