• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# codespan-reporting
2
3[![Continuous integration][actions-badge]][actions-url]
4[![Crates.io][crate-badge]][crate-url]
5[![Docs.rs][docs-badge]][docs-url]
6[![Matrix][matrix-badge]][matrix-lobby]
7
8[actions-badge]: https://img.shields.io/github/workflow/status/brendanzab/codespan/Continuous%20integration
9[actions-url]: https://github.com/brendanzab/codespan/actions
10[crate-url]: https://crates.io/crates/codespan-reporting
11[crate-badge]: https://img.shields.io/crates/v/codespan-reporting.svg
12[docs-url]: https://docs.rs/codespan-reporting
13[docs-badge]: https://docs.rs/codespan-reporting/badge.svg
14[matrix-badge]: https://img.shields.io/badge/matrix-%23codespan%3Amatrix.org-blue.svg
15[matrix-lobby]: https://app.element.io/#/room/#codespan:matrix.org
16
17Beautiful diagnostic reporting for text-based programming languages.
18
19![Example preview](./codespan-reporting/assets/readme_preview.svg?sanitize=true)
20
21Languages like Rust and Elm already support beautiful error reporting output,
22but it can take a significant amount work to implement this for new programming
23languages! The `codespan-reporting` crate aims to make beautiful error
24diagnostics easy and relatively painless for everyone!
25
26We're still working on improving the crate to help it support broader use cases,
27and improving the quality of the diagnostic rendering, so stay tuned for
28updates and please give us feedback if you have it. Contributions are also very
29welcome!
30
31## Example
32
33```rust
34use codespan_reporting::diagnostic::{Diagnostic, Label};
35use codespan_reporting::files::SimpleFiles;
36use codespan_reporting::term::termcolor::{ColorChoice, StandardStream};
37
38// `files::SimpleFile` and `files::SimpleFiles` help you get up and running with
39// `codespan-reporting` quickly! More complicated use cases can be supported
40// by creating custom implementations of the `files::Files` trait.
41
42let mut files = SimpleFiles::new();
43
44let file_id = files.add(
45    "FizzBuzz.fun",
46    unindent::unindent(
47        r#"
48            module FizzBuzz where
49
50            fizz₁ : Nat → String
51            fizz₁ num = case (mod num 5) (mod num 3) of
52                0 0 => "FizzBuzz"
53                0 _ => "Fizz"
54                _ 0 => "Buzz"
55                _ _ => num
56
57            fizz₂ : Nat → String
58            fizz₂ num =
59                case (mod num 5) (mod num 3) of
60                    0 0 => "FizzBuzz"
61                    0 _ => "Fizz"
62                    _ 0 => "Buzz"
63                    _ _ => num
64        "#,
65    ),
66);
67
68// We normally recommend creating a custom diagnostic data type for your
69// application, and then converting that to `codespan-reporting`'s diagnostic
70// type, but for the sake of this example we construct it directly.
71
72let diagnostic = Diagnostic::error()
73    .with_message("`case` clauses have incompatible types")
74    .with_code("E0308")
75    .with_labels(vec![
76        Label::primary(file_id, 328..331).with_message("expected `String`, found `Nat`"),
77        Label::secondary(file_id, 211..331).with_message("`case` clauses have incompatible types"),
78        Label::secondary(file_id, 258..268).with_message("this is found to be of type `String`"),
79        Label::secondary(file_id, 284..290).with_message("this is found to be of type `String`"),
80        Label::secondary(file_id, 306..312).with_message("this is found to be of type `String`"),
81        Label::secondary(file_id, 186..192).with_message("expected type `String` found here"),
82    ])
83    .with_notes(vec![unindent::unindent(
84        "
85            expected type `String`
86                found type `Nat`
87        ",
88    )]);
89
90// We now set up the writer and configuration, and then finally render the
91// diagnostic to standard error.
92
93let writer = StandardStream::stderr(ColorChoice::Always);
94let config = codespan_reporting::term::Config::default();
95
96term::emit(&mut writer.lock(), &config, &files, &diagnostic)?;
97```
98
99## Running the CLI example
100
101To get an idea of what the colored CLI output looks like,
102clone the [repository](https://github.com/brendanzab/codespan)
103and run the following shell command:
104
105```sh
106cargo run --example term
107```
108
109More examples of using `codespan-reporting` can be found in the
110[examples directory](./codespan-reporting/examples).
111
112## Projects using codespan-reporting
113
114`codespan-reporting` is currently used in the following projects:
115
116- [Arret](https://arret-lang.org)
117- [cargo-deny](https://github.com/EmbarkStudios/cargo-deny)
118- [CXX](https://github.com/dtolnay/cxx)
119- [Gleam](https://github.com/lpil/gleam/)
120- [Gluon](https://github.com/gluon-lang/gluon)
121- [MDBook LinkCheck](https://github.com/Michael-F-Bryan/mdbook-linkcheck)
122- [Nushell](https://www.nushell.sh/)
123- [Pikelet](https://github.com/pikelet-lang/pikelet)
124
125## Alternatives to codespan-reporting
126
127There are a number of alternatives to `codespan-reporting`, including:
128
129- [annotate-snippets][annotate-snippets]
130- [codemap][codemap]
131- [language-reporting][language-reporting] (a fork of codespan)
132
133These are all ultimately inspired by rustc's excellent [error reporting infrastructure][librustc_errors].
134
135[annotate-snippets]: https://crates.io/crates/annotate-snippets
136[codemap]: https://crates.io/crates/codemap
137[language-reporting]: https://crates.io/crates/language-reporting
138[librustc_errors]: https://github.com/rust-lang/rust/tree/master/compiler/rustc_errors/src
139
140## Contributing
141
142A guide to contributing to codespan-reporting [can be found here](/CONTRIBUTING.md).
143
144## Code of Conduct
145
146Please note that this project is released with a [Code of Conduct](./CODE_OF_CONDUCT.md).
147By participating in this project you agree to abide by its terms.
148