vendor/annotate-snippets-0.8.0/src/lib.rs

   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, [DisplayListFormatter](self::formatter::DisplayListFormatter) is
  42 //! used to format the `DisplayList` using a `Stylesheet` into a final `String` output.
  43 //!
  44 //! A user of the crate may choose to provide their own equivalent of the input
  45 //! structure with an `Into<DisplayList>` trait.
  46 //!
  47 //! A user of the crate may also choose to provide their own formatter logic,
  48 //! to convert a `DisplayList` into a `String`, or just a `Stylesheet` to
  49 //! use the crate's formatting logic, but with a custom stylesheet.
  50
  51 pub mod display_list;
  52 pub mod formatter;
  53 pub mod snippet;
  54 pub mod stylesheets;