Skip to content

Commit

Permalink
Merge pull request #47 from alexjeffburke/validate-documentation
Browse files Browse the repository at this point in the history 
Rework the README to allow the examples to be validated.
  • Loading branch information
@papandreou
papandreou committed Jul 17, 2020
2 parents 9ad4c7c + b815795 commit d76a0ca
Show file tree
Hide file tree
Showing 3 changed files with 87 additions and 65 deletions.
3 changes: 3 additions & 0 deletions .travis.yml
View file
Expand Up @@ -22,6 +22,9 @@ matrix:
- name: Lint
node_js: 14
script: npm run lint
- name: Documentation
node_js: 14
script: npm run test:documentation

script: '(nvm i 14 && npm run build) && npm run ci:test'
after_success: '<coverage/lcov.info ./node_modules/coveralls/bin/coveralls.js'
146 changes: 81 additions & 65 deletions README.md
View file
@@ -1,4 +1,4 @@
# one.color
# onecolor

[![NPM version](https://badge.fury.io/js/onecolor.svg)](http://badge.fury.io/js/onecolor)
[![Build Status](https://travis-ci.org/One-com/one-color.svg?branch=master)](https://travis-ci.org/One-com/one-color)
Expand Down Expand Up @@ -49,20 +49,25 @@ named color support):
</script>
```

In node.js (after `npm install onecolor`):
In the browser, the parser is exposed as a global named `onecolor`.
In node.js, it is returned directly with a require of the module
(after `npm install onecolor`):

```javascript
var color = require('onecolor');
console.warn(color('rgba(100%, 0%, 0%, .5)').alpha(0.4).cssa()); // 'rgba(255,0,0,0.4)'
console.warn(color('rgba(100%, 0%, 0%, .5)').alpha(0.4).cssa());
```

`one.color` is the parser. All of the above return color instances in
the relevant color space with the channel values (0..1) as instance
variables:
```output
'rgba(255,0,0,0.4)'
```

All of the above return color instances in the relevant color space
with the channel values (0..1) as instance variables:

```javascript
var myColor = one.color('#a9d91d');
myColor instanceof one.color.RGB; // true
var myColor = color('#a9d91d');
myColor instanceof color.RGB; // true
myColor.red(); // 0.6627450980392157
```

Expand All @@ -71,15 +76,15 @@ but the requires the slightly bigger <a href="//raw.github.com/One-com/one-color
browser):

```javascript
one.color('maroon').lightness(0.3).hex(); // '#990000'
color('maroon').lightness(0.3).hex(); // '#990000'
```

To turn a color instance back into a string, use the `hex()`, `css()`,
and `cssa()` methods:

```javascript
one.color('rgb(124, 96, 200)').hex(); // '#7c60c8'
one.color('#bb7b81').cssa(); // 'rgba(187,123,129,1)'
color('rgb(124, 96, 200)').hex(); // '#7c60c8'
color('#bb7b81').cssa(); // 'rgba(187,123,129,1)'
```

Color instances have getters/setters for all channels in all supported
Expand All @@ -88,8 +93,7 @@ colorspaces (`red()`, `green()`, `blue()`, `hue()`, `saturation()`, `lightness()
you're in. All the necessary conversions happen automatically:

```javascript
one
.color('#ff0000') // Red in RGB
color('#ff0000') // Red in RGB
.green(1) // Set green to the max value, producing yellow (still RGB)
.hue(0.5, true) // Add 180 degrees to the hue, implicitly converting to HSV
.hex(); // Dump as RGB hex syntax: '#2222ff'
Expand All @@ -99,15 +103,15 @@ When called without any arguments, they return the current value of
the channel (0..1):

```javascript
one.color('#09ffdd').green(); // 1
one.color('#09ffdd').saturation(); // 0.9647058823529412
color('#09ffdd').green(); // 1
color('#09ffdd').saturation(); // 0.9647058823529412
```

When called with a single numerical argument (0..1), a new color
object is returned with that channel replaced:

```javascript
var myColor = one.color('#00ddff');
var myColor = color('#00ddff');
myColor.red(0.5).red(); // .5

// ... but as the objects are immutable, the original object retains its value:
Expand All @@ -119,8 +123,7 @@ the second argument, a new value is returned with that channel
adjusted:

```javascript
one
.color('#ff0000') // Red
color('#ff0000') // Red
.red(-0.1, true) // Adjust red channel by -0.1
.hex(); // '#e60000'
```
Expand All @@ -133,7 +136,7 @@ All color instances have an alpha channel (0..1), defaulting to 1
It's preserved when converting between colorspaces:

```javascript
one.color('rgba(10, 20, 30, .8)').green(0.4).saturation(0.2).alpha(); // 0.8
color('rgba(10, 20, 30, .8)').green(0.4).saturation(0.2).alpha(); // 0.8
```

## Comparing color objects
Expand All @@ -142,87 +145,93 @@ If you need to know whether two colors represent the same 8 bit color, regardles
of colorspace, compare their `hex()` values:

```javascript
one.color('#f00').hex() === one.color('#e00').red(1).hex(); // true
color('#f00').hex() === color('#e00').red(1).hex(); // true
```

Use the `equals` method to compare two color instances within a certain
epsilon (defaults to `1e-9`).

```javascript
one.color('#e00').lightness(0.00001, true).equals(one.color('#e00'), 1e-5); // false
one.color('#e00').lightness(0.000001, true).equals(one.color('#e00'), 1e-5); // true
color('#e00').lightness(0.00001, true).equals(color('#e00'), 1e-5); // false
color('#e00').lightness(0.000001, true).equals(color('#e00'), 1e-5); // true
```

Before comparing the `equals` method converts the other color to the right colorspace,
so you don't need to convert explicitly in this case either:

```javascript
one.color('#e00').hsv().equals(one.color('#e00')); // true
color('#e00').hsv().equals(color('#e00')); // true
```

# API overview

Color parser function, the recommended way to create a color instance:

```javascript
one.color('#a9d91d'); // Regular hex syntax
one.color('a9d91d'); // hex syntax, # is optional
one.color('#eee'); // Short hex syntax
one.color('rgb(124, 96, 200)'); // CSS rgb syntax
one.color('rgb(99%, 40%, 0%)'); // CSS rgb syntax with percentages
one.color('rgba(124, 96, 200, .4)'); // CSS rgba syntax
one.color('hsl(120, 75%, 75%)'); // CSS hsl syntax
one.color('hsla(120, 75%, 75%, .1)'); // CSS hsla syntax
one.color('hsv(220, 47%, 12%)'); // CSS hsv syntax (non-standard)
one.color('hsva(120, 75%, 75%, 0)'); // CSS hsva syntax (non-standard)
one.color([0, 4, 255, 120]); // CanvasPixelArray entry, RGBA
one.color(['RGB', 0.5, 0.1, 0.6, 0.9]); // The output format of color.toJSON()
color('#a9d91d'); // Regular hex syntax
color('a9d91d'); // hex syntax, # is optional
color('#eee'); // Short hex syntax
color('rgb(124, 96, 200)'); // CSS rgb syntax
color('rgb(99%, 40%, 0%)'); // CSS rgb syntax with percentages
color('rgba(124, 96, 200, .4)'); // CSS rgba syntax
color('hsl(120, 75%, 75%)'); // CSS hsl syntax
color('hsla(120, 75%, 75%, .1)'); // CSS hsla syntax
color('hsv(220, 47%, 12%)'); // CSS hsv syntax (non-standard)
color('hsva(120, 75%, 75%, 0)'); // CSS hsva syntax (non-standard)
color([0, 4, 255, 120]); // CanvasPixelArray entry, RGBA
color(['RGB', 0.5, 0.1, 0.6, 0.9]); // The output format of color.toJSON()
```

The slightly bigger <a href="//raw.github.com/One-com/one-color/master/one-color-all.js">one-color-all.js</a> build adds support for
<a href='http://en.wikipedia.org/wiki/Web_colors'>the standard suite of named CSS colors</a>:

```javascript
one.color('maroon');
one.color('darkolivegreen');
color('maroon');
color('darkolivegreen');
```

Existing one.color instances pass through unchanged, which is useful
Existing onecolor instances pass through unchanged, which is useful
in APIs where you want to accept either a string or a color instance:

```javascript
one.color(one.color('#fff')); // Same as one.color('#fff')
color(color('#fff')); // Same as color('#fff')
```

Serialization methods:

```javascript
color.hex(); // 6-digit hex string: '#bda65b'
color.css(); // CSS rgb syntax: 'rgb(10,128,220)'
color.cssa(); // CSS rgba syntax: 'rgba(10,128,220,0.8)'
color.toString(); // For debugging: '[one.color.RGB: Red=0.3 Green=0.8 Blue=0 Alpha=1]'
color.toJSON(); // ["RGB"|"HSV"|"HSL", <number>, <number>, <number>, <number>]
var myColor = color('#bda65b');

myColor.hex(); // 6-digit hex string: '#bda65b'
myColor.css(); // CSS rgb syntax: 'rgb(10,128,220)'
myColor.cssa(); // CSS rgba syntax: 'rgba(10,128,220,0.8)'
myColor.toString(); // For debugging: '[onecolor.RGB: Red=0.3 Green=0.8 Blue=0 Alpha=1]'
myColor.toJSON(); // ["RGB"|"HSV"|"HSL", <number>, <number>, <number>, <number>]
```

Getters -- return the value of the channel (converts to other colorspaces as needed):

```javascript
color.red();
color.green();
color.blue();
color.hue();
color.saturation();
color.value();
color.lightness();
color.alpha();
color.cyan(); // one-color-all.js and node.js only
color.magenta(); // one-color-all.js and node.js only
color.yellow(); // one-color-all.js and node.js only
color.black(); // one-color-all.js and node.js only
var myColor = color('#bda65b');

myColor.red();
myColor.green();
myColor.blue();
myColor.hue();
myColor.saturation();
myColor.value();
myColor.lightness();
myColor.alpha();
myColor.cyan(); // one-color-all.js and node.js only
myColor.magenta(); // one-color-all.js and node.js only
myColor.yellow(); // one-color-all.js and node.js only
myColor.black(); // one-color-all.js and node.js only
```

Setters -- return new color instances with one channel changed:

<!-- evaldown evaluate:false -->

```javascript
color.red(<number>)
color.green(<number>)
Expand All @@ -241,6 +250,8 @@ color.black(<number>) // one-color-all.js and node.js only
Adjusters -- return new color instances with the channel adjusted by
the specified delta (0..1):

<!-- evaldown evaluate:false -->

```javascript
color.red(<number>, true)
color.green(<number>, true)
Expand All @@ -258,6 +269,8 @@ color.black(<number>, true) // one-color-all.js and node.js only

Comparison with other color objects, returns `true` or `false` (epsilon defaults to `1e-9`):

<!-- evaldown evaluate:false -->

```javascript
color.equals(otherColor[, <epsilon>])
```
Expand All @@ -267,15 +280,15 @@ color.equals(otherColor[, <epsilon>])
"Low level" constructors, accept 3 or 4 numerical arguments (0..1):

```javascript
new one.color.RGB(<red>, <green>, <blue>[, <alpha>])
new one.color.HSL(<hue>, <saturation>, <lightness>[, <alpha>])
new one.color.HSV(<hue>, <saturation>, <value>[, <alpha>])
new onecolor.RGB(<red>, <green>, <blue>[, <alpha>])
new onecolor.HSL(<hue>, <saturation>, <lightness>[, <alpha>])
new onecolor.HSV(<hue>, <saturation>, <value>[, <alpha>])
```

The <a href="//raw.github.com/One-com/one-color/master/one-color-all.js">one-color-all.js</a> build includes CMYK support:

```javascript
new one.color.CMYK(<cyan>, <magenta>, <yellow>, <black>[, <alpha>])
new onecolor.CMYK(<cyan>, <magenta>, <yellow>, <black>[, <alpha>])
```

All color instances have `rgb()`, `hsv()`, and `hsl()` methods for
Expand All @@ -288,12 +301,15 @@ specific colorspace, do an explicit conversion first to cut down on
the number of implicit conversions:

```javascript
var myColor = one
.color('#0620ff')
var myColor = color('#0620ff')
.lightness(+0.3)
.rgb();
// Alerts '0 0.06265060240963878 0.5999999999999999':
alert(myColor.red() + ' ' + myColor.green() + ' ' + myColor.blue());

console.log(myColor.red() + ' ' + myColor.green() + ' ' + myColor.blue());
```

```output
'0 0.06265060240963878 0.5999999999999999'
```

# Building
Expand All @@ -313,4 +329,4 @@ packages in the repository as well as the npm package:

# License

one.color is licensed under a standard 2-clause BSD license -- see the `LICENSE` file for details.
onecolor is licensed under a standard 2-clause BSD license -- see the `LICENSE` file for details.
3 changes: 3 additions & 0 deletions package.json
View file
Expand Up @@ -34,9 +34,11 @@
"eslint-plugin-node": "^11.1.0",
"eslint-plugin-promise": "^4.2.1",
"eslint-plugin-standard": "^4.0.1",
"evaldown": "^1.1.2",
"istanbul": "0.4.2",
"mocha": "2.4.5",
"mocha-lcov-reporter": "1.2.0",
"onecolor": "file:./",
"prettier": "^2.0.5",
"rollup": "^2.21.0",
"rollup-plugin-terser": "^6.1.0",
Expand All @@ -61,6 +63,7 @@
"preversion": "npm run lint && npm run build && TEST_BUNDLES=true npm test && bash -c 'git add one-color{-all,}.{js,map}'",
"lint": "eslint . && prettier --check '**/*.{js,md}'",
"test": "npm run lint && mocha",
"test:documentation": "evaldown --validate --capture=console ./README.md",
"coverage": "istanbul cover _mocha -- --reporter dot",
"ci:test": "TEST_BUNDLES=true npm run coverage"
},
Expand Down

0 comments on commit d76a0ca

Please sign in to comment.