trucolor

A node.js module and command line utility for using 24bit color SGR codes in modern terminals.

Install

Global version, for CLI use

npm install --global trucolor

Module, for programmatic use

npm install --save trucolor

CLI Usage

Synopsis:

trucolor [options] [name]: [operation...] color [operation...]
               ...[[name]: [operation...] color [operation...]]...

Options:
-h, --help     Display this help.
-v, --version  Return the current version. -vv Return name & version.
-V, --verbose  Be verbose. -VV Be loquacious.                        
-m, --message  Format message with SGR codes
-i, --in       Output SGR color escape code.                         
-o, --out      Output cancelling SGR color escape code.              
-r, --rgb      Output color as rgb(r, g, b)                          
-s, --swatch   Output an isolated color swatch.

In it's simplest form, trucolor 'color', will take any of the color expressions listed below and transform it into a simple hexadecimal triplet string, i.e AA00BB, ideal for passing into fish-shell's set_color built-in, or providing the basis of further color processing.

It can return color values and set terminal colors for a wide range of color assignment declarations and manipulation functions, based internally on the color-convert node module and less. See the examples below.

When outputting SGR codes, colors will be shifted to the availalble 256 or ansi color palette if 24 bit color is unavailable or will be omitted in a monochromatic terminal to make usage across environments safe. The CLI command respects --color=16m, --color=256, --color and --no-color flags. It does not affect value based output, such as the default or --rgb output, it only effects the --in, --out, --message and --swatch outputs.

The motivation for this is to allow more sophisticated graphic visualisation using in modern, xterm-compatible terminal emulators that have added 24 bit support.

Color definition

The color can be defined in any of the following formats:

• CSS Hexadecimal
  [#]RRGGBB or [#]RGB where R, G and B are 0-F.

• RGB
  rgb:R,G,B or rgb(R,G,B) where R,G and B are 0-255.
  Spaces can be incuded in rgb(R, G, B) declarations but require quoting/escaping on the CLI.

• HSL (Hue Saturation Lightness)
  hsl:H,S,L where H is 0-360, S 0-100 and L 0-100

• HSV (Hue Saturation Value)
  hsv:H,S,V where H is 0-360, S 0-100 and V 0-100

• HSB (Hue Saturation Brightness) (just an alias for HSV)
  hsb:H,S,B where H is 0-360, S 0-100 and B 0-100

• HWB (Hue White Black) hwb:H,W,B where H is 0-360, W 0-100 and B 0-100
  See HWB notation @csswg

• CSS named colors

• Special formatters The following keywords modify the meaning or destination of the color, or provide enhanced foramtting. They only work when used with the command switches that actually output SGR codes, namely: --message, --swatch, --in and --out. When used with the default command or with the --rgb switch, they have no effect and the value of the base color (plus any processing) will be output.

  background: Set the background color, rather than the foreground.

  normal: Set the color to the default foreground and background.
  reset: Sets colors and special formatting back to the default.

  bold: Set the font to bold.
  italic: Set the font to italic.
  underline: Set underline.
  faint: Set the colour to 50% opacity.
  invert: Invert the foreground and background.
  blink: Annoying as a note in Comic Sans, attached to a dancing, purple dinosaur with a talking paperclip.

  All of the above formatters need the correct code to end the range, either provided by using the --out switch, using the reset keyword, or simply use the --message option to automatically set the end range SGR code. Using normal alone won't fully clear the formatting.

Color manipulation

A number of color operations can be specified, either before or after the base color declaration.

light | dark : preset 20% darken/lighten.
saturate | sat | desaturate | desat | lighten | darken percent : basic operations.
spin degrees : hue shift.
mix | multiply | screen (named | rgb() | #hex) : mix with color.
overlay | softlight | soft | hardlight | hard color : light with color.
difference | diff | exclusion | excl color : subtract color.
average | ave | negation | not color : blend with color.
contrast dark color [light color] [threshold] : calculate contrasting color.

See http://lesscss.org/functions/#color-operations for more details.

Multiple Inputs

trucolor will output a list of color values if more than one base color is specified, allowing color assignment in a single block allowing easy ingest using read. Each color will be output on it's own line, and named according to the input base color. The names can be overridden by providing a name: before the base color.

> trucolor red yellow green purple
red FF0000
yellow FFFF00
green 008000
purple 800080

> trucolor Po: red LaaLaa: yellow Dipsy: green TinkyWinky: purple
Po FF0000
LaaLaa FFFF00
Dipsy 008000
TinkyWinky 800080

> trucolor hsl:120,100,50 apples: orange spin 180
hsl-120-100-50 00FF00
apples 005AFF

Custom Names:

Any color definition can be prefixed with a name: and the result will be cached with that name, allowing it to be recalled by the same name later.

> trucolor bob: black lighten 50 saturate 50 spin 180
40BFBF
> trucolor --rgb bob:
rgb(64, 191, 191)

Supported and tested terminals include:

Obviously all this depends on your terminals support for the extended formatting. The latest iTerm2 builds and X's XTerm have full support for everything trucolor can do, and anything that supports a terminal type of 'xterm-256color' will cover a fairly complete subset.

For example, Apple's Terminal.app doesn't have 24 bit color support nor does it have support for italics, but everything else works well.

• iTerm2 2.9 Beta (OS X)
• XTerm (^314 XQuartz 2.7.8)

Please let me know results in your terminal. http://github.com/MarkGriffiths/trucolor

Programmatic Usage

More to come here...

Simple generic palette

I use this to make sure help pages are consistent between different modules.

//ES6
require('trucolor').simplePalette(clr => {
    console.log("${clr.command}trucolor${clr.normal} palettes");
});

//ES5
var trucolor = require('trucolor');
trucolor.simplePalette(function(clr) {
    console.log(clr.command + "trucolor" + clr.normal + "palettes");
});

Bulk color creation

var trucolor = require('trucolor');

trucolor.bulk({
    color_1: 'red lighten 10',
    color_2: '#fe2316',
    color_3: 'hsl(120,50,60)'
}, { output: 'value|sgr|swatch' }, function (colour_object) {
    ... object containing HEX value, SGR codes or swatch strings, ready to write to stdio streams ...
}); // Synchronous operation, despite callback