README.md

LegibleError

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(http: 503))

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(internalCode: 34))

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.

Sponsorship

If you or your company depend on this project, please consider sponsorship so I have justification for maintenance .

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.