4 [![GitSpo Mentions](https://gitspo.com/badges/mentions/gajus/table?style=flat-square)](https://gitspo.com/mentions/gajus/table)
5 [![Travis build status](http://img.shields.io/travis/gajus/table/master.svg?style=flat-square)](https://travis-ci.org/gajus/table)
6 [![Coveralls](https://img.shields.io/coveralls/gajus/table.svg?style=flat-square)](https://coveralls.io/github/gajus/table)
7 [![NPM version](http://img.shields.io/npm/v/table.svg?style=flat-square)](https://www.npmjs.org/package/table)
8 [![Canonical Code Style](https://img.shields.io/badge/code%20style-canonical-blue.svg?style=flat-square)](https://github.com/gajus/canonical)
9 [![Twitter Follow](https://img.shields.io/twitter/follow/kuizinas.svg?style=social&label=Follow)](https://twitter.com/kuizinas)
12 * [Features](#table-features)
13 * [Install](#table-install)
14 * [Usage](#table-usage)
15 * [Cell Content Alignment](#table-usage-cell-content-alignment)
16 * [Column Width](#table-usage-column-width)
17 * [Custom Border](#table-usage-custom-border)
18 * [Draw Horizontal Line](#table-usage-draw-horizontal-line)
19 * [Single Line Mode](#table-usage-single-line-mode)
20 * [Padding Cell Content](#table-usage-padding-cell-content)
21 * [Predefined Border Templates](#table-usage-predefined-border-templates)
22 * [Streaming](#table-usage-streaming)
23 * [Text Truncation](#table-usage-text-truncation)
24 * [Text Wrapping](#table-usage-text-wrapping)
27 Produces a string that represents array data in a text table.
29 ![Demo of table displaying a list of missions to the Moon.](./.README/demo.png)
31 <a name="table-features"></a>
34 * Works with strings containing [fullwidth](https://en.wikipedia.org/wiki/Halfwidth_and_fullwidth_forms) characters.
35 * Works with strings containing [ANSI escape codes](https://en.wikipedia.org/wiki/ANSI_escape_code).
36 * Configurable border characters.
37 * Configurable content alignment per column.
38 * Configurable content padding per column.
39 * Configurable column width.
42 <a name="table-install"></a>
50 [![Buy Me A Coffee](https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png)](https://www.buymeacoffee.com/gajus)
51 [![Become a Patron](https://c5.patreon.com/external/logo/become_a_patron_button.png)](https://www.patreon.com/gajus)
53 <a name="table-usage"></a>
56 Table data is described using an array (rows) of array (cells).
64 // const {table} = require('table');
76 * @typedef {string} table~cell
80 * @typedef {table~cell[]} table~row
84 * @typedef {Object} table~columns
85 * @property {string} alignment Cell content alignment (enum: left, center, right) (default: left).
86 * @property {number} width Column width (default: auto).
87 * @property {number} truncate Number of characters are which the content will be truncated (default: Infinity).
88 * @property {number} paddingLeft Cell content padding width left (default: 1).
89 * @property {number} paddingRight Cell content padding width right (default: 1).
93 * @typedef {Object} table~border
94 * @property {string} topBody
95 * @property {string} topJoin
96 * @property {string} topLeft
97 * @property {string} topRight
98 * @property {string} bottomBody
99 * @property {string} bottomJoin
100 * @property {string} bottomLeft
101 * @property {string} bottomRight
102 * @property {string} bodyLeft
103 * @property {string} bodyRight
104 * @property {string} bodyJoin
105 * @property {string} joinBody
106 * @property {string} joinLeft
107 * @property {string} joinRight
108 * @property {string} joinJoin
112 * Used to dynamically tell table whether to draw a line separating rows or not.
113 * The default behavior is to always return true.
115 * @typedef {function} drawHorizontalLine
116 * @param {number} index
117 * @param {number} size
122 * @typedef {Object} table~config
123 * @property {table~border} border
124 * @property {table~columns[]} columns Column specific configuration.
125 * @property {table~columns} columnDefault Default values for all columns. Column specific settings overwrite the default values.
126 * @property {table~drawHorizontalLine} drawHorizontalLine
130 * Generates a text table.
132 * @param {table~row[]} rows
133 * @param {table~config} config
136 output = table(data);
153 <a name="table-usage-cell-content-alignment"></a>
154 ### Cell Content Alignment
156 `{string} config.columns[{number}].alignment` property controls content horizontal alignment within a cell.
158 Valid values are: "left", "right" and "center".
188 output = table(data, config);
194 ╔════════════╤════════════╤════════════╗
196 ╟────────────┼────────────┼────────────╢
198 ╟────────────┼────────────┼────────────╢
200 ╚════════════╧════════════╧════════════╝
203 <a name="table-usage-column-width"></a>
206 `{number} config.columns[{number}].width` property restricts column width to a fixed width.
227 output = table(data, options);
233 ╔════╤════════════╤════╗
235 ╟────┼────────────┼────╢
237 ╟────┼────────────┼────╢
239 ╚════╧════════════╧════╝
242 <a name="table-usage-custom-border"></a>
245 `{object} config.border` property describes characters used to draw the table border.
281 output = table(data, config);
296 <a name="table-usage-draw-horizontal-line"></a>
297 ### Draw Horizontal Line
299 `{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.
316 * @typedef {function} drawHorizontalLine
317 * @param {number} index
318 * @param {number} size
321 drawHorizontalLine: (index, size) => {
322 return index === 0 || index === 1 || index === size - 1 || index === size;
326 output = table(data, options);
345 <a name="table-usage-single-line-mode"></a>
348 Horizontal lines inside the table are not drawn.
357 ['-rw-r--r--', '1', 'pandorym', 'staff', '1529', 'May 23 11:25', 'LICENSE'],
358 ['-rw-r--r--', '1', 'pandorym', 'staff', '16327', 'May 23 11:58', 'README.md'],
359 ['drwxr-xr-x', '76', 'pandorym', 'staff', '2432', 'May 23 12:02', 'dist'],
360 ['drwxr-xr-x', '634', 'pandorym', 'staff', '20288', 'May 23 11:54', 'node_modules'],
361 ['-rw-r--r--', '1,', 'pandorym', 'staff', '525688', 'May 23 11:52', 'package-lock.json'],
362 ['-rw-r--r--@', '1', 'pandorym', 'staff', '2440', 'May 23 11:25', 'package.json'],
363 ['drwxr-xr-x', '27', 'pandorym', 'staff', '864', 'May 23 11:25', 'src'],
364 ['drwxr-xr-x', '20', 'pandorym', 'staff', '640', 'May 23 11:25', 'test'],
371 const output = table(data, config);
376 ╔═════════════╤═════╤══════════╤═══════╤════════╤══════════════╤═══════════════════╗
377 ║ -rw-r--r-- │ 1 │ pandorym │ staff │ 1529 │ May 23 11:25 │ LICENSE ║
378 ║ -rw-r--r-- │ 1 │ pandorym │ staff │ 16327 │ May 23 11:58 │ README.md ║
379 ║ drwxr-xr-x │ 76 │ pandorym │ staff │ 2432 │ May 23 12:02 │ dist ║
380 ║ drwxr-xr-x │ 634 │ pandorym │ staff │ 20288 │ May 23 11:54 │ node_modules ║
381 ║ -rw-r--r-- │ 1, │ pandorym │ staff │ 525688 │ May 23 11:52 │ package-lock.json ║
382 ║ -rw-r--r--@ │ 1 │ pandorym │ staff │ 2440 │ May 23 11:25 │ package.json ║
383 ║ drwxr-xr-x │ 27 │ pandorym │ staff │ 864 │ May 23 11:25 │ src ║
384 ║ drwxr-xr-x │ 20 │ pandorym │ staff │ 640 │ May 23 11:25 │ test ║
385 ╚═════════════╧═════╧══════════╧═══════╧════════╧══════════════╧═══════════════════╝
388 <a name="table-usage-padding-cell-content"></a>
389 ### Padding Cell Content
391 `{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.
399 ['0A', 'AABBCC', '0C'],
416 output = table(data, config);
433 <a name="table-usage-predefined-border-templates"></a>
434 ### Predefined Border Templates
436 You can load one of the predefined border templates using `getBorderCharacters` function.
454 border: getBorderCharacters(`name of the template`)
481 # ramac (ASCII; for use in terminals that do not support Unicode characters)
491 # void (no borders; see "bordless table" section of the documentation)
501 Raise [an issue](https://github.com/gajus/table/issues) if you'd like to contribute a new border template.
503 <a name="table-usage-predefined-border-templates-borderless-table"></a>
504 #### Borderless Table
506 Simply using "void" border character template creates a table with a lot of unnecessary spacing.
508 To create a more plesant to the eye table, reset the padding and remove the joining rows, e.g.
513 output = table(data, {
514 border: getBorderCharacters(`void`),
519 drawHorizontalLine: () => {
533 <a name="table-usage-streaming"></a>
536 `table` package exports `createStream` function used to draw a table and append rows.
538 `createStream` requires `{number} columnDefault.width` and `{number} columnCount` configuration properties.
555 stream = createStream(config);
558 stream.write([new Date()]);
562 ![Streaming current date.](./.README/streaming.gif)
564 `table` package uses ANSI escape codes to overwrite the output of the last line when a new row is printed.
566 The underlying implementation is explained in this [Stack Overflow answer](http://stackoverflow.com/a/32938658/368691).
568 Streaming supports all of the configuration properties and functionality of a static table (such as auto text wrapping, alignment and padding), e.g.
575 import _ from 'lodash';
600 stream = createStream(config);
607 random = _.sample('abcdefghijklmnopqrstuvwxyz', _.random(1, 30)).join('');
609 stream.write([i++, new Date(), random]);
613 ![Streaming random data.](./.README/streaming-random.gif)
615 <a name="table-usage-text-truncation"></a>
618 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.
620 `{number} config.columns[{number}].truncate` property (default: `Infinity`) truncates the text at the specified length.
628 ['Lorem ipsum dolor sit amet, consectetur adipiscing elit. Phasellus pulvinar nibh sed mauris convallis dapibus. Nunc venenatis tempus nulla sit amet viverra.']
640 output = table(data, config);
646 ╔══════════════════════╗
647 ║ Lorem ipsum dolor si ║
648 ║ t amet, consectetur ║
649 ║ adipiscing elit. Pha ║
650 ║ sellus pulvinar nibh ║
651 ║ sed mauris conva... ║
652 ╚══════════════════════╝
655 <a name="table-usage-text-wrapping"></a>
658 `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.
666 ['Lorem ipsum dolor sit amet, consectetur adipiscing elit. Phasellus pulvinar nibh sed mauris convallis dapibus. Nunc venenatis tempus nulla sit amet viverra.']
677 output = table(data, config);
683 ╔══════════════════════╗
684 ║ Lorem ipsum dolor si ║
685 ║ t amet, consectetur ║
686 ║ adipiscing elit. Pha ║
687 ║ sellus pulvinar nibh ║
688 ║ sed mauris convallis ║
689 ║ dapibus. Nunc venena ║
690 ║ tis tempus nulla sit ║
692 ╚══════════════════════╝
695 When `wrapWord` is `true` the text is broken at the nearest space or one of the special characters ("-", "_", "\", "/", ".", ",", ";"), e.g.
703 ['Lorem ipsum dolor sit amet, consectetur adipiscing elit. Phasellus pulvinar nibh sed mauris convallis dapibus. Nunc venenatis tempus nulla sit amet viverra.']
715 output = table(data, config);
721 ╔══════════════════════╗
722 ║ Lorem ipsum dolor ║
726 ║ Phasellus pulvinar ║
728 ║ convallis dapibus. ║
732 ╚══════════════════════╝