dye¶ ↑

Easy ANSI code coloring for strings in libraries.

Synopsis¶ ↑

require 'dye'

# you can directly use Dye.dye for basic styles
Dye.dye "a red bold underlined text on white background", :red, :bold, :underline, :onwhite

# you can define custom styles in your classes or modules
module MyModule
  extend self
  CUSTOM_STYLES = { :errorize => [ :red, :bold, :underline ],
                    :mysgr => [ :red, 8 ] }
  define_dye_method CUSTOM_STYLES
end

# use the custom styles
MyModule.dye "an error string", :errorize
MyModule.dye "my native (Select Graphic Rendition) string", :mysgr

# and use also the basic styles
MyModule.dye "red bold string", :red, :bold

# or use mixed custom and basic
MyModule.dye "red bold string", :mysgr, :bold

# you can eventually modify/add to the custom styles
CUSTOM_STYLES[:another] = [:green, :bold]
# and the style will be available right away
MyModule.dye "another style", :another

# you can also define the dye method as an instance method
any_instance.class.define_dye_method custom_styles

# and use it on the instance
any_instance.dye "any string", :any_style

# alternative no-color string
Dye.dye '    reversed    ', '=== reversed ===', :reversed

# back to plain text
plain_text = Dye.strip_ansi(ansi_string)

# raw SGR escape sequences
Dye.sgr(:cyan) #=> "\e[36m"
# strict_ansi?
Dye.sgr(:cyan, :bold) #=> "\e[36;1m"
# !strict_ansi?
Dye.sgr(:cyan, :bold) #=> "\e[36m\e[1m"

Features¶ ↑

Does not define methods in String
Allows you to set basic styles by just requiring the lib
Allows you to easily add your own custom styles
Allows extended (Select Graphic Rendition) parameters

Difference with the Colorer gem¶ ↑

The Colorer gem is meant for using in your own application, it’s a cool way to style string, but it is not the perfect fit for libraries. Indeed it defines an instance method for each style, and that might clash if another library defines the same style. That’s not a problem for applications.

The Dye gem instead does not have the same problem, although its syntax is not so cool as the Colorer’s one.

Basic Styles List¶ ↑

clear
bold
underline
blinking
reversed
black
red
green
yellow
blue
magenta
cyan
white
onblack
onred
ongreen
onyellow
onblue
onmagenta
oncyan
onwhite

Custom Styles¶ ↑

You can define your own custom styles by aggregating any basic styles names, besides can also add native SGR (Select Graphic Rendition) parameters (0..109) to any style:

custom_styles = { :errorize => [ :red, :bold, :underline ],
                  :okize => [ :green, :bold ],
                  :crazyize => [ :magenta, :onyellow, :bold, :underline ],
                  :mysgr => [ :red, 8 ] }
define_dye_method custom_styles

See en.wikipedia.org/wiki/ANSI_colors for a complete list of SGR codes.

Strict ANSI¶ ↑

Some terminals don’t parse composite SGR styles correctly, and need separate SGR for each.

puts "\e[7;31;46mSTRING\e[0m"         # strict_ansi == true (may be difficult to parse)
puts "\e[7m\e[31m\e[46mSTRING\e[0m"   # strict_ansi == false

On the other way most of the terminals that parse them correctly can parse also separate SGRs, so Dye will output non strict ansi by default. If you want to have strict ansi you can do:

Dye.strict_ansi = true

or you can set the DYE_STRICT_ANSI environment variable for a system wide setting.

Color¶ ↑

The color is true by defealut on a non-dumb tty terminal, anyway you can force it by explicitly setting it:

Dye.color?         #=> true/false by default depending on your terminal
Dye.color = true   # force true
Dye.color?         #=> true
Dye.color = false  # force false
Dye.color?         #=> false

ddnexus/dye