Home

Awesome

ttycolor

Build Status npm version Coverage Status

Terminal colors for node that respect whether the stdout and stderr streams are a tty.

Features

<p align="center"> <img src="https://raw.github.com/tmpfs/ttycolor/master/img/colors.png" /> </p> <p align="center"> <img src="https://raw.github.com/tmpfs/ttycolor/master/img/cat.png" /> </p> <p align="center"> <img src="https://raw.github.com/tmpfs/ttycolor/master/img/source.png" /> </p>

Installation

npm install ttycolor

Test

npm test

Example executables are not included in the default test suite as they do not contribute to the code coverage, however you can run tests against them with:

npm run exe

Examples

There are various example and test programs in the bin directory. Note that these executables are not included when the package is distributed via npm.

Normal

var ttycolor = require('ttycolor')();
console.log('%s', 'value');
console.log('%d', 3.14);
console.log('%j', {message: 'json'});
console.log('a %s of %d with %j', 'value', 3.14, {message: 'json'});

Defaults (recommended)

var ttycolor = require('ttycolor')();
var revert = ttycolor.defaults();
console.log('a %s message', 'log');
console.info('an %s message', 'info');
console.warn('a %s message', 'warn');
console.error('an %s message', 'error');

Custom

var ansi = require('ttycolor')().ansi;
console.log('%s', ansi('log message').white.bg.black);
console.info('%s', ansi('info message').cyan);
console.warn('%s', ansi('warn message').magenta);
console.error('%s', ansi('error message').bright.red);
console.log('pi %d', ansi(3.14).blue.underline);
console.log('%j', ansi({message: 'json'}).red);

API

Console

This package overrides the default console functions, you may access the original console functions via the console property exposed by the module. Note that the console.dir method is left untouched.

All overriden methods proxy to the original method after handling escape sequences.

console.log(format, ...)

Print a log message with escape sequence support, output is to stdout.

console.info(format, ...)

Print an info message with escape sequence support, output is to stdout.

console.warn(format, ...)

Print a warn message with escape sequence support, output is to stderr.

console.error(format, ...)

Print an error message with escape sequence support, output is to stderr.

Module

ansi(value)

Wrap value in a chainable color instance, the value will be coerced to a string when passed to a console function.

attributes

Map of attribute codes.

background

Map of background color codes.

colors

Array of color names.

console

Map referencing the original console methods.

defaults(styles)

Configure default styles for the console functions.

This method returns a closure that allows reverting to the previous console functions.

var ttycolor = require('ttycolor'), defaults = ttycolor.defaults, revert;
revert = defaults();
console.log('log: a %s message', 'log');
revert();
console.log('log: a %s message', 'log');

foreground

Map of foreground color codes.

format([test], format, ...)

Return a formatted string with escape sequences. If the first argument is a function it should return a boolean indicating whether escape sequences should be used.

Note that there are no default styles for this method even if defaults() has been invoked.

modes

Map of highlighting modes.

stringify(value, code, attr, tag)

Low-level method for creating escaped string sequences.

write(options, format, ...)

Asynchronously write to an arbitrary writable stream with escape sequence support if the stream is a tty as reported by tty.isatty.

The options object should contain the properties stream and callback. The callback is invoked when the write operation has completed and is passed the value written to the stream.

The stream must be open and have an associated fd or this method will throw an error.

Note this method is only available after the module main method has been initialized so that the stream write method can respect commmand line arguments. For example:

var ttycolor = require('ttycolor')();
// ttycolor.write(...);

styles

Map of styles to use when no arguments are passed to defaults().

Styles

Foreground Colors

console.log('%s', ansi('log message').white);

Background Colors

console.log('%s', ansi('log message').bg.black);

Background colors are set by accessing a color property via the bg property. Property names are identical to the foreground color list.

Note that the background color chain is reset after accessing a color property such that order is not important when combining background and foreground colors, the following are all equivalent:

ansi('value').bg.red.white.underline;
ansi('value').bg.red.underline.white;
ansi('value').underline.white.bg.red;
ansi('value').white.underline.bg.red;
ansi('value').white.bg.red.underline;

Attributes

console.log('%s', ansi('log message').bright);

Depending upon the terminal emulator some attributes may not be supported and will have no visual effect. Typically bright, underline and reverse are safe to use.

Default Styles

To keep your code clean and the program output consistent it is a good idea to use the default styles.

var ttycolor = require('ttycolor')(), defaults = ttycolor.defaults, revert;
revert = defaults();
console.info('an %s message', 'info');
console.error('an %s message', 'error');
revert();
console.info('an %s message', 'info');
console.error('an %s message', 'error');

Customise

To customise the styles when using defaults() create an object with the following structure (see below for some example code):

{
  "log": {
    "format": [
      "normal"
    ],
    "parameters": [
      "normal",
      "bright"
    ]
  },
  "info": {
    "format": [
      "cyan"
    ],
    "parameters": [
      "cyan",
      "bright"
    ]
  },
  "warn": {
    "format": [
      "magenta"
    ],
    "parameters": [
      "magenta",
      "bright"
    ]
  },
  "error": {
    "format": [
      "red"
    ],
    "parameters": [
      "red",
      "bright"
    ]
  }
}

If you need to format a particular parameter, declare a params object with the given index and assign a function that returns an ansi instance, for example:

{
  error: {
    format: [
      "red"
    ],
    parameters: [
      "red",
      "bright"
    ],
    params: {
      '0': function(arg) {
        // override the style for a parameter at index 0
        return ansi(arg).magenta; 
      }
    }
  }
}

Example

An example derived from the defaults executable:

#!/usr/bin/env node
var ttycolor = require('ttycolor')(), defaults = ttycolor.defaults,
  revert, styles, keys;
revert = defaults(); keys = Object.keys(ttycolor.styles); ansi = ttycolor.ansi;
keys.forEach(function(method) {console[method]('%s: %s', method, 'message')})
revert();
keys.forEach(function(method) {console[method]('%s: %s', method, 'message')})
styles = {
  log: {format: ['normal'], parameters: ['normal', 'underline']},
  info: {format: ['cyan'], parameters: ['cyan', 'underline']},
  warn: {format: ['magenta'], parameters: ['magenta', 'underline']},
  error: {format: ['red'], parameters: ['red', 'underline']}
}
defaults(styles);
keys.forEach(function(method) {console[method](method + ': %s', 'message')})
keys.forEach(function(method) {
  console[method]('[%s] %s', ansi(method).bright[styles[method].format],
    ansi(method).underline.bright[styles[method].format]);
});
keys.forEach(function(method) {
  console[method]('[%s] %s', ansi(method).bright[styles[method].format],
    ansi(method).bright);
});
<p align="center"> <img src="https://raw.github.com/tmpfs/ttycolor/master/img/defaults.png" /> </p> <p align="center"> <img src="https://raw.github.com/tmpfs/ttycolor/master/img/defaults-cat.png" /> </p>

Arguments

The module supports argument parsing with the modes always, auto and never. Argument parsing is built in to the module to prevent repeating the option parsing logic for multiple command line programs. All you need to do is document the option(s) in your program's help or documentation.

Note that this behaviour is enabled by default so that you may enable highlighting before options are parsed so that whichever module is used for option parsing will respect highlighting provided defaults() is invoked prior to parsing arguments and that the module uses the console methods to print errors.

By default this module will use the auto behaviour.

Defaults

The default argument parsing supports the following variations:

Custom

If you want to implement a custom argument parser you can pass a function when initializing the module.

function parser(modes, option, argv) {
  // do argument parsing and return a mode (always|auto|never)
  return modes.auto;
}
var ttycolor = require('ttycolor')(parser);
parser(modes, option, argv)

The parser function should return a string representing one of the available modes.

Disable

You may wish to disable argument parsing, to do so pass false when initializing the module.

var ttycolor = require('ttycolor')(false);

License

Everything is MIT. Read the license if you feel inclined.