easy-sgr

An easy-to-use library for adding graphical ANSI codes or SGR escape sequences to your project. Its main strengths are the multitude of methods that are provided, and the lack of dependencies; compile times should be pretty good.

This library does not support the usage of non-SGR ANSI escape sequences

Installation

Add this to your Cargo.toml:

[dependencies]
easy-sgr="0.0.1"

Usage

Color and Style enums

The simplest way to color text, using these two enums allows you to work inline of a string literal when using a macro such as println!, writeln! or format!:

use easy_sgr::{Color::*, Style::*};

println!("{Italic}{RedFg}This should be italic & red!{Reset}");

Color and Style are both enums that implement Display: when they are printed a matching SGR code is written.

This method is the best when it comes to simplicity, but has drawbacks; using it rewrites the Escape sequence \x1b[ and the End sequence m repeatedly. In this example this is what would be written:

\x1b[3m\x1b[31mThis should be italic & red!\x1b[0m

This would not be much of an issue for the vast majority of use cases.

EasySGR trait

This is similar to the method above but uses the EasySGR trait. This trait is implemented by anything that implements Into<AnsiString> including Style and Color. Its main purpose is to provide functions for chaining SGR codes.

The example above can be achieved using it as such:

use easy_sgr::{ Color::*, EasySGR, Style::*};

let sgr = Italic.color(RedFg);

println!("{sgr}This should be italic & red!{Reset}");

Now the output would look something like this:

\x1b[31;3mThis should be italic & red!\x1b[0m

Instead of a rewriting the entire sequence, the separator character ; is used instead.

Doing this avoids the issue of rewriting the Escape and End sequences, though is more expensive to use as it allocates a SGRString.

SGRString struct

SGRString is the type returned by all EasySGR functions, it encapsulates all possible SGR sequences. You can use it to reproduce the previous examples as such:

use easy_sgr::{Color::*, EasySGR, Style::*};

let text = "This should be italic & red!"
    .to_sgr()
    .style(Italic)
    .color(RedFg);
println!("{text}");

You can forgo .to_sgr() as .style(..), .color(..) and all other EasySGR functions can be directly called on the string literal and other types that implement it.

The method above still uses the EasySGR trait, you can go without it like here:

use easy_sgr::{ColorKind, SGRString, StyleKind};

let mut text = SGRString::from("This should be italic & red!");
text.italic = StyleKind::Place;
text.foreground = ColorKind::Red;

println!("{text}")

SGRWriter trait

The writer can also be used directly, instead of using the above methods:

use std::io::{stdout, Write};
use easy_sgr::{Color::*, EasySGR, SGRWriter, StandardWriter, Style::*};

let mut writer = StandardWriter::io(stdout());
writer.sgr(&Italic.color(RedFg)).unwrap();
writer.write_inner("This should be italic & red!").unwrap();
writer.sgr(&Reset).unwrap();

or, when writing to a String

use easy_sgr::{Color::*, EasySGR, SGRWriter, StandardWriter, Style::*};

let stylized_string = {
    let mut writer = StandardWriter::fmt(String::new());
    writer.sgr(&Italic.color(RedFg)).unwrap();
    writer.write_inner("This should be italic & red!").unwrap();
    writer.sgr(&Reset).unwrap();
    writer.writer.0
};

Structure

easy-sgr is split into three modules:

• discrete
• graphics
• writing

Though no modules really will be seen in usage, as all the types they contain are reexported.

TODO

• Add inline that doesn't write escape itself
• Add get_writer method to writing module
• Create writing tests
• Add examples to docs
• Implement FromStr for SGR types
• Parser (deSGR)
• Macros (SGRise)
• EasySGR implementation that doesn't allocate a SGRString
• (maybe) create smart clean system