README

Using ANSI escape codes, you can add color and formatting to terminals used by php5-cli. Simple-Ansi-Escape is a simple class to turn the arcane ANSI escape codes into friendly aliases that are easy to remember.

Simple-Ansi-Escape tries to be intuitive as possible and is very flexible in its parameters. As the name implies, it is also very simple. There is only one class definition that contains one static public method, ansiEscape(). Simple-Ansi-Escape supports most standard ANSI escape codes and some nonstandard ones. It does not, however, support xterm-256 extensions (yet).

Simple Usage

A separate, more in-depth and hands-on tutorial is distributed with the repository, see extras/tutorial.php. Run it, and read the source code.

There is a single class, SimpleAnsiEscape that defines one static public function, SimpleAnsiEscape::ansiEscape(). If you are using a PSR-4 compatible auto-loader, you can get started with some gaudy yellow blinking text with just two lines:

use SimpleAnsiEscape\SimpleAnsiEscape as esc;
echo esc::ansiEscape('color/yellow, blink', "I hope you enjoy Simple-Ansi-Escape!");

The full prototype is, in namespace SimpleAnsiEscape:

SimpleAnsiEscape::ansiEscape( [ array|string $formatting, [ $wrapAround = null ] ] )

::ansiEscape() tries to be very flexible in what you pass it. The first parameter can be either an array with one or more array elements, or a string. In its array form, each array element should correspond to a single escape alias such as "color/yellow" in the previous example. In its string form, you can pass comma-, space- or semicolon-delimited escape aliases. Examples:

// In the array form, one-parameter syntax:
echo esc::ansiEscape(array('color/blue', 'faint', 'underline')), "I hope you enjoy Simple-Ansi-Escape!");

// The same thing, as a string:
echo esc::ansiEscape('color/blue, faint, underline', "I hope you enjoy Simple-Ansi-Escape!");

// You can use commas, spaces, or semi-colons as well.  Although it looks poor, even
// mixing and matching will not confuse Simple-Ansi-Escape:
echo esc::ansiEscape('color/red faint; underline, bold', "I hope you enjoy Simple-Ansi-Escape!");

With no parameters, it is synonymous with `::ansiEscape('reset')`` and will reset all open-ended formatting.

You can also use ::ansiEscape() with a single parameter to output only the escape codes. When called with a single parameter, no ANSI reset is called automatically. While you need to call reset yourself (by calling ::ansiEscape() with no parameters), but it makes nesting a lot easier:

Note that you cannot nest within the same function call, but it's easy to nest using a couple of extra calls:

// This is INCORRECT.  The inner escape will terminate formatting and ' properly' will be
// in the default terminal style.
echo esc::ansiEscape(
    'text/green', 
    "This is NOT how you " . esc::ansiEscape('bold', 'nest') . " properly!"
);

// This is CORRECT.  We're build the value in the proper linear order:
echo esc::ansiEscape('text/green') . "This is how you ". esc::ansiEscape('bold')
    . "properly " . esc::ansiEscape('~bold') . "next formatting." . esc::ansiEscape();

Always reset

A final note: when using ANSI escape codes, you are sending tiny textual sequences that are interpreted by your terminal. The terminal has no knowledge of when php5-cli terminates; therefore, you must ensure you do not have any open-ended escape codes, or your formatting will spill out into the terminal, even after your script terminates.

If you have a colorful PS1 shell environmental variable, you may not notice this, so please be mindful. During development, if you make a mess of your terminal, simply run the reset shell command to start over fresh.

Formatting Syntax, Names

You can use the characters ~, ! or ^ for negate. For example ~bold, !bold and ^bold are all equivalent in that they remove bold formatting. Not all sequences can be negated. Background and text use 'bg/default', and 'color/default' to reset back to defaults. For those that do not have a negate syntax, you must simply send an ANSI reset.

Escape Aliases

Escape aliases are the heart of AnsiEscape. There is a supplied script, in extras/printEscAliases.php which will print a table much like the ones below, and show demo typeset instead so you can test your terminal's capabilities.

Most important (compatible) escape aliases are seen in the table below.

Lesser Supported and Non-Standard Escape Codes

These are escape codes that I've never seen work in a modern terminal. You may have better luck.

License

The code is licensed under the 2-clause BSD license.

abcarroll / simple-ansi-escape

Maintainers

Details