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))

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).

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.

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

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

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.