| //! A few wrappers for the `fmt::Write` objects that efficiently appends and remove |
| //! common indentation after every newline |
| //! |
| //! # Setup |
| //! |
| //! Add this to your `Cargo.toml`: |
| //! |
| //! ```toml |
| //! [dependencies] |
| //! indenter = "0.2" |
| //! ``` |
| //! |
| //! # Examples |
| //! |
| //! ## Indentation only |
| //! |
| //! This type is intended primarily for writing error reporters that gracefully |
| //! format error messages that span multiple lines. |
| //! |
| //! ```rust |
| //! use std::error::Error; |
| //! use core::fmt::{self, Write}; |
| //! use indenter::indented; |
| //! |
| //! struct ErrorReporter<'a>(&'a dyn Error); |
| //! |
| //! impl fmt::Debug for ErrorReporter<'_> { |
| //! fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
| //! let mut source = Some(self.0); |
| //! let mut i = 0; |
| //! |
| //! while let Some(error) = source { |
| //! writeln!(f)?; |
| //! write!(indented(f).ind(i), "{}", error)?; |
| //! |
| //! source = error.source(); |
| //! i += 1; |
| //! } |
| //! |
| //! Ok(()) |
| //! } |
| //! } |
| //! ``` |
| //! |
| //! ## "Dedenting" (removing common leading indendation) |
| //! |
| //! This type is intended primarily for formatting source code. For example, when |
| //! generating code. |
| //! |
| //! This type requires the feature `std`. |
| //! |
| //! ```rust |
| //! # #[cfg(feature = "std")] |
| //! # fn main() { |
| //! use std::error::Error; |
| //! use core::fmt::{self, Write}; |
| //! use indenter::CodeFormatter; |
| //! |
| //! let mut output = String::new(); |
| //! let mut f = CodeFormatter::new(&mut output, " "); |
| //! |
| //! write!( |
| //! f, |
| //! r#" |
| //! Hello |
| //! World |
| //! "#, |
| //! ); |
| //! |
| //! assert_eq!(output, "Hello\n World\n"); |
| //! |
| //! let mut output = String::new(); |
| //! let mut f = CodeFormatter::new(&mut output, " "); |
| //! |
| //! // it can also indent... |
| //! f.indent(2); |
| //! |
| //! write!( |
| //! f, |
| //! r#" |
| //! Hello |
| //! World |
| //! "#, |
| //! ); |
| //! |
| //! assert_eq!(output, " Hello\n World\n"); |
| //! # } |
| //! # #[cfg(not(feature = "std"))] |
| //! # fn main() { |
| //! # } |
| //! ``` |
| #![cfg_attr(not(feature = "std"), no_std)] |
| #![doc(html_root_url = "https://docs.rs/indenter/0.3.3")] |
| #![warn( |
| missing_debug_implementations, |
| missing_docs, |
| missing_doc_code_examples, |
| rust_2018_idioms, |
| unreachable_pub, |
| bad_style, |
| const_err, |
| dead_code, |
| improper_ctypes, |
| non_shorthand_field_patterns, |
| no_mangle_generic_items, |
| overflowing_literals, |
| path_statements, |
| patterns_in_fns_without_body, |
| private_in_public, |
| unconditional_recursion, |
| unused, |
| unused_allocation, |
| unused_comparisons, |
| unused_parens, |
| while_true |
| )] |
| use core::fmt; |
| |
| /// The set of supported formats for indentation |
| #[allow(missing_debug_implementations)] |
| pub enum Format<'a> { |
| /// Insert uniform indentation before every line |
| /// |
| /// This format takes a static string as input and inserts it after every newline |
| Uniform { |
| /// The string to insert as indentation |
| indentation: &'static str, |
| }, |
| /// Inserts a number before the first line |
| /// |
| /// This format hard codes the indentation level to match the indentation from |
| /// `core::backtrace::Backtrace` |
| Numbered { |
| /// The index to insert before the first line of output |
| ind: usize, |
| }, |
| /// A custom indenter which is executed after every newline |
| /// |
| /// Custom indenters are passed the current line number and the buffer to be written to as args |
| Custom { |
| /// The custom indenter |
| inserter: &'a mut Inserter, |
| }, |
| } |
| |
| /// Helper struct for efficiently indenting multi line display implementations |
| /// |
| /// # Explanation |
| /// |
| /// This type will never allocate a string to handle inserting indentation. It instead leverages |
| /// the `write_str` function that serves as the foundation of the `core::fmt::Write` trait. This |
| /// lets it intercept each piece of output as its being written to the output buffer. It then |
| /// splits on newlines giving slices into the original string. Finally we alternate writing these |
| /// lines and the specified indentation to the output buffer. |
| #[allow(missing_debug_implementations)] |
| pub struct Indented<'a, D: ?Sized> { |
| inner: &'a mut D, |
| needs_indent: bool, |
| format: Format<'a>, |
| } |
| |
| /// A callback for `Format::Custom` used to insert indenation after a new line |
| /// |
| /// The first argument is the line number within the output, starting from 0 |
| pub type Inserter = dyn FnMut(usize, &mut dyn fmt::Write) -> fmt::Result; |
| |
| impl Format<'_> { |
| fn insert_indentation(&mut self, line: usize, f: &mut dyn fmt::Write) -> fmt::Result { |
| match self { |
| Format::Uniform { indentation } => write!(f, "{}", indentation), |
| Format::Numbered { ind } => { |
| if line == 0 { |
| write!(f, "{: >4}: ", ind) |
| } else { |
| write!(f, " ") |
| } |
| } |
| Format::Custom { inserter } => inserter(line, f), |
| } |
| } |
| } |
| |
| impl<'a, D> Indented<'a, D> { |
| /// Sets the format to `Format::Numbered` with the provided index |
| pub fn ind(self, ind: usize) -> Self { |
| self.with_format(Format::Numbered { ind }) |
| } |
| |
| /// Sets the format to `Format::Uniform` with the provided static string |
| pub fn with_str(self, indentation: &'static str) -> Self { |
| self.with_format(Format::Uniform { indentation }) |
| } |
| |
| /// Construct an indenter with a user defined format |
| pub fn with_format(mut self, format: Format<'a>) -> Self { |
| self.format = format; |
| self |
| } |
| } |
| |
| impl<T> fmt::Write for Indented<'_, T> |
| where |
| T: fmt::Write + ?Sized, |
| { |
| fn write_str(&mut self, s: &str) -> fmt::Result { |
| for (ind, line) in s.split('\n').enumerate() { |
| if ind > 0 { |
| self.inner.write_char('\n')?; |
| self.needs_indent = true; |
| } |
| |
| if self.needs_indent { |
| // Don't render the line unless its actually got text on it |
| if line.is_empty() { |
| continue; |
| } |
| |
| self.format.insert_indentation(ind, &mut self.inner)?; |
| self.needs_indent = false; |
| } |
| |
| self.inner.write_fmt(format_args!("{}", line))?; |
| } |
| |
| Ok(()) |
| } |
| } |
| |
| /// Helper function for creating a default indenter |
| pub fn indented<D: ?Sized>(f: &mut D) -> Indented<'_, D> { |
| Indented { |
| inner: f, |
| needs_indent: true, |
| format: Format::Uniform { |
| indentation: " ", |
| }, |
| } |
| } |
| |
| /// Helper struct for efficiently dedent and indent multi line display implementations |
| /// |
| /// # Explanation |
| /// |
| /// This type allocates a string once to get the formatted result and then uses the internal |
| /// formatter efficiently to: first dedent the output, then re-indent to the desired level. |
| #[cfg(feature = "std")] |
| #[allow(missing_debug_implementations)] |
| pub struct CodeFormatter<'a, T> { |
| f: &'a mut T, |
| level: u32, |
| indentation: String, |
| } |
| |
| #[cfg(feature = "std")] |
| impl<'a, T: fmt::Write> fmt::Write for CodeFormatter<'a, T> { |
| fn write_str(&mut self, input: &str) -> fmt::Result { |
| let input = match input.chars().next() { |
| Some('\n') => &input[1..], |
| _ => return self.f.write_str(input), |
| }; |
| |
| let min = input |
| .split('\n') |
| .map(|line| line.chars().take_while(char::is_ascii_whitespace).count()) |
| .filter(|count| *count > 0) |
| .min() |
| .unwrap_or_default(); |
| |
| let input = input.trim_end_matches(|c| char::is_ascii_whitespace(&c)); |
| |
| for line in input.split('\n') { |
| if line.len().saturating_sub(min) > 0 { |
| for _ in 0..self.level { |
| self.f.write_str(&self.indentation)?; |
| } |
| } |
| |
| if line.len() >= min { |
| self.f.write_str(&line[min..])?; |
| } else { |
| self.f.write_str(&line)?; |
| } |
| self.f.write_char('\n')?; |
| } |
| |
| Ok(()) |
| } |
| |
| fn write_fmt(&mut self, args: fmt::Arguments<'_>) -> fmt::Result { |
| self.write_str(&args.to_string()) |
| } |
| } |
| |
| #[cfg(feature = "std")] |
| impl<'a, T: fmt::Write> CodeFormatter<'a, T> { |
| /// Wrap the formatter `f`, use `indentation` as base string indentation and return a new |
| /// formatter that implements `std::fmt::Write` that can be used with the macro `write!()` |
| pub fn new<S: Into<String>>(f: &'a mut T, indentation: S) -> Self { |
| Self { |
| f, |
| level: 0, |
| indentation: indentation.into(), |
| } |
| } |
| |
| /// Set the indentation level to a specific value |
| pub fn set_level(&mut self, level: u32) { |
| self.level = level; |
| } |
| |
| /// Increase the indentation level by `inc` |
| pub fn indent(&mut self, inc: u32) { |
| self.level = self.level.saturating_add(inc); |
| } |
| |
| /// Decrease the indentation level by `inc` |
| pub fn dedent(&mut self, inc: u32) { |
| self.level = self.level.saturating_sub(inc); |
| } |
| } |
| |
| #[cfg(test)] |
| mod tests { |
| extern crate alloc; |
| |
| use super::*; |
| use alloc::string::String; |
| use core::fmt::Write as _; |
| |
| #[test] |
| fn one_digit() { |
| let input = "verify\nthis"; |
| let expected = " 2: verify\n this"; |
| let mut output = String::new(); |
| |
| indented(&mut output).ind(2).write_str(input).unwrap(); |
| |
| assert_eq!(expected, output); |
| } |
| |
| #[test] |
| fn two_digits() { |
| let input = "verify\nthis"; |
| let expected = " 12: verify\n this"; |
| let mut output = String::new(); |
| |
| indented(&mut output).ind(12).write_str(input).unwrap(); |
| |
| assert_eq!(expected, output); |
| } |
| |
| #[test] |
| fn no_digits() { |
| let input = "verify\nthis"; |
| let expected = " verify\n this"; |
| let mut output = String::new(); |
| |
| indented(&mut output).write_str(input).unwrap(); |
| |
| assert_eq!(expected, output); |
| } |
| |
| #[test] |
| fn with_str() { |
| let input = "verify\nthis"; |
| let expected = "...verify\n...this"; |
| let mut output = String::new(); |
| |
| indented(&mut output) |
| .with_str("...") |
| .write_str(input) |
| .unwrap(); |
| |
| assert_eq!(expected, output); |
| } |
| |
| #[test] |
| fn dyn_write() { |
| let input = "verify\nthis"; |
| let expected = " verify\n this"; |
| let mut output = String::new(); |
| let writer: &mut dyn core::fmt::Write = &mut output; |
| |
| indented(writer).write_str(input).unwrap(); |
| |
| assert_eq!(expected, output); |
| } |
| |
| #[test] |
| fn nice_api() { |
| let input = "verify\nthis"; |
| let expected = " 1: verify\n this"; |
| let output = &mut String::new(); |
| let n = 1; |
| |
| write!( |
| indented(output).with_format(Format::Custom { |
| inserter: &mut move |line_no, f| { |
| if line_no == 0 { |
| write!(f, "{: >4}: ", n) |
| } else { |
| write!(f, " ") |
| } |
| } |
| }), |
| "{}", |
| input |
| ) |
| .unwrap(); |
| |
| assert_eq!(expected, output); |
| } |
| |
| #[test] |
| fn nice_api_2() { |
| let input = "verify\nthis"; |
| let expected = " verify\n this"; |
| let output = &mut String::new(); |
| |
| write!( |
| indented(output).with_format(Format::Uniform { indentation: " " }), |
| "{}", |
| input |
| ) |
| .unwrap(); |
| |
| assert_eq!(expected, output); |
| } |
| |
| #[test] |
| fn trailing_newlines() { |
| let input = "verify\nthis\n"; |
| let expected = " verify\n this\n"; |
| let output = &mut String::new(); |
| |
| write!(indented(output).with_str(" "), "{}", input).unwrap(); |
| |
| assert_eq!(expected, output); |
| } |
| |
| #[test] |
| fn several_interpolations() { |
| let input = "verify\nthis\n"; |
| let expected = " verify\n this\n and verify\n this\n"; |
| let output = &mut String::new(); |
| |
| write!(indented(output).with_str(" "), "{} and {}", input, input).unwrap(); |
| |
| assert_eq!(expected, output); |
| } |
| } |
| |
| #[cfg(all(test, feature = "std"))] |
| mod tests_std { |
| use super::*; |
| use core::fmt::Write as _; |
| |
| #[test] |
| fn dedent() { |
| let mut s = String::new(); |
| let mut f = CodeFormatter::new(&mut s, " "); |
| write!( |
| f, |
| r#" |
| struct Foo; |
| |
| impl Foo {{ |
| fn foo() {{ |
| todo!() |
| }} |
| }} |
| "#, |
| ) |
| .unwrap(); |
| assert_eq!( |
| s, |
| "struct Foo;\n\nimpl Foo {\n fn foo() {\n todo!()\n }\n}\n" |
| ); |
| |
| let mut s = String::new(); |
| let mut f = CodeFormatter::new(&mut s, " "); |
| write!( |
| f, |
| r#" |
| struct Foo; |
| |
| impl Foo {{ |
| fn foo() {{ |
| todo!() |
| }} |
| }}"#, |
| ) |
| .unwrap(); |
| assert_eq!( |
| s, |
| "struct Foo;\n\nimpl Foo {\n fn foo() {\n todo!()\n }\n}\n" |
| ); |
| } |
| |
| #[test] |
| fn indent() { |
| let mut s = String::new(); |
| let mut f = CodeFormatter::new(&mut s, " "); |
| f.indent(1); |
| write!( |
| f, |
| r#" |
| struct Foo; |
| |
| impl Foo {{ |
| fn foo() {{ |
| todo!() |
| }} |
| }} |
| "#, |
| ) |
| .unwrap(); |
| assert_eq!(s, " struct Foo;\n\n impl Foo {\n fn foo() {\n todo!()\n }\n }\n"); |
| } |
| |
| #[test] |
| fn inline() { |
| let mut s = String::new(); |
| let mut f = CodeFormatter::new(&mut s, " "); |
| write!( |
| f, |
| r#"struct Foo; |
| fn foo() {{ |
| }}"#, |
| ) |
| .unwrap(); |
| assert_eq!(s, "struct Foo;\n fn foo() {\n }"); |
| } |
| |
| #[test] |
| fn split_prefix() { |
| let mut s = String::new(); |
| let mut f = CodeFormatter::new(&mut s, " "); |
| writeln!(f).unwrap(); |
| assert_eq!(s, "\n"); |
| } |
| } |
