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.