pheasant v0.2.2
Pheasant.js
Pheasant.js makes colors manipulations easy.
Install
npm install pheasant
Usage
Pheasant expose one object, Pheasant
. It has the following methods:
.parse
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
.
.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)'
Color Formats
Built-in Support
Format | Parsing | Stringifying | Identifiers |
---|---|---|---|
#ABC | ✔ | ✔ | hex3 , hexa3 |
#ABCDEF | ✔ | ✔ | hex6 , hexa4 |
color names | ✔ | ✔ | colorName , colourName |
hsl() | ✔ | ✔ | hsl |
hsla() | ✔ | ✔ | hsla |
rgb() | ✔ | ✔ | rgb |
rgba() | ✔ | ✔ | rgba |
Format identifiers are case-insensitive.
Setting the default output format
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)'
Adding a format
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 returnnull
. If the returned value is not null, it’ll be wrapped in aPheasant.Color
object.
stringify
: a function wich convert aPheasant.Color
object to a string of your format. It must return null if it can’t stringify the color (e.g.: there’sNaN
values in it).normalize
: Optional. If set tofalse
, 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;
Tests
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
License
See the LICENSE file (MIT).