module Colorize

Overview

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.

NOTE To use Colorize, you must explicitly import it with require "colorize"

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(0, 255, 255)      # => "foo" in aqua
"foo".colorize.fore(0, 255, 255) # => "foo" in aqua

# This is the same as:

"foo".colorize(Colorize::ColorRGB.new(0, 255, 255))      # => "foo" in aqua
"foo".colorize.fore(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
"foo".colorize.fore(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 leaves the object's representation as it is but the object is a Colorize::Object then which is handy in conditions such as:

require "colorize"

"foo".colorize(Random::DEFAULT.next_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

See Colorize::Mode for available text decorations.

Defined in:

Class Method Summary

• .default_enabled?(stdout : IO, stderr : IO = stdout) : Bool

  Returns whether colorization should be enabled by default on the given standard output and error streams.

• .enabled=(enabled : Bool)

  Objects will only be colored if this is true, unless overridden by Colorize::Object#toggle.

• .enabled? : Bool

  Objects will only be colored if this is true, unless overridden by Colorize::Object#toggle.

• .on_tty_only! : Bool

  Resets Colorize.enabled? to its initial default value, i.e.

• .reset(io = STDOUT)

  Resets the color and text decoration of the io.

• .with : Colorize::Object(String)

  Helper method to use colorize with IO.

Class Method Detail

require "colorize"

Colorize.enabled = true
"hello".colorize.red.to_s # => "\e[31mhello\e[0m"

Colorize.enabled = false
"hello".colorize.red.to_s # => "hello"

require "colorize"

Colorize.enabled = true
"hello".colorize.red.to_s # => "\e[31mhello\e[0m"

Colorize.enabled = false
"hello".colorize.red.to_s # => "hello"

io = IO::Memory.new
Colorize.with.green.surround(io) do
  io << "green"
  Colorize.reset(io)
  io << " default"
end

io = IO::Memory.new
io << "not-green"
Colorize.with.green.bold.surround(io) do
  io << "green and bold if Colorize.enabled"
end