README.md
1# annotate-snippets
2
3`annotate-snippets` is a Rust library for annotation of programming code slices.
4
5[](https://crates.io/crates/annotate-snippets)
6
7[](https://coveralls.io/github/rust-lang/annotate-snippets-rs?branch=master)
8
9The library helps visualize meta information annotating source code slices.
10It takes a data structure called `Snippet` on the input and produces a `String`
11which may look like this:
12
13```text
14error[E0308]: mismatched types
15 --> src/format.rs:52:1
16 |
1751 | ) -> Option<String> {
18 | -------------- expected `Option<String>` because of return type
1952 | / for ann in annotations {
2053 | | match (ann.range.0, ann.range.1) {
2154 | | (None, None) => continue,
2255 | | (Some(start), Some(end)) if start > end_index => continue,
23... |
2471 | | }
2572 | | }
26 | |_____^ expected enum `std::option::Option`, found ()
27```
28
29[Documentation][]
30
31[Documentation]: https://docs.rs/annotate-snippets/
32
33Usage
34-----
35
36```rust
37use annotate_snippets::{
38 display_list::{DisplayList, FormatOptions},
39 snippet::{Annotation, AnnotationType, Slice, Snippet, SourceAnnotation},
40};
41
42fn main() {
43 let snippet = Snippet {
44 title: Some(Annotation {
45 label: Some("expected type, found `22`"),
46 id: None,
47 annotation_type: AnnotationType::Error,
48 }),
49 footer: vec![],
50 slices: vec![Slice {
51 source: r#" annotations: vec![SourceAnnotation {
52 label: "expected struct `annotate_snippets::snippet::Slice`, found reference"
53 ,
54 range: <22, 25>,"#,
55 line_start: 26,
56 origin: Some("examples/footer.rs"),
57 fold: true,
58 annotations: vec![
59 SourceAnnotation {
60 label: "",
61 annotation_type: AnnotationType::Error,
62 range: (187, 189),
63 },
64 SourceAnnotation {
65 label: "while parsing this struct",
66 annotation_type: AnnotationType::Info,
67 range: (34, 50),
68 },
69 ],
70 }],
71 opt: FormatOptions {
72 color: true,
73 ..Default::default()
74 },
75 };
76
77 let dl = DisplayList::from(snippet);
78 println!("{}", dl);
79}
80```
81
82Local Development
83-----------------
84
85 cargo build
86 cargo test
87
88When submitting a PR please use [`cargo fmt`][] (nightly).
89
90[`cargo fmt`]: https://github.com/rust-lang/rustfmt
91
){kind=link}
){kind=link}
){kind=link}