{"id":13995524,"url":"https://github.com/mxcl/LegibleError","last_synced_at":"2025-07-22T22:31:03.939Z","repository":{"id":46295219,"uuid":"168869992","full_name":"mxcl/LegibleError","owner":"mxcl","description":"Beating `Error.localizedDescription` at its own game.","archived":false,"fork":false,"pushed_at":"2024-02-22T11:50:41.000Z","size":42,"stargazers_count":184,"open_issues_count":1,"forks_count":9,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-07-11T09:39:52.540Z","etag":null,"topics":["error-messages","micro-framework","swift"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"unlicense","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mxcl.png","metadata":{"funding":{"github":"mxcl","patreon":"mxcl"},"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-02-02T19:37:20.000Z","updated_at":"2025-04-29T09:14:56.000Z","dependencies_parsed_at":"2024-10-27T00:57:53.682Z","dependency_job_id":null,"html_url":"https://github.com/mxcl/LegibleError","commit_stats":{"total_commits":25,"total_committers":3,"mean_commits":8.333333333333334,"dds":0.07999999999999996,"last_synced_commit":"bc596702d7ff618c3f90ba480eeb48b3e83a2fbe"},"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/mxcl/LegibleError","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mxcl%2FLegibleError","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mxcl%2FLegibleError/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mxcl%2FLegibleError/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mxcl%2FLegibleError/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mxcl","download_url":"https://codeload.github.com/mxcl/LegibleError/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mxcl%2FLegibleError/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266585670,"owners_count":23952163,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-22T02:00:09.085Z","response_time":66,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["error-messages","micro-framework","swift"],"created_at":"2024-08-09T14:03:27.725Z","updated_at":"2025-07-22T22:31:03.656Z","avatar_url":"https://github.com/mxcl.png","language":"Swift","funding_links":["https://github.com/sponsors/mxcl","https://patreon.com/mxcl"],"categories":["Swift"],"sub_categories":[],"readme":"## LegibleError ![badge-platforms][] ![badge-languages][] [![badge-ci][]][gha] [![badge-codecov][]][codecov] [![badge-version][]][cocoapods]\n\nLegibleError’s goal is to prevent you showing the user a string like this:\n\n\u003e The operation couldn’t be completed. (ThirdPartyModule.(unknown context at 0xx10d6b4a44).SomeError error 0.)\n\nThat string is the default `localizedDescription` for a Swift `Error`. Instead\nuse LegibleError and you’ll get something more like this:\n\n\u003e The operation couldn’t be completed. (ThirdPartyModule.SomeError.networkFailure(http: 503))\n\n## `Error.legibleLocalizedDescription`\n\nIf you have an `Error` like this:\n\n```swift\nenum SystemError: Error {\n    case databaseFailure(internalCode: Int)\n}\n\nlet error = SystemError.databaseFailure\n// ^^ obviously you’d get this from a callback or `catch` in the real-world\n\nlet alert = UIAlertController(…)\nalert.message = error.localizedDescription\npresent(alert)\n```\n\nThe alert will show:\n\n\u003e The operation couldn’t be completed. (MyModule.(unknown context at 0xx10d6b4a44).SystemError error 0.)\n\nBut if we were to use `.legibleLocalizedDescription`:\n\n```swift\nimport LegibleError\n\nlet alert = UIAlertController(…)\nalert.message = error.legibleLocalizedDescription\npresent(alert)\n```\n\nThe alert will show:\n\n\u003e The operation couldn’t be completed. (SystemError.databaseFailure(internalCode: 34))\n\nStill not great, but way more useful in a bug report.\n\nIf you want a great message, implement `LocalizedError` this will make both\n`localizedDescription` **and** `legibleLocalizedDescription` return the string\nyou specify:\n\n```swift\nenum SystemError: LocalizedError {\n    case databaseFailure\n\n    var errorDescription: String? {\n        switch self {\n        case databaseFailure(let code):\n            return \"A serious database failure occurred. Contact support. (#\\(code))\"\n        }\n    }\n}\n```\n\nThe alert will show:\n\n\u003e A serious database failure occurred. Contact support. (#34)\n\n---\n\nLegibleError exists because:\n\n1. You have no control over third parties and cannot force them to implement\n    `LocalizedError`\n2. Some Errors in your codebase are very unlikely and thus “localizing” them is\n    not a good maintenance burden.\n3. When logging errors you want the full information without any risk that the\n    localized version has “fallen behind”, get the compiler to do the work, in\n    such cases use `legibleDescription` (see the next section).\n\n## Loggable Error Descriptions\n\nThis:\n\n```swift\nlet msg = \"There was an error (\\(error))\"\n```\n\nWill give you this:\n\n\u003e There was an error (databaseFailure)\n\nWhich loses the context of the enum’s type; use `legibleDescription`:\n\n```swift\nlet msg = \"There was an error! \\(error.legibleDescription)\"\n```\n\n\u003e There was an error (SystemError.databaseFailure(internalCode: 34))\n\n`legibleDescription` is to `description` where `legibleLocalizedDescription` is\nto `localizedDescription`. `legibleDescription` is always appropriate for\ncommunicating to *you*, the developer, which error happened. Use it in logs and\nto supplement a good message for the user.\n\n## Way better descriptions on Linux\n\nLinux is a little behind, usually you only get `The operation could not be\ncompleted` on Linux. We fully support Linux.\n\n# Sponsorship\n\nIf you or your company depend on this project, please consider [sponsorship] so\nI have justification for maintenance .\n\n## Installation\n\nSwiftPM:\n\n```swift\npackage.append(.package(url: \"https://github.com/mxcl/LegibleError.git\", from: \"1.0.0\"))\n```\n\nCocoaPods:\n\n```ruby\npod 'LegibleError', '~\u003e 1.0'\n```\n\nCarthage:\n\n\u003e Waiting on: [@Carthage#1945].\n\n\n[badge-platforms]: https://img.shields.io/badge/platforms-macOS%20%7C%20Linux%20%7C%20iOS%20%7C%20tvOS%20%7C%20watchOS-lightgrey.svg\n[badge-languages]: https://img.shields.io/badge/swift-4.2%20%7C%205.x-orange.svg\n[badge-codecov]: https://codecov.io/gh/mxcl/LegibleError/branch/master/graph/badge.svg\n[badge-version]: https://img.shields.io/cocoapods/v/LegibleError.svg?label=version\n[badge-ci]: https://github.com/mxcl/LegibleError/workflows/Checks/badge.svg\n\n[gha]: https://github.com/mxcl/LegibleError/actions\n[codecov]: https://codecov.io/gh/mxcl/LegibleError\n[cocoapods]: https://cocoapods.org/pods/LegibleError\n\n[`LocalizedError`]: https://developer.apple.com/documentation/foundation/localizederror\n[@Carthage#1945]: https://github.com/Carthage/Carthage/pull/1945\n[sponsorship]: https://github.com/sponsors/mxcl\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmxcl%2FLegibleError","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmxcl%2FLegibleError","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmxcl%2FLegibleError/lists"}