{"id":16115520,"url":"https://github.com/byron/therror","last_synced_at":"2025-03-18T10:30:37.151Z","repository":{"id":193218951,"uuid":"688349985","full_name":"Byron/therror","owner":"Byron","description":"`thiserror` + killer-feature","archived":false,"fork":false,"pushed_at":"2023-12-16T13:04:37.000Z","size":693,"stargazers_count":6,"open_issues_count":1,"forks_count":0,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-02-28T08:52:23.069Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Byron.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE-APACHE","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":"2023-09-07T07:04:43.000Z","updated_at":"2023-12-12T04:15:35.000Z","dependencies_parsed_at":"2023-12-16T14:27:00.644Z","dependency_job_id":"64d4d89a-eb2c-43ad-b74d-bdf5e3b0ba40","html_url":"https://github.com/Byron/therror","commit_stats":null,"previous_names":["byron/theerror","byron/therror"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Byron%2Ftherror","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Byron%2Ftherror/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Byron%2Ftherror/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Byron%2Ftherror/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Byron","download_url":"https://codeload.github.com/Byron/therror/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243918628,"owners_count":20368745,"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","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":[],"created_at":"2024-10-09T20:19:03.865Z","updated_at":"2025-03-18T10:30:36.557Z","avatar_url":"https://github.com/Byron.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"derive(Error)\n=============\n\n[\u003cimg alt=\"github\" src=\"https://img.shields.io/badge/github-byron/therror-8da0cb?style=for-the-badge\u0026labelColor=555555\u0026logo=github\" height=\"20\"\u003e](https://github.com/byron/therror)\n[\u003cimg alt=\"crates.io\" src=\"https://img.shields.io/crates/v/therror.svg?style=for-the-badge\u0026color=fc8d62\u0026logo=rust\" height=\"20\"\u003e](https://crates.io/crates/therror)\n[\u003cimg alt=\"docs.rs\" src=\"https://img.shields.io/badge/docs.rs-therror-66c2a5?style=for-the-badge\u0026labelColor=555555\u0026logo=docs.rs\" height=\"20\"\u003e](https://docs.rs/therror)\n[\u003cimg alt=\"build status\" src=\"https://img.shields.io/github/actions/workflow/status/byron/therror/ci.yml?branch=main\u0026style=for-the-badge\" height=\"20\"\u003e](https://github.com/byron/therror/actions?query=branch%3Amain)\n\nThis library provides a convenient derive macro for the standard library's\n[`std::error::Error`] trait.\n\n[`std::error::Error`]: https://doc.rust-lang.org/std/error/trait.Error.html\n\n```toml\n[dependencies]\ntherror = \"1.0\"\n```\n\n*Compiler support: requires rustc 1.56+*\n\n\u003cbr\u003e\n\n## Example\n\n```rust\nuse therror::Error;\n\n#[derive(Error, Debug)]\npub enum DataStoreError {\n    #[error(\"data store disconnected\")]\n    Disconnect(#[from] io::Error),\n    #[error(\"the data for key `{0}` is not available\")]\n    Redaction(String),\n    #[error(\"invalid header (expected {expected:?}, found {found:?})\")]\n    InvalidHeader {\n        expected: String,\n        found: String,\n    },\n    #[error(\"unknown data store error\")]\n    Unknown,\n}\n```\n\n\u003cbr\u003e\n\n## Details\n\n- Thiserror deliberately does not appear in your public API. You get the same\n  thing as if you had written an implementation of `std::error::Error` by hand,\n  and switching from handwritten impls to therror or vice versa is not a\n  breaking change.\n\n- Errors may be enums, structs with named fields, tuple structs, or unit\n  structs.\n\n- A `Display` impl is generated for your error if you provide `#[error(\"...\")]`\n  messages on the struct or each variant of your enum, as shown above in the\n  example.\n\n  The messages support a shorthand for interpolating fields from the error.\n\n    - `#[error(\"{var}\")]`\u0026ensp;⟶\u0026ensp;`write!(\"{}\", self.var)`\n    - `#[error(\"{0}\")]`\u0026ensp;⟶\u0026ensp;`write!(\"{}\", self.0)`\n    - `#[error(\"{var:?}\")]`\u0026ensp;⟶\u0026ensp;`write!(\"{:?}\", self.var)`\n    - `#[error(\"{0:?}\")]`\u0026ensp;⟶\u0026ensp;`write!(\"{:?}\", self.0)`\n\n  These shorthands can be used together with any additional format args, which\n  may be arbitrary expressions. For example:\n\n  ```rust\n  #[derive(Error, Debug)]\n  pub enum Error {\n      #[error(\"invalid rdo_lookahead_frames {0} (expected \u003c {})\", i32::MAX)]\n      InvalidLookahead(u32),\n  }\n  ```\n\n  If one of the additional expression arguments needs to refer to a field of the\n  struct or enum, then refer to named fields as `.var` and tuple fields as `.0`.\n\n  ```rust\n  #[derive(Error, Debug)]\n  pub enum Error {\n      #[error(\"first letter must be lowercase but was {:?}\", first_char(.0))]\n      WrongCase(String),\n      #[error(\"invalid index {idx}, expected at least {} and at most {}\", .limits.lo, .limits.hi)]\n      OutOfBounds { idx: usize, limits: Limits },\n  }\n  ```\n\n- A `From` impl is generated for each variant containing a `#[from]` attribute.\n\n  Note that the variant must not contain any other fields beyond the source\n  error and possibly a backtrace. A backtrace is captured from within the `From`\n  impl if there is a field for it.\n\n  ```rust\n  #[derive(Error, Debug)]\n  pub enum MyError {\n      Io {\n          #[from]\n          source: io::Error,\n          backtrace: Backtrace,\n      },\n  }\n  ```\n\n- The Error trait's `source()` method is implemented to return whichever field\n  has a `#[source]` attribute or is named `source`, if any. This is for\n  identifying the underlying lower level error that caused your error.\n\n  The `#[from]` attribute always implies that the same field is `#[source]`, so\n  you don't ever need to specify both attributes.\n\n  Any error type that implements `std::error::Error` or dereferences to `dyn\n  std::error::Error` will work as a source.\n\n  ```rust\n  #[derive(Error, Debug)]\n  pub struct MyError {\n      msg: String,\n      #[source]  // optional if field name is `source`\n      source: anyhow::Error,\n  }\n  ```\n\n- The Error trait's `provide()` method is implemented to provide whichever field\n  has a type named `Backtrace`, if any, as a `std::backtrace::Backtrace`.\n\n  ```rust\n  use std::backtrace::Backtrace;\n\n  #[derive(Error, Debug)]\n  pub struct MyError {\n      msg: String,\n      backtrace: Backtrace,  // automatically detected\n  }\n  ```\n\n- If a field is both a source (named `source`, or has `#[source]` or `#[from]`\n  attribute) *and* is marked `#[backtrace]`, then the Error trait's `provide()`\n  method is forwarded to the source's `provide` so that both layers of the error\n  share the same backtrace.\n\n  ```rust\n  #[derive(Error, Debug)]\n  pub enum MyError {\n      Io {\n          #[backtrace]\n          source: io::Error,\n      },\n  }\n  ```\n\n- Errors may use `error(transparent)` to forward the source and Display methods\n  straight through to an underlying error without adding an additional message.\n  This would be appropriate for enums that need an \"anything else\" variant.\n\n  ```rust\n  #[derive(Error, Debug)]\n  pub enum MyError {\n      ...\n\n      #[error(transparent)]\n      Other(#[from] anyhow::Error),  // source and Display delegate to anyhow::Error\n  }\n  ```\n\n  Another use case is hiding implementation details of an error representation\n  behind an opaque error type, so that the representation is able to evolve\n  without breaking the crate's public API.\n\n  ```rust\n  // PublicError is public, but opaque and easy to keep compatible.\n  #[derive(Error, Debug)]\n  #[error(transparent)]\n  pub struct PublicError(#[from] ErrorRepr);\n\n  impl PublicError {\n      // Accessors for anything we do want to expose publicly.\n  }\n\n  // Private and free to change across minor version of the crate.\n  #[derive(Error, Debug)]\n  enum ErrorRepr {\n      ...\n  }\n  ```\n\n- See also the [`anyhow`] library for a convenient single error type to use in\n  application code.\n\n  [`anyhow`]: https://github.com/dtolnay/anyhow\n\n\u003cbr\u003e\n\n## Comparison to anyhow\n\nUse `therror` if you care about designing your own dedicated error type(s) so\nthat the caller receives exactly the information that you choose in the event of\nfailure. This most often applies to library-like code. Use [Anyhow] if you don't\ncare what error type your functions return, you just want it to be easy. This is\ncommon in application-like code.\n\n[Anyhow]: https://github.com/dtolnay/anyhow\n\n\u003cbr\u003e\n\n\n## A fork of `therror`\n\nThis fork was created with the idea of adding a killer-feature to `therror` which would definitely not make it into `therror` itself.\nWe shall write more once it is more than an idea.\n\nThe idea is to start out at `0.X.Y` where `X` is chosen to denote breaking changes, and `Y` is tracking the `therror` baseline while it matters.\nOnce it becomes clear how `therror` differentiates itself, while retaining compatibility to `therror` for its baseline features, and once\nthis differentiation becomes mature, we can continue increasing the major version to `2.0.0` and stand alone.\n\n## License\n\n\u003csup\u003e\nLicensed under either of \u003ca href=\"LICENSE-APACHE\"\u003eApache License, Version\n2.0\u003c/a\u003e or \u003ca href=\"LICENSE-MIT\"\u003eMIT license\u003c/a\u003e at your option.\n\u003c/sup\u003e\n\n\u003cbr\u003e\n\n\u003csub\u003e\nUnless you explicitly state otherwise, any contribution intentionally submitted\nfor inclusion in this crate by you, as defined in the Apache-2.0 license, shall\nbe dual licensed as above, without any additional terms or conditions.\n\u003c/sub\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbyron%2Ftherror","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbyron%2Ftherror","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbyron%2Ftherror/lists"}