diff options
Diffstat (limited to 'tools/node_modules/eslint/node_modules/table/README.md')
| -rw-r--r-- | tools/node_modules/eslint/node_modules/table/README.md | 671 |
1 files changed, 671 insertions, 0 deletions
diff --git a/tools/node_modules/eslint/node_modules/table/README.md b/tools/node_modules/eslint/node_modules/table/README.md new file mode 100644 index 0000000000..76613d4b7c --- /dev/null +++ b/tools/node_modules/eslint/node_modules/table/README.md @@ -0,0 +1,671 @@ +<a name="table"></a> +# Table + +[](https://travis-ci.org/gajus/table) +[](https://www.npmjs.com/package/table) +[](https://github.com/gajus/canonical) + +* [Table](#table) + * [Features](#table-features) + * [Usage](#table-usage) + * [Cell Content Alignment](#table-usage-cell-content-alignment) + * [Column Width](#table-usage-column-width) + * [Custom Border](#table-usage-custom-border) + * [Draw Horizontal Line](#table-usage-draw-horizontal-line) + * [Padding Cell Content](#table-usage-padding-cell-content) + * [Predefined Border Templates](#table-usage-predefined-border-templates) + * [Streaming](#table-usage-streaming) + * [Text Truncation](#table-usage-text-truncation) + * [Text Wrapping](#table-usage-text-wrapping) + + +Produces a string that represents array data in a text table. + + + +<a name="table-features"></a> +## Features + +* Works with strings containing [fullwidth](https://en.wikipedia.org/wiki/Halfwidth_and_fullwidth_forms) characters. +* Works with strings containing [ANSI escape codes](https://en.wikipedia.org/wiki/ANSI_escape_code). +* Configurable border characters. +* Configurable content alignment per column. +* Configurable content padding per column. +* Configurable column width. +* Text wrapping. + +<a name="table-usage"></a> +## Usage + +Table data is described using an array (rows) of array (cells). + +```js +import { + table +} from 'table'; + +// Using commonjs? +// const {table} = require('table'); + +let data, + output; + +data = [ + ['0A', '0B', '0C'], + ['1A', '1B', '1C'], + ['2A', '2B', '2C'] +]; + +/** + * @typedef {string} table~cell + */ + +/** + * @typedef {table~cell[]} table~row + */ + +/** + * @typedef {Object} table~columns + * @property {string} alignment Cell content alignment (enum: left, center, right) (default: left). + * @property {number} width Column width (default: auto). + * @property {number} truncate Number of characters are which the content will be truncated (default: Infinity). + * @property {number} paddingLeft Cell content padding width left (default: 1). + * @property {number} paddingRight Cell content padding width right (default: 1). + */ + +/** + * @typedef {Object} table~border + * @property {string} topBody + * @property {string} topJoin + * @property {string} topLeft + * @property {string} topRight + * @property {string} bottomBody + * @property {string} bottomJoin + * @property {string} bottomLeft + * @property {string} bottomRight + * @property {string} bodyLeft + * @property {string} bodyRight + * @property {string} bodyJoin + * @property {string} joinBody + * @property {string} joinLeft + * @property {string} joinRight + * @property {string} joinJoin + */ + +/** + * Used to dynamically tell table whether to draw a line separating rows or not. + * The default behavior is to always return true. + * + * @typedef {function} drawJoin + * @param {number} index + * @param {number} size + * @return {boolean} + */ + +/** + * @typedef {Object} table~config + * @property {table~border} border + * @property {table~columns[]} columns Column specific configuration. + * @property {table~columns} columnDefault Default values for all columns. Column specific settings overwrite the default values. + * @property {table~drawJoin} drawHorizontalLine + */ + +/** + * Generates a text table. + * + * @param {table~row[]} rows + * @param {table~config} config + * @return {String} + */ +output = table(data); + +console.log(output); +``` + +``` +╔════╤════╤════╗ +║ 0A │ 0B │ 0C ║ +╟────┼────┼────╢ +║ 1A │ 1B │ 1C ║ +╟────┼────┼────╢ +║ 2A │ 2B │ 2C ║ +╚════╧════╧════╝ +``` + + +<a name="table-usage-cell-content-alignment"></a> +### Cell Content Alignment + +`{string} config.columns[{number}].alignment` property controls content horizontal alignment within a cell. + +Valid values are: "left", "right" and "center". + +```js +let config, + data, + output; + +data = [ + ['0A', '0B', '0C'], + ['1A', '1B', '1C'], + ['2A', '2B', '2C'] +]; + +config = { + columns: { + 0: { + alignment: 'left', + minWidth: 10 + }, + 1: { + alignment: 'center', + minWidth: 10 + }, + 2: { + alignment: 'right', + minWidth: 10 + } + } +}; + +output = table(data, config); + +console.log(output); +``` + +``` +╔════════════╤════════════╤════════════╗ +║ 0A │ 0B │ 0C ║ +╟────────────┼────────────┼────────────╢ +║ 1A │ 1B │ 1C ║ +╟────────────┼────────────┼────────────╢ +║ 2A │ 2B │ 2C ║ +╚════════════╧════════════╧════════════╝ +``` + +<a name="table-usage-column-width"></a> +### Column Width + +`{number} config.columns[{number}].width` property restricts column width to a fixed width. + +```js +let data, + output, + options; + +data = [ + ['0A', '0B', '0C'], + ['1A', '1B', '1C'], + ['2A', '2B', '2C'] +]; + +options = { + columns: { + 1: { + width: 10 + } + } +}; + +output = table(data, options); + +console.log(output); +``` + +``` +╔════╤════════════╤════╗ +║ 0A │ 0B │ 0C ║ +╟────┼────────────┼────╢ +║ 1A │ 1B │ 1C ║ +╟────┼────────────┼────╢ +║ 2A │ 2B │ 2C ║ +╚════╧════════════╧════╝ +``` + +<a name="table-usage-custom-border"></a> +### Custom Border + +`{object} config.border` property describes characters used to draw the table border. + +```js +let config, + data, + output; + +data = [ + ['0A', '0B', '0C'], + ['1A', '1B', '1C'], + ['2A', '2B', '2C'] +]; + +config = { + border: { + topBody: `─`, + topJoin: `┬`, + topLeft: `┌`, + topRight: `┐`, + + bottomBody: `─`, + bottomJoin: `┴`, + bottomLeft: `└`, + bottomRight: `┘`, + + bodyLeft: `│`, + bodyRight: `│`, + bodyJoin: `│`, + + joinBody: `─`, + joinLeft: `├`, + joinRight: `┤`, + joinJoin: `┼` + } +}; + +output = table(data, config); + +console.log(output); +``` + +``` +┌────┬────┬────┐ +│ 0A │ 0B │ 0C │ +├────┼────┼────┤ +│ 1A │ 1B │ 1C │ +├────┼────┼────┤ +│ 2A │ 2B │ 2C │ +└────┴────┴────┘ +``` + +<a name="table-usage-draw-horizontal-line"></a> +### Draw Horizontal Line + +`{function} config.drawHorizontalLine` property is a function that is called for every non-content row in the table. The result of the function `{boolean}` determines whether a row is drawn. + +```js +let data, + output, + options; + +data = [ + ['0A', '0B', '0C'], + ['1A', '1B', '1C'], + ['2A', '2B', '2C'], + ['3A', '3B', '3C'], + ['4A', '4B', '4C'] +]; + +options = { + /** + * @typedef {function} drawJoin + * @param {number} index + * @param {number} size + * @return {boolean} + */ + drawHorizontalLine: (index, size) => { + return index === 0 || index === 1 || index === size - 1 || index === size; + } +}; + +output = table(data, options); + +console.log(output); +``` + +``` +╔════╤════╤════╗ +║ 0A │ 0B │ 0C ║ +╟────┼────┼────╢ +║ 1A │ 1B │ 1C ║ +║ 2A │ 2B │ 2C ║ +║ 3A │ 3B │ 3C ║ +╟────┼────┼────╢ +║ 4A │ 4B │ 4C ║ +╚════╧════╧════╝ +``` + +<a name="table-usage-padding-cell-content"></a> +### Padding Cell Content + +`{number} config.columns[{number}].paddingLeft` and `{number} config.columns[{number}].paddingRight` properties control content padding within a cell. Property value represents a number of whitespaces used to pad the content. + +```js +let config, + data, + output; + +data = [ + ['0A', 'AABBCC', '0C'], + ['1A', '1B', '1C'], + ['2A', '2B', '2C'] +]; + +config = { + columns: { + 0: { + paddingLeft: 3 + }, + 1: { + width: 2, + paddingRight: 3 + } + } +}; + +output = table(data, config); + +console.log(output); +``` + +``` +╔══════╤══════╤════╗ +║ 0A │ AA │ 0C ║ +║ │ BB │ ║ +║ │ CC │ ║ +╟──────┼──────┼────╢ +║ 1A │ 1B │ 1C ║ +╟──────┼──────┼────╢ +║ 2A │ 2B │ 2C ║ +╚══════╧══════╧════╝ +``` + +<a name="table-usage-predefined-border-templates"></a> +### Predefined Border Templates + +You can load one of the predefined border templates using `getBorderCharacters` function. + +```js +import { + table, + getBorderCharacters +} from 'table'; + +let config, + data; + +data = [ + ['0A', '0B', '0C'], + ['1A', '1B', '1C'], + ['2A', '2B', '2C'] +]; + +config = { + border: getBorderCharacters(`name of the template`) +}; + +table(data, config); +``` + +``` +# honeywell + +╔════╤════╤════╗ +║ 0A │ 0B │ 0C ║ +╟────┼────┼────╢ +║ 1A │ 1B │ 1C ║ +╟────┼────┼────╢ +║ 2A │ 2B │ 2C ║ +╚════╧════╧════╝ + +# norc + +┌────┬────┬────┐ +│ 0A │ 0B │ 0C │ +├────┼────┼────┤ +│ 1A │ 1B │ 1C │ +├────┼────┼────┤ +│ 2A │ 2B │ 2C │ +└────┴────┴────┘ + +# ramac (ASCII; for use in terminals that do not support Unicode characters) + ++----+----+----+ +| 0A | 0B | 0C | +|----|----|----| +| 1A | 1B | 1C | +|----|----|----| +| 2A | 2B | 2C | ++----+----+----+ + +# void (no borders; see "bordless table" section of the documentation) + + 0A 0B 0C + + 1A 1B 1C + + 2A 2B 2C + +``` + +Raise [an issue](https://github.com/gajus/table/issues) if you'd like to contribute a new border template. + +<a name="table-usage-predefined-border-templates-borderless-table"></a> +#### Borderless Table + +Simply using "void" border character template creates a table with a lot of unnecessary spacing. + +To create a more plesant to the eye table, reset the padding and remove the joining rows, e.g. + +```js +let output; + +output = table(data, { + border: getBorderCharacters(`void`), + columnDefault: { + paddingLeft: 0, + paddingRight: 1 + }, + drawJoin: () => { + return false + } +}); + +console.log(output); +``` + +``` +0A 0B 0C +1A 1B 1C +2A 2B 2C +``` + +<a name="table-usage-streaming"></a> +### Streaming + +`table` package exports `createStream` function used to draw a table and append rows. + +`createStream` requires `{number} columnDefault.width` and `{number} columnCount` configuration properties. + +```js +import { + createStream +} from 'table'; + +let config, + stream; + +config = { + columnDefault: { + width: 50 + }, + columnCount: 1 +}; + +stream = createStream(config); + +setInterval(() => { + stream.write([new Date()]); +}, 500); +``` + + + +`table` package uses ANSI escape codes to overwrite the output of the last line when a new row is printed. + +The underlying implementation is explained in this [Stack Overflow answer](http://stackoverflow.com/a/32938658/368691). + +Streaming supports all of the configuration properties and functionality of a static table (such as auto text wrapping, alignment and padding), e.g. + +```js +import { + createStream +} from 'table'; + +import _ from 'lodash'; + +let config, + stream, + i; + +config = { + columnDefault: { + width: 50 + }, + columnCount: 3, + columns: { + 0: { + width: 10, + alignment: 'right' + }, + 1: { + alignment: 'center', + }, + 2: { + width: 10 + } + } +}; + +stream = createStream(config); + +i = 0; + +setInterval(() => { + let random; + + random = _.sample('abcdefghijklmnopqrstuvwxyz', _.random(1, 30)).join(''); + + stream.write([i++, new Date(), random]); +}, 500); +``` + + +<a name="table-usage-text-truncation"></a> +### Text Truncation + +To handle a content that overflows the container width, `table` package implements [text wrapping](#table-usage-text-wrapping). However, sometimes you may want to truncate content that is too long to be displayed in the table. + +`{number} config.columns[{number}].truncate` property (default: `Infinity`) truncates the text at the specified length. + +```js +let config, + data, + output; + +data = [ + ['Lorem ipsum dolor sit amet, consectetur adipiscing elit. Phasellus pulvinar nibh sed mauris convallis dapibus. Nunc venenatis tempus nulla sit amet viverra.'] +]; + +config = { + columns: { + 0: { + width: 20, + truncate: 100 + } + } +}; + +output = table(data, config); + +console.log(output); +``` + +``` +╔══════════════════════╗ +║ Lorem ipsum dolor si ║ +║ t amet, consectetur ║ +║ adipiscing elit. Pha ║ +║ sellus pulvinar nibh ║ +║ sed mauris conva... ║ +╚══════════════════════╝ +``` + +<a name="table-usage-text-wrapping"></a> +### Text Wrapping + +`table` package implements auto text wrapping, i.e. text that has width greater than the container width will be separated into multiple lines, e.g. + +```js +let config, + data, + output; + +data = [ + ['Lorem ipsum dolor sit amet, consectetur adipiscing elit. Phasellus pulvinar nibh sed mauris convallis dapibus. Nunc venenatis tempus nulla sit amet viverra.'] +]; + +config = { + columns: { + 0: { + width: 20 + } + } +}; + +output = table(data, config); + +console.log(output); +``` + +``` +╔══════════════════════╗ +║ Lorem ipsum dolor si ║ +║ t amet, consectetur ║ +║ adipiscing elit. Pha ║ +║ sellus pulvinar nibh ║ +║ sed mauris convallis ║ +║ dapibus. Nunc venena ║ +║ tis tempus nulla sit ║ +║ amet viverra. ║ +╚══════════════════════╝ +``` + +When `wrapWord` is `true` the text is broken at the nearest space or one of the special characters ("-", "_", "\", "/", ".", ",", ";"), e.g. + +```js +let config, + data, + output; + +data = [ + ['Lorem ipsum dolor sit amet, consectetur adipiscing elit. Phasellus pulvinar nibh sed mauris convallis dapibus. Nunc venenatis tempus nulla sit amet viverra.'] +]; + +config = { + columns: { + 0: { + width: 20, + wrapWord: true + } + } +}; + +output = table(data, config); + +console.log(output); +``` + +``` +╔══════════════════════╗ +║ Lorem ipsum dolor ║ +║ sit amet, ║ +║ consectetur ║ +║ adipiscing elit. ║ +║ Phasellus pulvinar ║ +║ nibh sed mauris ║ +║ convallis dapibus. ║ +║ Nunc venenatis ║ +║ tempus nulla sit ║ +║ amet viverra. ║ +╚══════════════════════╝ +``` + |