diagnose: Beautiful error reporting done easily

[ bsd3, error-reporting, library ] [ Propose Tags ]

This package provides a simple way of getting beautiful compiler/interpreter errors using a very simple interface for the programmer.

A quick tutorial is available in the module Error.Diagnose, which goes on most of the basis of how to use it.


[Skip to Readme]

Flags

Manual Flags

NameDescriptionDefault
json

Allows exporting diagnostics as JSON. This is disabled by default as this relies on the very heavy dependency Aeson.

Disabled
megaparsec-compat

Includes a small compatibility layer (in the module Error.Diagnose.Compat.Megaparsec) to transform megaparsec errors into reports for this library.

Disabled
parsec-compat

Includes a small compatibility layer (in the module Error.Diagnose.Compat.Parsec) to transform parsec errors into reports for this library.

Disabled

Use -f <flag> to enable a flag, or -f -<flag> to disable that flag. More info

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees

Candidates

  • No Candidates
Versions [RSS] 1.6.3, 1.6.4, 1.7.0, 1.7.1, 1.7.2, 1.8.0, 1.8.1, 1.8.2, 1.9.0, 2.0.0, 2.0.1, 2.1.0, 2.1.1, 2.2.0, 2.3.0, 2.3.1, 2.4.0, 2.5.0, 2.5.1 (info)
Dependencies base (>=4.7 && <5), bytestring (>=0.10 && <0.11), data-default (>=0.7 && <0.8), hashable (>=1.3 && <1.4), prettyprinter (>=1.7 && <1.8), prettyprinter-ansi-terminal (>=1.1 && <1.2), text (>=1.2 && <1.3), unordered-containers (>=0.2 && <0.3) [details]
License BSD-3-Clause
Copyright 2021- Ghilain Bergeron
Author Ghilain Bergeron
Maintainer Ghilain Bergeron
Category Error Reporting
Home page https://github.com/mesabloo/diagnose#readme
Bug tracker https://github.com/mesabloo/diagnose/issues
Source repo head: git clone https://github.com/mesabloo/diagnose
Uploaded by mesabloo at 2022-04-22T10:49:20Z
Distributions
Downloads 1585 total (43 in the last 30 days)
Rating 2.25 (votes: 2) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs uploaded by user
Build status unknown [no reports yet]

Readme for diagnose-1.6.4

[back to package description]

Error reporting made easy

Diagnose is a small library used to report compiler/interpreter errors in a beautiful yet readable way. It was in the beginning heavily inspired by ariadne, but ended up quickly becoming its own thing.

As a great example, here's the output of the last test:

first example

If you do not like unicode characters, or choose to target platforms which cannot output them natively; you may alternatively print the whole diagnostic with ASCII characters, like this:

second example

Colors are also optional, and you may choose not to print them.

Features

  • Show diagnostics with/without 8-bit colors, with/without Unicode characters
  • Inline and multiline markers are nicely displayed
  • The order of markers matters! If there are multiple markers on the same line, they are ordered according to how they were put in each report
  • Reports spanning across multiple files are handled as well
  • 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
  • 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
  • Plug and play (mega)parsec integration and it magically works with your parsers!

Usage

You only need to import Error.Diagnose, and everything should be ready to go. You don't even need to import Prettyprinter, as it is already provided to you by Error.Diagnose!


A diagnostic can be viewed as a collection of reports, spanning on files. This is what the Diagnostic type embodies.

It has a Default instance, which can be used to construct an empty diagnostic (contains no reports, and has no files).

The second step is to add some reports. There are two kinds of reports:

  • Error reports, created through err
  • Warning reports, created by using warn

Both of these fonctions have the following type:

  -- | The main message, which is output at the top right after `[error]` or `[warning]`
  msg ->
  -- | A list of markers, along with the positions they span on
  [(Position, Marker msg)] ->
  -- | Some hints to be output at the bottom of the report
  [msg] ->
  -- | The created report
  Report msg

Each report contains markers, which are what underlines the code in the screenshots above. They come in three flavors:

  • A This marker indicates the main reason of the error. It is highlighted in red (for errors) or yellow (for warnings). Ideally, there is only one per report, but this isn't strictly required.
  • A Where marker adds additional context to the error by adding highlighted code to the error. 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. This is output in blue by default.
  • A Maybe marker is probably the rarest one. It is basically a way of suggesting fixes (as when GCC tells you that you probably mistyped a variable name). These markers are highlighted in green.

The Position datatype is however required to be used with this library. If you use another way of keeping track of position information, you will need to convert them to the Position datatype.

Once your reports are created, you will need to add them inside the diagnostic using addReport. You will also need to put your files into the diagnostic with addFile, else lines won't be printed and you will get <no-line> in your reports.

After all of this is done, you may choose to either print the diagnostic onto a handle using printDiagnostic or export it to JSON with diagnosticToJson or the ToJSON class of Aeson (the output format is documented under the diagnosticToJson function).

Example

Here is how the above screenshot was generated:

let beautifulExample =
      err
        "Could not deduce constraint 'Num(a)' from the current context"
        [ (Position (1, 25) (2, 6) "somefile.zc", This "While applying function '+'"),
          (Position (1, 11) (1, 16) "somefile.zc", Where "'x' is supposed to have type 'a'"),
          (Position (1, 8) (1, 9) "somefile.zc", Where "type 'a' is bound here without constraints")
        ]
        ["Adding 'Num(a)' to the list of constraints may solve this problem."]

-- Create the diagnostic 
let diagnostic  = addFile def "somefile.zc" "let id<a>(x : a) : a := x\n  + 1"
let diagnostic' = addReport diagnostic beautifulExample

-- Print with unicode characters and colors
printDiagnostic stdout True True diagnostic'

More examples are given in the test/rendering folder.

TODO list

  • Handle variable-width characters such as tabs or some unicode characters

    For tabs, we may just resort to having the user fix a given number of spaces in the printDiagnostic function.

License

This work is licensed under the BSD-3 clause license.

Copyright (c) 2021- Mesabloo, all rights reserved.