Styling

Clio was created to help in development of usable PHP command line interface (CLI) programs. Although there are no graphic capabilities for the command line, there are some things working in our favor. Monospaced fonts line up nicely and can be used to present data in a succinct way. For some terminal emulators (PHPStorm for one), you can use the full 24 bit RGB coloring, also making for interesting options.

When it comes to Typography, you only have four things you can control:

• Bolding
• Underlining
• Fill Color
• Text Color

There are a few classes that can be used to control these characteristics allowing you to use them consistently throughout your program allowing for a good design that improves your program's usability.

• Color - allows you to select a color, and depending on your terminal's color capability, the class will automatically command the terminal to show the closest color available.
• Style - allows you to create a style, that is a combination of bolding and underscoring and the text and fill colors, allowing for consistent styling.
• Markup - You associate any small string with a Style object. Then, whenever that string is encountered anywhere in the displayed text within any HTML class, that new styling will be triggered. When it is encountered again, it is turned off.

Example

Let's walk through an example using Colors, Styles and Markup.

Color

There are a couple of ways to create a color object. No matter the terminal mode, whether you can have a few colors or the full spectrum, Clio will try to match the color.

• RGB → $purple = new Color([38,2,128]);
• W3C Color Names → $steelBlue = new Color('Steel Blue') or Color::steelblue()

Style

From there, you can create Style objects, allowing you save a typography set. The four parameters of a Style object are:

• bold [boolean]
• underscore [boolean]
• textColor [Color]
• fillColor [Color]

Here is sample code to create and a style that represents code.

    $code = new Style(true, false, Color::lightseagreen(), Color::black());
    $clio->display("Here is some ")->style($code)->display("code")->clear();
        

And the terminal display of the text:

    Here is some code

Styles work independently, so if you use a new style, it replaces the old style entirely. If you want styles to layer, then use Markup, which allows previous styles to shine through.

Markup

A second way to style your PHP CLI program is to markup your text to change the styling inline. You associate any small string with a Style object. Then, whenever that string is encountered in paragraphs, tables and lists, that new styling will be triggered. When it is encountered again, it is turned off, such as:

    $clio->display("By default, two asterisks mean **bold** and two underlines means __underline__.");

Which will display like this:

    By default, two asterisks mean bold and two underlines means underline.

You can set up any symbol to mean any Style object. For example:

    $clio->addMarkupDefinition("!!",(new Style())->setColors("white","darkorange"));

    $clio->display("Pay attention to this !!word!!! and nothing else.")

Which will display like this:

    Pay attention to this word and nothing else.

The markup works in layers that can overlap, each markup starting and stopping individually. If a style does not specify a characteristic, such as underscore or fill color, then any other styles that have already been set will continue. For example, let's set up two styles:

    $royalBlue = new Style();
    $royalBlue->setTextColor("Royal Blue")->setUnderscore()

    $lavender = new Style()
    $lavender->setColors("Dim Gray","lavender")
        

Now let's set up the markup:

    $clio->addMarkupDefinition("[rb]",$royalBlue);
    $clio->addMarkupDefinition("^^",$lavender)
        

Now display some text with the styling in it

$clio->display("^^This is [rb]Royal Blue[rb], back to^^ normal.");

    This is Royal Blue, back to normal.
        

Software Documentation

The following sections lists the software documentation for:

• Color
• Style
• Markup

Color Class

The Color class represents one color. It knows the correct escape coding for any color in the three different terminal modes:

• Mode::VT100, "VT100", 16 - old-style VT100 terminal with just 16 basic colors
• Mode::XTERM, "xterm", 256 - very common xterm (such as bash) providing 256 colors
• Mode::RGB, "RGB", >256 - Test your terminal and if you can use this mode, then the color will be true

If you specify a color that is not represented in the lesser modes (VT100 and xterm), then Clio will match the closest color within that set. So, for example, if you want to use Maroon, but are running in xterm mode, Clio will pick xterm 88 which close to maroon.

Lastly, you can ask Clio for the best contrasting color (see getContrastColor) for a particular color. It will return a color object that is black or white. For all the W3C colors, this has been well tested and can be seen on the W3C Colors page. For all other colors specified through [R,G,B] it'll be right most of the time.

Constructor

Construct a color object, there are many ways to indicate a color:

• ColorInterface - another object implementing the ColorInterface (such as Color)
• String - a ">W3C Color name either as one string in the spec "darkblue" or a human readable version "Dark Blue"
• Integer - a number between 0 - 255 to specify a (somewhat random) xterm color, see Color Test for more about xterm colors
• Integer array - an RGB array consisting of [R,G,B]. The color object will then take that RGB and figure out the closest matching VT100 color and xterm color to match whatever mode your place your terminal.

__construct($color)

setEmpty

Set the Color object to empty.

setEmpty()

isEmpty

Whether a color object is empty.

Returns boolean indicating whether the color is empty.

[boolean] isEmpty()

isValid

Whether the color holds a valid color.

Returns boolean indicating whether the color is valid.

[boolean] isValid()

getName, getHumanName

Get the W3C name of the color, either in W3C form "darkblue" or human readable form "Dark Blue"

Returns a string if valid or null if not.

[string | null] getName()
[string | null] getHumanName()

getANSICode, getXTermCode, getRGB

Get the escape codes for the colors depending on the terminal mode.

For getANSICode and getXTermCode, it returns an integer to represent the code, for RGB it returns an array of integers [R,G,B]

[integer] getANSICode()
[integer] getXTermCode()
[R,G,B] getRGB()

getContrastColor

For the color stored in the object, return either a black or white color object that would serve as the best contrasting color. So, for example, for yellow, it would return black, for dark blue, it would return white. This was determined at first mathematically, then tweaked based on a RGB capability terminal (PHPStorm) on a true color 4K monitor.

Returns a either a black or a white color object, defaulting to black if a problem occurs.

[Color] getContrastColor()

red(), green(), antiquewhite(), etc...

For each of the W3C color names, there is a method for each color name.

blue()
lime()
chocolate()
...all the valid W3C color names

As well as the gray colors from the xterm grays...
gray8()
gray18()
...
gray238()

next, Previous

Return the next or previous color on the W3C Colors list.

Returns a Color object for the next or Previous color on the list, null if it is not a valid color or not a W3C color.

[Color] next() [Color] previous()

Style Class

The Style class stores the styling capability of a terminal. Namely,

• Bold
• Underscore
• Text Color
• Fill Color

Styles can be used to switch Clio's styling output. It can be sent in temporarily for a section of text, or pushed onto a stack and pulled off later.

Constructor

Construct a style object. You can specified an initial bold, underscore, text and fill color if desired.

__construct($bold = null, $underscore = null, ColorInterface $textColor = null, ColorInterface $fillColor = null)

overrideMembersTo

Copy one style object into another. However, if any property is set to null then the receiving object's property is unchanged.

overrideMembersTo(StyleInterface $style)

clearStyling

Clear out all stying. All properties are set to null.

clearStyling()

setBold, clearBoldStyling, getBold, isBoldOn

The bolding property, it is has three states: null, false, true. Null indicates that it has no effect on the current state of either Clio or another style object, true/false is whether the bolding is turned on or off.

setBold($on = true)
clearBoldStyling()
[null/true/false] getBold()
[true/false] isBoldOn()

setUnderscore, clearUnderscoreStyling, getUnderscore, isUnderscoreOn

The underscoring property, it is has three states: null, false, true. Null indicates that it has no effect on the current state of either Clio or another style object, true/false is whether the underscoring is turned on or off.

setUnderscore($on = true)
clearUnderscoreStyling()
[null/true/false] getUnderscore()
[true/false] isUnderscoreOn()

normal

Set the font styling to normal, turning bold and underscore off.

normal()

setTextColor, getTextColor, getTextColorName, hasTextColor, clearTextColor

The Text Color property

setTextColor($color)
[Color] getTextColor()
[string]getTextColorName()
[boolean] hasTextColor()
clearTextColor()

setFillColor, getFillColor, getFillColorName, hasFillColor, clearFillColor

The fill color property.

setFillColor($color)
[Color] getFillColor()
[string]getFillColorName()
[boolean] hasFillColor()
clearFillColor()

setColors, reverseColors

Set both the text and fill colors at once, or reverse the text and fill colors.

colors($textColor, $fillColor)
reverseColors()

Markup

Constructor

Construct a Markup object.

__construct($symbol, $style)