1#![deny(rust_2018_idioms)]
2
3//! A library for formatting of text or programming code snippets.
4//!
5//! It's primary purpose is to build an ASCII-graphical representation of the snippet
6//! with annotations.
7//!
8//! # Example
9//!
10//! ```text
11//! error[E0308]: mismatched types
12//! --> src/format.rs:52:1
13//! |
14//! 51 | ) -> Option<String> {
15//! | -------------- expected `Option<String>` because of return type
16//! 52 | / for ann in annotations {
17//! 53 | | match (ann.range.0, ann.range.1) {
18//! 54 | | (None, None) => continue,
19//! 55 | | (Some(start), Some(end)) if start > end_index => continue,
20//! ... |
21//! 71 | | }
22//! 72 | | }
23//! | |_____^ expected enum `std::option::Option`, found ()
24//! ```
25//!
26//! The crate uses a three stage process with two conversions between states:
27//!
28//! ```text
29//! Snippet --> DisplayList --> String
30//! ```
31//!
32//! The input type - [Snippet](self::snippet) is a structure designed
33//! to align with likely output from any parser whose code snippet is to be
34//! annotated.
35//!
36//! The middle structure - [DisplayList](self::display_list) is a
37//! structure designed to store the snippet data converted into a vector
38//! of lines containing semantic information about each line.
39//! This structure is the easiest to manipulate and organize.
40//!
41//! Finally, `impl Display` into a final `String` output.
42//!
43//! A user of the crate may choose to provide their own equivalent of the input
44//! structure with an `Into<DisplayList>` trait.
45//!
46//! A user of the crate may also choose to provide their own formatter logic,
47//! to convert a `DisplayList` into a `String`, or just a `Stylesheet` to
48//! use the crate's formatting logic, but with a custom stylesheet.
49// TODO: check documentation
50
51pub mod display_list;
52pub mod formatter;
53pub mod snippet;
54pub mod stylesheets;
55