module Colorize
¶
With Colorize you can change the fore- and background colors and text decorations when rendering text
on terminals supporting ANSI escape codes. It adds the colorize method to Object and thus all classes
as its main interface, which calls to_s and surrounds it with the necessary escape codes
when it comes to obtaining a string representation of the object.
Its first argument changes the foreground color:
require "colorize"
"foo".colorize(:green)
100.colorize(:red)
[1, 2, 3].colorize(:blue)
There are alternative ways to change the foreground color:
require "colorize"
"foo".colorize.fore(:green)
"foo".colorize.green
To change the background color, the following methods are available:
require "colorize"
"foo".colorize.back(:green)
"foo".colorize.on(:green)
"foo".colorize.on_green
You can also pass an RGB color to colorize:
require "colorize"
"foo".colorize(Colorize::ColorRGB.new(0, 255, 255)) # => "foo" in aqua
Or an 8-bit color:
require "colorize"
"foo".colorize(Colorize::Color256.new(208)) # => "foo" in orange
It's also possible to change the text decoration:
require "colorize"
"foo".colorize.mode(:underline)
"foo".colorize.underline
The colorize method returns a Colorize::Object instance,
which allows chaining methods together:
require "colorize"
"foo".colorize.fore(:yellow).back(:blue).mode(:underline)
With the toggle method you can temporarily disable adding the escape codes.
Settings of the instance are preserved however and can be turned back on later:
require "colorize"
"foo".colorize(:red).toggle(false) # => "foo" without color
"foo".colorize(:red).toggle(false).toggle(true) # => "foo" in red
The color :default will just leave the object as it is (but it's an Colorize::Object(String) then).
That's handy in for example conditions:
require "colorize"
"foo".colorize(some_bool ? :green : :default)
Available colors are:
:default
:black
:red
:green
:yellow
:blue
:magenta
:cyan
:light_gray
:dark_gray
:light_red
:light_green
:light_yellow
:light_blue
:light_magenta
:light_cyan
:white
Available text decorations are:
:bold
:bright
:dim
:underline
:blink
:reverse
:hidden
Class methods¶
.enabled=(enabled : Bool)
¶
(enabled : Bool)
If this value is true, Colorize::Object is enabled by default.
But if this value is false, Colorize::Object is disabled.
The default value is true.
require "colorize"
Colorize.enabled = true
"hello".colorize.red.to_s # => "\e[31mhello\e[0m"
Colorize.enabled = false
"hello".colorize.red.to_s # => "hello"
.enabled? : Bool
¶
: Bool
If this value is true, Colorize::Object is enabled by default.
But if this value is false, Colorize::Object is disabled.
The default value is true.
require "colorize"
Colorize.enabled = true
"hello".colorize.red.to_s # => "\e[31mhello\e[0m"
Colorize.enabled = false
"hello".colorize.red.to_s # => "hello"
.on_tty_only!
¶
Makes Colorize.enabled true if and only if both of STDOUT.tty?
and STDERR.tty? are true and the tty is not considered a dumb terminal.
This is determined by the environment variable called TERM.
If TERM=dumb, color won't be enabled.
.with
¶
Helper method to use colorize with IO.
io = IO::Memory.new
io << "not-green"
Colorize.with.green.bold.surround(io) do
io << "green and bold if Colorize.enabled"
end