annotate_snippets/lib.rs
1//! Format [diagnostic reports][Report], including highlighting snippets of text
2//!
3//! # Example
4//!
5//! ```rust
6//! # #[allow(clippy::needless_doctest_main)]
7#![doc = include_str!("../examples/expected_type.rs")]
8//! ```
9//!
10#![doc = include_str!("../examples/expected_type.svg")]
11//!
12//! # Visual overview
13//!
14//! [`Report`]
15//!
16#![doc = include_str!("../examples/multi_suggestion.svg")]
17//!
18//! ### Primary group
19//!
20//! [`Title`]
21//! ```text
22//! error: cannot construct `Box<_, _>` with struct literal syntax due to private fields
23//! ```
24//!
25//!
26//! [`Annotation`] on a [`Snippet`]
27//! ```text
28//! ╭▸ $DIR/multi-suggestion.rs:17:13
29//! │
30//! 17 │ let _ = Box {};
31//! │ ━━━
32//! │
33//! ```
34//!
35//! [`Message`]
36//! ```text
37//! ╰ note: private fields `0` and `1` that were not provided
38//! ```
39//!
40//!
41//!
42//! ### Secondary group: suggested fix
43//!
44//! [`Title`] (proposed solution)
45//! ```text
46//! help: you might have meant to use an associated function to build this type
47//! ```
48//!
49//! [`Patch`] Option 1 on a [`Snippet`]
50//! ```text
51//! ╭╴
52//! 21 - let _ = Box {};
53//! 21 + let _ = Box::new(_);
54//! ├╴
55//! ```
56//!
57//! [`Patch`] Option 2 on a [`Snippet`]
58//! ```text
59//! ├╴
60//! 17 - let _ = Box {};
61//! 17 + let _ = Box::new_uninit();
62//! ├╴
63//! ```
64//!
65//! *etc for Options 3 and 4*
66//!
67//! [`Message`]
68//! ```text
69//! ╰ and 12 other candidates
70//! ```
71//!
72//! ### Secondary group: alternative suggested fix
73//!
74//! [`Title`] (proposed solution)
75//! ```text
76//! help: consider using the `Default` trait
77//! ```
78//!
79//! Only [`Patch`] on a [`Snippet`]
80//! ```text
81//! ╭╴
82//! 17 - let _ = Box {};
83//! 17 + let _ = <Box as std::default::Default>::default();
84//! ╰╴
85//! ```
86//!
87//! # Cargo `features`
88//!
89//! - `simd` - Speeds up folding
90//!
91//! - `testing-colors` - Makes [Renderer::styled] colors OS independent, which
92//! allows for easier testing when testing colored output. It should be added as
93//! a feature in `[dev-dependencies]`, which can be done with the following command:
94//! ```text
95//! cargo add annotate-snippets --dev --feature testing-colors
96//! ```
97
98#![cfg_attr(docsrs, feature(doc_auto_cfg))]
99#![warn(clippy::print_stderr)]
100#![warn(clippy::print_stdout)]
101#![warn(missing_debug_implementations)]
102
103pub mod level;
104pub mod renderer;
105mod snippet;
106
107/// Normalize the string to avoid any unicode control characters.
108///
109/// This is important for untrusted input, as it can contain
110/// invalid unicode sequences.
111pub fn normalize_untrusted_str(s: &str) -> String {
112 renderer::normalize_whitespace(s)
113}
114
115#[doc(inline)]
116pub use level::Level;
117#[doc(inline)]
118pub use renderer::Renderer;
119pub use snippet::*;
120
121#[doc = include_str!("../README.md")]
122#[cfg(doctest)]
123pub struct ReadmeDoctests;