Colsole

Utility functions for colorful console applications.

Upgrade Note

• Version 1.0.x is not compatible with older versions
• Version 0.8.x is compatible with both the old syntax and new syntax

See Upgrading below.

Add to your Gemfile:

$ gem 'colsole', '>= 0.8.1', '< 2.0'

require 'colsole'
include Colsole
say 'b`Blue` Man Group'

All the methods described below can also be called directly on the Colsole module. This is useful when you want to use it at the top level of your project, without namespace contamination:

require 'colsole'
Colsole.say 'b`Blue` Man Group'

See the Examples file.

An alternative to puts with line wrapping, colors and more.

say "Hello"

Leave a trailing space to keep the cursor at the same line

say "appears in "
say "one line"

Embed color markers in the string:

say "This is r`red`, and this gu`entire phrase is green underlined`"

Provide the replace: true option after a space terminated "said" string to rewrite the line:

# space terminated string to say it without a newline
say "downloading data... "
# long process here...
say "download complete.", replace: true

Wrap long lines while keeping words intact, and keeping indentation based on the leading spaces in your string:

say word_wrap("    one two three four five", 15)

# output:
#    one two
#    three four
#    five

If length is not provided, word_wrap will attempt to determine it automatically based on the width of the terminal.

Use say! to output to stderr with color markers:

# red inverted ERROR
say! "ri` ERROR ` This just did not work"

Parses and returns a color-flagged string.

Returns true if we are running in an interactive terminal

Checks if the provided string is a command in the path.

Returns an array [width, height] of the terminal, or the supplied fallback if it is unable to detect.

Returns only the terminal width or height. This is a shortcut to terminal_size[0] / terminal_size[1].

Strings that are surrounded by backticks, and preceded by a color code and optional styling markers will be converted to the respective ANSI color.

say "this is b`blue` and ru`this is red underlined`"

The one letter color code is required, followed by up to 3 style code.

Version 0.8.x changes several things, including the syntax of the color markers. For easy transition, it is compatible with older versions.

Follow these steps to upgrade:

# => Require a more flexible version
# change this
gem 'colsole'
# to this
gem 'colsole', '>= 0.8.1', '< 2.0'

# => Remove 'say_status'
# It will no longer be supported in 1.0.0
say_status "text"

# => Replace 'resay'
# 'resay' is replaced with 'say replace: true'
# change this
resay "text"
# to this
say "text", replace: true

# => Change color markers syntax
# replace this
say "the !txtblu!blue"
# with this
say "the b`blue`"