Tone

Table of Contents

As you saw earlier, you can encode plain text as colorized text using #[]. Use of the #[] method is an alias to the longer #encode method. This allows you to use minimal syntax to create colorized text. Here’s a few more examples:

The first argument is the text you want to encode/colorize. This can be a word, phrase, paragraph, or entire document. All arguments that follow after the first argument are style arguments which allow you to style the color of your text as you see fit. In this case, the "Success" text will use a black foreground on a green background. The styles available for you to use will be explained shortly, though. For now, know that #[] is shorthand for #encode so any of the above examples could be replaced with #encode messages. Example:

Both methods are available to use depending on your preference.

Once your text has been encoded with colors, it can be nice to decode the colorized text back to plain text along with additional metadata. This is helpful — as an example — for testing purposes since you might not always want to deal with the hard to read escape characters. If we build upon the examples from the Encode section, we can decode our colorized text into plain text with extra metadata:

Notice we get an array of sub arrays which mimic the original arguments passed to #encode. This allows you to encode and decode with minimal effort. Here’s a more complex example where a sentence is used and formatted with the Amazing Print gem:

For plain text, you get a single element array but for colorized text, it will be broken down into an array of arguments. This allows you to easily iterate over this structure for parsing, transformation, or pattern matching purposes.

Here’s another example where a paragraph is used:

To display defaults, use:

The above will output something similar to what you see below (minus the categorization) of key and value which will allow you to pick and choose the style or combination of styles you desire.

• Styles

  • clear

  • bold

  • dim

  • italic

  • underline

  • inverse

  • hidden

  • strikethrough

• Foregrounds

  • black

  • red

  • green

  • yellow

  • blue

  • purple

  • cyan

  • white

  • bright_black

  • bright_red

  • bright_green

  • bright_yellow

  • bright_blue

  • bright_purple

  • bright_cyan

  • bright_white

• Backgrounds

  • on_black

  • on_red

  • on_green

  • on_yellow

  • on_blue

  • on_purple

  • on_cyan

  • on_white

  • on_bright_black

  • on_bright_red

  • on_bright_green

  • on_bright_yellow

  • on_bright_blue

  • on_bright_purple

  • on_bright_cyan

  • on_bright_white

These are the defaults for which you can mix-n-match as desired to produce colorful output. For example, if you want black text on a green background with an underline, you could use:

You can alias combinations of default styles with a descriptive name for shorthand reuse. This allows you to reduce duplicated effort and speed up your workflow. Here are a few examples:

Notice that the first argument is your alias and all arguments after the first argument is the list of styles. Once added, both the :success and :failure aliases can immediately be used. You can also add multiple aliases, at once, by chaining your messages:

Aliases — and associated styles — can be symbols or strings. The following, despite using strings, is identical to the above:

To see the list of all aliases added, use:

To get a specific alias, use:

In the case of a default, you’ll only get back the given key:

There are several checks performed which might result in a Tone::Error if not properly used. Here’s a few examples of what you might see.

When using this gem in your project, you might find it convenient to use the have_color RSpec matcher. This matcher is optional and must be manually required for use in your spec helper:

Once required, you can leverage the matcher in any spec as follows:

The first argument must be an instanced of Tone because you might have custom aliases which must be known in order to validate your spec. All subsequent arguments (one to many) that follow after the first argument can be a list of decoded tuples as would normally be answered by Tone#decode.

In situations where the spec fails, you’ll get a formatted error so you can quickly fix as necessary:

The following are worth considering, when using this gem, to help keep your implementation consistent.

Order your arguments by style, foreground, and background when encoding:

Order your arguments by style, foreground, and background when adding aliases:

These are not hard requirements but these little touches will help improve readability. 🎉