1# annotate-snippets
2
3`annotate-snippets` is a Rust library for annotation of programming code slices.
4
5[![crates.io](https://img.shields.io/crates/v/annotate-snippets.svg)](https://crates.io/crates/annotate-snippets)
6![build status](https://github.com/rust-lang/annotate-snippets-rs/actions/workflows/ci.yml/badge.svg)
7[![Coverage Status](https://coveralls.io/repos/github/rust-lang/annotate-snippets-rs/badge.svg?branch=master)](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