Clio

Clio is an easy to use PHP class for styling PHP CLI programs. In general, you will want to create one Clio instance to represent the terminal in which it is controlling.

Clio will send out the appropriate escape sequencing (depending on the mode) to achieve the text display you are requiring. If you are specifying RGB colors, but have to deal with a terminal capability of less colors, Clio utilizes the Color object to get as close as possible to that color.

Modes

One of the important selections you must make is the terminal mode. This dictates the kind of escape programming that will be used behind the scenes, as well as the number of colors that are available. If you are working on a specific terminal, you can run the Color Test GitHub project to see the capability of your terminal. It is the only accurate way to determine the color mode of your terminal, as terminal modes and what they mean are notoriously inconsistent. They best way to know whether you can generate RGB colors is to try it on the emulator directly.

There are three Clio modes:

• Clio::RGB - This is less common, but gives you the full RGB color spectrum, currently the PHPStorm console window does support RGB
• Clio::XTERM - This is the most common capability, giving you 256 colors
• Clio::VT100 - This is supported everywhere, but giving you only 16 somewhat randomly selected colors (that worked well with 1980's hardware)

Clio::XTERM is the default mode.

Software Documentation

Clio inherits the methods of the Terminal Class located in the ANSI Terminal GitHub project in which it depends. Clio inherits the Terminal Class directly, so some of these methods come from that class.

Since there is a fair number of methods, they have been grouped as follows:

• Layout Methods
• Prompt Methods
• Styling Methods
• Typography Methods

Layout Methods

Constructor

Construct a clio object, set the mode to match the capabilities of your terminal. Set the default text and fill for the colors that should be the basic foreground and background, generally black text with white background, or cyan or green text with a black background, but can be whatever you want. Use the default of null if you want the terminal's default colors to stay as is.

The Clio class is a child of the Terminal Class.

__construct($mode = self::XTERM, $defaultTextColor = null, $defaultFillColor = null)

display

Display the text in whatever styling has been set.

display($text)

line

Display the text and hit a carriage return.

line($text)

newLine, nl, out

Hit the carriage return $count times.

newLine($count = 1)

clearScreen

Clear the screen and move cursor to the top.

clearScreen()

Prompt Methods

prompt

Prompt the user. If a default is supplied, it will return null if the default was selected, either by hitting the carriage return or typing the default as an answer.

[string] prompt($text, $default = null)

pause

Shortcut function to pause execution until the user hits return

pause()

promptForYes

Runs the prompt method, appending (y/n) to the prompt. It is looking for an answer of "y", "ye" or "yes" (any capitalization) for confirmation.

[string] promptForYes($text)

promptSelect

Runs the prompt method. It then provides the choices in a comma delimited list. It will highlight the characters needed for uniqueness. If the default is given and answered, null is returned.

[string] promptSelect($intro, $choices, $default = null)

Styling Methods

setStyle, style

Set the bold, underscore, text and fill colors based on a Style object.

setStyle(StyleInterface $style)

clear

Clear out the current styling. The text and fill will be set to the default colors set it in the constructor (or cleared out if no default is defined).

Clio doesn't actually send out the escape coding for styling until text is output, but if you need for the clear to go out right away (such as the end of a command line program), then set the $rightAway parameter to true. If not, it will be done during the next output (and combined with any subsequent styling you specify).

clear($rightAway = false)

Typography Methods

setBold, b

Either start or stop bolding text.

b($on = true)

setUnderscore, u

Either start or stop underscoring text.

u($on = true)

textColor, setTextColor

Start drawing text in a particular color.

textColor($color = null)

clearTextColor

Rest back to default text color (if one is specified).

clearTextColor()

fillColor, setFillColor

Start drawing fill (background) in a particular color.

fillColor($color = null)

clearFillColor

Reset back to default fill color (if one is specified).

clearTextColor()

colors

Start drawing text and fill in specified colors.

colors($textColor = null, $fillColor = null)