node-colorific

Text coloring (with ANSI) for Node.js.

This package was heavily inspiried by Muslim Idris' node-curly-colors and several other ANSI/Color - specific packages available on the npm repository.

The reason - for me - to write yet another coloring package was that I personally don't like having any properties and/or functions attached to the String object and find it preferably to encode the colorinformation within the String itself. That leaves the possibility to save my messages in some JSON file and retrieve them later - making it easy to write internationalization functions. In addition I noticed that there are quite a couple of different format tags out there and people seem to like various different styles. So instead of inventing yet another fixed format library I tried to enable all kinds of custom format supporting - almost - every format that is currently already available.

Installation

$ npm install --save colorific

$ yarn add colorific

How to include

To use the default (Colorific) tag format (see below for more information), simply require the package as usual.

  var cc = require('colorific');

  // -or-

  import cc from 'colorific';

You can however also use a different tag format using the following format:

  var cc = require('colorific').create('#@KEY[@TEXT]');

  // -or-

  import { create } from 'colorific';

  const cc = create('#@KEY[@TEXT]');

If you like to use one of the already predefined tag formats simply do:

  var colorific = require('colorific');
  var cc        = colorific.create(colorific.CURLY_COLORS);

  // -or-

  import { create, CURLY_COLORS } from 'colorific';

  const cc = create(CURLY_COLORS);

How to use

Once you have you colorific instance you can simply use that as function to convert the ANSI codes embedded into a String to their correct ANSI representation. For example:

  var s = 'Sometime I want my text to be @red:red!';

  console.log(cc(s));

  // -or-

  const s = 'Sometime I want my text to be @red:red!';

  console.log(cc(s));

  // -or-

  const s = cc`Sometime I want my text to be @red:red!`;

  console.log(s);

If you have a printf-like formatted string simply do some like this:

  var s = 'Sometimes I want my %s to be @red:%s!';

  console.log(cc(s), "text", "red");

  // -or-

  const s = 'Sometimes I want my %s to be @red:%s!';
  
  console.log(cc(s), "text", "red");

  // -or-

  const s = cc`Sometimes I want my %s to be @red:%s!`;
  
  console.log(s, "text", "red");

(Predefined) Tag Formats

A tag format string can basically be any string. There are two special 'markers' in a tag format string which are @KEY and @TEXT. @KEY is a placeholder for a valid ANSI Code from the list below. @TEXT is used to represent the text to format. Anything before @TEXT is consider the opening 'tag', anything after is the closing 'tag'. If the is nothing after @TEXT the tag format is considered closing-tag-less and possible closing code will be appended to the resuling, ansi-encoded string. Any @KEY in the closing tag is used to represent a match to the ANSI Code used in the corresponding opening tag.

Base on the tag format colorific will generate internal regular expressions to represent the tag format.

There are already several tag formats predefined:

• COLORIFIC @@KEY:@TEXT

  My default format. Chosen to make be short but still easily distinguishable in a string.

  Example: @red:this is red

• COLOR_TERMINAL %@KEY@TEXT

  Inspired by color-terminal

  Example: %redthis is red

• STYISH #{@KEY \'@TEXT\'}

  Inspired by sty

  Example: #{red 'this is red'}

• SGML <@KEY>@TEXT</@KEY>

  SGML-like representation of color codes in string.

  Example: <red>this is red</red>

• CURLY_COLORS <{@KEY>@TEXT<}>

  Inspired by curly-colors

  Example: <{red>this is red<}>

• COLORS_TMPL {@KEY}@TEXT{/@KEY}

  Inspired by colors-tmpl

  Example: {red}:this is red{/red}

• XCOLOR {{@KEY}}@TEXT{{/@KEY}}

  Inspired by xcolor

  Example: {{red}}:this is red{{/red}}

Supported ANSI Codes

Currently the following codes are supported:

• Foreground Colors

  • default
  • black
  • red
  • green
  • yellow
  • blue
  • magenta
  • cyan
  • white

• Background Colors

  • default
  • black
  • red
  • green
  • yellow
  • blue
  • magenta
  • cyan
  • white

• Miscellaneous Styles

  • reset
  • bold
  • faint
  • underline
  • inverse

• Automatic when using a tag format with closings

  • boldOff
  • faintOff
  • underlineOff
  • inverseOff

Examples

Check the color-table.js in the example directory which generates a color table output.

License

The MIT License (MIT)

Copyright (c) 2013 Jan Oetjen [email protected]

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.