Get Started

Installation

To install via Composer:

composer require 1happyplace/clio

Or if you are not using composer, you can download it on the GitHub Repository: 1HappyPlace/clio.

Examples

The following sections show different examples of using Clio and the subsequent output.

Hello World

Start with a simple Hello World!:

Hello World!
    $clio = new Clio();
    $clio->line("Hello World!");
    

Learn about Escape Sequences

ANSI (American National Standards Institute) Escape Sequences are a method in which you can add styling to your shell program output (such as bash). It started back in the 1970’s in the hardware design of terminals used for mainframes. These terminals had no memory or ability to store programs. They were connected via serial port, which means that bits were sent to the device one at a time.

Simply sending characters to a screen did not allow for much typography or good user interface design. The hardware engineers then devised specific sequences sent inside the stream of characters, called in-band signalling. Those special character sequences hidden in the displayed character stream would then cause basic typographical methods, such as bold, underscoring, and if the terminal was physically able, text colors and fill.

Those hidden character sequences started with characters that would not be used for regular output, such as the escape code (ASCII 27). There was no reason for a computer to draw an escape character on the screen, so it was clear if an escape came down the pipe, it meant that a escape sequence was starting.

Each manufacturer came up with their own sequence protocol, so anytime a software engineer was programming a user interface for a terminal, it was for that specific make and model of the terminal. Obviously, that was not going to last.

DEC VT100 terminal

DEC VT100 terminal" by Jason Scott - Flickr: IMG_9976. Licensed under CC BY 2.0 via Wikimedia Commons

Along comes the Digital Equipment Corporation (DEC) terminal, the VT-100. It was widely popular, with a sturdy design and the satisfying clickety clack of keys. In time, there were other terminal manufacturers jumping on the bandwagon and they would adhere to the specific VT-100 terminal sequences, since so much software was already built with those sequences. After awhile, the ANSI group adopted a standard for all terminal output which was based on the VT-100 sequences.

Why is any of this important now in the 21st century? Back in the 1970’s and 80’s when escape sequencing standard was taking hold, Unix was exploding onto the scene, so the unix console adopted the VT-100 standard and it still lives with us today. In most shells, in order to spruce up your shell scripting output, you need to send these sequences to utilize better typography.

If you have access to a shell, try this:

echo -e “\e[4,36mHello\e[0m World!"

If your shell works appropriately, you should see:

Hello World!

And you have just created your first ANSI control sequence:

One of the oddities of the escape sequencing is the inability to turn off a single style. If a setting needs to be turned off, then all settings are cleared and it is necessary to reinstate the remaining styles.

For example, if both bold and underscore are active:<\p> echo -e "\e[1;4mBold and Underscored text"

in order to clear the bolding, the following sequence is necessary:

echo -e “\e[0m"
echo -e "\e[4m"

The first line clears all styling, the second one reinstates underscoring. Or, it can be combined into one statement:

echo -e “\e[0;4m"

The following table shows all the escape sequencing standard. There are generally three tiers of capability for a particular terminal type. Clio differentiates them by the following categories:

The table shows the escape sequence, followed by a range for any variables, the standard that started it, and a description of the effect of the sequence.

Escape Sequence Range Standard Description
\e[0m VT-100 Clear all formatting
\e[1m VT-100 Start bolding
\e[4m VT-100 Start underscoring
\e[3Xm 30-37 VT-100 Start showing text in the following basic colors, black, red, green, yellow, blue, magenta, cyan and light gray
\e[4Xm 40-47 VT-100 Start showing fill in the following basic colors, black, red, green, yellow, blue, magenta, cyan and light gray
\e[9Xm 90-97 VT-100 Start showing text in the following extended colors, gray, bright red, bright green, bright yellow, bright blue, bright magenta, bright cyan and white
\e[10Xm 100-107 VT-100 Show fill in the following extended colors, gray, bright red, bright green, bright yellow, bright blue, bright magenta, bright cyan and white
\e[38;5;Xm 0-255 xterm Set text color in the array of 256 xterm colors (use Color Test to check if available on your terminal)
\e[48;5;Xm 0-255 xterm Set fill color in the array of 256 xterm colors (use Color Test to check if available on your terminal)
\e[38;2;R;G;Bm 0-255 for each of the R, G, and B RGB Set text color in the full RGB spectrum (use Color Test to check if available on your terminal)
\e[48;5;Xm 0-255 RGB Set fill color in the full RGB spectrum (use Color Test to check if available on your terminal)