diff options
Diffstat (limited to 'deps/npm/node_modules/update-notifier/node_modules/chalk/readme.md')
| -rw-r--r-- | deps/npm/node_modules/update-notifier/node_modules/chalk/readme.md | 253 |
1 files changed, 173 insertions, 80 deletions
diff --git a/deps/npm/node_modules/update-notifier/node_modules/chalk/readme.md b/deps/npm/node_modules/update-notifier/node_modules/chalk/readme.md index 5cf111e353..dfcfdf25d8 100644 --- a/deps/npm/node_modules/update-notifier/node_modules/chalk/readme.md +++ b/deps/npm/node_modules/update-notifier/node_modules/chalk/readme.md @@ -1,7 +1,7 @@ <h1 align="center"> <br> <br> - <img width="360" src="https://cdn.rawgit.com/chalk/chalk/19935d6484811c5e468817f846b7b3d417d7bf4a/logo.svg" alt="chalk"> + <img width="320" src="https://cdn.rawgit.com/chalk/chalk/19935d6484811c5e468817f846b7b3d417d7bf4a/logo.svg" alt="chalk"> <br> <br> <br> @@ -9,81 +9,104 @@ > Terminal string styling done right -[](https://travis-ci.org/chalk/chalk) -[](https://coveralls.io/r/chalk/chalk?branch=master) -[](https://www.youtube.com/watch?v=9auOCbH5Ns4) +[](https://travis-ci.org/chalk/chalk) [](https://coveralls.io/github/chalk/chalk?branch=master) [](https://www.youtube.com/watch?v=9auOCbH5Ns4) [](https://github.com/sindresorhus/xo) - -[colors.js](https://github.com/Marak/colors.js) used to be the most popular string styling module, but it has serious deficiencies like extending `String.prototype` which causes all kinds of [problems](https://github.com/yeoman/yo/issues/68). Although there are other ones, they either do too much or not enough. - -**Chalk is a clean and focused alternative.** +### [See what's new in Chalk 2](https://github.com/chalk/chalk/releases/tag/v2.0.0)  -## Why +## Highlights -- Highly performant -- Doesn't extend `String.prototype` - Expressive API +- Highly performant - Ability to nest styles -- Clean and focused +- [256/Truecolor color support](#256-and-truecolor-color-support) - Auto-detects color support +- Doesn't extend `String.prototype` +- Clean and focused - Actively maintained -- [Used by ~4500 modules](https://www.npmjs.com/browse/depended/chalk) as of July 15, 2015 +- [Used by ~17,000 packages](https://www.npmjs.com/browse/depended/chalk) as of June 20th, 2017 ## Install -``` -$ npm install --save chalk +```console +$ npm install chalk ``` ## Usage +```js +const chalk = require('chalk'); + +console.log(chalk.blue('Hello world!')); +``` + Chalk comes with an easy to use composable API where you just chain and nest the styles you want. ```js -var chalk = require('chalk'); - -// style a string -chalk.blue('Hello world!'); +const chalk = require('chalk'); +const log = console.log; -// combine styled and normal strings -chalk.blue('Hello') + 'World' + chalk.red('!'); +// Combine styled and normal strings +log(chalk.blue('Hello') + 'World' + chalk.red('!')); -// compose multiple styles using the chainable API -chalk.blue.bgRed.bold('Hello world!'); +// Compose multiple styles using the chainable API +log(chalk.blue.bgRed.bold('Hello world!')); -// pass in multiple arguments -chalk.blue('Hello', 'World!', 'Foo', 'bar', 'biz', 'baz'); +// Pass in multiple arguments +log(chalk.blue('Hello', 'World!', 'Foo', 'bar', 'biz', 'baz')); -// nest styles -chalk.red('Hello', chalk.underline.bgBlue('world') + '!'); +// Nest styles +log(chalk.red('Hello', chalk.underline.bgBlue('world') + '!')); -// nest styles of the same type even (color, underline, background) -chalk.green( +// Nest styles of the same type even (color, underline, background) +log(chalk.green( 'I am a green line ' + chalk.blue.underline.bold('with a blue substring') + ' that becomes green again!' -); +)); + +// ES2015 template literal +log(` +CPU: ${chalk.red('90%')} +RAM: ${chalk.green('40%')} +DISK: ${chalk.yellow('70%')} +`); + +// ES2015 tagged template literal +log(chalk` +CPU: {red ${cpu.totalPercent}%} +RAM: {green ${ram.used / ram.total * 100}%} +DISK: {rgb(255,131,0) ${disk.used / disk.total * 100}%} +`); + +// Use RGB colors in terminal emulators that support it. +log(chalk.keyword('orange')('Yay for orange colored text!')); +log(chalk.rgb(123, 45, 67).underline('Underlined reddish color')); +log(chalk.hex('#DEADED').bold('Bold gray!')); ``` -Easily define your own themes. +Easily define your own themes: ```js -var chalk = require('chalk'); -var error = chalk.bold.red; +const chalk = require('chalk'); + +const error = chalk.bold.red; +const warning = chalk.keyword('orange'); + console.log(error('Error!')); +console.log(warning('Warning!')); ``` -Take advantage of console.log [string substitution](http://nodejs.org/docs/latest/api/console.html#console_console_log_data). +Take advantage of console.log [string substitution](https://nodejs.org/docs/latest/api/console.html#console_console_log_data_args): ```js -var name = 'Sindre'; +const name = 'Sindre'; console.log(chalk.green('Hello %s'), name); -//=> Hello Sindre +//=> 'Hello Sindre' ``` @@ -93,61 +116,46 @@ console.log(chalk.green('Hello %s'), name); Example: `chalk.red.bold.underline('Hello', 'world');` -Chain [styles](#styles) and call the last one as a method with a string argument. Order doesn't matter, and later styles take precedent in case of a conflict. This simply means that `Chalk.red.yellow.green` is equivalent to `Chalk.green`. +Chain [styles](#styles) and call the last one as a method with a string argument. Order doesn't matter, and later styles take precedent in case of a conflict. This simply means that `chalk.red.yellow.green` is equivalent to `chalk.green`. Multiple arguments will be separated by space. ### chalk.enabled -Color support is automatically detected, but you can override it by setting the `enabled` property. You should however only do this in your own code as it applies globally to all chalk consumers. +Color support is automatically detected, as is the level (see `chalk.level`). However, if you'd like to simply enable/disable Chalk, you can do so via the `.enabled` property. + +Chalk is enabled by default unless expicitly disabled via the constructor or `chalk.level` is `0`. -If you need to change this in a reusable module create a new instance: +If you need to change this in a reusable module, create a new instance: ```js -var ctx = new chalk.constructor({enabled: false}); +const ctx = new chalk.constructor({enabled: false}); ``` -### chalk.supportsColor - -Detect whether the terminal [supports color](https://github.com/chalk/supports-color). Used internally and handled for you, but exposed for convenience. - -Can be overridden by the user with the flags `--color` and `--no-color`. For situations where using `--color` is not possible, add an environment variable `FORCE_COLOR` with any value to force color. Trumps `--no-color`. - -### chalk.styles +### chalk.level -Exposes the styles as [ANSI escape codes](https://github.com/chalk/ansi-styles). +Color support is automatically detected, but you can override it by setting the `level` property. You should however only do this in your own code as it applies globally to all Chalk consumers. -Generally not useful, but you might need just the `.open` or `.close` escape code if you're mixing externally styled strings with your own. +If you need to change this in a reusable module, create a new instance: ```js -var chalk = require('chalk'); - -console.log(chalk.styles.red); -//=> {open: '\u001b[31m', close: '\u001b[39m'} - -console.log(chalk.styles.red.open + 'Hello' + chalk.styles.red.close); +const ctx = new chalk.constructor({level: 0}); ``` -### chalk.hasColor(string) - -Check whether a string [has color](https://github.com/chalk/has-ansi). - -### chalk.stripColor(string) +Levels are as follows: -[Strip color](https://github.com/chalk/strip-ansi) from a string. +0. All colors disabled +1. Basic color support (16 colors) +2. 256 color support +3. Truecolor support (16 million colors) -Can be useful in combination with `.supportsColor` to strip color on externally styled text when it's not supported. +### chalk.supportsColor -Example: +Detect whether the terminal [supports color](https://github.com/chalk/supports-color). Used internally and handled for you, but exposed for convenience. -```js -var chalk = require('chalk'); -var styledString = getText(); +Can be overridden by the user with the flags `--color` and `--no-color`. For situations where using `--color` is not possible, add the environment variable `FORCE_COLOR=1` to forcefully enable color or `FORCE_COLOR=0` to forcefully disable. The use of `FORCE_COLOR` overrides all other color support checks. -if (!chalk.supportsColor) { - styledString = chalk.stripColor(styledString); -} -``` +Explicit 256/Truecolor mode can be enabled using the `--color=256` and `--color=16m` flags, respectively. ## Styles @@ -157,11 +165,11 @@ if (!chalk.supportsColor) { - `reset` - `bold` - `dim` -- `italic` *(not widely supported)* +- `italic` *(Not widely supported)* - `underline` - `inverse` - `hidden` -- `strikethrough` *(not widely supported)* +- `strikethrough` *(Not widely supported)* ### Colors @@ -169,11 +177,18 @@ if (!chalk.supportsColor) { - `red` - `green` - `yellow` -- `blue` *(on Windows the bright version is used as normal blue is illegible)* +- `blue` *(On Windows the bright version is used since normal blue is illegible)* - `magenta` - `cyan` - `white` -- `gray` +- `gray` ("bright black") +- `redBright` +- `greenBright` +- `yellowBright` +- `blueBright` +- `magentaBright` +- `cyanBright` +- `whiteBright` ### Background colors @@ -185,29 +200,107 @@ if (!chalk.supportsColor) { - `bgMagenta` - `bgCyan` - `bgWhite` +- `bgBlackBright` +- `bgRedBright` +- `bgGreenBright` +- `bgYellowBright` +- `bgBlueBright` +- `bgMagentaBright` +- `bgCyanBright` +- `bgWhiteBright` + + +## Tagged template literal + +Chalk can be used as a [tagged template literal](http://exploringjs.com/es6/ch_template-literals.html#_tagged-template-literals). + +```js +const chalk = require('chalk'); + +const miles = 18; +const calculateFeet = miles => miles * 5280; + +console.log(chalk` + There are {bold 5280 feet} in a mile. + In {bold ${miles} miles}, there are {green.bold ${calculateFeet(miles)} feet}. +`); +``` + +Blocks are delimited by an opening curly brace (`{`), a style, some content, and a closing curly brace (`}`). + +Template styles are chained exactly like normal Chalk styles. The following two statements are equivalent: + +```js +console.log(chalk.bold.rgb(10, 100, 200)('Hello!')); +console.log(chalk`{bold.rgb(10,100,200) Hello!}`); +``` + +Note that function styles (`rgb()`, `hsl()`, `keyword()`, etc.) may not contain spaces between parameters. +All interpolated values (`` chalk`${foo}` ``) are converted to strings via the `.toString()` method. All curly braces (`{` and `}`) in interpolated value strings are escaped. -## 256-colors -Chalk does not support anything other than the base eight colors, which guarantees it will work on all terminals and systems. Some terminals, specifically `xterm` compliant ones, will support the full range of 8-bit colors. For this the lower level [ansi-256-colors](https://github.com/jbnicolai/ansi-256-colors) package can be used. +## 256 and Truecolor color support + +Chalk supports 256 colors and [Truecolor](https://gist.github.com/XVilka/8346728) (16 million colors) on supported terminal apps. + +Colors are downsampled from 16 million RGB values to an ANSI color format that is supported by the terminal emulator (or by specifying `{level: n}` as a Chalk option). For example, Chalk configured to run at level 1 (basic color support) will downsample an RGB value of #FF0000 (red) to 31 (ANSI escape for red). + +Examples: + +- `chalk.hex('#DEADED').underline('Hello, world!')` +- `chalk.keyword('orange')('Some orange text')` +- `chalk.rgb(15, 100, 204).inverse('Hello!')` + +Background versions of these models are prefixed with `bg` and the first level of the module capitalized (e.g. `keyword` for foreground colors and `bgKeyword` for background colors). + +- `chalk.bgHex('#DEADED').underline('Hello, world!')` +- `chalk.bgKeyword('orange')('Some orange text')` +- `chalk.bgRgb(15, 100, 204).inverse('Hello!')` + +The following color models can be used: + +- [`rgb`](https://en.wikipedia.org/wiki/RGB_color_model) - Example: `chalk.rgb(255, 136, 0).bold('Orange!')` +- [`hex`](https://en.wikipedia.org/wiki/Web_colors#Hex_triplet) - Example: `chalk.hex('#FF8800').bold('Orange!')` +- [`keyword`](https://www.w3.org/wiki/CSS/Properties/color/keywords) (CSS keywords) - Example: `chalk.keyword('orange').bold('Orange!')` +- [`hsl`](https://en.wikipedia.org/wiki/HSL_and_HSV) - Example: `chalk.hsl(32, 100, 50).bold('Orange!')` +- [`hsv`](https://en.wikipedia.org/wiki/HSL_and_HSV) - Example: `chalk.hsl(32, 1, 1).bold('Orange!')` +- [`hwb`](https://en.wikipedia.org/wiki/HWB_color_model) - Example: `chalk.hsl(32, 0, 50).bold('Orange!')` +- `ansi16` +- `ansi256` ## Windows -If you're on Windows, do yourself a favor and use [`cmder`](http://bliker.github.io/cmder/) instead of `cmd.exe`. +If you're on Windows, do yourself a favor and use [`cmder`](http://cmder.net/) instead of `cmd.exe`. + + +## Origin story + +[colors.js](https://github.com/Marak/colors.js) used to be the most popular string styling module, but it has serious deficiencies like extending `String.prototype` which causes all kinds of [problems](https://github.com/yeoman/yo/issues/68) and the package is unmaintained. Although there are other packages, they either do too much or not enough. Chalk is a clean and focused alternative. ## Related - [chalk-cli](https://github.com/chalk/chalk-cli) - CLI for this module -- [ansi-styles](https://github.com/chalk/ansi-styles/) - ANSI escape codes for styling strings in the terminal -- [supports-color](https://github.com/chalk/supports-color/) - Detect whether a terminal supports color +- [ansi-styles](https://github.com/chalk/ansi-styles) - ANSI escape codes for styling strings in the terminal +- [supports-color](https://github.com/chalk/supports-color) - Detect whether a terminal supports color - [strip-ansi](https://github.com/chalk/strip-ansi) - Strip ANSI escape codes - [has-ansi](https://github.com/chalk/has-ansi) - Check if a string has ANSI escape codes - [ansi-regex](https://github.com/chalk/ansi-regex) - Regular expression for matching ANSI escape codes - [wrap-ansi](https://github.com/chalk/wrap-ansi) - Wordwrap a string with ANSI escape codes +- [slice-ansi](https://github.com/chalk/slice-ansi) - Slice a string with ANSI escape codes +- [color-convert](https://github.com/qix-/color-convert) - Converts colors between different models +- [chalk-animation](https://github.com/bokub/chalk-animation) - Animate strings in the terminal +- [gradient-string](https://github.com/bokub/gradient-string) - Apply color gradients to strings + + +## Maintainers + +- [Sindre Sorhus](https://github.com/sindresorhus) +- [Josh Junon](https://github.com/qix-) ## License -MIT © [Sindre Sorhus](http://sindresorhus.com) +MIT |