- Terminal application part. I: Styles & Colors
- Terminal application part. II: Moving & Editing
- Terminal application part. III: User Inputs
Prologue
Have you ever wanted to make your CLI script shine? While cool scripts expose colors and styles, you are still stuck with black & white boring text? Hey! I've got something for you!
In this series of article, we will explore how to build a great terminal application: how to move the cursor, edit the screen, handle keyboard input, handle mouse input, and even more goodies!
But let's start with something simpler... Life is really bland without colors, doesn't it?... Let's add some spicy colors to our terminal application!
The hard way
You wonder how colors and styles are achieved? You guess that one have do deal with an obscur underlying driver? Actually, you're wrong: you can do that with a simple console.log().
So let's write a red "Hello world!":
console.log( '\x1b[31mHello world!' ) ;
Yes, you guessed it: \x1b[31m is an escape sequence that will be intercepted by your terminal and instructs it to switch to the red color. In fact, \x1b is the code for the non-printable control character escape... you know, that key on the top-left corner of your keyboard?
Eventually, if we want to produce a notice of this kind:
Warning: the error #105 just happened!
... you will have to code this:
console.log( '\x1b[31m\x1b[1mWarning:\x1b[22m \x1b[93mthe error \x1b[4m#105\x1b[24m just happened!\x1b[0m' ) ;
Just copy-paste it to the node's REPL console, to try it out!
Okey, now if you want the full list of what you can achieve with control sequences, have a look at the official xterm's control sequences guide.
Isn't that nice? We don't have to deal with an obscur underlying driver! We just have to deal with obscur escape sequences!
But that's not all: complex sequences are not compatible between all terminals.
Ok, ok... Let's hunt for a good lib then...
Popular libs
Since the goal of this part is just to put some colors and styles to our terminal application, there are two popular packages with a very high download count in the npm's registry: colors and chalk.
Escape sequences dealing only with colors & styles are known as ANSI escape code, they are standardized and therefore they work everywhere. That's the focus of those two packages.
The first package, colors, is probably the oldest package around dealing with colors and styles. At time of writing, it has no less than 3.5 millions of downloads for the last month.
Some example of the syntax, taken directly from the package's documentation:
var colors = require('colors');
console.log('hello'.green); // outputs green text
console.log('i like cake and pies'.underline.red) // outputs red underlined text
console.log('inverse the color'.inverse); // inverses the color
console.log('OMG Rainbows!'.rainbow); // rainbow
console.log('Run the trap'.trap); // Drops the bass
This is the old syntax. While it looks really easy to use, note that it extends the native String object, which is a very bad thing.
Due to popular pressure, some of them directly coming from the author of the chalk package itself, now colors can be required without extending native object... Of course, the syntax differs:
var colors = require('colors/safe');
console.log(colors.green('hello')); // outputs green text
console.log(colors.red.underline('i like cake and pies')) // outputs red underlined text
console.log(colors.inverse('inverse the color')); // inverses the color
console.log(colors.rainbow('OMG Rainbows!')); // rainbow
console.log(colors.trap('Run the trap')); // Drops the bass
The chalk package has recently surpassed colors, at time of writing its download count reached 5.7 millions.
Again, taken directly from the chalk's documentation:
var chalk = require('chalk');
// style a string
console.log( chalk.blue('Hello world!') );
// combine styled and normal strings
console.log( chalk.blue('Hello') + 'World' + chalk.red('!') );
// compose multiple styles using the chainable API
console.log( chalk.blue.bgRed.bold('Hello world!') );
// pass in multiple arguments
console.log( chalk.blue('Hello', 'World!', 'Foo', 'bar', 'biz', 'baz') );
// nest styles
console.log( chalk.red('Hello', chalk.underline.bgBlue('world') + '!') );
// nest styles of the same type even (color, underline, background)
console.log( chalk.green(
'I am a green line ' +
chalk.blue.underline.bold('with a blue substring') +
' that becomes green again!'
) );
The outsider: terminal-kit
It's time to introduce my little gem: terminal-kit.
The basic part of terminal-kit, the part dealing with styles and colors was inspired by chalk. It's easy, you can combine styles and colors, and furthermore, you don't have to use console.log() anymore. Why? Because terminal-kit IS a terminal lib, not just an ANSI's style helper.
Just compare the chalk's way:
console.log( chalk.blue.bold( 'Hello world!' ) ) ;
... and the terminal-kit's way:
term.blue.bold( 'Hello world!' ) ;
Less cumbersome, right?
This is the spaceship demo! After doing an npm install terminal-kit, go to node_modules/terminal-kit/demo/ and run ./spaceship.js to see it alive!
Let's have a look to some of the terminal-kit's primer, from the documentation:
// Require the lib, get a working terminal
var term = require( 'terminal-kit' ).terminal ;
// The term() function simply output a string to stdout, using current style
// output "Hello world!" in default terminal's colors
term( 'Hello world!\n' ) ;
// This output 'red' in red
term.red( 'red' ) ;
// This output 'bold' in bold
term.bold( 'bold' ) ;
// output 'mixed' using bold, underlined & red, exposing the style-mixing syntax
term.bold.underline.red( 'mixed' ) ;
// printf() style formating everywhere: this will output 'My name is Jack, I'm 32.' in green
term.green( "My name is %s, I'm %d.\n" , 'Jack' , 32 ) ;
// Width and height of the terminal
term( 'The terminal size is %dx%d' , term.width , term.height ) ;
// Move the cursor at the upper-left corner
term.moveTo( 1 , 1 ) ;
// We can always pass additionnal arguments that will be displayed...
term.moveTo( 1 , 1 , 'Upper-left corner' ) ;
// ... and formated
term.moveTo( 1 , 1 , "My name is %s, I'm %d.\n" , 'Jack' , 32 ) ;
// ... or even combined with other styles
term.moveTo.cyan( 1 , 1 , "My name is %s, I'm %d.\n" , 'Jack' , 32 ) ;
Okey, what if you don't want to output a string directly on the terminal, but just put it into a variable like colors and chalk does? Easy: just add the str property into your chainable combo:
var myString = term.red.str( 'Hello world!\n' ) ;
It happens that at least 95% of time, we deal with color only when we are about to output something directly into the terminal, and don't care about storing a string containing obscur escape sequences into some variable... That's why the default behaviour of the lib is to print, not to return.
If you want to output to stderr instead, just add the error property into your chainable combo:
term.red.error( 'Some errors occurs...\n' ) ;
Here is the list of styles the lib support:
- styleReset: reset all styles and go back to default colors
- bold: bold text
- dim: faint color
- italic: italic
- underline: underline
- blink: blink text, not widely supported
- inverse: foreground and background color
- hidden: invisible, but can be copy/paste'd
- strike: strike through
Note that your terminal may not support all of those features.
And now, here is the list of supported colors: black, red, green, yellow (actually brown or orange, most of the time), blue, magenta, cyan, white, brightBlack (grey, it sounds dumb, but in fact it's the combo of black and bright escape code), brightRed, brightGreen, brightYellow (true yellow), brightBlue, brightMagenta, brightCyan and brightWhite.
If you want to change the background color of characters about to be written, just prefix the above colors with 'bg' (and don't forget the camelCase rule, e.g. cyan becomes bgCyan).
For example, if you want to output 'Hello world!', 'Hello' in bold red over cyan and 'world!' in italic green over magenta for maximum contrast and bleeding eyes, just do that:
term.red.bgCyan.bold( 'Hello ' ).green.bgMagenta.italic('world!\n') ;
Hello world!
Ok, ok... Let's stop making that kind of insane example now...
Finally, if we are not bothered by very old terminals, we can use all of the 256 colors. Most terminal support them.
- .color256(register): it chooses between one of the 256 colors directly
- .colorRgb(r,g,b): pick the closest match for an RGB value (from a 16 or 256 colors palette or even the exact color if the terminal support 24 bits colors), r,g,b are in the 0..255 range
- .colorGrayscale(l): pick the closest match for a grayscale value (from a 16 or 256 colors palette or even the exact color if the terminal support 24 bits colors), l is in the 0..255 range
Example:
term.colorRgb( 0x33 , 0xff , 0x88 , "This is teal!" )
They all have their bg* counter-part, e.g.:
term.bgColorRgb( 0x33 , 0xff , 0x88 , "The background color is teal!" )
It's worth noting that providing some text to a style method will apply the color *ONLY* for the given text, while calling a style method without text will turn the current style on, until another style contradict that.
E.g:
term.red( "Red!\n" ) ;
term( "This is white\n" ) ;
term.red()( "Red!\n" ) ; // Note the parenthesis
term( "This is red\n" ) ;
In practice, it's always good to define some handy shortcuts. For example, one may want to define a standard way to output errors. Putting it all together:
var logError = require( 'terminal-kit' ).terminal.error.bold.red ;
// Later...
logError( 'Oh my! A bad thing happens!\n' ) ;
I hope you liked this little tutorial, next time we will learn how to move the cursor and edit the screen.
See ya! ;)