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

colorize.cr:119
colorize.cr:222

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

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

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

def self.default_enabled?(stdout : IO, stderr : IO = stdout) : Bool #

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

This is true if both streams are terminals (i.e. `IO#tty?` returns true), the `TERM` environment variable is not equal to `dumb`, and the `NO_COLOR` environment variable is not set to a non-empty string.

def self.enabled=(enabled : Bool) #

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

    require "colorize"

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

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

NOTE This is by default enabled if `.default_enabled?` is true for `STDOUT` and `STDERR`.

def self.enabled? : Bool #

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

    require "colorize"

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

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

NOTE This is by default enabled if `.default_enabled?` is true for `STDOUT` and `STDERR`.

def self.on_tty_only! : Bool #

Resets `Colorize.enabled?` to its initial default value, i.e. whether `.default_enabled?` is true for `STDOUT` and `STDERR`. Returns this new value.

This can be used to revert `Colorize.enabled?` to its initial state after colorization is explicitly enabled or disabled.

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

def self.reset(io = STDOUT) #

Resets the color and text decoration of the io.

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

def self.with : Colorize::Object(String) #

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