Struct Formatter

pub struct Formatter { /* private fields */ }

Text formatter with span highlights.

This allows you to format a given input char stream with highlights and colors (if the colors feature is enabled). A Highlight is defined by a Span, a string label and a Style, and will be rendered with the stream:

1 | fn main() {
2 |     println!("Hello World!")
  |              ^^^^^^^^^^^^^^ highlighting this string
3 | }

Highlights spans can cover multiple lines and overlap. See the Highlight documentation for more informations.

Implementations

impl Formatter

pub fn new() -> Self

Create a new formatter with no highlights.

Note

By default line numbers are shown. You can disable them using the hide_line_numbers method.

pub const fn with_margin_color(margin_color: Color) -> Self

Create a new formatter with no highlights and the specified margin color.

Note

By default line numbers are shown. You can disable them using the hide_line_numbers method.

pub fn set_line_numbers_visible(&mut self, visible: bool)

By default, line numbers are shown in a margin in the left side of the rendered text, like this:

1 | fn main() {
2 |     println!("Hello World!")
  |              ^^^^^^^^^^^^^^ highlighting this string
3 | }

The margin_color attribute is used to decorate the margin text (blue by default). You can use this function to enable or disable this functionality. Without line numbers, the previous example will look like this:

fn main() {
    println!("Hello World!")
             ^^^^^^^^^^^^^^ highlighting this string
}

pub fn show_line_numbers(&mut self)

Show the line numbers (this is the default).

pub fn hide_line_numbers(&mut self)

Hide the line numbers.

pub fn set_viewbox(&mut self, viewbox: Option<usize>)

Set the viewbox (default is 2).

The viewbox is used to ommit non-important lines from the render. A line is considered important if it is included at the start or end of an highlighted span. In the below example, lines 1 and 12 are important. With a viewport of 2, the two lines around important lines will be visible, and the other ommited. In this example, lines 4 to 9 are ommited.

 1 |   fn main() {
   |  __________^
 2 | |     some code;
 3 | |     more code;
.. | |
10 | |     more code;
11 | |     more code
12 | | }
   | |_^
13 |
14 |   fn another_function {

Here is the same example with a viewbox of 1:

 1 |   fn main() {
   |  __________^
 2 | |     some code;
.. | |
11 | |     more code
12 | | }
   | |_^
13 |

You can disable the viewbox all together by passing None to this function. In this case, all the lines will be visible.

pub fn add(&mut self, span: Span, label: Option<String>, style: Style)

Add a span highlight.

pub fn span(&self) -> Option<Span>

Returns the smallest span including every highlights.

impl Formatter

pub fn margin_len(&self, span: &Span) -> usize

Get the margin length (containing the line numbers) for the given span.

If line numbers are disabled, this will return 0.

pub fn render<E, I: Iterator<Item = Result<char, E>>, M: Metrics>( &self, input: I, span: Span, metrics: &M, ) -> Result<Formatted, E>

Render the given input stream of character. The result implements Display and can then be printed.

let file = File::open("examples/fib.txt").unwrap();
let chars = utf8_decode::UnsafeDecoder::new(file.bytes());
let metrics = DEFAULT_METRICS;
let buffer = SourceBuffer::new(chars, Position::default(), metrics);

let mut fmt = Formatter::with_margin_color(Color::Blue);
fmt.add(buffer.span(), None, Style::Error);

let formatted = fmt.render(buffer.iter(), buffer.span(), &metrics).unwrap();
println!("{}", formatted);

Trait Implementations

impl Default for Formatter

fn default() -> Formatter

Returns the “default value” for a type.