[−][src]Crate tcprint
Structured, colorized printing to the terminal using termcolor.
The termcolor crate has been carefully designed to allow CLI tools to print colors to the terminal in a cross-platform fashion — while most color-print crates only work with Unix color codes, termcolor also works on Windows. While this is a valuable capability, the termcolor API is fairly low-level.
This crate provides a slightly higher-level interface that aims to be
convenient for basic use cases, and extensible when needed. First of all,
the relevant state is gathered into a single ColorPrintState
structure
that can be passed around your application. This comprises (1) handles to
color-capable standard output and error streams and (2) a palette of
pre-defined colors. Second, macros are provided that make it easier to
print output mixing a variety of colors.
Basic Usage
#[macro_use] extern crate tcprint; use tcprint::{BasicColors, ColorPrintState}; let mut state = ColorPrintState::<BasicColors>::default(); let q = 17; tcprintln!(state, [red: "oh no:"], (" q is: {}", q));
The above will print the line oh no: q is 17
, where the phrase oh no:
will appear in red. The arguments to the tcprintln!
macro are structured
as:
tcprintln!(state_object, clause1, ...clauseN);
Where each clause takes on one of the following forms:
(format, args...)
to print without applying colorization[colorname: format, args...]
to print applying the named color (seeBasicColors
for a list of what’s available in the simple case){color_var, {block}: format, args...}
to print applying a color that is determined on-the-fly, potentially using local variables to choose the color (seetcprint!()
for examples)
Along with tcprintln!()
, macros named tcprint!()
, etcprintln!()
, and
etcprint!()
are provided, all in analogy with the printing macros
provided with the Rust standard library.
Log-Style Messages
An additional macro named tcreport!()
is provided to ease the printing
of log messages classified as "info", "warning", or "error". TODO:
should play nice with the standard log API!:
tcreport!(state, warning: "could not locate puppy");
This will emit the text warning: could not locate puppy
, where the
portion warning:
appears in bold yellow by default. Other allowed
prefixes are info:
(appearing in green) and error:
(appearing in red).
Custom Palettes
To use a custom palette of colors, define your own struct with public
fields of type termcolor::ColorSpec
. Then use that struct instead of
BasicColors
when creating the ColorPrintState
struct. This crate
re-exports Color
and ColorSpec
from termcolor
for convenience in
doing so.
#[macro_use] extern crate tcprint; use std::default::Default; use tcprint::{Color, ColorSpec, ColorPrintState}; #[derive(Clone, Debug, Eq, PartialEq)] struct MyPalette { /// In this app, pet names should always be printed using this color specification. pub pet_name: ColorSpec, } impl Default for MyPalette { fn default() -> Self { // By default, pet names are printed in bold blue. let mut pet_name = ColorSpec::new(); pet_name.set_fg(Some(Color::Blue)).set_bold(true); MyPalette { pet_name } } } fn main() { let mut state = ColorPrintState::<MyPalette>::default(); let name = "Quemmy"; tcprintln!(state, ("the name of my dog is "), [pet_name: "{}", name], ("!") ); }
If you want to use tcreport!()
with your custom palette, it must
implement the ReportingColors
trait.
TODO: figure out locking plan!
Re-exports
pub use termcolor::Color; |
pub use termcolor::ColorSpec; |
Macros
etcprint | Print to standard error with colorization, without a trailing newline. |
etcprintln | Print to standard error with colorization and a trailing newline. |
tcprint | Print to standard output with colorization, without a trailing newline. |
tcprintln | Print to standard output with colorization and a trailing newline. |
tcreport | Print a colorized log message. |
Structs
BasicColors | A basic selection of colors for printing to the terminal. |
ColorPrintState | State for colorized printing. |
Enums
ReportType | A helper enumeration of different “report” (log level) types. |
Traits
ReportingColors | Specify colors to be used by the |