mirror of
https://github.com/Mesabloo/diagnose.git
synced 2024-10-26 19:29:32 +03:00
rewrite README file
This commit is contained in:
parent
f61525c32a
commit
6db53b7020
70
README.md
70
README.md
@ -1,6 +1,7 @@
|
||||
# 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](https://github.com/zesterer/ariadne), but ended up quickly becoming its own thing.
|
||||
|
||||
As a great example, here's the output of the last test:
|
||||
|
||||
@ -11,6 +12,71 @@ you may alternatively print the whole diagnostic with ASCII characters, like thi
|
||||
|
||||
![second example](./assets/real-world-example-ascii.png)
|
||||
|
||||
-----------------
|
||||
Colors are also optional, and you may choose not to print them.
|
||||
|
||||
Copyright (c) 2021 Mesabloo, all rights reserved.
|
||||
## 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:
|
||||
```haskell
|
||||
-- | 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).
|
||||
|
||||
## License
|
||||
|
||||
This work is licensed under the BSD-3 clause license.
|
||||
|
||||
Copyright (c) 2021- Mesabloo, all rights reserved.
|
||||
|
@ -31,6 +31,7 @@ module Error.Diagnose
|
||||
-- * Re-exports
|
||||
module Export ) where
|
||||
|
||||
import Error.Diagnose.Pretty as Export
|
||||
import Error.Diagnose.Position as Export
|
||||
import Error.Diagnose.Report as Export
|
||||
import Error.Diagnose.Diagnostic as Export
|
||||
|
Loading…
Reference in New Issue
Block a user