{"id":21084015,"url":"https://github.com/mesabloo/diagnose","last_synced_at":"2025-04-05T01:09:24.108Z","repository":{"id":40699222,"uuid":"289240595","full_name":"Mesabloo/diagnose","owner":"Mesabloo","description":"A simple library for reporting compiler/interpreter errors","archived":false,"fork":false,"pushed_at":"2024-01-07T12:13:35.000Z","size":1608,"stargazers_count":232,"open_issues_count":9,"forks_count":17,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-05-14T09:01:36.340Z","etag":null,"topics":["ascii","compiler-errors","error-reporting","haskell","interpreter-errors","library","unicode"],"latest_commit_sha":null,"homepage":"https://hackage.haskell.org/package/diagnose","language":"Haskell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Mesabloo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"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":"2020-08-21T10:19:02.000Z","updated_at":"2024-05-30T05:09:35.971Z","dependencies_parsed_at":"2024-05-30T05:09:28.128Z","dependency_job_id":null,"html_url":"https://github.com/Mesabloo/diagnose","commit_stats":{"total_commits":126,"total_committers":3,"mean_commits":42.0,"dds":0.09523809523809523,"last_synced_commit":"5df8d9097b66867fcde2a704084dcd32887e90f7"},"previous_names":[],"tags_count":34,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mesabloo%2Fdiagnose","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mesabloo%2Fdiagnose/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mesabloo%2Fdiagnose/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mesabloo%2Fdiagnose/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Mesabloo","download_url":"https://codeload.github.com/Mesabloo/diagnose/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247271532,"owners_count":20911587,"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":["ascii","compiler-errors","error-reporting","haskell","interpreter-errors","library","unicode"],"created_at":"2024-11-19T20:21:26.017Z","updated_at":"2025-04-05T01:09:24.093Z","avatar_url":"https://github.com/Mesabloo.png","language":"Haskell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Error reporting made easy\n\nDiagnose is a small library used to report compiler/interpreter errors in a beautiful yet readable way.\nIt was in the beginning heavily inspired by [ariadne](https://github.com/zesterer/ariadne), but ended up quickly becoming its own thing.\n\nAs a great example, here's the output of the last test:\n\n![first example](./assets/real-world-example-unicode.png)\n\nIf you do not like unicode characters, or choose to target platforms which cannot output them natively;\nyou may alternatively print the whole diagnostic with ASCII characters, like this:\n\n![second example](./assets/real-world-example-ascii.png)\n\nColors are also optional, and you may choose not to print them.\n\n## Features\n\n- Show diagnostics with/without 8-bit colors, with/without Unicode characters\n- Inline and multiline markers are nicely displayed\n- The order of markers matters!\n  If there are multiple markers on the same line, they are ordered according to how they were put in each report\n- Reports spanning across multiple files are handled as well\n- Generic over the type of message which can be displayed, meaning that you can output custom data types as well as they can be pretty-printed\n- Diagnostics can be exported to JSON, if you don't quite like the rendering as it is, or if you need to transmit them to e.g. a website\n- Plug and play (mega)parsec integration and it magically works with your parsers!\n- Support for optional custom error codes, if you want to go the Rust way\n- Variable width Unicode characters are handled in a crossplatform manner\n- TAB characters have custom sizes specified when printing a diagnostic, so that *you* decide the width of a TAB, not your terminal emulator!\n- Colors can be tweaked thanks to the ability to export diagnostics as `Doc`uments\n\n## Usage\n\nYou only need to `import Error.Diagnose`, and everything should be ready to go.\nYou don't even need to `import Prettyprinter`, as it is already provided to you by `Error.Diagnose`!\n\n--------\n\nA diagnostic can be viewed as a collection of reports, spanning on files.\nThis is what the `Diagnostic` type embodies.\n\nIt is an instance of `Monoid`, which can be used to construct an empty\ndiagnostic (contains no reports, and has no files).\n\nThe second step is to add some reports.\nThere are two kinds of reports:\n- Error reports, created through `Err`\n- Warning reports, created by using `Warn`\n\nBoth of these fonctions have the following type:\n```haskell\n-- | An optional error code, shown right after @error@ or @warning@ in the square brackets\nMaybe msg -\u003e\n-- | The main message, which is output at the top right after @[error]@ or @[warning]@\nmsg -\u003e\n-- | A list of markers, along with the positions they span on\n[(Position, Marker msg)] -\u003e\n-- | Some hints to be output at the bottom of the report\n[Note msg] -\u003e\n-- | The created report\nReport msg\n```\n\nEach report contains markers, which are what underlines the code in the screenshots above.\nThey come in three flavors:\n- A `This` marker indicates the main reason of the error.\n  It is highlighted in red (for errors) or yellow (for warnings).\n  Ideally, there is only one per report, but this isn't strictly required.\n- A `Where` marker adds additional context to the error by adding highlighted code to the error.\n  This can be used to remind used that a variable was found of a given type earlier, or even where a previous declaration was found in another file.\n  This is output in blue by default.\n- A `Maybe` marker is probably the rarest one.\n  It is basically a way of suggesting fixes (as when GCC tells you that you probably mistyped a variable name).\n  These markers are highlighted in green.\n\nThe `Position` datatype is however required to be used with this library.\nIf you use another way of keeping track of position information, you will need to convert them to the `Position` datatype.\n\nOnce your reports are created, you will need to add them inside the diagnostic using `addReport`.\nYou will also need to put your files into the diagnostic with `addFile`, else lines won't be printed and you will get `\u003cno-line\u003e` in your reports.\n\nAfter all of this is done, you may choose to either:\n- print the diagnostic onto a file `Handle` (most likely `stdout` or `stderr`) using `printDiagnostic`;\n- create a `Doc`ument which can be further altered using `prettyDiagnostic`;\n- or export it to JSON with `diagnosticToJson` or the `ToJSON` class of Aeson (the output format is documented under the `diagnosticToJson` function).\n\n## Example\n\nHere is how the above screenshot was generated:\n```haskell\nlet beautifulExample =\n      err\n        Nothing\n        \"Could not deduce constraint 'Num(a)' from the current context\"\n        [ (Position (1, 25) (2, 6) \"somefile.zc\", This \"While applying function '+'\"),\n          (Position (1, 11) (1, 16) \"somefile.zc\", Where \"'x' is supposed to have type 'a'\"),\n          (Position (1, 8) (1, 9) \"somefile.zc\", Where \"type 'a' is bound here without constraints\")\n        ]\n        [\"Adding 'Num(a)' to the list of constraints may solve this problem.\"]\n        -- ^^^^ This is a 'Note' not a 'Hint', as specified by its 'IsString' instance\n\n-- Create the diagnostic\nlet diagnostic  = addFile mempty \"somefile.zc\" \"let id\u003ca\u003e(x : a) : a := x\\n  + 1\"\nlet diagnostic' = addReport diagnostic beautifulExample\n\n-- Print with unicode characters, and the default (colorful) style\nprintDiagnostic stdout WithUnicode 4 defaultStyle diagnostic'\n```\n\nMore examples are given in the [`test/rendering`](./test/rendering) folder (execute `stack test` to see the output).\n\n## TODO list\n\n\u003c\u003c empty, for now \u003e\u003e\n\n## License\n\nThis work is licensed under the BSD-3 clause license.\n\nCopyright (c) 2021-2022 Mesabloo, all rights reserved.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmesabloo%2Fdiagnose","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmesabloo%2Fdiagnose","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmesabloo%2Fdiagnose/lists"}