.config/coc/extensions/node_modules/coc-prettier/node_modules/table/README.md

   1 <a name="table"></a>
   2 # Table
   3
   4 [![Travis build status](http://img.shields.io/travis/gajus/table/master.svg?style=flat-square)](https://travis-ci.org/gajus/table)
   5 [![Coveralls](https://img.shields.io/coveralls/gajus/table.svg?style=flat-square)](https://coveralls.io/github/gajus/table)
   6 [![NPM version](http://img.shields.io/npm/v/table.svg?style=flat-square)](https://www.npmjs.org/package/table)
   7 [![Canonical Code Style](https://img.shields.io/badge/code%20style-canonical-blue.svg?style=flat-square)](https://github.com/gajus/canonical)
   8 [![Twitter Follow](https://img.shields.io/twitter/follow/kuizinas.svg?style=social&label=Follow)](https://twitter.com/kuizinas)
   9
  10 * [Table](#table)
  11     * [Features](#table-features)
  12     * [Install](#table-install)
  13     * [Usage](#table-usage)
  14         * [Cell Content Alignment](#table-usage-cell-content-alignment)
  15         * [Column Width](#table-usage-column-width)
  16         * [Custom Border](#table-usage-custom-border)
  17         * [Draw Horizontal Line](#table-usage-draw-horizontal-line)
  18         * [Single Line Mode](#table-usage-single-line-mode)
  19         * [Padding Cell Content](#table-usage-padding-cell-content)
  20         * [Predefined Border Templates](#table-usage-predefined-border-templates)
  21         * [Streaming](#table-usage-streaming)
  22         * [Text Truncation](#table-usage-text-truncation)
  23         * [Text Wrapping](#table-usage-text-wrapping)
  24
  25
  26 Produces a string that represents array data in a text table.
  27
  28 ![Demo of table displaying a list of missions to the Moon.](./.README/demo.png)
  29
  30 <a name="table-features"></a>
  31 ## Features
  32
  33 * Works with strings containing [fullwidth](https://en.wikipedia.org/wiki/Halfwidth_and_fullwidth_forms) characters.
  34 * Works with strings containing [ANSI escape codes](https://en.wikipedia.org/wiki/ANSI_escape_code).
  35 * Configurable border characters.
  36 * Configurable content alignment per column.
  37 * Configurable content padding per column.
  38 * Configurable column width.
  39 * Text wrapping.
  40
  41 <a name="table-install"></a>
  42 ## Install
  43
  44 ```bash
  45 npm install table
  46
  47 ```
  48
  49 [![Buy Me A Coffee](https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png)](https://www.buymeacoffee.com/gajus)
  50 [![Become a Patron](https://c5.patreon.com/external/logo/become_a_patron_button.png)](https://www.patreon.com/gajus)
  51
  52 <a name="table-usage"></a>
  53 ## Usage
  54
  55 Table data is described using an array (rows) of array (cells).
  56
  57 ```js
  58 import {
  59   table
  60 } from 'table';
  61
  62 // Using commonjs?
  63 // const {table} = require('table');
  64
  65 let data,
  66     output;
  67
  68 data = [
  69     ['0A', '0B', '0C'],
  70     ['1A', '1B', '1C'],
  71     ['2A', '2B', '2C']
  72 ];
  73
  74 /**
  75  * @typedef {string} table~cell
  76  */
  77
  78 /**
  79  * @typedef {table~cell[]} table~row
  80  */
  81
  82 /**
  83  * @typedef {Object} table~columns
  84  * @property {string} alignment Cell content alignment (enum: left, center, right) (default: left).
  85  * @property {number} width Column width (default: auto).
  86  * @property {number} truncate Number of characters are which the content will be truncated (default: Infinity).
  87  * @property {number} paddingLeft Cell content padding width left (default: 1).
  88  * @property {number} paddingRight Cell content padding width right (default: 1).
  89  */
  90
  91 /**
  92  * @typedef {Object} table~border
  93  * @property {string} topBody
  94  * @property {string} topJoin
  95  * @property {string} topLeft
  96  * @property {string} topRight
  97  * @property {string} bottomBody
  98  * @property {string} bottomJoin
  99  * @property {string} bottomLeft
 100  * @property {string} bottomRight
 101  * @property {string} bodyLeft
 102  * @property {string} bodyRight
 103  * @property {string} bodyJoin
 104  * @property {string} joinBody
 105  * @property {string} joinLeft
 106  * @property {string} joinRight
 107  * @property {string} joinJoin
 108  */
 109
 110 /**
 111  * Used to dynamically tell table whether to draw a line separating rows or not.
 112  * The default behavior is to always return true.
 113  *
 114  * @typedef {function} drawHorizontalLine
 115  * @param {number} index
 116  * @param {number} size
 117  * @return {boolean}
 118  */
 119
 120 /**
 121  * @typedef {Object} table~config
 122  * @property {table~border} border
 123  * @property {table~columns[]} columns Column specific configuration.
 124  * @property {table~columns} columnDefault Default values for all columns. Column specific settings overwrite the default values.
 125  * @property {table~drawHorizontalLine} drawHorizontalLine
 126  */
 127
 128 /**
 129  * Generates a text table.
 130  *
 131  * @param {table~row[]} rows
 132  * @param {table~config} config
 133  * @return {String}
 134  */
 135 output = table(data);
 136
 137 console.log(output);
 138 ```
 139
 140 ```
 141 ╔════╤════╤════╗
 142 ║ 0A │ 0B │ 0C ║
 143 ╟────┼────┼────╢
 144 ║ 1A │ 1B │ 1C ║
 145 ╟────┼────┼────╢
 146 ║ 2A │ 2B │ 2C ║
 147 ╚════╧════╧════╝
 148
 149 ```
 150
 151
 152 <a name="table-usage-cell-content-alignment"></a>
 153 ### Cell Content Alignment
 154
 155 `{string} config.columns[{number}].alignment` property controls content horizontal alignment within a cell.
 156
 157 Valid values are: "left", "right" and "center".
 158
 159 ```js
 160 let config,
 161   data,
 162   output;
 163
 164 data = [
 165   ['0A', '0B', '0C'],
 166   ['1A', '1B', '1C'],
 167   ['2A', '2B', '2C']
 168 ];
 169
 170 config = {
 171   columns: {
 172     0: {
 173       alignment: 'left',
 174       width: 10
 175     },
 176     1: {
 177       alignment: 'center',
 178       width: 10
 179     },
 180     2: {
 181       alignment: 'right',
 182       width: 10
 183     }
 184   }
 185 };
 186
 187 output = table(data, config);
 188
 189 console.log(output);
 190 ```
 191
 192 ```
 193 ╔════════════╤════════════╤════════════╗
 194 ║ 0A         │     0B     │         0C ║
 195 ╟────────────┼────────────┼────────────╢
 196 ║ 1A         │     1B     │         1C ║
 197 ╟────────────┼────────────┼────────────╢
 198 ║ 2A         │     2B     │         2C ║
 199 ╚════════════╧════════════╧════════════╝
 200 ```
 201
 202 <a name="table-usage-column-width"></a>
 203 ### Column Width
 204
 205 `{number} config.columns[{number}].width` property restricts column width to a fixed width.
 206
 207 ```js
 208 let data,
 209   output,
 210   options;
 211
 212 data = [
 213   ['0A', '0B', '0C'],
 214   ['1A', '1B', '1C'],
 215   ['2A', '2B', '2C']
 216 ];
 217
 218 options = {
 219   columns: {
 220     1: {
 221       width: 10
 222     }
 223   }
 224 };
 225
 226 output = table(data, options);
 227
 228 console.log(output);
 229 ```
 230
 231 ```
 232 ╔════╤════════════╤════╗
 233 ║ 0A │ 0B         │ 0C ║
 234 ╟────┼────────────┼────╢
 235 ║ 1A │ 1B         │ 1C ║
 236 ╟────┼────────────┼────╢
 237 ║ 2A │ 2B         │ 2C ║
 238 ╚════╧════════════╧════╝
 239 ```
 240
 241 <a name="table-usage-custom-border"></a>
 242 ### Custom Border
 243
 244 `{object} config.border` property describes characters used to draw the table border.
 245
 246 ```js
 247 let config,
 248   data,
 249   output;
 250
 251 data = [
 252   ['0A', '0B', '0C'],
 253   ['1A', '1B', '1C'],
 254   ['2A', '2B', '2C']
 255 ];
 256
 257 config = {
 258   border: {
 259     topBody: `─`,
 260     topJoin: `┬`,
 261     topLeft: `┌`,
 262     topRight: `┐`,
 263
 264     bottomBody: `─`,
 265     bottomJoin: `┴`,
 266     bottomLeft: `└`,
 267     bottomRight: `┘`,
 268
 269     bodyLeft: `│`,
 270     bodyRight: `│`,
 271     bodyJoin: `│`,
 272
 273     joinBody: `─`,
 274     joinLeft: `├`,
 275     joinRight: `┤`,
 276     joinJoin: `┼`
 277   }
 278 };
 279
 280 output = table(data, config);
 281
 282 console.log(output);
 283 ```
 284
 285 ```
 286 ┌────┬────┬────┐
 287 │ 0A │ 0B │ 0C │
 288 ├────┼────┼────┤
 289 │ 1A │ 1B │ 1C │
 290 ├────┼────┼────┤
 291 │ 2A │ 2B │ 2C │
 292 └────┴────┴────┘
 293 ```
 294
 295 <a name="table-usage-draw-horizontal-line"></a>
 296 ### Draw Horizontal Line
 297
 298 `{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
 300 ```js
 301 let data,
 302   output,
 303   options;
 304
 305 data = [
 306   ['0A', '0B', '0C'],
 307   ['1A', '1B', '1C'],
 308   ['2A', '2B', '2C'],
 309   ['3A', '3B', '3C'],
 310   ['4A', '4B', '4C']
 311 ];
 312
 313 options = {
 314   /**
 315     * @typedef {function} drawHorizontalLine
 316     * @param {number} index
 317     * @param {number} size
 318     * @return {boolean}
 319     */
 320   drawHorizontalLine: (index, size) => {
 321     return index === 0 || index === 1 || index === size - 1 || index === size;
 322   }
 323 };
 324
 325 output = table(data, options);
 326
 327 console.log(output);
 328
 329 ```
 330
 331 ```
 332 ╔════╤════╤════╗
 333 ║ 0A │ 0B │ 0C ║
 334 ╟────┼────┼────╢
 335 ║ 1A │ 1B │ 1C ║
 336 ║ 2A │ 2B │ 2C ║
 337 ║ 3A │ 3B │ 3C ║
 338 ╟────┼────┼────╢
 339 ║ 4A │ 4B │ 4C ║
 340 ╚════╧════╧════╝
 341
 342 ```
 343
 344 <a name="table-usage-single-line-mode"></a>
 345 ### Single Line Mode
 346
 347 Horizontal lines inside the table are not drawn.
 348
 349 ```js
 350 import {
 351   table,
 352   getBorderCharacters
 353 } from 'table';
 354
 355 const data = [
 356   ['-rw-r--r--', '1', 'pandorym', 'staff', '1529', 'May 23 11:25', 'LICENSE'],
 357   ['-rw-r--r--', '1', 'pandorym', 'staff', '16327', 'May 23 11:58', 'README.md'],
 358   ['drwxr-xr-x', '76', 'pandorym', 'staff', '2432', 'May 23 12:02', 'dist'],
 359   ['drwxr-xr-x', '634', 'pandorym', 'staff', '20288', 'May 23 11:54', 'node_modules'],
 360   ['-rw-r--r--', '1,', 'pandorym', 'staff', '525688', 'May 23 11:52', 'package-lock.json'],
 361   ['-rw-r--r--@', '1', 'pandorym', 'staff', '2440', 'May 23 11:25', 'package.json'],
 362   ['drwxr-xr-x', '27', 'pandorym', 'staff', '864', 'May 23 11:25', 'src'],
 363   ['drwxr-xr-x', '20', 'pandorym', 'staff', '640', 'May 23 11:25', 'test'],
 364 ];
 365
 366 const config = {
 367   singleLine: true
 368 };
 369
 370 const output = table(data, config);
 371 console.log(output);
 372 ```
 373
 374 ```
 375 ╔═════════════╤═════╤══════════╤═══════╤════════╤══════════════╤═══════════════════╗
 376 ║ -rw-r--r--  │ 1   │ pandorym │ staff │ 1529   │ May 23 11:25 │ LICENSE           ║
 377 ║ -rw-r--r--  │ 1   │ pandorym │ staff │ 16327  │ May 23 11:58 │ README.md         ║
 378 ║ drwxr-xr-x  │ 76  │ pandorym │ staff │ 2432   │ May 23 12:02 │ dist              ║
 379 ║ drwxr-xr-x  │ 634 │ pandorym │ staff │ 20288  │ May 23 11:54 │ node_modules      ║
 380 ║ -rw-r--r--  │ 1,  │ pandorym │ staff │ 525688 │ May 23 11:52 │ package-lock.json ║
 381 ║ -rw-r--r--@ │ 1   │ pandorym │ staff │ 2440   │ May 23 11:25 │ package.json      ║
 382 ║ drwxr-xr-x  │ 27  │ pandorym │ staff │ 864    │ May 23 11:25 │ src               ║
 383 ║ drwxr-xr-x  │ 20  │ pandorym │ staff │ 640    │ May 23 11:25 │ test              ║
 384 ╚═════════════╧═════╧══════════╧═══════╧════════╧══════════════╧═══════════════════╝
 385 ```
 386
 387 <a name="table-usage-padding-cell-content"></a>
 388 ### Padding Cell Content
 389
 390 `{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.
 391
 392 ```js
 393 let config,
 394   data,
 395   output;
 396
 397 data = [
 398   ['0A', 'AABBCC', '0C'],
 399   ['1A', '1B', '1C'],
 400   ['2A', '2B', '2C']
 401 ];
 402
 403 config = {
 404   columns: {
 405     0: {
 406       paddingLeft: 3
 407     },
 408     1: {
 409       width: 2,
 410       paddingRight: 3
 411     }
 412   }
 413 };
 414
 415 output = table(data, config);
 416
 417 console.log(output);
 418 ```
 419
 420 ```
 421 ╔══════╤══════╤════╗
 422 ║   0A │ AA   │ 0C ║
 423 ║      │ BB   │    ║
 424 ║      │ CC   │    ║
 425 ╟──────┼──────┼────╢
 426 ║   1A │ 1B   │ 1C ║
 427 ╟──────┼──────┼────╢
 428 ║   2A │ 2B   │ 2C ║
 429 ╚══════╧══════╧════╝
 430 ```
 431
 432 <a name="table-usage-predefined-border-templates"></a>
 433 ### Predefined Border Templates
 434
 435 You can load one of the predefined border templates using `getBorderCharacters` function.
 436
 437 ```js
 438 import {
 439   table,
 440   getBorderCharacters
 441 } from 'table';
 442
 443 let config,
 444   data;
 445
 446 data = [
 447   ['0A', '0B', '0C'],
 448   ['1A', '1B', '1C'],
 449   ['2A', '2B', '2C']
 450 ];
 451
 452 config = {
 453   border: getBorderCharacters(`name of the template`)
 454 };
 455
 456 table(data, config);
 457 ```
 458
 459 ```
 460 # honeywell
 461
 462 ╔════╤════╤════╗
 463 ║ 0A │ 0B │ 0C ║
 464 ╟────┼────┼────╢
 465 ║ 1A │ 1B │ 1C ║
 466 ╟────┼────┼────╢
 467 ║ 2A │ 2B │ 2C ║
 468 ╚════╧════╧════╝
 469
 470 # norc
 471
 472 ┌────┬────┬────┐
 473 │ 0A │ 0B │ 0C │
 474 ├────┼────┼────┤
 475 │ 1A │ 1B │ 1C │
 476 ├────┼────┼────┤
 477 │ 2A │ 2B │ 2C │
 478 └────┴────┴────┘
 479
 480 # ramac (ASCII; for use in terminals that do not support Unicode characters)
 481
 482 +----+----+----+
 483 | 0A | 0B | 0C |
 484 |----|----|----|
 485 | 1A | 1B | 1C |
 486 |----|----|----|
 487 | 2A | 2B | 2C |
 488 +----+----+----+
 489
 490 # void (no borders; see "bordless table" section of the documentation)
 491
 492  0A  0B  0C
 493
 494  1A  1B  1C
 495
 496  2A  2B  2C
 497
 498 ```
 499
 500 Raise [an issue](https://github.com/gajus/table/issues) if you'd like to contribute a new border template.
 501
 502 <a name="table-usage-predefined-border-templates-borderless-table"></a>
 503 #### Borderless Table
 504
 505 Simply using "void" border character template creates a table with a lot of unnecessary spacing.
 506
 507 To create a more plesant to the eye table, reset the padding and remove the joining rows, e.g.
 508
 509 ```js
 510 let output;
 511
 512 output = table(data, {
 513     border: getBorderCharacters(`void`),
 514     columnDefault: {
 515         paddingLeft: 0,
 516         paddingRight: 1
 517     },
 518     drawHorizontalLine: () => {
 519         return false
 520     }
 521 });
 522
 523 console.log(output);
 524 ```
 525
 526 ```
 527 0A 0B 0C
 528 1A 1B 1C
 529 2A 2B 2C
 530 ```
 531
 532 <a name="table-usage-streaming"></a>
 533 ### Streaming
 534
 535 `table` package exports `createStream` function used to draw a table and append rows.
 536
 537 `createStream` requires `{number} columnDefault.width` and `{number} columnCount` configuration properties.
 538
 539 ```js
 540 import {
 541   createStream
 542 } from 'table';
 543
 544 let config,
 545   stream;
 546
 547 config = {
 548   columnDefault: {
 549     width: 50
 550   },
 551   columnCount: 1
 552 };
 553
 554 stream = createStream(config);
 555
 556 setInterval(() => {
 557   stream.write([new Date()]);
 558 }, 500);
 559 ```
 560
 561 ![Streaming current date.](./.README/streaming.gif)
 562
 563 `table` package uses ANSI escape codes to overwrite the output of the last line when a new row is printed.
 564
 565 The underlying implementation is explained in this [Stack Overflow answer](http://stackoverflow.com/a/32938658/368691).
 566
 567 Streaming supports all of the configuration properties and functionality of a static table (such as auto text wrapping, alignment and padding), e.g.
 568
 569 ```js
 570 import {
 571   createStream
 572 } from 'table';
 573
 574 import _ from 'lodash';
 575
 576 let config,
 577   stream,
 578   i;
 579
 580 config = {
 581   columnDefault: {
 582     width: 50
 583   },
 584   columnCount: 3,
 585   columns: {
 586     0: {
 587       width: 10,
 588       alignment: 'right'
 589     },
 590     1: {
 591       alignment: 'center',
 592     },
 593     2: {
 594       width: 10
 595     }
 596   }
 597 };
 598
 599 stream = createStream(config);
 600
 601 i = 0;
 602
 603 setInterval(() => {
 604   let random;
 605
 606   random = _.sample('abcdefghijklmnopqrstuvwxyz', _.random(1, 30)).join('');
 607
 608   stream.write([i++, new Date(), random]);
 609 }, 500);
 610 ```
 611
 612 ![Streaming random data.](./.README/streaming-random.gif)
 613
 614 <a name="table-usage-text-truncation"></a>
 615 ### Text Truncation
 616
 617 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.
 618
 619 `{number} config.columns[{number}].truncate` property (default: `Infinity`) truncates the text at the specified length.
 620
 621 ```js
 622 let config,
 623   data,
 624   output;
 625
 626 data = [
 627   ['Lorem ipsum dolor sit amet, consectetur adipiscing elit. Phasellus pulvinar nibh sed mauris convallis dapibus. Nunc venenatis tempus nulla sit amet viverra.']
 628 ];
 629
 630 config = {
 631   columns: {
 632     0: {
 633       width: 20,
 634       truncate: 100
 635     }
 636   }
 637 };
 638
 639 output = table(data, config);
 640
 641 console.log(output);
 642 ```
 643
 644 ```
 645 ╔══════════════════════╗
 646 ║ Lorem ipsum dolor si ║
 647 ║ t amet, consectetur  ║
 648 ║ adipiscing elit. Pha ║
 649 ║ sellus pulvinar nibh ║
 650 ║ sed mauris conva...  ║
 651 ╚══════════════════════╝
 652 ```
 653
 654 <a name="table-usage-text-wrapping"></a>
 655 ### Text Wrapping
 656
 657 `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.
 658
 659 ```js
 660 let config,
 661   data,
 662   output;
 663
 664 data = [
 665     ['Lorem ipsum dolor sit amet, consectetur adipiscing elit. Phasellus pulvinar nibh sed mauris convallis dapibus. Nunc venenatis tempus nulla sit amet viverra.']
 666 ];
 667
 668 config = {
 669   columns: {
 670     0: {
 671       width: 20
 672     }
 673   }
 674 };
 675
 676 output = table(data, config);
 677
 678 console.log(output);
 679 ```
 680
 681 ```
 682 ╔══════════════════════╗
 683 ║ Lorem ipsum dolor si ║
 684 ║ t amet, consectetur  ║
 685 ║ adipiscing elit. Pha ║
 686 ║ sellus pulvinar nibh ║
 687 ║ sed mauris convallis ║
 688 ║ dapibus. Nunc venena ║
 689 ║ tis tempus nulla sit ║
 690 ║ amet viverra.        ║
 691 ╚══════════════════════╝
 692 ```
 693
 694 When `wrapWord` is `true` the text is broken at the nearest space or one of the special characters ("-", "_", "\", "/", ".", ",", ";"), e.g.
 695
 696 ```js
 697 let config,
 698   data,
 699   output;
 700
 701 data = [
 702   ['Lorem ipsum dolor sit amet, consectetur adipiscing elit. Phasellus pulvinar nibh sed mauris convallis dapibus. Nunc venenatis tempus nulla sit amet viverra.']
 703 ];
 704
 705 config = {
 706   columns: {
 707     0: {
 708       width: 20,
 709       wrapWord: true
 710     }
 711   }
 712 };
 713
 714 output = table(data, config);
 715
 716 console.log(output);
 717 ```
 718
 719 ```
 720 ╔══════════════════════╗
 721 ║ Lorem ipsum dolor    ║
 722 ║ sit amet,            ║
 723 ║ consectetur          ║
 724 ║ adipiscing elit.     ║
 725 ║ Phasellus pulvinar   ║
 726 ║ nibh sed mauris      ║
 727 ║ convallis dapibus.   ║
 728 ║ Nunc venenatis       ║
 729 ║ tempus nulla sit     ║
 730 ║ amet viverra.        ║
 731 ╚══════════════════════╝
 732
 733 ```
 734