Rainbow
Rainbow is a ruby gem for colorizing printed text on ANSI terminals.
It provides a string presenter object, which adds several methods to your strings for wrapping them in ANSI escape codes. These codes when printed in a terminal change text attributes like text color, background color, intensity etc.
Usage
To make your string colored wrap it with Rainbow()
presenter and call
.color(<color name>)
on it.
Example
require 'rainbow'
puts Rainbow("this is red").red + " and " + Rainbow("this on yellow bg").bg(:yellow) + " and " + Rainbow("even bright underlined!").underline.bright
# => "\e[31mthis is red\e[0m and \e[43mthis on yellow bg\e[0m and \e[4m\e[1meven bright underlined!\e[0m"
Rainbow presenter API
Rainbow presenter adds the following methods to presented string:
color(c)
(withforeground
, andfg
aliases)background(c)
(withbg
alias)bright
underline
blink
inverse
hide
italic
(not well supported by terminal emulators).
Text color can also be changed by calling a method named by a color:
black
red
green
yellow
blue
magenta
cyan
white
aqua
silver
aliceblue
indianred
All of the methods return self
(the presenter object) so you can chain method
calls:
Rainbow("hola!").blue.bright.underline
String mixin
If you don't like wrapping every string you want to colorize with Rainbow()
you can include all the rainbow presenter methods directly in a String class by
requiring rainbow/ext/string
:
require 'rainbow/ext/string'
puts "this is red".color(:red) + " and " + "this on yellow bg".background(:yellow) + " and " + "even bright underlined!".underline.bright
This way of using Rainbow is not recommended though as it pollutes String's public interface with methods that are presentation specific.
NOTE: the mixin doesn't include shortcut methods for changing text color, you should use "string".color(:blue) instead of "string".blue
NOTE: the mixin is included in String by default in rainbow 1.x versions. In rainbow 2.x the behavior was changed - if you're upgrading from 1.x to 2.x and you used direct String methods then you can either require the string extension as shown above or update your code to use the new presenter API.
Color specification
Both color
and background
accept color specified in any
of the following ways:
-
ANSI color number (where 0 is black, 1 is red, 2 is green and so on):
Rainbow("hello").color(1)
-
ANSI color name or X11 color name as a symbol:
Rainbow("hello").color(:yellow)
. This can be simplified toRainbow("hello").yellow
See Color list for all available color names.
Note that ANSI colors can be changed in accordance with terminal setting.
But X11 color is just a syntax sugar for RGB triplet. So you always see what you specified. -
RGB triplet as separate values in the range 0-255:
Rainbow("hello").color(115, 23, 98)
-
RGB triplet as a hex string:
Rainbow("hello").color("FFC482")
orRainbow("hello").color("#FFC482")
When you specify a color with a RGB triplet rainbow finds the nearest match from 256 colors palette. Note that it requires a 256-colors capable terminal to display correctly.
Configuration
Rainbow can be enabled/disabled globally by setting:
Rainbow.enabled = true/false
When disabled all the methods return an unmodified string
(Rainbow("hello").red == "hello"
).
It's enabled by default, unless STDOUT/STDERR is not a TTY or a terminal is dumb.
Advanced usage
Rainbow()
and Rainbow.enabled
operate on the global Rainbow wrapper
instance. If you would like to selectively enable/disable coloring in separate
parts of your application you can get a new Rainbow wrapper instance for each
of them and control the state of coloring during the runtime.
rainbow_one = Rainbow.new
rainbow_two = Rainbow.new
rainbow_one.enabled = false
Rainbow("hello").red # => "\e[31mhello\e[0m" ("hello" if not on TTY)
rainbow_one.wrap("hello").red # => "hello"
rainbow_two.wrap("hello").red # => "\e[31mhello\e[0m" ("hello" if not on TTY)
By default each new instance inherits enabled/disabled state from the global
Rainbow.enabled
.
This feature comes handy for example when you have multiple output formatters in your application and some of them print to a terminal but others write to a file. Normally rainbow would detect that STDIN/STDERR is a TTY and would colorize all the strings, even the ones that go through file writing formatters. You can easily solve that by disabling coloring for the Rainbow instances that are used by formatters with file output.
Windows support
For Windows support on Ruby < 2.0, you should install the following gems:
gem install windows-pr win32console
If the above gems aren't installed then all strings are returned unmodified.
Installation
Add it to your Gemfile:
gem 'rainbow'
Or just install it via rubygems:
gem install rainbow
Color list
ANSI colors
black
red
green
yellow
blue
magenta
cyan
white
X11 colors
aqua
aquamarine
mediumaquamarine
azure
beige
bisque
blanchedalmond
darkblue
lightblue
mediumblue
aliceblue
cadetblue
dodgerblue
midnightblue
navyblue
powderblue
royalblue
skyblue
deepskyblue
lightskyblue
slateblue
darkslateblue
mediumslateblue
steelblue
lightsteelblue
brown
rosybrown
saddlebrown
sandybrown
burlywood
chartreuse
chocolate
coral
lightcoral
cornflower
cornsilk
crimson
darkcyan
lightcyan
firebrick
fuchsia
gainsboro
gold
goldenrod
darkgoldenrod
lightgoldenrod
palegoldenrod
gray
darkgray
dimgray
lightgray
slategray
lightslategray
webgray
darkgreen
lightgreen
palegreen
darkolivegreen
yellowgreen
forestgreen
lawngreen
limegreen
seagreen
darkseagreen
lightseagreen
mediumseagreen
springgreen
mediumspringgreen
webgreen
honeydew
indianred
indigo
ivory
khaki
darkkhaki
lavender
lavenderblush
lemonchiffon
lime
linen
darkmagenta
maroon
webmaroon
mintcream
mistyrose
moccasin
oldlace
olive
olivedrab
orange
darkorange
orchid
darkorchid
mediumorchid
papayawhip
peachpuff
peru
pink
deeppink
lightpink
hotpink
plum
purple
mediumpurple
rebeccapurple
webpurple
darkred
orangered
mediumvioletred
palevioletred
salmon
darksalmon
lightsalmon
seashell
sienna
silver
darkslategray
snow
tan
teal
thistle
tomato
turquoise
darkturquoise
mediumturquoise
paleturquoise
violet
darkviolet
blueviolet
wheat
antiquewhite
floralwhite
ghostwhite
navajowhite
whitesmoke
lightyellow
greenyellow