module Colorize

Overview

WithColorize you can change the fore- and background colors and text decorations when rendering text on terminals supporting ANSI escape codes. It adds thecolorize method toObject and thus all classes as its main interface, which callsto_s and surrounds it with the necessary escape codes when it comes to obtaining a string representation of the object.

NOTE To useColorize, you must explicitly import it withrequire "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 tocolorize:

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

Thecolorize method returns aColorize::Object instance, which allows chaining methods together:

require "colorize"

"foo".colorize.fore(:yellow).back(:blue).mode(:underline)

With thetoggle 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 aColorize::Object then which is handy in conditions such as:

require "colorize"

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

SeeColorize::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 istrue, unless overridden byColorize::Object#toggle.

• .enabled? : Bool

  Objects will only be colored if this istrue, unless overridden byColorize::Object#toggle.

• .on_tty_only! : Bool

  ResetsColorize.enabled? to its initial default value, i.e.

  DEPRECATED This method is obsolete because it's the default behaviour since Crystal 1.17 (#15881). For resetting a previous override, useColorize.enabled = Colorize.default_enabled?(STDOUT, STDERR).

• .reset(io = STDOUT)

  Resets the color and text decoration of theio.

• .with : Colorize::Object(String)

  Helper method to use colorize withIO.

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