Easy ANSI code coloring for strings in libraries
Ruby
Switch branches/tags
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
lib
test
.gitignore
LICENSE
README.rdoc
VERSION
dye.gemspec

README.rdoc

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

Copyright

Copyright © 2010-2012 Domizio Demichelis. See LICENSE for details.