pheasant

Easy colors manipulations.

Pheasant.js

Pheasant.js makes colors manipulations easy.

npm install pheasant

Pheasant expose one object, Pheasant. It has the following methods:

This method return a Pheasant.Color object of the parsed string, or null if it can’t be parsed (see the support table below for the supported formats).

Pheasant.parse( 'red' ); // red 
Pheasant.parse( '#0F0' ); // green 
Pheasant.parse( '#0000FF' ); // blue 
Pheasant.parse( 'rgb(128, 128, 128)' ); // gray 
Pheasant.parse( 'rgba(255, 192, 203, 0.5)' ); // transparent pink 
Pheasant.parse( 'hsl(240, 100%, 50%)' ); // blue 
Pheasant.parse( 'hsla(120, 100%, 25%, 1)' ); // green 

Color objects has four attributes, .red, .green, .blue and .alpha. They also have two convenient methods: .getRGB() and .getRGBA(), which return an array of .red, .green and .blue properties, plus the .alpha one for .getRGBA().

Pheasant.parse( 'navy' ).blue; // 128 

You can use the .toString() method to convert colors to the format you want. Without argument, it convert the color to the default format (#ABCDEF). You can specify the format you want as a string. See the format identifiers below.

Pheasant.parse( 'red' ).toString(); // '#f00' 
Pheasant.parse( '#00F' ).toString( 'colorName' ); // 'blue' 
var c = Pheasant.parse( 'rgb(245, 245, 220)' );
c.toString( 'colorName' ); // 'beige' 
c.toString( 'hsl' ); // 'hsl(60,56%,91%)' 

Since it may be painful to write Pheasant.parse( 'foo' ).toString( 'bar' ) for a one-time conversion, Pheasant has a method for that: .convert.

This method takes two arguments, the first is the string to parse and the second is the identifier of the format to convert to.

Pheasant.parse( 'pink' ).toString( 'rgba' ); // 'rgba(255,192,203,1)' 
Pheasant.convert( 'pink', 'rgba' ); // 'rgba(255,192,203,1)' 
FormatParsingStringifyingIdentifiers
#ABChex3, hexa3
#ABCDEFhex6, hexa4
color namescolorName, colourName
hsl()hsl
hsla()hsla
rgb()rgb
rgba()rgba

Format identifiers are case-insensitive.

The default ouput format (for toString) is hex6. You can change it with Pheasant.setDefaultStringFormat():

Pheasant.parse( 'lightgreen' ).toString(); // '#90ee90' 
Pheasant.setDefaultStringFormat( 'rgb' );
Pheasant.parse( 'lightgreen' ).toString(); // 'rgb(144,238,144)' 

You can add a new format with Pheasant.addFormat(). This method takes one argument, an object with the following properties:

  • name: the identifier(s) of the format. Must be a string (one identifier) or an array of strings (multiple identifiers).
  • parse: a function which convert a string in your format to a color object. It must return an object with the following, optional, properties:
    • red: the red channel (integer between 0 and 255)
    • blue: the blue channel (integer between 0 and 255)
    • green: the green channel (integer between 0 and 255)
    • alpha: the alpha channel (float between 0 and 1) If it can’t parse the string, it must return null. If the returned value is not null, it’ll be wrapped in a Pheasant.Color object.
  • stringify: a function wich convert a Pheasant.Color object to a string of your format. It must return null if it can’t stringify the color (e.g.: there’s NaN values in it).
  • normalize: Optional. If set to false, the parsed string won’t be normalized before being passed to your .parse function (the normalizing process force the string to lowercase and remove trailing spaces).

The object must provide the parse and/or stringify attributes, and must provide the name attribute.

When a string is passed to Pheasant.parse, it tries to parse it with every available format. If no format can parse it (i.e. they all return null), it returns null.

The Pheasant.addFormat() method return either:

  • null if your format has only one name and it’s already taken
  • the name of your format if it’s available
  • an array of strings if your format has multiple names. Only the available names are returned

This means that if you try to register a new format with the identifier hex3 (already taken), it won’t be registered and the call will return null. If you try with HEX3, that’s the same since format identifiers are case-insensitive. If your format has two names, hex3 and hex_3, it will only be bound to hex_3, since hex3 is not available.

If you want to clear all the available formats, use the Pheasant.formats array:

Pheasant.formats.length = 0;

Clone this repo, and then run make. You need to install Mocha before:

[sudo] npm install -g mocha
git clone https://github.com/bfontaine/Pheasant.js.git
cd Pheasant
make

See the LICENSE file (MIT).