Ruby Paint
¶ ↑
Paint manages terminal colors and effects for you. It combines the strengths of term-ansicolor, rainbow and other similar projects into a simple to use, however still flexible terminal colorization gem with no core extensions by default.
Features¶ ↑
-
No string extensions (suitable for library development)
-
Simple API
-
Faster than other terminal color gems (as of October 2015)
-
Supports setting 256 colors (for capable terminals)
-
Supports setting any terminal effects
-
Fall-back modes for non-256-color terminals (
Paint.mode
), supported modes:-
256 colors
-
16 colors (only ansi colors, combined with bright effect)
-
8 colors (only ansi colors)
-
0 colors (deactivate)
-
Setup¶ ↑
Add to Gemfile:
gem 'paint'
and run `bundle install`
In Ruby do:
require 'paint'
Usage¶ ↑
The only method you need to know is: Paint.[]
The first argument given to Paint.[]
is the string to colorize
(if the object is not a string, to_s
will be called on it).
The other arguments describe how to modify/colorize the string. Let's
learn by example:
Paint['Ruby', :red] # sets ansi color red Paint['Ruby', :red, :bright] # also applies bright/bold effect Paint['Ruby', :bright, :red] # does the same as above Paint['Ruby', :red, :bright, :underline] # effects can often be combined Paint['Ruby', :red, :blue] # the second color you define is for background Paint['Ruby', nil, :blue] # pass a nil before a color to ignore foreground and only set background color Paint['Ruby', [100, 255, 5]] # you can define rgb colors that map to one of 256 colors. Only supported on 256-color terminals, of course Paint['Ruby', "gold", "snow"] # Paint supports rgb.txt color names, note that the arguments are strings (:yellow != "yellow")! Paint['Ruby', "#123456"] # html like definitions are possible. Paint['Ruby', "fff"] # another html hex definition Paint['Ruby', :inverse] # swaps fore- and background Paint['Ruby', :italic, :encircle, :rapid_blink, :overline] # probably not supported effects Paint['Ruby'] # don't pass any argument and the string will not be changed
When you pass multiple colors, the first one is taken as foreground color
and the second one defines the background color, every other will be
ignored. To only change the background color, you have to pass a
nil
first. Effects can be passed in any order.
You can find more examples in the specs.
Windows Support¶ ↑
For ANSI support in Windows OS, you can use ansicon or ConEmu.
More details about terminal colors and effects¶ ↑
Terminal colors/effects are set by ansi escape
sequences. These are strings that look like this:
\e[X;X;X;X;X]m
where X are integers with some meaning. For
example, 0 means reset, 31 means red foreground and 41 red background. When
you tell Paint to use one of the eight ansi base
colors as foreground color, it just inserts a number between 30 and 37 in
the sequence. The following colors are available:
:black, :red, :green, :yellow, :blue, :magenta, :cyan, :white, (:default)
When combined with the :bright
(= :bold
) effect,
the color in the terminal emulator often differs a little bit.
Through special sequences it's also possible to set 256-colors, instead of 8, which is also supported by many - but not all - terminals. Paint automatically translates given rgb colors to a suitable color of the 256 available colors.
When using the Paint.[]
method, Paint
wraps the given string between the calculated escape sequence and an reset
sequence ("\e[0m"
). You can get the raw escape
sequence by using the Paint.color
method.
Effects¶ ↑
Also see en.wikipedia.org/wiki/ANSI_escape_code:
Often supported¶ ↑
0) :reset, :nothing 1) :bright, :bold 4) :underline 7) :inverse, :negative 8) :conceal, :hide 22) :clean 24) :underline_off 26) :inverse_off, :positive 27) :conceal_off, :show, :reveal
Not widely supported¶ ↑
2) :faint 3) :italic 5) :blink, :slow_blink 6) :rapid_blink 9) :crossed, :crossed_out 10) :default_font, :font0 11-19) :font1, :font2, :font3, :font4, :font5, :font6, :font7, :font8, :font9 20) :fraktur 21) :bright_off, :bold_off, :double_underline 23) :italic_off, :fraktur_off 25) :blink_off 29) :crossed_off, :crossed_out_off 51) :frame 52) :encircle 53) :overline 54) :frame_off, :encircle_off 55) :overline_off
Paint.mode¶ ↑
You can choose between four ways to use Paint.[]
by setting
Paint.mode
to one of the following:
-
256: full support
-
16: don't use 256 colors, but the ansi eight ones (combined with bright effect)
-
8: don't use 256 colors, but the ansi eight ones
-
0: don't colorize at all
Paint tries to automatically detect the proper
value, please open an issue if Paint.detect_mode
yields a
wrong value for you.
Random ANSI Colors¶ ↑
With 1.0, the :random feature was removed, because it interfered with the caching mechanism. If you still need it, you will have to workaround by generating random colors yourself, before passing them into the Paint method:
Paint['Ruby', Paint.random] # get one of eight random ansi foreground colors Paint['Ruby', Paint.random(true)] # get one of eight random ansi background colors
Utilities¶ ↑
There are some supporting methods available. You can get a p
like alternative for calling puts Paint.[]
:
require 'paint/pa' pa "Ruby", :red, :underline # same as puts Paint["Ruby", :red, :underline]
Another helper method is Paint.unpaint
, which removes any ansi
colors:
Paint.unpaint( Paint['Ruby', :red, :bright] ).should == 'Ruby'
Advanced Usage: Shortcuts¶ ↑
There is an extension gem available that allows you to define custom color shortcuts. See SHORTCUTS.rdoc for more information.
J-_-L¶ ↑
Copyright © 2011-2016 Jan Lelis <janlelis.com>, released under the MIT license.
Mainly influenced by rainbow and term-ansicolor. Also see the list of contributors