# 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.

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

##
Defined in:

##
Class Method Summary

- .enabled=(enabled : Bool)

  If this value is `true`, `Colorize::Object` is enabled by default.

- .enabled? : Bool

  If this value is `true`, `Colorize::Object` is enabled by default.

- .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.

- .reset(io = STDOUT)

##
Class Method Detail

def self.enabled=(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"

def self.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"

def self.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.

def self.reset(io = STDOUT) #