<commit_before># Pheasant.js

[![Build Status](https://travis-ci.org/bfontaine/Pheasant.js.png)](https://travis-ci.org/bfontaine/Pheasant.js)

**Pheasant.js** makes colors manipulations easy.

## Install

### Server-side (Node)

```sh
npm install pheasant
```

Then use:

```js
var Pheasant = require( 'pheasant' );
```

### Client-side

Include the `build/pheasant.min.js` file in your page. There’s no dependency,
only 15ko of pure JavaScript (4.4ko gzip’d). Pheasant can also be used as an AMD
module.


## Usage

Pheasant exposes one object, `Pheasant`. It has the following methods:

### .parse

This function returns 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).

```js
Pheasant.parse( 'red' ); // red
Pheasant.parse( '#0F0' ); // green
Pheasant.parse( '#0000FF' ); // blue
Pheasant.parse( 'rgb(128, 128, 128)' ); // gray
Pheasant.parse( 'rgb(10%, 10%, 10%, 0.3)' ); // transparent 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
```

### .convert

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

```js
Pheasant.parse( 'pink' ).toString( 'rgba' ); // 'rgba(255,192,203,1)'
Pheasant.convert( 'pink', 'rgba' ); // 'rgba(255,192,203,1)'
```

### .guessFormat

This function takes one argument, a string, and return the first identifier
of its format, if it’s a supported one. It returns `null` if it can’t guess
the format.

```js
Pheasant.guessFormat( '#ccc' ); // 'hex3'
Pheasant.guessFormat( '#cccbbb' ); // 'hex6'
Pheasant.guessFormat( '#cccb' ); // null
```


### .range

This function takes an object as its argument, and return a range of colors. The
object must have the following properties:

- `from`: The color to start the range with. It can be a valid color string, or a
  `Pheasant.Color` object.
- `to`: The color to end the range with. As `from`, it can be a valid color
  string, or a `Pheasant.Color` object.

Additionally, the object can have the following optional properties:

- `length`: the length of the range (default to 100).
- `type`: the type of the range values. It must be one of the following:
    - `'string'` (default): Each value is a string describing the color. If you
      provide a `format` attribute, it’ll be used. If it’s not provided and if the
      two colors (`from` and `to`) both are strings of the same format, this is
      the one which will be used. If none of theses conditions are met, the
      default format will be used.
    - `'object'`: Each value is a `Pheasant.Color` object.
    - `'rgb'`: Each value is an array of three numbers, the red, green and blue
      channels.
    - `'rgba'`: Same as `'rgb'`, but with the alpha channel.
- `format`: this attribute is used only if the `type` is not provided or is set
  to `'string'`. It defines the format used for the colors strings.

This function returns an empty array if `from` and/or `to` are missing, and/or if the
length is lesser or equal to zero, and/or if the `type` attribute is not valid, and/or
the `format` attribute is not valid, and/or `from` (or `to`) is a string which
cannot be parsed. Some values in the range may be null if you choose the
`colorName` format, since some values don’t have a name (e.g. `rgba(1, 1, 1)`).

```js
// [ '#fff', '#fff', '#fff' ]
Pheasant.range({ from: '#fff', to: '#fff', length: 3 });

// ["#abc", "#89a", "#568", "#345", "#123"]
Pheasant.range({ from: '#ABC', to: '#123', length: 5 });

// ["#40bf40", "#3ca13c", "#378337", "#336633", "#2e482e", "#2a2a2a"]
Pheasant.range({
    from: 'hsl(120, 50%, 50%)',
    to: 'rgb(42, 42, 42)',
    length: 6,
    format: 'hex6'
});
```


## Color objects

You can create a `Color` object using the following constructor:

```js
var color = new Pheasant.Color( red, green, blue, alpha );
```
`alpha` is optional (default to 1), and `red`, `green` and `blue` should be
integers between 0 and 255.

`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()`.

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

### .toString

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.

```js
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`.

### .negative

This method returns a new object representing the negative of the current color.
It preserves the alpha channel.

```
var c1 = new Pheasant.color( 42, 42, 42 ),
    c2 = c1.negative();

c2.getRGB(); // [ 213, 213, 213 ]

Pheasant.parse( 'white' ).negative().toString( 'colorName' ); // 'black'
```

### .brightness

This method returns the [brightness index][brightness] of the color. This is an
integer between 0 (dark) and 255 (white). It can be used to mesure the contrast
between two colors.

[brightness]: http://www.had2know.com/technology/color-contrast-calculator-web-design.html
<commit_msg>Missing doc added, we still need some examples for .getHSV.<commit_after># Pheasant.js

[![Build Status](https://travis-ci.org/bfontaine/Pheasant.js.png)](https://travis-ci.org/bfontaine/Pheasant.js)

**Pheasant.js** makes colors manipulations easy.

## Install

### Server-side (Node)

```sh
npm install pheasant
```

Then use:

```js
var Pheasant = require( 'pheasant' );
```

### Client-side

Include the `build/pheasant.min.js` file in your page. There’s no dependency,
only 15ko of pure JavaScript (4.4ko gzip’d). Pheasant can also be used as an AMD
module.


## Usage

Pheasant exposes one object, `Pheasant`. It has the following methods:

### .parse

This function returns 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).

```js
Pheasant.parse( 'red' ); // red
Pheasant.parse( '#0F0' ); // green
Pheasant.parse( '#0000FF' ); // blue
Pheasant.parse( 'rgb(128, 128, 128)' ); // gray
Pheasant.parse( 'rgb(10%, 10%, 10%, 0.3)' ); // transparent 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
```

### .convert

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

```js
Pheasant.parse( 'pink' ).toString( 'rgba' ); // 'rgba(255,192,203,1)'
Pheasant.convert( 'pink', 'rgba' ); // 'rgba(255,192,203,1)'
```

### .guessFormat

This function takes one argument, a string, and return the first identifier
of its format, if it’s a supported one. It returns `null` if it can’t guess
the format.

```js
Pheasant.guessFormat( '#ccc' ); // 'hex3'
Pheasant.guessFormat( '#cccbbb' ); // 'hex6'
Pheasant.guessFormat( '#cccb' ); // null
```

### .range

This function takes an object as its argument, and return a range of colors. The
object must have the following properties:

- `from`: The color to start the range with. It can be a valid color string, or a
  `Pheasant.Color` object.
- `to`: The color to end the range with. As `from`, it can be a valid color
  string, or a `Pheasant.Color` object.

Additionally, the object can have the following optional properties:

- `length`: the length of the range (default to 100).
- `type`: the type of the range values. It must be one of the following:
    - `'string'` (default): Each value is a string describing the color. If you
      provide a `format` attribute, it’ll be used. If it’s not provided and if the
      two colors (`from` and `to`) both are strings of the same format, this is
      the one which will be used. If none of theses conditions are met, the
      default format will be used.
    - `'object'`: Each value is a `Pheasant.Color` object.
    - `'rgb'`: Each value is an array of three numbers, the red, green and blue
      channels.
    - `'rgba'`: Same as `'rgb'`, but with the alpha channel.
- `format`: this attribute is used only if the `type` is not provided or is set
  to `'string'`. It defines the format used for the colors strings.

This function returns an empty array if `from` and/or `to` are missing, and/or if the
length is lesser or equal to zero, and/or if the `type` attribute is not valid, and/or
the `format` attribute is not valid, and/or `from` (or `to`) is a string which
cannot be parsed. Some values in the range may be null if you choose the
`colorName` format, since some values don’t have a name (e.g. `rgba(1, 1, 1)`).

```js
// [ '#fff', '#fff', '#fff' ]
Pheasant.range({ from: '#fff', to: '#fff', length: 3 });

// ["#abc", "#89a", "#568", "#345", "#123"]
Pheasant.range({ from: '#ABC', to: '#123', length: 5 });

// ["#40bf40", "#3ca13c", "#378337", "#336633", "#2e482e", "#2a2a2a"]
Pheasant.range({
    from: 'hsl(120, 50%, 50%)',
    to: 'rgb(42, 42, 42)',
    length: 6,
    format: 'hex6'
});
```


## Color objects

You can create a `Color` object using the following constructor:

```js
var color = new Pheasant.Color( red, green, blue, alpha );
```
`alpha` is optional (default to 1), and `red`, `green` and `blue` should be
integers between 0 and 255.

`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()`.

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

### .toString

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.

```js
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`.

### .getRGB

This method returns an array of red, green and blue values.

```js
Pheasant.parse( 'red' ).getRGB(); // [ 255, 0, 0 ]
```

### .getRGBA

This method returns an array of red, green, blue, and opacity values.

```js
Pheasant.parse( 'red' ).getRGBA();                // [ 255,   0,   0, 1   ]
Pheasant.parse('hsla(42,12%,99%,0.5)').getRGBA(); // [ 253, 253, 252, 0.5 ]
```

### .getHSL

This method returns the equivalent HSL values of the color (hue, saturation,
lightness).

```js
Pheasant.parse('red').getHSL();  // [  0, 100, 50 ]
Pheasant.parse('#ffe').getHSL(); // [ 60, 100, 97 ]
```

### .getHSV

This method returns the equivalent HSV values of the color (hue, saturation,
value). HSV is also called HSB (“value” being replaced by “brightness”), so
an alias method called `.getHSB` is also available (this is exactly the same).

```js
// TODO
```

### .negative

This method returns a new object representing the negative of the current color.
It preserves the alpha channel.

```
var c1 = new Pheasant.color( 42, 42, 42 ),
    c2 = c1.negative();

c2.getRGB(); // [ 213, 213, 213 ]

Pheasant.parse( 'white' ).negative().toString( 'colorName' ); // 'black'
```

### .brightness

This method returns the [brightness index][brightness] of the color. This is an
integer between 0 (dark) and 255 (white). It can be used to mesure the contrast
between two colors.

[brightness]: http://www.had2know.com/technology/color-contrast-calculator-web-design.html

{'fraction_non_alphanumeric': 0.1572620215897939, 'fraction_numerical': 0.034756297023225385, 'mean_word_length': 3.79192789968652, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 4, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7600081', 'n_tokens_mistral': 4473, 'n_tokens_neox': 4037, 'n_words': 1643}