4 [![Travis build status](http://img.shields.io/travis/gajus/table/master.svg?style=flat)](https://travis-ci.org/gajus/table)
5 [![NPM version](http://img.shields.io/npm/v/table.svg?style=flat)](https://www.npmjs.com/package/table)
6 [![js-canonical-style](https://img.shields.io/badge/code%20style-canonical-brightgreen.svg?style=flat)](https://github.com/gajus/canonical)
9 * [Features](#table-features)
10 * [Usage](#table-usage)
11 * [Cell Content Alignment](#table-usage-cell-content-alignment)
12 * [Column Width](#table-usage-column-width)
13 * [Custom Border](#table-usage-custom-border)
14 * [Draw Horizontal Line](#table-usage-draw-horizontal-line)
15 * [Padding Cell Content](#table-usage-padding-cell-content)
16 * [Predefined Border Templates](#table-usage-predefined-border-templates)
17 * [Streaming](#table-usage-streaming)
18 * [Text Truncation](#table-usage-text-truncation)
19 * [Text Wrapping](#table-usage-text-wrapping)
22 Produces a string that represents array data in a text table.
24 ![Demo of table displaying a list of missions to the Moon.](./.README/demo.png)
26 <a name="table-features"></a>
29 * Works with strings containing [fullwidth](https://en.wikipedia.org/wiki/Halfwidth_and_fullwidth_forms) characters.
30 * Works with strings containing [ANSI escape codes](https://en.wikipedia.org/wiki/ANSI_escape_code).
31 * Configurable border characters.
32 * Configurable content alignment per column.
33 * Configurable content padding per column.
34 * Configurable column width.
37 <a name="table-usage"></a>
40 Table data is described using an array (rows) of array (cells).
48 // const {table} = require('table');
60 * @typedef {string} table~cell
64 * @typedef {table~cell[]} table~row
68 * @typedef {Object} table~columns
69 * @property {string} alignment Cell content alignment (enum: left, center, right) (default: left).
70 * @property {number} width Column width (default: auto).
71 * @property {number} truncate Number of characters are which the content will be truncated (default: Infinity).
72 * @property {number} paddingLeft Cell content padding width left (default: 1).
73 * @property {number} paddingRight Cell content padding width right (default: 1).
77 * @typedef {Object} table~border
78 * @property {string} topBody
79 * @property {string} topJoin
80 * @property {string} topLeft
81 * @property {string} topRight
82 * @property {string} bottomBody
83 * @property {string} bottomJoin
84 * @property {string} bottomLeft
85 * @property {string} bottomRight
86 * @property {string} bodyLeft
87 * @property {string} bodyRight
88 * @property {string} bodyJoin
89 * @property {string} joinBody
90 * @property {string} joinLeft
91 * @property {string} joinRight
92 * @property {string} joinJoin
96 * Used to dynamically tell table whether to draw a line separating rows or not.
97 * The default behavior is to always return true.
99 * @typedef {function} drawJoin
100 * @param {number} index
101 * @param {number} size
106 * @typedef {Object} table~config
107 * @property {table~border} border
108 * @property {table~columns[]} columns Column specific configuration.
109 * @property {table~columns} columnDefault Default values for all columns. Column specific settings overwrite the default values.
110 * @property {table~drawJoin} drawHorizontalLine
114 * Generates a text table.
116 * @param {table~row[]} rows
117 * @param {table~config} config
120 output = table(data);
136 <a name="table-usage-cell-content-alignment"></a>
137 ### Cell Content Alignment
139 `{string} config.columns[{number}].alignment` property controls content horizontal alignment within a cell.
141 Valid values are: "left", "right" and "center".
171 output = table(data, config);
177 ╔════════════╤════════════╤════════════╗
179 ╟────────────┼────────────┼────────────╢
181 ╟────────────┼────────────┼────────────╢
183 ╚════════════╧════════════╧════════════╝
186 <a name="table-usage-column-width"></a>
189 `{number} config.columns[{number}].width` property restricts column width to a fixed width.
210 output = table(data, options);
216 ╔════╤════════════╤════╗
218 ╟────┼────────────┼────╢
220 ╟────┼────────────┼────╢
222 ╚════╧════════════╧════╝
225 <a name="table-usage-custom-border"></a>
228 `{object} config.border` property describes characters used to draw the table border.
264 output = table(data, config);
279 <a name="table-usage-draw-horizontal-line"></a>
280 ### Draw Horizontal Line
282 `{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.
299 * @typedef {function} drawJoin
300 * @param {number} index
301 * @param {number} size
304 drawHorizontalLine: (index, size) => {
305 return index === 0 || index === 1 || index === size - 1 || index === size;
309 output = table(data, options);
326 <a name="table-usage-padding-cell-content"></a>
327 ### Padding Cell Content
329 `{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.
337 ['0A', 'AABBCC', '0C'],
354 output = table(data, config);
371 <a name="table-usage-predefined-border-templates"></a>
372 ### Predefined Border Templates
374 You can load one of the predefined border templates using `getBorderCharacters` function.
392 border: getBorderCharacters(`name of the template`)
419 # ramac (ASCII; for use in terminals that do not support Unicode characters)
429 # void (no borders; see "bordless table" section of the documentation)
439 Raise [an issue](https://github.com/gajus/table/issues) if you'd like to contribute a new border template.
441 <a name="table-usage-predefined-border-templates-borderless-table"></a>
442 #### Borderless Table
444 Simply using "void" border character template creates a table with a lot of unnecessary spacing.
446 To create a more plesant to the eye table, reset the padding and remove the joining rows, e.g.
451 output = table(data, {
452 border: getBorderCharacters(`void`),
457 drawHorizontalLine: () => {
471 <a name="table-usage-streaming"></a>
474 `table` package exports `createStream` function used to draw a table and append rows.
476 `createStream` requires `{number} columnDefault.width` and `{number} columnCount` configuration properties.
493 stream = createStream(config);
496 stream.write([new Date()]);
500 ![Streaming current date.](./.README/streaming.gif)
502 `table` package uses ANSI escape codes to overwrite the output of the last line when a new row is printed.
504 The underlying implementation is explained in this [Stack Overflow answer](http://stackoverflow.com/a/32938658/368691).
506 Streaming supports all of the configuration properties and functionality of a static table (such as auto text wrapping, alignment and padding), e.g.
513 import _ from 'lodash';
538 stream = createStream(config);
545 random = _.sample('abcdefghijklmnopqrstuvwxyz', _.random(1, 30)).join('');
547 stream.write([i++, new Date(), random]);
551 ![Streaming random data.](./.README/streaming-random.gif)
552 <a name="table-usage-text-truncation"></a>
555 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.
557 `{number} config.columns[{number}].truncate` property (default: `Infinity`) truncates the text at the specified length.
565 ['Lorem ipsum dolor sit amet, consectetur adipiscing elit. Phasellus pulvinar nibh sed mauris convallis dapibus. Nunc venenatis tempus nulla sit amet viverra.']
577 output = table(data, config);
583 ╔══════════════════════╗
584 ║ Lorem ipsum dolor si ║
585 ║ t amet, consectetur ║
586 ║ adipiscing elit. Pha ║
587 ║ sellus pulvinar nibh ║
588 ║ sed mauris conva... ║
589 ╚══════════════════════╝
592 <a name="table-usage-text-wrapping"></a>
595 `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.
603 ['Lorem ipsum dolor sit amet, consectetur adipiscing elit. Phasellus pulvinar nibh sed mauris convallis dapibus. Nunc venenatis tempus nulla sit amet viverra.']
614 output = table(data, config);
620 ╔══════════════════════╗
621 ║ Lorem ipsum dolor si ║
622 ║ t amet, consectetur ║
623 ║ adipiscing elit. Pha ║
624 ║ sellus pulvinar nibh ║
625 ║ sed mauris convallis ║
626 ║ dapibus. Nunc venena ║
627 ║ tis tempus nulla sit ║
629 ╚══════════════════════╝
632 When `wrapWord` is `true` the text is broken at the nearest space or one of the special characters ("-", "_", "\", "/", ".", ",", ";"), e.g.
640 ['Lorem ipsum dolor sit amet, consectetur adipiscing elit. Phasellus pulvinar nibh sed mauris convallis dapibus. Nunc venenatis tempus nulla sit amet viverra.']
652 output = table(data, config);
658 ╔══════════════════════╗
659 ║ Lorem ipsum dolor ║
663 ║ Phasellus pulvinar ║
665 ║ convallis dapibus. ║
669 ╚══════════════════════╝