Fabio Valentini
2 years ago
parent
be1c83017e
commit
282561a461
@ -1,138 +0,0 @@
|
|||||||
# codespan-reporting
|
|
||||||
|
|
||||||
[![Continuous integration][actions-badge]][actions-url]
|
|
||||||
[![Crates.io][crate-badge]][crate-url]
|
|
||||||
[![Docs.rs][docs-badge]][docs-url]
|
|
||||||
[![Gitter][gitter-badge]][gitter-lobby]
|
|
||||||
|
|
||||||
[actions-badge]: https://img.shields.io/github/workflow/status/brendanzab/codespan/Continuous%20integration
|
|
||||||
[actions-url]: https://github.com/brendanzab/codespan/actions
|
|
||||||
[crate-url]: https://crates.io/crates/codespan-reporting
|
|
||||||
[crate-badge]: https://img.shields.io/crates/v/codespan-reporting.svg
|
|
||||||
[docs-url]: https://docs.rs/codespan-reporting
|
|
||||||
[docs-badge]: https://docs.rs/codespan-reporting/badge.svg
|
|
||||||
[gitter-badge]: https://badges.gitter.im/codespan-rs/codespan.svg
|
|
||||||
[gitter-lobby]: https://gitter.im/codespan-rs/Lobby
|
|
||||||
|
|
||||||
Beautiful diagnostic reporting for text-based programming languages.
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
Languages like Rust and Elm already support beautiful error reporting output,
|
|
||||||
but it can take a significant amount work to implement this for new programming
|
|
||||||
languages! The `codespan-reporting` crate aims to make beautiful error
|
|
||||||
diagnostics easy and relatively painless for everyone!
|
|
||||||
|
|
||||||
We're still working on improving the crate to help it support broader use cases,
|
|
||||||
and improving the quality of the diagnostic rendering, so stay tuned for
|
|
||||||
updates and please give us feedback if you have it. Contributions are also very
|
|
||||||
welcome!
|
|
||||||
|
|
||||||
## Example
|
|
||||||
|
|
||||||
```rust
|
|
||||||
use codespan_reporting::diagnostic::{Diagnostic, Label};
|
|
||||||
use codespan_reporting::files::SimpleFiles;
|
|
||||||
use codespan_reporting::term::termcolor::{ColorChoice, StandardStream};
|
|
||||||
|
|
||||||
// `files::SimpleFile` and `files::SimpleFiles` help you get up and running with
|
|
||||||
// `codespan-reporting` quickly! More complicated use cases can be supported
|
|
||||||
// by creating custom implementations of the `files::Files` trait.
|
|
||||||
|
|
||||||
let mut files = SimpleFiles::new();
|
|
||||||
|
|
||||||
let file_id = files.add(
|
|
||||||
"FizzBuzz.fun",
|
|
||||||
unindent::unindent(
|
|
||||||
r#"
|
|
||||||
module FizzBuzz where
|
|
||||||
|
|
||||||
fizz₁ : Nat → String
|
|
||||||
fizz₁ num = case (mod num 5) (mod num 3) of
|
|
||||||
0 0 => "FizzBuzz"
|
|
||||||
0 _ => "Fizz"
|
|
||||||
_ 0 => "Buzz"
|
|
||||||
_ _ => num
|
|
||||||
|
|
||||||
fizz₂ : Nat → String
|
|
||||||
fizz₂ num =
|
|
||||||
case (mod num 5) (mod num 3) of
|
|
||||||
0 0 => "FizzBuzz"
|
|
||||||
0 _ => "Fizz"
|
|
||||||
_ 0 => "Buzz"
|
|
||||||
_ _ => num
|
|
||||||
"#,
|
|
||||||
),
|
|
||||||
);
|
|
||||||
|
|
||||||
// We normally recommend creating a custom diagnostic data type for your
|
|
||||||
// application, and then converting that to `codespan-reporting`'s diagnostic
|
|
||||||
// type, but for the sake of this example we construct it directly.
|
|
||||||
|
|
||||||
let diagnostic = Diagnostic::error()
|
|
||||||
.with_message("`case` clauses have incompatible types")
|
|
||||||
.with_code("E0308")
|
|
||||||
.with_labels(vec![
|
|
||||||
Label::primary(file_id, 328..331).with_message("expected `String`, found `Nat`"),
|
|
||||||
Label::secondary(file_id, 211..331).with_message("`case` clauses have incompatible types"),
|
|
||||||
Label::secondary(file_id, 258..268).with_message("this is found to be of type `String`"),
|
|
||||||
Label::secondary(file_id, 284..290).with_message("this is found to be of type `String`"),
|
|
||||||
Label::secondary(file_id, 306..312).with_message("this is found to be of type `String`"),
|
|
||||||
Label::secondary(file_id, 186..192).with_message("expected type `String` found here"),
|
|
||||||
])
|
|
||||||
.with_notes(vec![unindent::unindent(
|
|
||||||
"
|
|
||||||
expected type `String`
|
|
||||||
found type `Nat`
|
|
||||||
",
|
|
||||||
)]);
|
|
||||||
|
|
||||||
// We now set up the writer and configuration, and then finally render the
|
|
||||||
// diagnostic to standard error.
|
|
||||||
|
|
||||||
let writer = StandardStream::stderr(ColorChoice::Always);
|
|
||||||
let config = codespan_reporting::term::Config::default();
|
|
||||||
|
|
||||||
term::emit(&mut writer.lock(), &config, &files, &diagnostic)?;
|
|
||||||
```
|
|
||||||
|
|
||||||
## Running the CLI example
|
|
||||||
|
|
||||||
To get an idea of what the colored CLI output looks like,
|
|
||||||
clone the [repository](https://github.com/brendanzab/codespan)
|
|
||||||
and run the following shell command:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
cargo run --example term
|
|
||||||
```
|
|
||||||
|
|
||||||
More examples of using `codespan-reporting` can be found in the
|
|
||||||
[examples directory](./codespan-reporting/examples).
|
|
||||||
|
|
||||||
## Projects using codespan-reporting
|
|
||||||
|
|
||||||
`codespan-reporting` is currently used in the following projects:
|
|
||||||
|
|
||||||
- [Arret](https://arret-lang.org)
|
|
||||||
- [cargo-deny](https://github.com/EmbarkStudios/cargo-deny)
|
|
||||||
- [CXX](https://github.com/dtolnay/cxx)
|
|
||||||
- [Gleam](https://github.com/lpil/gleam/)
|
|
||||||
- [Gluon](https://github.com/gluon-lang/gluon)
|
|
||||||
- [MDBook LinkCheck](https://github.com/Michael-F-Bryan/mdbook-linkcheck)
|
|
||||||
- [Nushell](https://www.nushell.sh/)
|
|
||||||
- [Pikelet](https://github.com/pikelet-lang/pikelet)
|
|
||||||
|
|
||||||
## Alternatives to codespan-reporting
|
|
||||||
|
|
||||||
There are a number of alternatives to `codespan-reporting`, including:
|
|
||||||
|
|
||||||
- [annotate-snippets][annotate-snippets]
|
|
||||||
- [codemap][codemap]
|
|
||||||
- [language-reporting][language-reporting] (a fork of codespan)
|
|
||||||
|
|
||||||
These are all ultimately inspired by rustc's excellent [error reporting infrastructure][librustc_errors].
|
|
||||||
|
|
||||||
[annotate-snippets]: https://crates.io/crates/annotate-snippets
|
|
||||||
[codemap]: https://crates.io/crates/codemap
|
|
||||||
[language-reporting]: https://crates.io/crates/language-reporting
|
|
||||||
[librustc_errors]: https://github.com/rust-lang/rust/tree/master/src/librustc_errors
|
|
||||||
Loading…
Reference in new issue