[−][src]Crate bunt

This crate offers a couple of macros to easily print colored and formatted text to a terminal. It is basically just a convenience API on top of termcolor. Thus, some understanding of termcolor is useful to use bunt.

Mini example:

let ty = "u32";
bunt::println!("{$bold+red}error:{/$} invalid value for type `{[blue]}`", ty);

Format string syntax

The macros in this crate have almost the same syntax as the corresponding std::fmt macros: arguments are inserted with {} and braces are escaped with {{ and }}. bunt has two additions to that syntax:

Style tags

With {$style_spec}...{/$}, you can apply a style to a section of your string (which can also contain arguments). The start tag {$...} contains the style specification, while the end tag is always {/%}. These tags can also be nested.

bunt::println!("normal color ... {$yellow}Yellow :){/$} ... normal color again");
bunt::println!("{$bold}This is bold. {$red}This is also red!{/$} Just bold again{/$}.");

Each opening tag needs a matching closing one and the other way around.

ⓘThis example deliberately fails to compile
bunt::println!("{$red}unclosed tag :o");
ⓘThis example deliberately fails to compile
bunt::println!("{$red}close it once{/$} and close it another time 🙁 {/$}");

Styled arguments

If you want to style an argument, you can use tags right before and after that argument. However, there is also a shorthand syntax: {[style_spec] ...}. You can still use the syntax for named arguments, positional arguments, width, fill/alignmen, precision, formatting traits and everything else from std::fmt after the [...].

// Normal output via `Display`. Equivalent to `"value: {$green}{}{/$}"`
bunt::println!("value: {[green]}", 27);

// Output via `Debug`. All argument formatting syntax from `fmt` works
// inside the braces, after the `[...]`.
bunt::println!("value: {[green]:?}", vec![1, 2, 3]);

// Named argument + precision specified: works.
bunt::println!("value: {[green]foo:.5}", foo = 3.14);

Note: Currently, it is not yet possible to refer to parameters for the "precision" or "width" value. So, println!("Hello {1:0$}!", 5, "x");" will fail to compile right now.

Style specification

bunt has the same capabilities as termcolor. See termcolor::Color and termcolor::ColorSpec for more information. The syntax for style specs in bunt is a simple list of fragments that are joined by +. Examples:

  • red
  • #ff8030+bold
  • yellow+italic+intense
  • bg:white+blue+bold

Full list of allowed fragments:

  • Colors:
    • black, blue, green, red, cyan, magenta, yellow, white
    • RGB as hex string: #rrggbb, e.g. #27ae60
  • Background colors: same as colors but prefixed with bg:, e.g. bg:blue or bg:#c0392b
  • Attributes:
    • bold
    • italic
    • underline
    • intense

bunt macros make sure that your style spec makes sense (only one foreground/background color is allowed, duplicated attributes are not allowed). Invalid style specs result in a compile error.

ⓘThis example deliberately fails to compile
bunt::println!("{$red+blue}what{/$}");
ⓘThis example deliberately fails to compile
bunt::println!("{$bold+red+bold}you don't have to say it twice buddy{/$}");

Available macros

  • write and writeln: print to a termcolor::WriteColor instance.
  • print and println: print to stdout.
  • style: parses a format specification and returns the corresponding termcolor::ColorSpec value.

In larger applications, you should probably use write! and writeln! to have more control over how the stdout handle is created.

Re-exports

pub extern crate termcolor;

Macros

print

Writes formatted data to stdout (with ColorChoice::Auto).

println

Writes formatted data with newline to stdout (with ColorChoice::Auto).

style

Parses the given style specification string and returns the corresponding termcolor::ColorSpec value.

write

Writes formatted data to a termcolor::WriteColor target.

writeln

Writes formatted data with newline to a termcolor::WriteColor target.