annotate_snippets/lib.rs
1//! A library for formatting of text or programming code snippets.
2//!
3//! It's primary purpose is to build an ASCII-graphical representation of the snippet
4//! with annotations.
5//!
6//! # Example
7//!
8//! ```rust
9#![doc = include_str!("../examples/expected_type.rs")]
10//! ```
11//!
12#![doc = include_str!("../examples/expected_type.svg")]
13//!
14//! The crate uses a three stage process with two conversions between states:
15//!
16//! ```text
17//! Message --> Renderer --> impl Display
18//! ```
19//!
20//! The input type - [Message] is a structure designed
21//! to align with likely output from any parser whose code snippet is to be
22//! annotated.
23//!
24//! The middle structure - [Renderer] is a structure designed
25//! to convert a snippet into an internal structure that is designed to store
26//! the snippet data in a way that is easy to format.
27//! [Renderer] also handles the user-configurable formatting
28//! options, such as color, or margins.
29//!
30//! Finally, `impl Display` into a final `String` output.
31//!
32//! # features
33//! - `testing-colors` - Makes [Renderer::styled] colors OS independent, which
34//! allows for easier testing when testing colored output. It should be added as
35//! a feature in `[dev-dependencies]`, which can be done with the following command:
36//! ```text
37//! cargo add annotate-snippets --dev --feature testing-colors
38//! ```
39
40#![cfg_attr(docsrs, feature(doc_auto_cfg))]
41#![warn(clippy::print_stderr)]
42#![warn(clippy::print_stdout)]
43#![warn(missing_debug_implementations)]
44
45pub mod renderer;
46mod snippet;
47
48#[doc(inline)]
49pub use renderer::Renderer;
50pub use snippet::*;